@aitne-sh/aitne 0.1.8 → 0.1.10

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

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

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

@@ -17,8 +17,9 @@ section: memory
 tags:
   - core
   - memory
-  - storage
   - knowledge
+  - context
+  - safety
 status: stable
 ask_examples:
   - Where are my context files stored?
@@ -28,20 +29,21 @@ ask_examples:
   - How does the daemon prevent the agent from writing to disk directly?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-06-07
 keywords:
   - context
   - markdown
   - SQLite
-  - today.md
-  - user/profile.md
-  - roadmap.md
-  - rules/management.md
-  - rules/policies
-  - agent journal
+  - state/today.md
+  - identity/profile.md
+  - plans/roadmap.md
+  - policies/management.md
+  - policies/management-captures
+  - journal/agent.md
   - context API
   - AgentWriteTracker
   - durable memory
+  - context-vault v2
 related:
   - features/memory-files/today
   - features/memory-files/user-profile
@@ -53,15 +55,23 @@ ui_anchors:
   - /knowledge
   - /connections/knowledge
 context_files:
-  - today.md
-  - user/profile.md
-  - roadmap.md
-  - agent/journal.md
-  - daily/<date>.md
-  - projects/<slug>.md
-  - rules/management.md
-  - rules/policies/<slug>.md
-  - rules/policies/_index.md
+  - state/today.md
+  - identity/profile.md
+  - plans/roadmap.md
+  - journal/agent.md
+  - journal/daily/<date>.md
+  - plans/projects/<slug>.md
+  - policies/management.md
+  - policies/management-captures/<slug>.md
+  - policies/management-captures/_index.md
+config_keys:
+  - dayBoundaryHour
+  - dataDir
+api_endpoints:
+  - GET /api/context/*
+  - PUT /api/context/*
+  - PATCH /api/context/*
+  - DELETE /api/context/*
 ---
 
 # Memory Model
@@ -72,7 +82,11 @@ Aitne treats Markdown files in `~/.personal-agent/context/`
 as its long-term memory and SQLite
 (`~/.personal-agent/data/personal_agent.db`) as session-scoped state.
 Anything you want the agent to remember between runs lives in an MD
-file you can read, diff, and edit by hand.
+file you can read, diff, and edit by hand. The vault is partitioned
+into six authority classes — `identity/`, `state/`, `plans/`, `journal/`,
+`knowledge/`, and `policies/` — each carrying its own authority and
+lifecycle contract. See [Knowledge Layout](../reference/knowledge-layout.md)
+for the canonical map.
 
 ## Why This Concept Exists
 
@@ -98,27 +112,55 @@ indexes, and configuration.
   legal write path. The agent does not have direct `Edit` / `Write`
   permissions on the filesystem; it must go through the daemon.
 
+## How the Agent Writes
+
+The agent has no `Edit` or `Write` tool. To change a context file it
+calls the daemon over HTTP, and every write funnels through one
+endpoint family so the daemon can validate, hold locks, and snapshot a
+backup before touching disk. Paths are class-prefixed
+(`/api/context/<class>/<path>`):
+
+```bash
+# Append a section to today.md
+curl -X PATCH http://localhost:8321/api/context/state/today.md \
+  -H 'Content-Type: application/json' \
+  -d '{"mode":"append","section":"Notes","content":"Booked the dentist."}'
+```
+
+- `PUT /api/context/*` replaces a whole file; `PATCH` does a section op
+  (`append`, `replace`, `clear`, `clear_before`, `append_to_file`);
+  `DELETE` removes a file (permitted only for custom routines).
+- Legacy bare paths (`/api/context/today.md`) still resolve — the daemon
+  rewrites them to the canonical class-prefixed form in process, so a
+  plain `curl -X PATCH` without `-L` keeps working — but new writes
+  emit the class-prefixed path.
+- `state/today.md` and `plans/roadmap.md` are serialized behind
+  dedicated write locks, so two flows can't clobber each other.
+
 ## Concrete Examples
 
-- `today.md` — rewritten by the morning routine.
-- `user/profile.md` — your profile, hand-edited or appended by the
+- `state/today.md` — rewritten by the morning routine.
+- `identity/profile.md` — your profile, hand-edited or appended by the
   agent on request. Topic-shaped slices live alongside it
-  (`user/people.md`, `user/work.md`, `user/expertise.md`,
-  `user/personal.md`, `user/goals.md`). See
+  (`identity/people.md`, `identity/work.md`, `identity/expertise.md`,
+  `identity/personal.md`, `identity/goals.md`). See
   [User Profile](../features/memory-files/user-profile.md).
-- `roadmap.md` — long-running goals + Preparation Timeline rows that
+- `plans/roadmap.md` — long-running goals + Preparation Timeline rows that
   fire daily during the morning routine.
-- `agent/journal.md` — the agent's own running log of decisions,
+- `journal/agent.md` — the agent's own running log of decisions,
   retros, and judgement calls.
-- `daily/2026-04-25.md` — per-date archive of that day's plan,
+- `journal/daily/2026-04-25.md` — per-date archive of that day's plan,
   synthesized by the morning routine.
-- `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.
-- `rules/policies/<slug>.md` — one file per durable management rule
+- `plans/projects/<slug>.md` — one file per active project.
+- `policies/management.md` — the umbrella registry: Source-of-Truth
+  bindings, Managed Tasks, an Active Policies summary. Injected as
+  `<management_rules>` on the wide-path flows (DMs, mentions, the
+  morning routine); a few narrow routines (the journal stage, hourly
+  check, today refresh, observer events, scheduled tasks) opt out to
+  save budget.
+- `policies/management-captures/<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`.
+  `policies/management-captures/_index.md`.
 
 ## Where You See It in the Dashboard
 
@@ -129,8 +171,9 @@ indexes, and configuration.
 
 ## Related
 
-- [today.md](../features/memory-files/today.md)
-- [user/profile.md](../features/memory-files/user-profile.md)
-- [roadmap.md](../features/memory-files/roadmap.md)
+- [Knowledge Layout](../reference/knowledge-layout.md) — canonical map of every vault file
+- [state/today.md](../features/memory-files/today.md)
+- [identity/profile.md](../features/memory-files/user-profile.md)
+- [plans/roadmap.md](../features/memory-files/roadmap.md)
 - [Skills](skills.md) — the per-skill SKILL.md files that tell the
   agent how to read and write each context file.

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

@@ -29,7 +29,7 @@ ask_examples:
   - Where does the routine pre-pass write observations?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - observation
   - observations
@@ -40,11 +40,31 @@ keywords:
   - pre-pass
   - AgentWriteTracker
   - contentHash
+  - recordObservation
+  - observation queue
+  - dedupe
 related:
   - features/routines/hourly-check
   - features/routines/morning-routine
   - concepts/process-keys
   - concepts/routines
+  - features/integrations/git
+  - features/integrations/obsidian
+ui_anchors:
+  - /activity
+process_keys:
+  - routine.hourly_check
+  - routine.fetch_window
+config_keys:
+  - hourlyCheckIntervalMinutes
+  - hourlyCheckPrePassFreshnessMinutes
+api_endpoints:
+  - POST /api/observations
+  - GET /api/observations
+  - POST /api/observations/consume
+context_files:
+  - packages/daemon/src/core/routine-windows.ts
+  - packages/daemon/src/api/routes/observations.ts
 ---
 
 # Observations
@@ -57,13 +77,15 @@ 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.
+routine (`routine.morning_routine`, `routine.today_refresh`,
+`routine.hourly_check`, `routine.evening_review`,
+`routine.weekly_review`) is preceded by a lite-tier
+`routine.fetch_window` pre-pass that fetches mail / calendar / Notion
+windows and POSTs them to `/api/observations`.
+(`routine.monthly_review` has no pre-pass window.) 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
 
@@ -75,6 +97,18 @@ up to something the operator should hear about.
 
 ## Definitions
 
+**Two writer paths feed one queue.** Observations enter the
+`observations` table from two places, and downstream consumers cannot
+tell them apart:
+
+1. **Background pollers** (Obsidian, Git, GitHub, Notion, Calendar,
+   Mail) call `recordObservation` when they detect a change.
+2. **The pre-pass** — the lite-tier `routine.fetch_window` session
+   spawned ahead of each main routine — POSTs mail / calendar / Notion
+   windows to `/api/observations`.
+
+Both write rows of the same shape; the consumer reads the merged queue.
+
 - **Observation**: one row in the `observations` table.
 - **Actor**: who caused the change. `actor='agent'` rows are filtered
   out by the consumer (anti-loop).
@@ -88,9 +122,10 @@ up to something the operator should hear about.
   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.
+  mail / calendar / Notion integration and POSTs the results to
+  `/api/observations`. The server computes `contentHash` from
+  `(source, payload)`, so an unchanged item written twice in the same
+  cadence dedupes to a 409.
 
 ## Concrete Examples
 
@@ -106,5 +141,8 @@ up to something the operator should hear about.
 ## Related
 
 - [Hourly Check](../features/routines/hourly-check.md)
+- [Morning Routine](../features/routines/morning-routine.md)
+- [Process Keys](./process-keys.md)
+- [Routines](./routines.md)
 - [Git](../features/integrations/git.md)
 - [Obsidian](../features/integrations/obsidian.md)

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

@@ -26,14 +26,17 @@ ask_examples:
   - What is the difference between configurable and fixed ProcessKeys?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - process key
   - ProcessKey
   - dispatch
   - routing
+  - tier
   - CONFIGURABLE_PROCESS_KEYS
   - DEFAULT_PROCESS_TIERS
+  - REACTIVE_PROCESS_KEYS
+  - TIER_LOCKED_PROCESS_KEYS
   - PROCESS_TO_EVENT_TYPE
   - routine.morning_routine
   - message.dm
@@ -42,6 +45,25 @@ related:
   - concepts/backends-and-tiers
   - concepts/skills
   - reference/process-keys
+  - features/operations/backend-routing
+process_keys:
+  - routine.morning_routine
+  - routine.morning_routine_today
+  - routine.morning_routine_journal
+  - routine.evening_review
+  - routine.hourly_check
+  - routine.fetch_window
+  - routine.hourly_check.triage
+  - message.dm
+  - message.mention
+  - dashboard.chat
+  - dashboard.docs_qa
+  - agent.task
+  - agent.dm_task
+  - delegated_task
+  - delegated_task_heavy
+ui_anchors:
+  - /settings/models
 ---
 
 # ProcessKeys
@@ -64,37 +86,49 @@ those subsystems.
 ## Definitions
 
 - **CONFIGURABLE_PROCESS_KEYS**: the set the operator can override per
-  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 (`lite`, `medium`, or
-  `high`).
+  backend on `/settings/models`. The rest (`delegated_task`, `setup`,
+  `schedule.approaching`, …) use fixed defaults and are not surfaced
+  there.
+- **REACTIVE_PROCESS_KEYS**: those tied to in-the-loop events
+  (`message.dm`, `message.mention`, `dashboard.chat`,
+  `dashboard.docs_qa`, `setup`, `knowledge.import`). Everything else is
+  autonomous.
+- **DEFAULT_PROCESS_TIERS**: the per-key default model size — `lite`
+  (Haiku-class), `medium` (Sonnet-class), or `high` (Opus-class).
+  Unknown keys (including `routine.custom.<slug>`) default to `medium`.
+- **TIER_LOCKED_PROCESS_KEYS**: keys whose tier is hard-locked and
+  cannot be overridden by an operator pin. Today this is just
+  `dashboard.docs_qa`, locked to `medium`.
 - **PROCESS_TO_EVENT_TYPE**: maps a ProcessKey to the skill manifest
-  key.
+  key, so the skills compiler can pick the right tool set.
 
 ## Concrete Examples
 
-- 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`),
+- **Routines:** `routine.morning_routine` is the parent envelope read by
+  the pre-routine gate; the actual work runs as two parallel split keys
+  — `routine.morning_routine_today` (Stage A, today.md, medium) and
+  `routine.morning_routine_journal` (Stage B, daily journal, lite). Also
   `routine.evening_review`, `routine.weekly_review`,
-  `routine.hourly_check`,
-  `routine.roadmap_refresh`, `routine.today_refresh`,
-  `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.hourly_check`, `routine.roadmap_refresh`,
+  `routine.today_refresh`, `routine.user_profile_sweep`.
+  `routine.morning_routine_initial` was retired (2026-05-16) — the
+  first-run branch now 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
   `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`
-- Scheduled / external: `agent.task` (recurring schedules),
+- **Custom routines:** `routine.custom.<slug>` (kebab-case slug;
+  defaults to medium tier).
+- **Messaging:** `message.dm`, `message.mention`
+- **Dashboard:** `dashboard.chat`, `dashboard.docs_qa`
+- **Scheduled / external:** `agent.task` (recurring schedules),
   `agent.dm_task` (DM-tone scheduled briefings),
-  `schedule.approaching`, `calendar.change`, `gmail_classify`,
-  `setup`
+  `schedule.approaching`, `calendar.change`, `gmail_classify`, `setup`
+- **Delegated work:** `delegated_task` (lite) and `delegated_task_heavy`
+  — the only high-tier key, opt-in via the `delegatedTaskHeavyEnabled`
+  config flag. No install-time surface defaults to `high`; operators
+  pin high per-row on `/settings/models`.
 
 ## Where You See It in the Dashboard
 

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

@@ -30,7 +30,7 @@ ask_examples:
   - Which routine uses the high tier by default?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-15
+updated: 2026-05-28
 keywords:
   - routine
   - routines
@@ -52,6 +52,25 @@ related:
 ui_anchors:
   - /connections/routines
   - /settings/routines
+process_keys:
+  - routine.morning_routine
+  - routine.morning_routine_today
+  - routine.morning_routine_journal
+  - routine.evening_review
+  - routine.weekly_review
+  - routine.monthly_review
+  - routine.hourly_check
+  - routine.today_refresh
+  - routine.fetch_window
+  - routine.hourly_check.triage
+config_keys:
+  - dayBoundaryHour
+  - hourlyCheckEnabled
+  - hourlyCheckIntervalMinutes
+  - hourlyCheckActiveStartHour
+  - hourlyCheckActiveEndHour
+  - hourlyCheckPrePassFreshnessMinutes
+  - monthlyReviewEnabled
 ---
 
 # Routines
@@ -60,8 +79,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 and weekly retros fire on fixed schedules
-in code; the hourly check coalesces accumulated observations on a
+`dayBoundaryHour`; the evening review (18:00 daily), weekly review
+(Friday 19:00), and optional monthly review fire on fixed schedules in
+code; the hourly check coalesces accumulated observations on a
 configurable cadence.
 
 ## Why This Concept Exists
@@ -82,51 +102,58 @@ DM is who fired the event.
   a ProcessKey starting with `routine.`.
 - **Agent day**: the 24-hour window starting at `dayBoundaryHour`
   (default 04:00) — see [Agent Day](agent-day.md).
-- **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**: 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).
+- **Catch-up**: if the daemon was offline at the trigger time, a
+  boot-time check re-fires any routine whose window has already
+  opened but never ran (morning routine within the agent day; evening
+  review once it is past 18:00; weekly review across Fri–Sun). It never
+  double-fires a routine that already succeeded.
+- **Tier policy**: **no routine runs the high tier by default.** Every
+  recurring routine — morning, evening, weekly, hourly check —
+  defaults to **medium** (Sonnet on Claude). The **lite** (Haiku) tier
+  is reserved for the morning routine's Stage B and for mechanical
+  sub-jobs (the hourly-check triage gate and the pre-pass fetcher). The
+  only high-tier ProcessKey in the whole system is `delegated_task_heavy`,
+  which is opt-in and not a routine. See
+  [Backends and Tiers](backends-and-tiers.md).
+- **Two-stage morning routine**: the morning routine runs as a parent
+  envelope `routine.morning_routine` (medium) that fans out two stages
+  in parallel — Stage A `routine.morning_routine_today` (medium, builds
+  `state/today.md`) and Stage B `routine.morning_routine_journal` (lite,
+  authors the previous day's journal). The legacy heavy-tier
+  `routine.morning_routine_initial` first-run branch was retired in
+  Phase 7 (2026-05-16); a first run is now detected inline from a
+  missing `state/yesterday.md` and handled by the same medium-tier
+  parent with a daemon-prepared `<roadmap_skeleton>` block.
 - **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.
+  POSTs observations. The main routine then consumes the resulting
+  `<fetch_report>` block plus pending observations instead of hitting
+  upstream APIs itself — a cost-savings split introduced in 2026-05.
 
 ## Concrete Examples
 
 | ProcessKey | When | Tier |
 |---|---|---|
-| `routine.morning_routine` | `dayBoundaryHour` daily (parent envelope; first-run branch detected inline from missing `yesterday.md`) | medium |
+| `routine.morning_routine` | `dayBoundaryHour` daily (parent envelope; first-run branch detected inline from missing `state/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.morning_routine_journal` | Stage B of every morning routine (`journal/daily/<yesterday>.md` authoring) | lite |
 | `routine.evening_review` | 18:00 daily (fixed) | medium |
+| `routine.weekly_review` | Friday 19:00 (fixed, one hour after evening review) | medium |
+| `routine.monthly_review` | Last day of month at 18:00, **default off** (`monthlyReviewEnabled`) | medium |
 | `routine.hourly_check` | Every `hourlyCheckIntervalMinutes` (default 60) inside the active window | medium |
-| `routine.weekly_review` | Friday 18:00 (fixed) | medium |
-| `routine.fetch_window` | Spawned before each routine above | lite |
+| `routine.today_refresh` | On calendar drift or a dashboard "refresh today" request (not a fixed cron) | medium |
+| `routine.fetch_window` | Spawned before each routine above that needs fresh upstream data | lite |
 | `routine.hourly_check.triage` | Stage 2 gate of every hourly check | lite |
-| `routine.custom.<slug>` | Operator-defined recurrence | configurable |
+| `routine.custom.<slug>` | Operator-defined recurrence | medium (override per routine via `backend_tier`) |
 
 ## Where You See It in the Dashboard
 
-- **Settings → Routines** is where the hourly check active window, the
-  hourly check cadence, and any custom routines live. Morning, evening,
-  and weekly fire times are fixed in code and not surfaced here.
+- **Settings → Routines** is where the hourly check active window
+  (`hourlyCheckActiveStartHour` / `hourlyCheckActiveEndHour`), the
+  hourly check cadence (`hourlyCheckIntervalMinutes`), and any custom
+  routines live. Morning, evening, weekly, and monthly 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.