Deprecate the terminal (Mermaid→ASCII) surface; make termchart viewer-first

.claude-plugin/marketplace.json

@@ -8,18 +8,18 @@
     {
       "name": "termchart",
       "source": "./plugin",
-      "description": "A live canvas your AI draws on — instead of walls of text, your agent pushes rich, native visuals to a browser / iPad / second screen in real time: React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes, with animated edges and live status overlays (toasts, progress bars, loaders). Deterministic Mermaid → ASCII/Unicode is the terminal fallback. Persona recipes, a showcase gallery, and fullscreen panes.",
-      "version": "0.14.0",
+      "description": "A live canvas your AI draws on — instead of walls of text, your agent pushes rich, native visuals to a browser / iPad / second screen in real time: React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes, with animated edges and live status overlays (toasts, progress bars, loaders). Persona recipes, a showcase gallery, and fullscreen panes. (A deterministic Mermaid → ASCII/Unicode terminal renderer is still bundled but deprecated.)",
+      "version": "0.15.0",
       "license": "MIT",
       "keywords": [
-        "mermaid",
-        "ascii",
-        "diagram",
-        "terminal",
+        "viewer",
         "react-flow",
         "vega-lite",
-        "viewer",
-        "charts"
+        "dashboard",
+        "charts",
+        "diagram",
+        "mantine",
+        "ipad"
       ]
     }
   ]

AGENTS.md

@@ -1,10 +1,10 @@
 # termchart — agent guide
 
-termchart draws diagrams for you: **inline ASCII/Unicode in the terminal**, or **rich live
-visuals pushed to a web viewer** (React Flow graphs, Mantine UI dashboards, Vega-Lite charts,
-markdown, split panes) plus **status overlays** (toasts / progress bars / loaders). Prefer it
-over describing a diagram in prose, hand-drawing ASCII (which misaligns), or emitting a raw
-Mermaid block the user can't see inline.
+termchart draws diagrams for you: **rich live visuals pushed to a web viewer** (React Flow
+graphs, Mantine UI dashboards, Vega-Lite charts, markdown, split panes) plus **status overlays**
+(toasts / progress bars / loaders). Prefer it over describing a diagram in prose or emitting a
+raw Mermaid block the user can't see. (A deterministic Mermaid→ASCII terminal renderer is still
+bundled but **deprecated** — use the viewer.)
 
 This is the cross-tool [`AGENTS.md`](https://agents.md) standard — read natively by Antigravity,
 Cursor, Codex, Copilot, Gemini CLI, Windsurf, Zed, Aider, and others (and by Claude Code via
@@ -15,24 +15,6 @@ there are no per-agent install steps.
 
 - The `termchart` CLI must be on PATH (npm, Node ≥18). Self-heal before first use:
   `command -v termchart >/dev/null || npm i -g @ivanmkc/termchart`
-- **Always render to a file** with `--color none`, read it back, and paste it **verbatim** into
-  your reply. Agent terminals fold long tool output behind a `+N lines` collapse, so a diagram
-  left in the terminal shows up broken — it only displays correctly inside your message.
-
-## Inline diagrams (terminal)
-
-Write Mermaid in the supported subset (flowchart / sequence / state / class / ER / xychart),
-lint it, render to a file, then paste the file's contents:
-
-```bash
-printf 'graph LR\n A[Client]-->B[API]-->C[(DB)]' | termchart lint
-termchart --color none diagram.mmd > out.txt   # then READ out.txt and paste it byte-for-byte
-```
-
-Supported subset: `graph TD|LR` nodes `A[x]` `B{decision}` `C[(db)]` edges `-->`/`-->|label|`,
-`stateDiagram-v2`, `sequenceDiagram` (`A->>B: msg` only — no note/loop/alt/opt/par),
-`classDiagram`, `erDiagram`, `xychart-beta`. Full grammar + flags:
-<https://github.com/ivanmkc/termchart/blob/master/plugin/skills/termchart/SKILL.md>.
 
 ## Rich visuals + progress (the live viewer)
 
@@ -57,7 +39,9 @@ sequence/ER/class/state graphs) from the formats + copy-paste examples here:
 
 | Want | Use |
 |---|---|
-| an inline ASCII diagram in chat | `termchart` render (terminal) |
 | a live rich visual on a screen / iPad | `termchart push --type …` |
 | show activity the instant work starts | `termchart begin …` (placeholder + focus + loader) |
 | narrate long work (toasts / progress / loaders) | `termchart status …` |
+
+_Deprecated: `termchart <file>` still renders Mermaid → terminal ASCII, but it's no longer the
+recommended surface — push to the viewer instead._

README.md

@@ -7,14 +7,14 @@ it pushes *native* visuals to a browser tab in real time — architecture maps,
 reviews, charts, call graphs, live progress — so you glance at a **companion screen** (a second
 monitor or an iPad) and just *see* what your agent is doing and thinking, no scrolling required.
 It ships as a **CLI** (`termchart`) plus a **Claude Code plugin** (skills + the
-`/termchart:diagram` and `/termchart:diagram-remote` commands):
+`/termchart:diagram-remote` command):
 
