@aitne-sh/aitne 0.1.3 → 0.1.4

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

@@ -44,6 +44,15 @@ events** when they detect changes. They write observation rows to
 SQLite. A single `routine.hourly_check` consumes the queue and decides
 what is worth surfacing.
 
+Since 2026-05, observations have a **second writer**: every main
+routine (morning, today_refresh, hourly_check, evening, weekly) is
+preceded by a lite-tier `routine.fetch_window` pre-pass that fetches
+mail / calendar / Notion windows and POSTs them to
+`/api/observations`. The main routine then reads them via the same
+`pending=true` queue that the polling path feeds. Observation rows
+look identical regardless of which writer produced them — the
+distinction is invisible to downstream consumers.
+
 ## Why This Concept Exists
 
 Per-change notifications turned every routine commit, every saved
@@ -57,10 +66,19 @@ up to something the operator should hear about.
 - **Observation**: one row in the `observations` table.
 - **Actor**: who caused the change. `actor='agent'` rows are filtered
   out by the consumer (anti-loop).
-- **Hourly check**: the consumer routine. Light tier by default.
+- **Hourly check**: the consumer routine. Medium tier by default
+  (Sonnet); fed by both the background polling path and the pre-pass
+  fetcher.
 - **`AgentWriteTracker`**: the daemon component that tags
   agent-originated writes so observers don't observe the agent's own
   output.
+- **Pre-pass writer (2026-05+)**: the lite-tier `routine.fetch_window`
+  session spawned by each main routine's dispatcher. Fetches a
+  per-routine window (`ROUTINE_WINDOWS` in
+  `packages/daemon/src/core/routine-windows.ts`) for each enabled
+  mail / calendar / Notion integration and POSTs observations. The
+  server computes `contentHash` from `(source, payload)`, so an
+  unchanged item written twice in the same cadence dedupes to a 409.
 
 ## Concrete Examples
 

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

@@ -68,6 +68,11 @@ those subsystems.
   `routine.monthly_review`, `routine.hourly_check`,
   `routine.roadmap_refresh`, `routine.today_refresh`,
   `routine.user_profile_sweep`
+- Routine sub-jobs (lite tier, dispatcher-spawned, not user-facing):
+  `routine.fetch_window` (pre-pass mail/calendar/Notion fetcher that
+  runs before each main routine and POSTs observations) and
+  `routine.hourly_check.triage` (Stage 2 escalate-vs-log-only gate
+  inside the hourly check).
 - Custom routines: `routine.custom.<slug>` (kebab-case slug)
 - Messaging: `message.dm`, `message.mention`
 - Dashboard: `dashboard.chat`, `dashboard.docs_qa`

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

@@ -73,22 +73,34 @@ DM is who fired the event.
 - **Catch-up**: if the daemon was offline at the trigger time, the
   scheduler re-fires the routine on next launch when it is still in
   the same agent day.
-- **Heavy / light tier**: only `routine.morning_routine` (and the
-  one-shot `routine.morning_routine_initial`) run heavy by default
-  (Opus on Claude, GPT-5.5 on Codex, Gemini 3 Pro on Gemini). Evening,
-  weekly, and monthly reviews plus the hourly check default to light —
-  see [Backends and Tiers](backends-and-tiers.md).
+- **Tier policy**: only the one-shot `routine.morning_routine_initial`
+  runs heavy by default (Opus on Claude, GPT-5.5 on Codex, Gemini 3
+  Pro on Gemini). Every other recurring routine — morning, evening,
+  weekly, monthly, hourly check — defaults to **medium** (Sonnet on
+  Claude). The lite (Haiku) tier is reserved for mechanical
+  sub-jobs: the hourly-check triage gate and the new pre-pass
+  fetcher. See [Backends and Tiers](backends-and-tiers.md).
+- **Pre-pass fetcher**: each main routine that needs fresh mail /
+  calendar / Notion data is preceded by a lite-tier
+  `routine.fetch_window` session that fetches the relevant window and
+  POSTs observations. The main routine consumes the resulting
+  `<fetch_report>` block plus pending observations instead of
+  fetching upstream APIs itself. This is the cost-savings split
+  introduced in 2026-05.
 
 ## Concrete Examples
 
 | ProcessKey | When | Tier |
 |---|---|---|
 | `routine.morning_routine_initial` | First setup day, one-shot | heavy |
