@hybridlabor-api/aos 4.13.2 → 4.14.0

package/skills/global_config/visual-plan/references/canvas.md

@@ -0,0 +1,139 @@
+# Canvas & artboard placement — single source of truth
+
+This file is the canonical guide for how the visual-plan canvas works: artboard
+placement, lane layout, annotations, patching, and the legacy kit tree. Read it
+in full before authoring or editing any canvas/artboard content; do not author
+canvas layouts from memory or paraphrase these rules per mode.
+
+<!-- SHARED-CORE:canvas-surface START -->
+
+**The coordinate rule.** The `surface` sets each artboard's default footprint
+and width — never set width or use coordinates inside the wireframe HTML.
+Board-level artboard `x`/`y` IS allowed when it creates clear lanes. A
+larger explicit artboard `height` is allowed when the screen's content needs
+more vertical room; canvas frames do not scroll, so reserve enough height to
+show the entire UI. Let canvas auto-placement handle simple one-row boards.
+
+**Lay out mixed canvases in lanes.** When a canvas contains broad browser /
+desktop frames plus compact `mobile`, `popover`, or `panel` surfaces, do not put
+everything in one horizontal strip. Use board-level artboard `x`/`y` to reserve
+lanes with generous empty space: main flow on one row, compact surfaces in their
+own column or row, and loading/error states in a lower row. Keep at least 96px
+between rendered artboard rectangles plus room for annotation gutters; when a
+broad browser/desktop frame sits beside a compact panel/popover, leave at least
+160px so frame borders, labels, and hover controls never touch. Connect only
+neighboring steps; never draw a long connector that skips across unrelated
+frames. Connector labels must sit in open canvas space. If the label would touch
+or cross either artboard, remove the label and explain the transition with a
+nearby annotation instead. Before handoff, inspect the top canvas at default zoom
+and move any frame whose label, connector, or annotation crosses another frame.
+
+**Board-unit spacing defaults.** The canvas coordinate system uses approximately 2 board units per screen pixel. `browser` frames occupy roughly 700 × 600 board units; `desktop` frames roughly 900 × 700 board units. Apply these minimum x/y gaps when placing frames explicitly — any less and frames will touch or overlap:
+
+- x-gap between `browser` frames: **≥ 1100** (700-unit frame + 400-unit gutter)
+- x-gap between `desktop` frames: **≥ 1300** (900-unit frame + 400-unit gutter)
+- y-gap between rows of any surface: **≥ 1400** (includes frame height + section header + buffer)
+
+When in doubt, use larger values — the canvas auto-zooms to fit everything.
+
+**Full-content artboards.** Canvas frames are pan/zoom surfaces, not scroll
+containers. Keep wireframe HTML in natural document flow without an inner
+scroll region or fixed child height. If the screen is taller than the default
+surface preset, set the artboard's `height` to the measured content height plus
+breathing room; keep the surface width unchanged. Before handoff, inspect the
+bottom edge of every artboard at default zoom and confirm no control, row, or
+footer is clipped.
+
+**Canvas annotations are designer notes on the artboard.** When a top canvas is
+present, sprinkle design-review notes near the frames they explain: a short
+heading, supporting text, and bullets — plain text layers, never bordered or
+shadowed cards, and never a box around a frame. The renderer spaces notes away
+from frames, so place each note by the frame it describes. Use an arrow only to
+point at one specific control or transition; for a broad frame-level note, write
+text beside the frame with no connector. Connectors are for real sequences only —
+never fake "Step 1 → Step 2" lines between independent states.
+
+**Do not create overlapping annotations.** Anchor each ordinary note to the
+frame it explains with `targetId` + `placement` (top/right/bottom/left), and
+omit `type` or use `type: "note"`. The renderer parks notes in a gutter beside
+the frame and lays them out automatically. Do not use `type: "callout"`,
+`type: "text"`, `type: "arrow"`, x/y, or points for ordinary notes; those are
+freeform review-markup layers and must be reserved for intentional markup in
+open canvas space. Reserve arrows for a note that must point at one specific
+control inside a frame; a note that simply sits beside its frame needs no arrow.
+
+**Patching.** Edit one wireframe, canvas annotation, diagram, or block with targeted `contentPatches`
+(for example `patch-wireframe-html`, `patch-diagram-html`, `update-block`,
+`replace-blocks`, `update-canvas-annotation`) rather
+than regenerating the whole plan. `contentPatches` are part of the public MCP
+action schema, so Claude Code, Codex, Cursor, and other hosts can make surgical
+edits. If an agent is working from exported source files, use
+`read-visual-plan-source` / `patch-visual-plan-source`: `plan.mdx` holds
+frontmatter plus markdown/document blocks, `canvas.mdx` holds
+`<DesignBoard>/<Section>/<Artboard>/<Screen>/<Annotation>/<Connector>`, and the
+patch action normalizes the MDX back into the same JSON runtime model. JSON is
+the canonical runtime shape; MDX is the repo-friendly authoring/export surface.
+In the browser, humans edit `rich-text` prose inline; agents should still use
+`update-rich-text` content patches or source patches for prose, and use
+comments/structured patches for canvas, artboard, wireframe, and diagram edits.
+Never send a partial top-level `content` object as a shortcut to add a canvas,
+frame, or block: `content` is a full structured replacement, so omitted blocks
+or surfaces can disappear. If a full replacement is truly unavoidable, read the
+complete source/JSON first, include every existing block and surface in the new
+payload, and verify the source/export immediately after the update.
+
+**Never emit a titled artboard with no interior wireframe content.** Every artboard
+you place on the canvas must carry an `html` wireframe or reference a wireframe
+block via `blockId`; when using `blockId`, the referenced `wireframe` /
+`legacy-wireframe` block must remain in the plan. If you remove a duplicate
+wireframe from the document body, first move its `data` inline onto the
+corresponding `content.canvas.frames[*].wireframe` / `legacyWireframe`. A
+label-only frame or a frame pointing at a deleted block renders empty and is
+rejected at parse time. If you only have a title, write it as a section header or
+annotation, not an empty artboard.
+
+**UI mockups belong in the top visual review area.** Static UI/product visuals
+live on the canvas; multi-step UI flows get both canvas wireframes and a
+prototype. When the user asks for a mockup, UI state, loading state, layout,
+screen, or visual comparison, make the canvas the primary home for that static
+visual. When the user asks for a prototype or the plan contains a sequence the
+reviewer must feel, keep the canvas artboards and add `content.prototype` so the
+top surface shows Wireframes / Prototype tabs. Architecture/code diagrams stay
+inline in the document (the SKILL.md Visual Surface Choice section owns that
+rule) unless the user explicitly asks for a spatial board. Document blocks
+can explain, compare, or map implementation, but they should not host the
+primary UI mockup or prototype just because `custom-html`, screenshots, or prose
+are easier to produce. If the canvas/prototype surface cannot represent the
+requested UI fidelity, still keep the closest top-surface representation and
+call out or extend the needed renderer capability. A skeleton/loading mockup
+also lives in a canvas artboard — never move a mockup out of the canvas.
+
+**Storyboards are canvas artifacts, not document diagrams.** When the requested
+output is a product flow, onboarding journey, "light storyboard", or canvas
+wireframe, author the flow as multiple top-canvas artboards with real screen
+content and neighboring connectors. Keep document-body `diagram` blocks for
+architecture and mechanics that are not themselves user-visible screens. A
+storyboard made from a single inline HTML diagram is the wrong surface.
+
+For abstract product concepts, use the canvas to create the first "I get it"
+moment: one real app state near the top showing how the concept appears to a
+user, followed by separate annotations or diagrams for mechanics. Do not make
+the first artboard a hybrid of app UI and architecture notes; the app screen
+should be inspectable as product UI on its own.
+
+**Legacy kit tree.** Older plans set a `screen` array of `{ el, ...props }` kit
+nodes instead of `html`; the renderer still accepts and displays it so saved
+plans round-trip, but new plans emit `html`. Do not author fresh kit-tree
+screens, and do not put nested kit components such as `<FrameScreen>`, `<Card>`,
+`<Row>`, `<Title>`, or `<Btn>` inside a canvas `<Screen>`. A new canvas artboard
+with kit-tree children is a defect: replace it with
+`<Screen surface="..." html={...} />` using the HTML wireframe rules. The HTML
+path is the one that gets the renderer-owned surface sizing, theme tokens,
+sketch/clean toggle, and safe text layout used by good document-body
+wireframes. Likewise, old or imported plans may carry coordinate-based regions
+or free-float x/y on notes; those are legacy escape hatches the renderer still
+shows but you must never produce. The gutter parks notes by `targetId` +
+`placement`, and the coordinate rule at the top of this file governs all
+new-plan placement.
+
+<!-- SHARED-CORE:canvas-surface END -->

package/skills/global_config/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/skills/global_config/visual-plan/references/document-quality.md

@@ -0,0 +1,186 @@
+# 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.
+
+<!-- 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 -->

package/skills/global_config/visual-plan/references/exemplar.md

@@ -0,0 +1,62 @@
+# 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.
+
+<!-- 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 -->

package/skills/global_config/visual-plan/references/local-files.md

@@ -0,0 +1,99 @@
+# 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` also stays on-device: it uses the offline lint unless it
+  can reach a Plan renderer on an explicit loopback `--app-url`.
+- **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.
+  The token is carried in the URL fragment (which is not sent to the hosted
+  origin), and the local-plan route disables DOM autocapture and session replay
+  while retaining sanitized pageviews and error monitoring. 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 and checks the private-network preflight and JSON payload
+  entirely on loopback. It never sends MDX or assets to a remote validation
+  action. When `--app-url` points to a loopback Plan app, verify also validates
+  against that local app's real renderer schema via `validate-local-plan-source`.
+  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`, verify used the offline lint because the app URL was remote or the
+  local Plan app was unavailable. Run a local Plan app and pass
+  `--app-url 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 prevents plan/recap content from being uploaded to the
+Agent-Native Plan server or 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 -->