@aitne-sh/aitne 0.1.5 → 0.1.7

package/README.md

@@ -4,7 +4,7 @@
 
 ### Always on. Always yours.
 
-**A local-first, proactive personal AI agent that runs continuously on your own machine — and gets smarter about *you* every day.**
+**A local-first, proactive personal AI agent that runs continuously on your own machine — and learns *you* every day.**
 
 [![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)
@@ -21,129 +21,194 @@ aitne start
 
 ---
 
-## The concept
+## Overview
 
-ChatGPT and Claude are *reactive* — they wait for you to type. **Aitne is proactive.** It's a tiny daemon that lives on your laptop, watches your calendar, mail, repos 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 a Markdown journal you actually own.
+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.
 
-```mermaid
-flowchart LR
-    subgraph WORLD["Your digital life"]
-        direction TB
-        W1["💬 Messages"]
-        W2["📅 Calendar"]
-        W3["📧 Mail"]
-        W4["📦 Git"]
-        W5["📓 Notes"]
-    end
+You bring the brain — Claude Code, OpenAI Codex CLI, or Google Gemini CLI. Aitne is the nervous system that schedules, routes, observes, and remembers.
 
-    subgraph LOCAL["💻 Your laptop — Aitne"]
-        direction TB
-        DAEMON["⚙️ Daemon<br/>(always-on)"]
-        BRAIN["🧠 Your AI<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 chat"]
+## What makes Aitne different
 
-    WORLD <--> DAEMON
-    DAEMON <--> YOU
-```
+**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*.
 
-Three things make Aitne different:
+**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.
 
-| | |
-|---|---|
-| 🌱 **It compounds.** | Every day, every DM, every reaction emoji shapes the agent's understanding of *you*. After a month it sounds like you. After a year it knows what you forgot last quarter. |
-| 🗣️ **You manage it in plain language.** | "Don't ping me before 9am." "Remember my partner's birthday." "Stop running hourly checks on weekends." Aitne maps your words to settings, schedules, and profile updates — automatically. |
-| 🔌 **It rides on what you already have.** | Your Claude Code skills, your Codex config, your Gemini settings, your custom MCP servers — Aitne loads them into every session. No re-configuring. No re-buying. |
+**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`.
 
 ---
 
-## A day with Aitne
+## Installation
 
-> A real walkthrough of one user's Tuesday.
+### From npm
 
-**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.
+The recommended path. Installs the `aitne` CLI globally with the daemon, dashboard, and built-in agent assets.
 
-**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.
+```bash
+npm install -g @aitne-sh/aitne@latest
+aitne start
+```
 
-**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. Done.
+Then bring **at least one** AI backend:
 
-**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 `Agent Notes` on `today.md` and DMs once: *"⚠️ Heads up — `auth.ts:84` was just changed by @Yuki. Want me to summarize the diff?"*
+```bash
+# Claude Code — full feature support including server-side advisor
+npm install -g @anthropic-ai/claude-code
+claude auth login
 
-**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`."*
+# OpenAI Codex CLI
+npm install -g @openai/codex
+codex login --device-auth
 
-**15:45 — You forward a hotel confirmation email to Aitne.** It extracts dates, address, 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.
+# Google Gemini CLI
+npm install -g @google/gemini-cli
+# OAuth handled on first use
+```
 
-**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.
+Login once with each CLI you intend to use — Aitne auto-detects them on the next session.
 
-**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?
+### 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:
 
-That's a normal Tuesday. The point isn't any single trick — it's that **all of this happens without you opening an app.**
+```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.
 
 ---
 
-## What you can do with it
+## How it works
 
-A non-exhaustive list. Click any group to expand.
+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.
 
 <details>
-<summary><b>📅 Time, calendar, travel</b></summary>
+<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
-- "Find me a 30-min slot with Sarah and Mark next week" — Aitne checks freebusy across calendars
+- 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
 </details>
 
 <details>
-<summary><b>📧 Mail across all your accounts</b></summary>
+<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) — full filter rules across all providers
+- 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 → auto-extracted to a structured `receipts` table tagged with category, vendor, amount
+- 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/image attachments are extracted and indexed
+- IMAP IDLE for near-real-time delivery; PDF and 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 notes</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 & database CRUD — query, create, update, archive
+- 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 ("this is related to your `agent-architecture.md` from March")
+- 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
+- `!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
 </details>
 
 <details>
-<summary><b>📦 Code, Git, GitHub</b></summary>
+<summary><b>Code, Git, GitHub</b></summary>
 
 - Local Git: `git log`, `git diff`, `git show` exposed via daemon proxy
-- GitHub: PR lists, comments, issues, webhook receivers (HMAC-verified)
+- 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 + traces
+- "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>
+<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
@@ -153,17 +218,17 @@ A non-exhaustive list. Click any group to expand.
 </details>
 
 <details>
-<summary><b>📚 Reading, lifestyle, voice</b></summary>
+<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)
+- 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 & automation</b></summary>
+<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")
@@ -174,9 +239,9 @@ A non-exhaustive list. Click any group to expand.
 </details>
 
 <details>
