@aitne-sh/aitne 0.1.11 → 0.1.13

package/README.md

@@ -18,6 +18,10 @@ npm install -g @aitne-sh/aitne@latest
 aitne start
 ```
 
+<video src="https://github.com/user-attachments/assets/d5297828-011d-4d57-80a0-60a5e46063bf" controls playsinline></video>
+
+<sub>▶︎ 40-second tour. If the player doesn't load, <a href="https://github.com/user-attachments/assets/d5297828-011d-4d57-80a0-60a5e46063bf">watch it here</a>.</sub>
+
 ![Aitne setup and dashboard walkthrough](./docs/assets/aitne-demo.gif)
 
 </div>

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

@@ -11,7 +11,7 @@ hand back a faithful artifact; the main DM agent delivers it.
 
 - **You produce raw material, not a message.** You have no messaging
   tool. Your only owner-facing output is `finish(result, draft, notify,
-  significance?)`. The verbatim `result` is the fidelity anchor; the
+  verification, significance?)`. The verbatim `result` is the fidelity anchor; the
   `draft` is a plain summary the DM agent weaves into the conversation in
   its own voice. Never try to phrase a "✅ done!" message yourself.
 
@@ -41,6 +41,13 @@ hand back a faithful artifact; the main DM agent delivers it.
   reasonable, explicitly-stated assumption. If you must, `ask_user` ONCE
   with a sharp question and then stop the turn.
 
+- **Verify before you finish.** `finish` requires a
+  requirement-by-requirement `verification` checklist derived from the
+  brief's expected output, each item judged against your actual result
+  with concrete evidence. Never claim completion your evidence doesn't
+  support — an unmet requirement is disclosed automatically; a false
+  "met" is a lie the owner will act on.
+
 - **Finish cleanly, exactly once.** `finish` ends your session. Make the
   `result` complete (every number, URL, id) and the `draft` short and
   lead-with-the-answer.

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

@@ -79,6 +79,17 @@ return the same result shape:
   `routine.fetch_window`. If you hit the cap, record what's left as
   `{"type":"budget-exhausted","remaining":[…]}` in `errors`.
 
+## Turn efficiency
+
+This run is turn-capped; a run that overruns the cap is killed mid-fetch.
+Minimise round-trips — every model turn is one:
+- Load every deferred connector schema in ONE `ToolSearch` call (a
+  comma-separated `select:` list) — never one `ToolSearch` per tool.
+- Emit independent `<fetch>` rows' read calls in the SAME turn; they don't
+  depend on each other.
+- Never call per-item detail tools (`get_thread`, `get_event`, …) — the
+  list response already carries the compact subset you submit.
+
 ## Output format
 
 Print exactly one JSON line on stdout, then terminate:

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

@@ -20,9 +20,13 @@ backend:
   model: null
 
 # ── Limits (per execution) ───────────────────────────────────────────────────
+# Mirrors the runtime envelope (plan-presets / process_backend_config seed:
+# routine.evening_review is 50 / $2.00). These values prefill the dashboard
+# Definition form; a stale lower number saved there would clamp the real runs
+# via override_snapshot, so keep them in step with the seed authority.
 limits:
-  max_turns: 25
-  max_budget_usd: 0.50
+  max_turns: 50
+  max_budget_usd: 2.00
   timeout_minutes: 12
 
 # ── Expected outputs ─────────────────────────────────────────────────────────

package/agent-assets/agents/lesson-maintenance/agent.md

