@agent-native/core 0.122.4 → 0.123.1

package/src/templates/workspace-core/.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/src/templates/workspace-core/.agents/skills/adding-a-feature/SKILL.md

@@ -14,6 +14,8 @@ metadata:
 
 Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
 
+Scope check first: this is the checklist for a feature that adds app data or a new capability. A restyle, a copy change, or a screen with no new data model and no new agent-visible operation only needs the areas it actually touches — do not manufacture actions, state keys, or a skill for it.
+
 ## Why
 
 Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.

package/src/templates/workspace-core/.agents/skills/adding-workspace-apps/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: adding-workspace-apps
+description: >-
+  How to add an app to an Agent Native workspace: classifying an "agent"
+  request, scaffolding `apps/<app-name>`, app discovery and descriptions,
+  mounting and base paths, action-first data, and finishing a chat-template app.
+  Use when asked to create, build, scaffold, or generate a new agent or app in a
+  workspace.
+---
+
+# Adding Workspace Apps
+
+## Classify The Ask First
+
+When a user asks from Dispatch chat or through `@agent-native` in Slack or
+Telegram to create, build, make, scaffold, or generate an "agent", classify
+the ask first.
+Simple Dispatch-native behavior such as a reminder, digest, monitor, routing
+rule, saved instruction, or recurring workflow can stay in Dispatch as a
+recurring job/resource/destination. Robust unique products or teammates that
+need their own UI, data model, actions, integrations, or domain workflow should
+become a separate workspace app under `apps/<app-name>`, mounted at
+`/<app-name>`.
+
+## Where The App Lives
+
+Do not implement a new app by adding a route, page, component, or file to
+`apps/chat` or another existing app unless the user explicitly asks to modify
+that existing app.
+
+## Vault Access
+
+Dispatch vault access is workspace-wide by default: every saved vault key is
+available to every workspace app. Only create or request per-app vault grants
+when Dispatch's vault access setting is switched to manual mode.
+
+## Discovery, Links, And The UI Stack
+
+Workspace apps are discovered from `apps/<app-name>/package.json`. There is no
+separate workspace app registry to edit for Dispatch to list the app. Always
+save a concise, human-readable `description` there; Dispatch lists and A2A
+connected-agent context use the app name plus description so agents know what
+the app does. Use relative workspace links like `/<app-name>` and never
+hardcode `localhost`, `127.0.0.1`, `8080`, `8100`, or any dev port in app
+cards, instructions, redirects, or navigation; the active workspace
+gateway/browser origin owns the port. React Router apps must preserve
+`APP_BASE_PATH` / `VITE_APP_BASE_PATH` in
+`app/entry.client.tsx` via `appBasePath()` so the app hydrates correctly when
+mounted at `/<app-name>`. Use the framework/template UI stack for standard UI:
+shadcn/ui components and `@tabler/icons-react`. Do not add `lucide-react` or
+another icon library. Read `.agents/skills/shadcn-ui/SKILL.md` before adding,
+updating, or debugging shadcn components.
+
+## App Data Goes Through Actions
+
+Normal app data must flow through actions. For CRUD that the agent can perform,
+create `defineAction` files in `actions/`, mark reads with
+`http: { method: "GET" }`, and call them from React with `useActionQuery` /
+`useActionMutation`. Do not add duplicate JSON CRUD routes under `/api/*` for
+the same data unless the route is for uploads, streaming, webhooks, OAuth, or
+another route-only concern. Do not add routes whose main job is to wrap,
+proxy, or re-export an action; the action endpoint already exists at
+`/_agent-native/actions/:name`. Action-backed UI is what makes agent-created or
+agent-edited records appear without a manual refresh.
+
+## Database Portability
+
+App database code must be provider-agnostic. Define schemas with
+`@agent-native/core/db/schema` helpers and write app reads/writes with Drizzle's
+query builder and portable `drizzle-orm` operators. Do not import from
+`drizzle-orm/sqlite-core` or `drizzle-orm/pg-core` in app templates. Keep raw SQL
+for additive migrations, health checks, or carefully scoped maintenance, and
+never write SQLite-only or Postgres-only product code. Do not use SQL as object
+storage; file bytes belong in upload/private-blob providers with only references
+saved to app tables.
+
+## Scaffolding
+
+In local development, run
+`pnpm exec agent-native create <app-name> --template=<template>` from the
+workspace root. In production, Dispatch posts new-app requests to Builder
+branch creation; Builder should still scaffold the separate workspace app. The
+workspace dev gateway (`pnpm dev`) detects new `apps/<app-name>` directories
+automatically.
+
+## Finishing A Chat-Template App
+
+When using the chat template, treat it as scaffolding only. The finished app
+must be branded as the requested app, with its own home screen, navigation,
+package metadata, manifest, and domain workflow. Do not leave visible
+`Chat`, `Starter`, `Blank app`, `Start building`, or `New app` UI in a chat-derived
+app.
+
+## Related Skills
+
+- **workspace-conventions** — Shared workspace rules this workflow assumes.
+- **actions** — How to define the app operations the agent and UI share.
+- **composable-mini-apps** — Splitting work across focused sibling apps.
+- **portability** — Keeping database and hosting assumptions provider-agnostic.
+- **shadcn-ui** — Adding and upgrading the UI primitives.

