Ctrl K

Quick Ref / Command

Engineer Kit

/ak:preview

View files or generate visuals

View existing files and folders or generate visual explanations, diagrams, slides, diffs, plan reviews, and project recaps as Markdown or self-contained HTML.

Resolve operation

Handle stop/html

Route generation

Route HTML review

Rule 01

View mode reads existing content; generation mode creates new visual artifacts

Rule 02

--html output is self-contained and must include a theme toggle

Rule 03

Review modes diff, plan-review, and recap imply HTML

Rule 04

Mermaid syntax and publish-grade layout need dedicated validation

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

Start

Input, scope, route

1 Resolve operation If no arguments are provided, ask the user to choose view, generation, stop, or HTML review operation.
2 Handle stop/html Process --stop immediately; set HTML output mode when --html appears or when diff, plan-review, or recap is requested.
3 Route generation Use --explain, --slides, --diagram, or --ascii for Markdown generation; reject empty or invalid topics.

Work

Agent / skill execution

4 Route HTML review Use --diff for git changes, --plan-review for plan-vs-codebase comparison, and --recap for project context snapshots.
5 Route view mode Resolve explicit or contextual paths; existing files or directories load the markdown-novel-viewer route.
6 Load references Load generation, view, visual-routing, HTML design, CSS patterns, libraries, responsive nav, and mode templates as needed.

Verify

Gate, review, validation

7 Generate visual Create prose, ASCII, Mermaid, slides, diagrams, or self-contained HTML with required theme toggle and accessible responsive behavior.
8 Apply editorial layer When enabled and matching intent, use diagram-design or AntV; honor kill switches and fall back cleanly.
9 Save and open Save outputs under the active plan visuals folder or fallback, open Markdown through the server or HTML directly in the browser.

Syntax, arguments, subcommands

How to invoke the skill: syntax, positional arguments, shared options, then each subcommand with its own syntax and outcome.

Syntax

/ak:preview [path]

/ak:preview [--html] --explain|--slides|--diagram|--ascii <topic>

/ak:preview --stop

Arguments

[path]

Existing path

File or directory to open in the Markdown viewer. It must resolve on disk; unresolvable text is not treated as a topic unless a generation flag is present.

/ak:preview plans/checkout/plan.md

<topic> Required

Visual topic

Non-empty subject for explanation, slides, diagram, or ASCII generation. Multiple generation flags use the first flag and fold the rest into this topic.

/ak:preview --diagram webhook lifecycle

[ref]

Diff reference

Optional branch, commit, range, HEAD, pull request, or default main comparison for --diff. PR refs require gh.

/ak:preview --html --diff main

[plan-file]

Plan file

Optional plan path for --plan-review. If omitted, the Skill uses active plan context when available.

/ak:preview --html --plan-review plans/checkout/plan.md

[timeframe]

Recap window

Optional recent-history window for --recap, such as 30d or 3m. Defaults to two weeks.

/ak:preview --html --recap 30d

Shared options

--stop

Stop viewer

Stop the running Markdown viewer server immediately. It does not generate or open a file.

/ak:preview --stop

--explain

Explanation mode

Generate a visual explanation with prose, ASCII, Mermaid, and optional code around a required topic.

/ak:preview --explain auth middleware chain

--slides

Slides mode

Generate a presentation-style artifact when slides are explicitly wanted.

/ak:preview --slides deployment pipeline

--diagram

Diagram mode

Generate a focused diagram and inspect the rendered result, not only the Mermaid syntax.

/ak:preview --html --diagram checkout architecture

--ascii

ASCII mode

Generate a terminal-friendly ASCII diagram. It is not supported with --html.

/ak:preview --ascii folder structure

--diff

Diff review mode

Generate an HTML visual review of a branch, commit, range, HEAD, PR, or default main comparison.

/ak:preview --html --diff main

--plan-review

Plan review mode

Generate an HTML comparison between a plan and the current codebase; requires a plan path or active plan context.

/ak:preview --html --plan-review plans/checkout/plan.md

--recap

Recap mode

Generate an HTML recent-project context snapshot from project identity, Git history, status, decisions, and architecture.

/ak:preview --html --recap 2w

--no-antv

Disable AntV

Disable AntV infographic alternates for this run while allowing other fallbacks.

/ak:preview --html --diff main --no-antv

--no-diagram-design

Disable diagram-design

Disable diagram-design SVG alternates for this run while keeping Mermaid or table fallbacks.

