@aitne-sh/aitne 0.1.7 → 0.1.9

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

@@ -6,49 +6,127 @@ id: process-keys-ref
 aliases:
   - process key list
   - dispatch keys
+  - processkey reference
+  - routine 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:
+  - core
   - reference
   - dispatch
+  - backends
+  - routing
 status: stable
 ask_examples:
   - List all the ProcessKeys
   - What is the default tier for hourly check?
+  - Which ProcessKeys are configurable from the dashboard?
+  - What is routine.fetch_window used for?
 locale: en-US
+keywords:
+  - processkey
+  - ProcessKey
+  - dispatch
+  - tier
+  - lite
+  - medium
+  - high
+  - routine.morning_routine
+  - routine.fetch_window
+  - message.dm
+  - calendar.change
+  - delegated_task
+  - gmail_classify
 created: 2026-04-25
-updated: 2026-04-25
+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) | 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.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 — `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). 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 |
+| `routine.user_profile_sweep` | Periodic agent-day profile summarization pass | medium | no |
+| `routine.roadmap_refresh` | Periodic roadmap re-derivation (NOT in `ROUTINE_WINDOWS` — no `routine.fetch_window` pre-pass; the synthesis session itself drives the native-mode MCP fan-out) | medium | yes |
+| `routine.skill_curation` | Background skill-curation / overlay refinement loop (cron cadence picked at `/settings/self-learning`) | medium | yes |
 | `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 |
+| `message.dm` | Owner DM | medium | yes |
+| `message.mention` | @-mention in a paired Slack channel where the agent is invited (DMs are `message.dm`; Telegram/WhatsApp groups are filtered out) | medium | yes |
+| `dashboard.chat` | `/chat` send | medium | yes |
+| `dashboard.docs_qa` | Docs QA panel — tier is hard-forced to medium regardless of any `message.dm` override; backend choice still inherits | medium (forced) | yes (backend only) |
+| `agent.task` | Future-dated agent action (recurring schedules) | medium | yes |
+| `agent.dm_task` | DM-tone scheduled session (e.g. morning briefing) | medium | yes |
+| `schedule.approaching` | Pre-event reminder | medium | no |
+| `calendar.change` | Calendar event added / moved / cancelled | lite | yes |
+| `gmail_classify` | Mail classifier inference | lite | yes |
+| `delegated_task` | Generic delegated sub-job invocation | lite | no (server-resolved) |
+| `delegated_task_heavy` | Opt-in heavy variant gated by `delegatedTaskHeavyEnabled` (Approve-tier) | high | no (server-resolved) |
+| `observation.summarize` | Per-observation summarizer (cost-reduction §A) | lite | yes |
+| `integration_drift_sync` | Periodic drift-reconciler across connected integrations | lite | no |
+| `knowledge.import` | One-shot heavy session that ingests an owner-uploaded knowledge file | medium | no |
+| `setup` | One-shot setup wizard backend probe / write | medium | no |
+| `git.lifecycle.poll` | Git repo poll observer | lite | yes |
+| `git.push.detected` | New push on a watched git repo | lite | yes |
+| `git.push.force_pushed` | Force-push detected on a watched repo | lite | yes |
+| `git.branch.created` | New branch on a watched repo | lite | yes |
+| `git.tag.created` | New tag on a watched repo | lite | yes |
+| `git.merge_to_default` | Merge into the default branch | lite | yes |
+| `git.local_ahead.stale` | Local branch ahead of remote for too long | lite | yes |
+| `git.project.{init,update,refresh_architecture,retemplate}` | Project-doc lifecycle hooks for watched repos (one-shot, generative — Sonnet by default) | medium | yes |
+| `github.assigned` | Issue / PR assigned to the operator | lite | yes |
+| `github.pull_request.review_requested` | PR review requested | lite | yes |
+| `github.workflow_run.failed` | CI run failed on a tracked repo | lite | yes |
+| `github.security_alert` | Dependabot / security alert raised | lite | yes |
+| `wiki.ingest_url` | URL → vault ingest (WIKI_BUILDER_DESIGN P1) | medium | yes |
+| `wiki.compile` | Raw → wiki synthesis (P1) | medium | yes |
+| `wiki.ask` | Q&A against the compiled wiki (P1) | medium | yes |
+| `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`).
@@ -57,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

@@ -3,57 +3,101 @@ schema_version: 1
 slug: reference/skills
 title: Skills (Reference)
 id: skills-ref
+aliases:
+  - skill index
+  - built-in skills
+  - skill registry
 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:
+  - core
   - reference
   - skills
 status: stable
 ask_examples:
   - List all the built-in skills
   - What does the docs-search skill do?
+  - What does the wiki skill do?
+  - How is each skill scoped?
 locale: en-US
+keywords:
+  - skill
+  - skills
+  - SKILL.md
+  - skill registry
+  - overlay
+  - context skill
+  - mail skill
+  - wiki skill
+  - notify skill
 created: 2026-04-25
-updated: 2026-05-04
+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/operations/skill-self-optimization
+  - 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. |
-| `context` | Read / write context Markdown — projects, weekly/monthly summaries, agent journal, generic context files. |
+| `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. |
-| `mail` | Unified multi-provider mail interface (Gmail, Outlook, Yahoo, iCloud) — search, label, classify. |
+| `mail` | Unified multi-provider mail interface (Gmail, Outlook, Yahoo, iCloud, generic IMAP) — search, label, classify. |
+| `gmail-lifestyle` | Conditional skill (gated by `gmailLifestyleActive` / `gmailLifestyleActiveForDm`). Merges travel-booking queries, calendar-event commute calculations, and receipt save-to-external-vault. |
+| `managed-tasks` | Register, modify, stop, or one-off-run a Managed Task (`mt_<n>`) — a recurring agent fetch against a third-party app (Zoom / Gmail / Drive / Notion / custom MCP). Conditional skill gated by `managedTasksActive` / `managedTasksActiveForDm`. |
 | `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. |
+| `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. |
-| `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). |
+| `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). |
-| `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. |
+| `scheduled-managed-task` | Surface and act on Managed Tasks that are due now. |
+| `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`. See
-[Skill Self-Optimization](../features/operations/skill-self-optimization.md).
+## 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,22 +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
@@ -44,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 — see
-   [Use a Cloud Provider for Models](../guides/use-cloud-providers.md)).
-   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

@@ -3,53 +3,127 @@ schema_version: 1
 slug: troubleshooting/dashboard-shows-degraded
 title: Dashboard Shows Degraded
 id: dashboard-shows-degraded
+aliases:
+  - dashboard 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
-status: stable
+  - health
+  - 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
+  - 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
 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. `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/`.
+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)