@agent-native/core 0.122.3 → 0.123.0

package/docs/content/template-plan.mdx

@@ -11,7 +11,7 @@ description: "Agent-Native Plans turns your coding agent's plan into a structure
 adds the `/visual-plan`, `/visual-recap`, and `/visualize-repo` skills plus
 the hosted Plan connector to your coding agent — see
 [Plan plugin & marketplace](/docs/plan-plugin) for the plugin and marketplace
-routes. Forking the Plan template (covered under [For developers](#for-developers))
+routes. Forking the Plan template (covered under [Extending Plan](/docs/template-plan-developers))
 is the secondary path, for self-hosting or building on Plan itself.
 
 </Callout>
@@ -110,70 +110,27 @@ There are two ways into Plans:
 
 ## Install the skill {#install}
 
-Use the Agent-Native CLI. This is the recommended setup because it installs the
-Plans skill instructions, registers the hosted Plans MCP connector, **and** runs
-the client-specific auth/setup flow in one step, so your first tool call does not
-hit an OAuth wall:
+Use the Agent-Native CLI. This installs the Plans skill instructions, registers
+the hosted Plans MCP connector, **and** runs the client-specific auth flow in
+one step, so your first tool call does not hit an OAuth wall:
 
 ```bash
 npx @agent-native/core@latest skills add visual-plan
 ```
 
-The command installs three commands: `/visual-plan`, `/visual-recap`, and
-`/visualize-repo`.
+The command installs three commands — `/visual-plan`, `/visual-recap`, and
+`/visualize-repo` — plus the `plan` MCP connector at
+`https://plan.agent-native.com/mcp`. Authentication is a one-time browser
+sign-in at setup; this is intended, and it is what lets the agent persist and
+share the plans it generates.
 
-If you are using a chat-based host that accepts MCP connector URLs directly
-(rather than a CLI-configured client), connect the hosted Plans connector at
-`https://plan.agent-native.com/mcp` — see [MCP Clients](/docs/mcp-clients) for client-specific setup.
-
-Authentication is a one-time browser sign-in at setup — this is intended, and it
-is what lets the agent persist and share the plans it generates. What the auth
-step does depends on your client:
-
-- **OAuth-capable hosts** (Claude Code) get a URL-only MCP entry plus a prompt to
-  run `/mcp` and choose **Authenticate**.
-- **Codex / Cowork** run a short browser device-code flow: the CLI prints a code,
-  opens the verification page, and writes the connector once you approve.
-- In a **non-interactive shell or CI**, the auth step is skipped and the exact
-  command to run later is printed for you.
-
-By default the CLI targets every supported local client it can configure. Pass
-`--client codex`, `--client claude-code`, or another specific client when you
-want to narrow setup to one host:
-
-```bash
-npx @agent-native/core@latest skills add visual-plan
-```
-
-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`:
-
-```bash
-npx @agent-native/core@latest skills add visual-plan --no-connect
-```
-
-To auto-generate a recap on **every pull request**, pass `--with-github-action`.
-This writes a GitHub Action that runs the `visual-recap` skill on each PR and
-posts an interactive recap plan with an inline screenshot as a sticky comment —
-see [PR Visual Recap](/docs/pr-visual-recap).
-
-```bash
-npx @agent-native/core@latest skills add visual-plan --with-github-action
-```
-
-After the workflow is written, run `npx @agent-native/core@latest recap setup` to configure
-GitHub Actions secrets/variables where possible and `npx @agent-native/core@latest recap doctor`
-to verify the repo is ready.
-
-If you only want the portable instruction file through the open Skills CLI, use:
-
-```bash
-npx skills@latest add BuilderIO/agent-native --skill visual-plan
-```
-
-That installs the skill instructions only. It does not register the hosted MCP
-connector, so use the Agent-Native CLI path when you want the one-command setup.
+For the full flag reference (`--client`, `--mode`, `--mcp-url`, `--no-connect`,
+`--with-github-action`), the plugin/marketplace install routes for Claude Code
+and Codex, and the bare-instructions fallback, see
+[Plan plugin & marketplace → Install routes](/docs/plan-plugin#install). To
+auto-generate a recap on every pull request, that same page's
+`--with-github-action` flag writes the GitHub Action described in
+[PR Visual Recap](/docs/pr-visual-recap).
 
 <Callout tone="info">
 
@@ -188,18 +145,11 @@ improve — see [Plan plugin & marketplace](/docs/plan-plugin).
 
 If you live in VS Code, install the
 [Agent-Native Plans extension](https://marketplace.visualstudio.com/items?itemName=Builder.agent-native)
-to open the same Plan review surface in a side panel instead of sending you to a
-separate browser tab. Plans tools still return the normal web link, and the MCP
-metadata also includes a VS Code handoff URL:
-
-```text
-vscode://builder.agent-native/open?url=<encoded-plan-url>
-```
-
-The extension handles that URI, opens the decoded Plan URL in a VS Code webview,
-and includes a command to run the existing Agent Native MCP connect flow for VS
-Code / GitHub Copilot. This is especially useful from Claude Code or another
-coding-agent workflow where the plan should stay next to the files being edited.
+to open the same Plan review surface in a side panel instead of a separate
+browser tab. The extension handles the `vscode://builder.agent-native/open`
+handoff URL that Plan tools return alongside the normal web link, and it
+includes a command to run the Agent Native MCP connect flow for VS Code /
+GitHub Copilot.
 
 ## Use it from your coding agent
 
@@ -248,13 +198,17 @@ the diff or plan and the model you choose.
 - **Comment directly on the plan.** Pin feedback to text, images, wireframes, or
   canvas locations; choose whether the comment is for the agent or a human
   reviewer; @mention teammates with inline chips; and resolve comments as the
-  plan evolves.
+  plan evolves. See [Reviewing and Commenting on Plans](/docs/template-plan-review-workflow)
+  for the full comment and sharing model.
 - **Hand feedback to the agent clearly.** Text comments attach to the nearest
   prose block, visual comments include exact target metadata, and browser
   handoff includes focused screenshots for a small set of visual/canvas comment
   locations instead of one hard-to-read giant image.
 - **Export the result.** Keep an HTML, Markdown, or JSON receipt of the plan
   when you need a source-control-friendly handoff.
+- **Keep plan content private.** Use local-files mode to write plans to a local
+  MDX folder instead of the hosted database — see
+  [Local-Files Mode and Desktop Sync](/docs/template-plan-local-and-desktop).
 
 ## Editing in the browser as a guest {#guest}
 
@@ -270,188 +224,45 @@ editor toolbar or slash menu, and Plans autosaves the underlying markdown. Revie
 annotation mode temporarily turns text sections read-only so clicks can pin
 feedback; leave review mode to keep editing prose.
 
-## Sharing and commenting {#sharing}
-
-Sharing and commenting are the workflows that need an account:
-
-- **Viewing** a public or shared plan works for anyone with the link — no account
-  required.
-- **Commenting** on a shared plan requires an agent-native account.
-- **Sharing** a plan (publishing it to a link, private sharing, reviewer access,
-  cross-device or team review) requires signing in. Google sign-in appears when
-  the standard Google OAuth env vars are configured.
-
-The hosted Plans connector lives at `https://plan.agent-native.com/mcp`.
-Never put shared secrets in skill files.
-
-## Local-files privacy mode {#local-files}
-
-For privacy-focused work, ask for local-files mode:
-
-```text
-Use /visual-plan in local-files mode. Do not write this plan to the Plan DB.
-```
-
-or set the convention for your agent environment:
-
-```bash
-export AGENT_NATIVE_PLANS_MODE=local-files
-```
-
-In this mode the agent writes a local MDX folder and must not call the hosted
-Plan MCP tools. Use a repo folder such as `plans/<slug>/` when you want the plan
-checked in with the code. Use a temp or ignored folder, such as
-`/tmp/agent-native-plans/<slug>/` or `.agent-native/plans/<slug>/`, when the
-plan should stay out of git. The folder contains:
-
-- `plan.mdx`
-- optional `canvas.mdx`
-- optional `prototype.mdx`
-- optional `.plan-state.json`
-
-After writing the folder, the agent starts a tiny localhost bridge and opens the
-hosted Plan UI against that local-only source:
-
-```bash
-npx @agent-native/core@latest plan local check --dir plans/<slug>
-npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
-```
-
-The bridge URL looks like
-`https://plan.agent-native.com/local-plans/local-<opaque-id>#bridge=http://127.0.0.1:...`.
-The page is the normal Plan viewer, but the browser fetches `plan.mdx`,
-`canvas.mdx`, `prototype.mdx`, `.plan-state.json`, and local image assets from
-the localhost bridge. Plan content is not written to the hosted database and is
-not sent through hosted Plan actions. Keep the bridge process running while you
-review; the URL is local to your machine and is not a shareable team link. The
-serve command writes the open URL to `.plan-url` by default so coding agents can
-capture it without scraping long-running stdout; treat that file as local-only
-because the URL contains the bridge token, and do not commit it.
-
-On macOS, `--open` prefers Chrome/Chromium because Safari can block the hosted
-HTTPS Plan page from fetching an HTTP localhost bridge. For headless
-troubleshooting, run:
-
-```bash
-npx @agent-native/core@latest plan local verify --dir plans/<slug> --kind plan
-```
-
-`verify` starts the bridge, checks the private-network preflight and JSON
-payload, prints diagnostics, and exits.
-
-If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can also
-open the editable app route:
-
-```text
-http://localhost:<port>/local-plans/<slug>
-```
-
-For repo-backed folders, the direct local route can carry the repo-relative
-folder path so browser edits keep writing to that folder:
-
-```text
-http://localhost:<port>/local-plans/<slug>?path=plans%2F<slug>
-```
-
-The Plan app uses `apps.plan.roots[0].path` in `agent-native.json` as the
-default repo location for promoted local plans, falling back to `plans/`:
-
-```json
-{
-  "version": 1,
-  "apps": {
-    "plan": {
-      "mode": "local-files",
-      "roots": [{ "name": "Plans", "path": "plans", "kind": "plans" }]
-    }
-  }
-}
-```
-
-Direct local Plan routes include a menu action to save a temporary local folder
-into that repo location. After promotion, the page reopens with `?path=...` and
-continues autosaving MDX edits to the repo folder.
-
-Local-files mode prevents plan or recap content from going to the Agent-Native
-Plan database. It also disables hosted sharing, browser comments, plan history,
-and publish/export receipts until you explicitly opt into publishing. To move a
-local plan into the hosted database, call `publish-visual-plan` with the local
-MDX folder path; this uploads the plan, assigns it a hosted ID, enables sharing
-and commenting, and returns the hosted URL. Local-files mode does not
-automatically make your coding agent's LLM local; choose a local or approved
-model if that privacy boundary matters too.
-
-## Repo visual docs {#visualize-repo}
-
-Use `/visualize-repo` when you want a durable visual documentation layer for a
-codebase instead of a one-off plan or recap. It creates or opens a local Plan
-MDX workspace, updates `agent-native.json` with an `apps.visualize-repo`
-local-files section, and serves the docs through the same localhost bridge:
-
-```bash
-npx @agent-native/core@latest visualize-repo --open
-```
-
-If no `agent-native.json` exists, the command bootstraps one and recommends a
-small starter set from the repo structure, such as `actions/`,
-`app/components/`, `app/pages/`, `server/db/schema.ts`, `src/`, `packages/`,
-`templates/`, `docs/`, or `content/`. You can target specific source anchors:
-
-```bash
-npx @agent-native/core@latest visualize-repo \
-  --target actions/webhooks.ts \
-  --target server/db/schema.ts \
-  --target app/components/PromptComposer.tsx
-```
-
-The starter folder lives at `.agent-native/visual-docs/repo-overview` by
-default. Comments stay local in `comments.json`, so reviewers can mark sections
-for a coding agent and the agent can update both code and MDX in the same
-change. Run `visualize-repo check` for local lint, and `visualize-repo verify`
-when you want the Plan renderer schema to validate the MDX.
+<Callout tone="info">
 
-## Desktop local file sync {#desktop-local-sync}
+**Guest vs. signed-in, at a glance**
 
-Agent Native Desktop also gives hosted Plans a native local-folder bridge. This
-is different from local-files privacy mode: the hosted Plan database remains the
-source of truth for sharing, comments, history, and live review, while Desktop
-can mirror the current plan's source files to a folder you choose.
+- **As a guest** you can open a shared link, create a new plan, edit prose,
+  and use review annotation mode — no account needed.
+- **Signing in** additionally lets you save your own plans permanently, publish
+  a plan to a shareable link, grant viewer/editor/admin access to others, post
+  comments that notify people by email, and delete or restore plans you own.
 
-Open a plan in Agent Native Desktop, use the plan menu's **Local files** actions,
-then:
+</Callout>
 
-- **Link local folder** — choose the folder for that plan's MDX source.
-- **Sync to local folder** — write `plan.mdx`, optional `canvas.mdx`,
-  optional `prototype.mdx`, optional `.plan-state.json`, and image assets.
-- **Import local edits** — read the folder and apply it through
-  `import-visual-plan-source` with the plan's current update timestamp.
-- **Auto-sync changes** — keep exporting the hosted plan's latest source after
-  edits made in the app.
+## Requesting access to a private plan {#request-access}
 
-This path does not require cloning the Plan app or running a CLI. It is for
-file-first review/editing around a hosted plan, not for keeping plan content out
-of the hosted database.
+If someone opens a plan link they do not have permission to view, Plans does
+not just show a dead end. The page tells them the plan is private and offers a
+**Request access** action. Requesting access:
 
-## Deleting hosted plan data {#delete-data}
+- Requires being signed in (a guest is prompted to sign in first).
+- Records the request against the plan and, when the deployment has email
+  configured, sends the plan owner a message with the requester's name and a
+  link to open the plan and share it back if approved.
+- Is safe to click more than once — Plans checks whether you already have
+  access first, and a second request from the same person does not spam the
+  owner with duplicate emails.
 
-Signed-in owners can delete their hosted plans and recaps from the Plans list or
-the plan action menu.
+If the plan's visibility is set to **org** rather than fully private, and your
+account already has a pending invitation to that organization or an email
+domain that matches it, Plans offers to join the organization directly instead
+of sending a request.
 
-- **Soft delete** moves the plan to the **Deleted** tab, makes normal plan
-  views/direct links stop working, and removes public access by making the row
-  private. The SQL rows are retained so the owner can restore the plan later.
-- **Restore** is available from the **Deleted** tab for soft-deleted plans.
-- **Permanent delete** removes the hosted plan row and plan-scoped comments,
-  sections, activity events, version snapshots, share grants, abuse reports, and
-  SQL asset records. The UI requires typing `DELETE <plan-id>` before the final
-  button enables.
+## Recovering from auth errors {#auth-errors}
 
-Permanent delete removes the Plan app's database records and SQL-backed asset
-bytes/references. If a deployment uses an external upload provider, provider
-object retention follows that provider's lifecycle because the shared upload
-abstraction does not currently expose object deletion. Local-files privacy mode
-keeps the source in your local MDX folder instead; deleting hosted data does not
-touch local files.
+If a Plans tool ever returns `needs auth`, `Unauthorized`, or `Session
+terminated`, do not keep retrying it. Authenticate the connector with
+`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
+for Codex, or re-run `/mcp` → **Authenticate** in an OAuth-capable host. Start a
+new Codex thread or restart/reload the relevant client before expecting the tool
+registry to update.
 
 ## Useful prompts
 
@@ -463,674 +274,13 @@ touch local files.
 - "Use `/visual-recap` in local-files mode so no recap content is written to the Plan DB."
 - "Run `/visualize-repo` and start with our public API actions and schema."
 
-## Recovering from auth errors {#auth-errors}
-
-If a Plans tool ever returns `needs auth`, `Unauthorized`, or `Session
-terminated`, do not keep retrying it. Authenticate the connector with
-`npx -y @agent-native/core@latest reconnect https://plan.agent-native.com --client codex`
-for Codex, or re-run `/mcp` → **Authenticate** in an OAuth-capable host. Start a
-new Codex thread or restart/reload the relevant client before expecting the tool
-registry to update.
-
-## For developers
-
-The rest of this doc is for anyone forking or self-hosting the Plans template.
-Most users should install the skill with the CLI instead of scaffolding the app.
-
-### Quick start
-
-```bash
-npx @agent-native/core@latest create my-plans --standalone --template plan
-cd my-plans
-pnpm install
-pnpm dev
-```
-
-The hosted app-backed skill uses:
-
-- App: `https://plan.agent-native.com`
-- MCP: `https://plan.agent-native.com/mcp`
-
-The local template is useful when you are developing Plans itself, testing local persistence, or running a fully self-hosted review surface.
-
-### Data model
-
-Schema lives in `templates/plan/server/db/schema.ts`. Core tables:
-
-| Table              | What it holds                                                                                                                                                                           |
-| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `plans`            | Each plan or recap — `title`, `brief`, `kind` (plan/recap), `status`, `source`, `html`/`markdown`/`content`, `hosted_plan_id/url`, usage stats, `source_url`, `deleted_at`/`deleted_by` |
-| `plan_sections`    | Ordered sections within a plan — `type`, `title`, `body`, `html`, `sort_order`, `created_by`                                                                                            |
-| `plan_comments`    | Threaded comments — `kind`, `status`, `anchor`, `message`, `resolution_target`, `mentions_json`, `resolved_by`                                                                          |
-| `plan_events`      | Audit log of agent/human events on a plan                                                                                                                                               |
-| `plan_versions`    | Point-in-time snapshots for version history                                                                                                                                             |
-| `plan_shares`      | Per-principal share grants (viewer / editor / admin)                                                                                                                                    |
-| `plan_guest_mints` | Rate-limit records for guest session issuance                                                                                                                                           |
-| `plan_assets`      | Inline image assets stored as base64 (fallback when no upload provider)                                                                                                                 |
-
-<DataModel
-  id="doc-block-1dtds8f"
-  title="Plan data model"
-  summary="One plan row owns ordered sections plus comments, events, versions, shares, and inline assets."
-  entities={[
-    {
-      id: "plans",
-      name: "plans",
-      note: "each plan or recap",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "title",
-          type: "text",
-        },
-        {
-          name: "brief",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "kind",
-          type: "enum",
-          note: "plan | recap",
-        },
-        {
-          name: "status",
-          type: "text",
-        },
-        {
-          name: "source",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "hosted_plan_id",
-          type: "text",
-          nullable: true,
-          note: "hosted_plan_url paired",
-        },
-        {
-          name: "source_url",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "deleted_at",
-          type: "timestamp",
-          nullable: true,
-          note: "soft delete; deleted_by paired",
-        },
-      ],
-    },
-    {
-      id: "plan_sections",
-      name: "plan_sections",
-      note: "ordered sections within a plan",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "plan_id",
-          type: "text",
-          fk: "plans.id",
-        },
-        {
-          name: "type",
-          type: "text",
-        },
-        {
-          name: "title",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "body",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "html",
-          type: "text",
-          nullable: true,
-        },
-        {
-          name: "sort_order",
-          type: "integer",
-        },
-        {
-          name: "created_by",
-          type: "text",
-          nullable: true,
-        },
-      ],
-    },
-    {
-      id: "plan_comments",
-      name: "plan_comments",
-      note: "threaded comments",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "plan_id",
-          type: "text",
-          fk: "plans.id",
-        },
-        {
-          name: "kind",
-          type: "text",
-        },
-        {
-          name: "status",
-          type: "text",
-        },
-        {
-          name: "anchor",
-          type: "json",
-          nullable: true,
-        },
-        {
-          name: "message",
-          type: "text",
-        },
-        {
-          name: "resolution_target",
-          type: "text",
-          nullable: true,
-          note: "agent | human | null",
-        },
-        {
-          name: "mentions_json",
-          type: "json",
-          nullable: true,
-        },
-        {
-          name: "resolved_by",
-          type: "text",
-          nullable: true,
-        },
-      ],
-    },
-    {
-      id: "plan_events",
-      name: "plan_events",
-      note: "audit log of agent/human events",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "plan_id",
-          type: "text",
-          fk: "plans.id",
-        },
-      ],
-    },
-    {
-      id: "plan_versions",
-      name: "plan_versions",
-      note: "point-in-time snapshots",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "plan_id",
-          type: "text",
-          fk: "plans.id",
-        },
-      ],
-    },
-    {
-      id: "plan_shares",
-      name: "plan_shares",
-      note: "per-principal grants",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "plan_id",
-          type: "text",
-          fk: "plans.id",
-        },
-        {
-          name: "role",
-          type: "enum",
-          note: "viewer | editor | admin",
-        },
-      ],
-    },
-    {
-      id: "plan_guest_mints",
-      name: "plan_guest_mints",
-      note: "rate-limit records for guest session issuance",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-      ],
-    },
-    {
-      id: "plan_assets",
-      name: "plan_assets",
-      note: "inline image assets as base64",
-      fields: [
-        {
-          name: "id",
-          type: "text",
-          pk: true,
-        },
-        {
-          name: "plan_id",
-          type: "text",
-          fk: "plans.id",
-        },
-      ],
-    },
-  ]}
-  relations={[
-    {
-      from: "plans",
-      to: "plan_sections",
-      kind: "1-n",
-      label: "has sections",
-    },
-    {
-      from: "plans",
-      to: "plan_comments",
-      kind: "1-n",
-      label: "has comments",
-    },
-    {
-      from: "plans",
-      to: "plan_events",
-      kind: "1-n",
-      label: "has events",
-    },
-    {
-      from: "plans",
-      to: "plan_versions",
-      kind: "1-n",
-      label: "has versions",
-    },
-    {
-      from: "plans",
-      to: "plan_shares",
-      kind: "1-n",
-      label: "has shares",
-    },
-    {
-      from: "plans",
-      to: "plan_assets",
-      kind: "1-n",
-      label: "has assets",
-    },
-  ]}
-/>
-
-### Key actions
-
-Actions in `templates/plan/actions/`:
-
-- **Creation** — `create-visual-plan`, `create-visual-recap`, `create-ui-plan`, `create-prototype-plan`, `create-plan-design`, `create-visual-questions`
-- **Reading & editing** — `get-visual-plan`, `update-visual-plan`, `list-visual-plans`, `import-visual-plan-source`, `patch-visual-plan-source`, `read-visual-plan-source`, `export-visual-plan`
-- **Lifecycle** — `delete-visual-plan` for owner-only soft delete, restore, and typed-confirmation permanent delete
-- **Publishing & sharing** — `publish-visual-plan`
-- **Versions** — `list-plan-versions`, `get-plan-version`, `restore-plan-version`
-- **Comments & feedback** — `get-plan-feedback`, `reply-to-plan-comment`, `resolve-plan-comment`, `consume-plan-feedback`, `delete-plan-comment`
-- **Prototype** — `convert-visual-plan-to-prototype`, `create-prototype-plan`
-- **Context & navigation** — `view-screen`, `navigate`
-
-### Custom MDX blocks {#custom-mdx-blocks}
-
-Plans source files are MDX, but the app does not render arbitrary imported JSX
-components. A custom MDX tag must be registered as a Plan block so the server can
-parse and serialize it, the browser can render and edit it, and the agent can
-see it in the block vocabulary returned by `get-plan-blocks`.
-
-A registered block has three surfaces:
-
-- A React-free schema and MDX config, safe for server and agent code.
-- A normalized runtime type/schema entry in `shared/plan-content.ts`.
-- A browser block spec with `Read` and optional `Edit` React components.
-
-Keep the block `type` and MDX `tag` stable. The `type` is stored in normalized
-plan JSON; the `tag` is the component name in `plan.mdx`. The registry handles
-the base MDX attributes `id`, `title`, `summary`, and `editable`, so do not
-repeat them in `toAttrs`.
-
-1. Add a shared config for the data shape and MDX round trip.
-
-```ts filename="templates/plan/shared/risk-card.config.ts"
-import { z } from "zod";
-import {
-  markdown,
-  type BlockMdxConfig,
-} from "@agent-native/core/blocks/server";
-
-export type RiskCardSeverity = "low" | "medium" | "high";
-
-export interface RiskCardData {
-  severity?: RiskCardSeverity;
-  body: string;
-}
-
-const severities = new Set(["low", "medium", "high"]);
-
-export const riskCardSchema = z.object({
-  severity: z.enum(["low", "medium", "high"]).optional(),
-  body: markdown(z.string().trim().min(1).max(10_000)),
-}) as z.ZodType<RiskCardData>;
-
-export const riskCardMdx: BlockMdxConfig<RiskCardData> = {
-  tag: "RiskCard",
-  childrenField: "body",
-  toAttrs: (data) => ({
-    severity: data.severity,
-  }),
-  fromAttrs: (attrs, children) => {
-    const severity = attrs.string("severity");
-
-    return {
-      severity: severities.has(severity ?? "")
-        ? (severity as RiskCardSeverity)
-        : undefined,
-      body: children,
-    };
-  },
-};
-```
-
-2. Extend the normalized Plan content model in
-   `templates/plan/shared/plan-content.ts`.
-
-Add the new `type` to `PlanBlockType`, add a matching block interface to the
-`PlanBlock` union, and add the same data shape to `planBlockSchema`. This keeps
-database saves, source imports, and `update-block` patches validating the custom
-block instead of rejecting it as an unknown type.
-
-3. Register the React-free server spec in
-   `templates/plan/shared/plan-block-registry.ts`.
-
-```ts filename="templates/plan/shared/plan-block-registry.ts"
-import {
-  BlockRegistry,
-  defineBlock,
-  registerLibraryBlockConfigs,
-  registerBlocks,
-} from "@agent-native/core/blocks/server";
-import {
-  riskCardMdx,
-  riskCardSchema,
-  type RiskCardData,
-} from "./risk-card.config.js";
-
-const ServerReadStub = () => null;
-
-const riskCardServerBlock = defineBlock<RiskCardData>({
-  type: "risk-card",
-  schema: riskCardSchema,
-  mdx: riskCardMdx,
-  Read: ServerReadStub,
-  placement: ["block"],
-  label: "Risk card",
-  description: "A markdown risk note with a low, medium, or high severity.",
-});
-
-export function registerPlanBlocks(registry: BlockRegistry): void {
-  registerLibraryBlockConfigs(registry, {
-    overrides: PLAN_SERVER_LIBRARY_OVERRIDES,
-  });
-  registerBlocks(registry, [riskCardServerBlock]);
-}
-```
-
-4. Register the browser spec in
-   `templates/plan/app/components/plan/planBlocks.tsx`.
-
-```tsx filename="templates/plan/app/components/plan/planBlocks.tsx"
-import {
-  defineBlock,
-  registerLibraryBlocks,
-  registerBlocks,
-  type BlockReadProps,
-} from "@agent-native/core/blocks";
-import {
-  riskCardMdx,
-  riskCardSchema,
-  type RiskCardData,
-} from "@shared/risk-card.config";
-
-function RiskCardBlock({ data, blockId, ctx }: BlockReadProps<RiskCardData>) {
-  return (
-    <section
-      className="rounded-md border border-border bg-card p-4"
-      data-block-id={blockId}
-      data-severity={data.severity}
-    >
-      <div className="mb-2 text-xs font-semibold uppercase text-muted-foreground">
-        {data.severity ?? "risk"}
-      </div>
-      {ctx.renderMarkdown?.(data.body) ?? (
-        <p className="whitespace-pre-wrap text-sm">{data.body}</p>
-      )}
-    </section>
-  );
-}
-
-const riskCardBlock = defineBlock<RiskCardData>({
-  type: "risk-card",
-  schema: riskCardSchema,
-  mdx: riskCardMdx,
-  Read: RiskCardBlock,
-  placement: ["block"],
-  editSurface: "panel",
-  label: "Risk card",
-  description: "A markdown risk note with a low, medium, or high severity.",
-  empty: () => ({ severity: "medium", body: "Describe the risk." }),
-});
-
-registerLibraryBlocks(planBlockRegistry, {
-  overrides: PLAN_LIBRARY_OVERRIDES,
-});
-registerBlocks(planBlockRegistry, [riskCardBlock]);
-```
-
-With that in place, Plan MDX can use:
-
-```mdx
-<RiskCard id="risk-auth" severity="high">
-
-Token refresh failures can strand active reviewer sessions.
-
-</RiskCard>
-```
-
-The server registry makes this source importable/exportable, and the client
-registry makes it render in `PlanBlockView`. If the block should be generated by
-agents, keep `label`, `description`, `placement`, and `empty` precise; those
-fields flow into the live block vocabulary.
-
-When overriding an existing block, register the override after the shared
-library registration. Last registration wins for both `type` and MDX `tag`.
-
-After adding a block, run focused Plan tests:
-
-```bash
-pnpm --filter plan test -- plan-mdx plan-block-registry
-```
-
-### Route map
-
-- `app/routes/plans.$id.tsx` — plan editor / review surface
-- `app/routes/plans._index.tsx` — plan list
-- `app/routes/share.$token.tsx` — public / shared plan view
-- `app/routes/local-plans.$slug.tsx` — local-files mode preview
-
-### Local mode (advanced, offline) {#local-mode}
-
-For fully offline, no-account use, you can run the Plans app locally and point it at local MDX folders. For the stricter no-DB path, use [local-files privacy mode](#local-files), which reads from MDX folders instead of creating local SQL rows. Local mode is a separate, advanced path — not the default hosted flow.
-
-## Events and notifications {#events}
-
-The Plan template emits four events on the framework event bus. Any automation
-can subscribe to them — no custom integration code needed.
-
-### Event reference {#event-reference}
-
-#### `plan.created`
-
-Fires when a new visual plan or recap is created.
-
-| Field       | Type                  | Description                              |
-| ----------- | --------------------- | ---------------------------------------- |
-| `planId`    | string                | Unique plan identifier                   |
-| `title`     | string                | Plan title                               |
-| `kind`      | `"plan"` \| `"recap"` | Whether this is a plan or a recap        |
-| `status`    | string                | Initial status (e.g. `"review"`)         |
-| `path`      | string                | App-relative path (e.g. `/plans/plan-…`) |
-| `createdBy` | string                | Always `"agent"` for plan creation       |
-
-#### `plan.commented`
-
-Fires when one or more comments are added to a plan.
-
-| Field              | Type                             | Description                                                 |
-| ------------------ | -------------------------------- | ----------------------------------------------------------- |
-| `planId`           | string                           | Plan identifier                                             |
-| `title`            | string                           | Plan title                                                  |
-| `kind`             | `"plan"` \| `"recap"`            | Plan or recap                                               |
-| `commentIds`       | string[]                         | IDs of the new comments                                     |
-| `commentCount`     | number                           | Number of new comments in this batch                        |
-| `resolutionTarget` | `"agent"` \| `"human"` \| `null` | Dominant target — `"agent"` if any comment targets an agent |
-| `excerpt`          | string                           | First 200 characters of the first comment                   |
-| `author`           | string \| null                   | Email of the commenter, if known                            |
-| `path`             | string                           | App-relative path                                           |
-
-#### `plan.published`
-
-Fires when a local plan is published (or re-published) to a hosted shareable URL.
-
-| Field                 | Type                  | Description                        |
-| --------------------- | --------------------- | ---------------------------------- |
-| `planId`              | string                | Local plan identifier              |
-| `title`               | string                | Plan title                         |
-| `kind`                | `"plan"` \| `"recap"` | Plan or recap                      |
-| `hostedPlanId`        | string                | Hosted plan identifier             |
-| `url`                 | string                | Full public URL of the hosted plan |
-| `requestedVisibility` | string                | `"public"`, `"private"`, etc.      |
-
-#### `plan.status.changed`
-
-Fires when a plan's status changes (e.g. `review` → `approved`).
-
-| Field       | Type                  | Description                        |
-| ----------- | --------------------- | ---------------------------------- |
-| `planId`    | string                | Plan identifier                    |
-| `title`     | string                | Plan title                         |
-| `kind`      | `"plan"` \| `"recap"` | Plan or recap                      |
-| `oldStatus` | string \| null        | Previous status                    |
-| `newStatus` | string                | New status                         |
-| `changedBy` | string \| null        | Email of the person who changed it |
-| `path`      | string                | App-relative path                  |
-
-### Automation recipes {#automation-recipes}
-
-These automations are created by asking the plan agent — no code changes needed.
-The agent calls `manage-automations` with `action=define`, writes a
-`jobs/<name>.md` resource, and the event subscription starts immediately.
-
-#### Notify via webhook when someone comments on a plan
-
-Ask the plan agent:
-
-> "When someone adds a human comment on a plan, POST a message to my webhook."
-
-The agent creates an automation like this:
-
-```yaml
----
-triggerType: event
-event: plan.commented
-condition: "resolutionTarget is human or resolutionTarget is null"
-mode: agentic
-domain: plan
-enabled: true
----
-Send a POST request to ${keys.NOTIFY_WEBHOOK} with a JSON body containing:
-  - "title": the plan title from the event payload
-  - "excerpt": the comment excerpt from the event payload
-  - "url": the base app URL concatenated with the path field from the event payload
-  - "author": the author field from the event payload (may be null)
-```
-
-Before the automation can fire you need to add the webhook URL as an ad-hoc key:
-
-1. Go to **Settings → Keys** and add a key named `NOTIFY_WEBHOOK` with your
-   webhook URL (e.g. a Slack incoming webhook, a generic HTTP endpoint, or any
-   notification service URL).
-2. Optionally set a URL allowlist on the key to restrict which origins it can
-   POST to.
-
-The `web-request` tool resolves `${keys.NOTIFY_WEBHOOK}` server-side before
-sending — the raw URL never appears in the agent's context.
-
-**To target Slack specifically:** set `NOTIFY_WEBHOOK` to your Slack incoming
-webhook URL
-(`https://hooks.slack.com/services/…`). The automation body above already
-produces a payload Slack's incoming webhook accepts via the `text` or `blocks`
-fields — ask the agent to format the body as a Slack message if you want richer
-formatting.
-
-#### Wake the coding agent when feedback targets it
-
-For feedback directed at the coding agent (`resolutionTarget === "agent"`), ask:
-
-> "When a plan comment targets the agent, run my coding agent with the plan
-> excerpt as context."
-
-```yaml
----
-triggerType: event
-event: plan.commented
-condition: "resolutionTarget is agent"
-mode: agentic
-domain: plan
-enabled: true
----
-
-Use the manage-notifications action or web-request tool to alert the coding agent
-that new agent-targeted feedback has arrived on plan ${planId}: "${excerpt}".
-Include the plan path so the agent can navigate directly to it.
-```
-
-Because the automation runs a full agent loop (`mode: agentic`), it can call
-`web-request`, send notifications, or invoke any action the agent has access to.
-The exact delivery mechanism depends on what notification channels you have
-configured — the agent picks the best available one.
-
 ## What's next
 
+- [**Reviewing and Commenting on Plans**](/docs/template-plan-review-workflow) — comment types, resolving feedback, sharing, and deleting plans
+- [**Local-Files Mode and Desktop Sync**](/docs/template-plan-local-and-desktop) — keep plan content off the hosted database, or mirror it to a folder
+- [**Events and Automations**](/docs/template-plan-automations) — the plan event bus and automation recipes
+- [**Extending Plan**](/docs/template-plan-developers) — data model, actions, and custom MDX blocks for forking or self-hosting Plan
 - [**PR Visual Recap**](/docs/pr-visual-recap) — run `/visual-recap` automatically on every pull request
-- [**Automations**](/docs/automations) — event-triggered and scheduled automations
 - [**Plan plugin & marketplace**](/docs/plan-plugin) — install the Plan skills as a Claude Code or Codex plugin
 - [**Skills**](/docs/skills-guide) — how Agent-Native installs skills
 - [**MCP Clients**](/docs/mcp-clients) — configuring hosted MCP connectors