@agent-native/core 0.97.0 → 0.98.0

package/corpus/core/src/cli/skills-content/document-quality.ts

@@ -0,0 +1,196 @@
+export const DOCUMENT_QUALITY_CORE = `<!-- SHARED-CORE:document-quality START -->
+
+**The document is a serious technical plan, not marketing.** Write it the way a
+strong Claude or Codex implementation plan reads: outcome-first, prose-first,
+self-contained, and specific. State the objective and what "done" means, the
+scope and non-goals, the proposed approach with the key decisions and their
+rationale, ordered steps that name real files, symbols, actions, and data
+shapes, the risks, and a closing verification step (tests, build, or a checkable
+behavior). Replace vague prose with specifics; never ship a step like "make it
+work." No hero art, gradients, logos, nav bars, slogans, value props, giant
+landing-page headings, or marketing cards unless the user explicitly asks.
+
+**Every published plan must stand alone.** Even when the agent is revising an
+existing plan, the output is a plan to do the work, not a changelog of the
+conversation. Do not write phrases like "preserve the previous plan", "do not
+drop the old idea", "as discussed above", "this revision", "unlike the prior
+version", or "correction from the earlier plan". Fold the right decisions into
+the plan as normal objective, architecture, scope, and roadmap prose. A reviewer
+who opens the plan from a link with no chat history should understand it. Avoid
+negative framing that only makes sense against absent context ("not the old
+mode", "not just X") unless the contrast is defined in the plan and genuinely
+helps; state the positive model directly.
+
+**Make abstract plans instantly legible.** If the idea is broad, strategic, or
+intended for a third-party reviewer, put one concrete product snapshot near the
+top before dense architecture, mode tables, manifests, or roadmaps. For
+UI-capable concepts, that snapshot is usually a top-canvas app state plus a
+short paragraph that says what the user sees and what changes under the hood.
+Then put mechanics, data flow, sync boundaries, and implementation detail in
+separate diagrams or document sections.
+
+**Preserve the user's level of abstraction.** A motivating use case is not
+automatically the architecture. When the prompt describes a broader framework,
+product mode, or reusable primitive, separate the reusable core from specific
+apps, providers, customers, scripts, or launch examples. Use the concrete
+example to make the plan understandable, then make clear which parts are core,
+which are app-specific adapters, and which are future examples.
+
+**When top visuals exist, they and the document never duplicate each other.**
+For UI work, the UI story lives in the top visual surface: canvas artboards for
+static inspection, plus prototype tabs when the flow should be functional. The
+document carries the technical depth the visuals cannot show — concrete
+file/symbol maps, API and data contracts, code snippets, migration or
+implementation phases, risks, and validation. For architecture/code reviews,
+invert that: the document is the visual surface, and each recommendation
+carries its own nearby inline \`diagram\` / \`data-model\` block plus file
+evidence (the \`diagram\` bullet below owns how to author those diagrams).
+Repeat a wireframe in the document only for a genuinely new detail view or
+comparison. Skip the visual surface entirely for non-visual work and write a
+clean rich document. For a simple binary UI visual choice, show the two
+directions in the canvas only; do not repeat the same options as body
+wireframes or prose. Put the actual choice in the bottom "Open Questions" form.
+
+**Use the right block, and make it carry substance.** For the authoritative,
+machine-checked list of block types and their data schemas, call \`get-plan-blocks\`
+— it returns the live registry vocabulary (type, MDX tag, placement, key fields)
+so you never emit a block the editor cannot render or round-trip:
+
+- \`rich-text\` for plan prose with real bold/italic/code/links and nested lists.
+- \`annotated-code\` for the file map: when a load-bearing file is worth
+  highlighting, prefer the annotated walkthrough over a bare \`code\` block — carry
+  the real, syntax-highlighted code AND anchor short margin notes to the lines
+  that actually change (the new action, the changed schema, the wiring point), so
+  the reader sees what matters and why instead of code for code's sake. Each
+  annotation is \`{ lines: "12" | "12-18"; label?; note }\`; keep a few high-signal
+  notes per file, not one per line. Highlight only the files worth reading; never
+  an exhaustive list of every touched file, and never a prose-only description of
+  a file. Drop to a plain \`code\` block only for a throwaway snippet with nothing
+  to call out. When more than one file matters, group the blocks in a vertical
+  \`tabs\` block (the standard tab primitive) rather than a bespoke container. If
+  the exact code is unknown, show the smallest plausible planned shape or a
+  commented stub naming what to fill in. (\`code-tabs\` and \`implementation-map\`
+  are legacy: their renderers stay for old plans, but do not author new ones.)
+- For a decision: if the reviewer must still pick between a genuinely-open
+  either/or, put it in the bottom Open Questions \`question-form\` as a \`single\`
+  question — one option per real alternative, each with a short detail and
+  \`recommended: true\` on the one you would choose; do not also restate the same
+  choice elsewhere. If you have already committed to an approach, state it as
+  settled prose or a \`callout\` with \`tone="decision"\`, optionally with a
+  \`columns\` block for a side-by-side comparison of the options you weighed — not
+  as a confusing mid-document form for a question you have already answered.
+- \`columns\` for side-by-side before/after or current/target comparisons where
+  each side needs real nested blocks; label the columns clearly and avoid
+  stacking comparison blocks vertically when parallel reading is the point.
+- \`diagram\` for two-dimensional architecture, dependency, data-flow, or state
+  relationships, only when it clarifies something real. Prefer standard
+  two-dimensional layouts — paired before/after panels, layered diagrams,
+  swimlanes, dependency maps, matrices, or grouped regions; do not default to
+  left-to-right chains, and use a line only when the relationship is truly a
+  sequence. Do not use a body \`diagram\` as the primary artifact for a requested
+  product canvas, light storyboard, UI flow, screen flow, or wireframe; those
+  belong in the top canvas as artboards with \`Screen\` wireframes first. Use
+  diagrams below that canvas only for architecture, data flow, or implementation
+  mechanics. For architecture/code
+  diagrams, prefer \`data.html\` / \`data.css\` with semantic HTML and inline SVG so
+  the diagram can use panels, layers, matrices, arrows, annotations, and
+  responsive layout directly. Author diagram HTML with renderer-owned primitives
+  like \`.diagram-panel\`, \`.diagram-card\`, \`.diagram-node\`, \`.diagram-box\`,
+  \`.diagram-pill\`, \`.diagram-muted\`, and \`[data-rough]\`; they map to the plan's
+  Tailwind theme variables through \`--wf-ink\`, \`--wf-muted\`, \`--wf-line\`,
+  \`--wf-paper\`, \`--wf-card\`, \`--wf-accent\`, \`--wf-accent-soft\`, \`--wf-warn\`, and
+  \`--wf-ok\`, and switch to Excalifont plus rough.js outlines in sketchy mode. Do not
+  set \`font-family\` and do not hard-code hex, rgb, or hsl colors in diagram HTML
+  or CSS. Choose the outer \`frame\` intentionally: use \`show\` when the diagram
+  stands alone in a recap, comparison, or prose section; use \`hide\` when the
+  diagram sits inside docs chrome, columns, tabs, cards, a canvas surface, or
+  already has visible \`.diagram-panel\` / \`.diagram-box\` structure. Leave room
+  for the sketch font: keep labels short, give nodes generous width, and place
+  boundary/annotation labels in unused space instead of over nodes; labels must
+  not overlap nodes, connectors, or each other. For small text/SVG changes to an
+  existing HTML diagram, use \`patch-diagram-html\` with a unique
+  \`find\`/\`replace\` snippet instead of resending the whole \`data.html\` string.
+  Use legacy \`nodes\` / \`edges\` only for small previews or truly
+  sequential flows. In architecture/code plans, prefer a repeated section rhythm:
+  recommendation title, confidence and category badges, code-path evidence, a
+  local before/after or current/target spatial diagram, then concise
+  Problem/Solution/Why text.
+- \`tabs\` for multiple states, directions, or comparisons. A tab that reveals
+  only prose usually means the plan is under-specified — include a relevant
+  visual unless the tab is intentionally document-only.
+- \`table\`, \`checklist\`, \`callout\` for scannable structure.
+
+**Open questions live at the bottom as a form when answers would change the
+plan.** Surface answerable unresolved decisions in a final \`question-form\`
+block titled "Open Questions" so the renderer presents it as a distinct section.
+That bottom form is the ONLY place that enumerates the open questions: never add
+a second "Open Questions" heading, list, or recap of the same questions earlier
+in the document. A one-line pointer in the overview prose ("a few decisions are
+still open — see Open Questions below") is fine, but do not reproduce the
+question list or a parallel questions/decisions section above it.
+Use \`single\` or \`multi\` for clear choices, \`freeform\` for constraints,
+\`recommended: true\` for the default you would pick, and option \`wireframe\` /
+\`diagram\` previews only when the options are not already visible in the top
+canvas. \`single\` and \`multi\` questions always render a write-in field so a
+reviewer can answer with a custom option — never add an explicit "Other" option
+yourself; set \`allowOther: false\` only when a free-text answer makes no sense.
+Keep non-answerable assumptions or risks as concise \`callout\` blocks in
+the relevant section. Never bury a questions/decisions wall inside the plan
+narrative, and never ask the same question twice.
+
+For complex plans, do not end without an open-question audit. If architecture,
+scope, UX, data shape, rollout, provider mapping, or ownership still depends on
+a choice, either commit to a recommendation with rationale or add it to the
+bottom form with a recommended default. A complex plan with no open questions is
+fine only when every meaningful decision has been explicitly made.
+
+**Verification must exercise the real workflow.** The final verification section
+should go beyond typecheck/unit tests when the plan changes UI, local files,
+sync, providers, browser behavior, or multi-app flows. Include at least one
+end-to-end smoke that matches the user journey, such as a fresh repo/folder,
+real manifest or data fixture, browser interaction, save/sync action, and an
+on-disk or database assertion. Name the command or manual browser path when it
+is known.
+
+**\`custom-html\` is a bounded escape hatch only** — a single complete fragment
+inside a block, never \`html\`/\`head\`/\`body\`/\`script\` tags, never a generic
+placeholder, density demo, or proof that custom HTML works. Prefer the native
+blocks for normal plans. For architecture/code reviews, use \`diagram\`
+\`data.html\` / \`data.css\` for rich local HTML/SVG diagrams instead of
+\`custom-html\`. For UI/product work, \`custom-html\` is never the primary home for a
+requested mockup, UI state, or visual comparison. If UI fidelity requires
+HTML/CSS, image capture, or real React/CSS, the product fix is canvas support
+for that artifact type, not moving the mockup into the document.
+When \`custom-html\` is genuinely needed, author it against the sandbox-provided
+theme tokens (\`--wf-paper\`, \`--wf-card\`, \`--wf-ink\`, \`--wf-muted\`,
+\`--wf-line\`, \`--wf-radius\`, and the matching \`--plan-*\` aliases). Do not hardcode
+hex/rgb/hsl light palettes such as white cards with dark ink; the same fragment
+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. 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 -->`;
+
+export const DOCUMENT_QUALITY_REFERENCE_MD = `# Plan document quality — single source of truth
+
+This file is the canonical quality bar for the plan document below the canvas:
+how it reads, which blocks to use, how open questions are surfaced, and the
+pre-handoff check. Read it in full before authoring the plan document; it is the
+quality bar. Do not write the document from memory or paraphrase these rules per
+mode.
+
+${DOCUMENT_QUALITY_CORE}
+`;
+
+export const DOCUMENT_QUALITY_REFERENCE_POINTER = `The document is a serious technical plan, not marketing: outcome-first,
+prose-first, self-contained, built from the right native blocks, with open
+questions in a single bottom \`question-form\` and a pre-handoff visual check.
+Before authoring the plan document, READ \`references/document-quality.md\` in this
+skill directory — it is the single source of truth for the document quality bar.
+Do not write the document from memory.`;