-- **The canvas (primary).** Run the viewer **locally** (or deploy it); agents push rich,
-  *native* visuals over SSE — React Flow graphs, Vega-Lite charts, Mantine UI dashboards,
-  markdown, and split panes — plus live **status overlays** (toasts / progress bars / loaders).
-  Best on a second monitor or an iPad.
-- **Inline terminal text (secondary).** Deterministic **Mermaid → ASCII/Unicode** that pastes
-  cleanly into PRs, issues, and chat — no PNGs, no browser, no Mermaid handoff.
+- **The canvas.** Run the viewer **locally** (or deploy it); agents push rich, *native* visuals
+  over SSE — React Flow graphs, Vega-Lite charts, Mantine UI dashboards, markdown, and split
+  panes — plus live **status overlays** (toasts / progress bars / loaders). Best on a second
+  monitor or an iPad.
+- **Inline terminal text (deprecated).** A deterministic **Mermaid → ASCII/Unicode** renderer is
+  still bundled (`termchart <file>`), but it's no longer the focus — push to the viewer instead.
 
 ![termchart viewer rendering a narrative PR review — before/after cards, a timeline, a validation banner, and an FAQ, with a link out to the pull request](packages/viewer/docs/gallery/pr-review-summary.png)
 
@@ -39,7 +39,7 @@ the right visual and draws it:
 
 ```
 /termchart:diagram-remote  a sequence diagram of the OAuth login flow     →  on the canvas
-/termchart:diagram         a state machine for an order's lifecycle       →  inline ASCII
+/termchart:diagram-remote  a state machine for an order's lifecycle       →  on the canvas
 ```
 
 Or just say it in any message — *“put that on the termchart canvas”*, *“draw that as a diagram”* —
@@ -245,7 +245,11 @@ GCS env are set, GitHub wins and a line is logged).
 
 ---
 
-## In the terminal
+## In the terminal (deprecated)
+
+> ⚠️ **Deprecated.** The terminal Mermaid → ASCII/Unicode renderer still works but is no longer
+> the focus of termchart — prefer the live viewer above (`termchart serve` + `termchart push`).
+> It remains bundled for backward compatibility; this section is kept as reference.
 
 Deterministic Mermaid → ASCII/Unicode from the same `termchart` CLI. Built on
 [`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid) — a synchronous, no-DOM
@@ -343,24 +347,23 @@ below is an alternative for Claude users.
 ```
 
 On session start the plugin ensures the `termchart` CLI is on your PATH (installing it from
-npm if missing). Then use **`/termchart:diagram`** (inline terminal) or
-**`/termchart:diagram-remote`** (live viewer).
+npm if missing). Then use **`/termchart:diagram-remote`** to draw on the live viewer.
 
 #### Optional: a bare `/diagram` alias
 
