@aitne-sh/aitne 0.1.7 → 0.1.8

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

@@ -6,18 +6,22 @@ id: delegated-mode
 aliases:
   - delegated
   - direct mode
+  - native 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/invoke` proxy).
+  Each integration (Gmail, Google Calendar, …) runs in one of four
+  modes: direct (the daemon holds OAuth credentials and polls),
+  delegated (the agent's backend connector holds them; the daemon syncs
+  on opt-in cadences), native (the main backend's MCP connector reaches
+  the integration on-demand; no daemon polling and no daemon-side
+  proxy), or disabled. Under `delegated`, 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 proxy).
 section: integrations
 tags:
   - core
@@ -32,16 +36,18 @@ 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-04-26
+updated: 2026-05-17
 keywords:
   - delegated mode
   - direct mode
+  - native mode
   - same-backend
   - cross-backend
   - integrations.md
   - delegatedBackend
+  - nativeBackend
   - SKILL.delegated
-  - invoke endpoint
+  - exec endpoint
 related:
   - concepts/safety-model
   - concepts/skills
@@ -58,12 +64,13 @@ config_keys:
 
 ## TL;DR
 
-Each integration is in one of three modes:
+Each integration is in one of four 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/invoke` proxy |
+| `delegated` | The agent's backend connector (claude.ai / ChatGPT / Google) | Native MCP tools (same-backend) or the `/api/integrations/:key/exec` task-mode proxy (cross-backend) |
+| `native` | The main backend's connector (no daemon credentials, no daemon poller) | Native MCP tools on the main backend; observations are POSTed to `/api/observations/batch` for the routine pre-pass |
 | `disabled` | Nobody | Nothing — the integration is off |
 
 Under `delegated`, two sub-cases exist depending on whether the DM session's
@@ -72,9 +79,24 @@ 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/invoke {tool, args}`. The daemon spawns
-  a one-shot subprocess of `delegatedBackend`, runs the tool there,
-  and returns the raw result.
+  `POST /api/integrations/:key/exec` in **task mode** with body
+  `{task: "<natural-language description>", outputSchema, maxToolCalls,
+  cacheable}`. The daemon spawns a one-shot subprocess of
+  `delegatedBackend`, the task-mode planner picks the appropriate tool
+  from the integration's registered `capabilityTools`, runs it, and
+  returns a structured result conforming to `outputSchema`. The legacy
+  RPC route `POST /api/integrations/:key/invoke {tool, args}` was
+  retired 2026-05-01 — cross-backend tool-name divergence (Claude
+  `search_threads` vs Codex `search_emails` vs Gemini `search`) made
+  the RPC shape brittle. See `docs/design/17-delegated-mode-v2.md` §4.2 for the
+  retirement rationale and `docs/design/appendices/routine-data-acquisition.md` §8.1
+  for the task-mode body shape.
+
+`native` has no sub-cases. The integration's `nativeBackend` must equal
+the main DM backend — `BackendRouter.setMainBackend` 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`).
 
 ## Why This Concept Exists
 
@@ -97,23 +119,40 @@ that case the daemon spawns the other backend per call.
 - **`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.
+- **`delegated`** — daemon holds nothing for this integration. The
+  daemon's `delegated-sync-worker` polls on opt-in cadences via the
+  delegated backend's connector. Per-DM-turn calls reach the connector
+  through the agent's backend (same-backend) or via the daemon's
+  `/exec` proxy (cross-backend).
+- **`native`** — daemon holds nothing AND runs no poller. The main
+  backend's MCP connector reaches the integration on-demand within the
+  agent's own turn (DM, hourly_check, routine pre-pass). The agent
+  POSTs results to `/api/observations/batch` so the rest of the
+  observation pipeline (summarizer, hourly check) still operates. See
+  `docs/design/appendices/native-integration-mode.md` for the full
+  spec, including the per-key `runtime_state.integration_flip_lock:<key>`
+  drain protocol.
 - **`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/invoke` and the daemon spawns
-  `delegatedBackend` as a subprocess for each call. A
-  `SKILL.delegated.<sessionBackend>.md` file is materialized into the
-  session workdir.
+- **`nativeBackend`** — when native, which backend's connector is
+  expected. Must equal the main DM backend; changing the main backend
+  cascades unmatched `native` rows to `disabled` (the cascade is
+  triggered by `BackendRouter.setMainBackend` /
+  `PUT /api/backends/main`).
+- **Same-backend** — DM session backend matches `delegatedBackend` /
+  `nativeBackend`. 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`. Cross-backend exists only for `delegated` — never
+  for `native`, which is locked to the main DM backend. The agent
+  reaches the integration through `POST /api/integrations/:key/exec`
+  in task mode 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.
@@ -123,7 +162,8 @@ that case the daemon spawns the other backend per call.
 | 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** |
