@aitne-sh/aitne 0.1.11 → 0.1.13

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

@@ -15,8 +15,6 @@ summary: |
   and pointers to the canonical key tuples in shared/.
 section: config
 tags:
-  - core
-  - reference
   - config
   - operations
   - backends
@@ -78,7 +76,7 @@ ui_anchors:
   - /settings/infrastructure
   - /settings/models
 created: 2026-04-25
-updated: 2026-06-08
+updated: 2026-07-01
 related:
   - reference/api
   - reference/cli-commands
@@ -89,21 +87,24 @@ related:
 # Config Reference
 
 The full `AgentConfig` schema lives in
-`packages/daemon/src/config.ts`. Three canonical tuples in
-`packages/shared/src/editable-config-keys.ts` govern what is editable
-and when:
-
-- **`EDITABLE_RUNTIME_KEY_TUPLE`** — the ~130 keys mutable at runtime
-  via `PATCH /api/config`. Both the daemon and the dashboard import
-  from this tuple so the accepted-key set is enforced at compile time
-  in both packages.
-- **`RESTART_REQUIRED_KEY_TUPLE`** — runtime-editable keys whose
-  change does not apply to a running worker (the dashboard renders a
-  restart-required badge for these).
-- **`EDITABLE_BOOTSTRAP_KEY_TUPLE`** — `apiPort` only, written to
-  `.env` because it's read before the daemon binds.
-
-Anything not in those tuples must be set via env or restart.
+`packages/daemon/src/config.ts`. Three fixed lists of key names
+(TypeScript tuples) in `packages/shared/src/editable-config-keys.ts`
+decide which keys you can change, and when:
+
+- **`EDITABLE_RUNTIME_KEY_TUPLE`** — the ~130 keys you can change while
+  the daemon is running, via `PATCH /api/config`. Both the daemon and
+  the dashboard import this list, so the set of accepted keys is checked
+  at compile time in both packages.
+- **`RESTART_REQUIRED_KEY_TUPLE`** — keys you can edit at runtime, but
+  the new value only reaches a worker after a restart; it does not apply
+  to a worker that is already running. The dashboard shows a
+  restart-required badge for these.
+- **`EDITABLE_BOOTSTRAP_KEY_TUPLE`** — only `apiPort`. It is written to
+  `.env` because the daemon reads it before it starts listening on the
+  network (binds to a port).
+
+Any key that is not in one of these three lists can only be set through
+an environment variable or by restarting.
 
 ## Where Each Field Comes From
 
@@ -116,9 +117,9 @@ Anything not in those tuples must be set via env or restart.
 
 ## Selected Keys
 
-A representative slice of `EDITABLE_RUNTIME_KEY_TUPLE` — the full list
-of ~130 keys is in `editable-config-keys.ts`. Names below are exact and
-case-sensitive.
+A representative sample of `EDITABLE_RUNTIME_KEY_TUPLE`; the full list
+of ~130 keys is in `editable-config-keys.ts`. The names below are exact
+and case-sensitive.
 
 ### Identity and timezone
 
@@ -127,18 +128,19 @@ case-sensitive.
 | `agentDisplayName` | string | What the agent calls itself in DMs. |
 | `character` | string | Free-text user-defined communication style / persona (max 1000 chars). When non-empty, rendered as a `## Character (user-defined)` block into each backend's instruction file. The agent profile itself is selected by ProcessKey, not by this key. |
 | `timezone` | IANA tz | Empty falls back to the system tz. |
-| `dayBoundaryHour` | 0–9 | Default `4`. Controls the agent-day rollover (must be an early-morning hour). |
+| `dayBoundaryHour` | 0–9 | Default `4`. Sets the agent-day boundary — the moment "today" rolls over for the agent (must be an early-morning hour). |
 | `primaryLanguage` | BCP-47 | Output language for DMs, journal, and Obsidian writes. Templates stay English-headered. |
 | `vaultMode` | enum | Where context lives — `plain` (default; `<dataDir>/context`) or `obsidian` (an external Obsidian vault). |
 
 ### Activity scan and gate
 
