@aitne-sh/aitne 0.1.12 → 0.1.13

package/agent-assets/docs/features/wiki/search.md

@@ -21,9 +21,7 @@ summary: |
 section: wiki
 tags:
   - wiki
-  - search
-  - fts
-  - reference
+  - knowledge
 status: stable
 ask_examples:
   - How does !ask find the right wiki pages?
@@ -36,7 +34,7 @@ ask_examples:
   - What is fts_wiki?
 locale: en-US
 created: 2026-05-21
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - wiki search
   - fts_wiki
@@ -83,9 +81,9 @@ The wiki exposes two read paths the skills use to find content:
    A short, human-readable list with one bullet per wiki page, kept
    current by every `!compile` run. Good for "give me the lay of the
    land" queries.
-2. **`fts_wiki`** — a content-less SQLite FTS5 virtual table the
-   daemon syncs on every successful disk write. Good for "find any
-   page that mentions X" queries.
+2. **`fts_wiki`** — a full-text search index (a content-less SQLite
+   FTS5 virtual table) the daemon syncs on every successful disk
+   write. Good for "find any page that mentions X" queries.
 
 Both surfaces are read-only consumers; only `!compile` writes the
 catalogue, and only the wiki API write endpoints update `fts_wiki`.
@@ -139,9 +137,9 @@ CREATE VIRTUAL TABLE IF NOT EXISTS fts_wiki USING fts5(
 ```
 
 The `unicode61` tokenizer with `remove_diacritics 2` matches the
-mail FTS table for consistency. CJK content is handled by code-point
-breaking — searches work for Japanese, Chinese, Korean, and
-mixed-script wikis.
+mail FTS table for consistency. CJK (Chinese, Japanese, Korean)
+content is handled by code-point breaking, so searches work across
+those scripts and mixed-script wikis.
 
 ### Layer prefixes
 
@@ -157,9 +155,9 @@ The path classifier maps each on-disk file to one of six layers:
 Only four of these are actually indexed. `upsertWikiFulltextRow`
 **drops `log` and `inbox` rows** before insert: `log.md` is an
 append-only audit trail and `00_inbox/` is human-only, so indexing
-them would bury wiki and raw matches under log noise. So the values
-you ever see in `fts_wiki.layer` are `raw`, `wiki`, `output`, and
-`meta`.
+them would bury wiki and raw matches under log noise. So the only
+values you ever see in `fts_wiki.layer` are `raw`, `wiki`, `output`,
+and `meta`.
 
 Searches can filter by layer to restrict the result set — e.g.
 `layer=wiki` for only canonical pages, not raw notes.
@@ -173,7 +171,7 @@ evidence. The query supports:
 
 - `q` — the search query. Each whitespace-separated token is quoted
   and joined by implicit AND, so a multi-word query narrows the
-  result set. (Tokens are quoted to neutralise FTS5's `AND`/`OR`/
+  result set. (Tokens are quoted to neutralize FTS5's `AND`/`OR`/
   `NOT`/`NEAR` operator vocabulary — typing literally `rust AND go`
   matches those words, it does not parse as a boolean.)
 - `layer` — restrict to a single indexed layer (`raw` / `wiki` /
@@ -187,8 +185,8 @@ evidence. The query supports:
 
 Each result row carries `path`, `layer`, `title`, a body `snippet`
 (FTS5 `snippet()` output, `<mark>`-wrapped), `mtime` so the caller
-can rank by recency, and a BM25 `rank` (lower is better, `title`
-weighted above `body`).
+can rank by recency, and a BM25 relevance `rank` (lower is better,
+`title` weighted above `body`).
 
 There is no dashboard content-search bar today — the FTS surface is
 used by the agent, not the user UI. The dashboard timeline
@@ -222,7 +220,7 @@ A simplified flow for `!ask <question>`:
    question's key terms.
 2. It reads `10_raw/` notes only when the wiki pages need source
    verification.
-3. The LLM synthesises an answer from the pages it pulled.
+3. The LLM synthesizes an answer from the pages it pulled.
 4. The answer is written to
    `30_outputs/<YYYY-MM-DD>-<slug>.md` (the date-prefixed output
    shape the `OUTPUT_RE` path check enforces). The file records the

package/agent-assets/docs/features/wiki/workspaces.md

@@ -24,7 +24,6 @@ tags:
   - wiki
   - workspaces
   - config
-  - core
 status: stable
 ask_examples:
   - What is a wiki workspace?
@@ -37,7 +36,7 @@ ask_examples:
   - Can two wikis live in nested folders?
 locale: en-US
 created: 2026-05-21
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - wiki workspace
   - workspace
@@ -87,10 +86,10 @@ config_keys:
 # Wiki Workspaces, Vaults, and Write Strategy
 
 A **wiki workspace** is one row in the `wiki_workspaces` table plus
-the directory tree it points at. Aitne ships with no active
-workspace; the first run of the Enable flow creates one named
-`default`. Phase 5 unlocked multi-workspace — you can run as many
-side-by-side wikis as you have distinct knowledge domains.
+the directory tree it points at. Aitne starts with no active
+workspace. The first run of the Enable flow creates one named
+`default`. You can run as many side-by-side wikis as you have
+distinct knowledge domains — one per subject is a common setup.
 
 ## Internal vs external mode
 
@@ -109,8 +108,8 @@ Path-collision rules apply to both modes:
 - Two wiki workspaces may not nest — neither root can be inside the other.
 
 The dashboard probe (`POST /api/wiki/workspaces/probe`) runs these
-checks live before the workspace row is written and surfaces a
-human-readable error if any rule trips.
+checks live before the workspace row is written, and shows a
+plain-language error if any rule is broken.
 
 ## The layered layout
 
@@ -126,19 +125,19 @@ top-level subdirectories plus a workspace-root `log.md`:
 | `90_meta/` | Wiki agent | Taxonomy (`taxonomy.md`), schemas, health reports (`90_meta/health/<date>.md`), migration records (`90_meta/health/pre-migrate-<date>/`). |
 | `log.md` | Wiki agent (append-only) | One line per write. Drives the dashboard timeline. |
 
-The DM agent can read wiki search and index routes, but only the
+The DM agent can read the wiki search and index routes, but only the
 wiki process keys (`wiki.ingest_url`, `wiki.compile`, `wiki.ask`,
-`wiki.lint`, `wiki.trace`, `wiki.connect`) can write into these
-layers. The chokepoint is `POST /api/wiki/:workspace/files/:path` —
-the route validates the layer the path resolves into and rejects
-writes to `00_inbox/` unconditionally.
+`wiki.lint`, `wiki.trace`, `wiki.connect`) may write into these
+layers. Every write funnels through one route,
+`POST /api/wiki/:workspace/files/:path`, which checks which layer the
+path lands in and always rejects writes to `00_inbox/`.
 
 ## Multi-workspace addressing
 
-Every wiki bang command accepts an optional `@<name>` token
-immediately after the bang to target a specific workspace. The token
-is parsed before the command's own argument parser sees the rest, so
-multi-word topics and comma-separated arguments work as normal:
+Every wiki bang command takes an optional `@<name>` token right
+after the bang to aim at a specific workspace. Aitne reads this token
+before the command parses the rest of the line, so multi-word topics
+and comma-separated arguments still work as usual:
 
 ```
 !compile @research full
@@ -146,15 +145,15 @@ multi-word topics and comma-separated arguments work as normal:
 !connect @research diffusion models, score matching
 ```
 
-Omit the token and the command targets the **default** workspace —
-in practice the oldest active workspace (lowest id), which is the one
-named `default` on a fresh install, or the next-oldest active
-workspace if `default` has been archived.
+Leave the token off and the command targets the **default**
+workspace — in practice the oldest active workspace (lowest id). That
+is the one named `default` on a fresh install, or the next-oldest
+active workspace if `default` has been archived.
 
-A workspace name after `@` must start with a letter or digit and then
-contain only letters, digits, `.`, `_`, or `-` (max 64 chars). An
-invalid token is rejected with a usage error rather than silently
-falling back to the default.
+A workspace name after `@` must start with a letter or digit, and the
+rest may contain only letters, digits, `.`, `_`, or `-` (max 64
+chars). An invalid token gets a usage error rather than a silent
+fall-back to the default.
 
 See [guides/multiple-wikis-for-multiple-domains](../../guides/multiple-wikis-for-multiple-domains.md)
 for a walkthrough.
@@ -172,18 +171,18 @@ write. Three values:
   running). Used for external vaults that live in sandboxed
   locations (typically iCloud-synced vaults) where direct fs writes
   fail with `EPERM` / `EACCES` / `EROFS` / `EBUSY`.
-- **`auto`** — the resolver tries `fs` first, falls back to `cli`
-  on those sandbox error codes, and persists the resolved value back
-  to the row so subsequent writes skip the probe.
+- **`auto`** — tries `fs` first, falls back to `cli` on those
+  sandbox error codes, and saves the value it settled on back to the
+  row so later writes skip the check.
 
 Internal workspaces are pinned to `fs`. External workspaces start in
-`auto` and self-tune. You can override the resolved value from
-`/settings/wiki` if you need to force one path or the other (e.g. to
-test the CLI path on a non-sandboxed vault).
+`auto` and tune themselves. You can override the resolved value from
+`/settings/wiki` if you need to force one path or the other (for
+example, to test the CLI path on a non-sandboxed vault).
 
-The resolved strategy is surfaced in the workspace API response and
-on the `/settings/wiki` row, so you can always see which path
-(`fs` or `cli`) `auto` settled on. The full design is in
+The resolved strategy shows up in the workspace API response and on
+the `/settings/wiki` row, so you can always see which path (`fs` or
+`cli`) `auto` settled on. The full design is in
 WIKI_BUILDER_DESIGN.md §P2.B / §8.
 
 ## Dispatch mode (`parallel` / `serial`)
@@ -191,13 +190,13 @@ WIKI_BUILDER_DESIGN.md §P2.B / §8.
 `!ingest` honours the per-workspace **dispatch mode** in
 `/settings/wiki`:
 
-- **Parallel** (default): all URLs fan out simultaneously up to the
-  per-URL concurrency cap (`wiki_workspaces.concurrency_cap`, default
-  `3`, valid range 1–10). Fastest; small risk of bursting rate
-  limits at the URL host.
-- **Serial**: URLs are enqueued in submitted order; each agent
-  session starts only after the previous one completes. Slower but
-  predictable budget and rate.
+- **Parallel** (default): all URLs run at once, up to the per-URL
+  concurrency cap (`wiki_workspaces.concurrency_cap`, default `3`,
+  valid range 1–10). Fastest, with a small risk of tripping rate
+  limits at the URL's host.
+- **Serial**: URLs run in the order you submitted them; each agent
+  session starts only after the previous one finishes. Slower, but
+  the budget and request rate stay predictable.
 
 The acknowledgement DM tells you which mode ran
 (`in parallel` / `serially`).
@@ -205,10 +204,10 @@ The acknowledgement DM tells you which mode ran
 ## Language
 
 `wiki_workspaces.language` is the workspace's content language. It
-defaults to `en` and is independent of `runtimeSettings.primaryLanguage`
-— see WIKI_BUILDER_DESIGN.md §14 Q2 for the reasoning. You can pick
-any language tag from the picker in `/settings/wiki`; the value is
-passed to the wiki skills as the target language for compiled
+defaults to `en` and is separate from `runtimeSettings.primaryLanguage`
+— see WIKI_BUILDER_DESIGN.md §14 Q2 for the reasoning. Pick any
+language tag from the picker in `/settings/wiki`; Aitne passes that
+value to the wiki skills as the target language for compiled
 articles, ask answers, and trace / connect outputs.
 
 The wiki language does **not** cascade from your primary language at
@@ -217,16 +216,16 @@ wiki in English, and vice versa.
 
 ## Archive vs delete
 
-- **Archive** — flips `active=0` on the row but keeps the on-disk
+- **Archive** — sets `active=0` on the row but keeps the on-disk
   data and the row's metadata. Bang commands cannot target an
-  archived workspace; the dashboard hides it from the active list
-  but surfaces it in an "Archived" collapsible. You can unarchive by
-  re-enabling the workspace.
-- **Delete** — drops the row. On-disk data is **not** removed for
-  external workspaces (the daemon never deletes the user's vault).
-  For internal workspaces, the disk tree is also left in place under
-  `$PA_DATA_DIR/context/knowledge/wiki/<name>` — recover by re-creating
-  a workspace at the same name.
+  archived workspace; the dashboard hides it from the active list and
+  tucks it into an "Archived" collapsible. Re-enable the workspace to
+  unarchive it.
+- **Delete** — drops the row. The on-disk data is **not** removed for
+  external workspaces (the daemon never deletes your vault). For
+  internal workspaces, the disk tree is also left in place under
+  `$PA_DATA_DIR/context/knowledge/wiki/<name>` — to recover, create a
+  workspace again with the same name.
 
 ## Fields and defaults reference
 
@@ -250,5 +249,5 @@ Quick map between the dashboard knobs and the `wiki_workspaces` row:
 | Active | `active` | `1` |
 
 `dm_agent_write_enabled=0` is the safe default — the DM agent can
-only call the read-side wiki routes; writes happen inside dedicated
-`wiki.*` sessions spawned by bang commands.
+only call the read-side wiki routes. Writes happen inside dedicated
+`wiki.*` sessions that bang commands spawn.

package/agent-assets/docs/getting-started/01-what-is-this.md

@@ -18,7 +18,6 @@ summary: |
   Markdown files.
 section: getting-started
 tags:
-  - core
   - getting-started
   - backends
 status: stable
@@ -42,7 +41,7 @@ keywords:
   - markdown memory
   - backends
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 context_files:
   - state/today.md
   - plans/roadmap.md
@@ -59,7 +58,7 @@ related:
 # What is Aitne?
 
 Aitne is a local-first personal AI agent. It runs as a long-running
-daemon on your own machine, drives Claude Code, Codex CLI, Gemini
+background program (a daemon) on your own machine, drives Claude Code, Codex CLI, Gemini
 CLI, or OpenCode (`@opencode-ai/sdk` server) via provider API keys
 you register (with the CLI's local subscription login as a
 fallback), and keeps all of its memory as plain Markdown files under
@@ -122,7 +121,7 @@ decides what (if anything) is worth telling you about.
 
 - [Mail](../features/integrations/mail.md) — Gmail, Outlook, Yahoo,
   iCloud, or any IMAP server. Searches your messages locally via
-  FTS5. Auto-classifies into
+  FTS5 (SQLite's built-in full-text search). Auto-classifies into
   [reading list](../features/lifestyle/reading.md),
   [receipts](../features/lifestyle/receipts.md), and
   [travel bookings](../features/lifestyle/travel-bookings.md).

package/agent-assets/docs/getting-started/02-first-steps.md

@@ -14,7 +14,6 @@ summary: |
   pair a messaging app, and arrive at a green health pill.
 section: getting-started
 tags:
-  - core
   - getting-started
   - setup
 status: stable
@@ -31,7 +30,7 @@ keywords:
   - dashboard onboarding
   - health pill
 created: 2026-04-27
-updated: 2026-06-07
+updated: 2026-07-01
 related:
   - getting-started/01-what-is-this
   - getting-started/03-what-can-this-do
@@ -70,19 +69,19 @@ skippable in the wizard. Run through it once, top to bottom.
    the daemon claims you as the owner. See
    [Messaging Overview](../features/messaging/overview.md) for the
    list of supported apps and what each one does well.
-3. **Pick a main backend and register an API key.** Pick the LLM
+3. **Pick a main backend and register an API key.** This is the LLM
    the agent uses for "think hard" turns (Claude / Codex / Gemini /
-   OpenCode) and paste a provider API key — the supported way to run
-   a headless agent. If you skip the key, the daemon falls back to
-   whatever subscription login the matching CLI already has on your
-   machine; the dashboard surfaces a warning when this happens
-   because most providers do not support running agents on a
-   personal subscription. The same picker also lets you point the
+   OpenCode). Paste a provider API key — that is the supported way
+   to run the agent unattended (with no human signed in). If you skip
+   the key, the daemon falls back to whatever subscription login the
+   matching CLI already has on your machine, and the dashboard shows
+   a warning, because most providers do not support running agents on
+   a personal subscription. The same picker can instead point the
    backend at a cloud provider (Bedrock / Vertex / Foundry / Azure
-   OpenAI / Gemini-Vertex) instead of the direct API key — the
-   provider dropdown on `/settings/models` is the single surface for
-   both direct keys and cloud-provider credentials. Defaults are
-   sensible and can be changed later from `/settings/models`.
+   OpenAI / Gemini-Vertex) rather than a direct API key — the provider
+   dropdown on `/settings/models` is the single place for both direct
+   keys and cloud-provider credentials. The defaults are sensible, and
+   you can change them later from `/settings/models`.
    Background: [Backends and Tiers](../concepts/backends-and-tiers.md).
 4. **Skip integrations you do not need yet.** Mail, calendar, git,
    Notion, Obsidian are all optional and re-runnable any time from

package/agent-assets/docs/getting-started/03-what-can-this-do.md

@@ -14,7 +14,6 @@ summary: |
   granularity, with a link to the detailed feature doc for each.
 section: getting-started
 tags:
-  - core
   - getting-started
   - routines
   - messaging
@@ -35,7 +34,7 @@ keywords:
   - wiki
   - lifestyle
 created: 2026-04-27
-updated: 2026-05-28
+updated: 2026-07-01
 related:
   - getting-started/01-what-is-this
   - getting-started/02-first-steps
@@ -110,16 +109,17 @@ them — the agent reads what's there next time it runs.
 
 ## Build a personal wiki from what you DM
 
-A workspace-scoped builder turns URLs, pastes, and notes you send into a
-linked Markdown wiki. The raw capture, the synthesised article, and the
-cited answer all stay on disk and the agent only writes via the daemon
-API so the layout invariants hold.
+Send the agent URLs, pastes, or notes and it builds them into a linked
+Markdown wiki inside a dedicated workspace. The raw capture, the
+synthesized article, and any cited answer all stay as files on disk. The
+agent writes only through the daemon API, which keeps the folder layout
+consistent.
 
 - [Wiki Overview](../features/wiki/overview.md) — the workspace concept,
   the `00_inbox` / `10_raw` / `20_wiki` / `30_outputs` layers, and the
   approval gate on full rebuilds.
 - [Wiki Commands](../features/wiki/commands.md) — `!ingest` (capture
-  URLs), `!compile` (synthesise), `!ask` (cited Q&A), `!lint` /
+  URLs), `!compile` (synthesize), `!ask` (cited Q&A), `!lint` /
   `!trace` / `!connect` (audit, history, bridges), `!wiki` (status).
 - [Build Your Wiki](../guides/build-your-wiki.md) — the first-day
   walkthrough from empty workspace to first answered question.

package/agent-assets/docs/getting-started/04-first-day.md

@@ -15,7 +15,6 @@ aliases:
   - day zero
 section: getting-started
 tags:
-  - core
   - getting-started
   - setup
   - integrations
@@ -52,7 +51,7 @@ context_files:
 api_endpoints:
   - POST /api/knowledge/import
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 related:
   - getting-started/02-first-steps
   - getting-started/03-what-can-this-do
@@ -119,9 +118,9 @@ Send 3–5 DMs that read like introductions to a new assistant:
 
 The agent appends each fact to the right `identity/*.md` file (work
 facts → `identity/work.md`, people → `identity/people.md`, preferences →
-`identity/personal.md`, and so on). Identity-class facts (legal name,
-primary timezone) are deferred for your explicit confirmation
-rather than auto-written.
+`identity/personal.md`, and so on). Identity-class facts (your legal
+name, your primary timezone) wait for you to confirm them instead of
+being written automatically.
 
 ### Bootstrap from ChatGPT, Gemini, or anywhere else
 

package/agent-assets/docs/glossary.md

@@ -13,9 +13,7 @@ summary: |
   Single flat term list for Aitne vocabulary. Cross-references
   link to a single canonical anchor here so concept docs do not drift.
 tags:
-  - core
-  - reference
-  - glossary
+  - knowledge
 status: stable
 ask_examples:
   - What is a ProcessKey?
@@ -35,7 +33,7 @@ ask_examples:
   - What is an observation?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - terminology
   - vocabulary
@@ -102,7 +100,7 @@ and rationale.
 
 ## Backend
 
-One of the model providers Aitne can dispatch to: `claude`
+One of the AI model providers Aitne can send work to: `claude`
 (Claude Code SDK), `codex` (Codex CLI), `gemini` (Gemini CLI), or
 `opencode` (`@opencode-ai/sdk` HTTP server). Each backend is configured
 per-installation; one is the **main backend**, and the others can be
@@ -110,12 +108,13 @@ enabled as fallbacks.
 
 ## Browser History (B-3)
 
-Local-only history poller that reads the browser's own SQLite database
+A local-only poller that reads the browser's own SQLite history database
 (Chromium-based browsers — Chrome, Chromium, Edge, Brave, Comet, Atlas)
-and records page visits as observations. Drives the **research cluster** derivation, the weekly
-reload-memory block, and the [`!checks`](features/messaging/bang-commands.md)
-on-demand reload tally. No content is uploaded; only URLs, titles, and
-visit timings the browser itself recorded. See
+and records page visits as observations. It feeds the **research cluster**
+derivation, the weekly reload-memory block, and the
+[`!checks`](features/messaging/bang-commands.md) on-demand reload tally.
+Nothing is uploaded — only the URLs, titles, and visit timings the browser
+itself already recorded. See
 [Browser History](features/integrations/browser-history.md).
 
 ## Managed Chromium (B-4)
@@ -146,8 +145,9 @@ enabled custom commands appear in `!help`. See
 
 ## Backend Router
 
-The component that resolves a `ProcessKey` to a concrete `(backend,
-model, maxTurns, maxBudgetUsd)` binding at dispatch time. Lives in
+The component that turns a `ProcessKey` into a concrete `(backend,
+model, maxTurns, maxBudgetUsd)` binding at dispatch time (the moment an
+invocation is handed to a backend). Lives in
 `packages/daemon/src/core/backends/backend-router.ts`. Routing reads
 `process_backend_config` (per-process pins) layered over
 `backend_global_defaults` (installation-wide defaults).
@@ -160,8 +160,8 @@ matching anchor.
 
 ## Day Boundary
 
-The hour-of-day at which the agent day rolls over. Configured via
-`dayBoundaryHour` (default `4`).
+The hour of the day when the agent day rolls over (when "today" starts
+fresh). Configured via `dayBoundaryHour` (default `4`).
 
 ## deniedTools
 
@@ -262,7 +262,7 @@ in 2026-05 to trim morning-routine input tokens by ~24%.
 
 ## Observation
 
-One row in the `observations` table. A change record a polling
+One row in the `observations` table. A change record that a polling
 integration (Obsidian, Git, Notion, calendar, mail, browser history)
 or a `routine.fetch_window` pre-pass wrote into SQLite. The
 `routine.activity_scan` is the consumer — there is no per-change
@@ -272,7 +272,8 @@ to break the agent-observing-its-own-writes loop. See
 
 ## ProcessKey
 
-The branded string identifier for a class of agent invocation, e.g.
+The typed string identifier (a "branded" string in the TypeScript code)
+for a class of agent invocation, e.g.
 `routine.morning_routine`, `message.dm`, `dashboard.docs_qa`. Drives
 backend selection, skill manifest, agent profile, and task-flow
 template lookup. Defined in `packages/shared/src/process-key.ts`.

package/agent-assets/docs/guides/add-a-custom-routine.md

@@ -18,12 +18,10 @@ summary: |
   prompt for every run; runs appear on the Agent's detail page.
 section: add-a-custom-routine
 tags:
-  - guides
   - agents
   - routines
   - scheduler
   - autonomous
-  - core
 status: stable
 ask_examples:
   - How do I create a recurring agent?
@@ -32,7 +30,7 @@ ask_examples:
   - Where do I see my agent's runs?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - recurring agent
   - new agent
@@ -60,8 +58,8 @@ related:
 
 ## Goal
 
-Make the agent fire a particular kind of work on a schedule you pick —
-as a user **Agent** you can watch, tune, and toggle from `/agents`.
+Run a task you write on a schedule you pick, packaged as a user
+**Agent** you can watch, tune, and toggle from `/agents`.
 
 ## Prerequisites
 
@@ -89,7 +87,7 @@ as a user **Agent** you can watch, tune, and toggle from `/agents`.
      becomes the Markdown body of `agent.md` and is the prompt the
      agent receives every time it fires.
    - An **Advanced (YAML)** toggle reveals the raw `agent.md` editor
-     for long-tail fields the form doesn't expose (tags, tools,
+     for the extra fields the form doesn't expose (tags, tools,
      success criteria, error handling).
 3. Save. The dashboard writes `policies/agents/<slug>/agent.md`
    through the context vault and opens the new Agent's detail page;
@@ -114,7 +112,10 @@ curl -X POST http://localhost:8321/api/agents \
 ```
 
 - **`prompt` becomes the Agent's task prompt** — it is stored as the
-  Markdown body of `agent.md` and sent to the agent on every run.
+  Markdown body of `agent.md` and sent to the agent on every run. It
+  must be a real task definition: an empty body or a stand-in like
+  `"placeholder"`/`"TODO"` is rejected as `400 invalid_definition`
+  (the agent would skip every run as too ambiguous to act on).
 - **`schedule`** takes one of two forms: a raw 5-field cron
   (`{ "kind": "cron", "expression": "0 11 * * 2" }`, interpreted in
   the daemon's timezone unless `schedule.timezone` is set) or a
@@ -122,8 +123,8 @@ curl -X POST http://localhost:8321/api/agents \
   "weekly", "daysOfWeek": ["tuesday"], "time": "11:00" } }`).
   `/agents` is recurring-only — a one-time task belongs on
   `POST /api/schedule` instead.
-- **`backend.tier`** is optional; omitted, the Agent inherits the
-  `agent.task` process default (medium). `backend.process_key`
+- **`backend.tier`** is optional; if you omit it, the Agent inherits
+  the `agent.task` process default (medium). `backend.process_key`
   defaults to `agent.task` — you don't need to set it.
 - **`limits`** defaults: 20 turns, $0.25 per run, 10-minute timeout.
 - Success returns `201 { "status": "created", "slug": ... }`. A taken
@@ -152,9 +153,13 @@ curl -X POST http://localhost:8321/api/agents \
 - `400 invalid_definition` — fix the fields listed in `issues`.
 - `400 one_shot_not_supported` — `/agents` is recurring-only; use
   `POST /api/schedule` for one-time work.
-- A prompt that hits the absolute-block guardrails: the run fires but
-  the offending tool call is logged as `blocked_absolute` in the
-  action log.
+- **Run now** returns `409 agent_prompt_placeholder` — the Agent's
+  stored prompt is empty or still a placeholder stub (possible for
+  Agents created before this was validated); write the real task into
+  its `agent.md` and try again.
+- A prompt that trips the absolute-block guardrails — the run still
+  executes, but the offending tool call is logged as `blocked_absolute`
+  in the action log.
 
 ## Migrating From Custom Routines