@agent-native/core 0.44.4 → 0.45.0

package/dist/cli/skills.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../src/cli/skills.ts"],"names":[],"mappings":"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"}

package/dist/cli/skills.js

@@ -814,6 +814,37 @@ plan needs a richer review surface.
   update the plan with \`update-visual-plan\` rather than only changing course in
   chat, and re-read the approved plan before major steps.
 
+## Local-Files Privacy Mode
+
+Use local-files privacy mode when the user explicitly asks for no DB writes,
+no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+planning, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. In this mode the
+plan data must never be sent to the Plan MCP server or Plan app action surface.
+
+The local-files contract is:
+
+- Read source context from local files and shell commands only.
+- Write the plan as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
+  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
+  \`.plan-state.json\`.
+- Run \`agent-native plan local preview --dir plans/<slug> --kind plan\` after
+  writing or updating the folder. Report the returned local URL or the
+  \`/local-plans/<slug>\` route if the local Plan app is running with the same
+  \`PLAN_LOCAL_DIR\`.
+- Do **not** call \`create-visual-plan\`, \`create-ui-plan\`,
+  \`create-prototype-plan\`, \`create-plan-design\`, \`import-visual-plan-source\`,
+  \`update-visual-plan\`, \`patch-visual-plan-source\`, \`get-plan-feedback\`,
+  \`export-visual-plan\`, or any hosted Plan tool for that plan.
+- Treat feedback as file or chat feedback: update the MDX files directly, rerun
+  the local preview command, and summarize the new local URL/path. Hosted
+  comments, sharing, history, and publish/export receipts are unavailable until
+  the user explicitly opts into publishing.
+
+Local-files mode prevents plan content from going to the Agent-Native Plan
+database. It does not by itself make the coding agent's language model local;
+for that stronger privacy boundary, the host agent/model must also be local or
+otherwise approved by the user.
+
 ## Core Workflow
 
 1. Follow the host agent's normal planning flow: inspect the codebase, delegate
@@ -1466,6 +1497,41 @@ schema, API, file, and architecture changes become the same \`data-model\`,
 now they summarize work that exists. A reviewer scans the shape of the change
 before spending attention on the literal lines.
 
+## Local-Files Privacy Mode Exception
+
+Use local-files privacy mode when the user explicitly asks for no DB writes,
+no hosted Plan app, no Plan MCP publish, fully local files, offline/private
+recaps, or when \`AGENT_NATIVE_PLANS_MODE=local-files\` is set. This is the only
+exception to the hosted publish rule below.
+
+In local-files mode:
+
+- Read the diff/stat/source context from local files and shell commands only.
+  The existing \`agent-native recap collect-diff\`, \`scan\`, and
+  \`build-prompt --local-files\` helpers are safe to use because they operate on
+  local files and do not write to the Plan database.
+- Write the recap as a local MDX folder under \`plans/<slug>/\`: \`plan.mdx\`,
+  optional \`canvas.mdx\`, optional \`prototype.mdx\`, and optional
+  \`.plan-state.json\`. Set \`kind: "recap"\` and \`localOnly: true\` in
+  frontmatter/state when authoring the source.
+- Run \`agent-native plan local preview --dir plans/<slug> --kind recap\` after
+  writing or updating the folder. Report the returned local URL or the
+  \`/local-plans/<slug>\` route if the local Plan app is running with the same
+  \`PLAN_LOCAL_DIR\`.
+- Do **not** call \`create-visual-recap\`, \`create-visual-plan\`,
+  \`import-visual-plan-source\`, \`update-visual-plan\`,
+  \`patch-visual-plan-source\`, \`get-plan-feedback\`, \`export-visual-plan\`,
+  \`set-resource-visibility\`, or any hosted Plan tool for that recap.
+- Treat review feedback as file or chat feedback: update the MDX files directly,
+  rerun the local preview command, and summarize the new local URL/path.
+  Hosted comments, sharing, screenshots, usage attachment, and PR sticky comment
+  publishing are unavailable until the user explicitly opts into publishing.
+
+Local-files mode prevents recap content from going to the Agent-Native Plan
+database. It does not by itself make the coding agent's language model local;
+for that stronger privacy boundary, the host agent/model must also be local or
+otherwise approved by the user.
+
 ## Always Publish As An Agent-Native Plan — Never Inline
 
 The deliverable is ALWAYS a published Agent-Native Plan, created with the
@@ -1476,7 +1542,8 @@ entire value is the hosted, interactive, annotatable plan; an inline summary is
 not a recap, it is the thing a recap replaces. The only supported output is to
 publish the plan and return its absolute URL.
 
-If the \`plan\` MCP server's tools are not available, do NOT improvise an inline
+Except for the explicit local-files privacy mode above, if the \`plan\` MCP
+server's tools are not available, do NOT improvise an inline
 recap as a fallback. The usual cause is a connector that did not finish
 connecting this session (it registers zero tools), NOT necessarily an auth
 problem — so do not assume the user must authenticate. Stop and tell the user
@@ -1537,12 +1604,12 @@ evidence:
 
 - A \`file-tree\` of the changed files with each entry's \`change\` flag, so the
   reviewer sees the footprint of the work at a glance.
-- The \`diff\` of the KEY changed files, grouped under a \`## Key changes\`
-  \`rich-text\` heading in a single vertical \`tabs\` block (file labels as the left
-  rail), with a one-line \`summary\` and a few \`annotations\` on each — so the
-  reviewer can drop from the high-altitude shape straight into the load-bearing
-  code. Leave \`mode\` unset so each diff renders unified — the default — because a
-  tab panel is too narrow for split's side-by-side gutters to stay legible.
+- The split \`diff\` of the KEY changed files, grouped under a \`## Key changes\`
+  \`rich-text\` heading in a single horizontal \`tabs\` block (the default
+  orientation, one file per tab), with a one-line \`summary\` and a few
+  \`annotations\` on each — so the reviewer can drop from the high-altitude shape
+  straight into the load-bearing code. Use horizontal file tabs, not a vertical
+  side rail, so the selected file has enough width for the side-by-side diff.
 
 Skip the diff appendix only for a genuinely tiny change that reviews faster as
 plain diff (see "When To Use"); for any change worth recapping, the file-tree and
@@ -1822,6 +1889,11 @@ text-match screenshot is not enough; visually inspect the captured image.
 
 ## Open And Report The Recap
 
+In local-files privacy mode, report the local preview URL/path from
+\`agent-native plan local preview\` or the \`/local-plans/<slug>\` route for a local
+Plan app using the same \`PLAN_LOCAL_DIR\`. Do not invent a hosted URL and do not
+publish just to get an absolute Plan link.
+
 After creating the recap, link the reviewer to the rendered plan with an
 **absolute URL on the origin whose database actually holds the plan**. That
 origin is the Plan MCP server you just created the recap through — NOT whatever
@@ -1865,7 +1937,9 @@ artifacts, not as the main way to open the recap.
 ## Diff → Block Mapping
 
 Map each kind of change to the block that carries it, derived mechanically from
-the actual diff:
+the actual diff. The names below are the CONCEPTUAL block types, not the JSX
+tags — resolve every conceptual name to its exact tag + prop schema with the
+\`get-plan-blocks\` tool (see "Block reference" below) before authoring.
 
 - **Schema / migration change** → \`data-model\` for the resulting entities,
   fields, and relations. Flag what moved per field/entity with
@@ -1892,42 +1966,36 @@ the actual diff:
 - **Compatibility-sensitive change** → short \`rich-text\` notes beside the
   relevant \`data-model\` / \`api-endpoint\` block. Name the changed field,
   endpoint, or behavior and mark whether it is breaking, risky, or non-breaking;
-  pair that note with a \`diff\` for the literal lines.
-- **Any meaningful code hunk** → \`diff\` carrying the real \`before\` / \`after\` text
-  and the \`filename\` / \`language\`. Leave \`mode\` unset: unified is the default and
-  the right choice for a recap, since recap diffs almost always sit inside a
-  width-constrained container (a vertical-tabs panel or a comparison column)
-  where split's two line-number gutters cut the code off. Reach for \`mode:
-  "split"\` only for a standalone, full-document-width diff where side-by-side
-  genuinely helps. Give every \`diff\` a one-line \`summary\` saying what the hunk
-  changes and why; it renders as a description above the code so the reviewer
-  reads intent first. Never leave a diff unlabeled.
+  pair that note with a split \`diff\` for the literal lines.
+- **Any meaningful code hunk** → \`diff\` with \`mode: "split"\`, carrying the real
+  \`before\` / \`after\` text and the \`filename\` / \`language\`. Split mode is the
+  default for recap code review because before/after legibility is the point;
+  use \`mode: "unified"\` only for a genuinely narrow standalone hunk where
+  side-by-side would hide the code. Give every \`diff\` a one-line \`summary\`
+  saying what the hunk changes and why; it renders as a description above the
+  code so the reviewer reads intent first. Never leave a diff unlabeled.
   For the KEY changed files, attach \`annotations\` to the \`diff\` so the recap
   calls out what each important hunk does — this is the headline affordance for
-  annotating the key files updated. Each annotation is
-  \`{ side?: "before" | "after"; lines: "13" | "13-15"; label?: string; note }\`
-  and anchors to the AFTER-side line numbers by default (set \`side: "before"\` to
-  point at removed lines). Keep it to a few high-signal notes per file, not one
-  per line.
+  annotating the key files updated. Each annotation anchors to the AFTER-side
+  line numbers by default (set \`side: "before"\` to point at removed lines). Keep
+  it to a few high-signal notes per file, not one per line.
   When several key files each need a substantial diff, introduce the group with a
   \`rich-text\` heading block whose markdown is \`## Key changes\`, then place the
-  \`diff\` blocks under it in a reusable \`tabs\` block with
-  \`orientation: "vertical"\` so file labels form a left rail and the selected
-  file's diff renders unified on the right. Leave each diff's \`mode\` unset — the
-  tab panel is too narrow for split — and let the unified default carry it. Let
-  that heading label the section — do NOT also set a \`title\` on the \`tabs\` block.
-  Keep each tab label to the file path or a short basename plus directory hint.
+  \`diff\` blocks under it in a reusable \`tabs\` block with horizontal orientation
+  (the default — omit \`orientation\`) so the selected file's split diff gets the
+  full document width. Let that heading label the section — do NOT also set a
+  \`title\` on the \`tabs\` block. Keep each tab label to the file path or a short
+  basename plus directory hint.
   If the recap ends with more than one supporting diff, that trailing diff
-  appendix should be one vertical \`tabs\` block under its own \`## Key changes\`
+  appendix should be one horizontal \`tabs\` block under its own \`## Key changes\`
   heading, not a stack of separate \`diff\` blocks.
 - **Brand-new file or a substantial added block with no meaningful "before"** →
-  \`annotated-code\` rather than a one-sided \`diff\`. Carry the real new code
+  \`annotated-code\` rather than a one-sided split \`diff\`. Carry the real new code
   with its \`filename\` / \`language\` and anchor a few high-signal notes to the lines
-  that matter (\`{ lines: "12" | "12-18"; label?; note }\`) so the reviewer reads
-  what the new code does, not code for code's sake. Keep \`diff\` for true
-  before/after hunks where the removed lines still carry meaning, and group
-  several annotated walkthroughs in a vertical \`tabs\` block the same way diffs are
-  grouped.
+  that matter so the reviewer reads what the new code does, not code for code's
+  sake. Keep split \`diff\` for true before/after hunks where the removed lines
+  still carry meaning, and group several annotated walkthroughs in a horizontal
+  \`tabs\` block the same way diffs are grouped.
 - **Files added / removed / renamed** → \`file-tree\` with each entry's \`change\`
   flag (\`added\`, \`removed\`, \`modified\`, \`renamed\`) and a short \`note\`; attach a
   \`snippet\` only when one tells the reviewer something the path does not.
@@ -1941,10 +2009,9 @@ the actual diff:
   blocks carry implementation evidence.
 - **Architecture or data-flow shift** → \`diagram\` with \`data.html\` / \`data.css\`
   as a two-panel before/after, layered, or swimlane layout, or \`mermaid\` for a
-  quick graph. Use the two-dimensional layouts the Document Quality core
-  prescribes; do not reduce a structural change to a left-to-right chain.
-  Do not use \`diagram\` as a stand-in for rendered UI controls; UI changes need
-  \`wireframe\` blocks.
+  quick graph. Use two-dimensional layouts; do not reduce a structural change to
+  a left-to-right chain. Do not use \`diagram\` as a stand-in for rendered UI
+  controls; UI changes need \`wireframe\` blocks.
   Diagram HTML/CSS should use renderer-owned primitives such as
   \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
   \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; these map to the plan's
@@ -1957,349 +2024,55 @@ the actual diff:
   the objective the diff served, the key decisions visible in it, and the risks a
   reviewer should weigh. This is the only place the model writes freely.
 
-## Block MDX reference
-
-This is the authoritative tag + prop shape for every importable block. Author the
-recap source against THESE tags and props — do not guess from the conceptual
-names above (the conceptual name like \`api-endpoint\` is NOT the JSX tag). A wrong
-tag or prop shape either 500s the import with a ZodError or, for an unrecognized
-capitalized tag, now **fails the import with a clear "Unknown plan block" error**
-(it used to silently render as raw \`<JsonExplorer …>\` text — that footgun is
-fixed). Every block also takes the shared envelope attributes \`id\` (REQUIRED,
-unique across the whole plan), and optional \`title\`, \`summary\`, \`editable\` —
-those are omitted from the per-block prop lists below.
-
-The complete set of real block tags is exactly: \`RichText\`, \`FileTree\`,
-\`DataModel\`, \`Endpoint\`, \`Diff\`, \`AnnotatedCode\`, \`WireframeBlock\` (body
-\`<Screen>\` + wireframe-kit children), \`Columns\`/\`Column\`, \`TabsBlock\`, \`Callout\`,
-\`Diagram\`, \`Mermaid\`, \`Json\`, \`HtmlBlock\`, \`Table\`, \`Checklist\`, \`Code\`,
-\`OpenApi\`. Any other capitalized tag at the block level is rejected on import.
-
-Quick tag map (conceptual name → real JSX tag):
-
-| Conceptual | Real tag | Conceptual | Real tag |
-| --- | --- | --- | --- |
-| api-endpoint | \`Endpoint\` | diff | \`Diff\` |
-| data-model | \`DataModel\` | annotated-code | \`AnnotatedCode\` |
-| file-tree | \`FileTree\` | code | \`Code\` |
-| mermaid | \`Mermaid\` | rich-text | \`RichText\` |
-| diagram | \`Diagram\` | callout | \`Callout\` |
-| json-explorer | \`Json\` | columns | \`Columns\` (cols are \`Column\`) |
-| openapi-spec | \`OpenApi\` | tabs | \`TabsBlock\` |
-| wireframe | \`WireframeBlock\` (body \`<Screen>\`) | table | \`Table\` |
-| custom-html | \`HtmlBlock\` | checklist | \`Checklist\` |
-
-### Common mistakes (these now error on import)
-
-These WRONG tags used to be swallowed as raw text. Common synonyms are now
-auto-corrected to the canonical tag on import; anything not in this map is
-rejected with a "did you mean" hint. Always author with the canonical tag —
-do not rely on the aliases.
-
-| WRONG tag | → use |
-| --- | --- |
-| \`JsonExplorer\` | \`Json\` |
-| \`Tabs\` (or a nested \`Tab\` child) | \`TabsBlock\` (tabs are ONE JSON \`tabs={[…]}\` prop — there is NO nested \`<Tab>\` element) |
-| \`ApiEndpoint\` | \`Endpoint\` |
-| \`DiffBlock\` | \`Diff\` |
-| \`AnnotatedCodeBlock\` | \`AnnotatedCode\` |
-| \`Wireframe\` | \`WireframeBlock\` |
-
-Lowercase HTML tags inside \`RichText\`/markdown prose (\`<div>\`, \`<span>\`,
-\`<code>\`, \`<br>\`, …) are always fine — only capitalized component-style tags at
-the block level are validated.
-
-### \`Endpoint\` (API / route)
-
-Tag is \`Endpoint\` — NOT \`ApiEndpoint\`. Required attrs: \`method\`, \`path\`. Optional
-attrs: \`summary\` (the short title — NOT \`title\`), \`auth\`, \`deprecated\` (bool),
-\`change\`, \`params\`, \`request\`, \`responses\`. The prose \`description\` is the MDX
-**children** (body between the tags), NOT an attribute.
-
-- \`method\` ∈ \`GET | POST | PUT | PATCH | DELETE | HEAD | OPTIONS\`. For a
-  WebSocket upgrade use \`GET\`.
-- \`change\` (and per-param/per-response \`change\`) ∈ \`added | modified | removed | renamed\`.
-- \`params={[{ name, in, type?, required?, description?, change?, was? }]}\` where
-  \`in\` ∈ \`path | query | header | body\`.
-- \`request={{ contentType?, example? }}\` — \`example\` is a JSON **string**, not a
-  nested object.
-- \`responses={[{ status, description?, example?, change? }]}\` — each \`example\` is
-  a JSON **string** (the renderer parses it into the collapsible JsonExplorer).
-  Give each distinct message shape (e.g. success vs error, or separate WS frame
-  types) its OWN response entry, not one merged body.
-
-\`\`\`mdx
-<Endpoint
-  id="ep-create-task"
-  method="POST"
-  path="/api/tasks"
-  summary="Create a task"
-  request={{ contentType: "application/json", example: '{"title":"Ship recap"}' }}
-  responses={[{ status: "201", description: "Created", example: '{"id":"t_1","title":"Ship recap"}' }]}
->
-
-Creates a task scoped to the caller's org.
-
-</Endpoint>
-\`\`\`
-
-### \`DataModel\` (schema / ER)
-
-Tag is \`DataModel\`. Required attr: \`entities\` (>= 1). Optional attr: \`relations\`.
-There is NO top-level \`fields=\` attribute — fields live inside each entity. There
-is NO per-field \`required\` or \`description\` key; fold either into \`note\`.
-
-- \`entities={[{ id, name, note?, change?, fields: [...] }]}\` — \`id\` is referenced
-  by relations.
-- each field: \`{ name, type?, pk?, fk?, nullable?, default?, note?, change?, was? }\`.
-  \`pk\`/\`nullable\` are booleans; \`fk\` is a string target like \`"User.id"\`;
-  \`change\` ∈ \`added | modified | removed | renamed\`; \`was\` is the prior value
-  when \`change\` is \`modified\`.
-- \`relations={[{ from, to, kind?, label? }]}\` (optional — the renderer infers
-  simple \`1-n\` from \`fk\` when omitted); \`kind\` ∈ \`1-1 | 1-n | n-n\`.
-
-\`\`\`mdx
-<DataModel
-  id="dm-tasks"
-  entities={[
-    {
-      id: "task",
-      name: "Task",
-      fields: [
-        { name: "id", type: "uuid", pk: true },
-        { name: "title", type: "text" },
-        { name: "status", type: "text", change: "added", note: "open|done" }
-      ]
-    }
-  ]}
-/>
-\`\`\`
-
-### \`FileTree\` (changed files)
-
-Tag is \`FileTree\`. Required attr: \`entries\` (>= 1). Optional attr: \`title\`. The
-tree is built from the leaf \`path\`s — do NOT pass an ASCII tree in children; the
-block is self-closing.
-
-- \`entries={[{ path, change?, note?, snippet?, language? }]}\` — \`path\` is
-  slash-delimited; \`change\` ∈ \`added | modified | removed | renamed\`. Add a
-  \`snippet\` (with optional \`language\`) only when it says something the path does
-  not.
-
-\`\`\`mdx
-<FileTree
-  id="ft-changed"
-  title="Files touched"
-  entries={[
-    { path: "server/routes/tasks.ts", change: "modified", note: "add POST handler" },
-    { path: "server/db/schema.ts", change: "modified" },
-    { path: "tests/tasks.test.ts", change: "added" }
-  ]}
-/>
-\`\`\`
-
-### \`Mermaid\` (graph)
-
-Tag is \`Mermaid\` — this is its OWN block, separate from \`Diagram\`. Required attr:
-\`source\` (the diagram text). Optional attr: \`caption\`. Do NOT put mermaid text
-inside a \`Diagram\` block, and do NOT use \`<Diagram mermaid={...}>\` — that is not a
-real prop and will not render.
-
-\`\`\`mdx
-<Mermaid
-  id="mm-flow"
-  source={\`flowchart LR
-  Client --> API
-  API --> DB\`}
-  caption="Request path"
-/>
-\`\`\`
-
-### \`Diagram\` (HTML/SVG or node graph)
-
-Tag is \`Diagram\`. The whole payload is ONE \`data\` attribute:
-\`data={{ html?, css?, caption?, nodes?, edges?, notes? }}\`. It requires either
-\`html\` (an inert HTML/SVG fragment) OR at least one node — a \`Diagram\` with
-neither fails validation. This is for architecture / data-flow / dependency
-relationships, NOT rendered UI (use a wireframe for UI) and NOT mermaid (use
-\`Mermaid\`). Use \`.diagram-*\` primitives + \`--wf-*\` tokens in \`html\`/\`css\`; never
-hex colors or \`font-family\`.
-
-\`\`\`mdx
-<Diagram
-  id="dg-arch"
-  data={{
-    nodes: [
-      { id: "ui", label: "UI" },
-      { id: "api", label: "API" },
-      { id: "db", label: "DB" }
-    ],
-    edges: [
-      { from: "ui", to: "api" },
-      { from: "api", to: "db" }
-    ]
-  }}
-/>
-\`\`\`
-
-### \`Json\` (JSON explorer)
-
-Tag is \`Json\`. Required attr: \`json\` — a **string** containing the JSON.
-Optional attrs: \`title\`, \`collapsedDepth\` (number, default 2).
-
-\`\`\`mdx
-<Json
-  id="json-config"
-  title="Resolved config"
-  json={'{"flags":{"recap":true},"limit":50}'}
-/>
-\`\`\`
-
-### \`Diff\` (before/after)
-
-Tag is \`Diff\`. Required attrs: \`before\`, \`after\` (multiline source strings).
-Optional attrs: \`filename\`, \`language\`, \`mode\` (\`unified | split\`), \`annotations\`.
-Leave \`mode\` unset: it defaults to **unified**, which reads cleanly at any width
-and is what recap diffs want — they almost always live inside a width-constrained
-container (a vertical-tabs panel or a comparison column) where split's two
-line-number gutters cut the code off. Only set \`mode: "split"\` for a standalone,
-full-document-width diff where side-by-side genuinely helps. The reader always
-exposes a Unified/Split toggle (when there is room), so a viewer can switch
-either way regardless of the authored default. Give every diff a \`summary\` (the
-shared envelope attr) so the reviewer reads intent first.
-
-- \`annotations={[{ side?, lines, label?, note }]}\` — \`side\` ∈ \`before | after\`
-  (default \`after\`); \`lines\` is a 1-based ref like \`"13"\` or \`"13-15"\`.
-
-\`\`\`mdx
-<Diff
-  id="diff-handler"
-  filename="server/routes/tasks.ts"
-  language="ts"
-  summary="Add the POST /api/tasks handler"
-  before={\`router.get("/api/tasks", list);\`}
-  after={\`router.get("/api/tasks", list);\\nrouter.post("/api/tasks", create);\`}
-  annotations={[{ side: "after", lines: "2", label: "New route", note: "Creates a task" }]}
-/>
-\`\`\`
-
-### \`AnnotatedCode\` (new-file walkthrough)
-
-Tag is \`AnnotatedCode\`. Required attr: \`code\` (multiline string). Optional attrs:
-\`filename\`, \`language\`, \`annotations\`. Use this for a brand-new file with no
-meaningful "before".
-
-- \`annotations={[{ lines, label?, note }]}\` — 1-based \`lines\` ref (no \`side\`,
-  unlike \`Diff\`).
-
-\`\`\`mdx
-<AnnotatedCode
-  id="ac-create"
-  filename="server/tasks/create.ts"
-  language="ts"
-  code={\`export async function create(input: NewTask) {\\n  return db.tasks.insert(input);\\n}\`}
-  annotations={[{ lines: "1-3", label: "Handler", note: "Inserts and returns the row" }]}
-/>
-\`\`\`
-
-### \`RichText\` (prose)
-
-Tag is \`RichText\`. The markdown is the MDX **children** (body between the tags),
-NOT an attribute. Use \`## Key changes\` here as the heading above a grouped diff
-\`TabsBlock\`.
-
-\`\`\`mdx
-<RichText id="rt-why">
-
-## Why
-
-Adds a create endpoint so the agent can author tasks directly.
-
-</RichText>
-\`\`\`
-
-### \`Callout\` (tone note)
-
-Tag is \`Callout\`. Optional attr: \`tone\` ∈ \`info | decision | risk | warning | success\`.
-The body markdown is the MDX **children**, NOT an attribute.
-
-\`\`\`mdx
-<Callout id="co-risk" tone="risk">
-
-The new column is non-nullable with no default — existing rows need a backfill.
-
-</Callout>
-\`\`\`
-
-### \`Columns\` (side-by-side)
-
-Tag is \`Columns\`; each column is a nested \`<Column label="...">\` whose body is
-markdown and/or block components. 1–4 columns. Use labels \`Before\` / \`After\` for
-structured comparisons.
-
-\`\`\`mdx
-<Columns id="cols-schema">
-<Column label="Before">
-
-\`status\` did not exist.
-
-</Column>
-<Column label="After">
-
-<DataModel id="dm-after" entities={[{ id: "task", name: "Task", fields: [{ name: "status", type: "text", change: "added" }] }]} />
-
-</Column>
-</Columns>
-\`\`\`
-
-### \`TabsBlock\` (tab rail)
-
-Tag is \`TabsBlock\` — NOT \`Tabs\`, and there is NO nested \`<Tab>\` element. Required
-attr: \`tabs\` (1–12). Optional attr: \`orientation\` (\`horizontal | vertical\`; use
-\`vertical\` for a file rail). The whole \`tabs\` array (including nested child
-blocks) is ONE JSON prop; do NOT nest the tabs or their child blocks as MDX
-elements. Label the section with a preceding \`## Key changes\` \`RichText\` heading
-rather than a \`title\` on the block.
-
-\`\`\`mdx
-<TabsBlock
-  id="tabs-key"
-  orientation="vertical"
-  tabs={[
-    { id: "t-route", label: "routes/tasks.ts", blocks: [ /* Diff block objects */ ] },
-    { id: "t-schema", label: "db/schema.ts", blocks: [ /* Diff block objects */ ] }
-  ]}
-/>
-\`\`\`
-
-### \`WireframeBlock\` + \`<Screen>\` (UI)
-
-Tag is \`WireframeBlock\`; its body is a single \`<Screen surface ... >\` subtree
-(this is nested MDX, not a flat prop). On \`<Screen>\`, \`html\` must be a
-single-quoted string or a static template literal — NEVER a dynamic expression
-(\`html={someVar}\` throws on import). \`surface\` ∈
-\`desktop | mobile | popover | panel | browser\`. Optional \`<Screen>\` attrs:
-\`renderMode\` (\`wireframe | design\`), \`caption\`, \`css\`, \`skeleton\`. See the
-Wireframe Quality core above for the HTML rules.
-
-\`\`\`mdx
-<WireframeBlock id="wf-tasks">
-<Screen surface="browser" html={'<div style="display:flex;flex-direction:column;gap:12px;padding:16px;height:100%"><h1>Tasks</h1><button class="primary">New task</button></div>'} />
-</WireframeBlock>
-\`\`\`
-
-### Other blocks
-
-- \`HtmlBlock\` (custom-html) — flat attrs \`html\` (required, bounded fragment),
-  \`css?\`, \`caption?\`. Prefer a wireframe for UI; this is an escape hatch.
-- \`Table\` — flat attrs \`columns={["A","B"]}\` and \`rows={[["1","2"]]}\` (both arrays
-  of strings), optional \`density\` (\`compact | normal | relaxed\`).
-- \`Checklist\` — flat attr \`items={[{ id, label, checked?, note? }]}\`.
-- \`Code\` — flat attrs \`code\` (required string), \`language?\`, \`filename?\`,
-  \`caption?\`, \`maxLines?\`. For a multi-file rail use a \`TabsBlock\` of \`Code\`
-  blocks.
-- \`OpenApi\` — flat attrs \`spec\` (required JSON string of a whole OpenAPI/Swagger
-  doc), \`title?\`. The whole-document counterpart to \`Endpoint\`.
+## Block reference — call \`get-plan-blocks\`, do not memorize tags
+
+The conceptual block names above (\`api-endpoint\`, \`data-model\`, \`json-explorer\`,
+\`tabs\`, …) are NOT the JSX tags you author with, and the exact tags, required
+fields, and prop shapes change as the block library evolves. Do not author from
+memorized tags — they drift and silently produce a wrong tag (\`ApiEndpoint\`
+instead of \`Endpoint\`, \`JsonExplorer\` instead of \`Json\`, \`Tabs\` instead of
+\`TabsBlock\`) that errors on import.
+
+**Before writing any structured plan content, call \`get-plan-blocks\` on the
+\`plan\` MCP server.** It returns the authoritative, always-current block
+vocabulary generated live from the app's own block registry — the same config
+the renderer and MDX round-trip use — so it can never be stale even if this
+SKILL.md is an old installed copy:
+
+- \`get-plan-blocks\` (default \`format: "reference"\`) → a compact table of every
+  block's runtime \`type\`, exact MDX \`<Tag>\`, placement, and key data fields.
+  This is your map from each conceptual name above to its real tag and props.
+- \`get-plan-blocks\` with \`format: "schema"\` → the full per-block JSON Schema
+  plus a worked example for each block, when you need exact field types,
+  enums, or nesting (e.g. \`Diff.annotations\`, \`Endpoint.params[].in\`,
+  \`DataModel.entities[].fields[]\`).
+
+Author the recap source against the tags and schemas that call returns. The
+complete set of valid block-level tags is whatever \`get-plan-blocks\` lists;
+any other capitalized tag at the block level is rejected on import with an
+"Unknown plan block" / "did you mean" error. Lowercase HTML tags inside
+\`rich-text\`/markdown prose (\`<div>\`, \`<span>\`, \`<code>\`, \`<br>\`, …) are always
+fine — only capitalized component-style block tags are validated.
+
+A few recap-specific authoring rules the registry table cannot encode:
+
+- Every block takes a REQUIRED \`id\` (unique across the whole plan) plus the
+  shared optional \`summary\` / \`editable\` envelope; give a block a heading by
+  placing a \`rich-text\` block with a Markdown \`###\` heading directly above it
+  (blocks no longer take a \`title\`).
+- \`Endpoint\`: prose \`description\` is the MDX **children** (body between the
+  tags), not an attribute; for a WebSocket upgrade use \`method="GET"\`. Each
+  request/response \`example\` is a JSON **string** (the renderer parses it into
+  the JSON explorer), so keep it a single parseable JSON value.
+- \`TabsBlock\`: the whole \`tabs\` array (including nested child blocks) is ONE
+  JSON \`tabs={[…]}\` prop — there is NO nested \`<Tab>\` element.
+- \`WireframeBlock\`: its body is a single \`<Screen surface ... html=… />\` subtree
+  (nested MDX, not a flat prop); \`html\` must be a single-quoted string or static
+  template literal, never a dynamic \`html={someVar}\` expression. See the
+  Wireframe Quality core above for the HTML rules.
+- \`Diagram\`: the whole payload is one \`data={{ html?, css?, nodes?, edges?, … }}\`
+  attribute and requires either \`html\` or at least one node; \`Mermaid\` is its
+  own separate block (\`source\` text), not a \`Diagram\` prop.
 
 ## Before / After Is The Headline
 
@@ -2313,10 +2086,10 @@ comparisons there are two primitives, and they cover the whole need together:
   "the schema went from X to Y" or "the endpoint contract changed like this."
   Do not use \`columns\` simply to compact or group a list of API endpoints.
 - **\`diff\`** — for **code**. It renders the literal removed and added lines. Use
-  it for the actual hunks. Leave \`mode\` unset so it renders unified (the default,
-  legible at any width); reserve \`mode: "split"\` for a standalone full-width diff
-  where side-by-side genuinely helps — never inside a tabs panel or column, where
-  split's doubled gutters cut the code off.
+  it for the actual hunks. Use split mode by default for recap code review;
+  reserve \`mode: "unified"\` for genuinely narrow standalone hunks where
+  side-by-side would hide the code. Key-file diff groups should use horizontal
+  tabs so split diffs get the full document width.
 
 For UI diffs, wireframes are the visual comparison primitive. Use before/after
 wireframes when the comparison clarifies the change; use after-only or a state