+| Zero setup tax, with opt-in background polling on the delegated backend's connector cadence | **delegated** |
+| Zero setup tax, on-demand only — main backend reaches the integration when the agent turns up a reason to look (no daemon polling, no proxy spawn) | **native** |
 | The integration off entirely | **disabled** |
 
 When you pick `delegated`, also pick `delegatedBackend`:
@@ -136,28 +176,40 @@ When you pick `delegated`, also pick `delegatedBackend`:
   connector you want (e.g. Codex's full Gmail) but a different backend
   is your preferred DM driver (e.g. Claude).
 
+When you pick `native`, `nativeBackend` is fixed to your main DM
+backend. Flipping the main backend re-targets every `native` row; rows
+whose new `nativeBackend` has no descriptor connector for the
+integration (e.g. `gmail` native on a backend that doesn't ship a Gmail
+connector) cascade to `disabled` and the operator gets a DM.
+
 ## 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/invoke -d '{"tool":"search_emails","args":{...}}'` → daemon spawns Codex subprocess with `proxy.md` profile → Codex calls `mcp__codex_apps__gmail._search_emails` → returns raw result through daemon |
+| 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`. |
 
 ## 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`.
+`selectSkillVariantFile(skillSlug, sessionBackend, integrations)`
+returns one of four values, picked by tie-break order
+(`docs/design/appendices/native-integration-mode.md` §5.4.1):
+
+1. `"SKILL.delegated.<sessionBackend>.md"` — at least one touched
+   integration is delegated cross-backend. The body documents the
+   `/exec` task-mode proxy and any native siblings inline (§7.4
+   mixed-mode prompts).
+2. `"SKILL.native.<sessionBackend>.md"` — at least one touched
+   integration is `native` (and no cross-backend wins above). Native
+   is always explicit-skill-required (§7.5 — never drops to `null`).
+3. `null` — every touched integration is delegated same-backend AND
+   each declares the skill in its descriptor's
+   `sameBackendDropsSkillBody`. The connector self-describes; no body
+   is materialized.
+4. `"SKILL.md"` — direct mode, mixed states, or skill not gated by any
+   integration.
 
 ## Where You See It in the Dashboard
 
@@ -166,52 +218,79 @@ Mixed states (some same-backend, some cross-backend) fall back to
 - **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.
+- **Setup wizard** — first-run integration mode picker; both
+  `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
+  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. Example:
+agent consults at session-init. It is rendered as a Markdown table:
 
 ```markdown
-## gmail
-mode: delegated
-delegatedBackend: codex
-deniedTools:
-  - send_email
-  - delete_emails
-
-## google_calendar
-mode: delegated
-delegatedBackend: claude
-deniedTools:
-  - delete_event
+## Current state
+
+| Integration | Mode | Backend | Sub-tier | Last changed |
+|---|---|---|---|---|
+| gmail | delegated | codex | full-auto | 2026-05-15T07:15:32.911Z |
+| google_calendar | native | codex | — | 2026-05-15T07:15:38.605Z |
+| notion | disabled | — | — | 2026-05-15T07:14:56Z |
 ```
 
+The "Backend" column surfaces whichever binding is active for the row —
+`delegatedBackend` for `delegated`, `nativeBackend` for `native`. For
+`direct` and `disabled` rows it is `—`. The "Sub-tier" column annotates
+delegated Gmail rows (`draft-only` for Claude, `full-auto` for Codex)
+and is `—` for everything else. The file also includes the per-backend
+connector support matrix and the `deniedTools` block; both are rendered
+by `renderManagementMd` (`packages/daemon/src/core/management-md.ts`).
+
 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
+  `/exec` endpoint returns `502 auth_error`. Skill prose tells the
+  agent to surface this as "re-sign-in to the connector."
+- **Cross-backend, daemon's delegated-task queue saturated** — `/exec`
+  returns `503 delegated_proxy_busy`. The skill body advises a 3–5s
+  backoff with one retry.
+- **Cross-backend, fully-denied surface** — when every tool in the
+  integration's `capabilityTools` is in `deniedTools`, the task-mode
+  planner has nothing to pick. `/exec` short-circuits with
+  `errorClass: "denied_tool"` before spawning a subprocess.
+- **Same-backend or native, 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.
+- **Mode flip mid-call** — `/exec` returns `409 precondition`; agent
+  re-reads `integrations.md` and replans. `native` rows also flip-lock
+  via the per-key `runtime_state.integration_flip_lock:<key>` row —
+  observations posted during the drain receive
+  `results[*].status = "flip_locked"`; the partial / agent profile
+  records the row in `errors[]` and the next routine tick reaps it.
 
 ## 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.
+- Integration Delegation Framework (design) —
+  `docs/design/14-integration-delegation.md`, the load-bearing spec
+  (§14.14 covers the four modes and their cascade rules).
+- Delegated Mode v2 (design) — `docs/design/17-delegated-mode-v2.md` §4.2, the
+  `/exec` task-mode model that replaced the retired `/invoke` RPC
+  route.
+- Native Integration Mode (design) —
+  `docs/design/appendices/native-integration-mode.md`, the on-demand
+  surface used by `native` rows and its `integration_flip_lock:<key>`
+  drain protocol.
+- Routine Data Acquisition (design) — `docs/design/appendices/routine-data-acquisition.md`
+  §6.8 / §8.1, the per-(integration, mode) partial schema used by
+  `routine.fetch_window`.

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

@@ -18,14 +18,17 @@ tags:
   - core
   - memory
   - storage
+  - knowledge
 status: stable
 ask_examples:
   - Where are my context files stored?
   - How does the agent edit context files?
   - What is the difference between context MD and SQLite?
+  - Where do management rules and policies live?
+  - How does the daemon prevent the agent from writing to disk directly?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-04
+updated: 2026-05-15
 keywords:
   - context
   - markdown
@@ -35,6 +38,10 @@ keywords:
   - roadmap.md
   - rules/management.md
   - rules/policies
+  - agent journal
+  - context API
+  - AgentWriteTracker
+  - durable memory
 related:
   - features/memory-files/today
   - features/memory-files/user-profile
@@ -42,7 +49,6 @@ related:
   - features/memory-files/agent-journal
   - features/memory-files/schedule
   - features/memory-files/projects
-  - features/memory-files/management-rules
 ui_anchors:
   - /knowledge
   - /connections/knowledge
@@ -109,8 +115,7 @@ indexes, and configuration.
 - `projects/<slug>.md` — one file per active project.
 - `rules/management.md` — the umbrella registry: Source-of-Truth
   bindings, Managed Tasks, an Active Policies summary. Always
-  injected into every flow. See
-  [rules/management.md and rules/policies/](../features/memory-files/management-rules.md).
+  injected into every flow.
 - `rules/policies/<slug>.md` — one file per durable management rule
   ("from now on, do X"). The daemon auto-maintains a slug index at
   `rules/policies/_index.md`.

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

@@ -7,6 +7,8 @@ aliases:
   - observation
   - polling
   - hourly check
+  - observation queue
+  - phase 9
 category: concepts
 summary: |
   Observations are change records the polling integrations write into
@@ -17,22 +19,32 @@ tags:
   - core
   - observations
   - polling
+  - integrations
+  - routines
 status: stable
 ask_examples:
   - What is an observation?
   - Why doesn't the agent message me on every git commit?
   - How does the hourly check use observations?
+  - Where does the routine pre-pass write observations?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-15
 keywords:
   - observation
+  - observations
   - polling
   - hourly check
   - phase 9
+  - routine.fetch_window
+  - pre-pass
+  - AgentWriteTracker
+  - contentHash
 related:
   - features/routines/hourly-check
+  - features/routines/morning-routine
   - concepts/process-keys
+  - concepts/routines
 ---
 
 # Observations

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

@@ -16,18 +16,28 @@ section: process-keys
 tags:
   - core
   - dispatch
+  - backends
+  - routing
 status: stable
 ask_examples:
   - What is a ProcessKey?
   - Where can I see all the ProcessKeys?
   - How do I change which model handles a ProcessKey?
+  - What is the difference between configurable and fixed ProcessKeys?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-15
 keywords:
   - process key
+  - ProcessKey
   - dispatch
   - routing
+  - CONFIGURABLE_PROCESS_KEYS
+  - DEFAULT_PROCESS_TIERS
+  - PROCESS_TO_EVENT_TYPE
+  - routine.morning_routine
+  - message.dm
+  - dashboard.chat
 related:
   - concepts/backends-and-tiers
   - concepts/skills
@@ -57,17 +67,22 @@ those subsystems.
   backend on `/settings/models`.
 - **REACTIVE_PROCESS_KEYS**: those tied to in-the-loop events (DMs,
   dashboard chat, docs QA).
-- **DEFAULT_PROCESS_TIERS**: the per-key default (heavy or light).
+- **DEFAULT_PROCESS_TIERS**: the per-key default (`lite`, `medium`, or
+  `high`).
 - **PROCESS_TO_EVENT_TYPE**: maps a ProcessKey to the skill manifest
   key.
 
 ## Concrete Examples
 
-- Routines: `routine.morning_routine`, `routine.morning_routine_initial`,
+- Routines: `routine.morning_routine` (parent envelope read by the
+  pre-routine gate, plus the Phase 5 split keys
+  `routine.morning_routine_today` and `routine.morning_routine_journal`),
   `routine.evening_review`, `routine.weekly_review`,
-  `routine.monthly_review`, `routine.hourly_check`,
+  `routine.hourly_check`,
   `routine.roadmap_refresh`, `routine.today_refresh`,
-  `routine.user_profile_sweep`
+  `routine.user_profile_sweep`. `routine.morning_routine_initial` was
+  retired by morning-routine-optimization.md Phase 7 (2026-05-16) — the
+  first-run branch routes through `routine.morning_routine`.
 - 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

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

@@ -7,29 +7,40 @@ aliases:
   - autonomous routines
   - cron
   - scheduled work
+  - routine pre-pass
+  - morning routine
+  - evening review
 category: concepts
 summary: |
   Routines are the autonomous, scheduled tasks Aitne runs on
-  its own — morning routine, evening review, hourly check, weekly and
-  monthly retros, plus any custom routines you define.
+  its own — morning routine, evening review, hourly check, weekly
+  retro, plus any custom routines you define.
 section: routines
 tags:
   - core
-  - routine
+  - routines
   - autonomous
+  - scheduler
 status: stable
 ask_examples:
   - What routines does the agent run automatically?
   - How do I disable a routine?
   - Can I add my own routine?
+  - What is the routine pre-pass fetcher?
+  - Which routine uses the high tier by default?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-15
 keywords:
   - routine
+  - routines
   - cron
   - autonomous
   - scheduler
+  - routine.fetch_window
+  - pre-pass
+  - dayBoundaryHour
+  - hourly check
 related:
   - features/routines/morning-routine
   - features/routines/evening-review
@@ -37,6 +48,7 @@ related:
   - features/routines/hourly-check
   - features/routines/custom-routines
   - concepts/process-keys
+  - concepts/observations
 ui_anchors:
   - /connections/routines
   - /settings/routines
@@ -48,9 +60,9 @@ ui_anchors:
 
 A routine is a unit of agent work that runs on a schedule, not in
 response to a message. The morning routine fires once per agent day at
-`dayBoundaryHour`; evening / weekly / monthly retros fire on fixed
-schedules in code; the hourly check coalesces accumulated observations
-on a configurable cadence.
+`dayBoundaryHour`; evening and weekly retros fire on fixed schedules
+in code; the hourly check coalesces accumulated observations on a
+configurable cadence.
 
 ## Why This Concept Exists
 
@@ -73,13 +85,20 @@ 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.
-- **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).
+- **Tier policy**: no routine runs heavy by default. The morning
+  routine's first-run branch ran on heavy until
+  `docs/design/appendices/morning-routine-optimization.md` Phase 7
+  (2026-05-16) retired `routine.morning_routine_initial`; the
+  first-run branch now uses the medium-tier parent
+  `routine.morning_routine` with a daemon-prepared
+  `<roadmap_skeleton>` block. Every recurring routine — morning,
+  evening, weekly, hourly check — defaults to **medium**
+  (Sonnet on Claude). The morning routine itself is a two-stage
+  pipeline: Stage A `routine.morning_routine_today` (medium) runs
+  in parallel with Stage B `routine.morning_routine_journal` (lite).
+  The lite (Haiku) tier is reserved for Stage B plus mechanical
+  sub-jobs (the hourly-check triage gate and the 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
@@ -92,14 +111,14 @@ DM is who fired the event.
 
 | ProcessKey | When | Tier |
 |---|---|---|
-| `routine.morning_routine_initial` | First setup day, one-shot | heavy |
-| `routine.morning_routine` | `dayBoundaryHour` daily | medium |
+| `routine.morning_routine` | `dayBoundaryHour` daily (parent envelope; first-run branch detected inline from missing `yesterday.md`) | medium |
+| `routine.morning_routine_today` | Stage A of every morning routine (today.md synthesis + roadmap maintenance + schedule fan-out) | medium |
+| `routine.morning_routine_journal` | Stage B of every morning routine (daily/<yesterday>.md authoring) | lite |
 | `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.fetch_window` | Spawned before each routine above | lite |
 | `routine.hourly_check.triage` | Stage 2 gate of every hourly check | lite |
 | `routine.custom.<slug>` | Operator-defined recurrence | configurable |
 
@@ -107,8 +126,7 @@ DM is who fired the event.
 
 - **Settings → Routines** is where the hourly check active window, the
   hourly check cadence, and any custom routines live. Morning, evening,
-  weekly, and monthly fire times are fixed in code and not surfaced
-  here.
+  and weekly fire times are fixed in code and not surfaced here.
 - **Connections → Routines** is the unified view of next-fire times.
 - **Activity** logs each routine run with its outcome.