@aitne-sh/aitne 0.1.0

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

@@ -0,0 +1,51 @@
+---
+schema_version: 1
+slug: reference/api
+title: API Reference
+id: api-ref
+category: reference
+summary: |
+  Aitne's daemon serves a Hono HTTP API on PA_API_PORT
+  (default 8321). This is a high-level map; the source of truth is
+  the route registrations in packages/daemon/src/api/server.ts.
+section: api
+tags:
+  - reference
+  - api
+status: stable
+ask_examples:
+  - What endpoints does the daemon expose?
+  - How do I read context files via API?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - reference/config
+---
+
+# API Reference
+
+| Group | Path | Purpose |
+|---|---|---|
+| Context | `/api/context/*` | Read / write context Markdown files. |
+| Agent | `/api/agent/*` | run-now, regenerate, schedule, notify. |
+| Backends | `/api/backends/*` | Backend / process-config CRUD. |
+| Calendar | `/api/calendar` | Calendar proxy. |
+| Mail | `/api/mail` | Multi-provider mail proxy. |
+| Obsidian | `/api/obsidian` | Obsidian vault proxy. |
+| Notion | `/api/notion` | Notion proxy. |
+| Git / GitHub | `/api/git`, `/api/github` | Git / GitHub proxies. |
+| Skills | `/api/skills` | Skill metadata. |
+| Reading | `/api/books` | Reading list CRUD. |
+| Lifestyle | `/api/receipts`, `/api/travel-bookings`, `/api/travel-time` | Lifestyle data. |
+| Docs | `/api/docs/*` | Docs corpus + QA pipeline. |
+| Dashboard | `/api/dashboard/*` | Dashboard config + state. |
+| SSE | `/api/chat/stream`, `/api/events/stream` | SSE streams. |
+| Health | `/api/health`, `/api/metrics` | Daemon liveness / metrics. |
+| Setup | `/api/setup/*` | Setup wizard endpoints. |
+
+Auth: bearer token written to the OS keychain at first launch.
+
+## Related
+
+- [Config](config.md)

package/agent-assets/docs/reference/cli-commands.md