package/src/templates/workspace-core/.agents/skills/address-feedback/SKILL.md

@@ -75,7 +75,8 @@ The default posture is judgment plus action: fix clear, verified bugs you agree
 6. Verify changed behavior.
 
    - Run the smallest relevant test or typecheck command.
-   - For UI fixes, verify in a browser when feasible and inspect the actual screen.
+   - For UI fixes, inspect the actual screen with a browser tool you already
+     have. Do not write a browser-automation script to check a small fix.
    - If you cannot run a useful verification, say why.
 
 ## Report Format

package/src/templates/workspace-core/.agents/skills/authentication/SKILL.md

@@ -71,6 +71,34 @@ The auto-create path skips users with pending invites or a matching
 `AUTO_CREATE_DEFAULT_ORG=0` only for deployments that intentionally want manual
 org creation.
 
+### Stop And Confirm Before Creating Or Switching Organizations
+
+Vault credentials are scoped per organization and are **not** shared between
+them. A second organization therefore orphans every key synced under the first,
+and the only symptom is a missing-credential error somewhere else entirely,
+naming the key rather than the org change that caused it.
+
+So: **do not create an organization, repoint anyone's `active-org-id`, or
+migrate a user/roster/identity list into a new organization on your own
+initiative.** Stop, say plainly that it will orphan the existing organization's
+credentials, and get an explicit yes first — even when the user asked for
+something that seems to imply it ("use the real org user list", "align this to
+the Settings team view", "migrate my users").
+
+The intended pattern is **one organization per workspace**, with every app
+sharing it. When a request needs real org members, add them to the existing
+organization; never provision a parallel one per app. `createOrganization()`
+logs a loud warning when it creates an additional org for an account that
+already belongs to one, and `setActiveOrgId()` logs one whenever it moves an
+account from one org to another, naming both orgs and the orphaned credentials.
+Treat either warning as a bug report against your own change, not as noise.
+
+Write `active-org-id` only through `setActiveOrgId(email, orgId, reason)` from
+`@agent-native/core` (`src/org/active-org.ts`). Calling `putUserSetting(email,
+"active-org-id", ...)` directly is how a roster migration silently repointed 21
+accounts with nothing in the logs; the helper exists so that cannot happen
+again.
+
 Do not wrap normal app shells in `<RequireActiveOrg>` just to force setup. Use
 non-blocking org UI such as `InvitationBanner`, `OrgSwitcher`, and a `/team`
 route so users can accept invites, join domain-matched teams, or switch orgs

package/src/templates/workspace-core/.agents/skills/composable-mini-apps/SKILL.md

@@ -33,7 +33,20 @@ The main agent should discover available siblings before assuming capability:
 
 - Runtime agents receive an `<available-apps>` block built from
   `discoverAgents()`. Workspace siblings are layered in by
-  `discoverWorkspaceAgents()`.
+  `discoverWorkspaceAgents()`. It carries one line per app — enough to know a
+  sibling exists, not enough to know what it can do.
+- Use the built-in `describe-workspace-apps` tool for actual capability.
+  It reads each peer's live `/.well-known/agent-card.json` and returns their
+  callable action names; pass `app: "<id>"` for one peer's full list with
+  descriptions. Call it before building something a sibling may already own,
+  before telling a user what is or is not possible across apps, and whenever
+  someone asks which app to use for a job.
+- Never hand-maintain a markdown or code list of what each workspace app does.
+  A stale catalog is worse than none: it reads as authoritative while pointing
+  at capabilities that moved or vanished. An app's purpose belongs in its own
+  `package.json` `description` (which flows into the workspace manifest and the
+  `<available-apps>` block), and its capabilities belong in its exposed
+  actions — both of which `describe-workspace-apps` reads live.
 - UI shells, headless surfaces, and scripts can read the same registry through
   `GET /_agent-native/agents?selfAppId=<app-id>`.
 - Code or CLI callers should use the first-class A2A invocation path

package/src/templates/workspace-core/.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/src/templates/workspace-core/.agents/skills/qa/SKILL.md

@@ -1,9 +1,10 @@
 ---
 name: qa
 description: >-
-  Autonomous QA testing across template apps using Playwright. Use when testing
-  apps end-to-end, finding and fixing bugs, or running a QA sweep. Invoke as
-  /qa with optional --apps and --focus args.
+  Autonomous multi-app QA sweep that drives template apps with Playwright MCP.
+  Use only when the user explicitly runs /qa or asks for an end-to-end QA sweep.
+  Do not load it for ordinary feature work, single-page checks, or one-off bug
+  fixes.
 user-invocable: true
 scope: dev
 metadata:
@@ -14,6 +15,8 @@ metadata:
 
 Autonomous QA testing that spins up template apps, tests them with Playwright in parallel, fixes issues, retests, and reports findings. Only alerts the user when blocked.
 
+This is an explicitly requested sweep, not a default verification step. Do not run any part of it — dev servers, browser automation, tester agents — as follow-up to a normal code change.
+
 ## Usage
 
 ```

package/src/templates/workspace-core/.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/src/templates/workspace-core/.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/src/templates/workspace-core/.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
 ---

package/src/templates/workspace-core/.agents/skills/workspace-conventions/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: workspace-conventions
+description: >-
+  Shared conventions for a multi-app Agent Native workspace: finding
+  version-matched framework docs and source, shared vs app-owned code, file and
+  blob storage, env and secrets, agent scratch files, and Dispatch Resources.
+  Use when working across workspace apps, storing files or credentials, or
+  looking up framework APIs.
+---
+
+# Workspace Conventions
+
+The long-form detail behind the workspace `AGENTS.md` core rules. Read this
+before adding shared code, storing files or secrets, creating workspace
+resources, or looking up framework APIs.
+
+## Framework Docs Lookup
+
+Version-matched Agent Native docs ship with `@agent-native/core` in
+`node_modules/@agent-native/core/docs`. A source-only corpus of core and
+first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
+
+- From an app directory, use `pnpm action docs-search --query "<topic>"`,
+  `pnpm action docs-search --slug <slug>`, or `pnpm action docs-search --list`.
+  Use `pnpm action source-search --query "<pattern>"` or
+  `pnpm action source-search --path <path>` when source examples matter.
+- If the action runner is unavailable, read
+  `node_modules/@agent-native/core/docs/AGENTS.md` and search
+  `node_modules/@agent-native/core/docs/content/` directly with `rg`. Search
+  `node_modules/@agent-native/core/corpus/` for source examples.
+- For advanced workspace features, start with `workspace`, `multi-app-workspace`,
+  `a2a-protocol`, `pure-agent-apps`, `automations`, `recurring-jobs`,
+  `external-agents`, `mcp-protocol`, `feature-flags`, `sharing`, and `security`.
+
+Use package docs for framework APIs, the package corpus for reusable
+framework/template patterns, and this `AGENTS.md` plus `.agents/skills/` for
+workspace-specific conventions.
+Before building common workspace or agent UI, read `agent-native-toolkit` to
+inventory existing public kits and installed package seams. Read
+`customizing-agent-native` before adapting shared UI. Use the supported
+ladder: configure → compose → eject the smallest unit → propose a shared seam.
+Preview before `--apply`, commit `agent-native.ejections.json`, and never edit
+`node_modules` or eject protected runtime contracts.
+
+## Shared Conventions
+
+- All AI/LLM behavior goes through the app's agent chat. UI and server code
+  must not call model providers, AI SDK `generateText()` / `streamText()`, or
+  other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent
+  work, including hidden `context` and `submit: false` prefill/review flows.
+  Only use `useAgentChatContext`, `setAgentChatContextItem`,
+  `listAgentChatContext`, `removeAgentChatContextItem`, and
+  `clearAgentChatContext` when UI needs two-way sync with staged context chips.
+  Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven
+  UI or "AI" features.
+- Put shared code in `packages/shared` only when multiple apps need it.
+- Keep app-specific screens, actions, state, and skills inside `apps/<app>`.
+- SQL is for structured records, metadata, references, and searchable text. Store
+  large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,
+  ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
+  storage and persist only URLs, ids, or handles.
+- Store shared runtime configuration in the workspace root `.env`; use
+  `apps/<app>/.env` only for app-specific overrides. Never hardcode API keys,
+  tokens, webhook URLs, signing secrets, private Builder/internal data, customer
+  data, or credential-looking literals in source, docs, prompts, fixtures,
+  application state, action responses, or generated app content. Use
+  secrets/OAuth/runtime configuration and obvious placeholders in examples.
+- Prefer framework defaults until the workspace has a real custom rule,
+  component, plugin, action, or skill to share.
+- Keep the Workspace files view for user-authored or user-requested resources.
+  Agents may create hidden `agent_scratch` resources for temporary working
+  notes, scripts, task plans, or intermediate outputs, but should promote them
+  to normal workspace visibility only when the user explicitly asks to keep or
+  manage the file.
+- Runtime-editable global resources can be managed from Dispatch Resources.
+  Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,
+  `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for
+  personas/positioning/messaging/company facts/brand guidelines, and
+  `agents/<slug>.md` for custom agent profiles. Scope them to All apps when
+  every workspace app should inherit them. All-app resources are inherited at
+  runtime; do not copy or sync them into individual apps.
+
+## Related Skills
+
+- **adding-workspace-apps** — Creating and mounting a new app under `apps/`.
+- **agent-native-docs** — The full docs and source-corpus lookup workflow.
+- **agent-native-toolkit** — Inventory of shared workspace and agent UI.
+- **customizing-agent-native** — The configure → compose → eject ladder.
+- **delegate-to-agent** — Routing every AI feature through the agent chat.
+- **secrets** — Registering API keys and service credentials.
+- **storing-data** — Where structured data and large payloads belong.

package/src/templates/workspace-core/.agents/skills/writing-agent-instructions/SKILL.md

@@ -37,6 +37,27 @@ If a section is growing past a screen, it belongs in a skill. `AGENTS.md`
 answers "what is this app and what can I do," not "how exactly do I do the hard
 thing."
 
+### The 6,000-character cap is real and silent
+
+A template `AGENTS.md` is injected into the runtime agent's system prompt and
+hard-sliced at `COMPACT_PROMPT_RESOURCE_MAX_CHARS` (6,000). Past that, the agent
+sees a truncation marker instead of your text, so the tail stops being
+always-on guidance and becomes something it has to go fetch. `pnpm
+the repository's `guard:agent-chat-context` check fails the build when a first-party
+file overflows; generated apps do not ship that repository-only guard. Keep files
+under ~5,500 so ordinary edits don't tip them over.
+
+Two consequences worth designing around:
+
+- **Put the skills list second, right after the purpose line.** It is the
+  pointer to every deferred skill. If it lands in the truncated tail, the agent
+  cannot discover any of the depth you carefully moved out.
+- **Markdown tables cost more than they look.** Prettier pads table cells to
+  align columns, and that invisible whitespace counts against the cap — enough
+  padding in a wide action table to push a file back over it on its own. Both
+  `**/AGENTS.md` and `**/SKILL.md` are in `.prettierignore` for this reason;
+  keep them there and write table rows unpadded.
+
 ```markdown
 # Projects App
 
@@ -121,6 +142,45 @@ The goal is progressive disclosure, not reduced capability: a compact first
 request, precise discovery, and full fidelity once the agent knows which depth
 is relevant.
 
+## Say each thing once, in the layer that owns it
+
+Current-generation models do not need a rule repeated in the system prompt, the
+instructions, and the tool description. Repetition is not reinforcement — it is
+three chances to disagree with each other, and the model spends effort
+reconciling them before it can act. Pick the owning layer:
+
+| Layer | Owns |
+| --- | --- |
+| System prompt / `AGENTS.md` | Which capabilities exist, and policy spanning tools: turn shape, what to do first, invariants that hold every turn |
+| Tool / action description | How to call it, argument and result semantics, what to say about a result, when this tool rather than a sibling |
+| Skill | Multi-step workflows, worked examples, field references, edge cases |
+
+The common mistake is restating a tool's mechanics as a numbered core rule.
+Deferred tools are loaded through `tool-search`, so the model always reads the
+description before it can call the tool — a start/update/complete sequence or an
+argument enum in the prompt buys nothing and is charged on every turn. State
+that the capability exists and when it applies; let the description carry how.
+
+## Prefer judgment over rules, and interfaces over examples
+
+Blanket prohibitions were how older models were kept out of worst-case
+behavior. They now mostly cost accuracy, because a rule stated absolutely is
+wrong for some fraction of requests and the model has to guess which fraction it
+is in. Write the intent and let the model apply it:
+
+- Say "match the surrounding code's comment density" rather than "never write
+  comments." Say "response length mirrors the task" rather than "2–5 sentences."
+- Skip arbitrary numeric formatting prescriptions (bullet counts, nesting bans)
+  unless a surface genuinely breaks without them.
+- Keep hard constraints for the areas where a wrong call is expensive and not
+  self-correcting: security, destructive operations, fabricating data or
+  success, and credential handling. Those stay absolute.
+- Don't add few-shot examples of tool calls to teach usage. Examples narrow the
+  model to the shapes you showed. Make the tool's own interface expressive
+  instead — precise parameter names, enums that imply the state machine,
+  `.describe()` on every field. Keep a literal example only where it defines a
+  syntax the schema cannot, such as a `pnpm action` CLI invocation in dev mode.
+
 When documenting version history, restore, or audit trails, use actions for
 full restorable snapshots (`list-<resource>-versions`,
 `get-<resource>-version`, `restore-<resource>-version`). Do not copy legacy