@aitne-sh/aitne 0.1.8 → 0.1.9

package/agent-assets/agents/weekly-review/agent.md

@@ -0,0 +1,51 @@
+---
+# ── Identity ─────────────────────────────────────────────────────────────────
+slug: weekly-review
+name: Weekly Review
+description: "Writes the weekly synthesis note and reviews the roadmap every Friday evening."
+kind: builtin
+version: 1
+enabled: true
+tags: [routine, weekly, journal]
+
+# ── Schedule (Friday 19:00) ──────────────────────────────────────────────────
+schedule:
+  kind: cron
+  expression: "0 19 * * 5"
+
+# ── Backend / routing (tier/model deferred to process_backend_config) ───────
+backend:
+  process_key: routine.weekly_review
+  tier: null
+  model: null
+
+# ── Limits (per execution) ───────────────────────────────────────────────────
+limits:
+  max_turns: 30
+  max_budget_usd: 0.50
+  timeout_minutes: 15
+
+# ── Expected outputs ─────────────────────────────────────────────────────────
+# The synthesis note is keyed on the ISO week (`journal/weekly/YYYY-Www.md`),
+# which the `{date}`-only success-criteria evaluator cannot target in v1, so it
+# is documented here rather than asserted as a criterion.
+outputs:
+  - "journal/weekly/{week}.md"
+  - plans/roadmap.md
+
+success_criteria: []
+
+# ── Stop warning (byte-identical to BUILTIN_AGENT_REGISTRY, §12.1) ──────────
+stop_warning:
+  level: high
+  services_lost:
+    - "Weekly synthesis note (journal/weekly/{week}.md)"
+    - "Weekly roadmap review"
+  dependent_agents: []
+  reactivation_hint: "Re-enable from /agents/weekly-review. Resumes on the next Friday 19:00 firing."
+---
+
+# Weekly Review
+
+Built-in routine — the execution prompt lives in the task-flow, not here.
+See `agent-assets/task-flows/routine.weekly_review.md`.

package/agent-assets/docs/concepts/agent-day.md

@@ -15,9 +15,9 @@ summary: |
 section: agent-day
 tags:
   - core
-  - timing
   - memory
   - routines
+  - scheduler
 status: stable
 ask_examples:
   - When does the agent day actually roll over?
@@ -26,7 +26,7 @@ ask_examples:
   - What is dayBoundaryHour?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - day boundary
   - 04:00
@@ -40,6 +40,7 @@ related:
   - features/memory-files/today
 ui_anchors:
   - /settings
+  - /settings/schedule
 config_keys:
   - dayBoundaryHour
 ---
@@ -50,7 +51,7 @@ config_keys:
 
 Aitne treats the "day" as starting at **04:00 local time**, not
 00:00. Anything you log between midnight and 4am is filed under the day
-that just ended, so a late commit at 02:30 lands in the same `today.md`
+that just ended, so a late commit at 02:30 lands in the same `state/today.md`
 that opened the previous morning.
 
 ## Why This Concept Exists
@@ -58,7 +59,7 @@ that opened the previous morning.
 Owner-as-user installations almost always have late-night work sessions
 that, mentally, belong to "today" even though the wall-clock has already
 ticked over. A day boundary at midnight would split a single coherent
-working session across two `today.md` files, and the morning routine
+working session across two `state/today.md` files, and the morning routine
 would open against an empty schedule because no agent activity had been
 logged for the new calendar day yet.
 
@@ -69,25 +70,26 @@ clean boundary before they start.
 ## Definitions
 
 - **Agent day**: the 24-hour window starting at the configured day-boundary hour and ending at the same hour the next calendar day.
-- **Day boundary**: the hour-of-day that starts the agent day. Configured via the `dayBoundaryHour` setting (default `4`).
-- **Day-stamped file**: any file whose name includes `YYYY-MM-DD` (e.g. `daily/2026-04-25.md`, `weekly/2026-04-20.md`). The date stamp uses the agent-day boundary, not the calendar day.
+- **Day boundary**: the hour-of-day that starts the agent day. Configured via the `dayBoundaryHour` setting (default `4`, valid range `0`–`9`). Values above 9 are rejected — the boundary is intended for the small hours, not mid-day.
+- **Day-stamped file**: any file whose name includes `YYYY-MM-DD` (e.g. `journal/daily/2026-04-25.md`, `journal/weekly/2026-04-20.md`). The date stamp uses the agent-day boundary, not the calendar day.
 
 ## Concrete Examples
 
 | Wall-clock time | Calendar date | Agent day |
 |---|---|---|