package/corpus/core/src/cli/skills-content/exemplar.ts

@@ -0,0 +1,69 @@
+export const EXEMPLAR_CORE = `<!-- SHARED-CORE:exemplar START -->
+
+**GOOD.** A UI-first plan for a todo app: a canvas with a \`desktop\` artboard whose
+\`data.html\` is a real flex layout — a sidebar of links (\`Inbox 12\`, \`Today 4\`,
+\`Done\`), a main column with an \`<h1>Today</h1>\`, accent \`.wf-pill\`s for the
+filters, a muted section label \`OVERDUE\`, and \`.wf-card\` task rows carrying real
+titles, due dates, and a primary \`button.primary\` — styled only through bare
+elements, helper classes, and \`--wf-*\` tokens, so the renderer applies the
+correct desktop footprint, theme, and one subtle whole-frame wobble. Plain-text
+designer notes sit spaced off the frame, pointing only at the controls that need
+explanation. Below it, a Claude/Codex-grade document: objective and
+done-criteria, a few \`code\` blocks (grouped in a vertical \`tabs\` block when
+more than one) showing the real shape of the load-bearing files, a \`callout\`
+with \`tone="decision"\` stating the chosen approach with a \`columns\` block
+weighing the two real options behind it,
+and a validation step — none of it repeating the canvas. If the task also
+changes a multi-step completion flow, the same top area includes a Prototype tab
+whose screens use the same labels and states as the canvas artboards, with
+\`data-goto\` controls for the sequence. This is the bar.
+
+**GOOD.** A broad product-architecture plan opens with a plain recommendation
+and one concrete app state before the abstraction. The first canvas artboard is
+pure product UI that matches the current app shell; nearby notes explain the
+user-visible delta. A separate diagram below shows the mechanics, such as file
+or data flow. The document then separates the reusable core from app/provider
+adapters and examples, covers contracts, folder or schema shape, sync
+boundaries, roadmap, non-goals, a bottom Open Questions form for unresolved
+decisions, and a verification section with at least one realistic end-to-end
+smoke. A reviewer who was not in the chat gets the idea from the top snapshot
+before reading the technical plan.
+
+**GOOD.** A \`/visual-plan\` for a backend architecture review: no top canvas.
+The document opens with context and a legend, then repeats recommendation cards:
+title, confidence/category badges, a monospace grid of real file paths, one
+inline two-dimensional before/after or layered architecture diagram, and terse
+Problem/Solution/Why bullets using the codebase's vocabulary. The diagram uses
+space to show boundaries, layers, and ownership; it is not a default
+left-to-right chain. The plan ends with a top recommendation and a bottom
+question-form only if the next architecture direction is genuinely open. This is
+better than a top canvas because each diagram is local to the claim it supports.
+
+**BAD.** A \`data.html\` with hard-coded hex colors, a \`font-family\`, or fixed
+pixel width/height; gray placeholder bars "insinuating" text on a non-skeleton
+frame; a forced desktop + mobile pair for a popover; floating bordered
+annotation cards hugging the frames; a fresh hand-authored kit-tree \`screen\`
+instead of \`html\`; a multi-step UI flow with only static frames and no prototype
+tab; a mockup escaped into a document \`custom-html\` block; and a marketing-style
+document with a hero heading and value props that just restates what the canvas
+already shows. Also bad: an architecture-only plan forced into a top canvas of
+labeled boxes with overlapping text, where the actual code evidence and
+recommendations live elsewhere; a product wireframe that mixes a real screen
+with repo names, file-contract arrows, architecture explanations, or a made-up
+permanent inspector; and a plan that describes itself as a revision of a prior
+conversation instead of a standalone proposal. Never produce this.
+
+<!-- SHARED-CORE:exemplar END -->`;
+
+export const EXEMPLAR_REFERENCE_MD = `# Good vs. bad exemplar — single source of truth
+
+This file is the canonical worked example of a great plan (and the anti-patterns
+to avoid). Read it alongside the document-quality and canvas references before
+authoring a plan; it is the bar these plans must clear.
+
+${EXEMPLAR_CORE}
+`;
+
+export const EXEMPLAR_REFERENCE_POINTER = `For a worked example of the bar — a great UI-first plan and \`/visual-plan\`, plus
+the anti-patterns to avoid — READ \`references/exemplar.md\` in this skill
+directory before authoring a plan.`;

