@agent-native/core 0.122.4 → 0.123.1

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(

package/corpus/templates/slides/.agents/skills/actions/SKILL.md

@@ -18,6 +18,8 @@ Actions in `actions/` are the **single source of truth** for app operations. The
 
 Before creating any custom REST/API route for app data, inspect `actions/` and the action table in `AGENTS.md`. If an action already exists, call it directly from the agent or with `useActionQuery` / `useActionMutation` from the UI. If the capability is missing, create or update a `defineAction`. Do not add `/api/*`, `server/routes/*`, or other pass-through endpoints whose main job is to call, repackage, or re-export an action.
 
+**Stop trigger:** the moment you are about to create a file under `server/routes/api/` — or add server middleware to guard one — stop and check it against the exception list in *When You Still Need Custom `/api/` Routes* below. If it is not on that list, write a `defineAction` instead. This applies even when you already started the route; abandoning a half-written action to hand-roll routes is the exact failure this rule exists to prevent.
+
 ## Why
 
 Actions give the agent callable tools with structured input/output, AND they give the frontend a typed client contract through hooks. One implementation serves both the agent and the UI. They keep the agent's chat context clean, they're reusable, and they can be tested independently.
@@ -390,12 +392,28 @@ This is the canonical approach for new apps. Action names must be lowercase with
 
 ## When You Still Need Custom `/api/` Routes
 
-Most operations should be actions. You only need custom routes in `server/routes/api/` for:
+This is the complete exception list. A route in `server/routes/api/` is only
+justified when the caller is not your own UI or agent, or when the payload is
+not JSON:
 
 - **File uploads** — actions receive JSON params, not multipart form data
 - **Streaming responses** — SSE or chunked responses that need direct H3 control
 - **Webhooks** — external services POST to a specific URL
 - **OAuth callbacks** — redirect-based flows that need specific URL patterns
+- **Public unauthenticated endpoints** — SEO/OG images, share links, and other
+  URLs opened directly by a browser or crawler
+- **Binary or non-JSON responses** — media, exports, generated assets
+
+Everything else is an action: CRUD, settings, search, list/detail reads, auth
+state, and anything the UI fetches as JSON. If a route needs new middleware to
+scope it to the current user, that is a signal it should be an action — actions
+already run inside request context with access checks.
+
+Existing first-party templates still contain a shrinking, explicitly
+grandfathered set of older `/api/*` CRUD routes for app data. The repository's
+`guard:no-action-twin-routes` CI check ratchets that baseline down across the
+first-party template route trees (with the separately owned Plan template
+fenced out); it is not a substitute for keeping generated apps action-first.
 
 When the agent needs a durable image or file URL, call the core `upload-image`
 action or use `uploadFile()` in server code. Do not write base64 into SQL,

package/corpus/templates/slides/.agents/skills/deck-management/SKILL.md

@@ -58,10 +58,10 @@ pnpm action get-deck --id=<deckId>
 pnpm action view-screen
 ```
 
-**From the API:**
+**From actions:**
 
-- `GET /api/decks` -- list all decks (returns id, title, slide count, timestamps)
-- `GET /api/decks/:id` -- get a single deck with full data
+- `list-decks` -- list all decks (returns id, title, slide count, timestamps)
+- `get-deck` -- get a single deck with full data
 
 ## Writing Decks
 
@@ -72,11 +72,11 @@ pnpm action view-screen
 pnpm action db-exec --sql "INSERT INTO decks (id, title, data) VALUES (?, ?, ?)" --params '["new-id", "Title", "{...}"]'
 ```
 
-**From the API:**
+**From actions:**
 
-- `POST /api/decks` -- create a new deck
-- `PUT /api/decks/:id` -- update an existing deck
-- `DELETE /api/decks/:id` -- delete a deck
+- `add-deck` -- create a new deck
+- `save-deck` -- replace an authoritative full deck payload
+- `delete-deck` -- delete a deck
 
 ## Important Rules
 

package/corpus/templates/slides/.agents/skills/frontend-design/SKILL.md

@@ -1,14 +1,17 @@
 ---
 name: frontend-design
 description: >-
-  Create distinctive, production-grade frontend interfaces with high design
-  quality. Use when building web components, pages, artifacts, posters, or
-  applications (websites, landing pages, dashboards, React components,
-  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
-  creative, polished UI that avoids generic AI aesthetics.
+  Sets the visual direction for a new or redesigned surface, with production
+  quality that avoids generic AI aesthetics. Use when building a new page,
+  app, or marketing surface, defining visual identity, or doing a design pass
+  ("make this look good"). Do not load it for routine UI edits: adding a field
+  to an existing form, fixing spacing, wiring a button, or changing copy.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+local-changes: >-
+  Description narrowed and Verification rescoped deliberately; an upstream sync
+  must not restore the broad auto-load triggers or screenshot-everything step.
 metadata:
   internal: true
 ---
@@ -141,11 +144,22 @@ Avoid:
 
 ## Verification
 
+Match verification effort to the size of the change. For one component, one
+form, one page, or a restyle, run the app's existing checks — formatter,
+`pnpm typecheck`, existing tests — and stop there.
+
+Escalate to browser verification only when the user asks for it, or when the
+change is a multi-step user-visible flow that cannot be confirmed any other
+way. Never author a new Playwright/Puppeteer script, add a browser-automation
+dependency, or stand up an e2e harness to check work the user did not ask you
+to test that way; use an available browser tool, or say what you could not
+verify.
+
 For substantial frontend work:
 
 1. Run the relevant formatter/checks.
 2. Start the dev server when the app needs one.
-3. Verify with browser screenshots at desktop and mobile widths.
+3. Verify with the available browser tooling at desktop and mobile widths.
 4. Check interactive states: hover, focus, loading, empty, error, and destructive confirmations.
 5. When registering or changing a company adapter, run
    `@agent-native/toolkit/conformance`, including mixed-overlay focus,

package/corpus/templates/slides/.agents/skills/security/SKILL.md

@@ -127,6 +127,8 @@ Two more CI guards (also wired into `pnpm prep`) target the 2026-04 cross-tenant
 - `scripts/guard-no-env-mutation.mjs` — bans `process.env.<KEY> = …` (and bracket / compound forms) anywhere in production code. On serverless, every warm container handles many concurrent requests in one Node process, so `process.env` mutation leaks across in-flight requests (the "restore" line at the end of a handler races and never helps — most recently the Zoom webhook). Use `runWithRequestContext({ userEmail, orgId, timezone }, fn)` from `@agent-native/core/server` instead — it's AsyncLocalStorage-backed and per-request safe. Allowlisted paths: `scripts/`, `*.spec.ts` / `*.test.ts`, `packages/core/src/dev**`, `templates/*/test/`, anything under `/cli/` or `/scaffold/`. Per-line opt-out: `process.env.X = y // guard:allow-env-mutation — <reason>`.
 - `scripts/guard-no-localhost-fallback.mjs` — bans the literal `"local@localhost"` / `'local@localhost'` / `` `local@localhost` `` in production code. The bug class: `getRequestUserEmail() ?? "local@localhost"` silently pools every unauthenticated request into a single shared tenant, leaking credentials, tools, and `application_state` rows between accounts. The right behavior is to throw / 401 when there's no session. Allowlisted paths: the dev-mode auth shim (`packages/core/src/server/auth.ts`), `packages/core/src/dev**`, tests, `scripts/`, `seed/` / `seeds/`, plus a few framework helpers that intentionally inspect or migrate the dev identity. SQL DDL `DEFAULT 'local@localhost'` and the Drizzle helper `.default('local@localhost')` are skipped per-line — schema column defaults are intentional dev fixtures, not the dangerous fallback pattern. Per-line opt-out: `email ?? "local@localhost" // guard:allow-localhost-fallback — <reason>`.
 
+  The same guard also bans the **ambient process identity** as a request-scoped fallback: `?? process.env.AGENT_USER_EMAIL`, `|| process.env.WORKSPACE_OWNER_EMAIL`, and `?? getAmbientUserEmail()`. Those name the identity of the *deployment*, not the caller, so a handler reading one authorizes whoever the deploy env names rather than whoever signed in — it fails open toward more privilege. Exempt paths are the ones with no request by construction: `scripts/` (including `templates/*/scripts/`), `src/cli/`, `src/scripts/`, `script-helpers.ts` / `script-entries.ts`, tests, and seeds. It deliberately matches only the `??` / `||` fallback position, so reading the same env var to build an admin allowlist (`envEmails("WORKSPACE_OWNER_EMAIL").includes(email)`) is untouched. Known gaps, both requiring dataflow analysis the guard does not do: an env read aliased through a local (`const fallback = process.env.AGENT_USER_EMAIL; … ?? fallback`) and a destructured `const { AGENT_USER_EMAIL } = process.env`.
+
 ## Auth
 
 - All actions are protected by the auth guard automatically.

package/corpus/templates/slides/.agents/skills/self-modifying-code/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: self-modifying-code
 description: >-
-  How the agent can modify the app's own source code. Use when the agent needs
-  to edit components, routes, styles, or scripts, when designing UI for agent
-  editability, or when deciding what the agent should and shouldn't modify.
+  Tiers, checkpoints, and off-limits paths for an agent editing the app's own
+  source. Use when designing UI for agent editability, deciding whether a file
+  is safe for the agent to change, or when tempted to patch config, `.env`, or
+  an `@agent-native/*` package. Do not load it for ordinary source edits.
 scope: dev
 metadata:
   internal: true

package/corpus/templates/slides/.agents/skills/shadcn-ui/SKILL.md

@@ -1,11 +1,15 @@
 ---
 name: shadcn-ui
 description: >-
-  Use when adding, updating, debugging, styling, or composing shadcn/ui
-  components, forms, dialogs, menus, charts, sidebars, themes, registries, or
-  any project with a components.json file.
+  The shadcn CLI, component composition, theming, and registry workflow. Use
+  when adding, replacing, upgrading, or debugging a shadcn/ui primitive itself,
+  or when changing a theme or registry. Do not load it for ordinary edits to a
+  file that happens to import a shadcn component.
 scope: dev
 source: https://ui.shadcn.com/docs/skills
+local-changes: >-
+  Description narrowed deliberately; an upstream sync must not restore the
+  "any project with a components.json file" trigger.
 metadata:
   internal: true
 ---