@aitne-sh/aitne 0.1.7 → 0.1.8

package/README.md

@@ -2,198 +2,66 @@
 
 # Aitne
 
-### Always on. Always yours.
-
-**A local-first, proactive personal AI agent that runs continuously on your own machine — and learns *you* every day.**
+**A local-first, proactive personal AI agent.**
+A long-running TypeScript daemon watches your calendar, mail, repos, and notes — and acts on its own. Your AI of choice (Claude / Codex / Gemini; OpenCode coming soon) is the brain; Aitne is the nervous system.
 
 [![npm version](https://img.shields.io/npm/v/@aitne-sh/aitne.svg)](https://www.npmjs.com/package/@aitne-sh/aitne)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)](https://nodejs.org)
+[![Status](https://img.shields.io/badge/status-pre--1.0-orange)](#status)
 [![Platforms](https://img.shields.io/badge/platforms-macOS%20%7C%20Linux%20%7C%20Windows-blue)](#platform-support)
-[![Backends](https://img.shields.io/badge/backends-Claude%20%7C%20Codex%20%7C%20Gemini-purple)](#multi-backend)
 
 ```bash
 npm install -g @aitne-sh/aitne@latest
 aitne start
 ```
 
-</div>
-
----
-
-## Overview
+![Aitne setup and dashboard walkthrough](./docs/assets/aitne-demo.gif)
 
-ChatGPT and Claude wait for you to type. **Aitne does not.** It's a tiny TypeScript daemon that lives on your laptop, watches your calendar, mail, repositories, and notes, and acts on its own — drafting your morning plan at 04:00, surfacing the email you forgot, nudging you about the PR your teammate is waiting on, and weaving everything into Markdown files *you* own.
-
-You bring the brain — Claude Code, OpenAI Codex CLI, or Google Gemini CLI. Aitne is the nervous system that schedules, routes, observes, and remembers.
+</div>
 
 ---
 
-## What makes Aitne different
-
-**It compounds.** Every DM, every reaction, every implicit signal shapes how Aitne thinks about you. After a month it sounds like you. After a year it remembers what you forgot last quarter. The model never changes — *the context does*.
-
-**You manage it in plain language.** "Don't ping me before 9am." "Remember my partner's birthday." "Stop running hourly checks on weekends." A dedicated set of management skills (`management-task-register`, `management-policy`, `user-profile`, …) maps your words to settings, schedules, and profile updates. No 80-panel settings UI.
+## Why Aitne
 
-**It rides on what you already have.** Your `~/.claude/skills`, your `~/.codex/config.toml`, your `~/.gemini/` settings, your custom MCP servers — Aitne reads them on session init and layers its persona on top. Your existing toolkit shows up in every Aitne-spawned session. No re-configuring. No vendor lock.
-
-**Your memory is plain Markdown.** Everything Aitne writes lands in `~/.personal-agent/context/*.md`. You can `cat`, `vim`, `obsidian`, or `cp` any of it. Uninstall and the memory is still yours. No proprietary format. No migration headache.
-
-**It runs entirely on your machine.** The daemon binds to `127.0.0.1` only. Secrets live in the OS keychain (macOS Keychain / libsecret / DPAPI). No telemetry. No cloud state. Verify with `lsof` and `nettop`.
+- **Proactive, not reactive.** Drafts your morning plan at 04:00. Surfaces the email you forgot. Nudges you about the PR your teammate is waiting on. You don't have to open an app.
+- **Local-first.** Daemon binds to `127.0.0.1` only. Secrets in the OS keychain. Memory in plain Markdown under `~/.personal-agent/`. No telemetry, no cloud state.
+- **Multi-backend.** Bring Claude Code, Codex CLI, or Gemini CLI — or all three. Per-task tier routing decides which one runs for each kind of work. (OpenCode is wired internally and ships as preview-only in this release.)
+- **Compounds.** Every DM, every correction shapes how Aitne thinks about you. The model doesn't change — the context does.
 
 ---
 
-## Installation
-
-### From npm
-
-The recommended path. Installs the `aitne` CLI globally with the daemon, dashboard, and built-in agent assets.
-
-```bash
-npm install -g @aitne-sh/aitne@latest
-aitne start
-```
-
-Then bring **at least one** AI backend:
-
-```bash
-# Claude Code — full feature support including server-side advisor
-npm install -g @anthropic-ai/claude-code
-claude auth login
-
-# OpenAI Codex CLI
-npm install -g @openai/codex
-codex login --device-auth
-
-# Google Gemini CLI
-npm install -g @google/gemini-cli
-# OAuth handled on first use
-```
-
-Login once with each CLI you intend to use — Aitne auto-detects them on the next session.
-
-### From source (git)
-
-For contributors, or if you want to hack on the daemon directly. Requires Node ≥ 22 and pnpm 10.x.
-
-```bash
-git clone https://github.com/Aitne-sh/Aitne.git aitne
-cd aitne
-corepack enable
-pnpm install
-pnpm start          # build (if stale) + launch daemon and dashboard in background
-# or
-pnpm dev            # foreground with full stdio for debugging
-```
-
-Common workflows:
-
-```bash
-pnpm test           # vitest unit tests across packages/*
-pnpm test:watch
-pnpm lint           # turbo run lint
-pnpm clean          # turbo clean + remove node_modules and .buildstamp
-```
-
-### Verifying the install
-
-```bash
-aitne status        # PIDs, uptime, connected platforms, backends, today's spend
-aitne doctor        # 9-check install diagnostic
-aitne logs -f       # tail the daemon log
-```
-
-The daemon listens on `:8321`, the dashboard on `:3000`. Open `http://localhost:3000` and finish the 9-step setup wizard.
-
----
-
-## How it works
-
-A long-running daemon receives signals from every channel you've connected, parks short-term state in SQLite, and spawns an AI session whenever it needs to think. The session reads your Markdown memory, calls a curated set of skills, and writes results back through the daemon API.
-
-```mermaid
-flowchart LR
-    subgraph WORLD["Your digital life"]
-        direction TB
-        W1["Messages"]
-        W2["Calendar"]
-        W3["Mail"]
-        W4["Git / GitHub"]
-        W5["Notes"]
-    end
-
-    subgraph LOCAL["Your laptop"]
-        direction TB
-        DAEMON["Aitne daemon<br/>(always on)"]
-        BRAIN["AI session<br/>Claude / Codex / Gemini"]
-        MEMORY["Markdown memory<br/>plain files you own"]
-        DAEMON --- BRAIN
-        BRAIN --- MEMORY
-        DAEMON --- MEMORY
-    end
-
-    YOU["You<br/>Slack · Telegram · Discord<br/>WhatsApp · Web dashboard"]
-
-    WORLD --- DAEMON
-    DAEMON --- YOU
-```
-
-The daemon runs two execution paths in parallel:
-
-- **Reactive path** — owner DMs, mentions, cron-driven routines (morning, evening, weekly, monthly), and calendar-approach events flow through the EventBus into the Dispatcher, which spawns a backend session sized for the work.
-- **Polling path** — observers for Git, GitHub, Obsidian, Notion, Calendar, and mail write to an `observations` table without spawning sessions. A cron-driven hourly check triages those observations through a lite-tier session, then escalates to a full Sonnet-class session only if something worth surfacing was found.
-
-A pre-pass `routine.fetch_window` session runs before each routine, fanning out per-account fetches (mail, calendar, Notion) into the `observations` table so the main session reads from a single source.
-
-### What you can do with it
-
-A non-exhaustive catalogue — every entry below is backed by an implemented skill, route, or observer. Click to expand.
+## Highlights
 
 <details>
 <summary><b>Time, calendar, travel</b></summary>
 
 - Auto-generate `today.md` every morning with your real schedule
-- 15-min approach reminders for every calendar event, with travel time pre-computed via Google Maps
+- 15-min approach reminders for every event, with travel time pre-computed via Google Maps
 - Find a 30-min slot across multiple calendars — Aitne checks freebusy and replies with options
-- Auto-extract flight, hotel, restaurant, train confirmations from email into a structured travel timeline
-- Surface tomorrow's itinerary in the morning briefing
-- "What time should I leave for my next meeting?" — answers with live traffic
+- Auto-extract flight, hotel, train confirmations from email into a structured travel timeline
 </details>
 
 <details>
 <summary><b>Mail across every account</b></summary>
 
 - Unified inbox across Gmail, Outlook, Yahoo, and iCloud (OAuth or app-password / IMAP)
-- Local FTS5 full-text search across every account ("find emails about acme last quarter")
-- Auto-classify, label, and archive (Gmail) — filter rules across all providers
-- Draft replies in your style ("draft a polite no to this conference invite")
-- Forwarded receipts extract to a structured `receipts` table with category, vendor, amount
-- Daily digest of unread mail in the morning briefing
-- IMAP IDLE for near-real-time delivery; PDF and image attachments are extracted and indexed
+- Local FTS5 full-text search across every account
+- Auto-classify, label, archive, and draft replies in your style
+- Forwarded receipts auto-extract into a structured receipts table
+- IMAP IDLE for near-real-time delivery; PDF/image attachments are extracted and indexed
 </details>
 
 <details>
-<summary><b>Knowledge: Obsidian, Notion, your own notes</b></summary>
+<summary><b>Knowledge: Obsidian, Notion, your own wiki</b></summary>
 
 - Use your existing Obsidian vault as Aitne's primary memory store — wiki-links keep working
-- Append to your daily note via the official Obsidian CLI (`obsidian create` / `daily:append`)
-- Full Notion page and database CRUD — query, create, update, archive
-- "Summarize what I wrote about this project last month" — across vault layers
-- Auto-link new notes to existing concepts
-</details>
-
-<details>
-<summary><b>Build a personal wiki from anything you DM</b></summary>
-
-- DM `!ingest <url>` — the agent fetches, summarises, and saves a raw note in `10_raw/`
-- Run `!compile` to synthesise raw notes into linked wiki articles in `20_wiki/` with an auto-maintained `_index.md`
-- `!compile --preview` shows added / modified / unchanged pages plus cost and ETA before you spend tokens
-- `!compile full` rebuilds everything — cost-gated, with a dashboard approval queue and an optional git pre-compile snapshot for external vaults
+- Append to your daily note via the official Obsidian CLI
+- Full Notion page and database CRUD
+- DM `!ingest <url>` to capture a source, `!compile` to synthesize raw notes into linked wiki articles
 - `!ask <question>` answers from your own wiki and writes the cited reply to `30_outputs/`
-- `!lint` audits for orphans, broken links, schema drift, and taxonomy candidates → dated health report
-- `!trace <topic>` and `!connect A B` reconstruct how an idea evolved and find shared structure across domains
-- Multiple workspaces (`!ingest @research ...`, `!compile @ops full`) — default workspace falls through when `@` is omitted
-- Workspaces can be internal (`~/.personal-agent/wiki/`) or any number of external Obsidian vaults
+- `!lint`, `!trace`, `!connect` for vault health, idea evolution, cross-domain bridges
+- Multiple workspaces (`!ingest @research ...`) — internal or any number of external Obsidian vaults
 </details>
 
 <details>
@@ -202,816 +70,314 @@ A non-exhaustive catalogue — every entry below is backed by an implemented ski
 - Local Git: `git log`, `git diff`, `git show` exposed via daemon proxy
 - GitHub: PR lists, comments, issues, webhook receivers (HMAC-SHA256 verified)
 - Per-repo cron triggers — "every Monday at 09:00, summarize merged PRs into `projects/<repo>.md`"
-- "Why did this build break?" — agent reads CI status, diff, and traces
 - Auto-detect when a coworker modified a file you're about to ship
 - Unified Repositories: one row pairs a local clone with a GitHub remote; the doctor flags drift
 </details>
 
 <details>
-<summary><b>Tasks, projects, life admin</b></summary>
-
-- Unified task view across GitHub Issues, mail-derived TODOs, and your own `today.md`
-- Per-project Markdown files with auto-maintained status, deadlines, and people
-- Long-term roadmap with quarterly milestones
-- "Carry this to tomorrow" — handoff between `today.md`, `daily/`, `weekly/`, `monthly/`
-- Auto-detect recurring chores and set up reminders
-</details>
-
-<details>
-<summary><b>Reading, lifestyle, voice</b></summary>
-
-- Import Kindle highlights, build a reading-taste profile
-- Friday book recommendation DM based on your taste
-- Receipts auto-organized by month into your vault
-- Travel itinerary roll-up surfaced before each trip
-- Voice attachments — send a voice memo, get a Whisper-transcribed message (opt-in, runs locally via `ffmpeg-static` + `@huggingface/transformers`)
-</details>
-
-<details>
-<summary><b>Self-management and automation</b></summary>
-
-- Tell it to remember things in plain language ("I'm allergic to nuts")
-- Tell it to forget things ("delete that note about my old job")
-- Tell it to change schedules ("don't run hourly checks on weekends")
-- Tell it to change tone ("be more concise, no preamble")
-- Custom routines on any cron schedule with free-form prompts
-- Self-scheduled wakeups — agent decides when to check on something
+<summary><b>Self-management via natural language</b></summary>
+
+- "Don't run hourly checks on weekends" — patches the cron window
+- "Remember my partner's birthday is March 14" — appends to `user/profile.md`
+- "I prefer concise replies — no preamble" — updates the agent's `character` field
+- "Email me a summary every Friday at 5pm" — creates a recurring schedule
+- "Switch to Codex for code reviews" — flips the per-process backend mapping
+- Every change is journaled to `agent_actions` — audit anything via `aitne audit`
 </details>
 
 <details>
-<summary><b>Run your own tools</b></summary>
+<summary><b>Bring your own toolkit</b></summary>
 
-- Bring your own MCP servers — they materialize into every session workdir
-- Bring your own Claude Code skills — they show up wherever the agent runs
-- Bring your own Codex / Gemini config — Aitne reads it on session init
-- Custom skills via the `/api/skills` endpoint — drop a `SKILL.md` and it's live
+- Your `~/.claude/skills`, `~/.codex/config.toml`, and `~/.gemini/` settings are loaded on session init (`~/.opencode/` is recognised but its executor is coming soon)
+- Custom MCP servers materialize into every per-session workdir
+- Aitne layers its persona on top of your existing config — nothing gets overwritten
+- Voice attachments — opt-in local Whisper transcription via `ffmpeg-static` + `@huggingface/transformers`
 </details>
 
 ---
 
-## A day with Aitne
-
-A walkthrough of one user's Tuesday.
-
-**04:00 — While you sleep.** Aitne reads yesterday's handoff, your calendar for today, the last 24 hours of mail across your accounts, new commits in your repos, and the pending observations from Notion. It generates `today.md` and queues a Morning Briefing DM for after quiet hours end.
-
-**07:30 — Slack DM lands as you grab coffee:**
-> Good morning. 3 things to flag:
-> - **Sarah's PR (#487)** needs your review — she's been blocked since Friday
-> - **Sales call with Acme @ 14:00** — leaving home by 13:25 (12-min commute)
-> - **IRS reminder from Friday** — deadline is *tomorrow*
->
-> Today: 2 meetings, 4 tasks. Light day. Reply `end` to close, or just talk to me.
-
-**09:15 — You DM Aitne:** *"Tell Sarah I'll review by 11. And book lunch with Mark on Thursday — somewhere near his office."*
-
-Aitne drafts the Slack reply to Sarah, finds 3 lunch slots Thursday, checks Mark's last 5 lunch venues from your `people.md`, suggests Tartine. You confirm.
-
-**11:30 — Hourly check fires.** A new commit in your repo modified the API contract you're about to ship. Aitne adds a note to `today.md` and DMs once: *"Heads up — `auth.ts:84` was just changed by @Yuki. Want me to summarize the diff?"*
+## Status
 
-**13:45 — Calendar approach.** *"Sales call in 15 min. Acme is the warm lead from last Tuesday — they mentioned wanting webhook integration. Brief is in `projects/acme.md`."*
-
-**15:45 — You forward a hotel confirmation email.** Aitne extracts dates, address, and confirmation number into `travel_bookings`, saves the PDF to `~/.personal-agent/context/receipts/2026/05/`, and adds the trip to next week's morning briefing.
-
-**18:00 — Evening review.** Aitne notices you didn't reply to two emails from this morning. They get carried to tomorrow's `today.md`. It also sees you wrote *"shorter please"* twice today, classifies that as a tone-class signal, and silently shortens its replies going forward.
-
-**Friday 18:30 — Weekly review.**
-> Week of 2026-05-04: shipped 3 PRs, 2 deferred. Open loops: hotel cancellation, Acme follow-up. Focus next week: launch prep. Heads up: you've worked past 22:00 every day this week — should I clear Friday afternoon?
-
-The point isn't any single trick — it's that **all of this happens without you opening an app.**
+Pre-1.0. APIs, schema, and dashboard surfaces may still change. SQLite migrations are deliberately destructive ("clean reinstall, no data migration"); Markdown memory in `context/` is forward-compatible and safe to keep across upgrades.
 
 ---
 
-## How Aitne accumulates knowledge
-
-Every signal flows through the same pipeline: capture → short-term → long-term → injected back into every future conversation.
+## Install
 
-```mermaid
-flowchart TB
-    SOURCES["Sources: messages, calendar, mail,<br/>git, GitHub, Obsidian, Notion,<br/>your own manual edits"]
-    OB["Observers and adapters<br/>(WebSocket, IDLE, polling)"]
-    SQL["SQLite: observations,<br/>messages, agent_actions"]
-    TODAY["today.md<br/>(working view, always injected)"]
-    PROFILE["user/profile.md<br/>work, expertise,<br/>people, goals"]
-    PROJECTS["projects/*.md<br/>roadmap.md"]
-    JOURNAL["daily/YYYY-MM-DD.md<br/>weekly/YYYY-Www.md<br/>monthly/YYYY-MM.md"]
-    AI["Next session<br/>any backend, any platform"]
-
-    SOURCES --> OB
-    OB --> SQL
-    SQL --> TODAY
-    TODAY --> JOURNAL
-    TODAY --> PROFILE
-    TODAY --> PROJECTS
-
-    PROFILE -.-> AI
-    TODAY -.-> AI
-    PROJECTS -.-> AI
-    JOURNAL -.-> AI
+```bash
+npm install -g @aitne-sh/aitne@latest
+aitne start
 ```
 
-**Key properties:**
+Then bring at least one AI backend. The documented operating mode is **provider API keys** — paste them into the setup wizard (they land in the OS keychain, never `.env`):
 
-- **Plain Markdown.** `cat`, `vim`, `obsidian`, `cp` — there is no proprietary format. Uninstall and the memory stays yours.
-- **Layered retention.** `today.md` rotates to `yesterday.md` once per agent-day. `daily/` files are persistent by design (synthesized journal). `weekly/` is pruned after one year. `agent/journal.md` keeps the most recent ~12 weekly + 24 monthly sections. SQLite-backed history (messages, agent_actions) is pruned after 90 days.
-- **Always-injected context.** Every session starts with `user/profile.md` + `rules/management.md` + `today.md` already loaded — the agent never has to "search for context".
-- **You can always intervene.** Edit any file by hand. The agent picks up your changes on the next routine.
+| Backend | Install | Auth |
+|---|---|---|
+| **Claude Code** | `npm install -g @anthropic-ai/claude-code` | `ANTHROPIC_API_KEY` in the wizard (Anthropic's headless-agent policy disallows Pro/Max subscriptions for SDK-driven sessions) |
+| **OpenAI Codex CLI** | `npm install -g @openai/codex` | `OPENAI_API_KEY` in the wizard, or `codex login --device-auth` as fallback |
+| **Google Gemini CLI** | `npm install -g @google/gemini-cli` | `GEMINI_API_KEY` / `GOOGLE_API_KEY`, or OAuth on first use |
+| **OpenCode** (sst/opencode) | _coming soon_ — registered for preview; setup will open when the runtime executor lands | _coming soon_ |
 
-### Compounding intelligence
+The daemon listens on `:8321`, the dashboard on `:3000`. After `aitne start`, the browser opens to a 9-step setup wizard.
 
-The longer you use it, the better it gets. Not because the model improves — because the context does.
+### Verify the install
 
-```mermaid
-flowchart LR
-    D1["Day 1<br/>Empty profile<br/>Generic answers"]
-    W1["Week 1<br/>Calendar synced<br/>People dictionary"]
-    M1["Month 1<br/>Profile auto-filled<br/>Tone matches you"]
-    M3["Month 3<br/>Full project map<br/>Proactive nudges"]
-    Y1["Year 1<br/>Anticipates needs<br/>Recalls Q1 context"]
-
-    D1 --> W1 --> M1 --> M3 --> Y1
+```bash
+aitne status   # PIDs, uptime, connected platforms, today's spend
+aitne doctor   # 10-check install diagnostic
+aitne logs -f  # tail the daemon log
 ```
 
-### The implicit feedback loop
-
-Every interaction shapes Aitne's understanding of you implicitly. No buttons. No surveys.
-
-The Signal Detector tags each turn for **tone-class signals** (corrections like "be shorter", "no preamble") and **attribute-class signals** (durable facts like "I'm allergic to nuts"). The Evening Review interprets them:
-
-- **Tone** → updates the `character` runtime-config field, applied to every backend's system prompt.
-- **Attribute** → updates `user/profile.md` Learned Context.
-
-The line is enforced server-side: "I prefer concise replies" is tone (goes to character). "My flight is on Friday" is attribute (goes to profile).
+### From source
 
----
-
-## Talk to it like a person
+For contributors, or to hack on the daemon directly. Requires Node ≥ 22 and pnpm 10.x.
 
-Aitne has a dedicated set of management skills — `management-task-register`, `management-task-modify`, `management-task-stop`, `management-policy`, `user-profile`, `user-interview`. **You don't poke through 80 settings panels — you tell it.**
+```bash
+git clone https://github.com/Aitne-sh/Aitne.git aitne
+cd aitne
+corepack enable
+pnpm install
+pnpm dev          # foreground mode with full stdio
+```
 
-| You say (in any language) | Aitne does |
-|---|---|
-| *"Don't run the hourly check on weekends"* | Patches `hourlyCheckActiveStartHour/EndHour` per weekday |
-| *"Stop pinging me about Slack after 9pm"* | Updates `quietHoursStart/End` and per-platform notify policy |
-| *"Always check Sarah's calendar before scheduling with her"* | Adds a rule to `rules/management.md` |
-| *"Remember my partner's birthday is March 14"* | Appends to `user/profile.md` Learned Context |
-| *"I prefer concise replies — no preamble"* | Updates `character` field |
-| *"Move all my React work into one project file"* | Refactors `projects/*.md` and re-indexes |
-| *"Cancel tomorrow's morning briefing"* | Removes the `agent_schedule` row |
-| *"Forget what I said about my old job"* | Surgically edits `user/work.md` |
-| *"Email me a summary every Friday at 5pm"* | Creates a recurring schedule with a free-form prompt |
-| *"Switch to Codex for code reviews from now on"* | Updates `process_backend_config` mapping |
-
-Behind the scenes, the agent maps natural language to one of:
-
-- `PATCH /api/config` — runtime config (~100 keys)
-- `PUT /api/context/*` — Markdown memory (locked, validated, snapshotted)
-- `DELETE /api/schedule/:id` / `POST /api/recurring-schedules` — scheduling
-- `PATCH /api/config/character` — tone
-- `POST /api/triggers` — cron-driven custom routines
-
-Every change is journaled to `agent_actions` with `source_kind=user_directive`. Audit anything you don't recognize via `aitne audit`.
+See [docs/setup-guide.md](docs/setup-guide.md) for the full installation walkthrough.
 
 ---
 
-## Bring your own harness
+## How it works
 
-Already invested in Claude Code skills? Custom MCP servers? A polished `~/.codex/config.toml`? **Aitne loads them all.** No re-configuring. No vendor lock.
+A long-running daemon receives signals from every channel you've connected, parks short-term state in SQLite, and spawns an AI session whenever it needs to think. The session reads your Markdown memory, calls a curated set of skills, and writes results back through the daemon API.
 
 ```mermaid
 flowchart LR
-    Y1["~/.claude/<br/>skills, slash commands,<br/>MCP servers"]
-    Y2["~/.codex/<br/>config, plugins"]
-    Y3["~/.gemini/<br/>config, tools"]
-    Y4["Your custom<br/>MCP servers"]
-    A1["Aitne built-in skills<br/>(24 of them)"]
-    A2["Per-event task flows"]
-    A3["Persona MD per backend"]
-    SESS["Per-session workdir<br/>~/.personal-agent/agent-sessions/[id]/<br/>CLAUDE.md, AGENTS.md, GEMINI.md<br/>plus .claude/skills, .codex/skills<br/>plus materialized MCP config"]
-    RUN["Backend runs with<br/>your full toolkit plus Aitne's"]
-
-    Y1 --> SESS
-    Y2 --> SESS
-    Y3 --> SESS
-    Y4 --> SESS
-    A1 --> SESS
-    A2 --> SESS
-    A3 --> SESS
-    SESS --> RUN
-```
+    subgraph WORLD["Your digital life"]
+        direction TB
+        W1["Messages"]
+        W2["Calendar"]
+        W3["Mail"]
+        W4["Git / GitHub"]
+        W5["Notes"]
+    end
 
-| You already have… | In Aitne it just works |
-|---|---|
-| A Claude Code MCP server connected to your company's internal API | Every Aitne session can use it. No code changes. |
-| Custom slash commands you built for `/review` or `/test` | Available in every Aitne-spawned Claude Code session. |
-| A polished `AGENTS.md` for your Codex setup | Aitne layers its persona on top, keeping your config intact. |
-| Your Gemini auth and project preferences | Inherited automatically. |
-| Skills you wrote for `~/.claude/skills/` | Imported on demand. |
+    subgraph LOCAL["Your laptop"]
+        direction TB
+        DAEMON["Aitne daemon<br/>(always on, 127.0.0.1)"]
+        BRAIN["AI session<br/>Claude / Codex / Gemini<br/>(OpenCode coming soon)"]
+        MEMORY["Markdown memory<br/>plain files you own"]
+        DAEMON --- BRAIN
+        BRAIN --- MEMORY
+        DAEMON --- MEMORY
+    end
 
-**The growth flywheel:** Claude Code, Codex, or Gemini ships a new connector → Aitne picks it up on next session → you get it for free.
+    YOU["You<br/>Slack · Telegram · Discord<br/>WhatsApp · Web dashboard"]
 
----
+    WORLD --- DAEMON
+    DAEMON --- YOU
+```
 
-## Multi-platform, multi-app
+Two execution paths run in parallel:
 
-One agent, every surface. A morning brief delivered to Slack, a follow-up via WhatsApp, an email draft from the dashboard — Aitne carries the same context across all of them.
+- **Reactive path** — owner DMs/mentions, cron routines (morning / evening / weekly), calendar approach events. Event → priority heap → dispatcher → backend session.
+- **Polling path** — observers for Git, GitHub, Obsidian, Notion, Calendar, Mail write to an `observations` table without spawning sessions. An hourly cron triages those observations through a lite-tier session, then escalates to a full Sonnet-class session only if something worth surfacing was found.
 
-```mermaid
-flowchart LR
-    IN["Input surfaces:<br/>Slack DM, Telegram, Discord,<br/>WhatsApp, Web dashboard,<br/>manual file edits"]
-    AITNE["Aitne daemon"]
-    SVC["Connected apps:<br/>Google Calendar, Outlook Calendar,<br/>Gmail, Outlook, Yahoo, iCloud,<br/>Notion, Obsidian, GitHub,<br/>local Git, Google Maps,<br/>custom MCP servers"]
-    OUT["Output surfaces:<br/>same DM channel,<br/>today.md updates,<br/>calendar actions,<br/>drafted emails,<br/>proactive notifications"]
-
-    IN --> AITNE
-    AITNE --- SVC
-    AITNE --> OUT
-```
+A pre-pass `routine.fetch_window` session runs before each routine, fanning out per-account fetches (mail, calendar, Notion) into the `observations` table so the main session reads from a single source.
 
 ---
 
-## CLI reference
+## CLI
 
 ### Lifecycle
 
 | Command | What it does |
 |---|---|
-| `aitne start [--no-open]` | Build if stale, launch daemon + dashboard in background. Opens browser unless `--no-open`. |
-| `aitne stop` | Graceful shutdown (SIGTERM → SIGKILL after 10 s). |
-| `aitne restart [--no-open] [--clean-context]` | Stop then start. `--clean-context` wipes `context/` after a tarball backup. |
-| `aitne status` | PIDs, uptime, connected platforms, backends, today's spend, last action, next scheduled item. |
-| `aitne logs [-f] [-n N] [-d]` | Tail the daemon log. `-d` = dashboard log. `-f` = follow. `-n N` = last N lines. |
-| `aitne dev` | Foreground mode (full stdio, useful for debugging). |
-| `aitne build` | Force a build (skip the mtime gate). |
+| `aitne start [--no-open]` | Build if stale, launch daemon + dashboard in background |
+| `aitne stop` | Graceful shutdown (SIGTERM → SIGKILL after 10 s) |
+| `aitne restart [--clean-context]` | Stop then start. `--clean-context` wipes `context/` after a tarball backup |
+| `aitne status` | PIDs, uptime, platforms, backends, today's spend |
+| `aitne logs [-f] [-n N] [-d]` | Tail daemon log (`-d` = dashboard log, `-f` = follow) |
+| `aitne dev` | Foreground mode (full stdio) |
 
 ### Operations
 
 | Command | What it does |
 |---|---|
-| `aitne setup` | Re-open the dashboard `/setup` wizard. Auto-starts the daemon if needed. |
-| `aitne open` | Open the dashboard in your browser. |
-| `aitne doctor [--json]` | 8 base install checks; the repository-drift check expands into one extra row per drifted repo. |
-| `aitne audit [flags]` | Read the agent action log directly from SQLite. |
-| `aitne version [--json]` | Version, Node, install path, last build time. |
-| `aitne update [--check]` | Print the npm command to upgrade. `--check` makes one network call. |
-| `aitne uninstall [--keep-data\|--wipe-data]` | Stop the daemon and offer to wipe `~/.personal-agent`. |
-| `aitne help [cmd]` | Help (or per-command help). |
-
-### `aitne audit` flags
-
-| Flag | Default | Description |
-|---|---|---|
-| `--since <duration>` | `24h` | Time window (`1h`, `7d`, `2026-04-20`). |
-| `--type <pattern>` | — | `action_type` filter (`%` for LIKE matching). |
-| `--result <value>` | — | `success` / `failed` / `partial` / `skipped`. |
-| `--backend <name>` | — | `claude` / `codex` / `gemini`. |
-| `--limit <N>` | 50 | Row cap. |
-| `--detail` | off | Expand the `detail` JSON column. |
-| `--json` | off | Machine-readable output. |
-
-### `aitne doctor` checks
-
-1. Node version ≥ 22.0.0
-2. Daemon port (`PA_API_PORT`, default 8321) is bindable
-3. Dashboard port (`PA_DASHBOARD_PORT`, default 3000) is bindable
-4. OS secret store usable (`security` / `secret-tool` / `PA_MASTER_PASSWORD`)
-5. At least one backend CLI (`claude`, `codex`, or `gemini`) responds
-6. `~/.personal-agent` exists and is writable
-7. `better-sqlite3` native binding loads
-8. `agent-assets/skills/` is reachable
-9. Repository drift — one row per paired-local + GitHub repo whose `origin` no longer matches the registered `<owner>/<repo>`
-
----
-
-## Architecture
-
-```mermaid
-flowchart TB
-    PLAT["Input platforms:<br/>Slack, Telegram, Discord,<br/>WhatsApp, Web dashboard"]
-
-    subgraph DAEMON["Aitne daemon (Hono on :8321)"]
-        direction TB
-        EB["EventBus<br/>(priority heap)"]
-        DI["Dispatcher<br/>(2 reactive + 3 autonomous semaphores)"]
-        BR["BackendRouter<br/>ProcessKey to tier and backend<br/>plus fallback"]
-        AC["Agent Core<br/>(IAgentCore interface)"]
-        OB["Observers:<br/>Git, GitHub, Obsidian,<br/>Notion, Calendar, Mail"]
-        SC["Scheduler<br/>(node-cron + agent_schedule)"]
-    end
-
-    BACKENDS["AI runtimes:<br/>Claude Code SDK,<br/>Codex CLI subprocess,<br/>Gemini CLI subprocess"]
-
-    DATA["Local data:<br/>SQLite (WAL + FTS5),<br/>Markdown memory,<br/>OS Keychain"]
-
-    PLAT --> EB
-    SC --> EB
-    OB --> DATA
-    DATA --> EB
-    EB --> DI
-    DI --> BR
-    BR --> AC
-    AC --> BACKENDS
-    AC --> DATA
-```
-
-### Two execution paths
-
-**Reactive path** — owner DMs / mentions, cron routines, calendar approach events, scheduled tasks
-→ Event source → EventBus → Dispatcher → BackendRouter → Agent → output to user.
-
-**Polling path** — Obsidian, Git, GitHub, Notion, Calendar, Mail change detection
-→ Observer → `observations` table (UPSERT, with `actor='user'|'agent'`)
-… time passes …
-→ Hourly cron → Stage 2 lite-tier triage → Stage 3 full `routine.hourly_check` (if escalated) → agent reads pending → updates `today.md` / `roadmap.md` → notifies if needed.
+| `aitne doctor [--json]` | 10 install-health checks + repo-drift expansion |
+| `aitne audit [flags]` | Read the agent action log from SQLite — `--since`, `--type`, `--result`, `--backend`, `--detail`, `--json` |
+| `aitne setup` | Re-open the dashboard `/setup` wizard |
+| `aitne open` | Open the dashboard in your browser |
+| `aitne run-now <job>` | Fire a maintenance job on demand (currently `roadmap_maintenance`) |
+| `aitne verify <target>` | Read-only post-launch verification of a shipped design surface |
+| `aitne version` / `update` / `uninstall` | Self-explanatory |
 
-`AgentWriteTracker` prevents agent → observer → agent loops by tagging the agent's own writes so the hourly check filters them out. A pre-pass `routine.fetch_window` session fans out per-account fetches into the `observations` table before each routine runs.
-
-### Repo layout
-
-```
-packages/
-├── daemon/      # Hono server, EventBus, Dispatcher, BackendRouter, observers, SQLite layer, integration SDK wrappers
-├── dashboard/   # Next.js 16 + React 19 + Tailwind 4 + shadcn/ui
-└── shared/      # Types, Zod schemas, ProcessKey enum, branding constants
-
-agent-assets/    # Read by the daemon at session-init time
-├── agent-profiles/  # Persona MD per backend (CLAUDE.md / AGENTS.md / GEMINI.md)
-├── skills/          # 24 built-in skills (context, calendar, mail, notion, …)
-├── task-flows/      # Per-event prompt templates
-└── templates/       # Scaffold MD copied to context/ on first run
-
-bin/aitne.mjs    # CLI entry — lifecycle + ops
-scripts/         # Build/run helpers and per-command modules
-docs/design/     # Architecture and design docs — source of truth
-```
+`aitne help [cmd]` for per-command details.
 
 ---
 
-## Memory layout
-
-Everything the agent writes lives under `PA_DATA_DIR` (default `~/.personal-agent`):
-
-```
-~/.personal-agent/
-├── context/                    # Markdown memory — edit any file by hand at any time
-│   ├── _index.md              # Navigation hub
-│   ├── today.md               # Today's working view (always injected)
-│   ├── yesterday.md           # Daemon-rotated archive
-│   ├── roadmap.md             # Long-term goals (Morning + Evening injection)
-│   ├── context-index.md       # Auto-maintained index
-│   ├── user/
-│   │   ├── profile.md         # ~600 tokens, always injected
-│   │   ├── people.md          # Relationship dictionary
-│   │   ├── work.md, expertise.md, personal.md, goals.md
-│   ├── rules/                 # Policy files (management, redaction, journal)
-│   ├── routines/              # Per-cadence checklist rulebooks
-│   ├── dossiers/              # Carry-forward state per routine
-│   ├── projects/              # One file per active project + Obsidian Bases view
-│   ├── daily/YYYY-MM-DD.md    # Synthesized daily journal (persistent by design)
-│   ├── weekly/YYYY-Www.md     # Weekly review (1 yr file retention)
-│   ├── monthly/YYYY-MM.md     # Monthly review (persistent by design)
-│   ├── inbox/                 # Optional paste bucket
-│   └── agent/
-│       ├── journal.md         # Private agent self-reflection
-│       └── scratch/           # 48-h TTL temp files
-├── data/personal_agent.db     # SQLite (WAL + FTS5)
-├── logs/{daemon,dashboard}.log
-├── prompts/                   # Editable prompt templates
-├── attachments/               # Chat attachments
-├── agent-sessions/[id]/       # Per-session backend workdir
-├── secrets/                   # File-fallback secret store (empty when OS keychain is used)
-└── run/                       # PID files for daemon + dashboard
-```
-
-### Write chokepoint
+## Backends
 
-Context-MD writes go through `curl http://localhost:8321/api/context/<path>` rather than the SDK's `Edit`/`Write` tools on those paths. This is enforced by **skill instructions** (the bundled skills only ever invoke the daemon API) plus the **absolute-block path globs** that hard-deny SDK writes to secret paths (`.env`, `~/.ssh`, `~/.aws`, `~/.gnupg`, `~/.personal-agent/secrets/**`, …). Routing context writes through the daemon API gives one chokepoint for locks (`today.md` write lock), frontmatter validation, and snapshots (30-day `md_file_snapshots` retention).
+Aitne abstracts four AI runtimes behind a single `IAgentCore` interface. Every kind of work has a `ProcessKey` mapped to a tier (`lite` / `medium` / `high`) and a backend; for Claude those tiers map to **Haiku 4.5 / Sonnet 4.6 / Opus 4.7**.
 
----
-
-## Multi-backend
-
-Aitne abstracts three AI runtimes behind a single `IAgentCore` interface:
-
-| Backend | Implementation | Session resume | Strengths |
+| Backend | Implementation | Resume | Strengths |
 |---|---|---|---|
-| **Claude Code** | `@anthropic-ai/claude-agent-sdk` | Yes (SDK `resume` option) | Best for routines, deep context, server-side advisor |
-| **Codex CLI** | OpenAI Codex CLI subprocess + JSONL stream | Yes (`--resume <session-id>`) | Best for code-heavy tasks, fast iteration |
-| **Gemini CLI** | Google Gemini CLI subprocess + JSONL stream | Yes (`--resume <session-id>`) | Best for free-tier headroom, large-context summarization |
+| **Claude Code** | `@anthropic-ai/claude-agent-sdk` | ✓ | Best for routines, deep context, server-side advisor |
+| **Codex CLI** | OpenAI Codex CLI subprocess + JSONL stream | ✓ | Code-heavy tasks, fast iteration |
+| **Gemini CLI** | Google Gemini CLI subprocess + JSONL stream | ✓ | Free-tier headroom, large-context summarization |
+| **OpenCode** _(coming soon)_ | `opencode-ai` HTTP server + SDK client | ✓ | Multi-provider — routes to any `opencode auth login` provider. Preview-only in this release; the dashboard selectors are disabled until the runtime executor ships. |
 
-### Per-process tier routing
+The router fails over to a configured fallback backend automatically on `BackendQuotaError` or decisive failure, re-materializing the fallback's instruction file and skill directories into the session workdir.
 
-Every kind of work has a `ProcessKey` mapped to a tier (`lite` / `medium` / `high`) and a backend. For Claude, those tiers map to Haiku 4.5 / Sonnet 4.6 / Opus 4.7.
-
-| ProcessKey | Default tier | What runs there |
-|---|---|---|
-| `routine.morning_routine_initial` | **high** | First-day plan generation (one-shot, sets up profile) |
-| `routine.morning_routine` | medium | Daily plan generation — the highest-value recurring process |
-| `routine.evening_review` | medium | Today wrap-up |
-| `routine.weekly_review`, `routine.monthly_review` | medium | Cadence summaries |
-| `routine.hourly_check` | medium | Stage 3 observation aggregation |
-| `routine.hourly_check.triage` | lite | Stage 2 escalate-vs-log-only gate |
-| `routine.fetch_window` | lite | Pre-pass fan-out fetcher for routines |
-| `message.dm`, `message.mention` | medium | DM and channel response |
-| `dashboard.chat` | medium | Web chat |
-| `dashboard.docs_qa` | medium (tier-locked) | Docs panel — never burns Opus quota |
-| `agent.task`, `agent.dm_task` | medium | Scheduled wakeups |
-| `knowledge.import` | high | One-shot knowledge ingestion |
-| `calendar.change`, `gmail_classify` | lite | Polling-derived events |
-| `git.*`, `github.*` (event triage) | lite | Git/GitHub event triage |
-| `delegated_task` | lite | Delegated subprocess task mode |
-| `delegated_task_heavy` | high | Opt-in destructive-write task mode |
-| `observation.summarize` | lite | Per-observation classification |
-| `wiki.ingest_url`, `wiki.compile`, `wiki.ask`, `wiki.lint`, `wiki.trace`, `wiki.connect` | medium | Personal wiki surfaces |
-
-Configure each ProcessKey's backend and tier from the dashboard `/settings/models` page. The router fails over to a fallback backend automatically on `BackendQuotaError` or `BackendDecisiveFailure`, re-materializing the fallback's instruction file + skill directories into the session workdir.
+Per-process tier defaults and the routing table are editable from the dashboard at `:3000/settings/models`.
 
 ---
 
 ## Integrations
 
-### Messaging
-
-| Platform | Library | Mode | Setup |
-|---|---|---|---|
-| Slack | `@slack/bolt` | Socket Mode (WebSocket) | Bot + App tokens |
-| Telegram | `telegraf` | Long polling | Bot token |
-| Discord | `discord.js` | Gateway | Bot token |
-| WhatsApp | `@whiskeysockets/baileys` | QR pairing | Scan QR from dashboard |
-| Web Dashboard | Hono SSE | Always on | None |
-
-### Mail (multi-provider, unified API)
-
-| Provider | Auth | Features |
-|---|---|---|
-| **Gmail** | `googleapis` OAuth2 | Read · send · drafts · labels · IMAP IDLE · classifier · attachment extraction |
-| **Outlook** | `@azure/msal-node` Graph API | Read · send · drafts · folders |
-| **Yahoo** | IMAP + app password | Read · send · IMAP IDLE |
-| **iCloud** | IMAP + app password | Read · send · IMAP IDLE |
-
-Local FTS5 full-text search runs across every account via `GET /api/mail/search?q=...`. The classifier (`mail-classifier`) tags messages across all providers; the Gmail-specific classifier auto-applies labels.
-
-### Knowledge and docs
-
-- **Obsidian** — read directly via `Read`; write via the official Obsidian CLI (`obsidian create`, `obsidian append`, `obsidian daily:append`, …); `chokidar` watches the vault for user edits
-- **Notion** — `@notionhq/client` REST API; full page + database CRUD
-- **Wiki builder** — per-workspace ingest / compile / ask / lint / trace / connect surface backed by `packages/daemon/src/core/wiki/` (cost-gated full rebuilds, approval queue, compile preview, optional git pre-compile snapshot, dispatch-mode fan-out). One internal workspace or any number of external Obsidian vaults; addressed with `@<workspace>` on every bang command.
-- **Custom MCP servers** — register via `/api/mcp/servers`; materialized into the per-session workdir so backends use them transparently
-
-### Code
-
-- **Git** (local) — daemon proxies `git log`, `git diff`, `git show`; cron-driven repository observer; `automation_triggers` table fires LLM prompts on `cron.daily` / `cron.weekly`
-- **GitHub** — `@octokit/rest` + webhooks; PR list and comment, issue ops, HMAC-SHA256 signature verification at `POST /webhook/github`
-
-### Calendar and travel
-
-- **Google Calendar** — `googleapis` OAuth2; full event CRUD, freebusy, calendar list, 15-min approaching reminders
-- **Outlook Calendar** — Microsoft Graph via `@azure/msal-node` in direct mode, or user-managed MCP in delegated / native modes
-- **iCloud Calendar** — CalDAV via `tsdav`
-- **Google Maps** — Directions API for travel-time estimation tied to calendar events
-
-### Lifestyle
-
-- **Receipts** — auto-extracts PDF / image attachments from mail with category detection
-- **Travel bookings** — auto-extracts flight, hotel, restaurant, train confirmations
-- **Reading** — Kindle My Clippings importer; reading-taste profile; weekly book recommendations
-- **Voice** — opt-in Whisper transcription (`ffmpeg-static` + `@huggingface/transformers`) runs locally on voice attachments. Install via `POST /api/voice/install`.
-
-### Integration delegation modes
+| Category | Providers |
+|---|---|
+| **Messaging** | Slack (Socket Mode), Telegram, Discord, WhatsApp (Baileys), Web dashboard |
+| **Mail** | Gmail, Outlook, Yahoo, iCloud — unified API, classifier, local FTS5 search, IMAP IDLE |
+| **Calendar** | Google Calendar, Outlook Calendar, iCloud (CalDAV), Google Maps for travel time |
+| **Knowledge** | Obsidian (CLI + vault watch), Notion (REST), custom MCP servers |
+| **Code** | Local Git, GitHub (Octokit + webhooks) |
+| **Lifestyle** | Auto-extracted receipts · travel bookings · Kindle highlights · voice transcription (Whisper, opt-in) |
 
-Each integration runs in one of **four** modes:
+### Integration modes
 
-| Mode | Auth held by | Polling? | Setup cost | Capabilities |
-|---|---|---|---|---|
-| **`direct`** | Daemon (OAuth in OS Keychain) | Daemon poller | 5–6 vendor-console steps | Full feature set |
-| **`delegated`** | Main backend's connector | Cron `delegated-sync-worker` (per-cadence opt-in) | None — backend already authed | Reduced (whatever the connector exposes) |
-| **`native`** | Main backend's connector | None — agent reaches the integration in-turn via MCP | None | On-demand only; observations posted via `/api/observations` |
-| **`disabled`** | — | No | — | Off |
+Each integration runs in one of four modes:
 
-`delegated` runs the backend's connector on a cron cadence (default-off, opt-in per cadence). `native` skips polling entirely and routes calls in-band during DMs / hourly checks. Outlook Mail and Outlook Calendar are user-managed-connector native: install the MCP yourself, Aitne synthesises a probe pass.
+| Mode | Auth held by | Polling? | Capabilities |
+|---|---|---|---|
+| **`direct`** | Daemon (OAuth in OS Keychain) | Daemon poller | Full feature set |
+| **`delegated`** | Main backend's connector | Cron worker (per-cadence opt-in) | Whatever the connector exposes |
+| **`native`** | Main backend's connector | None — reached in-turn via MCP | On-demand only |
+| **`disabled`** | — | — | Off |
 
-Every mode change goes through `POST /api/integrations/:key/probe` and the per-key flip lock — a live capability check is mandatory before flipping to `delegated` or `native`.
+Every mode change goes through a live capability probe and a per-key flip lock.
 
 ---
 
-## Safety model
+## Memory
 
-Aitne stacks **four** independent safety layers. The bottom layer holds even when the upper layers are widened by the user.
+Everything Aitne writes lives in `~/.personal-agent/context/*.md` — plain Markdown you can `cat`, `vim`, `obsidian`, or `cp`:
 
-### Layer 1 — SDK permission model
-
-```typescript
-// Safe (strict) mode — claude-tool-collection.ts:CLAUDE_DEFAULT_ALLOWED_TOOLS
-permissionMode: "dontAsk"
-allowedTools:    ["Read", "Glob", "Grep", "Write", "Edit", "Skill",
-                  "Bash(curl *)", "Bash(git *)", "Bash(jq *)"]
-disallowedTools: ALWAYS_DISALLOWED_TOOLS + dashboard overrides
+```
+context/
+├── today.md             # Working view, always injected
+├── yesterday.md         # Daemon-rotated archive
+├── roadmap.md           # Long-term goals
+├── user/                # profile.md, people.md, work.md, …
+├── rules/               # Policy files (management, redaction)
+├── projects/            # One file per active project
+├── daily/YYYY-MM-DD.md  # Synthesized daily journal
+├── weekly/              # Weekly retrospectives
+└── agent/journal.md     # Private agent self-reflection
 ```
 
-Allow mode swaps to `permissionMode: "bypassPermissions"` but the absolute-block layer below still applies.
-
-### Layer 2 — PreToolUse hooks (Claude, Safe mode)
-
-In Safe mode, every `Bash(curl ...)` invocation is parsed: the hostname must be `localhost` or `127.0.0.1` and the port must match the daemon's `apiPort`. Connection-override flags (`--connect-to`, `--resolve`, `--proxy`, `-x`, `--socks`, `-K`) are also rejected. A parallel `jq` hook blocks `--rawfile` / env-leak filters. In Allow mode the curl/jq pair is skipped, but the absolute-block hook (below) and the context-write attribution hook still run. Vault writes are attributed to the agent via `AgentWriteTracker` so they don't loop back as observations.
-
-### Layer 3 — Daemon API risk tiers
-
-| Tier | Examples | Auth required |
-|---|---|---|
-| **Autonomous** | `GET /api/context/*`, `POST /api/notify`, `POST /api/schedule`, `POST /api/observations` | None (localhost only) |
-| **ReadSensitive** | `GET /api/observations`, `GET /api/calendar/events`, `GET /api/mail/search` | `X-Read-Token` or Bearer |
-| **Approve** | `PATCH /api/config`, `POST /api/setup/*`, `POST /api/system/factory-reset`, `POST /api/triggers`, `/api/repositories`, `/api/mcp/servers`, `/api/integrations` | Bearer |
-
-### Layer 4 — Absolute-block layer (`ALWAYS_DISALLOWED_TOOLS`)
+Context writes flow through `curl http://localhost:8321/api/context/<path>`, not the SDK's `Edit`/`Write` tools — this gives the daemon a single chokepoint for write locks, frontmatter validation, and 30-day snapshots. SQLite (`better-sqlite3` with FTS5) backs sessions, observations, agent actions, and history.
 
-Hard-blocked in **both Safe and Allow** modes. `bypassPermissions` and `allowedToolsOverride` cannot widen past this:
+---
 
-- Recursive delete: `rm -rf *`, `rm -r *`, `rm --recursive*`, plus every common short-flag bundle (`-rfv`, `-fr`, `-vr`, `-R`, `-fR`, …)
-- Privilege escalation: `sudo *`, `doas *`, `su *`
-- Pipe-to-shell RCE: `curl * | sh`, `wget * | bash`, `bash <(...)`, `sh <(...)`, no-space `bash<...` / `sh<...`
-- Indirect-eval RCE: `eval *`, `source *` (no Aitne skill or task flow uses these)
-- Platform secret CLI: `security *` (macOS), `secret-tool *` (Linux), `cmdkey *` (Windows)
-- Secret file reads and writes: `.env`, `**/.env`, `id_rsa*`, `id_ed25519*`, `~/.ssh/**`, `~/.gnupg/**`, `~/.aws/**`, `~/.config/gcloud/**`, `~/.config/gh/hosts.yml`, `~/.netrc`, `~/Library/Keychains/**`, `~/.local/share/keyrings/**`
-- Daemon-managed secret surfaces: `~/.personal-agent/secrets/**`, `~/.personal-agent/whatsapp/auth/**`, `~/.personal-agent/backups/**`
-- Anthropic-cloud managed-agent tools: `CronCreate`, `CronList`, `CronDelete`, `RemoteTrigger`, `PushNotification` (would bypass the local audit log, MD memory, and cost telemetry)
+## Safety
 
-Every blocked attempt lands in `agent_actions` with `action_type='blocked_absolute'`.
+Four independent layers, designed so that the bottom layer holds even when upper layers are widened:
 
-### Other guarantees
+1. **SDK permission model** — strict `allowedTools` whitelist in Safe mode; `bypassPermissions` in Allow mode
+2. **PreToolUse hooks** (Claude, Safe mode) — `curl` parsed for hostname + port; daemon-API is the only legal write path
+3. **Daemon API risk tiers** — `Autonomous` / `ReadSensitive` (X-Read-Token) / `Approve` (Bearer token)
+4. **Absolute-block layer** — recursive deletes, `sudo`, pipe-to-shell, secret-file reads/writes, Anthropic-cloud managed-agent tools — hard-denied in **both** modes regardless of overrides
 
-- **Localhost-only API** — daemon binds to `127.0.0.1` only
-- **Bearer token** — required for all Approve-tier endpoints
-- **Webhook HMAC** — GitHub webhooks verified with `X-Hub-Signature-256`
-- **No automated financial transactions** — never trade, transfer, or pay
-- **No automated social posting** — never post publicly on your behalf
-- **Single-owner only** — group chats and multi-user channels are filtered at the adapter layer
-- **Auth Health Monitor** — hourly probe of every backend's auth state, with grace periods, escalating DMs, and auto-recovery flows for Claude / Codex / Gemini
+Plus: localhost-only API, webhook HMAC verification, no automated financial transactions, no automated social posting, single-owner adapter filtering, hourly auth-health monitoring with auto-recovery.
 
 ---
 
-## Cost and quotas
-
-### Built-in controls
+## Cost
 
-| Control | Default | Configurable |
+| Control | Default | Effect when set |
 |---|---|---|
-| `maxConcurrentSessions` (autonomous) | 3 | yes |
-| `maxReactiveSessions` (DMs) | 2 | yes |
-| `executeTimeoutMinutes` (per-execute watchdog) | 60 | yes |
-| `autonomousDailyCostCapUsd` | null (alert-only) | yes |
-| `autonomousMonthlyCostCapUsd` | null (alert-only) | yes |
-| Per-ProcessKey `maxBudgetUsd` (in `process_backend_config`) | per-row, set from `/settings/models` | yes |
-| `delegated_task` hard caps | `maxToolCalls=15` · `maxBudgetUsd=$0.50` · `timeoutMs=300_000` | no (compile-time) |
+| `maxConcurrentSessions` (autonomous) | 3 | Hard semaphore |
+| `maxReactiveSessions` (DMs) | 2 | Hard semaphore |
+| `executeTimeoutMinutes` | 60 | Per-execute watchdog |
+| `autonomousDailyCostCapUsd` | `null` | Priority-based skipping: `hourly_check` at 100%, `evening_review` at 150%, `morning_routine` at 200%. Reactive DMs are not gated. |
+| `autonomousMonthlyCostCapUsd` | `null` | Alert + warn surface |
+| Per-ProcessKey `maxBudgetUsd` | per-row | Hard cap per execute |
 
-### Typical day's spend
-
-```
-04:00  Morning Routine  (Sonnet)            ~$0.15
-07:00  Morning Briefing (Sonnet)            ~$0.03
-09:00  Hourly Check     (Sonnet)            ~$0.05
-12:00  Hourly Check     (Sonnet)            ~$0.03
-12:55  DM response      (Sonnet)            ~$0.08
-18:00  Evening Review   (Sonnet)            ~$0.15
-─────────────────────────────────────────────────
-Total                                       ~$0.49
-```
-
-If you're on a Claude / Codex / Gemini subscription, none of this hits a metered API key — it consumes your subscription quota directly. Quota exhaustion is detected, dedupe-notified once per 2-hour window, and the next hourly tick retries automatically.
+Typical day for an active user: **~$0.50** (Morning routine + briefing + 2× hourly check + 1 DM + Evening review, all on Sonnet 4.6). Quota exhaustion is detected, dedupe-notified once per 2-hour window, and retried on the next tick.
 
 ---
 
 ## Configuration
 
-`.env` is **bootstrap-only**. Everything else is editable from the dashboard at runtime — or via natural-language DMs.
-
-### `.env` (bootstrap)
-
-```bash
-PA_DATA_DIR=~/.personal-agent
-PA_API_PORT=8321
-PA_DASHBOARD_PORT=3000
-PA_LOG_LEVEL=info                 # trace | debug | info | warn | error
-```
-
-### Pre-seeding identifiers via env (optional)
-
-Bot tokens and OAuth credentials always live in the OS keychain — they are never read from environment variables. The wizard's Messaging step (or `/connections/*`) is the single entry point. The few non-secret identifiers you can pre-seed for fully scripted installs:
-
-```bash
-PA_SLACK_OWNER_USER_ID=U...
-PA_TELEGRAM_OWNER_CHAT_ID=...
-PA_DISCORD_OWNER_USER_ID=...
-PA_WHATSAPP_ENABLED=true
-PA_WHATSAPP_OWNER_PHONE=...
-
-PA_PRIMARY_VAULT_PATH=~/Documents/MyVault
-PA_EXTERNAL_OBSIDIAN_VAULT_PATH=~/Documents/SecondaryVault
-
-PA_NOTION_DATABASE_IDS='{"tasks":"abc...","notes":"def..."}'
-```
-
-Everything else — bot tokens, OAuth refresh tokens, Notion API key, GitHub token, Google Maps key, Apple Calendar credentials — is set from the dashboard `/connections` page (or via the setup wizard) and lives in the keychain.
+`.env` is **bootstrap-only** (`PA_DATA_DIR`, `PA_API_PORT`, `PA_DASHBOARD_PORT`, `PA_LOG_LEVEL`). Everything else — ~100 runtime keys covering schedule, notifications, models, character, mail, voice, delegated mode — is editable from the dashboard at `:3000`, or via natural-language DMs to the agent.
 
-### Runtime settings
-
-The dashboard `/settings` tree exposes ~100 runtime keys. Headline groups:
-
-- **Schedule** — `timezone`, `dayBoundaryHour`, hourly check window and interval, cron schedules
-- **Notifications** — `quietHoursStart/End`, `maxNotificationsPerHour`, `maxNotificationsPerDay`, `batchIntervalMinutes`
-- **Sessions** — `sessionTimeoutDmMinutes`, `historyInjectionMaxMessages`, `historyInjectionMaxTokens`
-- **Safety** — execution mode per backend, `disallowedTools` overrides
-- **Models** — per-ProcessKey backend + tier, advisor on/off, advisor model
-- **Cost** — daily / monthly soft caps with 80% and 100% alerts
-- **Mail** — provider list, poll interval, IMAP IDLE on/off
-- **Character** — 1,000-char free-form tone description
-- **Language** — `primaryLanguage` nudges output language for DMs, knowledge, and vault writes
-- **Voice** — `voiceTranscriptionEnabled`, `voiceTranscriptionPrimaryLanguage` (the model itself is set via `PA_VOICE_TRANSCRIPTION_MODEL` env-only)
-- **Delegated task mode** — kill switch, per-day quota, heavy-tier opt-in, cache / pool / structured-output toggles
-
-…or just DM the agent: *"Don't run hourly checks on weekends."*
+Bot tokens and OAuth credentials always live in the OS keychain, never in environment variables.
 
 ---
 
 ## Platform support
 
-| Concern | macOS | Linux | Windows |
+| | macOS | Linux | Windows |
 |---|---|---|---|
-| **Secret storage** | Keychain (`security`) | `secret-tool` (libsecret) → AES file fallback | DPAPI via `powershell.exe` → AES file fallback |
-| **Folder picker** | `osascript` | `zenity` / `kdialog` / `yad` | `System.Windows.Forms.FolderBrowserDialog` |
+| **Secret storage** | Keychain | `secret-tool` (libsecret) → AES file fallback | DPAPI → AES file fallback |
+| **Folder picker** | `osascript` | `zenity` / `kdialog` / `yad` | `FolderBrowserDialog` |
 | **Process tree kill** | POSIX process group | POSIX process group | `taskkill /T /F` |
-| **Log tailing (`-f`)** | Built-in Node tailer | Built-in Node tailer | Built-in Node tailer (no `tail` binary needed) |
-| **Console windows** | n/a | n/a | Background spawns hide the console window |
 
-### WSL
+WSL falls back to the encrypted file store — set `PA_MASTER_PASSWORD` to a long random string. Windows users hitting `ENAMETOOLONG` on install should enable long paths via `LongPathsEnabled=1` registry key.
 
-GNOME Keyring / D-Bus are typically unavailable. Aitne falls back to the encrypted file store. Set:
-
-```bash
-export PA_MASTER_PASSWORD='use-a-long-random-string'
-```
-
-### Linux secret-tool
-
-```bash
-sudo apt-get install libsecret-tools     # Debian / Ubuntu
-sudo dnf install libsecret               # Fedora
-sudo pacman -S libsecret                 # Arch
-```
-
-### Windows long paths
-
-If `npm install` fails with `ENAMETOOLONG`, run from elevated PowerShell and reboot:
-
-```powershell
-Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
-                 -Name "LongPathsEnabled" -Value 1
-```
+Common gotchas: [docs/troubleshooting.md](docs/troubleshooting.md)
 
 ---
 
-## Troubleshooting
-
-### `aitne start` says "dist not found"
-
-The build did not complete. Run `aitne build` and check for TypeScript errors.
-
-### Port already in use
-
-Change `PA_API_PORT` (or `PA_DASHBOARD_PORT`) in `.env`. To find the conflicting process:
-
-```bash
-# macOS / Linux
-lsof -i :8321
-
-# Windows
-netstat -ano | findstr :8321
-```
-
-### `aitne` not found after `npm install -g`
-
-```bash
-npm config get prefix
-# add the printed prefix's `bin/` (or its root on Windows) to your PATH
-```
+## Documentation
 
-### SQLite errors on startup
-
-The DB can be reset safely — your Markdown memory in `context/` is untouched. The `*` clears the WAL + SHM companion files:
+| Topic | Doc |
+|---|---|
+| Documentation index | [docs/index.md](docs/index.md) |
+| Setup walkthrough | [docs/setup-guide.md](docs/setup-guide.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Maintenance playbook | [docs/maintenance.md](docs/maintenance.md) |
+| Advisor model | [docs/advisor.md](docs/advisor.md) |
 
-```bash
-aitne stop
-rm ~/.personal-agent/data/personal_agent.db*
-# Remove-Item "$env:USERPROFILE\.personal-agent\data\personal_agent.db*"  # Windows
-aitne start
-```
+---
 
-### Backend auth expired
+## Tech stack
 
-```bash
-aitne doctor                           # confirms which backend failed
-claude auth login                      # re-auth Claude
-codex login --device-auth              # re-auth Codex
-# Gemini re-auth happens automatically via the dashboard banner
-```
+Daemon: Node.js 22 · Hono · `@anthropic-ai/claude-agent-sdk` · `@slack/bolt` · `telegraf` · `discord.js` · `@whiskeysockets/baileys` · `googleapis` · `@azure/msal-node` · `@notionhq/client` · `@octokit/rest` · `tsdav` · `chokidar` · `node-cron` · `better-sqlite3` (FTS5) · `pino` · `zod`
 
-### Diagnostic dump
+Dashboard: Next.js 16 · React 19 · Tailwind 4 · shadcn/ui · TanStack Query · Recharts · Monaco
 
-```bash
-aitne audit --since 24h --result failed --detail
-```
+Monorepo: pnpm 10 workspaces · Turborepo · TypeScript 5.8 · Vitest 3 (100% coverage gate on a curated pure-logic subset)
 
 ---
 
-## Development
-
-### Tech stack
-
-| Layer | Stack |
-|---|---|
-| **Daemon** | Node.js 22 · Hono · `@anthropic-ai/claude-agent-sdk` · `@slack/bolt` · `telegraf` · `discord.js` · `@whiskeysockets/baileys` · `googleapis` · `@azure/msal-node` · `@notionhq/client` · `@octokit/rest` · `tsdav` · `chokidar` · `node-cron` · `heap-js` · `pino` · `zod` |
-| **Storage** | `better-sqlite3` (WAL + FTS5 trigram) · OS Keychain · plain Markdown |
-| **Dashboard** | Next.js 16 (App Router) · React 19 · Tailwind CSS 4 · shadcn/ui · TanStack Query · Recharts · Monaco Editor |
-| **Voice** | `ffmpeg-static` · `@huggingface/transformers` (Whisper, opt-in) |
-| **Monorepo** | pnpm 10.x workspaces · Turborepo · TypeScript 5.8 · Vitest 3 |
+## Contributing
 
-### Conventions
+Issues and PRs welcome. Conventions:
 
 - All code, comments, tests, and user-facing text are in **English**
 - TypeScript throughout, camelCase, ESM with `.js` import extensions
 - Tests colocated with source as `foo.ts` + `foo.test.ts`
-- Vitest enforces **100% coverage** on a curated subset of pure-logic modules
-- The `docs/design/` tree is the authoritative spec; `packages/daemon/src/` is the source of truth when they diverge
-
-### Source-of-truth pointers
-
-| If you need to… | Start in |
-|---|---|
-| Understand startup order | `packages/daemon/src/index.ts` |
-| Change event routing | `src/core/dispatcher.ts` + `src/core/event-bus.ts` |
-| Add a backend or change tier mapping | `packages/shared/src/process-key.ts` + `src/core/backends/backend-router.ts` |
-| Add an API route | `src/api/routes/` + register in `src/api/server.ts` |
-| Add an integration | `packages/shared/src/integrations.ts` (registry) + `src/services/<name>/` + optional `src/observers/` |
-| Edit a built-in skill | `agent-assets/skills/<slug>/SKILL.md` |
-| Edit an event task flow | `agent-assets/task-flows/<eventType>.md` |
-| Change risk classification | `src/safety/risk-classifier.ts` |
-| Change the absolute-block layer | `src/safety/always-disallowed.ts` |
-| Change auth health / recovery | `src/core/backends/auth-health-monitor.ts` + `auth-recovery.ts` |
+- `packages/daemon/src/` is the source of truth
 
 ---
 
 ## FAQ
 
-**Is Aitne a chatbot?**
-No. It's a daemon. It also responds to chat, but the more interesting half is what it does while you're not looking at it.
-
-**Does it phone home?**
-No. The daemon binds to `127.0.0.1` only. There is no telemetry. Verify with `lsof` and `nettop`.
-
-**Where do my secrets live?**
-In your OS-native credential store (macOS Keychain / libsecret / DPAPI). Never in `.env`. On systems without a credential store, in an AES-encrypted file under `~/.personal-agent/secrets/`.
-
-**Can I bring my own AI?**
-Yes — Claude Code, OpenAI Codex, and Google Gemini CLI are all supported. Pick one or all three. Per-process tier routing lets you mix-and-match.
-
-**Do I need an API key?**
-No metered API key required — Aitne uses your subscription quota via the official CLIs (`claude auth login`, `codex login`, `gemini`). If you'd rather pay-as-you-go, supply `ANTHROPIC_API_KEY` / `OPENAI_API_KEY` / `GEMINI_API_KEY` in the wizard.
-
-**Can I edit the agent's memory directly?**
-Yes — that's the entire point. Open `~/.personal-agent/context/today.md` in your editor, change anything, save. The agent picks up your edits on the next routine. Any edit is just text in a file — no proprietary format, no migration headaches if you uninstall.
-
-**What about Obsidian?**
-Aitne can use your existing Obsidian vault as the primary memory store. The agent reads vault files directly and writes via the official Obsidian CLI. Your wiki links keep working. Your daily notes get appended to.
+**Is Aitne a chatbot?** No — it's a daemon. It also responds to chat, but the more interesting half is what it does while you're not looking at it.
 
-**Can I run my own MCP servers?**
-Yes. Register them in the dashboard `/connections` page; the daemon writes the per-session MCP config into each backend's session workdir before launching, so all your MCP tools are available transparently.
+**Does it phone home?** No. The daemon binds to `127.0.0.1` only. No telemetry. Verify with `lsof` and `nettop`.
 
-**Do my existing Claude Code / Codex / Gemini settings work?**
-Yes. Aitne reads your `~/.claude/`, `~/.codex/`, `~/.gemini/` configs on session init and layers its persona on top. Custom skills, slash commands, MCP servers, and plugins all carry over. See [Bring your own harness](#bring-your-own-harness).
+**Can I edit memory directly?** Yes. Open `~/.personal-agent/context/today.md`, change anything, save. The agent picks up your edits on the next routine.
 
-**Does it work without internet?**
-The AI backends and reactive messaging need internet (to hit those services). The daemon, dashboard, observers (Git, Obsidian local), and Markdown memory are entirely offline.
+**Do my existing Claude Code / Codex / Gemini settings work?** Yes. Aitne reads `~/.claude/`, `~/.codex/`, and `~/.gemini/` on session init and layers its persona on top. (`~/.opencode/` is recognised but the OpenCode runtime is coming soon.)
 
-**Does it support languages other than English?**
-Yes. Talk to it in your native language — Japanese, German, Spanish, anything. The LLM handles it; the `primaryLanguage` setting nudges DM, knowledge, and vault outputs into that language too. Implementation code remains English-only.
+**Is this for my team?** No — single-owner by design. Group chats and multi-user channels are filtered at the adapter layer.
 
-**Is this for my whole team?**
-No — Aitne is **single-owner by design**. Group chats and multi-user channels are filtered at the adapter layer. If you want a team agent, run one Aitne per teammate.
+**Does it work without internet?** Backends and reactive messaging need internet. The daemon, dashboard, observers, and Markdown memory are entirely offline.
 
-**How do I uninstall?**
-`aitne uninstall`. It will offer to wipe `~/.personal-agent` or keep it for re-installation.
+**How do I uninstall?** `aitne uninstall` — offers to wipe `~/.personal-agent` or keep it for re-installation.
 
 ---
 
 ## License
 
-MIT — use, modify, and distribute freely. See [LICENSE](./LICENSE) for the full text.
-
----
-
-<div align="center">
-
-**Aitne — Always on. Always yours.**
-
-[Issues](https://github.com/Aitne-sh/Aitne/issues) · [Discussions](https://github.com/Aitne-sh/Aitne/discussions) · [npm](https://www.npmjs.com/package/@aitne-sh/aitne)
-
-</div>
+MIT — see [LICENSE](./LICENSE).