@agent-native/core 0.149.1 → 0.149.3

package/corpus/templates/plan/.agents/skills/actions/references/action-fields.md

@@ -0,0 +1,136 @@
+# Action Field Reference
+
+Full detail on the less-common `defineAction` fields and automatic behaviors.
+Read this when you need output validation, authorization, human approval,
+image results, or the exact rules for the auto-refresh behavior — the happy
+path in SKILL.md doesn't need any of these.
+
+## Screen Refresh (automatic)
+
+The framework auto-refreshes the UI after any successful mutating action. On completion of a non-`GET` action, the framework emits a change event with `source: "action"` that the client's `useDbSync` picks up and uses to invalidate `["action"]` React Query keys — so `list-*` / `get-*` hooks refetch without a full page reload. In-process calls emit directly; dev-mode `pnpm action ...` calls also write a durable marker so the web server sees child-process action changes.
+
+Rules:
+
+- `http: { method: "GET" }` → read-only, does NOT trigger a refresh (inferred automatically).
+- Any other action (default `POST`, `PUT`, `DELETE`, or `http: false`) → treated as mutating, triggers a refresh on success.
+- To override the inference on an unusual action (e.g. a `POST` that only reads), pass `readOnly: true` on the action definition.
+- To let a mutating action run concurrently with other same-turn tool calls, pass `parallelSafe: true`. Only do this when the action is internally concurrency-safe and order-independent (for example, it uses an app-level lock or idempotent upsert semantics). Mutating actions remain serialized by default.
+
+Agents do NOT need to call `refresh-screen` after a normal action — it's already handled. `refresh-screen` is only needed when the agent mutates data via a path the framework can't see (e.g. writing to an external system the app mirrors) or when the agent wants to pass a `scope` hint for narrower invalidation.
+
+## Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
+## Validating Return Values (`outputSchema`)
+
+`schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.
+
+```ts
+export default defineAction({
+  description: "Summarize a thread.",
+  schema: z.object({ threadId: z.string() }),
+  outputSchema: z.object({ summary: z.string(), messageCount: z.number() }),
+  outputErrorStrategy: "warn", // default; "strict" | "fallback"
+  // outputFallback: { summary: "", messageCount: 0 }, // used only by "fallback"
+  run: async ({ threadId }) => {
+    /* ... */
+  },
+});
+```
+
+- `"warn"` (default) — `console.warn` the issues and return the **original** result unchanged. Non-breaking.
+- `"strict"` — throw a clear error so a buggy action surfaces loudly.
+- `"fallback"` — return `outputFallback` in place of the invalid result.
+
+On success the validated value is returned, so coercion/defaults on `outputSchema` apply. Omit `outputSchema` and behavior is byte-for-byte unchanged (no wrapping).
+
+## Authorization (`authorize`)
+
+`authorize` decides whether the caller may run the action at all. It wraps
+`run`, so it holds at **all six dispatch sites** — agent tool, HTTP, frontend
+hook, MCP, A2A, CLI — unlike `needsApproval`, which is honoured only in the
+agent loop. Use `authorize` for "not everyone may do this"; use `needsApproval`
+to ask a human to bless one call a permitted caller is already allowed to make.
+
+```ts
+import { coachAccess } from "../lib/access.js"; // defineAppRoles(...)
+
+export default defineAction({
+  description: "Archive a client roster.",
+  schema: z.object({ id: z.string() }),
+  authorize: coachAccess.requireAny("coach-admin"),
+  run: async (args) => {
+    /* ... */
+  },
+});
+```
+
+The wrappers compose as `validate input -> authorize -> run -> validate output
+-> audit`: the gate sits inside input validation, so a guard reading `args` gets
+the parsed, coerced value, and auditing is outermost, so denials are recorded.
+
+A guard that throws denies with its own message; returning `false` denies
+generically; anything else (including `undefined`) allows. A guarded action
+needs a user identity, so an unattended CLI/cron caller with no user email is
+denied. `authorize` gates the operation; `accessFilter` / `assertAccess` still
+scope which rows a permitted caller may touch. See the `authentication` skill
+for `defineAppRoles` and the `sharing` skill for row scoping.
+
+## Human-in-the-Loop Approval (`needsApproval`)
+
+For high-consequence, outward-facing, hard-to-undo actions (sending an email, charging a card, deleting an account), set `needsApproval` so the agent **cannot** run the action without a human approving the specific call:
+
+```ts
+export default defineAction({
+  description: "Send an email via Gmail.",
+  schema: z.object({ to: z.string(), subject: z.string(), body: z.string() }),
+  needsApproval: true, // boolean, or (args, ctx) => boolean | Promise<boolean>
+  run: async (args) => {
+    /* ...actually send... */
+  },
+});
+```
+
+When the gate is truthy and the call isn't yet approved, the loop emits an `approval_required` event and **stops the turn — `run()` never executes**. A predicate gates conditionally (e.g. only external recipients) and **fails closed**: a throw is treated as "approval required". The human approves via the chat UI's Approve affordance, which re-issues the turn with the call's `approvalKey`, and only then does the action run.
+
+**Keep approvals rare** — the default is off and almost every action should leave it off. The canonical example is Mail's `send-email` (`needsApproval: true`). See the `security` skill and the Human Approval doc.

package/corpus/templates/plan/.agents/skills/actions/references/examples.md

@@ -0,0 +1,94 @@
+# Extra Examples, Legacy Pattern, and the Audit Script
+
+Read this for a second worked example beyond the one in SKILL.md, for the
+older bare-export action format you may find in existing code, or for the
+advisory dead-action audit tool.
+
+## Common Patterns
+
+**Read action (GET):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "List calendar events",
+  schema: z.object({
+    from: z.string().describe("Start date"),
+    to: z.string().describe("End date"),
+  }),
+  http: { method: "GET" },
+  run: async (args) => {
+    return await fetchEvents(args.from, args.to);
+  },
+});
+```
+
+**Write action (POST, default):**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Log a meal",
+  schema: z.object({
+    name: z.string().describe("Meal name"),
+    calories: z.coerce.number().describe("Calorie count"),
+  }),
+  run: async (args) => {
+    // args.calories is a number — z.coerce.number() handles string-to-number conversion from HTTP
+    const meal = await insertMeal(args);
+    return meal;
+  },
+});
+```
+
+**Agent-only action:**
+
+```ts
+import { z } from "zod";
+import { defineAction } from "@agent-native/core/action";
+
+export default defineAction({
+  description: "Navigate the UI to a view",
+  schema: z.object({
+    view: z.string().describe("Target view"),
+  }),
+  http: false,
+  run: async (args) => {
+    await writeAppState("navigate", { command: "go", view: args.view });
+    return "Navigated";
+  },
+});
+```
+
+## Legacy `parameters` Field
+
+Before Standard Schema support, `defineAction` took a plain JSON Schema object via `parameters` instead of a Zod `schema`. It still works — the action is still callable — but skips runtime validation and TypeScript inference. Migrate to `schema: z.object({...})` when you touch one of these.
+
+## Legacy Pattern (bare export)
+
+Older actions use a bare async function export with `parseArgs`:
+
+```ts
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function myAction(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  // ...
+}
+```
+
+This still works but is not auto-exposed as HTTP. Prefer `defineAction` for all new actions.
+
+## Audit Script (Advisory)
+
+`pnpm actions:audit [template ...]` (or `node scripts/audit-template-actions.mjs`) statically scans a template's `actions/` and prints two kinds of suggestions:
+
+1. **Likely UI-dead** — HTTP-exposed mutating actions whose name is never referenced under `app/` (candidates to delete or mark `agentTool: false`).
+2. **Likely redundant clusters** — groups like `update-foo-name` / `update-foo-order` that could collapse into one orthogonal `update-foo`.
+
+It is **advisory only**: it always exits 0, never fails CI, and uses conservative heuristics, so expect some false positives (e.g. an action the agent calls but the UI doesn't). Use it as a prompt to review, not a gate.

package/corpus/templates/plan/.agents/skills/actions/references/provider-apis.md

@@ -0,0 +1,95 @@
+# Provider API Integrations
+
+Read this when an action needs to call an external provider API — HubSpot,
+Gong, Slack, any credentialed third-party service — for ad hoc analysis,
+querying, reporting, or cross-source research.
+
+For provider integrations used in ad hoc analysis, querying, reporting, or
+cross-source research, do not hardcode every provider endpoint as a separate
+rigid action and do not encode one lookback window, filter shape, or pagination
+strategy as the only path the agent can take. Expose the shared provider API
+action trio instead:
+
+- `provider-api-catalog`: lists provider base URLs, auth style, credential keys,
+  docs/spec URLs, placeholders, and examples without exposing secrets.
+- `provider-api-docs`: fetches public provider docs/spec/changelog URLs when
+  the exact endpoint, filter operator, payload shape, or pagination contract is
+  uncertain. Registered docs URLs are curated starting points. Use
+  `responseMode: "markdown"` for clean readable docs, or
+  `responseMode: "matches"` with `search: { query | terms | regex }` for
+  compact snippets instead of flooding context with raw HTML.
+- `provider-api-request`: makes a constrained authenticated HTTP request to the
+  provider host, injects configured credentials, blocks private/internal URLs,
+  and redacts secrets.
+
+Use `@agent-native/core/provider-api` as the shared substrate, and build these
+actions as thin factory imports rather than copying `defineAction` schemas and
+handlers into each template:
+
+```ts
+import {
+  createProviderApiCatalogAction,
+  createProviderApiDocsAction,
+  createProviderApiRequestAction,
+} from "@agent-native/core/provider-api/actions/provider-api";
+import {
+  createDeleteStagedDatasetAction,
+  createListStagedDatasetsAction,
+  createQueryStagedDatasetAction,
+} from "@agent-native/core/provider-api/actions/staged-datasets";
+```
+
+Pass the app's existing provider runtime to the provider factories, and pass
+its app id to the staged-dataset factories. Keep app-specific descriptions,
+provider allow-lists, HTTP/tool-callability settings, and credential adapters
+as factory options. Only add a thin credential adapter when the app has
+app-specific credential lookup rules. If the app stores a built-in provider's
+OAuth grant under a narrower local provider id, use the runtime's
+`oauthProviderOverrides` instead of duplicating provider config. If credentials
+are stored on shareable/resource rows rather than in the shared credential or
+OAuth-token stores, build a resolver that enforces those access checks before
+exposing raw provider requests. Keep `provider-api-request` `http: false`
+unless a separate UI permission model authorizes arbitrary provider writes.
+Specific actions such as `search-records`, `search-emails`, or `sync-source`
+are convenience shortcuts, not capability limits; agents should fall back to
+the provider API trio when a question requires an endpoint or filter that the
+shortcut does not model.
+
+This is a framework tenet. The safety boundary should be provider host
+allow-listing, credential scoping, auth injection, private-network blocking,
+secret redaction, and user/org access checks, not an artificially small set of
+hand-authored read actions. If the upstream provider API supports a capability,
+the agent should normally be able to reach it through `provider-api-request`
+with the user's configured credentials. For large responses, expose staging
+(`stageAs`, `itemsPath`, pagination, and `query-staged-dataset`) or sandboxed
+code execution so the agent can reduce data without flooding context.
+
+For broad provider questions, cross-source joins, corpus-wide mention/search
+work, classification, or any answer where absence matters, design the action
+surface for full coverage instead of convenience-only samples. The agent should
+be able to fetch every relevant page or an explicitly bounded cohort, stage or
+save the raw provider response outside chat, and then use
+`query-staged-dataset`, `run-code`, or provider-side search to count, join,
+grep, classify, and aggregate. Tool descriptions and AGENTS.md guidance should
+teach agents to report source, filters, time window, row/record counts,
+pagination status, truncation, failed pages, and uncovered gaps. They must not
+turn default limits, sampled rows, truncated excerpts, or aborted calls into a
+confident "none found", "all records", or exhaustive conclusion.
+
+For public web pages and docs, prefer the token-efficient path: `web-search`
+to find likely URLs, `web-request` or `provider-api-docs` with clean
+`responseMode` output to read a page, and `run-code` with `webRead()` /
+`webFetch()` when you need to grep, aggregate, or compare many pages before
+returning a small result.
+
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.

package/corpus/templates/plan/.agents/skills/create-skill/SKILL.md

@@ -36,7 +36,6 @@ Before writing the skill, answer these:
    or application state (see the **adding-a-feature** skill). Most skills are
    about how to touch one or more of these correctly.
 3. **When should it trigger?** — Describe the situations in natural language.
-   Be slightly pushy — over-triggering is better than under-triggering.
 4. **Does it involve context awareness?** — Does the agent need to know what the
    user is looking at? If so, reference the `navigation` application-state key and
    the `view-screen` action pattern. See the **context-awareness** skill.
@@ -151,44 +150,21 @@ description: >-
 - Workflow/generator skills: verb-noun (`create-skill`, `capture-learnings`).
 - The directory name must match the `name` in frontmatter.
 
-## Skill Scope (runtime vs dev)
+## Frontmatter Fields
 
-An optional `scope` frontmatter field controls which agent loads the skill:
+| Field         | Required | Value                                         |
+| ------------- | -------- | --------------------------------------------- |
+| `name`        | yes      | Hyphen-case, matches the directory name        |
+| `description` | yes      | What the skill covers AND when it triggers     |
+| `scope`       | no       | `both` (default) \| `runtime` \| `dev`         |
 
-- `both` (default when omitted) — loaded by connected repo agents and the
-  in-app runtime agent. Use for any skill both audiences should follow.
-- `runtime` — loaded only by the in-app runtime agent.
-- `dev` — meant for the human's coding agent (e.g. Claude Code) only. **Excluded
-  from the runtime agent everywhere**: not in the system-prompt skills block and
-  not in `docs-search` results.
-
-Use `scope: dev` for internal-only skills that should guide connected repo
-agents such as Codex or Claude Code, but should not affect the deployed
-production agent. Do not use `metadata.internal` for runtime visibility; that
-field is catalog/package metadata and is intentionally not treated as
-production exclusion.
-
-```markdown
----
-name: release-checklist
-description: >-
-  Steps for cutting a release. Use when preparing or publishing a new version.
-scope: dev
----
-```
-
-Leave `scope` off for normal skills — the default (`both`) keeps them loading at
-runtime, so this is fully backward compatible. To make a dev-only skill visible
-to your coding agent but hidden from the runtime agent, mark it `scope: dev` and
-optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
-`.claude/skills/` independently of the runtime's `.agents/skills/`).
+For how to word a `description` and which `scope` a skill should get, follow
+**writing-agent-instructions** — it owns those rules.
 
 ## Tips
 
-- **Keep descriptions under 40 words** — they load into context on every
-  conversation. State what the skill does AND when to trigger it.
 - **Keep SKILL.md lean (under ~500 lines)** — move detailed content to
-  `references/` files (progressive disclosure).
+  `references/` files.
 - **Use standard markdown headings** — no XML tags or custom formats.
 
 ## Anti-Patterns
@@ -198,8 +174,6 @@ optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
 - **Introducing databases** — data lives in SQL via Drizzle (see **storing-data**).
 - **Ignoring sync** — if a skill creates data, mention wiring `useDbSync` /
   `useActionQuery` so the UI updates (see **real-time-sync**).
-- **Vague descriptions** — "Helps with development" won't trigger. Be specific
-  about _when_.
 - **Pure documentation** — skills should guide action, not just explain concepts.
 
 ## File Structure

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

@@ -1,11 +1,10 @@
 ---
 name: frontend-design
 description: >-
-  Sets the visual direction for a new or redesigned surface, with production
-  quality that avoids generic AI aesthetics. Use when building, redesigning, or
-  cleaning up any user-facing UI, including screenshot-driven feedback, copy or
-  density reduction, settings, control placement, or a design pass ("make this
-  look good"). Do not load it only for purely mechanical wiring or formatting.
+  Sets the visual direction for UI work, avoiding generic AI aesthetics. Use
+  for any user-facing UI change: new surfaces, screenshot-driven feedback,
+  copy/density cleanup, settings, control placement, or a "make this look
+  good" pass. Do not load it only for purely mechanical wiring or formatting.
 scope: dev
 license: Complete terms in LICENSE.txt
 source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md

package/corpus/templates/plan/.agents/skills/turn-into-app/SKILL.md

@@ -151,43 +151,30 @@ Generated apps must follow the shared Agent-Native surface model:
 - Use the right `AgentSidebar` for contextual AI. Every button-triggered
   `sendToAgentChat` handoff should open or focus that sidebar and keep the user
   on the current domain page.
-- Use a sans-first SaaS hierarchy for the app shell. Choose a named visual
-  direction in `DESIGN.md` before styling: product mode, audience, palette
-  family, type treatment, composition, shape language, and anti-references.
-  One restrained editorial cue is welcome, but warm beige plus terracotta is
-  not the default and serif type belongs in content previews or a deliberate
-  brand moment rather than the whole tool.
-- Preserve existing brand tokens. For a new unbranded app, choose a
-  product-fitting palette family and compare sibling apps before reusing their
-  accent. Keep shared semantic tokens and Agent-Native behavior consistent
-  while varying the visual world, density, composition, and shape language.
-- Give the AgentSidebar a subtle surface or divider boundary so it is visually
-  distinct from the domain page without becoming a heavy panel wall.
 - Every AI-labeled button must actually call `sendToAgentChat` with bounded
-  context and `openSidebar: true`. Keep `submit: true` for direct execution and
-  `submit: false` only when the user should edit the staged prompt first. Label
-  deterministic local actions as local, preview, or analyze instead of AI.
-- Standalone apps that render `AgentSidebar` must keep one assistant-ui runtime
-  context. Pin the versions compatible with the installed core/toolkit peer
-  graph, and add Vite dedupe/aliases when linked or transitive packages resolve
-  duplicate assistant-ui modules. Verify a fresh AI handoff has no
-  `AssistantUiStaleIndexErrorBoundary` or stale-index console error.
+  context and `openSidebar: true`. Label deterministic local actions as local,
+  preview, or analyze instead of AI.
+- Never use sparkle, wand, magic, robot, or similar decorative AI icons. Use a
+  message or neutral action icon, or no icon when the button label is enough.
 - Make the left navigation describe domain destinations. Chat is a separate
   destination, not the label for every app page.
 - Start with one primary action and one compact state. Put setup choices,
   advanced inputs, diagnostics, and long explanations behind progressive
   disclosure or later workflow steps.
-- Never use sparkle, wand, magic, robot, or similar decorative AI icons. Use a
-  message or neutral action icon, or no icon when the button label is enough.
-- Before handoff, inspect the first viewport for text density, repeated cards,
-  unrelated forms, and generic helper copy. Remove what the user does not need
-  until the next decision.
-- Run a `distill`, `typeset`, `colorize`, `layout`, `polish`, and `audit` pass
-  as useful named reviews. Make one intervention at a time and commit the
-  chosen direction rather than averaging several options into generic SaaS.
-- For before/after or original/generated review, stack the source first and the
-  result second by default. Reserve side-by-side layouts for short content that
-  remains comfortable to scan at the target width.
+- Choose a named visual direction in `DESIGN.md` before styling and build to it.
+  Preserve existing brand tokens; a new unbranded app picks its own
+  product-fitting palette rather than inheriting a sibling app's accent.
+- Standalone apps that render `AgentSidebar` must keep one assistant-ui runtime
+  context. Pin the versions compatible with the installed core/toolkit peer
+  graph, and add Vite dedupe/aliases when linked or transitive packages resolve
+  duplicate assistant-ui modules. Verify a fresh AI handoff has no
+  `AssistantUiStaleIndexErrorBoundary` or stale-index console error.
+- Before handoff, inspect the first viewport and remove the text density,
+  repeated cards, unrelated forms, and generic helper copy the user does not
+  need until the next decision.
+
+In a local code-agent runtime, read `frontend-design` for the visual direction
+contract, aesthetic guidelines, and named review passes behind these rules.
 
 ## 1. Extract the workflow
 

package/corpus/templates/plan/AGENTS.md

@@ -5,11 +5,6 @@ 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
@@ -20,7 +15,6 @@ generating or editing a plan.
   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.
@@ -31,16 +25,10 @@ generating or editing a plan.
 - `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
 
 - 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`,
@@ -50,8 +38,6 @@ Root skills to read before implementation: `adding-a-feature`, `actions`,
   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.
 - Before edits, read pending feedback with `get-plan-feedback`.
@@ -91,3 +77,8 @@ Root skills to read before implementation: `adding-a-feature`, `actions`,
 | `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 |