@@ -0,0 +1,121 @@
+---
+schema_version: 1
+slug: reference/cli-commands
+title: CLI Commands
+id: cli-commands
+category: reference
+summary: |
+  Lookup table for the aitne / pnpm commands that drive the daemon and
+  dashboard, plus the environment variables that override defaults.
+tags:
+  - cli
+  - reference
+status: stable
+ask_examples:
+  - What command starts the daemon?
+  - How do I stop Aitne?
+  - How do I tail the daemon log?
+  - Where does Aitne put its data?
+  - How do I see what the agent has been doing?
+locale: en-US
+created: 2026-04-27
+updated: 2026-04-27
+keywords:
+  - aitne start
+  - aitne stop
+  - aitne logs
+  - aitne doctor
+  - aitne audit
+  - pnpm start
+  - PA_DATA_DIR
+related:
+  - guides/install-and-run
+  - guides/reinstall-cleanly
+---
+
+# CLI Commands
+
+## `aitne` and `pnpm` are equivalent
+
+`aitne` is the project's CLI (`bin/aitne.mjs`). The `pnpm <cmd>` forms are
+workspace scripts that delegate to the same entry point. Use whichever you
+prefer — `aitne start` and `pnpm start` do the same thing. After installing
+the npm package globally (`npm i -g aitne`) the `aitne` binary is on
+your `$PATH` and you no longer need to be inside the repo to use it. The
+tables below show both forms.
+
+## Lifecycle
+
+| Command | What it does |
+|---|---|
+| `aitne start` / `pnpm start` | Build (if stale), then launch daemon + dashboard in the background. |
+| `aitne stop` / `pnpm stop` | Graceful shutdown (SIGTERM → SIGKILL after 10s) of both processes. |
+| `aitne restart` / `pnpm restart` | `stop` then `start`. `--clean-context` wipes `context/` after a tarball backup. |
+| `aitne status` / `pnpm status` | PIDs, uptime, integrations, today's spend, last action timestamp, next scheduled item. |
+| `aitne dev` / `pnpm dev` | Foreground mode — runs the daemon + dashboard with full stdio. |
+
+## Operations
+
+| Command | What it does |
+|---|---|
+| `aitne setup` | (Re-)open the dashboard `/setup` wizard; auto-starts the daemon if needed. |
+| `aitne open` | Open the dashboard root in the default browser. |
+| `aitne doctor` | Eight install-health checks (Node, ports, OS keychain, backend CLIs, native bindings, …). |
+| `aitne audit [--since 24h] [--type X] [--result failed]` | Show the agent action log; flags filter by time, action type, result, or backend. `--json` for machine-readable. |
+| `aitne version [--json]` | Print version, Node version, install path, last build time. |
+| `aitne update [--check]` | Print the npm command to upgrade. `--check` makes one network call to compare against the latest published version. |
+| `aitne uninstall [--keep-data\|--wipe-data]` | Stop the services, then offer to wipe `~/.personal-agent`. |
+
+## Logs
+
+| Command | What it does |
+|---|---|
+| `aitne logs` / `pnpm logs` | Print the daemon log (most recent lines). |
+| `aitne logs -f` | Tail the daemon log. |
+| `aitne logs -d` | Print the dashboard log instead. |
+| `aitne logs -n N` | Last N lines. |
+
+## Build and test
+
+| Command | What it does |
+|---|---|
+| `pnpm install` | Install workspace dependencies (pnpm 10.x, Node ≥ 22). |
+| `pnpm build` | Turbo build — shared → daemon → dashboard. |
+| `pnpm test` | Run the vitest suite (compiles first if stale). |
+| `pnpm test:watch` | Vitest in watch mode. |
+| `pnpm lint` | Run eslint per package. |
+| `pnpm clean` | Remove `node_modules`, `dist`, `.buildstamp`. |
+
+## Environment overrides
+
+| Variable | Default | What it controls |
+|---|---|---|
+| `PA_DATA_DIR` | `~/.personal-agent` | Where logs, the SQLite DB, context Markdown, and prompts live. |
+| `PA_API_PORT` | `8321` | Daemon HTTP port. |
+| `PA_DASHBOARD_PORT` | `3000` | Dashboard port. |
+
+All runtime state — PIDs, logs, SQLite DB, context Markdown, prompts —
+lives under `PA_DATA_DIR`, **not** inside the repo.
+
+## Where data lives
+
+```
+~/.personal-agent/
+├── data/personal_agent.db    # SQLite (sessions, actions, observations, FTS)
+├── context/                  # Markdown memory the agent reads and writes
+│   ├── user.md
+│   ├── today.md
+│   ├── roadmap.md
+│   ├── projects/
+│   ├── schedule/
+│   └── …
+├── logs/                     # Daemon and dashboard logs
+└── pids/                     # Process IDs for aitne start/stop
+```
+
+## Related
+
+- [Install and Run](../guides/install-and-run.md) — the procedural
+  guide that uses these commands end-to-end.
+- [Reinstall Cleanly](../guides/reinstall-cleanly.md) — when you need
+  to wipe state and start over.

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