-| `routine.morning_routine` | `dayBoundaryHour` daily | heavy |
-| `routine.evening_review` | 18:00 daily (fixed) | light |
-| `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | light |
-| `routine.weekly_review` | Friday 18:00 (fixed) | light |
-| `routine.monthly_review` | Last day of month, 18:00 (fixed) | light |
+| `routine.morning_routine` | `dayBoundaryHour` daily | medium |
+| `routine.today_refresh` | Every 4h inside the active window | medium |
+| `routine.evening_review` | 18:00 daily (fixed) | medium |
+| `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | medium |
+| `routine.weekly_review` | Friday 18:00 (fixed) | medium |
+| `routine.monthly_review` | Last day of month, 18:00 (fixed) | medium |
+| `routine.fetch_window` | Spawned before each routine above (except monthly) | lite |
+| `routine.hourly_check.triage` | Stage 2 gate of every hourly check | lite |
 | `routine.custom.<slug>` | Operator-defined recurrence | configurable |
 
 ## Where You See It in the Dashboard

package/agent-assets/docs/concepts/safety-model.md

@@ -121,13 +121,8 @@ of "report to me" events. Information about what the agent did is
 - **`matchToolPattern`** — pattern matcher used everywhere `deniedTools`
   is enforced. Exact match (`send_email`), prefix glob (`send_*`), or
   bare `*`.
-- **`/api/integrations/:key/exec`** — the cross-backend chokepoint
-  (task mode). Enforces `deniedTools` and the per-task allowed-tools
-  envelope server-side before spawning a subprocess. The legacy RPC
-  `/api/integrations/:key/invoke` route is retired (preserved as
-  commented code for future reactivation; the internal
-  `DelegatedBackendInvoker.invoke()` API remains wired for
-  daemon-internal pollers).
+- **`/api/integrations/:key/invoke`** — the cross-backend chokepoint.
+  Enforces `deniedTools` server-side before spawning a subprocess.
 - **`agent_actions`** — SQLite table of every agent action. Direct +
   cross-backend rows are full-fidelity. Same-backend native MCP rolls
   up to `mcp_tool_calls` + the parent session row.
@@ -137,7 +132,7 @@ of "report to me" events. Information about what the agent did is
 | Path | Enforcement |
 |---|---|
 | Direct mode (`/api/mail/*`, `/api/calendar/*`) | Route handler middleware checks `deniedTools` against the materialized skill body's `allowed-tools` list (frontmatter). |
-| Cross-backend (`/api/integrations/:key/exec`) | The task-mode subprocess is launched with the integration's allowed tools minus the user's `deniedTools`; daemon-side stream pre-emption aborts on out-of-allowlist `tool_use` events as `policy_violation`. |
+| Cross-backend (`/api/integrations/:key/invoke`) | Endpoint handler runs `matchToolPattern(deniedPattern, tool)` before spawning. Returns `403 denied_tool` on hit. |
 | Same-backend native MCP — Claude | `collectSessionDeniedTools` merges the deny patterns into the SDK's `disallowedTools` array at `query()` time. |
 | Same-backend native MCP — Gemini | Patterns are folded into `generateAdminPolicy`'s TOML deny rules (priority 1000). |
 | Same-backend native MCP — Codex | **Prose-only.** Codex bundles its connector apps into the binary; there is no per-tool deny config and the workspace-write sandbox does not match MCP tool calls. Skill prose lists the denied tools explicitly. Operators who require strict deny on Gmail / Calendar should pick a non-Codex DM backend or run those integrations through the proxy. |

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

@@ -24,19 +24,24 @@ ask_examples:
   - Why does the agent refuse to run a tool?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-04
 keywords:
   - SKILL.md
   - allowed-tools
   - skills-compiler
   - manifest
+  - self-optimization
+  - skill curation
+  - overlays
 related:
   - concepts/safety-and-execution
   - concepts/process-keys
   - reference/skills
+  - features/operations/skill-self-optimization
 ui_anchors:
   - /knowledge
   - /connections/mcp
+  - /settings/self-learning
 ---
 
 # Skills
@@ -84,12 +89,40 @@ visible to the model.
   `dashboard.docs_qa`.
 - `notify` — emit notifications through the configured messaging app.
 
