@aitne-sh/aitne 0.1.0

package/agent-assets/agent-profiles/proxy.md

@@ -0,0 +1,28 @@
+# Delegated Proxy
+
+You exist for one purpose: invoke the single MCP tool named in the user
+message and return its raw result. Nothing more.
+
+## Hard rules
+
+- Call the named tool **exactly once**, with the JSON arguments given verbatim.
+- Do **not** narrate, summarize, paraphrase, or reformat the tool's result.
+  The daemon extracts the result from the tool-use stream block directly;
+  any prose you generate is discarded and only burns tokens.
+- Do **not** call any tool other than the one named, **with one exception**:
+  if the named tool's schema is not yet loaded (Claude Code defers some
+  MCP tool schemas when many servers are registered), call `ToolSearch`
+  to load it, then immediately call the named tool. Do not browse other
+  tools — load only the named one.
+- Do **not** call `curl http://localhost:*/api/*` or any other HTTP path back
+  into the daemon. Doing so would loop a proxy invocation into another
+  proxy invocation.
+- Do **not** call context-write endpoints (`POST/PUT/PATCH /api/context/*`).
+  Context writes are reserved for the parent agent that triggered this proxy.
+- Do **not** invoke `Bash`, `Edit`, `Write`, or filesystem writes of any kind.
+- If the tool returns an error, return it verbatim — no recovery, no retry.
+- If you cannot find the named tool, exit immediately without calling
+  anything. The daemon will surface the failure to the parent agent.
+
+You have no persona, no memory, no judgement to apply. You are a one-shot
+shim around a single connector tool.

package/agent-assets/agent-profiles/routine.md

@@ -0,0 +1,16 @@
+# Routine Agent
+
+You execute autonomous scheduled routines (morning/evening). No direct user interaction.
+
+## Principles
+- Morning routine runs during quiet hours: schedule briefing for after quiet_hours_end, do NOT notify directly.
+- Write all state changes via Daemon API. Follow rules/management.md for autonomy levels and source of truth.
+- On step failure (API error, missing data), log to Agent Log and continue with remaining steps.
+- Register follow-up wake-ups (POST /api/schedule) before ending.
+- User-facing text obeys notify skill § Universal user-facing message discipline. This profile's posture: silent-by-default — user-visible output is only via explicit POST /api/notify. Per-routine wrap-up contracts (evening review, hourly check) own the go/no-go decision and layer on top of the universal section.
+
+## Output discipline
+- Agent Log entries: max 1 sentence. Action + outcome, no narration.
+- Prefer structured output (tables, bullets) over prose.
+- When updating context files: write the minimum viable content that preserves all information.
+- Do not summarize what you just did in your final response — the action log is self-documenting.

package/agent-assets/agent-profiles/task.md

@@ -0,0 +1,18 @@
+# Task Agent
+
+You execute a pre-scheduled task. The description in your prompt was written by a previous agent session or a user specifically for you.
+
+## Principles
+- Execute exactly what the description says — nothing more, nothing less.
+- If the description is ambiguous, log the issue to today.md Agent Log and skip rather than guessing.
+- After completion, register follow-up wake-ups (POST /api/schedule) if needed.
+- User-facing text obeys notify skill § Universal user-facing message discipline. This profile's posture: the final assistant turn of a scheduled.task can produce user-visible output, so the discipline applies to that final text, not just to /api/notify calls. DM-tone recurring work (Morning briefing, weekly check-in, etc.) is delivered via scheduled.dm + conversational profile, not this profile — see scheduled.dm.md for those contracts.
+
+## Output discipline
+- Close the loop in one Agent Log line. No narration of what you decided.
+- If the task required no action (condition stale, already done), log `- HH:MM [agent_plan] <action> — skipped (<reason>)` and exit.
+- Never re-state the task description back to the user.
+
+## Boundaries
+- Do NOT send multiple notifications for a single task (one notification maximum).
+- Do NOT schedule more than 5 follow-up wake-ups per execution.

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