-<summary><b>🔧 Run your own tools</b></summary>
+<summary><b>Run your own tools</b></summary>
 
-- Bring your own MCP servers — they materialize into every session
+- 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
@@ -184,97 +249,99 @@ A non-exhaustive list. Click any group to expand.
 
 ---
 
-## How Aitne accumulates knowledge about you
+## A day with Aitne
 
-Every signal Aitne sees flows through the same pipeline: capture → short-term → long-term → injected back into every future conversation.
+A walkthrough of one user's Tuesday.
 
-```mermaid
-flowchart TB
-    subgraph SOURCES["📥 Sources"]
-        direction LR
-        S1["💬 messages"]
-        S2["📅 calendar"]
-        S3["📧 mail"]
-        S4["📦 git/github"]
-        S5["📓 obsidian/notion"]
-        S6["✋ you editing<br/>files by hand"]
-    end
+**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.
 
-    OB["⚙️ Observers & adapters<br/>(WebSocket · IDLE · polling)"]
+**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.
 
-    subgraph SHORT["🟡 Short-term memory"]
-        direction LR
-        ST1[("SQLite<br/>observations<br/>messages<br/>actions")]
-        ST2["today.md<br/>(working view,<br/>always injected)"]
-    end
+**09:15 — You DM Aitne:** *"Tell Sarah I'll review by 11. And book lunch with Mark on Thursday — somewhere near his office."*
 
-    subgraph LONG["🟢 Long-term memory (Markdown)"]
-        direction TB
-        LT1["user/profile.md<br/>work · expertise<br/>people · goals"]
-        LT2["projects/*.md<br/>roadmap.md"]
-        LT3["daily/YYYY-MM-DD.md<br/>↓<br/>weekly/YYYY-Www.md<br/>↓<br/>monthly/YYYY-MM.md"]
-    end
+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.
 
-    AI(("🧠 Next session<br/>(any backend,<br/>any platform)"))
+**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?"*
+
+**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.**
+
+---
+
+## How Aitne accumulates knowledge
+
+Every signal flows through the same pipeline: capture → short-term → long-term → injected back into every future conversation.
+
+```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 --> ST1
-    ST1 -- "hourly check<br/>aggregates" --> ST2
-    ST2 -- "evening review<br/>condenses" --> LT3
-    ST2 -- "patterns identified" --> LT1
-    ST2 -- "project-tagged<br/>updates" --> LT2
-    LT3 -- "Friday roll-up" --> LT3
-    LT3 -- "month-end roll-up" --> LT3
-
-    LT1 -. "always injected" .-> AI
-    ST2 -. "always injected" .-> AI
-    LT2 -. "morning + evening" .-> AI
-    LT3 -. "recalled when relevant" .-> AI
+    OB --> SQL
+    SQL --> TODAY
+    TODAY --> JOURNAL
+    TODAY --> PROFILE
+    TODAY --> PROJECTS
+
+    PROFILE -.-> AI
+    TODAY -.-> AI
+    PROJECTS -.-> AI
+    JOURNAL -.-> AI
 ```
 
 **Key properties:**
 
-- **Plain Markdown.** You can `cat`, `vim`, `obsidian`, or `cp` any of these files. There is no proprietary format. Uninstall and the memory is still 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 1 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."
+- **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.
 
----
-
-## Compounding intelligence
+### Compounding intelligence
 
-The longer you use it, the better it gets. Not because the model improves — because *the context does*.
+The longer you use it, the better it gets. Not because the model improves — because the context does.
 
 ```mermaid