@@ -0,0 +1,56 @@
+---
+# ── Identity ─────────────────────────────────────────────────────────────────
+slug: lesson-maintenance
+name: Lesson Maintenance
+description: "Mechanical (no-LLM) lesson-store upkeep — confidence (cf) re-stamping and the graduated demote/archive/re-promote lifecycle — before the evening review."
+kind: builtin
+version: 1
+enabled: true
+tags: [routine, daily, lessons, feedback, no-llm]
+
+# ── Schedule (17:40 — before the 17:45 roadmap pass and 18:00 Evening Review) ─
+schedule:
+  kind: cron
+  expression: "40 17 * * *"
+
+# ── Backend / routing ────────────────────────────────────────────────────────
+# `process_key: null` — this is a no-LLM in-process pass with no backend-routing
+# key (§5.5.1). Reserved for built-ins; the schema rejects a null key for user
+# Agents.
+backend:
+  process_key: null
+  tier: null
+  model: null
+
+# ── Limits (no LLM turn — zero budget; `max_turns` must be ≥ 1 per schema) ──
+limits:
+  max_turns: 1
+  max_budget_usd: 0
+  timeout_minutes: 5
+
+# ── Expected outputs ─────────────────────────────────────────────────────────
+outputs:
+  - policies/agent-lessons.md
+
+success_criteria: []
+
+# ── Stop warning (byte-identical to BUILTIN_AGENT_REGISTRY, §12.1) ──────────
+stop_warning:
+  level: normal
+  services_lost:
+    - "Mechanical lesson-store maintenance (confidence re-stamping, graduated demote/archive/re-promote lifecycle)"
+  dependent_agents:
+    - evening-review
+  reactivation_hint: "Re-enable from /agents/lesson-maintenance. Runs daily at 17:40, before Evening Review."
+---
+
+# Lesson Maintenance
+
+No-LLM in-process pass — there is no task-flow. Implemented by the daemon
+callback `onLessonMaintenance` registered in `scheduler.ts`
+(SELF_IMPROVEMENT_PHASE2 §2.1/§2.3): re-stamps each lesson's numeric
+confidence (`cf=`) and enacts the graduated demote → archive → re-promote
+lifecycle over `policies/agent-lessons.md` and every
+`policies/agents/<slug>/lessons.md`, so expiration fires even on nights with
+zero feedback signals and hand-edited files re-normalize. It runs at 17:40 so
+the 18:00 Evening Review consolidation reads freshly-normalized stores.

package/agent-assets/agents/morning-routine/agent.md

@@ -2,7 +2,7 @@
 # ── Identity ─────────────────────────────────────────────────────────────────
 slug: morning-routine
 name: Morning Routine
-description: "Regenerates state/today.md, creates the daily journal entry, and delivers the morning DM digest at the day boundary."
+description: "Regenerates state/today.md and creates the daily journal entry at the day boundary."
 kind: builtin
 version: 1
 enabled: true
@@ -28,9 +28,14 @@ backend:
   model: null
 
 # ── Limits (per execution) ───────────────────────────────────────────────────
+# Mirrors the runtime envelope (plan-presets / process_backend_config seed:
+# parent routine.morning_routine and Stage A routine.morning_routine_today are
+# both 50 / $2.00). These values prefill the dashboard Definition form; a
+# stale lower number saved there would clamp the real runs via
+# override_snapshot, so keep them in step with the seed authority.
 limits:
-  max_turns: 30
-  max_budget_usd: 0.50
+  max_turns: 50
+  max_budget_usd: 2.00
   timeout_minutes: 15
 
 # ── Expected outputs (informational; drive the dashboard + criteria intent) ──
@@ -43,8 +48,8 @@ outputs:
 # today.md is regenerated wholesale every morning, so a section-count floor is
 # a real check (it fails on a degenerate/empty regen). The daily journal is
 # written for the *previous* agent-day (`daily/<yesterday>.md`), which the
-# `{date}`-only evaluator cannot target, and the DM digest is conditional —
-# both are listed under `outputs` rather than asserted as criteria.
+# `{date}`-only evaluator cannot target, so it is listed under `outputs`
+# rather than asserted as a criterion.
 success_criteria:
   - id: today_md_populated
     kind: file_section_count
@@ -64,7 +69,6 @@ stop_warning:
   services_lost:
     - "Daily state/today.md regeneration"
     - "Daily journal entry creation"
-    - "Morning DM digest delivery"
   dependent_agents:
     - evening-review
     - weekly-review

package/agent-assets/agents/source-librarian/agent.md