-| 2026-04-25 02:30 | April 25 | April 24 (late session) |
-| 2026-04-25 04:30 | April 25 | April 25 |
-| 2026-04-25 23:50 | April 25 | April 25 |
-| 2026-04-26 03:55 | April 26 | April 25 (still!) |
+| 2026-04-25 02:30 | April 25 | April 24 (before boundary) |
+| 2026-04-25 04:30 | April 25 | April 25 (after boundary) |
+| 2026-04-25 23:50 | April 25 | April 25 (normal) |
+| 2026-04-26 03:55 | April 26 | April 25 (before boundary) |
 
 ## Where You See It in the Dashboard
 
 - The Schedule view labels each day's column by **agent day**, so a 02:30 calendar entry appears under the previous day's header.
 - Activity → Conversations groups sessions by agent day for the same reason.
 - Cost analytics roll up by agent day so a late-night research binge does not split into two separate "days" of spend.
+- To change the boundary, open **Settings → Schedule** (`/settings/schedule`) and edit the day-boundary hour.
 
 ## Related
 
-- [Morning Routine](../features/routines/morning-routine.md) opens at the day boundary's morning-routine hour, not midnight.
+- [Morning Routine](../features/routines/morning-routine.md) opens shortly after the day boundary as part of the morning routine, not at midnight.
 - [today.md](../features/memory-files/today.md) is rebuilt once per agent day, anchored on the boundary.

package/agent-assets/docs/concepts/auth-health.md

@@ -20,6 +20,7 @@ tags:
   - safety
   - backends
   - operations
+  - health
 status: stable
 ask_examples:
   - Why is the dashboard showing a degraded backend?
@@ -28,7 +29,7 @@ ask_examples:
   - What is the SubscriptionAuthWarning banner?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - auth
   - authentication
@@ -43,9 +44,18 @@ related:
   - concepts/backends-and-tiers
   - concepts/costs-and-quotas
   - troubleshooting/auth-failed
+ui_anchors:
+  - /settings/models
+  - /
 config_keys:
   - authProbeDisabled
   - authPreflightFreshnessMs
+api_endpoints:
+  - POST /api/backends/:backendId/check-auth
+  - POST /api/backends/:backendId/recovery/start
+  - GET /api/backends/:backendId/recovery/status
+  - POST /api/backends/:backendId/recovery/code
+  - POST /api/backends/:backendId/recovery/cancel
 ---
 
 # Auth Health
@@ -71,12 +81,21 @@ routine fails.
   is live. Without an API key, the probe checks whatever local CLI
   login Aitne fell back to (Claude credentials store, Codex token,
   Gemini ADC).
-- **Preflight freshness**: how long the daemon trusts a successful
-  probe before re-running.
-- **Recovery**: backend-specific repair. The recommended path is
-  re-pasting the API key on `/settings/models`; for the fallback
-  path, re-running the matching CLI login (`claude`,
-  `codex login`, `gemini auth`).
+- **Preflight freshness**: how long the daemon trusts a cached probe
+  result before the router consults the backend again. Controlled by
+  `authPreflightFreshnessMs` (default 600000 = 10 min). A cached
+  `expired`/`missing` status younger than this window makes the router
+  skip the main backend and route straight to fallback. Set to `0` to
+  disable the pre-flight check entirely.
+- **Recovery**: backend-specific repair. The recommended path is always
+  re-pasting a paid API key on `/settings/models`. If you run on CLI
+  subscription auth instead, you can recover the login from the same
+  page: `/settings/models` exposes a recovery dialog that drives the
+  backend's own interactive login subprocess —
+  `claude auth login --claudeai` (browser OAuth), `codex login
+  --device-auth` (device code), or Gemini's direct OAuth flow. As a
+  manual fallback you can always re-run the backend's CLI login in a
+  terminal yourself.
 
 ## Concrete Examples
 