/ak:preview --html --diagram auth --no-diagram-design

--no-editorial-visuals

Disable editorial visuals

Disable all additive editorial visual layers for this run.

/ak:preview --html --recap 30d --no-editorial-visuals

Output / publish flags

Only flags that change the artifact or publish it. Not the full option set.

--html

Self-contained HTML

Switch generation output to a browser-openable HTML file with inline CSS/JS.

Example

/ak:preview --html --diagram checkout architecture

Composable flags

How options work together on one invocation. This does not replace the option cards above.

--html composes with --explain, --slides, and --diagram.

--no-antv, --no-diagram-design, and --no-editorial-visuals disable parts of the editorial visual layer.

Modes / Routes

--explain

Visual explanation of code, architecture, or concepts with prose, ASCII, and Mermaid.

Validate:: topic required

--slides

Presentation-style walkthrough, one concept per slide.

Validate:: topic required

--diagram

Focused architecture or data-flow diagram.

Validate:: topic required

--ascii

Terminal-friendly ASCII diagram; not supported with HTML.

Validate:: topic required

--diff

Visual diff review of branch, commit, range, HEAD, or PR reference; implies HTML.

Research:: git data
Validate:: git context

--plan-review

Compare a plan against actual codebase and surface gaps; implies HTML.

Research:: plan + code
Validate:: plan path or active plan

--recap

Project context snapshot over a timeframe; implies HTML.

Research:: git + architecture
Validate:: git history

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

View file or folder Recommended

/ak:preview plans/checkout/plan.md

Use when:: Use for visual explanations, file previews, or diagrams when an existing path should be opened instead of generating a new artifact.
Expected:: Resolves the path, confirms it exists, loads the view-mode reference, then opens the Markdown file or directory in the preview reader without changing repository files.

Markdown diagram

/ak:preview --diagram checkout webhook lifecycle

Use when:: Use for visual explanations, file previews, or diagrams when a terminal/shareable Markdown artifact is enough.
Expected:: Treats the topic as generation mode, loads generation-mode guidance, creates a focused diagram with ASCII plus Mermaid, and validates Mermaid syntax through the Mermaid v11 skill.

HTML diagram

/ak:preview --html --diagram checkout webhook lifecycle

Use when:: Use for visual explanations, file previews, or diagrams when a browser-openable visual with zoom controls is needed.
Expected:: Switches to HTML mode, reads the HTML design/CSS/library references and diagram template, writes a self-contained HTML file with inline assets and the mandatory light/dark theme toggle.

Plan review

/ak:preview --plan-review plans/checkout/plan.md

Use when:: Use for visual explanations, file previews, or diagrams when a plan must be checked against actual repository state.
Expected:: Auto-enables HTML, reads the plan and referenced code, maps the blast radius, and outputs a browser report with alignment, gaps, risks, and current-vs-planned architecture.

Diff review

/ak:preview --diff main

Use when:: Use for visual explanations, file previews, or diagrams when current git changes need a browser-readable review before handoff.
Expected:: Auto-enables HTML, detects the diff scope against main, gathers git stat/name-status and changed-file context, then creates an HTML review with KPIs, review cards, file map, and decision context.

Explain visually

/ak:preview --explain checkout webhook retries

Use when:: A concept needs a visual explanation rather than opening an existing file.
Expected:: Treats the topic as generation mode, writes a focused visual explanation artifact, and does not mutate the explained source files.

Slides

/ak:preview --slides checkout launch narrative

Use when:: The explanation should be a slide deck instead of a single diagram.
Expected:: Generates a slide artifact for the topic, keeps the narrative scoped to the request, and reports the output path.

ASCII only

/ak:preview --ascii checkout webhook lifecycle

Use when:: The diagram must stay readable in a terminal without HTML.
Expected:: Writes a terminal-readable ASCII diagram for the topic and skips the HTML/browser preview path.

Session recap

/ak:preview --recap 7d

Use when:: You need a visual recap of recent work over a timeframe.
Expected:: Collects the requested timeframe, generates a recap visual, and reports the artifact path without rewriting git history.

Handled Scope

Resolve operation
Handle stop/html
Route generation
Route HTML review
Route view mode
Load references

Artifacts Produced

Preview Output

Pattern

{plan_dir}/visuals/{slug}.md or {slug}.html; view mode opens an existing path

Outputs are visual explanations, diagrams, slides, review reports, or a browser view of existing files/directories.