@@ -0,0 +1,74 @@
+---
+schema_version: 1
+slug: reference/config
+title: Config Reference
+id: config-ref
+category: reference
+summary: |
+  All AgentConfig fields, their types, and where each is set
+  (environment, database settings table, or in-process default).
+section: config
+tags:
+  - reference
+  - config
+status: stable
+ask_examples:
+  - What configuration keys does the agent expose?
+  - Where does config get loaded from?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - reference/api
+---
+
+# Config Reference
+
+The full schema is `AgentConfig` in `packages/daemon/src/config.ts`.
+A subset listed in `applyConfigUpdates` is mutable at runtime via
+`PATCH /api/config`. The rest must be set via env or restart.
+
+## Selected Keys
+
+| Key | Type | Default |
+|---|---|---|
+| `timezone` | IANA tz | `""` (falls back to system tz, e.g. `America/New_York`) |
+| `dayBoundaryHour` | 0–23 | `4` |
+| `hourlyCheckEnabled` | boolean | `true` |
+| `hourlyCheckIntervalMinutes` | number | `60` |
+| `hourlyCheckActiveStartHour` | 0–23 | `4` |
+| `hourlyCheckActiveEndHour` | 1–24 | `24` (end-exclusive; `24` ≡ midnight) |
+| `hourlyCheckMinObservations` | number | `1` |
+| `quietHoursStart` | `HH:MM` string | `"22:00"` |
+| `quietHoursEnd` | `HH:MM` string | `"08:00"` |
+| `maxNotificationsPerHour` | number | `3` |
+| `maxNotificationsPerDay` | number | `12` |
+| `batchIntervalMinutes` | number | `15` |
+| `executeTimeoutMinutes` | number | `60` |
+| `maxConcurrentSessions` | number | `3` |
+| `disallowedTools` | string[] | absolute-block defaults |
+| `allowedToolsOverride` | string[] | empty |
+| `autonomousDailyCostCapUsd` | number | `0` (off) |
+
+The runtime-mutable subset can be edited from `/settings/*`. Restart-only
+fields (e.g. `apiPort`) require `pa restart`.
+
+### Routine schedule keys do not exist
+
+Morning, evening, weekly, and monthly routines fire at fixed times in
+`packages/daemon/src/core/scheduler.ts`. There is no `morningRoutineHour`,
+`eveningReviewHour`, `weeklyReviewDay`, or `monthlyReviewHour` config key.
+
+| Routine | Trigger |
+|---|---|
+| `routine.morning_routine` | daily at `dayBoundaryHour` |
+| `routine.evening_review` | daily at `18:00` local |
+| `routine.weekly_review` | Friday `18:00` local |
+| `routine.monthly_review` | last day of month at `18:00` local |
+
+Only the hourly check has a configurable cadence (`hourlyCheckIntervalMinutes`)
+and an active window (`hourlyCheckActiveStartHour` / `…ActiveEndHour`).
+
+## Related
+
+- [API](api.md)

package/agent-assets/docs/reference/disallowed-tools.md