+## Self-Optimization (Overlays)
+
+Skills aren't frozen. A background process — **skill curation** —
+watches how your knowledge layout drifts (file moves, new
+sub-folders, schema tweaks in `user/`, `projects/`, etc.) and
+proposes JSON **overlays** that update specific sections of the
+relevant skill: knowledge layout, routing tables, frontmatter
+schema, search recipes, convention notes, cross-references.
+
+Overlays live at `<dataDir>/overlays/<skill>/<section-id>.json` and
+are merged in by the SkillsCompiler at session-init. The original
+`SKILL.md` files in `agent-assets/skills/` are never rewritten;
+disabling the overlay (or deleting the JSON file) reverts to the
+seed payload immediately.
+
+The optimizer agent runs in an isolated workdir with a tightly
+scoped toolset (`Bash(curl http://localhost:8321/api/skill-curation/*)`,
+`Read`) and an auto-revert safety net — if the next run sees more
+drift signals than the previous overlay generated, the section is
+reverted and frozen for two cycles.
+
+See [Skill Self-Optimization](../features/operations/skill-self-optimization.md)
+for cadence, manual run, and the dashboard surface.
+
 ## Where You See It in the Dashboard
 
 - **Knowledge → Skills** lists every skill, its description, and the
   events it loads for.
 - **Connections → MCP** is where MCP servers (which surface as tools
   inside skills) attach.
+- **Settings → Self-learning (`/settings/self-learning`)** is where
+  the curation cadence, model, and per-skill exclusions live, plus
+  a "Run optimization now" button and a rolled-up summary of the
+  most recent runs.
 
 ## Related
 
@@ -98,3 +131,5 @@ visible to the model.
   `allowed-tools` is too permissive.
 - [Process Keys](process-keys.md) — the dispatch identity that picks
   which skill manifest to load.
+- [Skill Self-Optimization](../features/operations/skill-self-optimization.md) —
+  how overlays are generated and applied.

package/agent-assets/docs/features/integrations/calendar.md

@@ -11,7 +11,10 @@ category: features
 summary: |
   The calendar integration pulls your events into Aitne so the
   morning routine, schedule files, and travel-time skill can reason
-  about your day.
+  about your day. The Connections → Calendar page also picks the
+  backend that handles approaching-event notifications and observed
+  calendar changes (Calendar Event Model) — that picker only applies
+  when the integration runs in direct mode.
 section: integrations
 tags:
   - integration
@@ -22,22 +25,39 @@ ask_examples:
   - How do I connect my Google Calendar?
   - Why doesn't my calendar event show up in today's schedule?
   - Can the agent create calendar events?
+  - What is the Calendar Event Model setting on the Connections page?
+  - Why is the Calendar Event Model card missing when my calendar is delegated?
+  - Will Aitne notice calendar changes while my calendar is delegated?
+  - Which model handles approaching-event reminders?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-04-28
 keywords:
   - calendar
   - google calendar
   - events
+  - calendar event model
+  - calendar.change
+  - approaching event
+  - reminder
+  - change observation
+  - calendar poller
+  - delegated mode
+  - direct mode
 related:
   - features/routines/morning-routine
   - features/memory-files/schedule
+  - concepts/delegated-mode
+  - concepts/process-keys
+  - concepts/observations
 ui_anchors:
   - /connections/calendar
 api_endpoints:
   - /api/calendar
 config_keys:
   - calendarPollIntervalSeconds
+process_keys:
+  - calendar.change
 ---
 
 # Calendar
@@ -73,20 +93,71 @@ action). It does not auto-schedule on its own.
 ## Where in the Dashboard
 
 - **Connections → Calendar** holds OAuth, scope, and polling.
+- The same page hosts the **Calendar Event Model** card (see below)
+  when Google Calendar is in direct mode.
+
+## Calendar Event Model
+
+The Calendar Event Model picker chooses the backend and model that
+runs when the agent reacts to a calendar event. It binds the
+`calendar.change` ProcessKey, which fires from the calendar poller in
+three situations:
+
+- An event is about to start (the operator gets an approaching-event
+  reminder).
+- An event was added, moved, or deleted between polls (recorded as a
+  change observation; the hourly check picks it up).
+- An event was created far in advance (long-horizon events nudge the
+  roadmap-refresh routine so `roadmap.md` can build a preparation
+  timeline).
+
+Light tier is the default and almost always sufficient — these flows
+are classification and scheduling, not generation. The default backend
+is whichever you picked as your main backend during setup; you can
+override per-process here if you want a different mix.
+
+The picker is **only meaningful when Google Calendar runs in direct
+mode.** In delegated mode the daemon hands off all Google Calendar
+work to the connector inside your agent's backend, so:
+
+- No approaching-event reminders fire from the daemon.
+- No change observations are recorded between polls.
+- The hourly check has no calendar-side observations to react to.
+- Long-horizon roadmap-refresh nudges from calendar do not fire.
+
+The agent only learns about calendar state in delegated mode when it
+asks the connector itself inside a session (for example, while
+running the morning routine). It is a pull-only model — the daemon
+does not push.
+
+To avoid presenting a setting that does nothing, the dashboard hides
+the Calendar Event Model card whenever Google Calendar is delegated.
+If you want approaching-event reminders and change observations back,
+switch the integration mode to direct on the same page.
 
 ## Configuration
 
 | Setting | Default | Notes |
 |---|---|---|