-Claude Code namespaces plugin commands (`/termchart:diagram`). For a plain `/diagram`, drop a
-one-line user command:
+Claude Code namespaces plugin commands (`/termchart:diagram-remote`). For a plain `/diagram`,
+drop a one-line user command that draws on the viewer:
 
 ```bash
 mkdir -p ~/.claude/commands
 cat > ~/.claude/commands/diagram.md <<'EOF'
 ---
-description: Render a diagram as terminal ASCII via termchart
-argument-hint: [mermaid source OR a description of the diagram you want]
+description: Draw a diagram on the termchart live viewer
+argument-hint: [a description of the diagram you want]
 ---
-Render the following as aligned terminal text with the `termchart` CLI, following the
-`termchart` skill: write Mermaid in the supported subset, `termchart lint` it, then
-`termchart --ascii --color none` it and paste the output verbatim.
+Push the following to the termchart viewer, following the `diagram-recipes` skill: pick the
+right rich type (component / flow / vegalite / panes / …), author its JSON, and
+`termchart push --type <type> …`.
 
 $ARGUMENTS
 EOF

packages/cli/README.md

@@ -1,12 +1,13 @@
 # termchart
 
-Diagrams for coding agents, two ways:
-
-- **In the terminal** — deterministic **Mermaid → ASCII/Unicode** that pastes cleanly into
-  PRs, issues, and chat. No PNGs, no browser, no Mermaid handoff.
-- **To a live viewer** — `termchart push` / `termchart status` send rich, native visuals
-  (React Flow, Vega-Lite, Mantine UI, markdown, panes) and progress overlays to a browser tab
-  you run locally or deploy. See the [repo](https://github.com/ivanmkc/termchart).
+Diagrams for coding agents:
+
+- **To a live viewer (the focus)** — `termchart push` / `termchart status` send rich, native
+  visuals (React Flow, Vega-Lite, Mantine UI, markdown, panes) and progress overlays to a
+  browser tab you run locally or deploy. See the [repo](https://github.com/ivanmkc/termchart).
+- **In the terminal (deprecated)** — a deterministic **Mermaid → ASCII/Unicode** renderer
+  (`termchart <file>`) is still bundled for backward compatibility, but it's no longer the
+  focus; prefer the viewer.
 
 Terminal rendering is built on
 [`beautiful-mermaid`](https://github.com/lukilabs/beautiful-mermaid), a synchronous no-DOM grid

packages/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ivanmkc/termchart",
   "version": "0.7.0",
-  "description": "Push native diagrams, charts, dashboards & live status to the termchart viewer (browser/iPad) in real time — the CLI for the live canvas your AI draws on; also renders deterministic Mermaid → ASCII/Unicode in the terminal.",
+  "description": "Push native diagrams, charts, dashboards & live status to the termchart viewer (browser/iPad) in real time — the CLI for the live canvas your AI draws on. (Also bundles a deprecated Mermaid → ASCII/Unicode terminal renderer.)",
   "type": "module",
   "bin": {
     "termchart": "dist/cli.js"
@@ -38,12 +38,13 @@
     "url": "git+https://github.com/ivanmkc/termchart.git"
   },
   "keywords": [
-    "mermaid",
-    "ascii",
-    "terminal",
+    "viewer",
     "diagram",
+    "react-flow",
+    "vega-lite",
+    "dashboard",
+    "charts",
     "cli",
-    "unicode",
-    "flowchart"
+    "mermaid"
   ]
 }

packages/cli/src/cli.ts

@@ -23,11 +23,9 @@ import { VERSION } from "./version.js";
 const DEFAULT_NON_TTY_WIDTH = 80;
 
 
-const USAGE = `termchart — deterministic Mermaid → ASCII/Unicode for terminals
+const USAGE = `termchart — push rich diagrams to a live viewer (browser / iPad)
 
 Usage:
-  termchart [file]            Render a Mermaid file, or stdin if omitted
-  termchart lint [file]       Check source is within the renderable subset
   termchart serve [flags]     Start a local viewer + print its URL and env exports (--port --token --wsid --bucket)
   termchart begin [flags]     Show a scope as "composing" instantly — placeholder + focus + loader in one call (--project --agent --description)
   termchart push [flags]      Push a diagram to the remote viewer (--project --agent --type --description --focus [--schema <file> to make it template-able])
@@ -45,7 +43,11 @@ Usage:
   termchart run <id>          Refresh a scheduled board now — enforce lifecycle, assemble its prompt + run its agent, which pushes the board (--timeout <secs>, default 600)
   termchart --version
 
-Render flags:
+Deprecated (terminal Mermaid → ASCII render — prefer the viewer above):
+  termchart [file]            Render a Mermaid file, or stdin if omitted
+  termchart lint [file]       Check source is within the renderable subset
+
+Deprecated terminal-render flags:
   --ascii                     Pure ASCII (+,-,|) instead of Unicode box-drawing
   --safe, --portable          Alias for --ascii — guaranteed alignment in any terminal
                               (Unicode box glyphs are ambiguous-width; width-2 terminals misalign)
@@ -236,6 +238,14 @@ export function main(argv: string[]): number {
     return 3;
   }
 
+  // The terminal Mermaid → ASCII renderer (and its lint) is deprecated: termchart is now a
+  // viewer-first tool. Still functional for backward compatibility, but nudge to the viewer.
+  // Notice goes to stderr so it never contaminates the rendered output on stdout.
+  process.stderr.write(
+    "termchart: the terminal Mermaid → ASCII renderer is deprecated — prefer the viewer " +
+      "(`termchart serve`, then `termchart push`). See the README.\n",
+  );
+
   if (args.command === "lint") {
     const result = lint(source);
     for (const w of result.warnings) process.stderr.write(`warning: ${w}\n`);

plugin/.claude-plugin/plugin.json

@@ -1,23 +1,21 @@
 {
   "name": "termchart",
   "displayName": "termchart",
-  "description": "A live canvas your AI draws on. Instead of walls of text, your agent pushes rich, native visuals to a browser tab / iPad / second screen in real time — React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine UI dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes — with animated edges and live status overlays (toasts, progress bars, loaders). Deterministic Mermaid→ASCII/Unicode is the terminal fallback. Ships persona recipes, a showcase gallery, fullscreen panes, and a collapsible sidebar. Adds /termchart commands + skills, backed by the termchart CLI.",
-  "version": "0.14.0",
+  "description": "A live canvas your AI draws on. Instead of walls of text, your agent pushes rich, native visuals to a browser tab / iPad / second screen in real time — React Flow graphs (architecture, sequence, call-graph, ER/class, state machine, PR-review, journeys, recursion trees), Vega-Lite charts (incl. scientific + Big-O), Mantine UI dashboards & product comparisons, deep-code walkthroughs, markdown, and split panes — with animated edges and live status overlays (toasts, progress bars, loaders). Ships persona recipes, a showcase gallery, fullscreen panes, and a collapsible sidebar. Adds /termchart commands + skills, backed by the termchart CLI. (A deterministic Mermaid→ASCII/Unicode terminal renderer is still bundled but deprecated.)",
+  "version": "0.15.0",
   "author": {
     "name": "Ivan Cheung"
   },
   "repository": "https://github.com/ivanmkc/termchart",
   "license": "MIT",
   "keywords": [
-    "mermaid",
-    "ascii",
-    "unicode",
-    "diagram",
-    "terminal",
-    "flowchart",
+    "viewer",
     "react-flow",
     "vega-lite",
-    "viewer",
-    "charts"
+    "dashboard",
+    "charts",
+    "diagram",
+    "mantine",
+    "ipad"
   ]
 }