@aitne-sh/aitne 0.1.12 → 0.1.13

package/agent-assets/docs/reference/process-keys.md

@@ -14,11 +14,8 @@ summary: |
   tier. Mirrors packages/shared/src/process-key.ts.
 section: process-keys
 tags:
-  - core
-  - reference
-  - dispatch
-  - backends
   - routing
+  - backends
 status: stable
 ask_examples:
   - List all the ProcessKeys
@@ -41,7 +38,7 @@ keywords:
   - delegated_task
   - gmail_classify
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 config_keys:
   - monthlyReviewEnabled
   - delegatedTaskHeavyEnabled
@@ -61,12 +58,13 @@ related:
 
 # ProcessKeys
 
-A **ProcessKey** identifies the kind of work being dispatched (an owner DM,
-the morning routine, an activity scan, …). The dispatcher passes a ProcessKey
-to the `BackendRouter`, which resolves it to a `{ main, fallback }` backend
-plus an execution tier — the dispatcher never picks a model directly.
+A **ProcessKey** is a label for one kind of work the agent runs — an owner
+DM, the morning routine, an activity scan, and so on. When a piece of work
+starts, the dispatcher hands its ProcessKey to the `BackendRouter`, which
+turns the key into a `{ main, fallback }` backend pair plus an execution
+tier. The dispatcher itself never picks a model; the router does that.
 
-The **default tier** column maps to a model size, not a specific id:
+The **default tier** column maps to a model size, not to a specific id:
 
 - `lite` → Haiku-class (cheap, fast, narrow)
 - `medium` → Sonnet-class (the default for most owner-facing and routine work)
@@ -128,21 +126,21 @@ The **default tier** column maps to a model size, not a specific id:
 | `routine.research_wiki_summary` | Accept path for the "wiki summary" option — writes a wiki note into Obsidian inbox / Notion / local context per integration availability | medium | yes |
 | `browser_task` | Open-ended browser sub-agent (BROWSER_TASK_REDESIGN_PLAN.md §6.1). Claude-only backend floor; dispatched from `POST /api/browser-task` (DM, dashboard, or scheduler). | medium | yes |
 
-"Configurable" = the operator can override the backend / tier on
-`/settings/models` (i.e. the key appears in `CONFIGURABLE_PROCESS_KEYS`).
-"no" means the binding is fixed and uses the corresponding tier's
-global default.
+**Configurable** means the operator can override the backend or tier for
+that key on `/settings/models` — these are the keys listed in
+`CONFIGURABLE_PROCESS_KEYS`. **no** means the binding is fixed and always
+uses the global default for its tier.
 
 This list mirrors `packages/shared/src/process-key.ts`. The codebase
 is the source of truth.
 
 ## Reactive vs Autonomous
 
-The set `REACTIVE_PROCESS_KEYS` (owner currently in the loop) is:
-`message.dm`, `message.mention`, `dashboard.chat`, `dashboard.docs_qa`,
-`setup`, `knowledge.import`. Every other key is autonomous and runs
-under the tighter Approve-tier MCP tool-stripping that B-003 Phase 3
-established.
+Reactive keys run while the owner is in the loop, waiting on a reply.
+`REACTIVE_PROCESS_KEYS` holds them: `message.dm`, `message.mention`,
+`dashboard.chat`, `dashboard.docs_qa`, `setup`, `knowledge.import`. Every
+other key is autonomous — it runs on its own, under the tighter Approve-tier
+MCP tool-stripping that B-003 Phase 3 established.
 
 ## Tier Locks
 
@@ -160,6 +158,6 @@ by `DELEGATED_TASK_HARD_CAPS` (server-enforced, not user-tunable):
 - `maxTimeoutMs` ≤ 300 000
 - `maxSchemaBytes` ≤ 4096
 
-`config.ts` holds the *defaults* (`delegatedTaskDefaultMaxToolCalls`,
-…); the caps above bound a prompt-injected caller regardless of the
-per-request fields.
+`config.ts` holds the *defaults* (`delegatedTaskDefaultMaxToolCalls`, …),
+but the caps above bound the request even when a prompt-injected caller
+tries to raise the per-request fields.

package/agent-assets/docs/reference/skills.md

@@ -13,8 +13,6 @@ summary: |
   a SKILL.md under agent-assets/skills/<slug>/.
 section: skills
 tags:
-  - core
-  - reference
   - skills
 status: stable
 ask_examples:
@@ -34,7 +32,7 @@ keywords:
   - wiki skill
   - notify skill
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 ui_anchors:
   - /knowledge?tab=skills
 process_keys:
@@ -56,11 +54,13 @@ related:
 
 # Built-in Skills
 
-Aitne ships a fixed set of built-in skills the agent loads per session. Most
-are always available; a few are **conditional** — loaded only when a gating
-flag is set (`gmail-lifestyle`, `managed-tasks`) or only for a specific event
-type (`browser-task` / `background-task` / `background-task-reply`, on owner
-DMs). The table below is the canonical roster.
+A skill is a small instruction file that teaches the agent how to do one job.
+Aitne ships a fixed set of built-in skills, and the agent loads the ones it
+needs at the start of each session. Most are always available. A few are
+**conditional** — the agent loads them only when a gating flag turns them on
+(`gmail-lifestyle`, `managed-tasks`), or only for a specific event such as an
+owner DM (`browser-task` / `background-task` / `background-task-reply`). The
+table below is the full, authoritative roster.
 
 | Slug | Purpose |
 |---|---|
@@ -94,14 +94,16 @@ DMs). The table below is the canonical roster.
 
 ## How skills are sourced
 
-The source of truth is each skill's `SKILL.md` under
-`agent-assets/skills/<slug>/`. The `description` field in that file's
-frontmatter is what the dispatcher uses for runtime skill selection.
+Each skill is defined by its own `SKILL.md` file under
+`agent-assets/skills/<slug>/` — that file is the single source of truth. The
+`description` field at the top of that file (its frontmatter) is the text the
+dispatcher reads when it decides which skills to load for a session.
 
 ## Runtime overlays
 
-A subset of these skills' sections (knowledge layout, routing tables, search
-recipes, etc.) is refined at runtime through JSON **overlays** maintained by
-the skill-curation loop. The seed files in `agent-assets/skills/` are never
-rewritten — overlays are applied at session-init by the `SkillsCompiler` and
-live under `<dataDir>/skill-curation-overlays/<slug>/<section-id>.json`.
+Some sections of these skills (knowledge layout, routing tables, search
+recipes, and the like) can be refined at runtime through JSON **overlays** — small
+patches maintained by the skill-curation loop. The shipped seed files in
+`agent-assets/skills/` are never rewritten. Instead, the `SkillsCompiler`
+applies the overlays when a session starts, reading them from
+`<dataDir>/skill-curation-overlays/<slug>/<section-id>.json`.

package/agent-assets/docs/troubleshooting/auth-failed.md

@@ -12,7 +12,6 @@ summary: |
   via the backend's CLI or paste a fresh API key.
 section: troubleshooting
 tags:
-  - troubleshooting
   - safety
   - backends
   - health
@@ -23,7 +22,7 @@ ask_examples:
   - The auth-health pill went red, what now?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - auth failed
   - auth error
@@ -56,16 +55,18 @@ api_endpoints:
 
 ## Most Likely Causes
 
-1. **Provider API key revoked or rotated** — the most common cause
-   on a healthy install. Re-paste the key on `/settings/models`.
+1. **Provider API key revoked or rotated** (replaced with a new one) —
+   the most common cause on a healthy install. Re-paste the key on
+   `/settings/models`.
 2. **Subscription-fallback login expired** when no API key was
-   registered (the daemon was running on the CLI's local login —
-   `claude auth login`, `codex login`, `gemini` — and that session
-   timed out). The recommended fix is to register an API key.
-3. **Account-level scope change** at the provider (key disabled,
-   project deleted, billing suspended). For cloud-provider auth
-   (Bedrock / Vertex / Foundry for Claude, Vertex AI for Gemini),
-   IAM-role / service-account changes show up the same way.
+   registered. This means the daemon was signed in through the CLI's
+   local login — `claude auth login`, `codex login`, `gemini` — and
+   that session timed out. The recommended fix is to register an API key.
+3. **Account-level change** at the provider (key disabled, project
+   deleted, billing suspended). If you use cloud-provider auth
+   (Bedrock / Vertex / Foundry for Claude, Vertex AI for Gemini), a
+   change to the underlying IAM role or service account shows up the
+   same way.
 
 ## Diagnostic Steps
 
@@ -109,3 +110,4 @@ probe (default 10 minutes).
 ## Related
 
 - [Auth Health](../concepts/auth-health.md)
+- [Dashboard Shows Degraded](./dashboard-shows-degraded.md)

package/agent-assets/docs/troubleshooting/dashboard-shows-degraded.md

@@ -18,7 +18,6 @@ summary: |
 section: troubleshooting
 status: stable
 tags:
-  - troubleshooting
   - operations
   - health
   - memory
@@ -28,7 +27,7 @@ ask_examples:
   - Why are context writes being refused with 503?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - degraded
   - degraded banner
@@ -61,17 +60,18 @@ related:
   followed by the offending path.
 - An **Open Management Mode** button on the right of the banner (links to
   Settings → Management Mode).
-- Any routine or skill that touches a context file fails: while degraded the
+- Any routine or skill that touches a memory file fails. While degraded, the
   context API returns **HTTP 503** for every request — reads (`GET`) as well as
-  writes (`POST`/`PUT`/`PATCH`/`DELETE`) — so the agent never reads or writes a
-  stale fallback location.
+  writes (`POST`/`PUT`/`PATCH`/`DELETE`). This is on purpose: it stops the agent
+  from quietly falling back to the wrong, out-of-date location.
 
 ## What "Degraded" Actually Means
 
-Degraded mode is set by the daemon's vault-health probe, which re-runs every
-30 seconds. It is **not** about backend auth, message delivery, or a stuck
-write lock — it is specifically about the daemon being unable to safely write
-your memory files.
+Every 30 seconds the daemon runs a vault-health probe — a quick background
+check on the folder that holds your memory files. If that check fails, the
+daemon switches to degraded mode. It is **not** about backend auth, message
+delivery, or a stuck write lock — it means only one thing: the daemon can't
+safely write your memory files right now.
 
 You only see this banner if you switched memory to an **Obsidian-style vault**
 (`vaultMode: "obsidian"`). The default `vaultMode: "plain"` stores memory under
@@ -83,7 +83,7 @@ The `reason` in the banner is one of:
 |--------------------------------|---------|
 | `primary_vault_unreachable`    | The configured vault path doesn't exist, isn't a directory, or isn't writable (e.g. an external drive was unplugged). |
 | `primary_vault_not_configured` | Vault mode is Obsidian but no `primaryVaultPath` is set. |
-| `primary_vault_missing_content`| The path is reachable but doesn't carry the expected vault markers (it was never seeded / restructured). |
+| `primary_vault_missing_content`| The path is reachable but is missing the marker files that identify a set-up vault (it was never seeded, or was moved/restructured). |
 
 A context-vault migration (`POST /api/setup/migrate-context`) is a **separate**
 state, not a degraded reason — it does **not** raise this banner. During a

package/agent-assets/docs/troubleshooting/fallback-keeps-firing.md

@@ -17,7 +17,6 @@ summary: |
 section: fallback-keeps-firing
 status: stable
 tags:
-  - troubleshooting
   - backends
   - routing
   - health
@@ -53,15 +52,16 @@ related:
   - concepts/backends-and-tiers
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 ---
 
 # Fallback Keeps Firing
 
-The backend router resolves every run to a `{ main, fallback }` pair. When
-the main backend can't take the work, the router transparently switches to
-the fallback so the run still completes. If that happens once, it's normal.
-If it happens run after run, the main backend has a persistent problem.
+For every run, the router picks two backends: a `main` and a `fallback`. (A
+backend is the service that does the actual work — Claude, Codex, or Gemini.)
+When the main backend can't take the job, the router quietly switches to the
+fallback so the run still finishes. One switch now and then is normal. A
+switch on run after run means the main backend has a lasting problem.
 
 ## What you see
 
@@ -70,32 +70,34 @@ If it happens run after run, the main backend has a persistent problem.
 
 ## Most likely causes
 
-1. **Main backend's auth has expired.** The most common cause — the CLI
-   credentials (or API key) for the main backend are no longer valid, so
-   every run raises a `BackendDecisiveFailure("auth")` and the router falls
-   over.
-2. **Main backend's usage window is exhausted.** Claude and Codex meter
-   usage per rolling window; Gemini also hits its per-day free-tier cap.
-   When the limit is reached the backend raises a `BackendQuotaError` and
-   the router falls over until the window resets.
-3. **A repeating `BackendDecisiveFailure` from a config issue** — e.g. the
-   main backend's CLI isn't installed, a pinned model id no longer
-   resolves, or execution-mode settings reject the run.
+1. **The main backend's auth has expired.** This is the most common cause.
+   The CLI credentials (or API key) for the main backend are no longer
+   valid, so every run raises a `BackendDecisiveFailure("auth")` and the
+   router falls over.
+2. **The main backend's usage window is used up.** Claude and Codex count
+   usage against a rolling window (a limit that refills over time); Gemini
+   also has a per-day free-tier cap. Once the limit is reached, the backend
+   raises a `BackendQuotaError` and the router falls over until the window
+   resets.
+3. **A repeating `BackendDecisiveFailure` from a config problem** — for
+   example, the main backend's CLI isn't installed, a pinned model id no
+   longer resolves, or execution-mode settings reject the run.
 
 `BackendQuotaError` and `BackendDecisiveFailure` are the two signals the