-| `calendarPollIntervalSeconds` | 300 | How often to poll for changes. |
+| `calendarPollIntervalSeconds` | 300 | How often to poll for changes (direct mode only). |
+
+The Calendar Event Model is configured through its dashboard card
+rather than an env-style setting; the underlying state lives in the
+`process_backend_config` table for the `calendar.change` row.
 
 ## When Something Goes Wrong
 
 - A **stale calendar** in `/schedule` after a real-world add usually
   means the poll has not yet run. Check the next-fire timestamp.
 - An **OAuth-expired** state reports on the auth-health card.
+- **No reminders or change observations** while in delegated mode is
+  expected behavior, not a bug — switch to direct mode to restore the
+  daemon-side flows. See "Calendar Event Model" above.
 
 ## Related
 
 - [Morning Routine](../routines/morning-routine.md)
 - [daily/ files](../memory-files/schedule.md)
+- [Delegated Mode](../../concepts/delegated-mode.md)
+- [ProcessKeys](../../concepts/process-keys.md)
+- [Observations](../../concepts/observations.md)

package/agent-assets/docs/features/integrations/git.md

@@ -52,8 +52,8 @@ flagging.
 
 - **Polls** each watched repo every `gitPollIntervalSeconds`.
 - **Records observations** when new commits land between polls. The
-  commit range, changed files, and summary stats are included so the
-  hourly check can decide whether the activity matters.
+  commit author is included so agent-originated commits do not
+  re-surface to the agent (defended via `AgentWriteTracker`).
 - **Surfaces patterns**, not individual commits — three small commits
   in an hour will not page you.
 
@@ -83,8 +83,8 @@ by design.
 ## When Something Goes Wrong
 
 - A **missing observation** for a commit you just made: check that the
-  repo path is actually watched on `/connections/repositories` and that
-  the poll has fired since.
+  repo path is actually watched on `/connections/git` and that the
+  poll has fired since.
 - A repo that **never appears** in observations: the agent's own
   writes are filtered out (see `AgentWriteTracker`); make sure the
   commit was authored by you, not by an agent session.

package/agent-assets/docs/features/integrations/github.md

@@ -10,161 +10,129 @@ aliases:
 category: features
 summary: |
   GitHub is the remote-side counterpart to the Git integration. The
-  daemon polls the user's notifications feed and watched-repo CI failures
-  via the local `gh` CLI, recording observations and DM-ing the user
-  about high-priority signals (review requests, default-branch CI failures,
-  Dependabot alerts, assignments). The agent never auto-comments,
-  auto-merges, or pushes.
+  daemon polls notifications and CI failures via the local `gh` CLI;
+  high-priority signals (review requests, default-branch CI failures,
+  security alerts, assignments) become direct DMs.
 section: integrations
 tags:
   - integration
   - github
   - observation
-  - polling
 status: stable
 ask_examples:
   - How do I connect GitHub?
   - Will the agent message me on every CI failure?
   - Can the agent reply to GitHub issues?
-  - Why isn't the GitHub poller firing?
 locale: en-US
 created: 2026-04-25
 updated: 2026-04-28
-keywords:
-  - github
-  - notifications
-  - workflow_run
-  - review_requested
-  - gh cli
 related:
   - features/integrations/git
-  - features/routines/hourly-check
   - concepts/observations
 ui_anchors:
   - /connections/repositories
-config_keys:
-  - githubPollIntervalSeconds
-  - gitRepos
-  - githubRepos
 ---
 
 # GitHub
 
 ## In One Sentence
 
-The daemon polls GitHub Notifications + watched-repo CI failures via
-the local `gh` CLI, surfacing high-priority signals as DMs and feeding
-everything else into the hourly check.
+The daemon polls GitHub via the local `gh` CLI: review requests, CI
+failures on the default branch, security alerts, and assignments
+become DMs; everything else is recorded for the hourly check.
 
-## How It Works
+## What It Does
 