@@ -0,0 +1,76 @@
+---
+schema_version: 1
+slug: reference/disallowed-tools
+title: Disallowed Tools (Reference)
+id: disallowed-tools-ref
+category: reference
+summary: |
+  The absolute-block tool patterns. Cannot be widened by config or
+  by skill-level allow-lists. Mirrors src/safety/always-disallowed.ts.
+section: disallowed-tools
+tags:
+  - reference
+  - safety
+status: stable
+ask_examples:
+  - What can the agent never run?
+  - Can I unblock a tool in the absolute-block list?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-26
+related:
+  - concepts/safety-and-execution
+---
+
+# Disallowed Tools
+
+There are two distinct deny layers — the **absolute-block layer**
+(non-overridable) and the **default strict-mode list** (in `config.ts`,
+relaxable in Allow mode or via `allowedToolsOverride`).
+
+## Absolute-block layer (cannot be widened past)
+
+These patterns are denied unconditionally regardless of execution mode
+or `allowedToolsOverride`. Source of truth:
+`packages/daemon/src/safety/always-disallowed.ts`.
+
+| Category | Examples |
+|---|---|
+| Recursive delete | `Bash(rm -rf *)`, `Bash(rm -r *)`, `Bash(rm -R*)`, `Bash(rm -fr*)`, `Bash(rm --recursive*)`, plus the bypass-coverage family of every short-flag bundle containing `r`/`R` (see source) |
+| Privilege escalation | `Bash(sudo *)`, `Bash(doas *)`, `Bash(su *)` |
+| Pipe-to-shell RCE | `Bash(curl * | sh*)`, `Bash(curl * | bash*)`, `Bash(wget * | sh*)`, `Bash(wget * | bash*)`, `Bash(bash <(*)*)`, `Bash(sh <(*)*)`, `Bash(bash<*)`, `Bash(sh<*)`, `Bash(eval *)`, `Bash(source *)` |
+| Platform secret-management CLIs | `Bash(security *)` (macOS Keychain), `Bash(secret-tool *)` (libsecret), `Bash(cmdkey *)` (Windows Credential Manager) |
+| Secret-file reads | `Read(.env)`, `Read(.env.*)`, `Read(**/.env)`, `Read(id_rsa*)`, `Read(id_ed25519*)`, `Read(~/.ssh/**)`, `Read(~/.gnupg/**)`, `Read(~/.aws/**)`, `Read(~/.config/gcloud/**)`, `Read(~/.config/gh/hosts.yml)`, `Read(~/.netrc)`, `Read(~/Library/Keychains/**)`, `Read(~/.local/share/keyrings/**)` |
+| Daemon-managed secret surfaces | `Read(~/.personal-agent/backups/**)`, `Read(~/.personal-agent/whatsapp/auth/**)`, `Read(~/.personal-agent/secrets/**)` |
+| Secret-file writes | `Write(...)` and `Edit(...)` mirrors of every secret-file Read pattern above |
+
+Plain `curl` / `wget` are intentionally **not** in this list — skills
+rely on `curl http://localhost:<port>/api/...` as the daemon-API
+chokepoint for memory writes.
+
+> **Codex allow-mode gap.** Codex CLI has no hook or admin-policy
+> surface for shell commands, so allow mode runs under
+> `--dangerously-bypass-approvals-and-sandbox` and the absolute-block
+> layer can't enforce on Codex there. See
+> `docs/design/09-safety-cost.md` §6.4 for the accepted gap.
+
+## Default strict-mode list (relaxable)
+
+`config.ts > disallowedTools` ships with additional defaults that the
+operator can widen out of via `allowedToolsOverride` or by switching
+to Allow mode. These include `Bash(chmod *)`, `Bash(chown *)`,
+`Bash(git push --force *)`, `Bash(git reset --hard *)` and a handful
+of other footgun patterns. They are **not** in the absolute-block
+layer — Allow mode permits them.
+
+## Audit log
+
+Every absolute-block match is logged as
+`agent_actions(action_type='blocked_absolute')` with a redacted form
+of the offending argument and the matched category. The classifier
+that produces the category is `classifyAbsoluteBlock` in
+`src/safety/always-disallowed.ts`.
+
+## Related
+
+- [Safety and Execution](../concepts/safety-and-execution.md)

package/agent-assets/docs/reference/keyboard-shortcuts.md

@@ -0,0 +1,39 @@
+---
+schema_version: 1
+slug: reference/keyboard-shortcuts
+title: Keyboard Shortcuts
+id: keyboard-shortcuts
+category: reference
+summary: |
+  Keyboard shortcuts available in the dashboard. The set is small by
+  design — the dashboard is a low-cognition surface.
+section: keyboard-shortcuts
+tags:
+  - reference
+  - dashboard
+status: stable
+ask_examples:
+  - What keyboard shortcuts work in the dashboard?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - features/messaging/dashboard-chat
+---
+
+# Keyboard Shortcuts
+
+| Keys | Action |
+|---|---|
+| `?` | Open the contextual help slide-over. On `/docs`, focuses the inline QA composer. |
+| `Cmd+K` / `Ctrl+K` | Open the search palette (settings + Actions). |
+| `Esc` | Close the slide-over / palette. |
+| `Cmd+Enter` | Send the current QA composer / chat message. |
+
+Shortcuts are skipped when an input or textarea is focused (so typing
+`?` in chat does not open the slide-over). The exception is `Cmd+K`,
+which still opens regardless.
+
+## Related
+
+- [Dashboard Chat](../features/messaging/dashboard-chat.md)

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