package/corpus/core/src/cli/skills-content/help.ts

@@ -0,0 +1,77 @@
+export const HELP = `npx @agent-native/core@latest skills
+
+Usage:
+  npx @agent-native/core@latest skills list
+  npx @agent-native/core@latest skills status [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
+  npx @agent-native/core@latest skills update [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray [--client codex|claude-code|cowork|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
+
+Examples:
+  npx @agent-native/core@latest skills add assets
+  npx @agent-native/core@latest skills add content --mode local-files
+  npx @agent-native/core@latest skills add design-exploration
+  npx @agent-native/core@latest skills add visual-edit
+  npx @agent-native/core@latest skills add visual-plan
+  npx @agent-native/core@latest skills add visual-recap
+  npx @agent-native/core@latest skills add visualize-repo
+  npx @agent-native/core@latest skills add visual-recap --with-github-action
+  npx @agent-native/core@latest skills add visual-plan --mode local-files
+  npx @agent-native/core@latest skills add visual-plan --mode self-hosted --mcp-url https://my-plan-app.example.com
+  npx @agent-native/core@latest skills status visual-plan
+  npx @agent-native/core@latest skills update visual-plan
+  npx @agent-native/core@latest skills update scaffold --project
+  npx @agent-native/core@latest skills add visual-plan --no-connect
+  npx @agent-native/core@latest skills add context-xray --client all
+  npx @agent-native/core@latest skills add assets --client claude-code
+  npx @agent-native/core@latest skills add assets --mcp-url https://my-app.ngrok-free.dev
+  npx @agent-native/core@latest skills add ./dist/assets-skill --client codex
+  npx @agent-native/core@latest skills add BuilderIO/skills --client codex --scope project
+  npx @agent-native/core@latest skills add BuilderIO/skills --with-github-action
+
+The add command installs the SKILL.md instructions, registers the app-backed
+MCP connector, and then authenticates it in one step so you do not hit an OAuth
+wall on the first tool call. Hosted installs can configure Claude Code, Codex,
+Claude Cowork, Cursor, OpenCode, and GitHub Copilot / VS Code; local-files
+instruction installs target the shared .agents skill path used by Codex, Pi,
+Cursor, OpenCode, Copilot, and similar agents, plus Claude Code's native skill
+path when selected. Pass --client to narrow it. Authentication reuses
+"npx @agent-native/core@latest connect": OAuth-capable clients (Claude Code,
+Cursor, OpenCode, GitHub Copilot / VS Code) get URL-only entries and authenticate
+inside that host, while Codex / Cowork run the browser device-code flow. In a
+non-interactive shell or CI the auth step is skipped and the exact
+"npx @agent-native/core@latest connect <url> --client all" command is printed instead.
+
+Running "npx @agent-native/skills@latest add ..." uses this same shared install
+flow with the broader BuilderIO skills catalog enabled. Pass --no-connect to
+register MCP where possible without authenticating (leave auth to the host or run
+"npx @agent-native/core@latest connect" later). Pass --mcp-url to register that connector against
+a custom origin (an ngrok tunnel, a local dev server, or a self-hosted
+deployment) instead of the built-in hosted default — a bare origin gets the
+standard /_agent-native/mcp path appended. Use app-skill pack for marketplace
+bundles and custom adapter output.
+
+When installing visual-plan, visual-recap, or visualize-repo interactively, the
+CLI asks where Plans artifacts should live: hosted Plans for shareable
+links/comments, local files for "No sharing, all local.", or a
+self-hosted/custom Plan app URL.
+Pass --mode to choose directly. Local-files mode skips MCP registration and
+auth and installs instructions that default to a no-auth block catalog fetch,
+MDX folders, and the localhost bridge viewer.
+
+When installing content with --mode local-files, the CLI installs Content
+instructions and writes or updates agent-native.json with repo-backed Markdown /
+MDX roots for docs, blog, content, and resources. Use a local Content app, Agent
+Native Desktop, or another trusted local bridge for Content actions to read and
+write those files.
+
+When installing visual-recap interactively, the CLI offers to add the optional PR
+Visual Recap GitHub Action. Pass --with-github-action to write it directly, then
+run "npx @agent-native/core@latest recap setup" / "npx @agent-native/core@latest recap doctor" to configure and
+verify GitHub Actions. Docs: https://www.agent-native.com/docs/pr-visual-recap.
+
+The status/update commands inspect copied Agent Native skill folders and refresh
+their instruction files from the current @agent-native/core package. In generated
+apps/workspaces, "skills update scaffold --project" refreshes the framework
+skills copied into the scaffold and repairs AGENTS.md / CLAUDE.md and
+.agents/skills / .claude/skills compatibility links.`;