@@ -86,7 +105,9 @@ routine fails.
 - Operator never registered an API key, ran on the subscription
   fallback, and the underlying `claude` CLI session expired → probe
   fails → card flips amber → recommended fix is to register an API
-  key on `/settings/models`; otherwise re-run the CLI login.
+  key on `/settings/models`. To keep using subscription auth instead,
+  open the recovery dialog on the same page and complete the browser
+  OAuth login it launches.
 
 Cloud-provider credentials (Bedrock / Vertex / Foundry / Azure
 OpenAI / Gemini-Vertex) are not probed against a `models` endpoint —
@@ -94,7 +115,23 @@ those providers trust the SDK's runtime auth chain, so the auth-
 health card stays neutral until the first execution either succeeds
 or surfaces a runtime auth error.
 
+## The "API key recommended" warning
+
+Separate from probe failures, `/settings/models` (and the setup
+wizard's AI Backends step) shows a standing **API-key-recommended**
+warning whenever a backend has no registered key. Skipping the key
+falls the daemon back to that backend's local CLI subscription login,
+which most providers do not officially support for automated agents —
+Anthropic in particular currently prohibits running the Claude Agent
+SDK on a Claude Pro / Max subscription. The warning is advisory, not a
+probe result: it stays visible while you are on the fallback so you can
+register a paid key and leave the gray area.
+
 ## Related
 
-- [Backends and Tiers](backends-and-tiers.md)
-- [Troubleshooting: Auth Failed](../troubleshooting/auth-failed.md)
+- [Backends and Tiers](backends-and-tiers.md) — tiers, models, and
+  fallback routing.
+- [Costs and Quotas](costs-and-quotas.md) — how API-key billing and
+  quota signals interact.
+- [Troubleshooting: Auth Failed](../troubleshooting/auth-failed.md) —
+  step-by-step recovery when a card goes red.

package/agent-assets/docs/concepts/backends-and-tiers.md

@@ -31,7 +31,7 @@ ask_examples:
   - How does Aitne fail over when a backend hits its quota?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - claude
   - codex
@@ -55,6 +55,24 @@ related:
   - features/operations/backend-routing
 ui_anchors:
   - /settings/models
+  - /analytics
+process_keys:
+  - message.dm
+  - dashboard.chat
+  - dashboard.docs_qa
+  - routine.morning_routine
+  - gmail_classify
+  - calendar.change
+  - delegated_task
+  - delegated_task_heavy
+config_keys:
+  - claudeExecutionPermissionMode
+  - codexExecutionPermissionMode
+  - geminiExecutionPermissionMode
+  - opencodeExecutionPermissionMode
+  - opencodeBaseUrl
+  - opencodeServerUsername
+  - delegatedTaskHeavyEnabled
 ---
 
 # Backends and Tiers
@@ -62,27 +80,39 @@ ui_anchors:
 ## TL;DR
 
 Four backends are supported: **Claude Code** (default), **Codex**,
-**Gemini CLI**, and **OpenCode**. Each backend exposes three classes
-of model used at install time:
-
-- **Medium / Main** (Sonnet 4.6 / GPT-5.4-mini / Gemini 3 Flash /
-  Sonnet 4.6 via OpenCode) — the default for owner-facing work (DMs,
-  daily / weekly review, morning routine, dashboard chat, scheduled
-  tasks).
-- **Lite / Delegated** (Haiku 4.5 on Claude and OpenCode; latest
-  light tier on Codex / Gemini) — cheaper model used for "simple"
-  backend surfaces with no owner in the loop: Gmail classification,
-  GitHub event triage, git-poll observers, calendar-change
-  handlers, the routine pre-pass fetcher, the `delegated_task`
-  invoker.
-- **High / Heavy** (Opus 4.7 / GPT-5.5 / Gemini 3 Pro / Opus 4.7
-  via OpenCode) — registered but *not* auto-selected. Operators opt
-  in per-process from `/settings/models`. After morning-routine
-  Phase 7 (2026-05-16) the only flows that run heavy by default are
-  `setup` (one-shot wizard) and `knowledge.import` (owner-uploaded
-  files). The first morning routine after setup runs on medium
-  tier with a daemon-prepared `<roadmap_skeleton>` block instead of
-  the retired heavy `routine.morning_routine_initial`.
+**Gemini CLI**, and **OpenCode**. Each backend exposes three model
+tiers. The per-backend defaults seeded at install time are:
+
+| Tier | Claude | Codex | Gemini | OpenCode |
+|---|---|---|---|---|
+| **medium** (main) | Sonnet 4.6 | GPT-5.4 | Gemini 3.1 Pro (preview) | Sonnet 4.6 |
+| **lite** (delegated) | Haiku 4.5 | GPT-5.4 Mini | Gemini 3.1 Flash Lite (preview) | Haiku 4.5 |
+| **high** (heavy) | Opus 4.8 | GPT-5.4¹ | Gemini 3.1 Pro (preview)¹ | Opus 4.8 |
+
+¹ Codex and Gemini have no separately-seeded high model — their high
+tier collapses to the medium model via `SEED_HIGH_TIER_OVERRIDE`.
+Codex's flagship GPT-5.5 is Opus-priced and stays an opt-in; Gemini
+has no Opus-priced Google flagship worth defaulting to. Pin a higher
+model per row from `/settings/models` if you want it.
+
+What each tier is for:
+
+- **Medium / Main** — the default for owner-facing work: DMs and
+  mentions, dashboard chat, morning / evening / weekly / monthly
+  review, the hourly check, scheduled tasks.
+- **Lite / Delegated** — the cheaper model for "simple" backend
+  surfaces with no owner in the loop: Gmail classification, GitHub
+  event triage, git-poll observers, calendar-change handlers, the
+  routine pre-pass fetcher, the `delegated_task` invoker.
+- **High / Heavy** — registered but *not* auto-selected. After the
+  "no Opus by default" pass (2026-05-16), **no install-time-seeded
+  surface defaults to high.** The only `high`-tagged ProcessKey is
+  `delegated_task_heavy`, and it is opt-in (gated by the
+  `delegatedTaskHeavyEnabled` config flag). Operators can pin any
+  other ProcessKey to high per row from `/settings/models`. The
+  first morning routine after setup runs on **medium** tier with a
+  daemon-prepared `<roadmap_skeleton>` block instead of the retired
+  heavy `routine.morning_routine_initial`.
 
 Every ProcessKey resolves to a backend + model binding via
 `BackendRouter`. Aitne **does not store or read subscription-plan
@@ -126,11 +156,13 @@ top of the `@opencode-ai/sdk` HTTP server and supports the same
 `ProcessKey` set as the other backends. Two operating modes:
 
 - **Managed** — the daemon spawns and supervises a local
-  `opencode` HTTP server on loopback. Configuration (model,
-  permissions, agent dir) is written into a managed `opencode.json`
-  under `<dataDir>/opencode-home/`.
+  `opencode` HTTP server on loopback (`127.0.0.1`, OS-picked port).
+  Per-session config (model, permissions, agent dir) is passed
+  inline to the server via the `OPENCODE_CONFIG_CONTENT` env var —
+  no config file is written to disk.
 - **Remote** — you point Aitne at an existing OpenCode server
-  baseUrl (your own cluster or a managed deployment).
+  baseUrl (your own cluster or a managed deployment), set via the
+  `opencodeBaseUrl` / `opencodeServerUsername` config keys.
 
 OpenCode is a runtime peer of Claude / Codex / Gemini for
 dispatching ProcessKeys, but it intentionally does **not** host
@@ -156,10 +188,12 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 - **Backend**: the agent runtime. One of `claude`, `codex`, `gemini`,
   `opencode`.
 - **Tier**: `lite`, `medium`, or `high`. `high` maps to the strongest
-  model (Opus 4.7 / GPT-5.5 / Gemini 3 Pro / Opus 4.7 via OpenCode).
-  `medium` (Sonnet 4.6 and equivalents) is the operator's day-to-day
-  tier for owner-facing work; `lite` (Haiku 4.5 and equivalents) is
-  reserved for mechanical / delegated surfaces.
+  model class (Opus-class — Opus 4.8 on Claude and OpenCode; on Codex
+  and Gemini the seeded high binding collapses to the medium model).
+  `medium` (Sonnet-class — Sonnet 4.6 and equivalents) is the
+  operator's day-to-day tier for owner-facing work; `lite`
+  (Haiku-class — Haiku 4.5 and equivalents) is reserved for
+  mechanical / delegated surfaces.
 - **Main / Fallback**: each ProcessKey has a `main` backend and a
   `fallback`. The router fails over on `BackendQuotaError` /
   `BackendDecisiveFailure`.
@@ -174,12 +208,13 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 | `routine.hourly_check` | claude | Sonnet 4.6 |
 | `message.dm` | claude | Sonnet 4.6 |
 | `dashboard.chat` | claude | Sonnet 4.6 |
-| `dashboard.docs_qa` | inherits from `message.dm` | Sonnet 4.6 (light forced) |
+| `dashboard.docs_qa` | inherits from `message.dm` | Sonnet 4.6 (locked to medium) |
 | `gmail_classify` | claude | Haiku 4.5 |
 | `github.*` | claude | Haiku 4.5 |
 | `git.push.detected` (and other git-poll keys) | claude | Haiku 4.5 |
 | `calendar.change` | claude | Haiku 4.5 |
 | `delegated_task` | claude | Haiku 4.5 |
+| `delegated_task_heavy` | claude | Opus 4.8 (high; opt-in, off by default) |
 
 ## Where You See It in the Dashboard
 

package/agent-assets/docs/concepts/costs-and-quotas.md

@@ -31,7 +31,7 @@ ask_examples:
   - How does Gemini's per-day quota work?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - cost
   - budget
@@ -43,6 +43,7 @@ keywords:
   - opencode
   - openrouter
   - daily cap
+  - monthly cap
   - autonomous cap
 related:
   - concepts/backends-and-tiers
@@ -53,6 +54,11 @@ ui_anchors:
   - /settings/models
 config_keys:
   - autonomousDailyCostCapUsd
+  - autonomousMonthlyCostCapUsd
+process_keys:
+  - routine.morning_routine
+  - routine.fetch_window
+  - routine.hourly_check
 ---
 
 # Costs and Quotas
@@ -92,8 +98,13 @@ agent's problem to *avoid*: the dashboard shows you what each routine
 costs so you can re-pin tiers if a routine has gotten too expensive.
 
 The autonomous daily-cost cap (`autonomousDailyCostCapUsd`) is a
-bumper, not a budget — it pauses autonomous routines when crossed but
-does not interrupt reactive (in-the-loop) traffic.
+bumper, not a budget — once the day's autonomous spend crosses it the
+dispatcher starts shedding the *lowest-priority* routines first
+(hourly check), and only escalates to higher-priority ones as spend
+climbs further; the morning routine is the last to be cut. Reactive
+(in-the-loop) DMs and dashboard chat always pass through. A separate
+`autonomousMonthlyCostCapUsd` is a notifications-only soft cap — it
+fires an alert when crossed but never skips a session.
 
 ## Authentication policy
 
@@ -137,13 +148,23 @@ register an API key on `/settings/models`.
   `codex login`, `gemini auth`). Used only when no API key is
   configured. Cost behaviour then matches whatever the subscription
   enforces (e.g. Claude's rolling 5-hour Opus window on a Max plan).
-- **Daily cost cap**: `autonomousDailyCostCapUsd` — autonomous routines
-  pause on the day they cross it. Reactive DMs / dashboard chat keep
-  running; you can always reach the agent.
+- **Daily cost cap**: `autonomousDailyCostCapUsd` (default unset) —
+  once the day's autonomous spend crosses it, lower-priority routines
+  are skipped first (hourly check at 100% of the cap, the morning
+  routine only at 200%). Reactive DMs / dashboard chat keep running;
+  you can always reach the agent. Distinct from the removed
+  `maxDailyCostUsd`, which used to blanket-block reactive traffic too.
+- **Monthly cost cap**: `autonomousMonthlyCostCapUsd` (default unset) —
+  a notifications-only soft threshold across the rolling agent month;
+  it raises an alert in the Notifications Center but never skips a
+  session.
 - **Per-process tier**: each ProcessKey has its own tier, max-turns,
   and max-budget USD. Configurable on `/settings/models`.
 - **Quota error**: `BackendQuotaError` thrown by an SDK / CLI tells
-  the router to fail over to the fallback backend.
+  the router to fail over to the fallback backend. Its sibling
+  `BackendDecisiveFailure` (e.g. an auth failure) triggers the same
+  failover — these two signals are why a routine that started on
+  Claude can finish on Codex.
 
 ## Concrete Examples
 
@@ -162,21 +183,35 @@ register an API key on `/settings/models`.
   `routine.morning_routine` envelope (medium tier) with a
   daemon-prepared `<roadmap_skeleton>` block.
 - Gemini hourly check on Flash via `GEMINI_API_KEY` = ~$0.0005 per
-  fire on the paid tier; free tier instead consumes a per-day quota
-  slot.
+  fire on the paid tier; the free tier instead consumes one of a
+  fixed per-day request budget (Aitne caps Gemini at 450 requests/day
+  to match Google's free-tier daily limit — this ceiling is
+  Gemini-only by design; Claude and Codex meter per-window and surface
+  exhaustion as a quota error).
 - Claude Code without an API key (subscription fallback on a Max20
   login) = covered by the subscription, but the daemon flags the
   fallback because it falls outside Anthropic's published policy.
 
-## Where You See It in the Dashboard
+## Where You See It
 
-- **Analytics** rolls today's cost by backend, by ProcessKey, and by
-  hour. When a backend is running on the subscription fallback,
-  remaining-window math is shown there too.
+In the dashboard:
+
+- **Analytics** (`/analytics`) rolls today's cost by backend, by
+  ProcessKey, and by hour. When a backend is running on the
+  subscription fallback, remaining-window math is shown there too.
 - **Sidebar footer** shows the day's running total.
 - **Activity** event details include the per-execute cost.
-- **Settings → Models** exposes the per-backend API-key panel and a
-  warning banner whenever a backend is running on subscription auth.
+- **Settings → Models** (`/settings/models`) exposes the per-backend
+  API-key panel and a warning banner whenever a backend is running on
+  subscription auth.
+
+From a DM or the terminal:
+
+- **`!cost`** (and `!cost claude` / `!cost codex` / `!cost gemini`)
+  DM the agent for trailing-7-day spend, broken down or per-backend.
+- **`aitne status`** prints today's action count and spend;
+  **`aitne audit`** lists the action log (filter with `--since`,
+  `--backend`, `--result`).
 
 ## Related
 

package/agent-assets/docs/concepts/delegated-mode.md

@@ -36,7 +36,7 @@ ask_examples:
   - Why don't I see a SKILL.md for Gmail in my Codex session?
 locale: en-US
 created: 2026-04-26
-updated: 2026-05-17
+updated: 2026-05-28
 keywords:
   - delegated mode
   - direct mode
@@ -55,9 +55,16 @@ related:
   - features/integrations/mail
 ui_anchors:
   - /connections
+  - /connections/mail
+  - /connections/calendar
   - /settings/models
-config_keys:
-  - integrations
+api_endpoints:
+  - PATCH /api/integrations/:key
+  - POST /api/integrations/:key/exec
+  - POST /api/integrations/:key/probe
+  - POST /api/observations/batch
+context_files:
+  - policies/integrations.md
 ---
 
 # Delegated Mode (Integration Modes)
@@ -98,6 +105,12 @@ the main DM backend — `BackendRouter.setMainBackend` cascades unmatched
 is indistinguishable from `delegated` same-backend (both are in-session
 MCP); the difference is who polls (no one, for `native`).
 
+> The four modes are `direct | delegated | native | disabled`
+> (`INTEGRATION_MODES` in `packages/shared/src/integrations.ts`).
+> `git` and `github` support only `direct | delegated | disabled` — no
+> native mode (they use read-only CLI connectors), and `browser_history`
+> is `direct | disabled` only.
+
 ## Why This Concept Exists
 
 The setup tax for direct mode (OAuth client setup in a vendor console, then
@@ -154,7 +167,10 @@ that case the daemon spawns the other backend per call.
   subprocess for each call. A `SKILL.delegated.<sessionBackend>.md`
   file is materialized into the session workdir.
 - **`integrations.md`** — daemon-rendered snapshot of every
-  integration's mode at `~/.personal-agent/integrations.md`. The agent
+  integration's mode. After the context-vault restructure it lives
+  inside the vault under the `policies` class at
+  `<contextDir>/policies/integrations.md` (the legacy
+  `~/.personal-agent/integrations.md` location was retired). The agent
   reads it to know which path to take.
 
 ## How to Choose
@@ -184,12 +200,35 @@ connector) cascade to `disabled` and the operator gets a DM.
 
 ## Concrete Examples
 
-| Setup | What happens on a Gmail search |
+What happens on a Gmail search, by setup:
+
+| Setup | Path |
 |---|---|
-| Gmail direct | Agent: `curl /api/mail/<acct>/messages?q=...` → daemon hits Gmail API with stored OAuth |
-| Gmail delegated to Codex × Codex DM (same-backend) | Agent: `mcp__codex_apps__gmail._search_emails(...)` → Codex's connector hits Gmail. No daemon involvement. No skill file. |
-| Gmail delegated to Codex × Claude DM (cross-backend) | Agent: `curl -X POST /api/integrations/gmail/exec -d '{"task":"Search Gmail for newer_than:1d, return id/subject/from/snippet/date for each message","outputSchema":{"type":"object","required":["messages"],"properties":{"messages":{"type":"array","items":{...}}}},"maxToolCalls":3,"cacheable":true}'` → daemon spawns Codex subprocess with `proxy.md` profile → task-mode planner picks `_search_emails` from the registered `capabilityTools` → returns structured `{messages:[…]}` conforming to `outputSchema` |
-| Gmail native on Codex DM | Agent: `mcp__codex_apps__gmail._search_emails(...)` (identical to delegated same-backend) → Codex's connector hits Gmail. No daemon involvement. Daemon poller is OFF; the routine pre-pass POSTs results to `/api/observations/batch`. |
+| Gmail **direct** | `curl /api/mail/<acct>/messages?q=...` → daemon hits Gmail API with stored OAuth |
+| Gmail **delegated** to Codex, Codex DM (same-backend) | Agent calls `mcp__codex_apps__gmail._search_emails(...)` → Codex's connector hits Gmail. No daemon involvement. No skill file. |
+| Gmail **delegated** to Codex, Claude DM (cross-backend) | Agent POSTs to `/api/integrations/gmail/exec` in task mode (see below) → daemon spawns a Codex subprocess → returns a structured result. |
+| Gmail **native** on Codex DM | Identical call to delegated same-backend (`mcp__codex_apps__gmail._search_emails(...)`). No daemon involvement. The daemon poller is OFF; the routine pre-pass POSTs results to `/api/observations/batch`. |
+
+The cross-backend row above issues a task-mode `/exec` call:
+
+```bash
+curl -X POST http://localhost:8321/api/integrations/gmail/exec \
+  -d '{
+    "task": "Search Gmail for newer_than:1d, return id/subject/from/snippet/date for each message",
+    "outputSchema": {
+      "type": "object",
+      "required": ["messages"],
+      "properties": { "messages": { "type": "array", "items": { } } }
+    },
+    "maxToolCalls": 3,
+    "cacheable": true
+  }'
+```
+
+The daemon spawns a Codex subprocess with the `proxy.md` profile, the
+task-mode planner picks `_search_emails` from the registered
+`capabilityTools`, runs it, and returns a structured `{messages:[…]}`
+conforming to `outputSchema`.
 
 ## How the Skill File Resolves
 
@@ -222,14 +261,14 @@ returns one of four values, picked by tie-break order
   `delegated` and `native` are gated on a **live probe** (§4.12.2)
   that confirms three things before the mode is written to
   `integrations.md`: the backend binary is resolvable, backend auth
-  is valid, and the connector reports every `requiredCapability` the
-  descriptor demands. Cached probe rows are invalidated on mode
+  is valid, and the connector reports every `requiredCapabilities`
+  entry the descriptor demands. Cached probe rows are invalidated on mode
   change. `POST /api/integrations/:key/probe` is the chokepoint.
 
 ## How `integrations.md` Reflects This
 
-`~/.personal-agent/integrations.md` is the operator-readable snapshot the
-agent consults at session-init. It is rendered as a Markdown table:
+`<contextDir>/policies/integrations.md` is the operator-readable snapshot
+the agent consults at session-init. It is rendered as a Markdown table:
 
 ```markdown
 ## Current state