-GitHub access is **delegated to the local `gh` CLI** rather than carried
-by a daemon-side personal access token. Authentication happens once via
-`gh auth login`; the daemon shells out to `gh api …` per poll. This
-keeps secrets in the OS keychain that `gh` already manages, and lines
-up with the future delegated-mode story (Claude / Codex / Gemini will
-share the same auth path).
+- **Polls Notifications** every `githubPollIntervalSeconds` (default
+  600s) using ETag caching — 304s cost no rate-limit quota.
+- **Polls workflow_runs** per watched GitHub repository on the same
+  cadence, filtered by `status=failure`. Watched repos can come from a
+  local clone's GitHub `origin` or from an explicit `owner/repo` entry.
+- **DMs the user** on the four high-priority triggers below; quieter
+  signals are coalesced into the hourly check summary.
 
-Two cadences run on a single timer:
+The agent never auto-comments, auto-merges, or pushes.
 
-1. **Notifications** — `gh api notifications` with ETag caching.
-   304 Not Modified responses cost zero rate quota.
-2. **Workflow runs** — per watched GitHub repo (any explicit
-   `owner/repo` entry in the GitHub card, plus any entry in the
-   Git Repositories card whose `origin` resolves to GitHub),
-   `gh api repos/<owner>/<name>/actions/runs?status=failure`.
+## High-priority events
 
-When `githubRepos` is non-empty, notification processing is scoped to
-those `owner/repo` entries. When it is empty, the poller preserves the
-older behavior and processes the authenticated user's unread
-notifications globally.
+The agent will DM the user (priority `high`, can break quiet hours
+depending on your notify-skill settings) on:
 