-graph LR
-    D1["📆 <b>Day 1</b><br/>Empty profile<br/>Generic answers<br/>Asks who's Sarah"]
-    W1["📅 <b>Week 1</b><br/>Calendar synced<br/>People dictionary<br/>Mail patterns ID'd"]
-    M1["🌙 <b>Month 1</b><br/>Profile auto-filled<br/>Tone matches you<br/>Recurring tasks tracked"]
-    M3["📈 <b>Month 3</b><br/>Full project map<br/>Knows your peers<br/>Proactive nudges"]
-    Y1["🎯 <b>Year 1</b><br/>Anticipates needs<br/>Recalls Q1 context<br/>You can't go back"]
-
-    D1 -->|implicit feedback| W1
-    W1 -->|evening review| M1
-    M1 -->|project tracking| M3
-    M3 -->|long-term memory| Y1
-
-    style D1 fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
-    style W1 fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
-    style M1 fill:#dbeafe,stroke:#3b82f6,stroke-width:2px
-    style M3 fill:#dcfce7,stroke:#22c55e,stroke-width:2px
-    style Y1 fill:#dcfce7,stroke:#22c55e,stroke-width:3px
+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
 ```
 
 ### The implicit feedback loop
 
-Every interaction shapes Aitne's understanding of you, *implicitly*. No buttons. No surveys. Just talk to it.
+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 the raw signals on the next pass:
+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 between the two is enforced server-side: a signal like "I prefer concise replies" is *tone* (goes to character). A signal like "my flight is on Friday" is *attribute* (goes to profile).
+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).
 
 ---
 
@@ -290,7 +357,7 @@ Aitne has a dedicated set of management skills — `management-task-register`, `
 | *"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 |
+| *"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 |
@@ -307,274 +374,60 @@ Every change is journaled to `agent_actions` with `source_kind=user_directive`.
 
 ---
 
-## Bring your own harness (BYOH)
+## Bring your own harness
 
-Already invested in Claude Code skills? Custom MCP servers? A polished `~/.codex/config.toml`? **Aitne loads them all.** No re-configuring. No re-buying. No vendor lock.
+Already invested in Claude Code skills? Custom MCP servers? A polished `~/.codex/config.toml`? **Aitne loads them all.** No re-configuring. No vendor lock.
 
 ```mermaid
 flowchart LR
-    subgraph YOUR["🔵 Your existing setup"]
-        direction TB
-        Y1["~/.claude/<br/>· skills<br/>· slash commands<br/>· MCP servers"]
-        Y2["~/.codex/<br/>· config<br/>· plugins"]
-        Y3["~/.gemini/<br/>· config<br/>· tools"]
-        Y4["Custom MCP servers<br/>(your data sources,<br/>internal tools)"]
-    end
-
-    subgraph AITNE_SKILLS["🟡 Aitne's built-ins"]
-        direction TB
-        A1["23 skills<br/>(Calendar, Mail, Notion,<br/>Roadmap, Schedule, ...)"]
-        A2["Per-event task flows<br/>(morning, hourly,<br/>DM, mention, ...)"]
-        A3["Persona MD<br/>(per-backend)"]
-    end
-
-    SESS["📦 Per-session workdir<br/>~/.personal-agent/agent-sessions/&lt;id&gt;/<br/>CLAUDE.md · AGENTS.md · GEMINI.md<br/>+ .claude/skills/ · .codex/skills/<br/>+ MCP config materialized"]
-
-    RUN["🚀 Backend runs with<br/><b>your full toolkit + Aitne's</b>"]
-
-    YOUR --> SESS
-    AITNE_SKILLS --> SESS
+    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
-
-    style YOUR fill:#dbeafe,stroke:#3b82f6
-    style AITNE_SKILLS fill:#fef3c7,stroke:#f59e0b
-    style SESS fill:#dcfce7,stroke:#22c55e
-    style RUN fill:#fae8ff,stroke:#a855f7
 ```
 
 | 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` | They're available in every Aitne-spawned Claude Code session. |
+| 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 + project preferences | Inherited automatically. |
+| Your Gemini auth and project preferences | Inherited automatically. |
 | Skills you wrote for `~/.claude/skills/` | Imported on demand. |
 
-**The growth flywheel:** Claude Code / Codex / Gemini ship a new connector → Aitne picks it up on next session → you get it for free.
+**The growth flywheel:** Claude Code, Codex, or Gemini ships a new connector → Aitne picks it up on next session → you get it for free.
 
 ---
 
 ## Multi-platform, multi-app
 
-One agent, every surface.
+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.
 
 ```mermaid
