@agent-native/core 0.152.1 → 0.153.1

package/dist/templates/workspace-core/.agents/skills/voice-transcription/SKILL.md

@@ -1,222 +0,0 @@
----
-name: voice-transcription
-description: >-
-  Framework-wide voice dictation in the agent sidebar composer. Use when
-  changing composer microphone UX, the transcribe-voice route, or the
-  Voice Transcription settings section. Covers transcription-source routing,
-  cleanup routing, Google realtime gating, and the voice transcription
-  application-state keys.
-scope: dev
-metadata:
-  internal: true
----
-
-# Voice Transcription
-
-The microphone inside the sidebar composer offers two distinct paths:
-editable dictation and an opt-in realtime speech-to-speech agent session.
-Users configure dictation separately from AI cleanup in Settings → Voice
-Transcription. Both paths are available in every template that renders the
-shared agent sidebar.
-
-## UX rules
-
-- **Always show the mic alongside the send button.** Cursor replaces send
-  with mic when the composer is empty; their users complain. We keep both
-  visible — Lovable does the same.
-- **Ask before switching modes.** The mic opens a compact shadcn popover with
-  **Real-time voice** as the primary action and **Dictate** as the secondary;
-  never silently replace the established dictation behavior. Users can choose
-  **Remember my preference** to skip the chooser on later clicks.
-- **Dictation is click-to-toggle, not push-to-talk.** More forgiving in a sidebar, avoids
-  host-app hotkey clashes. Keyboard shortcut is `Cmd/Ctrl+Shift+M` and
-  `Escape` cancels mid-recording.
-- **Transcript lands in the composer, editable, never auto-sent.** Insert at
-  the caret via `editor.chain().focus().insertContent(text).run()`.
-- **No CSS transitions for the recording state.** Framework rule; use static
-  brand color (`#625DF5`) instead of pulses.
-- **Icon:** Tabler `IconMicrophone` (idle) / `IconPlayerStopFilled` (recording).
-  Never use a sparkle or robot icon.
-- **Errors via inline alert or toast, never `window.alert`.**
-
-## Realtime speech mode
-
-Realtime speech mode is a full-duplex OpenAI Realtime WebRTC session, separate
-from the dictation providers below. It prefers the authenticated user's
-complete Builder connection and the Builder-managed metered gateway. A scoped
-`OPENAI_API_KEY` is the fallback when Builder is not connected. The server owns
-the `gpt-realtime-2.1` session configuration and keeps credentials out of
-browser code. If neither provider is configured, show **Connect Builder** as
-the primary microphone-popover action and OpenAI key setup as the secondary
-action before requesting microphone permission.
-
-- Starting voice mode collapses the chat into a persistent bottom-end speech
-  orb. The orb stays visible above the chat even when the chat opens
-  automatically. Clicking it shows or hides chat without ending the session;
-  opening chat slides the orb clear of the sidebar. The progressively disclosed
-  controls contain only settings and the separate end-session action.
-- The orb's compact waveform stays visible for the full session and reflects
-  actual microphone or assistant audio activity. At silence it rests at its
-  baseline instead of turning into a loading spinner. Once connected, a soft,
-  slowly rotating blue glow marks the live session; brighten and speed up the
-  glow while the agent is working, and keep it static under reduced motion.
-  While connecting, show a distinct compact spinner; when the session becomes
-  live, the assistant gives one brief spoken greeting so readiness is
-  unambiguous. Do not apply a text-sized `max_output_tokens` cap to that audio
-  greeting because audio tokens can truncate it mid-sentence.
-- The orb settings cog opens in place without ending voice mode or navigating
-  away. Nested pickers must not dismiss the settings popover. Language and
-  intelligence update the active Realtime session; the microphone picker swaps
-  the live WebRTC input track and remembers the browser-local device choice;
-  an output-voice change updates immediately only before the assistant has
-  emitted audio and otherwise applies to the next conversation, matching the
-  Realtime API's voice immutability rule.
-- Semantic VAD keeps listening, starts responses automatically, and supports
-  barge-in while the agent is speaking.
-- Function calls must cross the authenticated realtime tool bridge and enter
-  `executeAgentToolCall`. Never call `ActionEntry.run` directly: that bypasses
-  schema validation, approvals, audit/journal behavior, timeouts, redaction,
-  and mutation refreshes.
-- Preserve the active browser-tab id in request context so `set-url-path`,
-  `set-search-params`, `view-screen`, and tab-scoped application state affect
-  the app the user is actually speaking to. Realtime tool manifests are capped,
-  so prioritize `navigate`, `set-url-path`, `set-search-params`, and
-  `view-screen` before packing large template registries.
-- Keep `tool-search` in the initial Realtime manifest. A successful specific
-  search may expand the live session with matching action schemas, but the
-  server must derive those schemas from its own registry, bind authorization
-  to the authenticated voice session, and continue execution through
-  `executeAgentToolCall`. Treat `session.update.tools` as a full replacement:
-  preserve the pinned navigation/discovery tools, evict lower-priority entries
-  within the manifest cap, and wait for `session.updated` before asking the
-  model to continue with a newly discovered tool.
-- Do not persist audio or interim transcript deltas. Append completed user and
-  assistant utterances as ordinary text messages to the exact chat thread
-  captured when the session starts. Input transcription completes
-  asynchronously from assistant generation, so reserve provider conversation
-  item order and publish only the contiguous completed sequence; never use
-  completion arrival time as chat order. Ending voice mode opens that chat so
-  the user can continue over text. Store only compact lifecycle and latest
-  context at `application_state["realtime-voice-session"]`; delete it when the
-  session ends.
-- Store the user-controlled language, intelligence, and output-voice choices at
-  `application_state["realtime-voice-prefs"]`. Keep this separate from
-  `voice-transcription-prefs`, which configures editable dictation rather than
-  the speech-to-speech session.
-- Store the optional remembered chooser selection at
-  `application_state["voice-input-preference"]`. Keep it separate from both
-  mode-specific preference objects.
-- Missing-key failures should open Settings focused on the user-scoped
-  `OPENAI_API_KEY` field. Never send, log, or echo the key to the browser.
-
-## Source And Cleanup
-
-Settings must keep these as separate choices:
-
-- **Live transcription source**: `mac-native`, `google-realtime`, or `batch`.
-- **AI cleanup**: independent off/on toggle. Cleanup uses managed Gemini first
-  when a managed AI services connection is configured, then BYOK Gemini (`GEMINI_API_KEY`).
-  Gemini cleanup/title/summary generation is not a live STT source.
-
-`application_state["voice-transcription-prefs"]` stores
-`{ transcriptionMode, provider, instructions }`. The legacy `provider` field
-is still written for old clients and batch provider preferences:
-
-| Value             | Meaning                                                        | Needs key                    |
-| ----------------- | -------------------------------------------------------------- | ---------------------------- |
-| `mac-native`      | Native macOS/Tauri speech path; web clients normalize to browser-native where needed | No                           |
-| `google-realtime` | Dedicated WebSocket → Google Speech-to-Text gRPC `StreamingRecognize` path | `GOOGLE_APPLICATION_CREDENTIALS` |
-| `batch`           | Upload audio after stop through the existing batch route       | Builder/Gemini/Groq/OpenAI depending on fallback |
-| `auto` provider   | Browser SpeechRecognition when supported; server batch fallback chain otherwise | No key needed in browsers that support SpeechRecognition |
-| `builder-gemini`  | Managed Gemini Flash-Lite batch/cleanup preference             | Managed AI services account connected |
-| `gemini`          | Direct Google Gemini BYOK batch/cleanup preference             | `GEMINI_API_KEY`             |
-| `groq`            | Groq Whisper batch preference                                  | `GROQ_API_KEY`               |
-| `openai`          | OpenAI Whisper batch preference                                | `OPENAI_API_KEY`             |
-| `browser`         | Legacy native/browser live speech preference                   | No                           |
-
-Default behavior:
-
-- The shared web settings/composer default to Batch / `auto`. In `auto` mode,
-  `useVoiceDictation` uses `startBrowser()` (Web Speech API, no key required,
-  incremental streaming) when the browser supports `SpeechRecognition`. It only
-  falls back to the MediaRecorder → server upload path when `SpeechRecognition`
-  is not available (e.g. Firefox). This means dictation works out of the box in
-  Chrome, Edge, and Safari without any API key configuration.
-- Dedicated macOS Tauri-native surfaces may save `mac-native`, but do not
-  assume the shared React settings default to it.
-- Old stored `builder` values are treated as `builder-gemini`.
-- Old stored `browser` values are treated as `mac-native`.
-- Saved `google-realtime` preferences must never hit `/_agent-native/transcribe-voice`. They go through the dedicated session bridge `POST /_agent-native/transcribe-stream/session`, which mints an opaque ai-services websocket session and keeps the Google service-account JSON off the client.
-- In the current bridge, the Google option is only actually ready when both the user's `GOOGLE_APPLICATION_CREDENTIALS` secret exists and a managed AI services connection is configured, because the framework mints the managed ai-services session before streaming begins.
-
-## Where the pieces live
-
-| File                                                                  | Purpose                                             |
-| --------------------------------------------------------------------- | --------------------------------------------------- |
-| `packages/toolkit/src/composer/useVoiceDictation.ts`                  | Provider-routing hook (MediaRecorder / Web Speech)  |
-| `packages/toolkit/src/composer/VoiceButton.tsx`                       | Mic button + live amplitude + cancel overlay        |
-| `packages/toolkit/src/composer/RealtimeVoiceMode.tsx`                | Opt-in popover + persistent speech orb              |
-| `packages/toolkit/src/composer/useRealtimeVoiceMode.tsx`             | WebRTC lifecycle, provider events, and tool bridge  |
-| `packages/toolkit/src/composer/TiptapComposer.tsx`                    | Wires the hook, insertion, and keyboard shortcut    |
-| `packages/core/src/client/settings/VoiceTranscriptionSection.tsx`     | Live source + cleanup controls in sidebar settings  |
-| `packages/core/src/client/transcription/BuilderTranscriptionCta.tsx`  | CTA shown when Builder account isn't connected      |
-| `packages/core/src/client/transcription/use-live-transcription.ts`    | Web Speech live-transcription hook for recordings   |
-| `packages/core/src/server/transcribe-voice.ts`                        | Route handler (routes to Builder/Gemini/Groq/Whisper) |
-| `packages/core/src/server/realtime-voice.ts`                          | Authenticated OpenAI SDP and action-tool routes     |
-| `packages/core/src/transcription/builder-transcription.ts`            | Builder proxy transcription client                  |
-| `packages/core/src/voice/`                                            | Shared voice context pack, prompt, and replacement helpers |
-| `packages/core/src/secrets/register-framework-secrets.ts`             | Framework-level provider key registration           |
-
-## Key resolution (server)
-
-`transcribe-voice.ts` is batch-only. Do not add realtime streaming to this
-route. Google Speech-to-Text realtime uses a dedicated audio-frame protocol:
-client audio frames → `/_agent-native/transcribe-stream/session` →
-ai-services WebSocket → Google gRPC `StreamingRecognize` → partial / final
-transcript events. Use the canonical docs URL:
-https://cloud.google.com/speech-to-text/v2/docs/streaming-recognize
-
-Batch routing is based on the user's provider preference:
-
-1. If `builder-gemini` and `resolveHasBuilderPrivateKey()` → calls `transcribeWithBuilder({ model: "gemini-3-1-flash-lite" })` via Builder proxy, or uses Builder Gemini Flash-Lite to clean up a live native/browser transcript when the desktop client sends text instead of audio.
-2. If `builder` and `resolveHasBuilderPrivateKey()` → legacy alias; prefer `builder-gemini`.
-3. If `gemini` → resolves `GEMINI_API_KEY` and calls the direct Google Gemini path.
-4. If `groq` → resolves `GROQ_API_KEY` and calls Groq's Whisper-compatible endpoint.
-5. If `openai` → resolves `OPENAI_API_KEY`:
-   - `readAppSecret({ key: "OPENAI_API_KEY", scope: "user", scopeId: session.email })` — user's encrypted secret.
-   - `resolveCredential("OPENAI_API_KEY")` — env var + SQL settings fallback.
-
-In auto mode / no preference, the route tries Builder Gemini Flash-Lite first
-when Builder is connected, then Gemini BYOK, Groq, and OpenAI.
-When a request includes `instructions`, pass them through to the selected LLM
-provider. Gemini uses them in the transcription prompt, Builder receives them
-as transcription/cleanup instructions, and Whisper-compatible providers receive
-them as provider prompt/context.
-
-Requests may also include a multipart `voiceContext` JSON field. Parse it with
-`parseVoiceContextPack()` from `@agent-native/core/voice` and pass the resulting
-context through `buildVoiceGuidanceBlock()`; do not hand-roll separate prompt
-formats. The context pack is for bounded snippets, active references, route/page
-metadata, and preferred vocabulary/replacements only. Browser-native and Google
-realtime final text can POST `{ text, provider, instructions, voiceContext }` to
-`/_agent-native/transcribe-voice` when AI cleanup is enabled; batch audio can
-send the same `voiceContext` field with its audio upload.
-
-Never hardcode a shared key. Never log the value. Never echo it back to the
-client.
-
-## Overriding per-template
-
-Templates can:
-- **Disable the mic**: pass `voiceEnabled={false}` to `TiptapComposer`.
-- **Replace the button**: wrap `TiptapComposer` and render your own `extraActionButton`; the framework mic stays immediately before the primary send/stop control. Use `stopButton` for an active-run control so the disabled send button becomes stop when the draft is empty and returns when the user types.
-- **Pre-register provider keys as `required: true`**: call `registerRequiredSecret(...)` from your own server plugin when a template needs a specific BYOK provider in onboarding.
-
-## Don'ts
-
-- Don't call transcription providers from the client — go through `/_agent-native/transcribe-voice` so the user's secret stays server-side.
-- Don't remove the cancel affordance — mic permission abuse paranoia is real.
-- Don't auto-submit the transcript — users always edit before sending.
-- Don't route realtime tool calls around the central guarded agent executor.
-- Don't persist realtime audio or put provider keys in SDP/session payloads.
-- Don't copy Cursor's "hide send when empty" pattern — it confuses users.

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