package/corpus/core/src/cli/skills-content/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Barrel for the large embedded-markdown string constants used by
+ * `agent-native skills` (SKILL.md bodies, shared reference docs, and the CLI
+ * help text). Split out of `skills.ts` so that file can lead with real CLI
+ * logic instead of ~3,000 lines of data. Content is purely relocated here —
+ * no bytes were changed.
+ */
+export * from "./help.js";
+export * from "./assets-skill.js";
+export * from "./content-skill.js";
+export * from "./design-exploration-skill.js";
+export * from "./design-visual-edit-skill.js";
+export * from "./plan-setup-auth.js";
+export * from "./wireframe.js";
+export * from "./canvas.js";
+export * from "./document-quality.js";
+export * from "./exemplar.js";
+export * from "./connection.js";
+export * from "./local-files.js";
+export * from "./visual-plan-skill.js";
+export * from "./visual-recap-skill.js";
+export * from "./visualize-repo-skill.js";

package/corpus/core/src/cli/skills-content/local-files.ts

@@ -0,0 +1,95 @@
+export const LOCAL_FILES_REFERENCE_MD = `# 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\` is a quick OFFLINE lint (a subset of the
+  renderer schema), so a green \`check\` does not guarantee the plan renders;
+  \`plan local verify\` is the authoritative validation against the real 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, AND
+  validates the content against the real renderer schema via the Plan app's
+  \`validate-local-plan-source\` action. A non-\`ok\` result with
+  \`validation.valid: false\` lists the renderer's exact schema-path issues (e.g.
+  \`blocks[1].data.tabs[0]...\`); fix those before handing off. If \`validation.ran\`
+  is \`false\`, the Plan app did not expose the validate endpoint (older/unreachable
+  deploy) — point \`--app-url\` at a current Plan app (e.g. a local
+  \`http://localhost:8096\`) for the authoritative check. 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/core/src/cli/skills-content/plan-setup-auth.ts

@@ -0,0 +1,80 @@
+/**
+ * Setup/auth block for the `/visual-plan` skill. Interpolated into
+ * `VISUAL_PLANS_SKILL_MD` below so the install + one-step authenticate
+ * instructions are single-sourced. The materialized SKILL.md copies under
+ * `templates/plan/.agents/skills/*`, top-level `skills/*`, and
+ * `.agents/skills/*` are guarded byte-identical by `skills.sync.spec.ts`.
+ */
+export const PLAN_SETUP_AUTH_MD = `## Setup & Authentication
+
+There are two ways into Plans.
+
+**Coding agent (CLI).** Install once with the Agent-Native CLI. The command
+installs the Plans skills, registers the hosted Plans MCP connector, and runs
+auth/setup for the selected local client(s) in the same step (a one-time browser
+sign-in at setup — this is intended), so the first tool call in that client does
+not hit an OAuth wall:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add visual-plans
+\`\`\`
+
+After that, \`/visual-plan\`, \`/visual-recap\`, and \`/visualize-repo\` are the
+installed slash commands. If you only need one command, use
+\`skills add visual-plan\`, \`skills add visual-recap\`, or
+\`skills add visualize-repo\` instead. The other planning modes
+(\`create-ui-plan\`, \`create-prototype-plan\`, \`create-plan-design\`,
+\`create-visual-questions\`) are MCP tools reachable from \`/visual-plan\`, not
+separate slash commands. Pass \`--no-connect\` to register the connector without
+authenticating, then run
+\`npx @agent-native/core@latest connect https://plan.agent-native.com --client all\`
+whenever you are ready, or choose a narrower \`--client\`. Auth and MCP tool
+loading are per client config/session.
+
+**Local-only / text installs.** If the user wants no sharing and all local files,
+install with \`--mode local-files\`:
+
+\`\`\`bash
+npx @agent-native/core@latest skills add visual-plans --mode local-files
+\`\`\`
+
+This mode does not register the Plan MCP connector. Before authoring structured
+MDX, fetch the no-auth, schema-only block catalog with
+\`npx @agent-native/core@latest plan blocks --out plan-blocks.md\`, read that file,
+write the MDX folder locally, run \`plan local check\`, then run \`plan local serve\`.
+For repo-wide visual docs, run
+\`npx @agent-native/core@latest visualize-repo --open\` to create/update
+\`agent-native.json\`, seed \`.agent-native/visual-docs/repo-overview\`, and open
+the local bridge.
+Plain text skill
+installs (Vercel Skills CLI, copied GitHub files, etc.) can follow that same
+local flow if \`@agent-native/core\` is available. Text alone cannot register
+MCP tools; hosted/shareable Plans still need the Agent-Native CLI
+install/reconnect step above.
+
+**Browser (people you share with).** Open the Plans editor and create & edit
+with no sign-up — you work as a guest. Sign in only when you want to save or
+share; signing in claims the plans you made as a guest into your account.
+
+Sharing and commenting require an account: public/shared plans are viewable by
+anyone with the link, but commenting on them needs an agent-native account.
+
+For no-account, no-DB plan storage, use local-files mode and the local bridge
+command. The optional \`plan blocks\` lookup reads only public schema metadata.
+If network access is unavailable, use the bundled references and a local Plan
+app/runtime for validation.
+
+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.
+
+Hosted default: connect \`https://plan.agent-native.com/_agent-native/mcp\`. Do
+not put shared secrets in skill files.`;