-flowchart TB
-    subgraph IN["📥 Input surfaces"]
-        direction LR
-        I1["💬 Slack DM/mention"]
-        I2["📲 Telegram"]
-        I3["🎮 Discord"]
-        I4["💚 WhatsApp"]
-        I5["🌐 Web dashboard chat"]
-        I6["✋ Manual file edits"]
-    end
-
-    subgraph SVC["🔌 Connected apps"]
-        direction TB
-        SV1["📅 Google Calendar · Outlook Calendar"]
-        SV2["📧 Gmail · Outlook · Yahoo · iCloud"]
-        SV3["📓 Notion · Obsidian"]
-        SV4["📦 GitHub · local Git"]
-        SV5["🗺️ Google Maps"]
-        SV6["🔧 Custom MCP servers"]
-    end
-
-    AITNE(("🧠 Aitne"))
+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
-
-    subgraph OUT["📤 Output surfaces"]
-        direction LR
-        O1["💬 Same DM channel"]
-        O2["📋 today.md<br/>updates"]
-        O3["📅 Calendar<br/>actions"]
-        O4["📧 Drafted emails"]
-        O5["🔔 Proactive<br/>notifications"]
-    end
-
+    AITNE --- SVC
     AITNE --> OUT
 ```
 
-**One conversation, every channel.** 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.
-
----
-
-## Highlights
-
-| | |
-|---|---|
-| 🌅 **Proactive routines** | Morning · evening · weekly · monthly · hourly observation sweep |
-| 💬 **Reactive on every chat platform** | Slack · Telegram · Discord · WhatsApp · Web dashboard |
-| 🧠 **Multi-backend brain** | Claude (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) · Codex CLI · Gemini CLI |
-| 📝 **MD-centric memory** | Plain Markdown you own — `today.md` · `roadmap.md` · `projects/*` · `daily/` · `weekly/` · `monthly/` |
-| 🔌 **23 built-in skills** | Calendar, mail, Notion, Obsidian, schedule, roadmap, receipts, travel, reading, voice, … |
-| 🔁 **4-mode integration framework** | `direct` (daemon polls) · `delegated` (backend's connector) · `native` (main backend MCP on demand) · `disabled` |
-| 🛡️ **Four-layer safety** | SDK allowlist · PreToolUse hooks · daemon API risk tiers · absolute-block layer that holds even in Allow mode |
-| 🪪 **Local-first & private** | Binds to `127.0.0.1`. No telemetry. Secrets in OS Keychain. Zero cloud state. |
-| 🧰 **Production tooling** | Background daemon · `aitne doctor` · cost analytics · auth health monitor with auto-recovery |
-| 🌍 **Speak any language** | The LLM handles it — talk to Aitne in Japanese, English, German, anything. `primaryLanguage` config nudges its outputs too. |
-
----
-
-## Table of contents
-
-1. [Quick start](#quick-start)
-2. [Setup guide](#setup-guide)
-3. [CLI reference](#cli-reference)
-4. [Architecture](#architecture)
-5. [Memory layout](#memory-layout)
-6. [Multi-backend](#multi-backend)
-7. [Integrations](#integrations)
-8. [Safety model](#safety-model)
-9. [Cost & quotas](#cost--quotas)
-10. [Configuration](#configuration)
-11. [Platform support](#platform-support)
-12. [Troubleshooting](#troubleshooting)
-13. [Development](#development)
-14. [FAQ](#faq)
-15. [License](#license)
-
----
-
-## Quick start
-
-### 1. Install
-
-```bash
-npm install -g @aitne-sh/aitne@latest
-```
-
-Installs the `aitne` CLI globally with the daemon, dashboard, and built-in agent assets.
-
-### 2. Bring at least one AI backend
-
-Aitne is the nervous system; you bring the brain. Install **at least one** of:
-
-```bash
-# Claude Code (recommended — full features, server-side advisor support)
-npm install -g @anthropic-ai/claude-code
-
-# OpenAI Codex CLI
-npm install -g @openai/codex
-
-# Google Gemini CLI
-npm install -g @google/gemini-cli
-```
-
-Login once with each CLI you intend to use — Aitne auto-detects them.
-
-### 3. Start
-
-```bash
-aitne start
-```
-
-The daemon (`:8321`) and dashboard (`:3000`) launch in the background and your browser opens to the setup wizard.
-
-### 4. Confirm
-
-```bash
-aitne status
-```
-
-```
-Aitne status:
-
-  Daemon:      running (PID 12345)
-    Uptime:    1m 23s
-    API:       http://127.0.0.1:8321
-    Platforms: slack, dashboard
-    Backends:  claude
-  Dashboard:   running (PID 12346)
-    URL:       http://localhost:3000
-
-  Last action: 2026-05-11T07:30:14Z  (routine.morning_routine)
-  Today:       6 action(s)  ·  $0.043 spent
-  Next:        2026-05-11T18:00:00Z  routine.evening_review
-```
-
-That's it. Open `http://localhost:3000` and finish the wizard.
-
----
-
-## Setup guide
-
-### Prerequisites
-
-| Requirement | Version | Why |
-|---|---|---|
-| **Node.js** | ≥ 22.0.0 | Daemon runtime (LTS) |
-| **At least one AI backend** | — | Claude Code, Codex CLI, or Gemini CLI |
-| **OS Keychain** | macOS / libsecret on Linux / DPAPI on Windows | Secret storage (file-based fallback available) |
-
-### Step 1 — Install Aitne
-
-```bash
-npm install -g @aitne-sh/aitne@latest
-```
-
-> Want to hack on the source? See [Development](#development).
-
-### Step 2 — Install at least one backend CLI
-
-#### Claude Code (recommended)
-
-```bash
-npm install -g @anthropic-ai/claude-code
-claude --version
-claude auth login                 # uses your Claude subscription
-```
-
-#### OpenAI Codex CLI
-
-```bash
-npm install -g @openai/codex
-codex --version
-codex login --device-auth         # device-flow OAuth
-```
-
-#### Google Gemini CLI
-
-```bash
-npm install -g @google/gemini-cli
-gemini --version
-# OAuth handled automatically on first use
-```
-
-You can install all three. Per-process tier routing lets you mix-and-match: Sonnet for routines and DMs, Haiku for delegated/polling, Codex for code-heavy work, Gemini for free-tier headroom — and Opus only on the keys that genuinely need it (first-day morning routine, knowledge import, opt-in heavy task mode).
-
-### Step 3 — Launch and run the wizard
-
-```bash
-aitne start
-```
-
-Aitne builds (if needed), launches both processes, and opens `http://localhost:3000/setup`. The wizard walks 9 screens:
-
-| # | Step | What it asks |
-|---|---|---|
-| 1 | **Basics** | Agent display name + primary language |
-| 2 | **Vault** | Plain (`~/.personal-agent/context/`) or your existing Obsidian vault path |
-| 3 | **AI Backend** | Pick the main backend (Claude / Codex / Gemini), authenticate (API key or CLI login), choose execution mode (Safe vs. Allow) |
-| 4 | **Mail** | Gmail (OAuth) · Outlook (OAuth) · Yahoo / iCloud (IMAP + app password) — each card sets `direct` / `delegated` / `native` mode where supported |
-| 5 | **Calendar** | Google Calendar (OAuth) · Outlook Calendar (OAuth or user-managed MCP) — same mode picker per card |
-| 6 | **Note** | Notion (OAuth) and an optional secondary Obsidian vault path to watch |
-| 7 | **Messaging** | Slack · Telegram · Discord · WhatsApp pairing |
-| 8 | **Rules** | A short conversation with the agent — it interviews you and stages a `character` block + a `management-rules` block, which you confirm before saving |
-| 9 | **Done** | Summary; agent runs its first `setup` session |
-
-Required steps: Basics, Vault, AI Backend, Rules. Everything else exposes a **Skip** button — you can come back later from `/connections/*` or `/settings/*`.
-
-### Step 4 — Verify
-
-```bash
-aitne status         # PIDs, uptime, connected platforms, backends, today's spend
-aitne doctor         # install diagnostic
-aitne logs -f        # tail the daemon log
-```
-
 ---
 
 ## CLI reference
@@ -597,7 +450,7 @@ aitne logs -f        # tail the daemon log
 |---|---|
 | `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]` | 9 install checks; the repository-drift check expands into one extra row per repo whose `origin` no longer matches its registered slug. |
+| `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. |
@@ -608,13 +461,13 @@ aitne logs -f        # tail the daemon log
 
 | Flag | Default | Description |
 |---|---|---|
-| `--since <duration>` | `24h` | Time window (e.g. `1h`, `7d`, `2026-04-20`). |
+| `--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 under each row. |
-| `--json` | off | Machine-readable JSON output. |
+| `--detail` | off | Expand the `detail` JSON column. |
+| `--json` | off | Machine-readable output. |
 
 ### `aitne doctor` checks
 
@@ -634,58 +487,36 @@ aitne logs -f        # tail the daemon log
 
 ```mermaid
 flowchart TB
-    subgraph PLAT["📱 Input platforms"]
-        direction LR
-        P1[Slack]
-        P2[Telegram]
-        P3[Discord]
-        P4[WhatsApp]
-        P5[Dashboard]
-    end
+    PLAT["Input platforms:<br/>Slack, Telegram, Discord,<br/>WhatsApp, Web dashboard"]
 
-    subgraph DAEMON["⚙️ Aitne daemon (Hono :8321)"]
+    subgraph DAEMON["Aitne daemon (Hono on :8321)"]
         direction TB
-        EB[EventBus<br/>priority heap]
-        DI[Dispatcher<br/>semaphores: 2 reactive +<br/>3 autonomous]
-        BR[BackendRouter<br/>ProcessKey → tier → backend<br/>+ fallback]
-        AC[Agent Core<br/>IAgentCore interface]
-        OB[Observers<br/>Git · GitHub · Obsidian ·<br/>Notion · Calendar · Mail]
-        SC[Scheduler<br/>node-cron + agent_schedule]
+        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
 
-    subgraph BACKENDS["🧠 AI runtimes"]
-        direction LR
-        BC[Claude Code SDK]
-        BX[Codex CLI subprocess]
-        BG[Gemini CLI subprocess]
-    end
+    BACKENDS["AI runtimes:<br/>Claude Code SDK,<br/>Codex CLI subprocess,<br/>Gemini CLI subprocess"]
 
-    subgraph DATA["💾 Local data"]
-        direction LR
-        SQL[(SQLite<br/>WAL + FTS5)]
-        MD["📝 Markdown memory<br/>~/.personal-agent/context/"]
-        KC[OS Keychain]
-    end
+    DATA["Local data:<br/>SQLite (WAL + FTS5),<br/>Markdown memory,<br/>OS Keychain"]
 
     PLAT --> EB
     SC --> EB
-    OB --> SQL
-    SQL -- "hourly check pulls" --> EB
+    OB --> DATA
+    DATA --> EB
     EB --> DI
     DI --> BR
     BR --> AC
-    AC --> BC
-    AC --> BX
-    AC --> BG
-    AC <-->|curl localhost API| DAEMON
-    DAEMON <--> SQL
-    DAEMON <--> MD
-    DAEMON <--> KC
+    AC --> BACKENDS
+    AC --> DATA
 ```
 
 ### Two execution paths
 
-**Reactive path** — owner DMs/mentions, cron routines, calendar approach events, scheduled tasks
+**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
@@ -705,13 +536,13 @@ packages/
 
 agent-assets/    # Read by the daemon at session-init time
 ├── agent-profiles/  # Persona MD per backend (CLAUDE.md / AGENTS.md / GEMINI.md)
-├── skills/          # 23 built-in skills (context, calendar, mail, notion, …)
-├── task-flows/      # Per-event prompt templates (one per event type)
+├── 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 & design docs (v4.16) — source of truth
+docs/design/     # Architecture and design docs — source of truth
 ```
 
 ---
@@ -736,9 +567,9 @@ Everything the agent writes lives under `PA_DATA_DIR` (default `~/.personal-agen
 │   ├── 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)
+│   ├── 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
@@ -747,8 +578,8 @@ Everything the agent writes lives under `PA_DATA_DIR` (default `~/.personal-agen
 ├── logs/{daemon,dashboard}.log
 ├── prompts/                   # Editable prompt templates
 ├── attachments/               # Chat attachments
-├── agent-sessions/<id>/       # Per-session backend workdir
-├── secrets/                   # File-fallback secret store (`<name>.enc`); empty when OS keychain is used
+├── agent-sessions/[id]/       # Per-session backend workdir
+├── secrets/                   # File-fallback secret store (empty when OS keychain is used)
 └── run/                       # PID files for daemon + dashboard
 ```
 
@@ -764,9 +595,9 @@ Aitne abstracts three AI runtimes behind a single `IAgentCore` interface:
 
 | Backend | Implementation | Session resume | Strengths |
 |---|---|---|---|
-| **Claude Code** | `@anthropic-ai/claude-agent-sdk` | ✅ Full session resume | Best for routines, deep context, server-side advisor |
-| **Codex CLI** | OpenAI Codex CLI subprocess + JSONL stream | New session each time | Best for code-heavy tasks, fast iteration |
-| **Gemini CLI** | Google Gemini CLI subprocess + JSONL stream | New session each time | Best for free-tier, large-context summarization |
+| **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 |
 
 ### Per-process tier routing
 
@@ -791,8 +622,9 @@ Every kind of work has a `ProcessKey` mapped to a tier (`lite` / `medium` / `hig
 | `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 & 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.
+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.
 
 ---
 
@@ -805,7 +637,7 @@ Configure each ProcessKey's backend & tier from the dashboard `/settings/models`
 | Slack | `@slack/bolt` | Socket Mode (WebSocket) | Bot + App tokens |
 | Telegram | `telegraf` | Long polling | Bot token |
 | Discord | `discord.js` | Gateway | Bot token |
-| WhatsApp | `baileys` | QR pairing | Scan QR from dashboard |
+| WhatsApp | `@whiskeysockets/baileys` | QR pairing | Scan QR from dashboard |
 | Web Dashboard | Hono SSE | Always on | None |
 
 ### Mail (multi-provider, unified API)
@@ -817,29 +649,30 @@ Configure each ProcessKey's backend & tier from the dashboard `/settings/models`
 | **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.
+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 & docs
+### 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 & comment, issue ops, HMAC-SHA256 signature verification at `POST /webhook/github`
+- **GitHub** — `@octokit/rest` + webhooks; PR list and comment, issue ops, HMAC-SHA256 signature verification at `POST /webhook/github`
 
-### Calendar & travel
+### 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` (Apple Calendar service; reachable from any platform)
+- **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
+- **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`.
@@ -852,10 +685,10 @@ Each integration runs in one of **four** modes:
 |---|---|---|---|---|
 | **`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 | No daemon polling — agent reaches the integration in-turn via MCP | None | On-demand only; observations posted via `/api/observations` |
+| **`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 |
 
-`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.
+`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.
 
 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`.
 
@@ -893,12 +726,14 @@ In Safe mode, every `Bash(curl ...)` invocation is parsed: the hostname must be
 
 Hard-blocked in **both Safe and Allow** modes. `bypassPermissions` and `allowedToolsOverride` cannot widen past this:
 
-- Recursive delete: `rm -rf *`, `rm -r *`, `rm --recursive*` (every flag-bundle variant)
+- 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 <(...)`
-- Platform secret CLI: `security *`, `secret-tool *`, `cmdkey *`
-- Secret file reads/writes: `.env`, `~/.ssh/**`, `~/.gnupg/**`, `~/.aws/**`, `~/.config/gcloud/**`
-- Daemon-managed secrets: `~/.personal-agent/secrets/**`, `~/.personal-agent/whatsapp/auth/**`
+- 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)
 
 Every blocked attempt lands in `agent_actions` with `action_type='blocked_absolute'`.
 
@@ -914,7 +749,7 @@ Every blocked attempt lands in `agent_actions` with `action_type='blocked_absolu
 
 ---
 
-## Cost & quotas
+## Cost and quotas
 
 ### Built-in controls
 
@@ -947,13 +782,12 @@ If you're on a Claude / Codex / Gemini subscription, none of this hits a metered
 
 ## Configuration
 
-`.env` is **bootstrap-only**. Everything else is editable from the dashboard at runtime — or via natural-language DMs to the agent.
+`.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     # macOS / Linux
-# PA_DATA_DIR=C:\Users\You\.personal-agent  # Windows
+PA_DATA_DIR=~/.personal-agent
 PA_API_PORT=8321
 PA_DASHBOARD_PORT=3000
 PA_LOG_LEVEL=info                 # trace | debug | info | warn | error
@@ -961,21 +795,18 @@ 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're 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:
+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
-# Owner identifiers (non-secret — let messaging adapters know who you are)
 PA_SLACK_OWNER_USER_ID=U...
 PA_TELEGRAM_OWNER_CHAT_ID=...
 PA_DISCORD_OWNER_USER_ID=...
 PA_WHATSAPP_ENABLED=true
 PA_WHATSAPP_OWNER_PHONE=...
 
-# Obsidian vault paths
 PA_PRIMARY_VAULT_PATH=~/Documents/MyVault
 PA_EXTERNAL_OBSIDIAN_VAULT_PATH=~/Documents/SecondaryVault
 
-# Notion default database routing
 PA_NOTION_DATABASE_IDS='{"tasks":"abc...","notes":"def..."}'
 ```
 
@@ -983,9 +814,9 @@ Everything else — bot tokens, OAuth refresh tokens, Notion API key, GitHub tok
 
 ### Runtime settings
 
-The dashboard `/settings` tree exposes ~100 runtime keys. The headline ones:
+The dashboard `/settings` tree exposes ~100 runtime keys. Headline groups:
 
-- **Schedule** — `timezone`, `dayBoundaryHour`, hourly check window & interval, cron schedules
+- **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
@@ -994,7 +825,7 @@ The dashboard `/settings` tree exposes ~100 runtime keys. The headline ones:
 - **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`, `voiceTranscriptionModel`, `voiceTranscriptionPrimaryLanguage`
+- **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."*
@@ -1093,21 +924,6 @@ aitne audit --since 24h --result failed --detail
 
 ## Development
 
-For contributors:
-
-```bash
-git clone https://github.com/Aitne-sh/Aitne.git aitne
-cd aitne
-corepack enable
-pnpm install
-pnpm start          # build (if stale) + launch in background
-pnpm dev            # foreground mode with full stdio
-pnpm test           # vitest — unit tests across packages/*
-pnpm test:watch
-pnpm lint           # turbo run lint
-pnpm clean          # remove all build artifacts and node_modules
-```
-
 ### Tech stack
 
 | Layer | Stack |
@@ -1124,7 +940,7 @@ pnpm clean          # remove all build artifacts and node_modules
 - 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 (v4.16) is the authoritative spec; `packages/daemon/src/` is the source of truth when they diverge
+- The `docs/design/` tree is the authoritative spec; `packages/daemon/src/` is the source of truth when they diverge
 
 ### Source-of-truth pointers
 
@@ -1146,7 +962,7 @@ pnpm clean          # remove all build artifacts and node_modules
 ## 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*.
+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`.
@@ -1161,7 +977,7 @@ Yes — Claude Code, OpenAI Codex, and Google Gemini CLI are all supported. Pick
 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.
+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.
@@ -1170,13 +986,13 @@ Aitne can use your existing Obsidian vault as the primary memory store. The agen
 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.
 
 **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-byoh).
+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).
 
 **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.
 
 **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 / vault outputs into that language too. Implementation code remains English-only.
+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 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.