@@ -0,0 +1,51 @@
+---
+# ── Identity ─────────────────────────────────────────────────────────────────
+slug: source-librarian
+name: Source Librarian
+description: "Weekly triage of unfiled source documents into knowledge/sources/ cards, taxonomy upkeep, and library-vault consistency checks."
+kind: builtin
+version: 1
+enabled: true
+tags: [routine, weekly, sources, maintenance]
+
+# ── Schedule (Saturday 09:00; scheduler adds a no-LLM nothing-to-do prefilter) ─
+schedule:
+  kind: cron
+  expression: "0 9 * * 6"
+
+# ── Backend / routing (tier/model deferred to process_backend_config) ───────
+backend:
+  process_key: routine.source_maintenance
+  tier: null
+  model: null
+
+# ── Limits (per execution) ───────────────────────────────────────────────────
+limits:
+  max_turns: 50
+  max_budget_usd: 1.00
+  timeout_minutes: 20
+
+# ── Expected outputs ─────────────────────────────────────────────────────────
+# Cards are keyed on agent-chosen collection/slug paths, which the
+# `{date}`-only success-criteria evaluator cannot target in v1, so they are
+# documented here rather than asserted as criteria.
+outputs:
+  - "knowledge/sources/<collection>/<slug>.md"
+  - knowledge/sources/_index.md
+
+success_criteria: []
+
+# ── Stop warning (byte-identical to BUILTIN_AGENT_REGISTRY, §12.1) ──────────
+stop_warning:
+  level: normal
+  services_lost:
+    - "Weekly filing of unfiled source documents into knowledge/sources/"
+    - "Source library and vault consistency checks"
+  dependent_agents: []
+  reactivation_hint: "Re-enable from /agents/source-librarian. Resumes on the next Saturday 09:00 firing."
+---
+
+# Source Librarian
+
+Built-in routine — the execution prompt lives in the task-flow, not here.
+See `agent-assets/task-flows/routine.source_maintenance.md`.

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

@@ -14,7 +14,6 @@ summary: |
   drives every routine schedule and date-stamped memory file.
 section: agent-day
 tags:
-  - core
   - memory
   - routines
   - scheduler
@@ -26,7 +25,7 @@ ask_examples:
   - What is dayBoundaryHour?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - day boundary
   - 04:00
@@ -49,23 +48,24 @@ config_keys:
 
 ## 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 `state/today.md`
-that opened the previous morning.
+Aitne starts each "day" at **04:00 local time**, not at 00:00. In other
+words, the agent-day boundary (the moment "today" rolls over) sits at 4am
+by default. Anything you do between midnight and 4am counts toward the day
+that is just ending, so a late commit at 02:30 lands in the same
+`state/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 `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.
+Most people who run Aitne for themselves work late into the night. Those
+sessions still feel like "today" to you, even after the clock has ticked
+past midnight. A boundary at midnight would cut one continuous work session
+in half, spreading it across two `state/today.md` files. It would also leave
+the morning routine with nothing to open against: no agent activity has been
+logged yet for the fresh calendar day.
 
-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.
+04:00 is a safe default. It is late enough to capture even very late nights,
+yet early enough that an early riser (someone up at 5–6am) still starts the
+day on the far side of a clean boundary.
 
 ## Definitions
 

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

@@ -16,7 +16,6 @@ summary: |
   recovery flows when the right signal is available.
 section: auth-health
 tags:
-  - core
   - safety
   - backends
   - operations
@@ -29,7 +28,7 @@ ask_examples:
   - What is the SubscriptionAuthWarning banner?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - auth
   - authentication
@@ -44,6 +43,7 @@ related:
   - concepts/backends-and-tiers
   - concepts/costs-and-quotas
   - troubleshooting/auth-failed
+  - troubleshooting/dashboard-shows-degraded
 ui_anchors:
   - /settings/models
   - /
@@ -68,14 +68,15 @@ 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.
+A routine that quietly fails because a token expired is the most
+common operator headache. The auth-health monitor catches that early:
+it tells you "your credentials expired" before the next morning
+routine trips over the same problem.
 
 ## Definitions
 
-- **Probe**: a no-op call against each backend's auth surface. With
+- **Probe**: a lightweight test call that checks each backend's login
+  without doing any real work. With
   a registered API key the probe hits the provider's lightweight
   `models` endpoint (Anthropic, OpenAI, Google) and verifies the key
   is live. Without an API key, the probe checks whatever local CLI
@@ -138,3 +139,5 @@ register a paid key and leave the gray area.
   quota signals interact.
 - [Troubleshooting: Auth Failed](../troubleshooting/auth-failed.md) —
   step-by-step recovery when a card goes red.
+- [Dashboard Shows Degraded](../troubleshooting/dashboard-shows-degraded.md) —
+  what to do when the dashboard flags a backend as degraded.

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

@@ -13,13 +13,11 @@ aliases:
 category: concepts
 summary: |
   Aitne runs on four backends — Claude Code, Codex, Gemini CLI, OpenCode.