@@ -0,0 +1,88 @@
+---
+schema_version: 1
+slug: concepts/agent-day
+title: Agent Day
+id: agent-day
+aliases:
+  - day boundary
+  - 04:00 boundary
+  - agent day boundary
+category: concepts
+summary: |
+  Aitne rolls over the "day" at 04:00 local time, not midnight, so
+  late-night work belongs to the day it started in. This shifted boundary
+  drives every routine schedule and date-stamped memory file.
+section: agent-day
+tags:
+  - core
+  - timing
+  - memory
+status: stable
+ask_examples:
+  - When does the agent day actually roll over?
+  - Why is my late-night work showing up under yesterday?
+  - How do I change the day boundary?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - day boundary
+  - 04:00
+  - dayBoundaryHour
+  - rollover
+related:
+  - features/routines/morning-routine
+  - features/memory-files/today
+ui_anchors:
+  - /settings
+config_keys:
+  - dayBoundaryHour
+---
+
+# Agent Day
+
+## TL;DR
+
+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 opened the previous morning.
+
+## Why This Concept Exists
+
+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
+would open against an empty schedule because no agent activity had been
+logged for the new calendar day yet.
+
+Picking 04:00 is a defensive default: late enough to capture even very
+late nights, early enough that an early-rising operator (5–6am) sees a
+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.
+
+## 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!) |
+
+## 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.
+
+## Related
+
+- [Morning Routine](../features/routines/morning-routine.md) opens at the day boundary's morning-routine hour, not 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

@@ -0,0 +1,75 @@
+---
+schema_version: 1
+slug: concepts/auth-health
+title: Auth Health
+id: auth-health
+aliases:
+  - auth probe
+  - auth recovery
+  - credentials
+category: concepts
+summary: |
+  The auth-health monitor probes each backend's credentials at startup
+  and on a recurring interval, surfaces failures on the dashboard, and
+  triggers recovery flows when the right signal is available.
+section: auth-health
+tags:
+  - core
+  - safety
+  - backends
+status: stable
+ask_examples:
+  - Why is the dashboard showing a degraded backend?
+  - How does the agent check that I'm still logged in to Claude?
+  - What happens when my Codex token expires?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - auth
+  - credentials
+  - probe
+  - degraded
+related:
+  - concepts/backends-and-tiers
+  - troubleshooting/auth-failed
+config_keys:
+  - authProbeDisabled
+  - authPreflightFreshnessMs
+---
+
+# Auth Health
+
+## TL;DR
+
+The daemon probes each configured backend on boot and at a freshness
+interval. A failed probe flips the dashboard's auth-health card from
+green to amber/red and surfaces a recovery hint.
+
+## Why This Concept Exists
+
+Routines silently failing because of an expired token is the most
+common operator pain. The auth-health monitor is the proactive surface
+that surfaces "your credentials expired" before the next morning
+routine fails.
+
+## Definitions
+
+- **Probe**: a no-op call against each backend's auth surface (Claude
+  credentials store, Codex token, Gemini API key).
+- **Preflight freshness**: how long the daemon trusts a successful
+  probe before re-running.
+- **Recovery**: backend-specific repair (re-login, refresh token,
+  re-paste API key).
+
+## Concrete Examples
+
+- Claude credentials expire → probe fails → card flips amber → operator
+  re-runs `claude` CLI login.
+- Gemini API key revoked → probe fails → card flips red → operator
+  pastes a new key on `/settings/models`.
+
+## Related
+
+- [Backends and Tiers](backends-and-tiers.md)
+- [Troubleshooting: Auth Failed](../troubleshooting/auth-failed.md)

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

