@aitne-sh/aitne 0.1.8 → 0.1.9

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-05-28
 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,52 @@ 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
+- `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. Always
   injected into every flow.
-- `rules/policies/<slug>.md` — one file per durable management rule
+- `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 +168,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.
 

package/agent-assets/docs/concepts/safety-and-execution.md

@@ -19,7 +19,8 @@ section: safety
 tags:
   - core
   - safety
-  - cost
+  - operations
+  - backends
 status: stable
 ask_examples:
   - What is the difference between Safe and Allow mode?
@@ -27,7 +28,7 @@ ask_examples:
   - How do I see what tools the agent is allowed to use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - safety
   - safe mode
@@ -35,18 +36,23 @@ keywords:
   - absolute block
   - disallowed tools
   - approval
+  - execution mode
+  - risk tier
 related:
+  - concepts/safety-model
   - concepts/skills
   - features/operations/approvals
   - reference/disallowed-tools
 ui_anchors:
   - /settings/advanced
+  - /settings/models
 config_keys:
   - disallowedTools
   - allowedToolsOverride
   - claudeExecutionPermissionMode
   - codexExecutionPermissionMode
   - geminiExecutionPermissionMode
+  - opencodeExecutionPermissionMode
 ---
 
 # Safety and Execution Modes
@@ -57,10 +63,13 @@ Three layers gate what the agent can do:
 
 1. **Skill `allowed-tools`** — the visible toolset for that session.
 2. **Execution mode** — Safe (strict permission checks, sandboxes)
-   or Allow (SDK bypass, sandbox off). Per-backend.
-3. **Always-disallowed** — a hard floor. Recursive deletes, sudo,
+   or Allow (SDK bypass, sandbox off). Set per-backend.
+3. **Always-disallowed** — a hard floor. Recursive deletes, `sudo`,
    secret-file reads / writes are denied unconditionally regardless
-   of mode.
+   of mode, and neither a skill nor Allow mode can widen past it.
+
+A fourth idea — the **risk tier** — sits on top of the daemon API and
+decides whether a *write* runs on its own or waits for your approval.
 
 ## Why This Concept Exists
 
@@ -72,37 +81,57 @@ disallowed-tools floor.
 
 ## Definitions
 
-- **Safe mode**: the default. Strict permission checks, Claude curl/jq
-  hooks, Codex workspace-write sandbox, Gemini whitelist TOML.
+- **Safe mode**: the default. Strict permission checks, plus a
+  backend-specific enforcement layer — Claude curl/jq hooks, the Codex
+  workspace-write sandbox, the Gemini whitelist TOML, and the OpenCode
+  permission block.
 - **Allow mode**: the looser posture. SDK bypass, sandbox off, minimal
-  TOML. The absolute-block layer still holds.
+  TOML. The absolute-block layer still holds in Allow mode, so the
+  destructive-ops floor never opens. Set independently per backend, so
+  one backend can run Allow while the others stay Safe.
 - **Absolute block**: the unconditional layer. `ALWAYS_DISALLOWED_TOOLS`
   in `src/safety/always-disallowed.ts`. Cannot be widened by skills,
   by config, or by allow-mode.
-- **Risk tier**: `read`, `notify`, `approve`. Read = autonomous. Notify
-  = the agent proceeds after DMing the operator. Approve = blocked
-  until the operator clicks approve in the dashboard.
+- **Risk tier**: every daemon-API operation carries one of three tiers —
+  `autonomous`, `read_sensitive`, or `approve`. *Autonomous* runs without a
+  prompt. *Read-sensitive* reads (email, calendar, notes, context files) are
+  the same blast radius as autonomous but are gated by a read token when
+  `enforceReadToken` is on. *Approve* is blocked until you confirm with a
+  bearer token (the dashboard does this when you click Approve). There is no
+  separate "notify" tier — that behaviour now lives in the skill prompts: for
+  potentially destructive actions the agent DMs you first, then proceeds. See
+  [Safety model](safety-model.md) for the full taxonomy.
 
 ## Concrete Examples
 
-| Action | Risk tier |
+The daemon API is the agent's only write path, so most of its own writes are
+`autonomous` (the memory chokepoint validates and snapshots them). The
+absolute-block layer and Approve tier are where the agent is actually stopped.
+
+| Action | What gates it |
 |---|---|
-| Read `today.md` | read |
-| Append to `agent/journal.md` | notify |
-| Send a DM | notify |
-| Update `roadmap.md` | approve |
-| Recursive delete | absolute-block (refused) |
-| `chmod` on a daemon-owned file | absolute-block |
+| Read `state/today.md` | `read_sensitive` (read token if `enforceReadToken`) |
+| Append to `journal/agent.md` | `autonomous` — daemon API write |
+| Update `plans/roadmap.md` | `autonomous`, plus a roadmap write-lock |
+| Send a DM | `autonomous`; destructive follow-ups DM you first |
+| Configure an automation trigger | `approve` — needs a bearer token |
+| `chmod` on a daemon-owned file | Safe-mode disallowed (allowed in Allow mode) |
+| Recursive delete (`rm -rf`), `sudo`, secret-file read | absolute-block (refused in both modes) |
 
 ## Where You See It in the Dashboard
 
-- **Settings → Advanced** holds `disallowedTools`, `allowedToolsOverride`,
-  and the per-backend execution mode switch.
-- **Activity** logs every blocked tool call as `action_type='blocked_absolute'`.
+- **Settings → Advanced** holds the `disallowedTools` and
+  `allowedToolsOverride` tool-policy lists.
+- **Settings → Models & Cost** holds the per-backend Safe / Allow
+  **Execution Mode** switch (you can also set it in the setup wizard).
+- **Activity** logs every absolute-blocked tool call as
+  `action_type='blocked_absolute'`.
 - **Approvals** is where Approve-tier actions queue when they fire.
 
 ## Related
 
+- [Safety model](safety-model.md) — the full risk-tier taxonomy and where
+  each API endpoint is classified.
 - [Skills](skills.md) — where each session's per-task `allowed-tools` lives.
 - [Approvals](../features/operations/approvals.md) — the operator-side
   surface for Approve-tier actions.