-router watches; one of them is firing on every attempt.
+router watches, and one of them is firing on every attempt.
 
 ## Diagnose
 
 1. **Check auth on `/settings/models`.** Each backend has a card showing
    its auth status. If the main backend's card flags expired or failed
    auth, that's your cause — re-verify or re-authenticate it there.
-2. **Check quota/spend on `/analytics` (Cost tab).** Look at the main
-   backend's recent spend. A flat ceiling or a depleted window points to
-   cause 2. If you set `autonomousDailyCostCapUsd`, autonomous runs also
-   stop once the daily cap is hit (reactive DMs are never blocked by it).
-3. **Read the failure detail in `/activity`.** Open the offending row to
-   see the exact error. From the CLI you can do the same:
+2. **Check quota and spend on `/analytics` (Cost tab).** Look at the main
+   backend's recent spend. Spend that flattens against a ceiling, or a
+   window that has run dry, points to cause 2. If you set
+   `autonomousDailyCostCapUsd`, autonomous runs also stop once the daily
+   cap is hit (reactive DMs are never blocked by it).
+3. **Read the failure detail in `/activity`.** Open the row that fell over
+   to see the exact error. You can do the same from the CLI:
 
    ```bash
    # recent runs on the main backend that didn't succeed

package/agent-assets/docs/troubleshooting/messaging-not-pairing.md

@@ -16,13 +16,12 @@ summary: |
   DM, or the message landed in a group instead of a direct channel.
 section: messaging
 tags:
-  - troubleshooting
   - messaging
   - pairing
 status: stable
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - magic phrase
   - owner channel
@@ -53,8 +52,8 @@ deep link (Telegram / WhatsApp), the pairing card on
 
 ## Know which secret your platform uses
 
-Not every platform uses the typed phrase, so the fix depends on the
-platform:
+Not every platform uses a typed phrase, so the right fix depends on which
+one you are pairing:
 
 | Platform | Secret | How you send it |
 |---|---|---|
@@ -69,11 +68,11 @@ All secrets are single-use and expire after **5 minutes**.
 
 1. **The secret expired.** The phrase or token is only valid for 5
    minutes. If you took longer, it has lapsed — regenerate a fresh one.
-2. **You wrapped the phrase in a sentence (Slack / Discord).** The
-   matcher requires the four words to be the **only** content of the
-   message. Sending "my phrase is apple-banana-cherry-date" is rejected
-   by design, and the agent replies asking you to send the phrase on its
-   own. Matching otherwise ignores case, punctuation, and emoji.
+2. **You wrapped the phrase in a sentence (Slack / Discord).** The four
+   words have to be the **only** thing in the message. Sending "my phrase
+   is apple-banana-cherry-date" is turned down on purpose, and the agent
+   replies asking you to send the phrase on its own. Aside from that, the
+   check ignores capitalization, punctuation, and emoji.
 3. **You sent it in a group or channel.** Pairing — and all agent
    messaging — works only in a one-to-one DM. Group chats are out of
    scope.

package/agent-assets/docs/troubleshooting/morning-routine-didnt-run.md

@@ -16,11 +16,10 @@ summary: |
   boot/wake catch-up, the missed-fire self-heal, or the retry chain.
 section: morning-routine-didnt-run
 tags:
-  - troubleshooting
   - routines
   - autonomous
   - scheduler
-  - dispatch
+  - routing
 status: stable
 ask_examples:
   - Why didn't my morning routine fire?
@@ -28,7 +27,7 @@ ask_examples:
   - How do I regenerate today.md by hand?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - morning routine didn't run
   - morning routine skipped
@@ -74,24 +73,25 @@ without any action from you:
   So a missed routine often resolves itself on the next `aitne start`
   or `aitne restart`.
 - **Sleep wake catch-up.** If the machine was asleep at the trigger
-  minute (laptop lid closed at 04:00), the cron fire is silently lost —
-  cron never replays missed ticks. The daemon detects the wall-clock
-  gap when the machine wakes and queues the morning routine itself,
-  along with any missed evening/weekly reviews.
+  minute (laptop lid closed at 04:00), the scheduled trigger is
+  silently lost — the scheduler (cron) never replays a tick it missed.
+  When the machine wakes, the daemon spots the gap in wall-clock time
+  and queues the morning routine itself, along with any missed evening
+  or weekly reviews.
 - **Missed-fire self-heal.** A periodic check (every 10 minutes)
   notices when the day is more than ~15 minutes old with no morning
   attempt and nothing queued, and queues the routine. This covers
   sleeps too short for the wake detector and any other lost trigger.
 - **Retry on failure.** If the routine runs but fails to produce a
-  fresh `state/today.md`, the daemon retries up to 3 times with an
-  exponential back-off (5, then 10, then 15 minutes). After 3 failed
-  attempts it sends you a DM asking you to regenerate manually.
-- **Hung-run recovery.** If a run starts and then wedges (typically a
-  sleep mid-run that kills the backend connection), the self-heal
-  check re-queues it once the run has been silent past the stall
-  threshold (~2 hours by default) — at most twice per day, after which
-  it alerts instead of re-running. Either way you get an owner DM so
-  the silence never goes unnoticed.
+  fresh `state/today.md`, the daemon retries up to 3 times, waiting a
+  little longer between each try (5, then 10, then 15 minutes). After 3
+  failed attempts it sends you a DM asking you to regenerate manually.
+- **Hung-run recovery.** If a run starts and then gets stuck (usually
+  the machine sleeps mid-run and drops the backend connection), the
+  self-heal check re-queues it once the run has stayed silent past the
+  stall threshold (~2 hours by default) — at most twice per day, after
+  which it alerts you instead of re-running. Either way you get an owner
+  DM, so the silence never goes unnoticed.
 
 Give it a few minutes, or restart the daemon, before digging deeper.
 
@@ -111,8 +111,9 @@ Give it a few minutes, or restart the daemon, before digging deeper.
    run. See [Quota Exhausted](quota-exhausted.md).
 4. **Mid-retry.** The routine threw and is in the 5/10/15-minute
    retry window — the row may simply not have landed yet.
-5. **Day-boundary subtlety.** Before `dayBoundaryHour` (default 04:00),
-   the routine still "belongs to" yesterday — see
+5. **Day-boundary subtlety.** Before the agent-day boundary (the moment
+   "today" rolls over, set by `dayBoundaryHour`, default 04:00), the
+   routine still "belongs to" yesterday — see
    [Agent Day](../concepts/agent-day.md).
 
 Note: the morning routine takes priority over the activity scan, not the

package/agent-assets/docs/troubleshooting/observation-not-detected.md

@@ -15,10 +15,8 @@ summary: |
   watched, or a change the agent authored itself (filtered out).
 section: troubleshooting
 tags:
-  - troubleshooting
   - observations
   - polling
-  - activity-scan
 status: stable
 ask_examples:
   - Why didn't the agent notice my new commit?
@@ -26,7 +24,7 @@ ask_examples:
   - Why is the activity scan empty?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - observation
   - polling
@@ -64,16 +62,17 @@ gate. Work through them in that order.
 
 ## How detection actually works
 
-Observers (Obsidian, Git, Notion, Calendar) do **not** fire an event per
-change. They poll on a cadence and call `recordObservation(...)`, which
-appends a row to the `observations` table. The activity scan later reads those
-rows in a single batch. So a "missing" observation is usually a row that was
-never written, or one that was written but filtered.
+Observers (Obsidian, Git, Notion, Calendar) do **not** fire an event the
+instant something changes. Instead they poll — check the source on a fixed
+schedule — and each time they call `recordObservation(...)`, which appends a
+row to the `observations` table. The activity scan later reads those rows in
+one batch. So a "missing" observation is usually a row that was never written,
+or one that was written but then filtered out.
 
-`AgentWriteTracker` tags every change as `actor='agent'` or `actor='user'`.
-Changes the agent itself wrote are tagged `actor='agent'` and skipped by the
-activity scan — this is the deliberate anti-loop filter that stops the agent
-from observing its own output.
+`AgentWriteTracker` tags every change as either `actor='agent'` or
+`actor='user'`. Changes the agent wrote itself are tagged `actor='agent'` and
+skipped by the activity scan. This is a deliberate anti-loop filter: it keeps
+the agent from reacting to its own output.
 
 ## Most likely causes
 
@@ -85,9 +84,9 @@ from observing its own output.
 3. **The change was tagged `actor='agent'`.** If the agent (not you) authored
    the commit or note, the anti-loop filter drops it.
 4. **It was below the gate threshold.** The activity scan only runs its full
-   pass when at least the activity-scan agent's **min observations**
-   threshold (default `1`; legacy key `activityScanMinObservations`) of
-   pending observations exists. A single low-signal change can be held back.
+   pass once the number of pending observations reaches the activity-scan
+   agent's **min observations** threshold (default `1`; legacy key
+   `activityScanMinObservations`). A single low-signal change can be held back.
 
 ## Diagnostic steps
 

package/agent-assets/docs/troubleshooting/quota-exhausted.md

@@ -14,7 +14,6 @@ summary: |
   spending limit, or pin a different model.
 section: quota-exhausted
 tags:
-  - troubleshooting
   - cost
   - backends
   - quotas
@@ -26,7 +25,7 @@ ask_examples:
   - Why did an autonomous run get skipped for the cost cap?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - quota
   - BackendQuotaError
@@ -51,37 +50,40 @@ related:
 ## What You See
 
 - A `BackendQuotaError` row in Activity.
-- Fallback ran the next routine instead of main.
-- Or: an autonomous run was skipped with reason
-  `autonomous_cost_cap_exceeded` — this is a *separate* safety net
-  (`autonomousDailyCostCapUsd`, default off) that skips only autonomous
-  work, never reactive DMs. (`autonomousMonthlyCostCapUsd`, also default
-  off, is notifications-only — it never skips a run, just alerts.)
-  It is not a provider quota error; raise the cap on `/settings/models`
-  or wait for the next agent day.
+- The fallback backend ran the next routine instead of the main one.
+- Or: an autonomous run was skipped with the reason
+  `autonomous_cost_cap_exceeded`. This is a *separate* safety net, not a
+  provider quota error. It comes from `autonomousDailyCostCapUsd` (default
+  off), which skips only autonomous work and never touches reactive DMs.
+  Its sibling `autonomousMonthlyCostCapUsd` (also default off) only sends
+  a notification — it alerts you but never skips a run. To clear the skip,
+  raise the cap on `/settings/models` or wait for the next agent day (the
+  moment "today" rolls over, 04:00 local by default).
 
 ## Most Likely Causes
 
 1. **Provider rate limit** on your API key (Anthropic / OpenAI /
-   Google) — the supported path. Check the provider console for the
-   per-minute / per-day caps tied to your billing.
+   Google). Running on an API key is the supported path. Check the
+   provider console for the per-minute / per-day caps tied to your
+   billing.
 2. **Gemini per-agent-day request ceiling** reached. Aitne caps
-   Gemini at 450 model requests per agent day (a conservative fraction
-   of Google's free-tier daily limit on `GEMINI_API_KEY` /
-   `GOOGLE_API_KEY` without billing). This ceiling is Gemini-only and
-   model-agnostic — it is not tied to any one model id. The error reads
-   "Gemini daily-request ceiling reached" and resets at the next
-   agent-day boundary (04:00 local).
+   Gemini at 450 model requests per agent day — a deliberately low
+   fraction of Google's free-tier daily limit for `GEMINI_API_KEY` /
+   `GOOGLE_API_KEY` keys without billing. This ceiling applies to Gemini
+   only and covers every Gemini model together, so it is not tied to any
+   one model id. The error reads "Gemini daily-request ceiling reached"
+   and resets at the next agent-day boundary (04:00 local).
 3. **Cloud-provider quota** — Bedrock / Vertex / Foundry / Azure
    OpenAI / Gemini-Vertex enforce their own per-region / per-model
-   quotas. The error surfaces the same way as a direct-API quota.
-4. **Subscription fallback exhausted** — no API key registered, so
-   the backend is running on the CLI's local subscription login.
-   The underlying provider's subscription limits then apply (e.g.
-   Claude's rolling 5-hour Opus window on a Max plan login). The
-   recommended fix is to register an API key on `/settings/models`;
-   the fallback is not provider-supported for automated agent use.
-   See [Costs and Quotas](../concepts/costs-and-quotas.md).
+   quotas. The error shows up the same way as a direct-API quota.
+4. **Subscription fallback exhausted** — you have no API key
+   registered, so the backend is running on the CLI's local
+   subscription login. The provider's subscription limits then apply
+   (for example, Claude's rolling 5-hour Opus window on a Max plan
+   login). The recommended fix is to register an API key on
+   `/settings/models`; the fallback is not provider-supported for
+   automated agent use. See
+   [Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Diagnostic Steps