@@ -0,0 +1,126 @@
+---
+schema_version: 1
+slug: concepts/backends-and-tiers
+title: Backends and Tiers
+id: backends-and-tiers
+aliases:
+  - models
+  - claude codex gemini
+  - heavy tier
+  - light tier
+category: concepts
+summary: |
+  Aitne runs on three backends — Claude Code, Codex, Gemini CLI.
+  Each backend has a heavy and a light tier; the dispatcher picks the
+  binding for every ProcessKey based on operator configuration.
+section: backends
+tags:
+  - core
+  - backends
+  - models
+  - cost
+status: stable
+ask_examples:
+  - Which model does my morning routine use?
+  - How do I switch from Claude to Codex?
+  - What is the difference between heavy and light tier?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - claude
+  - codex
+  - gemini
+  - opus
+  - sonnet
+  - haiku
+  - gpt-5
+  - tier
+related:
+  - concepts/process-keys
+  - concepts/costs-and-quotas
+  - features/operations/backend-routing
+ui_anchors:
+  - /settings/models
+---
+
+# Backends and Tiers
+
+## TL;DR
+
+Three backends are supported: **Claude Code** (default),
+**Codex**, and **Gemini CLI**. Each backend exposes three classes of
+model used at install time:
+
+- **Main** (Sonnet 4.6 / GPT-5.4-mini / Gemini 3 Flash) — the default
+  for owner-facing work (DMs, daily / weekly / monthly review,
+  morning routine, dashboard chat, scheduled tasks).
+- **Delegated** (Haiku 4.5 on Claude; 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
+  `delegated_task` invoker.
+- **Heavy** (Opus 4.7 / GPT-5.5 / Gemini 3 Pro) — registered but
+  *not* auto-selected. Operators opt in per-process from
+  `/settings/models`.
+
+Every ProcessKey resolves to a backend + model binding via
+`BackendRouter`. Aitne does not store or read subscription-plan state
+— bindings come from `process_backend_config` rows seeded at install
+time.
+
+## Why This Concept Exists
+
+Different work has different cost / quality tradeoffs. Owner-facing
+surfaces (DMs, daily review) need real instruction-following.
+Background polling (mail / calendar / git events) just needs a
+classifier-shaped output. Splitting Sonnet vs Haiku at the seed layer
+keeps the cost of an autonomous loop bounded without compromising the
+quality of work the operator actually reads.
+
+Multiple backends exist so Aitne isn't single-vendor. The same
+operator can keep Claude as the primary brain, fall back to Codex when
+Claude's quota is exhausted, or use Gemini for cheap polling tasks.
+
+## Definitions
+
+- **Backend**: the agent runtime. One of `claude`, `codex`, `gemini`.
+- **Tier**: `heavy` or `light`. Heavy maps to the strongest model
+  (Opus / GPT-5.5 / Gemini 3 Pro). Light is the operator's day-to-day
+  tier and split at install time into Sonnet (main) vs Haiku
+  (delegated/simple).
+- **Main / Fallback**: each ProcessKey has a `main` backend and a
+  `fallback`. The router fails over on `BackendQuotaError` /
+  `BackendDecisiveFailure`.
+
+## Concrete Examples
+
+| ProcessKey | Default main | Seeded model |
+|---|---|---|
+| `routine.morning_routine` | claude | Sonnet 4.6 |
+| `routine.evening_review` | claude | Sonnet 4.6 |
+| `routine.weekly_review` | claude | Sonnet 4.6 |
+| `routine.monthly_review` | claude | Sonnet 4.6 |
+| `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) |
+| `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 |
+
+## Where You See It in the Dashboard
+
+- **Settings → Models** is the unified surface: pick the main backend,
+  override the per-process binding, toggle the optional advisor.
+- The **Activity** event detail shows which backend / model actually
+  ran each turn (after fallback resolution).
+- **Analytics** rolls cost up by backend.
+
+## Related
+
+- [Costs and Quotas](costs-and-quotas.md) — how to read the rollup.
+- [Backend Routing](../features/operations/backend-routing.md) — the
+  fallover machinery.

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

@@ -0,0 +1,103 @@
+---
+schema_version: 1
+slug: concepts/costs-and-quotas
+title: Costs and Quotas
+id: costs-and-quotas
+aliases:
+  - cost
+  - budget
+  - quota
+  - subscription limit
+category: concepts
+summary: |
+  How Aitne meters subscription windows and per-call costs,
+  and where the operator sees the rollup. Cost tracking is
+  observational — the dashboard reports, it does not bill.
+section: cost
+tags:
+  - cost
+  - quotas
+  - core
+status: stable
+ask_examples:
+  - How do I see how much my agent is spending?
+  - When do my Opus tokens reset?
+  - Why is the agent saying "subscription limit reached"?
+locale: en-US
+created: 2026-04-25
+updated: 2026-04-25
+keywords:
+  - cost
+  - budget
+  - quota
+  - max5
+  - max20
+  - opus window
+  - gemini quota
+related:
+  - concepts/backends-and-tiers
+  - features/operations/cost-tracking
+ui_anchors:
+  - /analytics
+config_keys:
+  - autonomousDailyCostCapUsd
+---
+
+# Costs and Quotas
+
+## TL;DR
+
+Each backend bills differently:
+
+- **Claude Code** — flat-rate inside `Claude Max5` / `Max20` with a
+  rolling 5-hour Opus window.
+- **Codex** — flat-rate inside `Codex Pro`.
+- **Gemini** — per-token billed against the Google API quota; free tier
+  has per-day caps.
+
+The dashboard rolls cost up by ProcessKey, by backend, and by agent day.
+
+## Why This Concept Exists
+
+A proactive agent can spend without you watching. Aitne's
+philosophy is that cost is the operator's problem to *see*, not the
+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.
+
+## Definitions
+
+- **Subscription window**: Claude Max plans have a rolling 5-hour
+  budget for Opus + a separate Sonnet bucket. The dashboard shows
+  remaining quota and the next reset time.
+- **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.
+- **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.
+
+## Concrete Examples
+
+- Morning routine on Opus / Max20 = "no extra charge", but eats the
+  rolling 5-hour window.
+- Morning routine on Sonnet / Max5 = covered by the Sonnet bucket
+  (fast resets), Opus window untouched.
+- A Gemini hourly check on Flash / API tier = ~$0.0005 per fire.
+
+## Where You See It in the Dashboard
+
+- **Analytics** rolls today's cost by backend, by ProcessKey, and by
+  hour. Window-remaining math is here too.
+- **Sidebar footer** shows the day's running total.
+- **Activity** event details include the per-execute cost.
+
+## Related
+
+- [Cost Tracking](../features/operations/cost-tracking.md) — operator
+  surface walkthrough.
+- [Backends and Tiers](backends-and-tiers.md)

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

@@ -0,0 +1,223 @@
+---
+schema_version: 1
+slug: concepts/delegated-mode
+title: Delegated Mode (Integration Modes)
+id: delegated-mode
+aliases:
+  - delegated
+  - direct mode
+  - same-backend
+  - cross-backend
+  - integration delegation
+category: concepts
+summary: |
+  Each integration (Gmail, Google Calendar, …) runs in one of three
+  modes: direct (the daemon holds OAuth credentials), delegated (the
+  agent's backend connector holds them), or disabled. Under delegation,
+  the agent reaches the integration through one of two paths depending
+  on whether its DM session backend matches the connector's owner —
+  same-backend (native MCP, no daemon involved) or cross-backend
+  (`/api/integrations/:key/exec` task mode: the agent describes intent
+  in natural language and the daemon's delegate picks the connector
+  tool).
+section: integrations
+tags:
+  - core
+  - integrations
+  - safety
+  - skills
+status: stable
+ask_examples:
+  - What's the difference between direct and delegated mode?
+  - Why does Gmail work without my OAuth setup?
+  - When does the daemon spawn another backend to handle a Gmail call?
+  - Why don't I see a SKILL.md for Gmail in my Codex session?
+locale: en-US
+created: 2026-04-26
+updated: 2026-04-26
+keywords:
+  - delegated mode
+  - direct mode
+  - same-backend
+  - cross-backend
+  - integrations.md
+  - delegatedBackend
+  - SKILL.delegated
+  - invoke endpoint
+related:
+  - concepts/safety-model
+  - concepts/skills
+  - concepts/safety-and-execution
+  - features/integrations/mail
+ui_anchors:
+  - /connections
+  - /settings/models
+config_keys:
+  - integrations
+---
+
+# Delegated Mode (Integration Modes)
+
+## TL;DR
+
+Each integration is in one of three modes:
+
+| Mode | Who holds credentials | What the agent calls |
+|---|---|---|
+| `direct` | Daemon (OAuth in macOS Keychain) | `curl /api/mail/*` / `curl /api/calendar/*` |
+| `delegated` | The agent's backend connector (claude.ai / ChatGPT / Google) | Native MCP tools or the `/api/integrations/:key/exec` task endpoint |
+| `disabled` | Nobody | Nothing — the integration is off |
+
+Under `delegated`, two sub-cases exist depending on whether the DM session's
+backend is the same as the integration's `delegatedBackend`:
+
+- **Same-backend** — DM agent calls the connector's MCP tool directly.
+  The daemon is not involved. No skill body is materialized.
+- **Cross-backend** — DM agent calls
+  `POST /api/integrations/:key/exec {task, outputSchema, …}` with a
+  natural-language `task`. The daemon spawns a one-shot subprocess of
+  `delegatedBackend`, lets it pick the right MCP tool against the
+  per-task allowed-tools envelope, validates the JSON, and returns it.
+  (Earlier versions of this concept used an RPC `{tool, args}` shape
+  at `/invoke`; that route is retired — see DELEGATED-TASK-MODE-DESIGN.md.)
+
+## Why This Concept Exists
+
+The setup tax for direct mode (OAuth client setup in a vendor console, then
+JSON download, then keychain seeding) is the single biggest blocker for
+non-technical operators. Every supported backend — Claude Code, Codex,
+Gemini CLI — already ships first-party connectors to Gmail, Calendar,
+Drive, and more. When the operator is signed into claude.ai or ChatGPT,
+the agent can reach those services through the backend's own MCP tools,
+zero daemon credentials required.
+
+Delegated mode lets the operator skip the vendor console entirely. The
+two sub-cases (same- vs cross-backend) exist because the agent's DM
+session may run on a different backend than the one whose connector is
+signed in — e.g. a Claude DM session whose Gmail comes from Codex. In
+that case the daemon spawns the other backend per call.
+
+## Definitions
+
+- **`direct`** — daemon holds the credentials (OAuth refresh token in
+  macOS Keychain, app-password for Yahoo / iCloud, …). Pollers run.
+  Full feature set. The operator did the vendor-console setup.
+- **`delegated`** — daemon holds nothing for this integration. Pollers
+  are stopped. The connector running inside the agent's backend (or a
+  spawned-on-demand backend) does the work.
+- **`disabled`** — nobody holds credentials. The integration is off.
+- **`delegatedBackend`** — when delegated, which backend's connector
+  serves the calls. `claude` / `codex` / `gemini`. Editable per
+  integration in **Connections → Gmail / Google Calendar**.
+- **Same-backend** — DM session backend matches `delegatedBackend`. The
+  daemon is not in the loop; the agent calls native MCP directly. No
+  skill body is materialized for the integration's slug — the connector
+  describes its own tools at session-init.
+- **Cross-backend** — DM session backend differs from `delegatedBackend`.
+  The agent reaches the integration through
+  `POST /api/integrations/:key/exec` (task mode — natural-language
+  `task` + JSON `outputSchema`) and the daemon spawns
+  `delegatedBackend` as a 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
+  reads it to know which path to take.
+
+## How to Choose
+
+| You want… | Pick |
+|---|---|
+| Full feature set (send mail, attachments, full search) and you're comfortable with one-time vendor-console setup | **direct** |
+| Zero setup tax, willing to live with whatever the connector exposes (Claude Gmail = draft-only; Codex Gmail = full) | **delegated** |
+| The integration off entirely | **disabled** |
+
+When you pick `delegated`, also pick `delegatedBackend`:
+
+- **Same as your DM main backend** → faster, simpler, no proxy spawn,
+  but per-tool cost is not measurable (rolls up into the parent
+  session). Best when one backend has everything you need.
+- **Different from your DM main backend** → adds a one-shot subprocess
+  per call; per-call cost is auditable. Best when one backend has the
+  connector you want (e.g. Codex's full Gmail) but a different backend
+  is your preferred DM driver (e.g. Claude).
+
+## Concrete Examples
+
+| Setup | What happens on a Gmail search |
+|---|---|
+| 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…","outputSchema":{...},"cacheable":true}'` → daemon spawns Codex subprocess → Codex picks the right MCP primitive (e.g. `_search_emails`) → daemon validates the JSON against the schema and returns it |
+
+## How the Skill File Resolves
+
+`selectSkillVariantFile(skillSlug, sessionBackend, integrations)` returns
+one of three values:
+
+- `"SKILL.md"` — direct mode, or skill not gated by any integration.
+- `null` — every touched integration is delegated and same-backend.
+  No skill is materialized (the connector self-describes).
+- `"SKILL.delegated.<sessionBackend>.md"` — at least one touched
+  integration is delegated cross-backend; one body per session backend
+  covers every `delegatedBackend` because the API is uniform.
+
+Mixed states (some same-backend, some cross-backend) fall back to
+`SKILL.md`.
+
+## Where You See It in the Dashboard
+
+- **Connections → Gmail / Google Calendar** — per-integration mode
+  picker, `delegatedBackend` dropdown, deny-list editor.
+- **Settings → Models** — main backend switch. Flipping main flips the
+  same-/cross-backend status of every delegated integration and
+  re-materializes the active DM workdir.
+- **Setup wizard** — first-run integration mode picker; delegated mode
+  is gated on a live probe that confirms the connector reports every
+  `requiredCapability` for the integration.
+
+## How `integrations.md` Reflects This
+
+`~/.personal-agent/integrations.md` is the operator-readable snapshot the
+agent consults at session-init. Example:
+
+```markdown
+## gmail
+mode: delegated
+delegatedBackend: codex
+deniedTools:
+  - send_email
+  - delete_emails
+
+## google_calendar
+mode: delegated
+delegatedBackend: claude
+deniedTools:
+  - delete_event
+```
+
+A daemon-side write chokepoint guarantees the file matches DB state. The
+fs-watcher reverts hand-edits that fail validation and DMs the operator.
+
+## Failure Modes
+
+- **Cross-backend, connector signed out on `delegatedBackend`** — the
+  invoke endpoint returns `502 auth_error`. Skill prose tells the agent
+  to surface this as "re-sign-in to the connector."
+- **Same-backend, connector not signed in on the DM backend** — the
+  agent has no Gmail tools at all. The setup wizard's pre-commit live
+  probe is the primary defense; if the operator signs out
+  post-setup, the agent will report "no Gmail tools available" until
+  re-signed.
+- **Mode flip mid-call** — the invoke endpoint returns
+  `409 precondition`; agent re-reads `integrations.md` and replans.
+
+## Related
+
+- [Safety Model](safety-model.md) — how the deny list (the primary
+  defense in delegated mode) works.
+- [Skills](skills.md) — how `selectSkillVariantFile` picks the body.
+- Integration Delegation Framework (design) — `docs/design/14-integration-delegation.md`,
+  the load-bearing spec.
+- Delegated Mode v2 (design) — `DELEGATED-MODE-V2-DESIGN.md`, the
+  canonical model for the current behavior.