@agent-native/core 0.97.0 → 0.98.1

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.`;

package/corpus/core/src/cli/skills-content/visual-plan-skill.ts

@@ -0,0 +1,470 @@
+export const VISUAL_PLANS_SKILL_MD = `---
+name: visual-plan
+description: >-
+  Turn ordinary text plans into rich interactive visual plans with diagrams,
+  file maps, annotated code, open questions, and UI/prototype review when
+  useful.
+metadata:
+  visibility: exported
+---
+
+# Agent-Native Plans
+
+Agent-Native Plans is structured visual planning mode for coding agents. Build
+the plan you would normally write in Markdown, but as a scannable document with
+editable blocks mixed in: inline diagrams, code snippets,
+open questions, and an optional top visual review area (wireframe canvas, live
+prototype, or both in tabs). Architecture and backend plans stay document-only;
+UI and product plans start with the top canvas/prototype (the Visual Surface
+Choice section owns that rule).
+
+\`/visual-plan\` is the packaged command and main entry point. Choose the review
+mode from the task: UI-first when the work is primarily product UI and review
+should start with screens, prototype-first when review should start with a
+functional live prototype, design-first when review needs full-fidelity branded
+screens, or visual-intake when the user explicitly wants a questionnaire before
+planning. When a Codex, Claude Code, Markdown, or pasted plan already exists,
+\`/visual-plan\` uses that source plan as the starting point and builds the review
+surface from it instead of starting over.
+
+## When To Use
+
+Create or adapt a visual plan whenever the plan would be better as a reviewable
+artifact than a chat paragraph. This includes modest work such as a single UI
+surface with states, a small workflow, a before/after product change, or a
+component/API/data-shape decision that needs alignment, plus larger multi-file,
+ambiguous, long-running, risky, or UI-heavy work. Use it when architecture /
+data flow / UI direction / options / open questions would benefit from inline
+diagrams or structured blocks, when the user needs to react to a direction
+before you implement, or when an existing text plan needs a richer review
+surface.
+
+## Plan Discipline
+
+- **Gate thoughtfully.** A visual plan is a richer review surface, not only a
+  tool for giant projects. Use it when the user needs to see, compare, comment
+  on, or approve a direction before code, even for a modest UI/state/workflow
+  change. Skip it for truly trivial, unambiguous work — typos, one-line fixes, a
+  single well-specified function, anything whose diff you could describe in one
+  sentence — and just make the change. Never pad a plan with filler and never
+  ship a single-step plan.
+- **Research before you draft.** Read the real files, actions, schema, and
+  patterns first; name actual files, symbols, and data shapes instead of
+  inventing them. Check existing \`actions/\` before proposing endpoints and prefer
+  named client helpers over raw fetch. Delegate wide exploration to a sub-agent.
+  Lead with reuse: for each step, name what it reuses — existing actions, schema,
+  components, helpers — before what it adds, so the plan explains the genuinely new
+  delta instead of redescribing what already exists.
+- **Decide the hard-to-reverse bets first.** For non-trivial backend, data, or API
+  work, sketch where the feature is headed, then call out the decisions that are
+  expensive to undo once data or callers depend on them — wire format, public ids,
+  data-model shape, auth and ownership boundaries — and get those right in the plan
+  even if most of the feature ships later. Then scope to the smallest first cut that
+  proves the approach without foreclosing it, stating both what is in and what is
+  explicitly deferred.
+- **Keep examples at the right altitude.** When the user's idea is a broad
+  framework, product, or operating-model change, do not collapse it into the
+  first concrete example, provider, or sync path they mention. Separate the core
+  abstraction from motivating examples and app/provider adapters. Use examples
+  to make the plan legible, but label them as examples unless they are the whole
+  requested scope.
+- **Publish standalone plans.** If the user pasted, referenced, or already has a
+  Codex / Claude Code / Markdown plan, treat it as source material, but rewrite
+  the published plan as a clean standalone proposal. Preserve the source plan's
+  useful intent and codebase facts, label inferred visuals as inferred, and avoid
+  revision language such as "preserve the prior plan", "do not drop the old
+  idea", "unlike the previous version", or "this revision changes...". A reader
+  who never saw the chat or earlier drafts should understand the plan.
+- **Make the first read concrete.** If the plan is meant to be shared with
+  someone outside the chat, or if the concept is abstract, lead near the top with
+  one concrete product example before mode tables, architecture, or roadmaps. For
+  UI-capable concepts, that usually means a top-canvas app state that shows the
+  real user workflow in product terms. Do not rely on phrases that only make
+  sense in conversation, and do not frame the plan as "not the old idea"; state
+  the positive model directly.
+- **Planning is read-only.** Make no source edits while building or reviewing the
+  plan. Start editing only after the user approves the direction.
+- **Clarify vs. assume.** Do not ask how to build it — explore and present the
+  approach and options in the plan. Ask a clarifying question only when an
+  ambiguity would change the design and you cannot resolve it from the code; use
+  the host agent's normal ask-user-question flow and batch 2-4 high-leverage
+  questions before finalizing. Do not call \`create-visual-questions\` for
+  ordinary clarification or preflight; reserve it for the visual-intake mode when
+  the user explicitly asks for a visual intake questionnaire. Otherwise state the
+  assumption explicitly and proceed, and keep anything unresolved in the plan's
+  single bottom \`question-form\` Open Questions block. For complex plans, do a
+  final open-question pass before handoff: if a decision would affect
+  architecture, scope, UX, data shape, or rollout, either decide it in the plan
+  with rationale or put it in that bottom form with a recommended default.
+- **The plan is the approval gate.** After surfacing it, ask the user to review
+  and approve before you write code, and name which files/areas the work touches.
+  Presenting the plan and requesting sign-off is the approval step — do not ask a
+  separate "does this look good?" question.
+- **The document is the source of truth, not the chat.** When scope shifts,
+  update the plan with \`update-visual-plan\` rather than only changing course in
+  chat, and make the updated document stand alone. Do not describe the update as
+  a correction to an earlier draft inside the plan itself. Re-read the approved
+  plan before major steps.
+
+## Create A Structured Agent-Native Plan — Never Inline
+
+The deliverable is ALWAYS a structured Agent-Native Plan, not a chat-only plan.
+The hosted Plan MCP connector (\`plan\` server, or legacy \`agent-native-plans\`) is
+the default collaboration and commenting surface; it is not a reason to reject
+the planning pattern as an external dependency or rented layer. Plans are
+portable source artifacts (\`plan.mdx\`, optional \`canvas.mdx\` /
+\`prototype.mdx\`, JSON, and HTML export), and ownership-sensitive workflows can
+use local-files mode or a self-hosted/custom Plan app URL without abandoning the
+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 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
+
+This section describes the default hosted Plan MCP workflow. If
+\`AGENT_NATIVE_PLANS_MODE=local-files\` is set, or the user asks for fully local
+files/no hosted Plan writes, use **Local-Files Privacy Mode** instead; carry
+forward only the code-research and plan-composition guidance here.
+
+1. Follow the host agent's normal planning flow: inspect the codebase, delegate
+   wide exploration when useful, gather the info needed, and ask native
+   clarifying questions as needed before generating the plan. If a source plan
+   already exists, gather its exact text from the user's paste, a referenced
+   file, or recent visible agent context; do not invent source text.
+2. Call \`get-plan-blocks\` for the authoritative block catalog — do not author
+   from memorized tags. Then call the mode-matched create tool:
+   \`create-visual-plan\` for document-first plans (architecture, backend, data,
+   refactor, API), \`create-ui-plan\` for UI-first plans, \`create-prototype-plan\`
+   for prototype-first plans, \`create-plan-design\` for design-first plans,
+   \`create-visual-questions\` only when the user explicitly asks for a visual
+   intake questionnaire. When a source plan already exists,
+   pass it as \`planText\` and preserve the original plan's useful intent while
+   producing a standalone plan document, not a revision memo.
+3. For UI/product plans, compose the top canvas first with the primary
+   wireframes and annotated states, then write the document with native blocks
+   (see \`references/canvas.md\` and \`references/document-quality.md\`). For
+   broad product architecture plans with a user-facing implication, add a
+   concrete "what this looks like in the app" visual before the abstract
+   architecture or mode tables. Keep the document close to the standalone
+   Markdown plan the agent would normally output. If an existing plan was
+   provided, carry forward the right facts and decisions without referring to
+   the previous draft or explaining how this version differs. For non-visual
+   plans, skip the top visual surface (Visual Surface Choice below owns the rule)
+   and put \`diagram\`, \`data-model\`,
+   \`api-endpoint\`, \`diff\`, \`file-tree\`, \`code\`, and \`annotated-code\` blocks
+   directly next to the relevant prose.
+   Wide document layout is renderer-owned and intentionally allowlisted: only
+   literal code-review surfaces (\`diff\`, \`annotated-code\`) and \`tabs\` blocks
+   with vertical orientation or diff-like children break out wider than prose.
+   Keep \`api-endpoint\`, \`openapi-spec\`, \`data-model\`, \`json-explorer\`,
+   \`wireframe\`, question, and \`custom-html\` blocks in normal document flow unless
+   their own renderer says otherwise.
+4. Surface the returned Plans link or inline MCP App and ask the user to review.
+   Always include the actual URL in chat so the next step is a click in CLI or
+   other text-only hosts. When the host exposes an embedded browser/preview panel
+   and a tool can open arbitrary URLs there, open the returned plan URL
+   automatically for convenient review — a convenience and smoke test, never the
+   only handoff or the access
+   model. Plans should load out of the box for the local agent and local browser
+   session; if a signed-in embedded browser cannot read a local plan that an
+   anonymous/tool check can read, fix the app/action ownership or access path
+   rather than patching one plan by hand. For high-stakes plans (architecture,
+   backend, data, multi-file, or risky), also kick off the self-review pass in
+   **Self-Review Before Handoff** while the user reads, instead of blocking the
+   handoff on it.
+5. For hosted plans, call \`get-plan-feedback\` before editing, after review,
+   after any long pause,
+   and before the final response. Treat \`anchorDetails\`, resolver intent, recent
+   review events, and any focused screenshots from browser handoff as the source
+   of truth for exactly what changed and exactly what each comment points at.
+6. For hosted plans, apply changes with \`update-visual-plan\`, preferring
+   targeted \`contentPatches\`.
+   Treat the top-level \`content\` payload as a full replacement, not a merge; do
+   not send a partial \`content\` object to add a canvas or one block. If a full
+   replacement is unavoidable, first read the complete plan source/content, carry
+   forward every existing block and visual surface, and verify the source/export
+   afterward so the document body was not truncated. When the user wants
+   source-control friendly edits, use \`patch-visual-plan-source\` against the MDX
+   files instead of regenerating the plan.
+7. For hosted plans, export with \`export-visual-plan\` only when the user wants a
+   shareable receipt or repo-check-in artifacts.
+
+## Self-Review Before Handoff
+
+For high-stakes plans — architecture, backend, data-model, migration, multi-file,
+or otherwise risky work — run one adversarial self-review pass before treating the
+plan as final. Skip it for small, UI-only, or single-decision plans where the cost
+outweighs the value. Keep the pass cheap and non-blocking:
+
+- **Surface the plan first, review concurrently.** Post the link and let the user
+  start reading, then run the review in parallel — never make the user wait on it.
+- **Review the written plan; do not re-research.** Critique the plan text and its
+  own blocks. The grounding was already done while drafting, so the review checks
+  the output instead of re-exploring the repo.
+- **Spawn one skeptical reviewer** whose only job is to find what is weak, missing,
+  or wrong — not to praise. Point it at: hard-to-reverse decisions made implicitly
+  or not at all (wire format, public ids, data-model shape, auth, ownership); steps
+  not anchored in real files or symbols; a menu of options where the plan should
+  commit to one; obvious missing decisions ("what happens when X?", "why not Y?");
+  and padding or single-step filler.
+- **Fix vs. ask.** Apply clear-cut fixes yourself with \`update-visual-plan\`
+  \`contentPatches\` — vague non-goals, unanchored claims, an obvious missing
+  decision. Route genuine judgment calls back to the user instead: add them to the
+  bottom \`question-form\` Open Questions block or batch them into the normal
+  ask-user-question flow. Do not silently decide them.
+- **Do not surprise the user mid-read.** On a large plan, apply the patches before
+  the editor loads; otherwise note briefly that a self-review is running so the
+  plan changing under them is expected. When you next respond, summarize what the
+  review changed and what it surfaced for the user to decide.
+
+## Visual Surface Choice
+
+Choose the surface before creating the plan or after reading the source plan. Do
+not add visual chrome by default:
+
+For UI/product plans, the top canvas is usually the primary review surface. Put
+the first meaningful wireframes there, not buried as document-body blocks. Use
+multiple canvas artboards when states matter, such as the default view, an
+overflow menu or popover, a side panel, loading, or error. Put short annotations
+beside frames with \`targetId\` plus \`placement\`; keep implementation details,
+tradeoffs, file maps, data contracts, risks, and verification in the document
+body below the canvas.
+
+When the user asks for a flow, storyboard, journey, wireframe, canvas, or "what
+this looks like", treat that as a canvas-first request. Make one artboard per
+user-visible state, connect only adjacent transitions, and use short canvas
+annotations for the product notes. Do not substitute a document-body \`diagram\`
+block for the requested storyboard just because HTML diagrams are faster to
+write; diagrams belong below the canvas for backend mechanics, architecture, or
+data-flow explanation.
+
+Keep product wireframes and explanatory/meta diagrams separate. Start with pure
+screens that look like the app state under discussion, without callout prose or
+architecture notes embedded inside the UI. Put arrows, labels, contracts, data
+flow, and mode explanations in separate annotations, separate canvas diagrams,
+or the document body.
+
+When the plan touches an existing app, inspect the current shell/components
+before drawing. The first artboard should look like the real app at the same
+density: existing sidebars, toolbar placement, overflow menus, app chrome, and
+framework agent chrome stay in their real places. Model secondary surfaces as
+separate states, such as a top-right overflow popover, sheet, panel, loading
+state, or separate AgentSidebar, rather than inventing a permanent inspector or
+folding framework chrome into the product UI.
+
+- **No visual surface** for architecture-only, backend-only, data migration,
+  copy-only, or otherwise non-visual plans. Do not use the top canvas for
+  architecture diagrams, dependency maps, file plans, API contracts, or
+  data-flow-only reviews. Use a strong document with local inline diagrams
+  only when relationships need a visual explanation, usually one spatial diagram
+  per recommendation or decision. Prefer grouped regions, layers, quadrants,
+  matrices, or before/after panels over a single-axis chain unless the
+  relationship is truly sequential.
+- **Canvas only** for one static screen, a before/after comparison, a component
+  state, a small popover, or a visual direction that does not require clicking.
+  Put those wireframes in \`content.canvas\` and omit \`content.prototype\`.
+- **Canvas + prototype** for multi-step UI flows, onboarding, wizards,
+  review/approval flows, navigation changes, or anything where the reviewer
+  needs to operate the behavior. Keep the static wireframes in
+  \`content.canvas\`, add the aligned functional prototype in
+  \`content.prototype\`, and rely on the top visual tabs to switch between them.
+- **Prototype-first** when the user asks to operate the UI or when interaction is
+  the main question. Use \`create-prototype-plan\`, which still preserves static
+  mocks where useful.
+
+For mixed canvas + prototype plans, reuse the same real labels, app statuses,
+and screen ids across both surfaces. The canvas is the inspectable static reference;
+the prototype is the interactive version of that same flow, not a separate
+design direction.
+
+## Wireframe quality — read \`references/wireframe.md\`
+
+UI recap/plan wireframes must meet a strict quality bar — full-width chrome,
+pinned bottom bars, real product content, before/after comparability, the right
+\`surface\` preset, \`--wf-*\` tokens instead of hex, and no \`<html>\`/\`<style>\`/font
+tags. Before authoring ANY wireframe / \`<Screen>\` / \`WireframeBlock\`, READ
+\`references/wireframe.md\` in this skill directory — it is the single source of
+truth for HTML wireframe quality, shared word for word with \`/visual-plan\`
+and \`/visual-recap\`. Do not author wireframes from memory.
+
+## Canvas — read \`references/canvas.md\`
+
+The canvas is the single source of truth for static UI mockups: the \`surface\`
+locks each artboard's footprint, mixed surfaces lay out
+in lanes, annotations are plain-text designer notes anchored by
+\`targetId\`/\`placement\`, and edits are surgical \`contentPatches\`. Before
+authoring or editing ANY canvas, artboard, or annotation, READ
+\`references/canvas.md\` in this skill directory — it is the single source of truth
+for canvas/artboard mechanics. Do not author canvas layouts from memory.
+Canvas artboards use the same HTML wireframe path as document-body
+\`WireframeBlock\` screens: author \`<Screen surface="..." html={...} />\` with a
+semantic HTML fragment. Do not author fresh kit-tree children such as
+\`<FrameScreen>\`, \`<Card>\`, \`<Row>\`, or \`<Btn>\` inside canvas \`<Screen>\` tags;
+those are legacy compatibility markup for old plans and produce brittle canvas
+layouts.
+
+## Document quality — read \`references/document-quality.md\`
+
+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.
+
+## Good vs. bad exemplar — read \`references/exemplar.md\`
+
+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.
+
+## Tool Guidance
+
+- \`create-visual-plan\`: start one structured visual plan per agent task/run, or
+  import an existing text plan by passing \`planText\`; \`content\` may include no
+  visual surface, canvas only, or canvas + prototype.
+- \`create-ui-plan\`: start a UI-first plan when the work is primarily product UI.
+- \`create-prototype-plan\`: start a prototype-first plan with a functional top
+  review surface.
+- \`create-plan-design\`: start a full-fidelity branded Design-tab plan with an
+  optional matching Prototype tab.
+- \`convert-visual-plan-to-prototype\`: convert an existing HTML wireframe canvas
+  into a prototype plan.
+- \`create-visual-questions\`: use only when the user explicitly asks for a visual
+  intake questionnaire, not as \`/visual-plan\` preflight.
+- \`update-visual-plan\`: revise content, status, or comments with targeted
+  \`contentPatches\` (see Core Workflow step 6).
+- \`read-visual-plan-source\`: read the normalized plan as \`plan.mdx\`,
+  optional \`canvas.mdx\`, optional \`.plan-state.json\`, and JSON.
+- \`patch-visual-plan-source\`: apply granular MDX AST patches by stable block,
+  artboard, annotation, component, or wireframe-node id.
+- \`import-visual-plan-source\`: create or replace a plan from an MDX folder.
+- \`get-visual-plan\`: read the current structured plan, exported HTML, and
+  annotations; it also returns the MDX folder for source workflows.
+- \`get-plan-feedback\`: read unconsumed human feedback. Use it frequently; it
+  returns grouped threads, exact anchor details, expected resolver, and recent
+  review-event payloads so agents can act only on the comments meant for them.
+- \`get-plan-blocks\`: resolve block tags before authoring — do not memorize tags;
+  call this first to get the authoritative tag names, required fields, and prop
+  shapes from the live block registry.
+- \`export-visual-plan\`: export HTML, Markdown fallback, structured JSON, and MDX
+  files for repo check-in.
+
+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 — 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
+
+This section applies to hosted plans with \`get-plan-feedback\` /
+\`update-visual-plan\`. In local-files mode, do not call hosted feedback or update
+tools; interpret file/chat feedback directly, edit the MDX files, rerun the
+local bridge check/serve/verify command, and report the new local URL.
+
+\`get-plan-feedback\` returns rich anchors — read them before acting on any comment.
+
+- **Coordinate frames.** \`targetX\`/\`targetY\` are percentages *within* the
+  element named by \`targetSelector\`/\`targetKind\`. Bare \`x\`/\`y\` are percentages
+  of the whole plan document. \`canvasX\`/\`canvasY\` are raw board-world pixels on
+  the design canvas (board size given when available).
+- **Wireframe pins.** Anchors on wireframes include \`targetNodeId\` and
+  \`targetNodePath\` (e.g. \`card > list > listItem "Acme Inc"\`) identifying the
+  exact kit node. Use \`targetNodeId\` directly with wireframe node patch ops;
+  use \`data-design-id\` values from design artboards with
+  \`update-design-element-style\`. Prefer the node id/path over raw coordinates;
+  fall back to coordinates plus the focused screenshot (red ring marks the exact
+  point) only when no node id is present.
+- **Text quotes.** Resolve \`textQuote\` against current prose using
+  \`contextBefore\`/\`contextAfter\` for disambiguation. If \`ambiguous: true\`, ask
+  the user — do not guess which occurrence is meant.
+- **Detached comments.** \`get-plan-feedback\` flags threads whose quoted text no
+  longer exists as \`detached\` (in \`detachedThreads\`). Reconcile these against
+  rewritten content — never silently drop them.
+- **Routing.** \`resolutionTarget\` is the only routing signal: act on \`agent\`,
+  treat \`human\` as context only. \`@mentions\` are people to notify, never a
+  routing signal.
+- **Two-axis state.** Mark every ingested comment as consumed
+  (\`consumedCommentIds\` on \`update-visual-plan\`). Set \`status=resolved\` only on
+  agent-targeted comments you actually addressed; leave human-targeted comments
+  open.
+
+## Visibility & Sharing
+
+Use \`set-resource-visibility\` to change who can see a plan (e.g. public, login,
+or org-scoped). Use \`share-resource\` to grant specific users or roles access
+by email or role. Gate visibility before sharing any plan that covers
+unreleased or private work — default to the narrowest scope that meets the
+review need.
+
+## 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.
+
+**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 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.
+
+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.
+
+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.
+`;