@@ -1,363 +0,0 @@
----
-name: writing-agent-instructions
-description: >-
-  How to write great agent instructions for an agent-native app or template:
-  AGENTS.md, skills, and tool/action descriptions. Use when authoring or
-  reviewing AGENTS.md, writing a SKILL.md, wording action descriptions, or
-  deciding what belongs in instructions vs skills vs memory.
-scope: dev
-metadata:
-  internal: true
----
-
-# Writing Agent Instructions & Skills
-
-This is a creator-facing guide. When you build an agent-native app or template,
-the agent's behavior is only as good as the instructions you give it. Three
-surfaces carry that guidance: `AGENTS.md` (the map), skills (the deep dives),
-and action/tool descriptions (how the agent picks the right tool). Write each
-one for fast retrieval, not for prose.
-
-## Keep AGENTS.md small and skimmable
-
-`AGENTS.md` is loaded as orientation. It should be the smallest thing that lets
-the agent act correctly, with everything deep pushed into skills. Aim for these
-sections and little else:
-
-- **Purpose line** — one sentence on what the app is and the primary workflow.
-- **Core rules** — the handful of invariants that must always hold (data in SQL,
-  operations go through actions, AI goes through the agent chat, schema changes
-  are additive). Short, imperative bullets.
-- **Application-state keys** — the `navigation`/selection/focus keys the agent
-  reads to know what the user is looking at, with their shape.
-- **Action table** — a compact table of action name -> purpose (see below).
-- **Skills index** — a list of the skills that exist and when to read each one.
-
-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
-guard:agent-chat-context` — the repository's own 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
-
-One workspace for projects, tasks, and notes. Agent and UI share the same SQL
-data and the same actions.
-
-## Core Rules
-
-- Data lives in SQL via Drizzle. Use actions for all writes.
-- All AI work goes through the agent chat; never call an LLM inline.
-- Schema changes are additive only.
-
-## Application State
-
-- `navigation.view`: `home` | `project`
-- `navigation.projectId`: selected project on a project page
-
-## Actions
-
-| Action           | Purpose                     |
-| ---------------- | --------------------------- |
-| `list-projects`  | List accessible projects    |
-| `create-project` | Create a project            |
-| `update-project` | Rename or archive a project |
-
-## Skills
-
-- `project-imports` — read before importing legacy CSV exports.
-- `sharing` — read before exposing a project to other users.
-```
-
-## Single-source AGENTS.md (CLAUDE.md is a symlink)
-
-Keep one canonical instructions file: `AGENTS.md`. If a client expects
-`CLAUDE.md`, make it a symlink to `AGENTS.md` rather than a second copy. Two
-hand-maintained files drift, and the agent ends up with contradictory rules.
-One source of truth, linked where needed.
-
-## Keep generated guidance in sync
-
-Framework guidance is authored once in this repo and copied outward. Treat
-`.agents/skills/` as the canonical source for shared skills. Generated
-workspace skills in `packages/core/src/templates/workspace-core/.agents/skills/`
-and first-party template copies of shared skills must stay byte-for-byte in
-sync; run `pnpm sync:workspace-skills` after editing a shared skill, and
-`pnpm guard:workspace-skills` before calling the guidance done.
-
-Generated app and workspace instructions must teach the same action-first data
-contract:
-
-- Normal app data goes through `defineAction` files in `actions/`.
-- React calls actions with `useActionQuery`, `useActionMutation`, or
-  `callAction`; route paths are a transport detail hidden behind helpers.
-- Custom `/api/*` routes are only for route-shaped protocols such as uploads,
-  streaming, webhooks, OAuth callbacks, public SEO/OG endpoints, or binary
-  assets.
-- Do not create pass-through routes whose main job is to call, repackage, or
-  re-export an action.
-
-Generated guidance must also distinguish deterministic tools from AI-shaped
-workflows. Provider reads, validation, deterministic transforms, CRUD, and
-persistence belong in focused actions. Research, analysis, generation,
-recommendation, synthesis, and other user-steerable multi-step work should
-start in the AgentSidebar and let the agent orchestrate those actions. State
-that `sendToAgentChat({ openSidebar: true })` is the default handoff and that
-follow-ups stay in the same thread; do not add a second freeform prompt box.
-
-## Budget the first model request
-
-Treat the initial prompt and tool catalog as a latency budget. The agent should
-start with a compact map of the app, then retrieve depth only when the task
-needs it.
-
-- Set `initialToolNames` to the small set of actions used in the app's primary
-  workflows. Keep `tool-search` available so every other registered action and
-  connected MCP tool remains discoverable on demand.
-- Keep essential, always-applicable rules in `AGENTS.md`. Put workflow detail
-  in skills and long reference material in `references/` or workspace
-  resources that the agent can read when relevant.
-- Do not inject full documents, transcripts, data dictionaries, source trees,
-  or provider catalogs through `systemPrompt` or `extraContext`. Inject a
-  bounded summary, stable ids/paths, and the exact action or resource lookup
-  that retrieves the full content.
-- Avoid duplicating action descriptions in prose. The starter tools already
-  carry schemas; uncommon actions are available through `tool-search`.
-- Keep `view-screen` concise. Return navigation, selection, visible summary,
-  and ids needed for a follow-up read rather than full record bodies.
-
-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
-raw-route version panels, such as document-version `/api/*` helpers, into new
-features. The Plans version-history pattern is the preferred model.
-
-## SKILL.md frontmatter must say what AND when
-
-The `description` is the only thing the agent sees when deciding whether to read
-a skill. It must answer two questions: what the skill covers, and when to
-trigger it. A description that only describes the topic will not fire.
-
-```markdown
----
-name: project-imports
-description: >-
-  How to import projects from the legacy CSV export. Use when the user uploads
-  a project CSV or asks to migrate projects from the old system.
----
-```
-
-- Lead with the capability, then add an explicit **"Use when…"** clause.
-- Be slightly pushy — over-triggering beats a skill that never loads.
-- Keep it under ~40 words; it is loaded into context on every conversation.
-
-### Scope a skill to runtime vs dev
-
-An optional `scope` field decides which agent loads the skill:
-
-- `both` (default when omitted) — loaded by connected repo agents and the
-  in-app runtime agent.
-- `runtime` — loaded only by the in-app runtime agent.
-- `dev` — for the human's coding agent (e.g. Claude Code) only. A `scope: dev`
-  skill is invisible to the runtime agent everywhere (system-prompt skills block
-  and `docs-search`).
-
-Use `scope: dev` for internal-only guidance that should help connected repo
-agents such as Codex or Claude Code, but should not influence the deployed
-production agent. Do not use `metadata.internal` for this: it is catalog/package
-metadata and does not control runtime visibility.
-
-```markdown
----
-name: release-checklist
-description: >-
-  Steps for cutting a release. Use when preparing or publishing a new version.
-scope: dev
----
-```
-
-Omit `scope` for normal skills (the default `both` keeps them loading at
-runtime — fully backward compatible). For a dev-only skill, mark it `scope: dev`
-and optionally mirror it under `.claude/skills/<name>/SKILL.md` so Claude Code
-picks it up while the runtime agent skips it.
-
-## Progressive disclosure: lean SKILL.md, depth in references/
-
-Write the SKILL.md as the lean, must-know layer: the rule, how to do it, the
-do/don't list, and pointers. Push long examples, exhaustive field references,
-API quirks, and edge-case tables into `references/` files the agent reads only
-when it needs them.
-
-```
-.agents/skills/project-imports/
-├── SKILL.md            # rule + happy path + do/don't
-└── references/
-    └── csv-format.md   # full column spec, encodings, edge cases
-```
-
-This keeps the always-loaded surface small and lets depth scale without bloating
-context. See the **create-skill** skill for the full skill format.
-
-## Write action-oriented tables
-
-The agent scans tables faster than prose. Prefer a table of name -> purpose over
-paragraphs describing each operation. The same applies to state keys, field
-types, and any enumerable set. Tables are skimmable, diffable, and easy to keep
-in sync when you add an action.
-
-## Write clear tool/action descriptions
-
-Action descriptions are tool descriptions — they drive tool selection. Make each
-one a precise, single-purpose sentence:
-
-- Say what it does and what it returns, not how it's implemented.
-- Describe each parameter in its `.describe()` so the agent fills it correctly.
-- One responsibility per action. If a description needs "and also…", split it.
-- Mark read-only actions (`readOnly: true` / `http: { method: "GET" }`) so the
-  agent knows they're safe to call freely.
-- For provider-backed shortcuts, make clear they are convenience paths, not
-  capability ceilings. If arbitrary provider endpoints/filters may matter,
-  point instructions to `provider-api-catalog`, `provider-api-docs`, and
-  `provider-api-request` instead of implying the shortcut is all the agent can
-  do.
-
-```ts
-defineAction({
-  description: "Create a project. Returns the new project id and title.",
-  schema: z.object({
-    title: z.string().min(1).describe("Project title shown in the sidebar"),
-  }),
-  // ...
-});
-```
-
-## Bake in anti-fabrication and verify-before-done
-
-App instructions should make honesty and verification the default behavior:
-
-- **Never fabricate.** If data isn't found or an action fails, say so and recover
-  — don't invent results or claim success. Read the real value via an action or
-  query before reporting it.
-- **Verify before declaring done.** After a change, confirm it with a read-back
-  (re-query the row, re-read the screen via `view-screen`) instead of assuming
-  the write worked.
-- **Recover, don't give up.** On a recoverable error (a failed query, a transient
-  fetch), retry or fix the input rather than abandoning the task. Keep this
-  separate from the anti-fabrication rule — don't conflate "don't make things up"
-  with "stop at the first error."
-
-Put these as core rules in `AGENTS.md` so they apply to every turn.
-
-## Bake in secrets hygiene
-
-Instruction authors must make credential handling explicit anywhere an app,
-skill, action, webhook, integration, or extension touches external services.
-Write the rule in terms of values, not just files: never hardcode real API keys,
-tokens, webhook URLs, signing secrets, OAuth refresh tokens, private
-Builder/internal data, or customer data in source, docs, tests, fixtures,
-prompts, screenshots, or generated content.
-
-Examples may name credential keys such as `OPENAI_API_KEY` or `SLACK_WEBHOOK`,
-but values must be placeholders (`<OPENAI_API_KEY>`, `${keys.SLACK_WEBHOOK}`) or
-clearly fake test data. Tell agents which approved channel to use instead:
-deployment env vars for deploy-level secrets, `app_secrets` /
-`saveCredential` / `resolveCredential` for scoped API keys, `oauth_tokens` for
-OAuth, and `${keys.NAME}` substitution for extension/automation outbound HTTP.
-
-## What goes where
-
-- **AGENTS.md** — applies to the whole app, every turn: purpose, core rules,
-  state keys, action index, skills index.
-- **Skills** — reusable how-to for a specific pattern, loaded on demand. Applies
-  to everyone working in the app.
-- **Memory (`memory/MEMORY.md`)** — per-user preferences and corrections, not
-  authored guidance. See **capture-learnings**.
-
-## Do
-
-- Keep `AGENTS.md` to roughly one screen of orientation; link out for depth.
-- Update the action table and skills index whenever you add an action or skill.
-- Write every SKILL.md description with an explicit "Use when…".
-- Use tables for any enumerable set (actions, state keys, field types).
-
-## Don't
-
-- Don't duplicate skill content inside `AGENTS.md` — point to the skill.
-- Don't maintain two instruction files; symlink `CLAUDE.md` to `AGENTS.md`.
-- Don't write vague descriptions ("helps with projects") — they won't trigger.
-- Don't document niche/buried UI behaviors in instructions; let code and UI
-  carry those.
-- Don't paste real credentials, credential-looking dummy strings, private
-  Builder/internal data, or customer data into examples. Use placeholders.
-
-## Related Skills
-
-- **create-skill** — The skill format and templates this guide refers to.
-- **adding-a-feature** — The four-area model (UI, actions, skills/instructions,
-  application state) every feature must satisfy.
-- **actions** — How action descriptions become agent tools.
-- **context-awareness** — Application-state keys and the `view-screen` pattern.
-- **capture-learnings** — Where per-user learnings go instead of AGENTS.md.