-The first five keys are **deprecated fallbacks**: the activity-scan
-cadence, active window, min-observations threshold, and enable switch
-moved onto the activity-scan agent (`/agents/activity-scan`, Definition
-tab → Cadence card; Enable/Disable). The keys are still accepted by
-`PATCH /api/config` but no longer surfaced in the dashboard; values
-resolve agent override → legacy config key → built-in default.
+The first five keys are **deprecated fallbacks**. The activity-scan
+cadence (how often it runs), active window, minimum-observations
+threshold, and enable switch now live on the activity-scan agent
+(`/agents/activity-scan`, Definition tab → Cadence card; Enable/Disable).
+`PATCH /api/config` still accepts these keys, but the dashboard no longer
+shows them. A value resolves in this order: agent override → legacy
+config key → built-in default.
 
 | Key | Type | Notes |
 |---|---|---|
@@ -247,7 +249,7 @@ resolve agent override → legacy config key → built-in default.
 ### Feedback learning
 
 The feedback learning loop (capture → nightly consolidation → injection of
-durable lessons). All six knobs are runtime-editable via `PATCH /api/config`,
+durable lessons). All knobs are runtime-editable via `PATCH /api/config`,
 surfaced by `GET /config`, and tunable from the dashboard `/settings/lessons`
 page. Defaults and ranges below are enforced in
 `packages/daemon/src/settings/runtime-settings.ts`.
@@ -255,12 +257,15 @@ page. Defaults and ranges below are enforced in
 | Key | Type | Notes |
 |---|---|---|
 | `feedbackLearningEnabled` | boolean | Default `true` (env `FEEDBACK_LEARNING_ENABLED`). Master kill-switch for the whole loop — capture, consolidation, and injection. |
-| `selfTuningEnabled` | boolean | Default `false` (env `SELF_TUNING_ENABLED`). Actuation gate for the self-tuning review cycle. While `false`, the loop runs in shadow mode: the weekly review still receives `<tuning_recommendations>` and records verdicts via `POST /api/tuning/verdicts`, but no config change is ever applied. With the flag on, apply verdicts for config knobs actuate through the bounded config chokepoint — one owner DM per applied change, `!revert tuning` undoes the latest, and a daily monitor auto-reverts any change whose 7-day verify metrics regressed. Flip only after ≥2 clean shadow cycles (SELF_TUNING_REVIEW_CYCLE_DESIGN.md §7 shadow→live gate). |
+| `selfTuningEnabled` | boolean | Default `false` (env `SELF_TUNING_ENABLED`). Actuation gate for the self-tuning review cycle. While `false`, the loop runs in shadow mode: the weekly review still receives `<tuning_recommendations>` and records verdicts via `POST /api/tuning/verdicts`, but no config change is ever applied. With the flag on, apply verdicts for config knobs actuate through the bounded config chokepoint — one owner DM per applied change, `!revert tuning` undoes the latest, and a daily monitor auto-reverts any change whose 7-day verify metrics regressed. Flip only after ≥2 clean shadow cycles (SELF_TUNING_REVIEW_CYCLE_DESIGN.md §7 shadow→live gate); the daemon DMs you once when 3 consecutive shadow cycles were fully approved (graduation). |
 | `feedbackPromotionThreshold` | 1–10 | Default `2` (env `FEEDBACK_PROMOTION_THRESHOLD`). Weighted-evidence threshold a behavioral / self-critique lesson must clear before it becomes injectable. |
 | `feedbackLessonMaxBytesGlobal` | 1024–32768 | Default `8192` (env `FEEDBACK_LESSON_MAX_BYTES_GLOBAL`). Byte cap for `policies/agent-lessons.md`. |
 | `feedbackLessonMaxBytesPerAgent` | 512–16384 | Default `4096` (env `FEEDBACK_LESSON_MAX_BYTES_PER_AGENT`). Byte cap for each `policies/agents/<slug>/lessons.md`. |