-The classifier maps each event to either a `recordObservation` call
-(for the hourly check to coalesce) or both an observation **and** an
-EventBus emit (for high-priority signals that warrant a direct DM).
+- A teammate or bot **requested your review** on a PR.
+- You were **assigned** to an issue or PR.
+- A **Dependabot or code-scanning security alert** fired on a watched
+  repository.
+- A **default-branch CI failure** (feature-branch failures stay
+  observation-only — they're the normal developer feedback loop).
 
-## High-priority events
-
-| Trigger | Event type | Task-flow |
-|---|---|---|
-| `notifications.reason === "review_requested"` | `github.pull_request.review_requested` | `github.pull_request.review_requested.md` |
-| `notifications.reason === "assign"` | `github.assigned` | `github.assigned.md` |
-| `notifications.reason === "security_alert"` | `github.security_alert` | `github.security_alert.md` |
-| Workflow run failure on default branch | `github.workflow_run.failed` | `github.workflow_run.failed.md` |
+Each DM follows the notify skill's awareness-gate: if the agent already
+sees you triaging it in `today.md`, it stays silent and just logs.
 
-Feature-branch CI failures stay observation-only (LOW priority) — they
-are the developer's normal feedback loop, not interruption-worthy.
+## Setup
 
-## Cold-start safety
+1. Install `gh`: `brew install gh` on macOS; see
+   [cli.github.com](https://cli.github.com/) for other platforms.
+2. Authenticate: `gh auth login` (browser flow).
+3. Add `owner/repo` entries to **Connections → GitHub**, or add local
+   repository paths to **Connections → Git Repositories**. For local
+   paths, the poller derives `owner/name` from each repo's `origin`
+   remote — non-GitHub remotes are silently skipped.
+4. Restart the daemon (the poll interval is captured at start time).
 
-On first start with a fresh database, the workflow-runs path records
-the latest failures without emitting direct events. This prevents the
-user from waking up to 30 stale CI-failure DMs after enabling the
-integration while still warming the idempotency table. Notifications are
-inherently cold-start-safe because GitHub returns only currently-unread
-notifications.
+The daemon does NOT need a personal access token in its keychain — it
+re-uses whatever `gh` already has.
 
-## Idempotency
+## Cold-start behavior
 
-Every emission goes through a pre-check: `SELECT 1 FROM observations
-WHERE source = ? AND ref = ?` covers both consumed and pending rows.
-If a `review_requested` notification stays unread for an hour and you
-poll every 10 minutes, the user is DM'd **once**, not six times.
+The first time the daemon polls a watched repo, it records the latest
+failed workflow runs **without emitting any events**. This prevents a
+flood of DMs about historical CI failures the user has already triaged.
+New failures landing after that warm-up are surfaced normally.
 
 ## Where in the Dashboard
 
-- **Connections → GitHub** shows the integration status, the
-  `gh auth login` reminder, explicit `owner/repo` watched repos, and
-  event model routing cards.
-- **Git Repositories** on the same page lists local clone paths whose
-  GitHub remotes are also watched for workflow failures.
+- **Connections → GitHub** shows status and the `gh auth login`
+  hint.
+- **Connections → GitHub** controls explicit `owner/repo` watched repos.
+  When this list is non-empty, notification processing is scoped to it.
+- **Connections → Git Repositories** controls local clone paths whose
+  GitHub remotes are watched for workflow_run failures.
 
 ## Configuration
 
 | Setting | Default | Notes |
 |---|---|---|
-| `githubPollIntervalSeconds` | 600 | Both notifications and workflow_runs poll on this cadence. Restart-required (the timer is captured at construction time). |
-| `gitRepos` | `[]` | Local repo paths. The poller derives `owner/name` via `git remote get-url origin` for each entry whose remote is on GitHub. |
-| `githubRepos` | `[]` | Direct remote repos in `owner/repo` form. Enables workflow polling without a local clone and scopes GitHub notification processing when non-empty. |
+| `githubPollIntervalSeconds` | 600 (10 min) | Both poll cadences. Lower for faster review-request alerts at the cost of slightly more rate-limit budget. **Restart-required.** |
+| `gitRepos` | `[]` | Local repo paths to watch. |
+| `githubRepos` | `[]` | Direct remote repos in `owner/repo` form. Also scopes notification processing when non-empty. |
 
 ## When Something Goes Wrong
 
-- **`gh` CLI not found.** The daemon log shows `\`gh\` CLI is not on
-  PATH — install via \`brew install gh\` (or platform equivalent),
-  then \`gh auth login\``. Polls stay quiet (exponential backoff up
-  to 16 ticks ≈ 2.6 hours at default cadence) until `gh` is
-  reachable.
-- **Authentication expired.** `gh auth status` non-zero produces
-  a `GitHub poll failed (auth)` warning per backoff cycle. Log in
-  again with `gh auth login`.
-- **No DMs for a known PR review request.** Confirm the notification
-  is actually surfaced via `gh api notifications` from your shell —
-  if it's missing there too, GitHub's own notification routing has
-  filtered it (watch / mention settings on the source repo).
-- **Wrong default branch detection.** The poller queries
-  `gh api repos/<o>/<r> --jq .default_branch` once at startup. If
-  this lookup fails (rate limit, transient network), the cached
-  default is `main`. Restart the daemon after the issue clears to
-  re-resolve.
-
-## Backend routing
-
-High-priority GitHub events are first-class process keys:
-
-- `github.pull_request.review_requested`
-- `github.assigned`
-- `github.security_alert`
-- `github.workflow_run.failed`
-
-Configure them under **Connections → Git & Code** or **Settings →
-Models → Process Routing**. Each row can route to Claude Code, Codex,
-or Gemini CLI, with the same fallback, auth-health, turn-limit, and
-cost-audit behavior as other autonomous processes.
+- **No DMs after enabling.** Run `gh auth status` from your shell. If
+  it reports anything other than logged-in, the daemon log will show
+  a backoff message — re-run `gh auth login` and the next poll tick
+  picks up.
+- **`gh` not installed.** Daemon logs warn with the install command;
+  the observer keeps retrying with exponential backoff (capped at
+  ~16 ticks).
+- **Default branch detected as `main` but mine is `master`.** The
+  one-time `gh api repos/<o>/<r> --jq .default_branch` lookup at
+  startup failed (rate limit or transient). Restart after the
+  condition clears.
+- **Repeated DMs for the same notification.** Should not happen — the
+  poller pre-checks `observations(source, ref)` before every emit. If
+  it does, file a bug with the notification id.
+
+## Delegated mode (coming soon)
+
+A future release will let Claude Code, Codex, or Gemini CLI handle
+GitHub directly via their native MCP / `gh` integrations, optionally
+replacing the daemon-side poller. Most users won't need this — the
+built-in poller already covers the common surface — but it'll be
+useful if you'd rather skip the daemon-side polling entirely.
 
 ## Related
 
 - [Git](git.md) — local repo file watcher (separate observer).
-- [Hourly Check](../routines/hourly-check.md) — consumer of
-  observation-only signals.
-- [Observations](../../concepts/observations.md) — the storage
-  contract this poller writes against.
+- [Hourly Check](../routines/hourly-check.md) — the consumer of
+  non-DM-priority observations.