-  Each backend exposes light, medium, and high model tiers; the dispatcher
+  Each backend exposes lite, medium, and high model tiers; the dispatcher
   picks the binding for every ProcessKey based on operator configuration.
 section: backends
 tags:
-  - core
   - backends
-  - models
   - cost
   - routing
 status: stable
@@ -31,7 +29,7 @@ ask_examples:
   - How does Aitne fail over when a backend hits its quota?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - claude
   - codex
@@ -53,6 +51,9 @@ related:
   - concepts/process-keys
   - concepts/costs-and-quotas
   - features/operations/backend-routing
+  - concepts/auth-health
+  - troubleshooting/fallback-keeps-firing
+  - troubleshooting/quota-exhausted
 ui_anchors:
   - /settings/models
   - /analytics
@@ -85,7 +86,7 @@ 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 |
+| **medium** (main) | Sonnet 5 | GPT-5.4 | Gemini 3.1 Pro (preview) | Sonnet 5 |
 | **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 |
 
@@ -114,9 +115,10 @@ What each tier is for:
   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
-state** — there is no "Claude Pro / Max / Team" or "ChatGPT Plus /
+Every [ProcessKey](process-keys.md) — Aitne's internal name for one
+kind of work, such as a morning routine or a Gmail classification —
+resolves to a backend + model binding via `BackendRouter`. Aitne
+**does not store or read subscription-plan state** — there is no "Claude Pro / Max / Team" or "ChatGPT Plus /
 Pro" picker in the wizard or settings, and the DB has no plan
 column. Bindings come from `process_backend_config` rows seeded at
 install time and edited from `/settings/models`.
@@ -132,11 +134,11 @@ Each backend authenticates via a provider API key registered on
 | `opencode` | `opencode-server` (server URL + HTTP Basic-Auth username / optional password). Model-provider keys (Anthropic / OpenAI / OpenRouter / …) live on the OpenCode server itself — configure them there with `opencode auth login`; Aitne does not store or forward them | "Managed" mode runs a local `opencode` HTTP server on loopback; a "Remote" mode pointing at a baseUrl you operate is designed but not wired up yet |
 
 API keys are the recommended and provider-supported auth method for
-headless agent use; if you skip the key the daemon falls back to the
+headless agent use. If you skip the key, the daemon falls back to the
 CLI's local subscription login, which most providers do not
 officially support — Anthropic in particular currently prohibits the
 Claude Agent SDK on a Claude Pro / Max subscription. The dashboard
-surfaces a warning whenever a backend is on subscription auth.
+shows a warning whenever a backend is on subscription auth.
 
 Cloud / aggregator providers (Bedrock / Vertex / Foundry / Azure
 OpenAI / Gemini-Vertex / OpenRouter via OpenCode) let teams reuse
@@ -179,9 +181,9 @@ through the daemon's polling path or another backend's MCP). See
 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.
+classifier-shaped output. Splitting Sonnet vs Haiku in the
+install-time defaults keeps the cost of an autonomous loop bounded
+without hurting the quality of the 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
@@ -194,10 +196,13 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 - **Tier**: `lite`, `medium`, or `high`. `high` maps to the strongest
   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
