@agent-native/core 0.122.3 → 0.123.0

package/corpus/templates/plan/.agents/skills/storing-data/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: storing-data
+description: >-
+  How to store application data in agent-native apps. All data lives in SQL.
+  Use when adding data models, deciding where to store data, or reading/writing
+  application data.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Storing Data — SQL is the Source of Truth
+
+## Rule
+
+All application data lives in **SQL** (SQLite locally, persistent database in production). The agent and UI share the same database. SQL stores structured records, metadata, references, and searchable text — not large raw file payloads. Do not store durable app data in the filesystem unless the app is explicitly running a Local File Mode artifact flow described below.
+
+Large binary or file-like payloads (images, video/audio, PDFs, ZIPs, screenshots, session replay chunks, thumbnails, generated assets, `data:` URLs, and base64 file bodies) must go through configured file/blob storage such as `uploadFile()` or `putPrivateBlob()`. Persist only the returned URL, asset id, or opaque blob handle in SQL. If storage is unavailable in hosted or persistent-database mode, fail closed with setup guidance instead of falling back to base64 in `application_state`, `settings`, `resources`, or app tables. Local SQLite-only dev fallbacks may exist for tiny assets, but they must be capped, documented as dev-only, and kept off hot list/read paths.
+
+**Local File Mode exception:** some artifact apps (Content, Plans, Slides, Dashboards, Designs, etc.) can intentionally use repo files as the source of truth for the artifact itself. This must be explicit via `agent-native.json`, `AGENT_NATIVE_MODE=local-files`, or an app-owned local-file action helper. In that mode, the UI and agent still go through app actions, but those actions read/write scoped files through `@agent-native/core/local-artifacts` instead of SQL rows. App state, auth, settings, credentials, collaboration metadata, and hosted database mode remain SQL. File-to-database or file-to-provider synchronization is an explicit sync step, not an implicit side effect of editing.
+
+When you add a data model, a list, or a read path, also follow the `performance` skill: project only the columns a list renders, index the columns hot queries filter/sort on, and avoid query waterfalls — so apps stay fast as data grows.
+
+## How It Works
+
+Agent-native apps use Drizzle ORM over the configured SQL backend. Local development works out of the box with a SQLite file at `data/app.db`; production and shared preview deploys need a persistent `DATABASE_URL` because container/serverless filesystems can reset. The code should behave the same across backends, but the local SQLite file is not durable once deployed.
+
+For app code, use Drizzle's schema/query DSL by default. Raw SQL is an escape hatch for additive migrations, health checks, or one-off maintenance, not the normal way to build features.
+
+### Naming migrations
+
+When you add an entry to a `runMigrations([...])` list (`@agent-native/core/db`), always give it a unique `name:` slug (e.g. `name: "analytics-alert-rules-table"`) alongside its `version`. Never renumber or reuse version numbers on existing entries.
+
+Why: version numbers alone are not a safe identity. Two branches that each independently extend the same migration list can ship different DDL under the same version numbers — whichever branch deploys first "claims" those version numbers in the bookkeeping table, and the other branch's DDL is silently treated as already applied even though it never ran. This exact collision took down analytics: parallel branches both extended their migration list through v75-v83 with different DDL, so `analytics_alert_rules`, `analytics_alert_incidents`, and `session_recordings.network_error_count` never made it to production despite the bookkeeping table showing every version as applied. A `name:` slug is tracked independently of version numbers, so it applies exactly once per database regardless of what any other branch already recorded.
+
+Existing unnamed migrations don't need to be renamed retroactively (the two gating strategies coexist), but any new entry should always carry a name.
+
+### Core SQL Stores (auto-created, available in all templates)
+
+| Store               | Purpose                                              | Access                                     |
+| ------------------- | ---------------------------------------------------- | ------------------------------------------ |
+| `application_state` | Ephemeral UI state (compose windows, navigation)     | `readAppState()` / `writeAppState()`       |
+| `settings`          | Persistent KV config (preferences, app settings)     | `getSetting()` / `putSetting()`            |
+| `oauth_tokens`      | OAuth credentials                                    | `@agent-native/core/oauth-tokens`          |
+| `sessions`          | Auth sessions                                        | `@agent-native/core/server`               |
+
+### Domain Data (per-template)
+
+Define schema with the framework Drizzle helpers in `server/db/schema.ts`. Get a database instance with `const db = getDb()` from `server/db/index.ts`. All queries are async.
+
+```ts
+import { eq } from "drizzle-orm";
+import { table, text, integer, now } from "@agent-native/core/db/schema";
+
+export const tasks = table("tasks", {
+  id: text("id").primaryKey(),
+  title: text("title").notNull(),
+  completed: integer("completed", { mode: "boolean" })
+    .notNull()
+    .default(false),
+  createdAt: text("created_at").notNull().default(now()),
+});
+
+const rows = await db.select().from(tasks).where(eq(tasks.id, taskId));
+```
+
+Never import `sqliteTable` / `pgTable` or column helpers from `drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Use `@agent-native/core/db/schema` so the same schema can run against SQLite, Postgres, libSQL/Turso, D1, and other supported backends.
+
+| Template     | Tables                                        |
+| ------------ | --------------------------------------------- |
+| **Mail**     | emails, labels (+ Gmail API when connected)   |
+| **Calendar** | events, bookings                              |
+| **Forms**    | forms, responses                              |
+| **Content**  | documents                                     |
+| **Slides**   | decks (JSON stored in SQL)                    |
+| **Videos**   | compositions in registry + localStorage       |
+
+### Agent Access
+
+The agent uses app-specific actions to read/write the database. Core DB scripts are for inspection and maintenance, not for implementing normal product behavior:
+
+- `pnpm action db-schema` — Show all tables, columns, types
+- `pnpm action db-query --sql "SELECT * FROM forms"` — Run SELECT queries
+- `pnpm action db-exec --sql "UPDATE ..."` — Last-resort ad-hoc maintenance for short columns, multi-column writes, or computed updates when no domain action exists. For several related writes, prefer `--statements '[{"sql":"...","args":[...]}]'` so they run sequentially in one transaction. Schema changes are blocked; use reviewed additive migrations/startup code instead.
+- `pnpm action db-patch --table <t> --column <c> --where "<clause>" --find "<old>" --replace "<new>"` — **Surgical search/replace on a large text column.** Sends the diff instead of re-transmitting the whole value, so it's dramatically more token-efficient than `db-exec UPDATE` when editing multi-kilobyte documents, slide HTML, dashboard/form JSON, etc. Targets exactly one row per call — narrow `--where` by primary key. Supports `--edits '[{find,replace},...]'` for batch edits and `--all` to replace every occurrence.
+- App-specific actions for domain operations — **always prefer these over raw SQL when one exists.** They encode business rules, power the client action hooks, and for editor-backed tables (documents, slides) also push live Yjs updates to open collaborative editors. `db-patch` is the generic fallback for tables without a dedicated edit action.
+
+**For one-off maintenance, how to choose between `db-exec UPDATE` and `db-patch`:**
+
+| Scenario                                                       | Use          |
+| -------------------------------------------------------------- | ------------ |
+| `SET status = 'published'` on one row                          | `db-exec`    |
+| `SET calories = calories + 50`                                 | `db-exec`    |
+| Updating several columns at once                               | `db-exec`    |
+| Inserting/updating several rows as one logical operation        | `db-exec --statements` |
+| Fixing a typo in a 50KB markdown document's `content` column   | `db-patch`   |
+| Changing a single key in a dashboard's JSON blob               | `db-patch`   |
+| Tweaking one paragraph of slide HTML stored in `decks.data`    | `db-patch`   |
+| Any edit where you'd otherwise re-send thousands of characters | `db-patch`   |
+
+All of these honor the per-user / per-org data scoping — you can't read or write rows outside the current user's data, regardless of which tool you choose.
+
+### Frontend Access
+
+The frontend calls actions using React Query hooks from the client API. The framework owns the HTTP transport behind these hooks, so components should not call action routes with raw `fetch`.
+
+```ts
+import { useActionQuery, useActionMutation } from "@agent-native/core/client/hooks";
+
+// Read data
+const { data } = useActionQuery("list-meals", { date: "2025-01-01" });
+
+// Write data
+const { mutate } = useActionMutation("log-meal");
+```
+
+Actions are the **preferred way** for the frontend to access data. You rarely need custom `/api/` routes — only for file uploads, streaming, webhooks, or OAuth callbacks.
+
+### Production / Cloud Deployment
+
+Local SQLite works out of the box for development. To deploy to production or any environment where data must survive restarts:
+
+1. Set `DATABASE_URL` to a persistent SQL database.
+2. Set `DATABASE_AUTH_TOKEN` only when the provider requires a separate token, such as Turso/libSQL.
+3. No code changes should be needed when the schema and queries stay portable.
+
+Turso is one valid option, not the required option. Common choices include Neon or Supabase Postgres, Turso/libSQL, plain Postgres, durable SQLite, Cloudflare D1 bindings, and managed platform SQL environments when available.
+
+### Real-time Sync
+
+Polling streams database changes to the UI. When the agent writes to the database via scripts, the UI updates automatically via `useDbSync()` which invalidates React Query caches.
+
+## Do
+
+- Use Drizzle ORM for structured domain data (forms, bookings, documents)
+- Use Drizzle query builder methods (`select`, `insert`, `update`, `delete`) and portable operators from `drizzle-orm` (`eq`, `and`, `or`, `inArray`, `desc`, etc.) for app reads/writes
+- Use framework schema helpers from `@agent-native/core/db/schema`, not dialect-specific Drizzle imports
+- Use the `settings` store for app configuration and user preferences
+- Use `application-state` for ephemeral UI state that the agent and UI share
+- Use `oauth-tokens` for OAuth credentials
+- Use `uploadFile()` or `putPrivateBlob()` for large files/blob data and store only URLs, ids, or handles in SQL
+- Use core DB scripts (`db-schema`, `db-query`, `db-exec`, `db-patch`) for ad-hoc database operations
+- Use `db-exec --statements` instead of several separate `db-exec` calls for related writes; it is faster and rolls back the whole batch if one statement fails
+- Reach for `db-patch` instead of `db-exec UPDATE` whenever you're making a small change to a large text/JSON column — it's much cheaper on tokens
+
+## Don't
+
+- Don't store structured app data as JSON files
+- Don't store app state in localStorage, sessionStorage, or cookies (except for UI-only preferences like sidebar width)
+- Don't keep state only in memory (server variables, global stores)
+- Don't use Redis or any external state store for app data
+- Don't store large files, base64 blobs, `data:` URLs, screenshots, videos, audio, PDFs, ZIPs, or session replay chunks directly in SQL rows, `application_state`, `settings`, or `resources`
+- Don't implement product features with raw SQL or `getDbExec()` when Drizzle can express the query
+- Don't write SQLite-only or Postgres-only SQL in app code
+- Don't interpolate user input directly into SQL queries — use Drizzle ORM's query builder
+
+## Security
+
+- **SQL injection** — Use Drizzle ORM's query builder, never raw string interpolation for SQL queries
+- **Validate before writing** — Check data shape before writing, especially for user-submitted data
+
+## Application State and Context Awareness
+
+When storing app-state, include **navigation state** — the agent needs to know what the user is looking at. The `application_state` table holds ephemeral UI state that both the agent and UI share. Key patterns:
+
+- **`navigation` key** — the UI writes current view and selection on every route change. The agent reads this before acting.
+- **`navigate` key** — the agent writes one-shot commands to navigate the UI. The UI processes and deletes them.
+- **Domain-specific keys** (e.g., `compose-{id}`) — bidirectional state for features like email drafts.
+
+When adding a new data model or feature, also consider what navigation and selection state needs to be exposed via application-state. See the **context-awareness** skill for the full pattern.
+
+## Related Skills
+
+- **context-awareness** — How to expose navigation and selection state via application-state
+- **real-time-sync** — Set up polling so the UI updates when the database changes
+- **actions** — Create actions with `defineAction` to query the database
+- **client-methods** — Keep route details behind named client helpers/hooks
+- **self-modifying-code** — The agent can also modify the app's source code

package/corpus/templates/plan/AGENTS.md

@@ -1,325 +1,93 @@
 # Agent-Native Plan — Agent Guide
 
 Agent-Native Plan is a local-first structured visual plan mode for coding
-agents. Its job is to turn agent plans into editable rich blocks, diagrams,
-wireframes, prototype options, annotations, and comments that a person can
-review before code changes happen.
+agents: it turns agent plans into editable rich blocks, diagrams, wireframes,
+prototype options, annotations, and comments a person reviews before code
+changes happen.
 
 Before building common workspace or agent UI, read `agent-native-toolkit` to
 inventory existing public kits and installed package seams. Use
 `customizing-agent-native` for the configure → compose → eject → propose seam
 ladder.
 
+## Skills
+
+The plan skills own all planning behavior. Read the matching SKILL.md before
+generating or editing a plan.
+
+- `visual-plan` — `/visual-plan`, the canonical slash command for any rich plan;
+  also governs `create-ui-plan`, `create-prototype-plan`, `create-plan-design`,
+  and `create-visual-questions`.
+- `visual-recap` — `/visual-recap`, visual code-review recaps for PRs, commits,
+  branches, and git diffs.
+- `visualize-repo` — repo-native visual docs from local plan folders.
+- `plan-authoring-flow` — command/action routing and design fidelity.
+- `plan-hosted-writes` — session, revision guard, post-write verify.
+- `plan-comments-and-feedback` — feedback fields, anchors, replies, deletion.
+- `plan-browser-editing` — inline prose, design element, branding edits.
+- `plan-source-sync` — plan MDX export/import/patch and local plan folders.
+- `plan-version-history` — snapshots and restore.
+- `plan-local-codebase-chat` — questions about a linked local codebase.
+- `plan-review-recaps` — recap comparison blocks and PR recap CI.
+- `plan-events` — plan lifecycle events and automations.
+
+Root skills to read before implementation: `adding-a-feature`, `actions`,
+`storing-data`, `real-time-sync`, `security`, `delegate-to-agent`,
+`frontend-design`, `shadcn-ui`, `self-modifying-code`.
+
 ## Core Rules
 
-- Store large file/blob payloads in configured file/blob storage, not SQL: no
-  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
-  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
-  or `resources`; persist URLs, ids, or handles instead.
-- Never hardcode API keys, tokens, webhook URLs, signing secrets, private Builder/internal data, customer data, or credential-looking literals. Use secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Follow the root framework rules: data in SQL, actions first, application
   state for navigation/selection, and shared agent chat for AI work.
 - Use actions for app operations and keep frontend/API parity.
 - Keep database code provider-agnostic and additive.
+- Store large file/blob payloads in configured file/blob storage, not SQL: no
+  base64, `data:` URLs, images, video/audio, PDFs, ZIPs, screenshots,
+  thumbnails, or replay chunks in app tables, `application_state`, `settings`,
+  or `resources`; persist URLs, ids, or handles instead.
+- Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+  Builder/internal data, customer data, or credential-looking literals. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
 - Use `view-screen` or application state when the active page/selection is
   unclear.
 - For new features, update UI, actions, skills/instructions, and application
   state when applicable.
 - Default to structured visual artifacts over long Markdown. Text is one block
   type, not the whole plan.
-- Current app actions require a real user session so plans stay scoped and
-  shareable. Local development can use the framework's auto-created dev account;
-  hosted persistence, private sharing, reviewer links, and cross-device/team
-  workflows use account login, with Google sign-in shown when the standard
-  Google OAuth env vars are configured.
-- Runtime plan content is normalized JSON in SQL. MDX is the source-control
-  surface: `plan.mdx` for frontmatter plus markdown/document blocks,
-  `prototype.mdx` for optional Prototype/PrototypeScreen/PrototypeTransition
-  markup, `canvas.mdx` for optional DesignBoard/Section/Artboard/Screen/
-  Annotation/Connector markup, optional `assets/`, and optional
-  `.plan-state.json`.
-- New canvas wireframes must use `<Screen html={...} />` / `data.html`
-  semantic HTML. Nested kit-tree nodes such as `FrameScreen`, `Card`, `Row`, and
-  `Btn` are legacy compatibility only and should not be authored for new
-  plans/recaps.
-- Surface material assumptions only when they change behavior, data, security,
-  tests, deployment, or definition of done.
 - Before edits, read pending feedback with `get-plan-feedback`.
-- Before any destructive hosted-plan write (`replace-blocks`, a top-level
-  `content` replacement, or a source `replace-file`), call `get-visual-plan`
-  immediately before the write and pass its `plan.updatedAt` as
-  `expectedUpdatedAt`. Never reuse a revision from an earlier read. Prefer
-  targeted content or source patches whenever they can express the edit.
-- After every hosted-plan write, call `get-visual-plan` again and verify the
-  persisted text, blocks, canvas, and prototype before claiming success. If the
-  write addressed agent-targeted feedback, call `resolve-plan-comment` and
-  `consume-plan-feedback` only after this verification; addressed feedback must
-  be both resolved and consumed so it neither remains visibly open nor returns
-  as pending work.
+- Read `plan-hosted-writes` before any hosted plan write: writes need a real
+  user session, destructive writes need a fresh `expectedUpdatedAt`, and every
+  write must be verified by a re-read before you claim success.
+- Runtime plan content is normalized JSON in SQL; MDX (`plan.mdx`,
+  `canvas.mdx`, `prototype.mdx`) is the source-control surface — see
+  `plan-source-sync`.
+- New canvas wireframes use `<Screen html={...} />` semantic HTML; nested
+  kit-tree nodes are legacy only — see `plan-authoring-flow`.
 
 ## Application State
 
 - `navigation.view` is `chat`, `plans`, `plan`, `extensions`, or `team`.
 - `navigation.planId` identifies the active visual plan when present.
-- `local-codebase` is written by the Ask Plan browser folder picker when a user
-  links a local codebase. It includes the selected folder name plus personal
-  resource paths for the latest code index, file tree, and captured source
-  snapshots.
+- `local-codebase` holds the folder the Ask Plan picker linked plus personal
+  resource paths for its index, file tree, and snapshots — see
+  `plan-local-codebase-chat`.
 - `navigate` moves the UI to the plan list or a specific visual plan.
-- The sidebar brand header has a `Customize branding` popover. Treat it as a
-  source-code request, not plan data: local Code mode edits `templates/plan`
-  source directly, while hosted/live surfaces route people to Desktop or
-  Builder for code customization.
-
-## Normal Planning Flow
-
-`/visual-plan` is the main command. Treat it like the host agent's standard
-planning mode: inspect the codebase, use parallel agents when useful, gather the
-information needed, ask clarifying questions through the host's native
-ask-user-question tools when needed, then call `create-visual-plan` to publish
-the plan. When the user pasted, referenced, or already has a Codex / Claude Code
-/ Markdown plan, keep `/visual-plan` as the command and pass the source text to
-`create-visual-plan` as `planText` so the new review surface builds from what
-they already have.
-
-For UI-first work where the plan leads with product screens, use `/visual-plan`
-and call `create-ui-plan`.
-
-For prototype-first work — when the user needs to operate the behavior before
-implementation — use `/visual-plan` and call `create-prototype-plan`. Prototype
-plans must be functional review surfaces with local state and realistic controls;
-do not pass off static screen-to-screen navigation as a prototype. Keep static
-mocks in the document and use the top viewer for functional review, comments,
-rough/clean mode, dark/light mode, and prototype popout.
-(`create-prototype-plan` is an MCP tool reached from `/visual-plan`, not a
-separate slash command.)
-
-For full-fidelity branded UI design before implementation, use `/visual-plan` and
-call `create-plan-design`. Research the real app shell, `design.md` if present,
-`.fig` brand-kit/design-system data when available, and codebase CSS/Tailwind/
-token signals. Pass high-fidelity bounded HTML/CSS screens for the Design tab,
-stable `data-design-id` attributes for targeted element style edits, and
-transitions only when a matching Prototype tab should be clickable. Treat the
-Design tab as the visual source of truth and the Prototype tab as the same
-direction made interactive. (`create-plan-design` is an MCP tool reached from
-`/visual-plan`, not a separate slash command.)
-
-Treat “higher fidelity,” “pixel-accurate,” “polished mockup,” “production-like,”
-“real design,” and “not a sketch/wireframe” as design-first requests, even when
-the prompt also says “mockup.” For an existing plan, do not create a duplicate:
-call `update-visual-plan` on the same plan id with a
-`set-visual-render-mode` patch using `renderMode: "design"`, and replace or patch
-the affected screen HTML/CSS in the same update. Put scoped styles in each
-screen's `css` field, never in `<style>` tags. Merely switching the viewer-local
-Clean toggle removes rough.js for one browser but does not create a high-fidelity
-artifact.
-
-Use `/visual-recap` when the user wants a high-level review surface for a PR,
-commit, branch, or git diff that already changed. Recaps are reverse plans:
-derive blocks from the real diff, call `create-visual-recap` with the recap
-MDX source, publish it as a review aid, and state that reviewers still need to
-inspect the actual changed lines.
-
-The markdown/document portion should stay close to the plan the agent would
-normally produce. Diagrams, wireframes, mockups, annotations, and an optional
-bottom `question-form` Open Questions block are additive review aids, not a
-separate intake flow.
-
-Do not automatically call `create-visual-questions` from `/visual-plan`. If a
-normal plan has answerable unresolved decisions, keep them in the same plan as a
-bottom `question-form` block with single-choice, multi-choice, or freeform
-questions, recommended options when useful, and wireframe/diagram previews for
-visual directions. If the user explicitly requests a visual intake questionnaire
-before planning, call `create-visual-questions` from `/visual-plan`.
-(`create-visual-questions` is an MCP tool reached from `/visual-plan`, not a
-separate slash command.)
-
-## Skills
-
-The plan skills own all planning behavior. Read the matching SKILL.md before
-generating or editing a plan — they carry the shared Wireframe & Canvas and
-Document Quality cores, so do not restate those rules here.
-
-- `.agents/skills/visual-plan/SKILL.md` — `/visual-plan`, the canonical slash
-  command for any rich plan; also governs the MCP-tool modes: UI-first
-  (`create-ui-plan`), prototype-first (`create-prototype-plan`), design-first
-  (`create-plan-design`), and visual-intake (`create-visual-questions`).
-- `.agents/skills/visual-recap/SKILL.md` — `/visual-recap`, high-level visual
-  code-review recaps for PRs, commits, branches, and git diffs.
-
-When the user critiques a plan's look or structure, fix the renderer or the
-sync-guarded skills (not just one stored plan) so the improvement sticks.
-
-## Review Recaps
-
-- `columns` is the generic before/after layout primitive for structured
-  comparisons. Use it for side-by-side schema, API, prose, and model blocks.
-- The PR Visual Recap GitHub Action runs the `visual-recap` skill on each PR via
-  an LLM coding agent (Claude Code or Codex, chosen with `VISUAL_RECAP_AGENT`;
-  model and reasoning depth via `VISUAL_RECAP_MODEL` / `VISUAL_RECAP_REASONING`)
-  when `PLAN_RECAP_TOKEN` and the backend's API key are configured, shows a
-  non-required `Visual Recap` check while it runs, then posts a sticky comment
-  with an inline screenshot. The recap is informational and must not imply the
-  diff has been reviewed.
-
-## Local Codebase Chat
-
-- The Ask Plan page can link a browser-selected local codebase folder. The UI
-  indexes safe text files, skips generated/secret-looking paths, writes a small
-  personal instruction resource under `instructions/local-codebases/`, and
-  stores captured file snapshots under `codebases/<id>/snapshots/<timestamp>/`.
-- For live codebase questions, call `view-screen` when context is unclear and
-  inspect `localCodebase`. First read its `indexPath` with the `resources` tool
-  using `scope: "personal"`, then read relevant captured file `resourcePath`s
-  before making claims. Do not infer API contracts, schema shape, or UI behavior
-  from file names alone.
-- If the file needed to answer is absent or skipped, ask the user to sync again
-  or attach the file instead of guessing.
-- For API/schema/UI visualization from a local codebase, call
-  `get-plan-blocks` or `list-plan-components` before `visual-answer`, then
-  publish blocks such as `openapi-spec`, `api-endpoint`, `data-model`,
-  `diagram`, `file-tree`, `tabs`, and `annotated-code` grounded in the files
-  you read.
-
-## Source Sync
-
-- Use `export-visual-plan` or `read-visual-plan-source` when a user or external
-  agent wants plan files to check into a repo.
-- Use `get-local-plan-folder` to read a DB-free local MDX folder from
-  `PLAN_LOCAL_DIR` or from a repo-relative `path`, and
-  `update-local-plan-folder` to apply structured `contentPatches` back to that
-  same folder. Pass `path` whenever the user is viewing a
-  `/local-plans/:slug?path=...` URL. These local-folder actions do not read or
-  write SQL.
-- Use `update-local-plan-comments` to add, reply to, resolve, or delete review
-  comments on a local plan. They persist to a `comments.json` sidecar beside
-  `plan.mdx` (committed with the plan, no SQL), are always addressed to the
-  agent (`resolutionTarget: "agent"`), and are surfaced by `get-local-plan-folder`.
-  Local comments are a one-way handoff to the coding agent — delivery is the
-  composer's "Send to agent" copy-to-clipboard, not notifications or sharing.
-  In bridge mode the read-only bridge serves no comments, so the colocated
-  folder's `comments.json` is merged in for display and persistence.
-- Use `promote-local-plan-folder` when a temporary local plan should be saved
-  into the repo. Its default target is `apps.plan.roots[0].path/<slug>` from
-  `agent-native.json`, falling back to `plans/<slug>`.
-- Commit `.plan-state.json` with repo-backed plan folders when present. It is
-  source metadata for stable bare-Markdown block IDs, not a disposable preview
-  cache.
-- Use `import-visual-plan-source` to create or replace a plan from an MDX folder.
-- Use `patch-visual-plan-source` for small source edits by stable semantic IDs.
-  It patches the MDX AST, runs formatting, parses back to normalized JSON, and
-  persists the runtime model. Prefer this over regenerating a whole plan when the
-  requested change is a few lines, one annotation, one artboard, or one
-  wireframe node.
-- `replace-file` is a destructive source operation. Use it only when targeted
-  source patches cannot express the edit, after a fresh `get-visual-plan`, and
-  pass that read's `plan.updatedAt` as `expectedUpdatedAt`. Re-read the plan
-  after the patch and verify that unrelated MDX files and visual surfaces were
-  preserved.
-- In Agent Native Desktop, the Plan menu can link a user-chosen local folder for
-  the current plan, write the exported MDX files to it, import local edits back
-  through `import-visual-plan-source`, and optionally auto-export whenever the
-  hosted plan changes. This is a native desktop bridge; it does not require a
-  cloned Plan app or CLI process.
-- Do not fork the vocabulary. MDX components must map to the same runtime terms:
-  `DesignBoard`, `Section`, `Artboard`, `Screen`, `Annotation`, `Connector`, and
-  the wireframe kit primitives from `shared/plan-content.ts`.
-
-## Version History
-
-- Plans keep DB-backed snapshots before meaningful authoring changes. Pure
-  comments, feedback replies, and comment status changes do not create history
-  snapshots.
-- Use `list-plan-versions` to see saved snapshots for a plan, and
-  `get-plan-version` to inspect one full snapshot before recommending a
-  rollback.
-- Use `restore-plan-version` only when the user asks to restore or roll back.
-  The current plan is snapshotted first with `Before restore`, so restore is
-  reversible. Restore preserves sharing, ownership, hosted publish metadata,
-  comments, and activity history; it restores the plan's authoring content and
-  legacy sections.
-
-## Browser Editing
-
-- Prose in `rich-text` blocks is edited inline with the shared
-  `RichMarkdownEditor`, autosaved through `update-visual-plan` with
-  `contentPatches: [{ op: "update-rich-text", blockId, markdown }]`.
-- Local `/local-plans/:slug` folders opened from `PLAN_LOCAL_DIR` or a
-  repo-relative `?path=...` use the same Notion-style browser editor, but
-  autosave through `update-local-plan-folder` so changes are written to
-  `plan.mdx`, `canvas.mdx`, and `prototype.mdx` without touching the Plan
-  database.
-- Review annotation mode makes prose temporarily read-only so clicks can pin
-  feedback. Leaving review mode restores inline prose editing.
-- Canvas, artboard, wireframe, diagram, and custom visual edits remain driven by
-  comments, source patches, or structured content patches rather than direct
-  rich-text editing.
-- Design-mode artboards can be element-edited with `update-visual-plan`
-  `contentPatches: [{ op: "update-design-element-style", frameId, blockId,
-elementId, styles }]`. Elements must have `data-design-id` or
-  `data-plan-design-id`; use `patch-wireframe-html` / `patch-prototype-html` for
-  structural or text changes.
-- Plan comments include reviewer identity, @mentions, resolver intent
-  (`agent` or `human`), exact anchors, and design-review threads. When adding
-  human feedback through `update-visual-plan`, preserve `authorEmail` and
-  `authorName` when known; pass `parentCommentId` to reply inline to an
-  existing comment thread. Text feedback should anchor to the nearest prose
-  block, and visual/canvas feedback should include target coordinates plus
-  concise surrounding context.
-- Use `delete-plan-comment` only when the user explicitly asks to remove a
-  comment, undo an accidental comment, or clean up an obsolete thread. Deleting
-  is a soft delete: normal comment views hide the comment while the database row
-  remains for audit/debugging. Deleting a thread root also deletes its replies.
-  When feedback has merely been handled, prefer `resolve-plan-comment` and
-  `consume-plan-feedback` so review history remains visible.
-- Use `delete-visual-plan` only when the owner explicitly asks to delete or
-  restore their hosted plan/recap data. `mode=soft` moves the resource to the
-  Deleted tab and makes normal reads/direct links stop working; `mode=restore`
-  undeletes it; `mode=hard` permanently removes the plan row plus plan-scoped
-  comments, sections, events, versions, shares, reports, SQL asset records, and
-  collab snapshots. Hard delete requires the exact confirmation phrase
-  `DELETE <planId>`.
-- `get-plan-feedback` returns flat comments, grouped threads, anchor summaries,
-  detailed anchor lines, and recent review events that describe the edit/comment
-  delta. Use those fields before changing code or updating the plan, especially
-  to distinguish comments the agent should act on from comments intended for a
-  human reviewer.
-- **Anchor interpretation.** `targetX`/`targetY` are percentages within the
-  named element; bare `x`/`y` are percentages of the whole document;
-  `canvasX`/`canvasY` are board-world pixels. Wireframe anchors carry
-  `targetNodeId`/`targetNodePath` — prefer those over raw coordinates; fall back
-  to coordinates plus the focused screenshot only when no node id is present.
-  Resolve `textQuote` with `contextBefore`/`contextAfter`; if `ambiguous: true`,
-  ask the user. Threads in `detachedThreads` no longer match current prose —
-  reconcile, never drop. Act on `resolutionTarget=agent`; treat `human` as
-  context only; `@mentions` are notification signals, not routing. Mark ingested
-  comments consumed (`consumedCommentIds`); set `status=resolved` only on
-  agent-targeted comments you actually addressed. When a plan write addresses
-  feedback, do not resolve or consume it until a post-write `get-visual-plan`
-  confirms the requested change persisted. Then do both: call
-  `resolve-plan-comment` for the addressed thread and `consume-plan-feedback`
-  for its comments.
-- New human comments send best-effort transactional email when email is
-  configured: root comments and replies notify the plan owner, @mentioned
-  members, and replies also notify prior human participants in that thread.
-  Reuse the shared `renderEmail` template; do not invent a separate
-  plan-specific email style.
-- `report-visual-plan` records a bounded abuse report for a public plan or recap
-  without changing plan content. It requires the caller to be scoped to an
-  accessible public plan, accepts a fixed reason plus optional short details,
-  and updates an existing open report from the same reporter instead of creating
-  duplicate rows.
-
-## Events
-
-The plan app emits four events on the framework event bus: `plan.created`,
-`plan.commented`, `plan.published`, and `plan.status.changed`. Automations can
-subscribe to any of them — if a user asks to "notify me when someone comments"
-or similar, call `manage-automations` with `action=define` (trigger `plan.commented`,
-optional condition on `resolutionTarget`) rather than writing bespoke integration
-code. See the `automations` skill and the [Visual Plans events docs](/docs/template-plan#events)
-for payload schemas and recipe examples.
 
-Read the relevant root skill before implementation: `adding-a-feature`,
-`actions`, `storing-data`, `real-time-sync`, `security`, `delegate-to-agent`,
-`frontend-design`, `shadcn-ui`, and `self-modifying-code`.
+## Actions
+
+| Action | Purpose |
+| --- | --- |
+| `view-screen`, `navigate` | Read the screen; move the UI |
+| `list-visual-plans`, `get-visual-plan`, `show-visual-plan` | List, read, render plans |
+| `create-visual-plan`, `create-ui-plan`, `create-prototype-plan`, `create-plan-design`, `create-visual-questions` | Create a plan per mode; one call per plan |
+| `create-visual-recap`, `search-pr-recaps` | Create and find recaps |
+| `visualize-plan`, `convert-visual-plan-to-prototype` | Convert pasted plans; legacy mock→prototype |
+| `update-visual-plan` | Patch blocks, screens, fidelity, comments, status |
+| `get-plan-blocks`, `list-plan-components`, `visual-answer` | Block schemas, components, visual answers |
+| `publish-visual-plan`, `export-visual-plan` | Share hosted; export HTML/MD/JSON/MDX |
+| `get-plan-access-status`, `request-plan-access` | Check or request access |
+| `get-plan-feedback`, `consume-plan-feedback`, `resolve-plan-comment`, `reply-to-plan-comment`, `delete-plan-comment` | Read, consume, resolve, reply, delete feedback |
+| `list-plan-versions`, `get-plan-version`, `restore-plan-version` | List, inspect, restore snapshots |
+| `read-visual-plan-source`, `import-visual-plan-source`, `patch-visual-plan-source` | Read, replace, patch MDX source |
+| `get-local-plan-folder`, `update-local-plan-folder`, `update-local-plan-comments`, `promote-local-plan-folder`, `validate-local-plan-source` | DB-free local plan folders |
+| `delete-visual-plan`, `report-visual-plan` | Delete/restore; report abuse |

package/corpus/templates/plan/app/components/layout/Sidebar.tsx

@@ -6,14 +6,17 @@ import {
   type ChatThreadSummary,
 } from "@agent-native/core/client/agent-chat";
 import { useCodeMode } from "@agent-native/core/client/agent-chat";
-import { agentNativePath, appPath } from "@agent-native/core/client/api-path";
+import { appPath } from "@agent-native/core/client/api-path";
 import { PromptComposer } from "@agent-native/core/client/composer";
 import { DevDatabaseLink } from "@agent-native/core/client/db-admin";
 import { useSession } from "@agent-native/core/client/hooks";
 import { LanguagePicker, useT } from "@agent-native/core/client/i18n";
 import { openCommandMenu } from "@agent-native/core/client/navigation";
 import { OrgSwitcher } from "@agent-native/core/client/org";
-import { FeedbackButton } from "@agent-native/core/client/ui";
+import {
+  buildSignInReturnHref,
+  FeedbackButton,
+} from "@agent-native/core/client/ui";
 import { SidebarFooterActions } from "@agent-native/toolkit/app-shell";
 import {
   ChatHistoryRail,
@@ -288,15 +291,13 @@ function PlanChatsSection({
 }
 
 function signInForPlanCreate() {
-  window.location.href = `${agentNativePath(
-    "/_agent-native/sign-in",
-  )}?return=${encodeURIComponent("/plans?create=1")}`;
+  window.location.href = buildSignInReturnHref({
+    returnTo: "/plans?create=1",
+  });
 }
 
 function signInWithReturnPath(returnPath: string) {
-  window.location.href = `${agentNativePath(
-    "/_agent-native/sign-in",
-  )}?return=${encodeURIComponent(returnPath || "/")}`;
+  window.location.href = buildSignInReturnHref({ returnTo: returnPath });
 }
 
 function PlansSidebarSection({ collapsed }: { collapsed: boolean }) {

package/corpus/templates/plan/app/pages/PlansPage.tsx

@@ -19,6 +19,7 @@ import {
 } from "@agent-native/core/client/org";
 import { ShareButton } from "@agent-native/core/client/sharing";
 import {
+  buildSignInReturnHref,
   ErrorReportActions,
   type ErrorReportDebugItem,
 } from "@agent-native/core/client/ui";
@@ -2151,11 +2152,9 @@ export function PlansPage({ localPlanSlug }: { localPlanSlug?: string } = {}) {
   );
   // Redirect to sign-in, returning to wherever the guest currently is.
   const openSignIn = useCallback((returnOverride?: string) => {
-    const returnPath =
-      returnOverride ?? planReturnPathFromLocation(window.location);
-    window.location.href = `${agentNativePath(
-      "/_agent-native/sign-in",
-    )}?return=${encodeURIComponent(returnPath)}`;
+    window.location.href = buildSignInReturnHref({
+      returnTo: returnOverride ?? planReturnPathFromLocation(window.location),
+    });
   }, []);
   const requestCreatePlan = useCallback(() => {
     if (sessionLoading) return;
@@ -6156,11 +6155,7 @@ function PlanShareControl({
   }, [planId]);
 
   const openAuthFlow = useCallback((authUrl?: string) => {
-    const returnPath = `${window.location.pathname}${window.location.search}`;
-    const target =
-      authUrl ||
-      `${agentNativePath("/_agent-native/sign-in")}?return=${encodeURIComponent(returnPath)}`;
-    window.location.href = target;
+    window.location.href = authUrl || buildSignInReturnHref();
   }, []);
 
   const copyPublishedUrl = useCallback(