-| `feedbackLessonStaleDays` | 7–365 | Default `60` (env `FEEDBACK_LESSON_STALE_DAYS`). Lessons whose `last=` date is older are pruned, except `kind=constraint` (durable). |
+| `feedbackLessonStaleDays` | 7–365 | Default `60` (env `FEEDBACK_LESSON_STALE_DAYS`). Staleness horizon for the graduated expiration lifecycle: an active lesson past the horizon whose time-decayed confidence is below the floor demotes to provisional (reversible); a provisional lesson uncorroborated for twice the horizon is archived. `kind=constraint` lessons are durable and never expire. |
 | `feedbackSignalRetentionDays` | 30–365 | Default `180` (env `FEEDBACK_SIGNAL_RETENTION_DAYS`). Consumed `feedback_signals` rows older than this are swept. |
+| `feedbackLessonConfidenceFloor` | 0–1 | Default `0.25` (env `FEEDBACK_LESSON_CONFIDENCE_FLOOR`). Inferred lessons whose effective (time-decayed) confidence `cf` falls below this floor are dropped from injection; also the demote test in the expiration lifecycle. Durable `constraint` lessons are exempt from the injection filter, and explicit owner corrections are floor-tested on their undecayed `cf` (an obeyed directive produces no corroborating signals, so decay alone must not silently un-bind it). `0` disables the filter. |
+| `feedbackContradictionGuardCf` | 0–1 | Default `0.6` (env `FEEDBACK_CONTRADICTION_GUARD_CF`). Anti-whiplash guard: a new candidate contradicting an established lesson with `cf` at or above this value is held provisional until it accumulates 1.5x the usual evidence. Explicit owner corrections always win immediately. |
+| `feedbackOutcomeLearningEnabled` | boolean | Default `true` (env `FEEDBACK_OUTCOME_LEARNING_ENABLED`). Includes the per-notification-type outcome rollup (replied / corrected / ignored, correction rate) in the nightly consolidation worksheet so lesson promotions weigh real reactions. |
 
 ## Routine Schedule Times Are Not Configurable
 
@@ -284,10 +289,10 @@ cadence and active window — edited on the activity-scan agent's page
 
 ## Restart-Required Keys
 
-The `RESTART_REQUIRED_KEY_TUPLE` covers fields whose new value is
-written through `applyConfigUpdates` but does not apply to a running
-worker — the dashboard renders a badge prompting an `aitne restart`.
-The current list:
+The `RESTART_REQUIRED_KEY_TUPLE` covers fields whose new value is saved
+through `applyConfigUpdates` but does not reach a worker that is already
+running — the dashboard shows a badge prompting an `aitne restart`. The
+current list:
 
 - `apiPort` (env-only)
 - `externalObsidianVaultName` / `externalObsidianVaultPath` / `externalObsidianWatch`

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

@@ -14,9 +14,7 @@ summary: |
   by skill-level allow-lists. Mirrors src/safety/always-disallowed.ts.
 section: reference
 tags:
-  - reference
   - safety
-  - core
   - audit
 status: stable
 ask_examples:
@@ -25,7 +23,7 @@ ask_examples:
   - Why can't the agent read my .env or SSH keys?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - disallowedTools
   - deniedTools
@@ -41,16 +39,18 @@ related:
 
 # Disallowed Tools
 
-There are two distinct deny layers — the **absolute-block layer**
-(non-overridable) and the **default strict-mode list** (`DEFAULT_DISALLOWED_TOOLS`
-in `src/settings/runtime-settings.ts`, relaxable in Allow mode or via
-`allowedToolsOverride`).
+The agent keeps two separate lists of tools it refuses to run. The
+first is the **absolute-block layer**, which nothing can turn off —
+not your config, not a skill's allow-list. The second is the
+**default strict-mode list** (`DEFAULT_DISALLOWED_TOOLS` in
+`src/settings/runtime-settings.ts`), which you *can* relax by
+switching to Allow mode or by setting `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`.
+The agent always refuses these patterns — no matter which execution
+mode it is in, and no matter what you put in `allowedToolsOverride`.
+Source of truth: `packages/daemon/src/safety/always-disallowed.ts`.
 
 | Category | Examples |
 |---|---|
