@hybridlabor-api/aos 4.17.0 → 4.18.1

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

@@ -1,139 +0,0 @@
-# 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

@@ -1,51 +0,0 @@
-# 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

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

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

@@ -1,99 +0,0 @@
-# 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 -->