@aitne-sh/aitne 0.1.8 → 0.1.9

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

@@ -41,24 +41,47 @@ keywords:
   - delegated_task
   - gmail_classify
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
+config_keys:
+  - monthlyReviewEnabled
+  - delegatedTaskHeavyEnabled
+  - hourlyCheckIntervalMinutes
+  - dayBoundaryHour
+api_endpoints:
+  - POST /api/browser-task
+ui_anchors:
+  - /settings/models
 related:
   - concepts/process-keys
   - concepts/backends-and-tiers
   - features/operations/backend-routing
+  - features/integrations/browser-history
+  - features/operations/managed-chromium
 ---
 
 # ProcessKeys
 
+A **ProcessKey** identifies the kind of work being dispatched (an owner DM,
+the morning routine, an hourly check, …). 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.
+
+The **default tier** column maps to a model size, not a specific id:
+
+- `lite` → Haiku-class (cheap, fast, narrow)
+- `medium` → Sonnet-class (the default for most owner-facing and routine work)
+- `high` → Opus-class (opt-in only; see [Tier Locks](#tier-locks) and
+  [Delegated Task Hard Caps](#delegated-task-hard-caps))
+
 | ProcessKey | Trigger | Default tier | Configurable |
 |---|---|---|---|
 | `routine.morning_routine` | Daily at `dayBoundaryHour` (default 04:00). Parent envelope; LLM dispatch flows through the two stage keys below. | medium | yes |
-| `routine.morning_routine_today` | Stage A of the morning-routine pipeline — today.md synthesis, schedule fan-out, profile-question pick, user-editable checks. Stage A also populates roadmap.md from a daemon-prepared `<roadmap_skeleton>` block on the first-run branch (Phase 7 retired the heavy-tier `routine.morning_routine_initial`). | medium | yes |
-| `routine.morning_routine_journal` | Stage B of the morning-routine pipeline — authors `daily/<yesterday>.md` from the daemon-prepared journal skeleton. | lite | yes |
-| `routine.today_refresh` | Every 4h inside the active window — drift-refresh of `today.md` | medium | yes |
+| `routine.morning_routine_today` | Stage A of the morning-routine pipeline — `state/today.md` synthesis, schedule fan-out, profile-question pick, user-editable checks. Stage A also populates `plans/roadmap.md` from a daemon-prepared `<roadmap_skeleton>` block on the first-run branch (Phase 7 retired the heavy-tier `routine.morning_routine_initial`). | medium | yes |
+| `routine.morning_routine_journal` | Stage B of the morning-routine pipeline — authors `journal/daily/<yesterday>.md` from the daemon-prepared journal skeleton. | lite | yes |
+| `routine.today_refresh` | Calendar-drift-triggered (calendar change touching today's items; 5-min dedup, fires ~30s later) — drift-refresh of `state/today.md` | medium | yes |
 | `routine.evening_review` | Daily at 18:00 local (fixed) | medium | yes |
 | `routine.weekly_review` | Friday 18:00 local (fixed) | medium | yes |
-| `routine.monthly_review` | Monthly cadence (gated OFF by default — kill switch `monthlyReviewEnabled` in runtime settings) | medium | no |
+| `routine.monthly_review` | Monthly cadence (gated OFF by default — kill switch `monthlyReviewEnabled` in runtime settings). The routine itself is off by default, but its backend/tier binding is still configurable. | medium | yes |
 | `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | medium | yes |
 | `routine.hourly_check.triage` | Stage 2 triage gate of every hourly check | lite | yes |
 | `routine.fetch_window` | Pre-pass fetcher spawned before each main routine | lite | yes |
@@ -99,6 +122,11 @@ related:
 | `wiki.lint` | Health pass over the wiki — writes `90_meta/health/<date>.md` | medium | yes |
 | `wiki.trace` | Chronological evolution of an idea across raw / wiki / outputs | medium | yes |
 | `wiki.connect` | Bridges two domains — writes `30_outputs/<date>-connect-<slug>.md` | medium | yes |
+| `routine.research_cluster_update` | Nightly per-cluster journal append (one row per cluster per day with new activity) | lite | yes |
+| `routine.research_offer_dm` | Two-Option Offer DM composition when a research cluster qualifies | lite | yes |
+| `routine.research_dispatch` | Accept path for the "research dive" option — WebSearch + WebFetch parallel research. Claude-only per §10.3 backend safety floor. | medium | yes |
+| `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`).
@@ -107,3 +135,31 @@ global default.
 
 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.
+
+## Tier Locks
+
+`TIER_LOCKED_PROCESS_KEYS` supersedes operator pins. Current entry:
+
+- `dashboard.docs_qa` → `medium` (DOCS_QA_DESIGN.md §10.1).
+
+## Delegated Task Hard Caps
+
+The `delegated_task` / `delegated_task_heavy` request shape is bounded
+by `DELEGATED_TASK_HARD_CAPS` (server-enforced, not user-tunable):
+
+- `maxToolCalls` ≤ 15
+- `maxBudgetUsd` ≤ 0.50
+- `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.

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

@@ -34,17 +34,40 @@ keywords:
   - wiki skill
   - notify skill
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
+ui_anchors:
+  - /knowledge?tab=skills
+process_keys:
+  - dashboard.docs_qa
+api_endpoints:
+  - /api/skills
+  - /api/skills/manifest/:processKey
+  - /api/browser-task
+  - /api/browser-history/offers/:slug/accept
+context_files:
+  - state/today.md
+  - plans/roadmap.md
+  - state/profile-questions.md
 related:
   - concepts/skills
+  - features/integrations/browser-history
+  - features/operations/managed-chromium
 ---
 
 # 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`, on owner DMs). The table below is the canonical roster.
+
 | Slug | Purpose |
 |---|---|
 | `agent-actions` | Read the agent action log (`agent_actions` table) for retrospective audits. |
 | `attach` | Attach a generated or downloaded file to the agent's reply when the user expects a file artifact. |
+| `browser-history` | Read normalised browser activity through `/api/browser-history/*`. Used by research-cluster journal updates, accept-path dispatches, owner pulls of shopping / reload traces, and the morning research summary. Never reads browser SQLite or profile dirs directly. |
+| `browser-history-respond` | Bridge the owner's natural-language reply to a research-offer DM ("dig deeper" / "summarise") into a structured `/api/browser-history/offers/<slug>/{accept,decline}` call. |
+| `browser-task` | Drive managed Chromium for open-ended browser tasks the user describes in DM. POSTs to `/api/browser-task` with a natural-language description; relays sub-agent clarifications back through DM. Loaded only on `message.received.dm`. |
 | `context` | Read / write context Markdown — projects, weekly summaries, agent journal, generic context files. |
 | `docs-search` | Read-only search and fetch over the operator-facing docs corpus. Used for `dashboard.docs_qa`. |
 | `external-services` | Call Google Calendar, the user's Obsidian vault, GitHub, or the agent Skills-management routes through the daemon proxy. |
@@ -55,23 +78,26 @@ related:
 | `notify` | Send a notification through the paired messaging app and decide whether notifying is warranted. |
 | `notion` | Read, query, search, create, update, and archive Notion pages and databases. |
 | `observations` | Drain the pending-observations queue and inspect raw external-source change records. |
-| `project-doc` | Read / write per-project markdown files under `projects/<slug>.md`. |
+| `project-doc` | Read / write Git-backed and manual project context docs. Git-managed repos write to `knowledge/repos/<slug>/overview.md` plus per-day `journal/repos/<slug>/<date>.md`; manual non-git project pages live at `plans/projects/<slug>.md`. |
 | `reading` | Query reading history and highlights; owns the reading-taste profile via the `books` and `reading_highlights` tables. |
-| `roadmap` | Read / write `roadmap.md` (cross-request write lock). |
+| `roadmap` | Read / write `plans/roadmap.md` (cross-request write lock). |
 | `schedule` | Schedule future agent wake-ups and DMs via the daemon (writes `agent_schedule` and `recurring_schedules` rows). |
 | `scheduled-managed-task` | Surface and act on Managed Tasks that are due now. |
-| `today` | Read or write `today.md` — morning routines, hourly checks, DMs that need a today snapshot. |
-| `user-interview` | Manage the profile-interview queue at `agent/profile-questions.md`; ask one question at a time. |
-| `user-profile` | Record user facts — identity, people, work, expertise, habits, goals — into the `user/*` slices. |
+| `today` | Read or write `state/today.md` — morning routines, hourly checks, DMs that need a today snapshot. |
+| `user-interview` | Manage the profile-interview queue at `state/profile-questions.md`; ask one question at a time. |
+| `user-profile` | Record user facts — identity, people, work, expertise, habits, goals — into the `identity/*` slices (`profile.md`, `people.md`, `work.md`, …). |
 | `wiki` | Build and maintain the personal wiki workspace — `!ingest` / `!compile` / `!ask` / `!lint` / `!trace` / `!connect`. |
 
+## 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.
 
-A subset of these skills' sections (knowledge layout, routing
-tables, search recipes, etc.) is also 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>/overlays/<skill>/<section-id>.json`.
+## 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>/overlays/<skill>/<section-id>.json`.

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

@@ -10,27 +10,41 @@ category: troubleshooting
 summary: |
   A backend's auth-health card flipped amber or red. Re-authenticate
   via the backend's CLI or paste a fresh API key.
-section: auth-failed
+section: troubleshooting
 tags:
   - troubleshooting
   - safety
   - backends
+  - health
 status: stable
 ask_examples:
   - Why is the auth-health card amber?
   - How do I re-login to Claude?
+  - The auth-health pill went red, what now?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-28
 keywords:
   - auth failed
   - auth error
   - subscription warning
   - API key invalid
+  - BackendDecisiveFailure
+  - re-authenticate
 related:
   - concepts/auth-health
   - concepts/costs-and-quotas
   - features/operations/backend-routing
+ui_anchors:
+  - /settings/models
+  - /connections
+config_keys:
+  - authPreflightFreshnessMs
+  - authProbeDisabled
+api_endpoints:
+  - POST /api/backends/:backendId/check-auth
+  - POST /api/backends/:backendId/recovery/start
+  - POST /api/backends/:backendId/recovery/code
 ---
 
 # Auth Failed
@@ -49,32 +63,47 @@ related:
    `claude`, `codex login`, `gemini auth` — 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 providers
-   (Bedrock / Vertex / Foundry / Azure OpenAI / Gemini-Vertex),
+   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.
 
 ## Diagnostic Steps
 
 1. Click the pill to see the recovery hint.
-2. Check `/settings/models` — the backend card shows whether it is
+2. Open `/settings/models`. The backend card shows whether it is
    running on a registered API key (the supported path) or on the
-   subscription fallback. The `SubscriptionAuthWarning` banner
-   appears whenever any backend is on the fallback.
-3. If on the API key, paste a fresh key on `/settings/models` — the
-   daemon mirrors it into `process.env` and re-probes immediately.
-4. If on the subscription fallback, the recommended fix is to
-   register an API key on `/settings/models` (or one of the cloud-
-   provider options exposed on the same picker — Bedrock / Vertex /
-   Foundry / Azure OpenAI / Gemini-Vertex).
-   If you cannot or do not want to, run the corresponding CLI login
-   (`claude`, `codex login`, `gemini auth`) and the daemon picks up
-   the new credentials on the next probe. Note that this fallback
-   is not provider-supported for automated agent use — see
-   [Costs and Quotas](../concepts/costs-and-quotas.md).
+   subscription fallback. The **API-key panel always carries the
+   subscription-auth warning** — registering a paid key is the
+   recommended path because several providers (Anthropic in
+   particular) do not support running automated agents on a
+   subscription plan.
+
+## Fixing It
+
+**If the backend is on a registered API key:** paste a fresh key on
+`/settings/models`. The daemon mirrors it into `process.env` and
+re-probes immediately — no restart needed.
+
+**If the backend is on the subscription fallback:** the recommended
+fix is to register an API key on `/settings/models`. The same picker
+also exposes cloud-provider auth — Bedrock / Vertex / Foundry for
+Claude, Vertex AI for Gemini. (Codex Azure OpenAI is not offered here;
+it needs a `~/.codex/config.toml` the env-mirroring path cannot write,
+so Codex stays direct-key only.)
+
+If you cannot or do not want to register a key, re-run the
+corresponding CLI login (`claude`, `codex login`, `gemini auth`) and
+the daemon picks up the new credentials on the next probe. Some
+backends also expose an in-dashboard device-code recovery flow
+(`recovery/start` → `recovery/code`) reachable from the pill's
+recovery hint. Note that subscription auth is not provider-supported
+for automated agent use — see
+[Costs and Quotas](../concepts/costs-and-quotas.md).
 
 ## Confirming the Fix
 
-- The pill flips green within `authPreflightFreshnessMs`.
+The pill flips green within `authPreflightFreshnessMs` of the next
+probe (default 10 minutes).
 
 ## Related
 

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

@@ -5,63 +5,125 @@ title: Dashboard Shows Degraded
 id: dashboard-shows-degraded
 aliases:
   - dashboard degraded
-  - degraded pill
-  - health pill red
-  - health degraded
+  - degraded banner
+  - daemon degraded
+  - primary vault unreachable
+  - writes are blocked
 category: troubleshooting
 summary: |
-  The DegradedBanner appears at the top of every page when the daemon
-  reports a critical-write block. Usually an integration auth failure
-  or a context-file lock issue.
-section: dashboard-shows-degraded
+  A red "Daemon degraded" banner appears above every page when the daemon
+  enters degraded mode. This almost always means your Obsidian-style primary
+  vault is unreachable (path moved, drive unplugged, or not yet seeded), or a
+  context migration is in progress. While degraded, every context write is
+  refused with HTTP 503.
+section: troubleshooting
+status: stable
 tags:
   - troubleshooting
   - operations
   - health
-status: stable
+  - memory
 ask_examples:
   - Why is the dashboard showing a degraded banner?
-  - What does "writes are blocked" mean?
+  - What does "primary vault unreachable" mean?
+  - Why are context writes being refused with 503?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - degraded
-  - health pill
+  - degraded banner
+  - primary vault unreachable
+  - management mode
+  - /api/health
+  - "503"
+config_keys:
+  - vaultMode
+  - primaryVaultPath
+api_endpoints:
+  - GET /api/health
+context_files:
+  - policies/management.md
+ui_anchors:
+  - /settings
   - /health
-  - auth health
-  - indexer degraded
 related:
   - troubleshooting/auth-failed
-  - features/memory-files/today
+  - guides/use-an-existing-obsidian-vault
+  - concepts/memory-model
 ---
 
 # Dashboard Shows Degraded
 
 ## What You See
 
-- A red banner at the top of every page reading
-  "Writes are blocked".
-- Routines that write context files fail.
+- A red banner pinned above every page. Its headline is either
+  **"Primary vault unreachable"** or **"Daemon degraded: `<reason>`"**, often
+  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 writes a context file fails: the context API
+  returns **HTTP 503** for every `POST`/`PUT`/`PATCH`/`DELETE` while degraded.
+
+## 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.
 
-## Most Likely Causes
+You only see this banner if you switched memory to an **Obsidian-style vault**
+(`vaultMode: "obsidian"`). The default `vaultMode: "plain"` stores memory under
+`~/.personal-agent/context/` and does not enter this state.
 
-1. The today-write-lock did not release (rare; daemon was killed
-   mid-write).
-2. An integration auth failure that propagated.
-3. The data directory ran out of disk.
+The `reason` in the banner is one of:
+
+| `reason`                       | Meaning |
+|--------------------------------|---------|
+| `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). |
+| `migration_in_progress`        | A context-vault migration (`/api/setup/migrate-context`) is running. Writes are gated until it finishes; reads still work. This one clears itself. |
 
 ## Diagnostic Steps
 
-1. `aitne logs` — search for the most recent error.
-2. Confirm `df -h` shows free space on the data directory.
-3. Check for a stale lock file in `~/.personal-agent/`.
+1. **Read the banner.** The `reason` and `path` tell you most of the story.
+2. `aitne logs` — look for `Vault health probe entered degraded mode`; the
+   logged `reason` matches the banner.
+3. If the reason is `migration_in_progress`, **wait** — the migration releases
+   the write gate when it completes; do not restart mid-migration.
+4. Otherwise the issue is your vault path. Confirm it exists and is writable:
+   - `ls -ld "<path-from-banner>"` — the directory must exist.
+   - `df -h "<path-from-banner>"` — confirm the volume is mounted with free
+     space (a full or read-only filesystem reports as `not_writable`).
+   - If it lives on an external drive, re-mount the drive.
+
+## Fixing It
+
+Open **Settings → Management Mode** (the banner's button, or `/settings`):
+
+- **Path moved or drive unplugged** — restore the original path, or point
+  `primaryVaultPath` at the vault's current location.
+- **You don't need an external vault** — switch Management Mode back to
+  **This app** (`vaultMode: "plain"`); memory returns to
+  `~/.personal-agent/context/`.
+- **`primary_vault_missing_content`** — the target needs to be seeded. Re-run
+  the Obsidian vault setup so `policies/management.md` and the rest of the
+  skeleton are written into it. See
+  [Use an existing Obsidian vault](../guides/use-an-existing-obsidian-vault.md).
 
 ## Confirming the Fix
 
-- The banner clears within 30 seconds of the underlying issue
-  resolving.
+- The vault-health probe re-runs every 30 seconds, and the dashboard refetches
+  `/api/health` every 10 seconds. Once the path is reachable again, the banner
+  clears within roughly half a minute — no restart needed.
+- To check from the CLI without the dashboard, query the daemon:
+  `curl -s localhost:8321/api/health | grep -o '"status":"[^"]*"'` — it should
+  report `"status":"ok"` (degraded reports `"status":"degraded"` with a
+  populated `degraded` object).
 
 ## Related
 
-- [Auth Failed](auth-failed.md)
+- [Auth Failed](auth-failed.md) — unrelated; covers backend auth, not the vault.
+- [Use an existing Obsidian vault](../guides/use-an-existing-obsidian-vault.md)
+- [Memory model](../concepts/memory-model.md)

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

@@ -7,58 +7,122 @@ aliases:
   - fallback firing
   - backend fallback
   - main backend down
+  - fallover loop
 category: troubleshooting
 summary: |
-  The router transitioned main → fallback for several runs in a row.
-  Almost always main backend is unhealthy or quota-exhausted.
+  The router keeps switching from your main backend to its fallback,
+  run after run. Almost always the main backend is unhealthy
+  (expired auth) or quota-exhausted. This doc shows how to confirm the
+  cause and get runs back onto the main backend.
 section: fallback-keeps-firing
+status: stable
 tags:
   - troubleshooting
   - backends
   - routing
-status: stable
-ask_examples:
-  - Why does the fallback keep running?
-  - How do I stop the fallover loop?
-locale: en-US
-created: 2026-04-25
-updated: 2026-04-25
+  - health
+  - cost
 keywords:
   - fallback
   - BackendQuotaError
   - BackendDecisiveFailure
   - router fallover
+  - auth expired
+  - quota exhausted
+ask_examples:
+  - Why does the fallback backend keep running?
+  - How do I stop the fallover loop?
+  - Why isn't my main backend being used?
+ui_anchors:
+  - /settings/models
+  - /analytics
+  - /activity
+process_keys:
+  - message.dm
+  - routine.morning_routine
+api_endpoints:
+  - GET /api/health
+  - POST /api/backends/:backendId/check-auth
+config_keys:
+  - autonomousDailyCostCapUsd
 related:
   - troubleshooting/auth-failed
   - troubleshooting/quota-exhausted
   - features/operations/backend-routing
+  - concepts/auth-health
+  - concepts/backends-and-tiers
+locale: en-US
+created: 2026-04-25
+updated: 2026-05-28
 ---
 
 # Fallback Keeps Firing
 
-## What You See
+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.
+
+## What you see
+
+- Multiple recent Activity rows whose backend is *not* your main backend.
+- Notifications that mention a "fallback".
+
+## 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.
+
+`BackendQuotaError` and `BackendDecisiveFailure` are the two signals the
+router watches; one of them is firing on every attempt.
+
+## Diagnose
 
-- Multiple recent Activity rows with backend != main.
-- Notifications mentioning "fallback".
+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:
 
-## Most Likely Causes
+   ```bash
+   # recent runs on the main backend that didn't succeed
+   aitne audit --backend claude --result failed --since 24h
+   ```
 
-1. Main backend's auth has expired.
-2. Main backend's heavy-tier window is depleted.
-3. A `BackendDecisiveFailure` is repeating — usually a config issue.
+   (`--backend` accepts `claude`, `codex`, or `gemini`.)
 
-## Diagnostic Steps
+## Fix
 
-1. Open `/connections` — auth-health card.
-2. Open `/analytics` — main-backend cost / quota.
-3. Look at the failure detail in Activity for the offending row.
+- **Expired auth →** re-authenticate the main backend from its card on
+  `/settings/models`, then run a test. See [Auth Failed](auth-failed.md).
+- **Exhausted quota →** wait for the usage window to reset, raise the cap,
+  or accept the fallback until it clears. See
+  [Quota Exhausted](quota-exhausted.md).
+- **Config issue →** fix the reported problem (install the CLI, repin a
+  valid model, relax execution mode) on `/settings/models`.
 
-## Confirming the Fix
+## Confirm the fix
 
-- The next run uses the main backend.
+- The next run uses the main backend again — visible in `/activity` or via
+  `aitne audit --backend <id> --since 1h`.
 
 ## Related
 
 - [Auth Failed](auth-failed.md)
 - [Quota Exhausted](quota-exhausted.md)
 - [Backend Routing](../features/operations/backend-routing.md)
+- [Auth Health](../concepts/auth-health.md)
+- [Backends and Tiers](../concepts/backends-and-tiers.md)