@@ -79,13 +79,14 @@ managed-Chromium chokepoints above).
 
 ## Default strict-mode list (relaxable)
 
-`DEFAULT_DISALLOWED_TOOLS` (in `src/settings/runtime-settings.ts`, the
-seed for `config.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.
+`DEFAULT_DISALLOWED_TOOLS` (in `src/settings/runtime-settings.ts`)
+seeds `config.disallowedTools` with a few extra blocks you can lift —
+either by setting `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 patterns that are easy to run by accident and hard to undo.
+Because they are **not** part of the absolute-block layer, Allow mode
+permits them.
 
 ## Audit log
 

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

@@ -9,13 +9,11 @@ aliases:
   - key bindings
 category: reference
 summary: |
-  Keyboard shortcuts available in the dashboard. The set is small by
-  design — the dashboard is a low-cognition surface.
+  Keyboard shortcuts available in the dashboard. The set is small on
+  purpose — the dashboard is meant to stay calm and easy to scan.
 section: reference
 tags:
-  - reference
   - dashboard
-  - core
 status: stable
 ask_examples:
   - What keyboard shortcuts work in the dashboard?
@@ -23,7 +21,7 @@ ask_examples:
   - What does pressing "?" do in the dashboard?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - shortcut
   - hotkey
@@ -42,9 +40,9 @@ related:
 
 # Keyboard Shortcuts
 
-The dashboard ships a deliberately small set of shortcuts — it is a
-low-cognition surface, not a power-user IDE. These work from any
-dashboard screen.
+The dashboard ships a deliberately small set of shortcuts — it is built
+to stay calm and easy to scan, not to be a power-user IDE. These work
+from any dashboard screen.
 
 | Keys | Action |
 |---|---|

package/agent-assets/docs/reference/knowledge-layout.md

@@ -19,8 +19,6 @@ summary: |
   api/routes/context/permissions.ts.
 section: knowledge-layout
 tags:
-  - reference
-  - core
   - memory
   - knowledge
   - operations
@@ -34,7 +32,7 @@ ask_examples:
   - Which files can the agent write to?
 locale: en-US
 created: 2026-05-18
-updated: 2026-06-08
+updated: 2026-07-01
 keywords:
   - context
   - knowledge
@@ -87,15 +85,17 @@ knowledge of you. Every file lives under `PA_DATA_DIR/context/`
 (default `~/.personal-agent/context/`) as plain Markdown that you can read,
 edit, version, and back up with ordinary tools.
 
-The vault is partitioned into **six authority classes** — `identity/`, `state/`,
-`plans/`, `journal/`, `knowledge/`, and `policies/`. Each top-level directory
-carries a distinct authority + lifecycle contract; the daemon enforces those
-contracts via the file's YAML frontmatter (advisory in this release; strict in
-the next phase). This shape landed in the context-vault v2 restructure
+The vault is split into **six authority classes** — `identity/`, `state/`,
+`plans/`, `journal/`, `knowledge/`, and `policies/`. An authority class is
+simply a top-level directory with its own rules for who may write to it and
+how long its files are kept. The daemon enforces those rules through each
+file's YAML frontmatter (advisory in this release; strict in the next
+phase). This shape landed in the context-vault v2 restructure
 (migration `0004-context-vault-restructure`); legacy pre-v2 paths such as <!-- drift-allow -->
 `today.md`, `user/profile`, `rules/management`, `agent/journal`, etc. continue to work <!-- drift-allow -->
-because the daemon normalizes them in-process — never via HTTP 3xx — for one
-minor release while shipped skills and task-flows are updated.
+because the daemon rewrites them to the new paths in-process — never via an
+HTTP 3xx redirect — for one minor release while the shipped skills and
+task-flows are updated.
 
 The layout below is the canonical source-of-truth. It mirrors
 `packages/daemon/src/core/context-paths.ts` (`CONTEXT_RELATIVE_PATHS`) and

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