@agent-native/core 0.79.26 → 0.79.27

package/corpus/templates/content/shared/content-source.ts

@@ -125,11 +125,17 @@ function normalizeSourcePath(filePath: string): string | null {
 export function isContentSourcePath(filePath: string): boolean {
   const normalized = normalizeSourcePath(filePath);
   if (!normalized) return false;
+  if (isBuilderMdxSourcePath(normalized)) return false;
   return CONTENT_SOURCE_EXTENSIONS.some((ext) =>
     normalized.toLowerCase().endsWith(ext),
   );
 }
 
+export function isBuilderMdxSourcePath(filePath: string): boolean {
+  const normalized = normalizeSourcePath(filePath);
+  return !!normalized && normalized.toLowerCase().endsWith(".builder.mdx");
+}
+
 export function isValidContentSourceId(id: string | null | undefined): boolean {
   return !!id && VALID_SOURCE_ID_RE.test(id);
 }

package/corpus/templates/content/shared/nfm-registry.ts

@@ -34,6 +34,7 @@ import {
   type SerializableBlock,
 } from "@agent-native/core/blocks/server";
 
+import { builderDocsBlockConfigs } from "./builder-docs-blocks";
 import { inlineDatabaseBlockConfig } from "./inline-database-block";
 
 /**
@@ -58,6 +59,9 @@ export function registerContentBlocks(registry: BlockRegistry): void {
   registerLibraryBlockConfigs(registry, {
     overrides: { table: { type: "table-block" } },
   });
+  for (const block of builderDocsBlockConfigs) {
+    registry.register(block);
+  }
   registry.register(inlineDatabaseBlockConfig);
 }
 

package/corpus/templates/content/vite.config.ts

@@ -31,6 +31,8 @@ const LOCAL_COMPONENTS_STUB_IMPORTS = new Set([
   "./local-components.generated.ts",
 ]);
 const COMPONENT_EXTENSIONS = new Set([".tsx", ".jsx", ".ts", ".js"]);
+const ALLOW_PRODUCTION_LOCAL_FILES_ENV =
+  "AGENT_NATIVE_ALLOW_LOCAL_FILES_IN_PRODUCTION";
 const CONTENT_LOCAL_DEFAULTS: LocalArtifactOptions["defaults"] = {
   roots: [
     { name: "Docs", path: "docs", kind: "docs", extensions: [".md", ".mdx"] },
@@ -64,6 +66,14 @@ function envManifestPath() {
   );
 }
 
+function localFilesAllowedForBuild() {
+  if (process.env.NODE_ENV !== "production") return true;
+  const value = process.env[ALLOW_PRODUCTION_LOCAL_FILES_ENV]
+    ?.trim()
+    .toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+
 function localWorkspaceRootSync() {
   const manifestPath = envManifestPath() || findAgentNativeManifest();
   if (!manifestPath) return null;
@@ -339,6 +349,9 @@ function contentLocalComponentsPlugin(): Plugin {
     },
     async load(id) {
       if (id !== RESOLVED_LOCAL_COMPONENTS_MODULE_ID) return null;
+      if (!localFilesAllowedForBuild()) {
+        return renderLocalComponentsModule([]);
+      }
       return renderLocalComponentsModule(await loadLocalComponentFiles());
     },
   };

package/corpus/templates/plan/.agents/skills/visual-plan/SKILL.md

@@ -119,24 +119,15 @@ skill's review discipline. Do not advise the user to skip `/visual-plan` because
 the default surface is hosted; choose the right Plan mode for the user's
 ownership, privacy, sharing, and branding needs.
 
-By default, create the plan via the Plan MCP connector. NEVER hand the plan over
-as inline chat content — no Markdown prose, ASCII sketch, table, or fenced
-wireframe. Some clients lazy-load connector tools through a deferred tool
-registry instead of showing the `plan` namespace upfront; before declaring the
-connector missing, search/load tools with the host's discovery surface
-(`tool_search` when available) for `create_visual_plan`, `create_ui_plan`, or
-`get_plan_blocks`, then use the Plan MCP tools it exposes. If the connector's
-tools are still missing after discovery, do NOT fall back to inline output: the
-usual cause is a connector that did not finish connecting this session (it
-registers zero tools), not auth. Stop and give the user the exact restore step
-for their current client: in Codex/Codex Desktop run
-`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
-and start a new Codex session; in Claude Code run `/mcp` and choose
-Authenticate/Reconnect (or run the same reconnect command with
-`--client claude-code` and restart Claude). Auth is stored per client
-config/session, so one client's reconnect does not make another running client
-load tools. Never reinstall from scratch just to fix auth. Publish once the tool
-is reachable. Local-files privacy mode (after Tool Guidance) is the exception.
+By default, create the plan via the Plan MCP connector and NEVER hand it over as
+inline chat content — no Markdown prose, ASCII sketch, table, or fenced
+wireframe. If the `plan` (or legacy `agent-native-plans`) tools are not visible,
+discover them through the host's `tool_search` first; if they are still missing,
+STOP and give the user the client-specific reconnect step rather than improvising
+an inline plan. Before publishing, or whenever a connector or auth error appears,
+READ `references/connection.md` in this skill directory — it is the single source
+of truth for the never-inline rule, connector discovery, and the per-client
+reconnect steps. Local-files privacy mode (after Tool Guidance) is the exception.
 
 ## Core Workflow
 
@@ -372,69 +363,19 @@ directory before authoring a plan.
 When the user critiques a plan's look or structure, fix the renderer or this
 skill — never hand-edit one stored plan. Turn feedback into better guidance.
 
-## Local-Files Privacy Mode
-
-Use local-files privacy mode when the user explicitly asks for no DB writes,
-no hosted Plan database writes, no Plan MCP publish, fully local files, offline/private
-planning, repo-owned/source-controlled planning artifacts, or when
-`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
-policy says a plan must stay under their own brand, domain, source control, or
-infrastructure. In this mode the plan data must never be sent to the Plan MCP
-server or Plan app action surface. Schema-only block catalog lookup is allowed
-because it sends no plan content: use the MCP `get-plan-blocks` tool if it is
-already available, or run
-`npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
-file before authoring MDX.
-
-The local-files contract is:
-
-- Read source context from local files and shell commands only.
-- Fetch/read the block catalog before writing structured MDX. The
-  `plan blocks` command calls the public no-auth `get-plan-blocks` route and
-  writes only registry metadata to disk; use `--format schema` if exact nested
-  fields are needed. If network access is unavailable, use the bundled
-  references and rely on `plan local check` / `plan local serve` to catch
-  invalid tags. For `checklist` and `question-form`, copy the catalog examples
-  verbatim: checklist items need `id` and `label`; question-form questions need
-  `id`, `title`, and `mode`; and each option needs `id` and `label`. `plan local
-  check` validates these required fields against the renderer schema.
-- Write the plan as a local MDX folder: use `plans/<slug>/` when the user
-  wants the artifact checked into the repo, or use a repo-ignored/temporary
-  folder such as `.agent-native/plans/<slug>/` or `/tmp/agent-native-plans/<slug>/`
-  when it should not be checked in. The folder contains `plan.mdx`, optional
-  `canvas.mdx`, optional `prototype.mdx`, and optional `.plan-state.json`. Use
-  that exact chosen folder as `<plan-dir>` in every local CLI command below.
-- Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before
-  serving, then run
-  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind plan --open`.
-  Report the returned local bridge URL from stdout or `<plan-dir>/.plan-url`.
-  Treat `.plan-url` as a local token file and do not commit it. The URL opens
-  the hosted Plan UI but reads from the localhost bridge on this machine, so it
-  is not shareable across machines. On macOS, `--open` prefers Chromium browsers;
-  if Safari opens, switch to Chrome/Chromium because Safari can block the hosted
-  HTTPS page from fetching the HTTP localhost bridge. If the Plan app itself is
-  running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route
-  is also valid.
-- For headless verification, run
-  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind plan`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
-  the `bridgeUrl` from the verify/serve JSON to read the concrete validation
-  error.
-- 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 except the
-  schema-only block catalog lookup above.
-- Treat feedback as file or chat feedback: update the MDX files directly, rerun
-  the local bridge command, and summarize the new local bridge URL. 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.
+## Local-Files Privacy Mode — read `references/local-files.md`
+
+When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
+publish, fully local/offline/private planning, repo-owned source-controlled
+artifacts, or `AGENT_NATIVE_PLANS_MODE=local-files` — do not call any hosted Plan
+tool except the schema-only `get-plan-blocks` catalog lookup. Author a local MDX
+folder and
+preview it with `plan local check` / `plan local serve` / `plan local verify`.
+Before using local-files mode, READ `references/local-files.md` in this skill
+directory — it is the single source of truth for the full contract (catalog
+lookup, MDX folder layout, the local bridge commands, and the hosted tools you
+must not call). Carry forward only the code-research and plan-composition
+guidance from Core Workflow; everything hosted is replaced by the local bridge.
 
 ## Interpreting comment anchors
 
@@ -514,17 +455,9 @@ For fully offline, no-account use, run the Plans app locally and sync plans to
 your repo as MDX. This local mode is a separate advanced path, not the default
 hosted flow.
 
-If a Plans tool returns `needs auth`, `Unauthorized`, or `Session terminated`,
-do not keep retrying the tool. Stop and give the user the reconnect step for the
-client they are using: Codex/Codex Desktop should run
-`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
-and start a new Codex session; Claude Code should run `/mcp` and choose
-Authenticate/Reconnect for the plan connector, or run the reconnect command with
-`--client claude-code` and restart Claude. To refresh every local client config
-that already has the Plan entry, use `--client all`, then restart/reload each
-client. Reconnect re-authenticates WITHOUT reinstalling and finds the entry by
-URL regardless of connector name. Never reinstall from scratch just to fix auth.
-Continue once the connector is available.
+If a Plans tool returns `needs auth`, `Unauthorized`, or `Session terminated`, do
+not keep retrying it — stop and give the user the per-client reconnect step from
+`references/connection.md`, then continue once the connector is available.
 
 Hosted default: connect `https://plan.agent-native.com/_agent-native/mcp`. Do
 not put shared secrets in skill files.

package/corpus/templates/plan/.agents/skills/visual-plan/references/connection.md

@@ -0,0 +1,51 @@
+# Connecting & publishing — single source of truth
+
+This file is the canonical rule for the never-inline deliverable, finding the
+Plan MCP connector, and restoring it when its tools are missing. It is shared
+word for word by `/visual-plan` and `/visual-recap`. Read it when you are about
+to publish, or whenever a connector or auth error appears; do not improvise an
+inline fallback from memory.
+
+<!-- SHARED-CORE:connection START -->
+
+**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
+content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
+sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
+entire value is the hosted, interactive, annotatable Plan; an inline summary is
+the thing a Plan replaces, not a degraded version of one. The only supported
+output is to publish through the Plan MCP connector and return its absolute URL.
+Local-files privacy mode (`references/local-files.md`) is the one exception.
+
+**The connector is usually the `plan` server**, but older installed agents may
+expose the same hosted connector as `agent-native-plans` — both names are valid,
+so never report the connector as missing just because it is named
+`agent-native-plans` instead of `plan`. Some clients also lazy-load connector
+tools through a deferred tool registry instead of showing the namespace upfront.
+Before declaring the connector missing, search/load tools with the host's
+discovery surface (`tool_search` when available) for `create_visual_plan`,
+`create_visual_recap`, or `get_plan_blocks`, then use the tools it exposes.
+
+**If the tools are still missing after discovery, do NOT fall back to inline
+output.** 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 re-authenticate. Stop and give the user the exact restore
+step for their current client:
+
+- **Codex / Codex Desktop:** run
+  `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+  and start a new Codex session.
+- **Claude Code:** run `/mcp` and choose Authenticate/Reconnect, or run the same
+  reconnect command with `--client claude-code` and restart Claude.
+
+The same applies when a Plan tool returns `needs auth`, `Unauthorized`, or
+`Session terminated`: stop retrying the tool and give the reconnect step instead.
+
+Auth is stored per client config/session, so one client's reconnect does not make
+another running client load tools. `--client all` refreshes every local client
+config that already has the Plan entry, but each running client still has to
+reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
+and finds the entry by URL regardless of connector name — never reinstall from
+scratch just to fix auth. Publish once the tool is reachable. Falling back to
+inline content is a defect, not a degraded mode.
+
+<!-- SHARED-CORE:connection END -->

package/corpus/templates/plan/.agents/skills/visual-plan/references/document-quality.md

@@ -173,6 +173,10 @@ must read in dark mode without a plan-specific patch.
 
 **Before handoff, open the plan and check it.** Fix overlap, excessive
 whitespace, clipped fragments, misleading inactive controls, poor contrast, and
-unreadable diagrams before asking for approval.
+unreadable diagrams before asking for approval. Check the top canvas in the
+current Plan theme, especially dark mode: white mockup panels, low-contrast
+muted text, or invisible controls are defects. If a frame only works in one
+theme, rewrite the HTML with `--wf-*` tokens and semantic helper classes before
+surfacing the plan.
 
 <!-- SHARED-CORE:document-quality END -->

package/corpus/templates/plan/.agents/skills/visual-plan/references/local-files.md

@@ -0,0 +1,85 @@
+# Local-files privacy mode — single source of truth
+
+This file is the canonical contract for fully local, no-database planning and
+recaps. It is shared word for word by `/visual-plan` and `/visual-recap`. Read it
+in full before using local-files mode; do not call any hosted Plan tool for a
+local plan/recap except the schema-only block-catalog lookup described below.
+
+<!-- SHARED-CORE:local-files START -->
+
+**When to use it.** Use local-files privacy mode when the user explicitly asks
+for no DB writes, no hosted Plan database writes, no Plan MCP publish, fully local
+files, offline/private work, or repo-owned/source-controlled artifacts, or when
+`AGENT_NATIVE_PLANS_MODE=local-files` is set. Also use it when a user or repo
+policy says the work must stay under their own brand, domain, source control, or
+infrastructure. In this mode the plan/recap data must never be sent to the Plan
+MCP server or the Plan app action surface. This is the only exception to the
+always-publish rule in `references/connection.md`.
+
+The local-files contract:
+
+- **Read context locally.** Read source, diff, and stat context from local files
+  and shell commands only. For recaps, the
+  `npx @agent-native/core@latest recap collect-diff`, `scan`, and
+  `build-prompt --local-files` helpers are safe — they operate on local files and
+  do not write to the Plan database.
+- **Fetch the block catalog first** (it sends no plan content). Use the MCP
+  `get-plan-blocks` tool if it is already available, or run
+  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` and read that
+  file before authoring MDX; it calls the public no-auth `get-plan-blocks` route.
+  Use `--format schema` when you need exact nested fields. If network access is
+  unavailable, use the bundled `references/*.md` and rely on `plan local check` to
+  catch invalid tags. Copy the catalog examples verbatim for the fields the
+  registry table cannot encode: `checklist` items need `id` and `label`;
+  `question-form` questions need `id`, `title`, and `mode`, and each option needs
+  `id` and `label`; and `Code` / `AnnotatedCode` / `Diff` are whitespace-sensitive
+  — encode multiline code as JSON string attributes such as `code={"const x =\n  y"}`
+  (a static template literal is accepted only when it has no `${...}`
+  interpolation). `plan local check` validates these required fields against the
+  renderer schema.
+- **Write a local MDX folder.** Use `plans/<slug>/` to check the artifact into the
+  repo, or a repo-ignored/temporary folder such as `.agent-native/plans/<slug>/`
+  or `/tmp/agent-native-plans/<slug>/` when it should not be checked in. The
+  folder holds `plan.mdx`, optional `canvas.mdx`, optional `prototype.mdx`, and
+  optional `.plan-state.json`. For a recap, set `kind: "recap"` and
+  `localOnly: true` in the frontmatter/state. Use that exact folder as
+  `<plan-dir>` in every command below.
+- **Check, then serve.** Run
+  `npx @agent-native/core@latest plan local check --dir <plan-dir>` before any
+  preview, then
+  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind <plan|recap> --open`
+  (use `--kind plan` for plans, `--kind recap` for recaps). Report the local
+  bridge URL from stdout or `<plan-dir>/.plan-url`; treat `.plan-url` as a local
+  token file and do not commit it. The URL opens the hosted Plan UI but reads from
+  the localhost bridge on this machine, so it is not shareable across machines. On
+  macOS `--open` prefers Chromium browsers; if Safari opens, switch to
+  Chrome/Chromium because Safari can block the hosted HTTPS page from fetching the
+  HTTP localhost bridge. If the Plan app itself is running locally with the same
+  `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route is also valid. In a truly
+  offline environment, hand off the `<plan-dir>` path after `plan local check` and
+  note that interactive preview requires network access to the hosted Plan UI or a
+  running local Plan app.
+- **Headless verify.** Run
+  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind <plan|recap>`.
+  It starts the bridge, checks the private-network preflight and JSON payload,
+  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch the
+  `bridgeUrl` from the verify/serve JSON to read the concrete validation error.
+- **Never call hosted tools for that plan/recap.** Do not call
+  `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`,
+  `create-plan-design`, `create-visual-recap`, `create-visual-questions`,
+  `import-visual-plan-source`, `update-visual-plan`, `patch-visual-plan-source`,
+  `get-plan-feedback`, `export-visual-plan`, `set-resource-visibility`, or any
+  other hosted Plan tool — except the schema-only block-catalog lookup above.
+- **Feedback is file/chat feedback.** Update the MDX files directly, rerun
+  `plan local check`, and rerun `serve` or `verify` when that preview path is
+  available. Summarize the new local URL when one exists; otherwise summarize the
+  checked `<plan-dir>` path. Hosted comments, sharing, screenshots, history, usage
+  attachment, and publish/export receipts are unavailable until the user
+  explicitly opts into publishing.
+
+Local-files mode only prevents plan/recap content from reaching the Agent-Native
+Plan database. It does not by itself make the coding agent's language model local;
+for that stronger boundary the host agent/model must also be local or otherwise
+approved by the user.
+
+<!-- SHARED-CORE:local-files END -->

package/corpus/templates/plan/.agents/skills/visual-plan/references/wireframe.md

@@ -64,6 +64,27 @@ themes. For any inline border, background, or text color, reference a token:
 and `--wf-radius`. Never hard-code a hex color and never set `font-family` — the
 renderer owns the sketch/clean font.
 
+**Never use host/Tailwind theme classes in wireframe HTML.** Classes such as
+`bg-white`, `bg-zinc-50`, `bg-slate-950`, `text-zinc-950`,
+`text-slate-400`, `border-zinc-200`, `hover:bg-slate-800`, `shadow-xl`,
+or arbitrary color utilities like `bg-[#fff]` leak the host app's CSS into the
+mockup and can make dark-mode canvas frames unreadable. Use bare semantic
+elements, `.wf-*` helper classes, and `--wf-*` color tokens instead. Before
+publishing, scan every wireframe `class` and `style` attribute: if a class sets
+background, text, border, ring, fill, stroke, gradient, placeholder, decoration,
+or shadow color, rewrite it to renderer tokens or remove it. Layout-only classes
+are still discouraged; inline flex/grid styles are safer and easier to review.
+
+**Keep Rough.js sparse.** `.wf-card` and `.wf-box` already render with
+theme-safe filled backgrounds (`--wf-card`) and soft tokenized borders that work
+in both light and dark mode. Do not add `data-rough` to broad root wrappers,
+dialog shells, page panels, grid cells, or nested containers unless that single
+container is the visual point. The renderer sketches the outer frame and
+standard controls by default; use `data-rough` only for a deliberate one-off
+shape. If a mockup starts looking like stacked/overlapping sketch lines, remove
+rough targets from parent containers and let backgrounds plus spacing separate
+the surfaces.
+
 **Use literal CSS lengths for spacing.** The `--wf-*` tokens are for colors and
 renderer-owned visual styling, not layout spacing. Do not use guessed spacing
 tokens such as `var(--wf-space-4)`, Tailwind spacing classes, or theme spacing

package/corpus/templates/plan/.agents/skills/visual-recap/SKILL.md

@@ -19,110 +19,33 @@ 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 database writes, 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 `npx @agent-native/core@latest 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.
-- Fetch/read the block catalog before writing structured MDX. Use
-  `npx @agent-native/core@latest plan blocks --out plan-blocks.md` when the Plan
-  MCP connector is not registered; it calls the public no-auth
-  `get-plan-blocks` route and sends no recap content. If network access is
-  unavailable, use the bundled references and validate the MDX with
-  `plan local check`; do not run `plan local serve` unless the hosted Plan UI is
-  reachable or a local Plan app is already running. For `checklist` and `question-form`,
-  copy the catalog examples verbatim: checklist items need `id` and `label`;
-  question-form questions need `id`, `title`, and `mode`; and each option needs
-  `id` and `label`. `plan local check` validates these required fields against
-  the renderer schema.
-- Write the recap as a local MDX folder: use `plans/<slug>/` when the user
-  wants the artifact checked into the repo, or use a repo-ignored/temporary
-  folder such as `.agent-native/plans/<slug>/` or `/tmp/agent-native-plans/<slug>/`
-  when it should not be checked in. The folder contains `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. Use that exact chosen folder as `<plan-dir>` in every local CLI command
-  below.
-- Run `npx @agent-native/core@latest plan local check --dir <plan-dir>` before
-  any preview. When the hosted Plan UI is reachable, run
-  `npx @agent-native/core@latest plan local serve --dir <plan-dir> --kind recap --open`.
-  Report the returned local bridge URL from stdout or `<plan-dir>/.plan-url`.
-  Treat `.plan-url` as a local token file and do not commit it. The URL opens
-  the hosted Plan UI but reads from the localhost bridge on this machine, so it
-  is not shareable across machines. On macOS, `--open` prefers Chromium browsers;
-  if Safari opens, switch to Chrome/Chromium because Safari can block the hosted
-  HTTPS page from fetching the HTTP localhost bridge. If the Plan app itself is
-  running locally with the same `PLAN_LOCAL_DIR`, the `/local-plans/<slug>` route
-  is also valid. In a truly offline environment, hand off the local `<plan-dir>`
-  path after `plan local check` and note that interactive preview requires either
-  network access to the hosted Plan UI or a running local Plan app.
-- For headless verification, run
-  `npx @agent-native/core@latest plan local verify --dir <plan-dir> --kind recap`.
-  It starts the bridge, checks the private-network preflight and JSON payload,
-  prints diagnostics, and exits. If the browser hangs on "Loading plan", fetch
-  the `bridgeUrl` from the verify/serve JSON to read the concrete validation
-  error.
-- 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 except the
-  schema-only block catalog lookup above.
-- Treat review feedback as file or chat feedback: update the MDX files directly,
-  rerun `plan local check`, and rerun `serve` or `verify` only when that preview
-  path is available. Summarize the new local URL when one exists; otherwise
-  summarize the checked local folder 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
-`create-visual-recap` tool on the Plan MCP connector. The connector is usually
-exposed as the `plan` server, but older installed agents may expose the same
-hosted connector as `agent-native-plans`; both names are valid. NEVER hand the
-recap to the user as inline chat content — not Markdown prose, not an ASCII
-sketch, not a table, not a fenced "wireframe", not a "here's the recap" summary.
-A recap's 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.
-
-Some clients lazy-load connector tools through a deferred tool registry instead
-of showing the `plan` namespace upfront. Before declaring the Plan connector
-missing, search/load tools with the host's discovery surface (`tool_search` when
-available) for `create_visual_recap`, `create_visual_plan`, or
-`get_plan_blocks`, then use the Plan MCP tools it exposes.
-
-Except for the explicit local-files privacy mode above, if neither the `plan`
-nor legacy `agent-native-plans` Plan MCP tools are available after deferred tool
-discovery, do NOT improvise an inline recap as a fallback. Do not report the
-connector as disconnected just because it is named `agent-native-plans` instead
-of `plan`, or because the tools were not visible before discovery. 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 how to restore it for their current client: in
-Codex/Codex Desktop, run
-`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
-and start a new Codex session; in Claude Code, run `/mcp` and choose
-Authenticate/Reconnect, or run the reconnect command with `--client claude-code`
-and restart Claude. Auth is stored per client config/session; `--client all`
-refreshes every local client config that already has the Plan entry, but each
-running client still has to reload its MCP tools. Reconnect re-authenticates
-WITHOUT reinstalling and finds the entry by URL regardless of connector name.
-Never reinstall from scratch just to fix auth. Then publish once the tool is
-reachable. Falling back to inline content is a defect, not a degraded mode.
+## Publish As An Agent-Native Plan — Never Inline
+
+The deliverable is ALWAYS a published Agent-Native Plan, created with
+`create-visual-recap` on the Plan MCP connector — NEVER inline chat content (not
+Markdown prose, an ASCII sketch, a table, a fenced "wireframe", or a "here's the
+recap" summary). A recap's entire value is the hosted, interactive, annotatable
+plan; an inline summary is not a degraded recap, it is the thing a recap
+replaces. If the `plan` (or legacy `agent-native-plans`) tools are not visible,
+discover them through the host's `tool_search` first; if they are still missing,
+STOP and give the user the client-specific reconnect step rather than improvising
+an inline recap. Before publishing, or whenever a connector or auth error
+appears, READ `references/connection.md` in this skill directory — it is the
+single source of truth for the never-inline rule, connector discovery, and the
+per-client reconnect steps. Local-files privacy mode (below) is the one
+exception.
+
+## Local-Files Privacy Mode — read `references/local-files.md`
+
+When the user wants no hosted Plan database writes — no DB writes, no Plan MCP
+publish, fully local/offline/private recaps, or `AGENT_NATIVE_PLANS_MODE=local-files`
+— do not call any hosted Plan tool except the schema-only `get-plan-blocks`
+catalog lookup. Read the diff with the local `recap collect-diff` / `scan` /
+`build-prompt --local-files` helpers, author a local MDX folder (set
+`kind: "recap"` and `localOnly: true`), and preview it with `plan local check`,
+`plan local serve --kind recap`, and `plan local verify --kind recap`. Before
+using local-files mode, READ `references/local-files.md` in this skill directory
+— it is the single source of truth for the full contract.
 
 ## When To Use
 
@@ -510,6 +433,11 @@ A few recap-specific authoring rules the registry table cannot encode:
   explicitly closed around children (`<RichText ...>...</RichText>`). Never
   leave a bare opening tag like `<RichText ...>` in a paragraph; MDX treats it
   as unclosed JSX and import fails before the recap can render.
+- Code-bearing blocks (`Code`, `AnnotatedCode`, and `Diff`) are
+  whitespace-sensitive. Prefer the exact MDX form from the `get-plan-blocks`
+  examples / source exporter, where multiline code is encoded as JSON string
+  attributes such as `code={"const x =\n  y"}`. Static template literals are
+  accepted only when they are static strings with no `${...}` interpolation.
 - `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

package/corpus/templates/plan/.agents/skills/visual-recap/references/connection.md

@@ -0,0 +1,51 @@
+# Connecting & publishing — single source of truth
+
+This file is the canonical rule for the never-inline deliverable, finding the
+Plan MCP connector, and restoring it when its tools are missing. It is shared
+word for word by `/visual-plan` and `/visual-recap`. Read it when you are about
+to publish, or whenever a connector or auth error appears; do not improvise an
+inline fallback from memory.
+
+<!-- SHARED-CORE:connection START -->
+
+**The deliverable is ALWAYS a published Agent-Native Plan, never inline chat
+content.** Do not hand the plan or recap to the user as Markdown prose, an ASCII
+sketch, a table, a fenced "wireframe", or a "here's the summary" paragraph. The
+entire value is the hosted, interactive, annotatable Plan; an inline summary is
+the thing a Plan replaces, not a degraded version of one. The only supported
+output is to publish through the Plan MCP connector and return its absolute URL.
+Local-files privacy mode (`references/local-files.md`) is the one exception.
+
+**The connector is usually the `plan` server**, but older installed agents may
+expose the same hosted connector as `agent-native-plans` — both names are valid,
+so never report the connector as missing just because it is named
+`agent-native-plans` instead of `plan`. Some clients also lazy-load connector
+tools through a deferred tool registry instead of showing the namespace upfront.
+Before declaring the connector missing, search/load tools with the host's
+discovery surface (`tool_search` when available) for `create_visual_plan`,
+`create_visual_recap`, or `get_plan_blocks`, then use the tools it exposes.
+
+**If the tools are still missing after discovery, do NOT fall back to inline
+output.** 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 re-authenticate. Stop and give the user the exact restore
+step for their current client:
+
+- **Codex / Codex Desktop:** run
+  `npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+  and start a new Codex session.
+- **Claude Code:** run `/mcp` and choose Authenticate/Reconnect, or run the same
+  reconnect command with `--client claude-code` and restart Claude.
+
+The same applies when a Plan tool returns `needs auth`, `Unauthorized`, or
+`Session terminated`: stop retrying the tool and give the reconnect step instead.
+
+Auth is stored per client config/session, so one client's reconnect does not make
+another running client load tools. `--client all` refreshes every local client
+config that already has the Plan entry, but each running client still has to
+reload its MCP tools afterward. Reconnect re-authenticates WITHOUT reinstalling
+and finds the entry by URL regardless of connector name — never reinstall from
+scratch just to fix auth. Publish once the tool is reachable. Falling back to
+inline content is a defect, not a degraded mode.
+
+<!-- SHARED-CORE:connection END -->