+
+## Source Changes
+
+Before building common workspace or agent UI, read `agent-native-toolkit`; read
+`customizing-agent-native` before adapting shared UI.

package/corpus/templates/plan/app/global.css

@@ -2345,6 +2345,7 @@
   box-shadow: none;
   opacity: 0.55;
   pointer-events: none;
+  /* compositing-ok: drag preview — transient, transformed every frame. */
   will-change: transform;
 }
 .notion-drag-preview > * {

package/corpus/templates/plan/changelog/2026-08-10-full-page-chat-now-uses-the-available-width-up-to-1000px-for.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-10
+---
+
+Full-page chat now uses the available width up to 1000px for more comfortable prompts and responses.

package/corpus/templates/plan/changelog/2026-08-11-plan-no-longer-reloads-when-runtime-state-changes.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-11
+---
+
+Plan no longer reloads when runtime state changes

package/corpus/templates/plan/server/ui-plan-html.ts

@@ -766,7 +766,10 @@ button, input, textarea { font: inherit; }
 .canvas-controls button:hover { background: color-mix(in srgb, var(--ink) 8%, transparent); }
 .canvas-viewport { position: absolute; inset: 0; overflow: hidden; cursor: grab; touch-action: none; background-image: linear-gradient(var(--grid-line) 1px, transparent 1px), linear-gradient(90deg, var(--grid-line) 1px, transparent 1px); background-size: var(--grid-size) var(--grid-size); background-position: var(--grid-offset-x) var(--grid-offset-y); }
 .canvas-viewport.is-panning { cursor: grabbing; user-select: none; }
-.board-canvas { position: absolute; left: 0; top: 0; transform-origin: 0 0; will-change: transform; }
+/* No will-change on the pan/zoom canvas: it pins a raster at the scale it was
+   promoted at, so zooming in stretches that texture instead of re-rasterizing
+   and the board stays blurry. A plain 2D transform re-rasterizes crisply. */
+.board-canvas { position: absolute; left: 0; top: 0; transform-origin: 0 0; }
 .board-note, .board-frame, .board-card, .board-group-label, .flow-connector, .canvas-helper-note, .canvas-annotation, .annotation-arrow { position: absolute; }
 .board-note, .board-frame, .board-card, .canvas-helper-note, .canvas-annotation { z-index: 2; color: var(--ink); cursor: default; }
 .board-group-label { z-index: 2; display: flex; align-items: center; color: var(--ink); font: 760 18px/1 var(--doc-font); }

package/corpus/templates/plan/vite.config.ts

@@ -8,6 +8,11 @@ const agentNativePlugins = agentNative as unknown as (
 ) => any[];
 
 export default defineConfig({
+  server: {
+    watch: {
+      ignored: ["**/data/**", "**/plans/**"],
+    },
+  },
   plugins: [
     ...reactRouterPlugins(),
     ...agentNativePlugins({