Skip to content

t1k:preview

FieldValue
Modulet1k-orchestration
Version2.9.24
Effortmedium
Tools—

Keywords: diagram, diff, explain, html, slides, view, visualize

/t1k:preview
[path] OR [--html] --explain|--slides|--diagram|--ascii [topic] OR --html --diff|--plan-review|--recap

Universal viewer + visual generator. View existing content OR generate new visual explanations.

Flag / InputModeOutput
<file.md>ViewRendered in novel-reader UI
<directory/>BrowseDirectory listing
--explain <topic>GenerateMermaid + code + prose
--slides <topic>GenerateStep-by-step walkthrough
--diagram <topic>GenerateArchitecture or data flow
--ascii <topic>GenerateTerminal-friendly ASCII
--html --explainHTML GenerateSelf-contained HTML explanation
--html --slidesHTML GenerateMagazine-quality HTML deck
--html --diagramHTML GenerateHTML diagram with zoom controls
--html --diff [ref]HTML GenerateVisual diff review
--html --plan-reviewHTML GeneratePlan vs codebase comparison
--html --recapHTML GenerateProject context snapshot
--refresh [--engine auto]OrchestrationMulti-file regeneration into docs/diagrams/
--stopControlStop preview server

If invoked without arguments, ask user which operation they want.

  1. --stop — stop server and exit
  2. --refresh — delegate to scripts/refresh-orchestrator.cjs; short-circuit all other generation modes
  3. --html flag — set HTML output mode flag
  4. Generation flags (--explain, --slides, --diagram, --ascii) — load references/generation-modes.md
  5. HTML-only flags (--diff, --plan-review, --recap) — auto-set HTML, load references/generation-modes.md
  6. Argument is a path — view mode, load references/view-mode.md
  7. Unresolvable — ask user to clarify
FlagModeBehaviour
--syntax <mermaid|plantuml|d2|c4|dot>Modifier for --diagramSelects diagram syntax. Default: mermaid (unchanged).
--from-file <path>SourceConsume pre-generated diagram (SVG/DOT/Mermaid source); auto-detect syntax from extension; render only.
--engine <auto|<name>|none>Adapterauto → invoke scripts/adapter-discovery.cjs; named engine → use that adapter; none → generic analyzer. Default: none (unchanged).
--refresh [--out-dir <path>]OrchestrationThin wrapper: delegates to scripts/refresh-orchestrator.cjs. Same code path as t1k diagram refresh. Default out-dir = docs/diagrams/.
--out-dir <path>Modifier for --refreshOverride output directory for refresh. Default: docs/diagrams/.
--forceModifier for --refreshBypass SHA-256 protection when user-modified files exist. Use with caution.

Backwards compatibility: existing --diagram behaviour is unchanged when no --syntax flag is passed (defaults to mermaid).

When --engine auto or --refresh is used, discovery reads .claude/metadata.json → installedModules[*].skills[] (SSOT). For the full algorithm and global-only mode behaviour, see references/adapter-contract.md.

--refresh delegates entirely to scripts/refresh-orchestrator.cjs. This is the same execution path invoked by t1k diagram refresh (CLI). For the full algorithm, SHA-256 protection, sandbox rules, and failure modes, see references/refresh-orchestrator.md.

  1. Active plan (from ## Plan Context hook): {plan_dir}/visuals/{mode}-{slug}-{date}.{ext}
  2. Fallback: plans/visuals/{mode}-{slug}-{date}.{ext}

Topic-to-slug: lowercase, hyphens, alphanumeric only, max 80 chars.

When --html is added:

  • Self-contained single HTML file (no external dependencies except Mermaid CDN)
  • Embedded CSS with dark/light theme toggle (MANDATORY)
  • Mermaid diagrams render interactively
  • Auto-opens via xdg-open (Linux) or open (macOS)

Before generating HTML, read: references/html-design-guidelines.md

Reference loading by mode: references/generation-modes.md

ErrorAction
Invalid/empty topicAsk user to provide a topic
File write failureReport error, check disk space and permissions
--diff without git contextExplain: “No git repo detected.”
--plan-review without planExplain: “Provide plan file path or active plan.”
--html --ascii combinationNot supported — suggest --html --diagram instead

Full error table and gotchas: references/hard-rules.md

ConditionLoad
--syntax or --diagramreferences/tool-selection.md
--refreshreferences/refresh-orchestrator.md + references/adapter-contract.md
--from-file with non-Mermaid content (extension .puml, .dot, .d2)Relevant section of references/source-code-diagrams.md

Triggers on: preview, visualize, diagram, explain visually, slides, html output, visual diff, plan review, recap, ascii diagram, generate html, make slides, show diagram, refresh diagrams, regenerate diagrams, update my class diagram, rebuild diagrams, sync diagrams

Runs in t1k-docs-manager (or inline). Mode selection stays inline; the two scripts are deterministic.

StepAgent
Run scripts/adapter-discovery.cjst1k-docs-manager
Run scripts/refresh-orchestrator.cjs for --refresht1k-docs-manager