+  `medium` (Sonnet-class — Sonnet 5 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.
+  mechanical / delegated surfaces. Sonnet 5 became the seeded medium
+  default on 2026-06-30; the prior **Sonnet 4.6** is retained as a
+  `(legacy)` model — hidden from the pickers but still resolvable for
+  any row already pinned to it.
 - **Main / Fallback**: each ProcessKey has a `main` backend and a
   `fallback`. The router fails over on `BackendQuotaError` /
   `BackendDecisiveFailure`.
@@ -206,13 +211,13 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 
 | 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.activity_scan` | 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 (locked to medium) |
+| `routine.morning_routine` | claude | Sonnet 5 |
+| `routine.evening_review` | claude | Sonnet 5 |
+| `routine.weekly_review` | claude | Sonnet 5 |
+| `routine.activity_scan` | claude | Sonnet 5 |
+| `message.dm` | claude | Sonnet 5 |
+| `dashboard.chat` | claude | Sonnet 5 |
+| `dashboard.docs_qa` | inherits from `message.dm` | Sonnet 5 (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 |
@@ -232,4 +237,10 @@ Claude's quota is exhausted, or use Gemini for cheap polling tasks.
 
 - [Costs and Quotas](costs-and-quotas.md) — how to read the rollup.
 - [Backend Routing](../features/operations/backend-routing.md) — the
-  fallover machinery.
+  failover machinery.
+- [Auth Health](auth-health.md) — check whether each backend's
+  credentials are still valid.
+- [Fallback Keeps Firing](../troubleshooting/fallback-keeps-firing.md) —
+  when the router keeps switching to the fallback backend.
+- [Quota Exhausted](../troubleshooting/quota-exhausted.md) — what to do
+  when a backend runs out of quota.

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

@@ -17,7 +17,6 @@ summary: |
   dashboard reports, it does not bill.
 section: cost
 tags:
-  - core
   - cost
   - quotas
   - backends
@@ -31,7 +30,7 @@ ask_examples:
   - How does Gemini's per-day quota work?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - cost
   - budget
@@ -88,7 +87,10 @@ is not provider-supported for automated agent use — see
 shape becomes whatever the underlying subscription enforces (e.g.
 Claude's rolling 5-hour Opus window when running on a Max plan login).
 
-The dashboard rolls cost up by ProcessKey, by backend, and by agent day.
+The dashboard rolls cost up three ways: by ProcessKey (the routine or
+event type that triggered the run), by backend, and by agent day (the
+window Aitne treats as "today", which rolls over at 04:00 local by
+default).
 
 ## Why This Concept Exists
 
@@ -194,14 +196,12 @@ register an API key on `/settings/models`.
 
 ## Where You See It
 
-In the dashboard:
+In the dashboard, the **Analytics** page (`/analytics`) is the full
+cost rollup — by backend, by ProcessKey, by model, over daily / weekly
+/ monthly windows, with the day's running total in the sidebar. See
+[Cost Tracking](../features/operations/cost-tracking.md) for the guided
+tour. One surface is specific to this page's topic:
 
-- **Analytics** (`/analytics`) rolls cost by backend, by ProcessKey
-  (event type), by model, and over daily / weekly / monthly periods,
-  plus a today total.
-- **Sidebar** shows the day's running total next to the Analytics
-  entry.
-- **Activity** event details include the per-execute cost.
 - **Settings → Models** (`/settings/models`) exposes the per-backend
   API-key panel and a warning banner whenever a backend is running on
   subscription auth.

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

@@ -24,7 +24,6 @@ summary: |
   (`/api/integrations/:key/exec` task-mode proxy).
 section: integrations
 tags:
-  - core
   - integrations
   - safety
   - skills
@@ -36,7 +35,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-06-07
+updated: 2026-07-01
 keywords:
   - delegated mode
   - direct mode
@@ -101,9 +100,10 @@ backend is the same as the integration's `delegatedBackend`:
 
 `native` has no sub-cases. The integration's `nativeBackend` must equal
 the main DM backend — `cascadeNativeBindingsOnMainSwitch` cascades
-unmatched `native` rows to `disabled`. From the agent's call-site view, `native`
-is indistinguishable from `delegated` same-backend (both are in-session
-MCP); the difference is who polls (no one, for `native`).
+unmatched `native` rows to `disabled`. From where the agent actually makes
+the call, `native` looks identical to `delegated` same-backend (both use
+in-session MCP tools); the only difference is who polls in the background —
+for `native`, no one does.
 
 > The four modes are `direct | delegated | native | disabled`
 > (`INTEGRATION_MODES` in `packages/shared/src/integrations.ts`).
@@ -113,19 +113,19 @@ MCP); the difference is who polls (no one, for `native`).
 
 ## 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. Claude Code, Codex, and Gemini CLI all ship
-first-party connectors to Gmail, Calendar, Drive, and more (OpenCode
-ships none). 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.
+Direct mode has a real setup cost: you create an OAuth client in a vendor
+console, download a JSON key, then load it into the macOS Keychain. For
+non-technical operators, that is the single biggest blocker. Claude Code,
+Codex, and Gemini CLI all ship first-party connectors to Gmail, Calendar,
+Drive, and more (OpenCode ships none). When you're signed into claude.ai
+or ChatGPT, the agent can reach those services through the backend's own
+MCP tools, with no daemon credentials at all.
+
+Delegated mode lets you skip the vendor console entirely. The two
+sub-cases (same- vs cross-backend) exist because your DM session may run
+on a different backend than the one whose connector is signed in — for
+example, a Claude DM session whose Gmail comes from Codex. In that case
+the daemon spawns the other backend once per call.
 
 ## Definitions