@@ -0,0 +1,59 @@
+---
+schema_version: 1
+slug: reference/process-keys
+title: ProcessKeys (Reference)
+id: process-keys-ref
+aliases:
+  - process key list
+  - dispatch keys
+category: reference
+summary: |
+  The full list of ProcessKeys, what triggers each, and the default
+  tier. Mirrors packages/shared/src/process-key.ts.
+section: process-keys
+tags:
+  - reference
+  - dispatch
+status: stable
+ask_examples:
+  - List all the ProcessKeys
+  - What is the default tier for hourly check?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/process-keys
+---
+
+# ProcessKeys
+
+| ProcessKey | Trigger | Default tier | Configurable |
+|---|---|---|---|
+| `routine.morning_routine` | Daily at `dayBoundaryHour` (default 04:00) | heavy | yes |
+| `routine.morning_routine_initial` | One-shot, fired once during the setup wizard's first day | heavy | no |
+| `routine.evening_review` | Daily at 18:00 local (fixed) | light | yes |
+| `routine.weekly_review` | Friday 18:00 local (fixed) | light | yes |
+| `routine.monthly_review` | Last day of month, 18:00 local (fixed) | light | yes |
+| `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | light | yes |
+| `routine.user_profile_sweep` | Periodic agent-day summarization pass | light | no |
+| `routine.today_refresh` | Mid-day re-check of `today.md` | light | no |
+| `routine.roadmap_refresh` | Periodic roadmap re-derivation | light | no |
+| `routine.custom.<slug>` | Operator-defined recurrence (see [Custom Routines](../features/routines/custom-routines.md)) | configurable | yes |
+| `message.dm` | Owner DM | light | yes |
+| `message.mention` | @-mention in shared channel | light | yes |
+| `dashboard.chat` | `/chat` send | light | yes |
+| `dashboard.docs_qa` | Docs QA panel | light (forced) | yes (within forced light) |
+| `agent.task` | Future-dated agent action (recurring schedules) | light | yes |
+| `agent.dm_task` | DM-tone scheduled session (e.g. morning briefing) | light | yes |
+| `schedule.approaching` | Pre-event reminder | light | no |
+| `calendar.change` | Calendar event added / moved / cancelled | light | yes |
+| `gmail_classify` | Mail classifier inference | light | yes |
+| `setup` | Setup wizard one-shot | heavy | no |
+
+"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.
+
+This list mirrors `packages/shared/src/process-key.ts`. The codebase
+is the source of truth.

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

@@ -0,0 +1,50 @@
+---
+schema_version: 1
+slug: reference/skills
+title: Skills (Reference)
+id: skills-ref
+category: reference
+summary: |
+  Index of built-in skills bundled with Aitne. Each maps to
+  a SKILL.md under agent-assets/skills/<slug>/.
+section: skills
+tags:
+  - reference
+  - skills
+status: stable
+ask_examples:
+  - List all the built-in skills
+  - What does the docs-search skill do?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/skills
+---
+
+# Built-in Skills
+
+| Slug | Purpose |
+|---|---|
+| `attach` | Attach a generated or downloaded file to the agent's reply when the user expects a file artifact. |
+| `context` | Read / write context Markdown — projects, weekly/monthly 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. |
+| `mail` | Unified multi-provider mail interface (Gmail, Outlook, Yahoo, iCloud) — search, label, classify. |
+| `management-policy` | Capture a durable management rule from a DM ("every morning X", "from now on when Y, do Z"). Persists to the management policy store. |
+| `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. |
+| `reading` | Query reading history and highlights; owns the reading-taste profile via the `books` and `reading_highlights` tables. |
+| `receipts` | Query and manage receipt / invoice attachments detected from Gmail; download and save to the external Obsidian vault. |
+| `roadmap` | Read / write `roadmap.md` (cross-request write lock). |
+| `schedule` | Schedule future agent wake-ups and DMs via the daemon (writes `agent_schedule` and `recurring_schedules` rows). |
+| `today` | Read or write `today.md` — morning routines, hourly checks, DMs that need a today snapshot. |
+| `travel` | Query the travel-bookings store (flights, hotels, restaurants, trains). |
+| `travel-time` | Estimate door-to-door travel time via Google Maps; calculate departure times. |
+| `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. |
+
+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.

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

@@ -0,0 +1,57 @@
+---
+schema_version: 1
+slug: troubleshooting/auth-failed
+title: Auth Failed
+id: auth-failed
+aliases:
+  - credentials expired
+  - login required
+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
+tags:
+  - troubleshooting
+  - safety
+  - backends
+status: stable
+ask_examples:
+  - Why is the auth-health card amber?
+  - How do I re-login to Claude?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - concepts/auth-health
+  - features/operations/backend-routing
+---
+
+# Auth Failed
+
+## What You See
+
+- A red or amber pill on `/connections` or the dashboard health card.
+- Routines failing with `BackendDecisiveFailure`.
+
+## Most Likely Causes
+
+1. **Token expired** (Codex, Gemini API).
+2. **Claude credentials rotated** out of the keychain.
+3. **Scope changed** (e.g. Claude Max plan was downgraded).
+
+## Diagnostic Steps
+
+1. Click the pill to see the recovery hint.
+2. For Claude: `claude` CLI login, the daemon picks up the new
+   credentials on probe refresh.
+3. For Codex / Gemini: paste a fresh token / API key on
+   `/settings/models`.
+
+## Confirming the Fix
+
+- The pill flips green within `authPreflightFreshnessMs`.
+
+## Related
+
+- [Auth Health](../concepts/auth-health.md)

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

@@ -0,0 +1,55 @@
+---
+schema_version: 1
+slug: troubleshooting/dashboard-shows-degraded
+title: Dashboard Shows Degraded
+id: dashboard-shows-degraded
+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
+tags:
+  - troubleshooting
+  - operations
+status: stable
+ask_examples:
+  - Why is the dashboard showing a degraded banner?
+  - What does "writes are blocked" mean?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+related:
+  - troubleshooting/auth-failed
+  - features/memory-files/today
+---
+
+# 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.
+
+## Most Likely Causes
+
+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.
+
+## Diagnostic Steps
+
+1. `pa 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/`.
+
+## Confirming the Fix
+
+- The banner clears within 30 seconds of the underlying issue
+  resolving.
+
+## Related
+
+- [Auth Failed](auth-failed.md)

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

@@ -0,0 +1,54 @@
+---
+schema_version: 1
+slug: troubleshooting/fallback-keeps-firing
+title: Fallback Keeps Firing
+id: fallback-keeps-firing
+category: troubleshooting
+summary: |
+  The router transitioned main → fallback for several runs in a row.
+  Almost always main backend is unhealthy or quota-exhausted.
+section: fallback-keeps-firing
+tags:
+  - troubleshooting
+  - backends
+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
+related:
+  - troubleshooting/auth-failed
+  - troubleshooting/quota-exhausted
+  - features/operations/backend-routing
+---
+
+# Fallback Keeps Firing
+
+## What You See
+
+- Multiple recent Activity rows with backend != main.
+- Notifications mentioning "fallback".
+
+## Most Likely Causes
+
+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.
+
+## Diagnostic Steps
+
+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.
+
+## Confirming the Fix
+
+- The next run uses the main backend.
+
+## Related
+
+- [Auth Failed](auth-failed.md)
+- [Quota Exhausted](quota-exhausted.md)
+- [Backend Routing](../features/operations/backend-routing.md)