@aitne-sh/aitne 0.1.7 → 0.1.9

package/README.md

@@ -2,108 +2,166 @@
 
 # Aitne
 
-### Always on. Always yours.
-
-**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)
 [![Node](https://img.shields.io/badge/node-%E2%89%A522-brightgreen)](https://nodejs.org)
 [![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)
+
+**Wake up to a brief that was written for you, by you.**
+
+At 04:00, Aitne reads your calendar, mail, GitHub, and notes — then drafts a one-page plan for the day ahead: today's meetings, the email thread you missed, the PR your teammate is waiting on. Before you've finished coffee, the summary is in your DMs. By evening it journals what actually happened.
+
+All on your laptop. All Markdown you own. Bring your own AI (Claude Code / Codex / Gemini CLI) — Aitne is the part that watches, schedules, and remembers.
 
 ```bash
 npm install -g @aitne-sh/aitne@latest
 aitne start
 ```
 
+![Aitne setup and dashboard walkthrough](./docs/assets/aitne-demo.gif)
+
 </div>
 
 ---
 
-## Overview
+## A day with Aitne
+
+Aitne is a daemon on your laptop, connected to your calendar, mail (Gmail / Outlook / iCloud / Yahoo), GitHub, Obsidian, and Notion. You talk to it through DMs in Slack / Telegram / Discord / WhatsApp — or through a local dashboard at `:8322`.
+
+- **04:00 — Morning routine.** Aitne reads everything that landed overnight (mail, GitHub activity, calendar changes, vault updates) and writes `today.md` — sample below.
+- **Morning — Brief.** The plan lands in your DMs as a short summary.
+- **Through the day — Nudges.** Meeting reminders with travel time, hourly background checks for the things you care about (eval results, PR review requests, new mail). DMs only when there's something worth your attention.
+- **Evening — Review.** Aitne writes a daily journal: what got done, what slipped, one observation about the week.
 
-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 steer it through natural-language DMs ("skip morning routine on Sundays", "ping me when the overnight job finishes") and bang commands (`!cost`, `!ask`, `!ingest`).
 
-You bring the brain — Claude Code, OpenAI Codex CLI, or Google Gemini CLI. Aitne is the nervous system that schedules, routes, observes, and remembers.
+---
+
+## Aitne's plan for today
+
+`today.md` — written each morning into `~/.personal-agent/context/state/`. Plain Markdown you can `cat`, `vim`, or sync to Obsidian. Sample:
+
+```text
+2026-05-20 (Wednesday)
+Day type: Weekday | Work focus: on | Study focus: on | Personal focus: on
+
+User Schedule
+ 10:00 — Team standup (#ml-platform)
+ 13:30 — RAG eval review with research team
+ 16:00 — 1:1 with manager (quarterly check-in)
+ 21:00 — Overnight training window opens (8xH100 reserved)
+
+User Tasks
+ Land the embedding-index refactor PR — address review feedback [URGENT] [work]
+ Cancel unused GPU reservation before 18:00 — billing cutoff [work]
+ Skim 3 papers from yesterday's arxiv digest — pick one for Friday's reading group [study]
+ Renew gym membership before Friday [personal]
+ Reply to dentist about reschedule [personal]
+
+Agent Plan
+ 09:45 Notify: standup in 15 min [work] →notify
+ 17:30 Notify: cancel GPU reservation by 18:00 to avoid overnight charges [work] →notify
+ 20:45 Notify: training window opens in 15 min — confirm dataset hash [work] →notify
+
+Agent Notes
+ (HIGH) 2026-05-22 (Fri): Reading group at 16:00 — pick paper by Thu evening
+ (HIGH) 2026-05-23 (Sat): Friend's birthday dinner — gift not bought yet
+ (MED)  2026-05-25 (Mon): Quarterly OKR review — draft self-assessment by EOD Sun
+ Two coworkers pushed to feat/embedding-index since you last pulled [work]
+ Overnight eval run finished — accuracy +1.2pp, p95 latency +18ms [work]
+ Bank statement available — review when convenient [personal]
+ Weather: rain 06:00–10:00 — leave 10 min earlier [personal]
+
+Agent Log
+ 04:12 Morning Routine completed — today.md drafted from 23 raw signals
+ 07:02 Sent morning brief to Slack DM (4 priorities, 2 timing alerts)
+ 12:38 Hourly check: 1 new GitHub review request, 0 calendar changes
+ 18:00 Evening Review completed — 3 of 5 tasks closed; 2 carried to tomorrow
+
+Handoff
+ Tomorrow
+  Reply to dentist about reschedule [personal]
+  Pick reading-group paper [study]
+  Triage overnight training-run metrics [work]
+ Later
+  2026-05-22 (Fri): Reading group at 16:00
+  2026-05-23 (Sat): Friend's birthday dinner
+  2026-05-25 (Mon): Quarterly OKR review
+```
 
 ---
 
-## What makes Aitne different
+## Why Aitne
 
-**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 don't open it. It opens to you.**
+Most AI tools wait for you to type. Aitne goes first — it watches all day and reaches out only when there's something worth acting on.
 
-**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.
+**Nothing leaves your laptop.**
+The daemon binds to `127.0.0.1` only. Secrets sit in your OS keychain. Memory is plain Markdown under `~/.personal-agent/`. No vendor account, no remote sync, no telemetry — your AI provider's API is the only thing that talks to the network, on your own key.
 
-**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.
+**Bring your own model.**
+Per-task routing assigns the right tier to the right backend, and the router fails over automatically on quota or auth issues. Run one backend or all of them — your choice.
 
-**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.
+**Memory compounds, the model doesn't have to.**
+Every DM, every correction, every observation goes into your Markdown context. The model stays stateless — your story grows.
 
-**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`.
+Already running Claude Code in a terminal? Aitne is the part that wakes itself up before you do, watches your mail and calendar between your sessions, remembers what you told it last week, and reaches you in your DMs without a terminal open.
 
 ---
 
-## Installation
+## Is this for you?
 
-### From npm
+**Aitne fits if you...**
+- already use Claude Code, Codex CLI, or Gemini CLI daily
+- want context that survives sessions, without uploading your life to someone's server
+- are comfortable running a daemon on your laptop and pasting an API key
 
-The recommended path. Installs the `aitne` CLI globally with the daemon, dashboard, and built-in agent assets.
+**You'll bounce off if you...**
+- want a polished hosted chat UI — this isn't that
+- don't have an API key for at least one provider (Aitne spawns sessions on your behalf; the cost lands on your account)
+- expect zero setup — there's a 9-step wizard for integrations and channels
+
+---
+
+## Install
 
 ```bash
 npm install -g @aitne-sh/aitne@latest
 aitne start
 ```
 
-Then bring **at least one** AI backend:
+The daemon listens on `:8321`, the dashboard on `:8322`. After `aitne start`, your browser opens to the setup wizard.
 
-```bash
-# Claude Code — full feature support including server-side advisor
-npm install -g @anthropic-ai/claude-code
-claude auth login
+You also need at least one AI backend installed and one API key. The documented operating mode is **provider API keys** — paste them into the wizard (they land in the OS keychain, never `.env`):
 
-# OpenAI Codex CLI
-npm install -g @openai/codex
-codex login --device-auth
+| 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 sessions) |
+| **OpenAI Codex CLI** | `npm install -g @openai/codex` | `OPENAI_API_KEY` in the wizard, or `codex login --device-auth` |
+| **Google Gemini CLI** | `npm install -g @google/gemini-cli` | `GEMINI_API_KEY` / `GOOGLE_API_KEY`, or OAuth on first use |
+| **OpenCode** (sst/opencode) | `npm install -g opencode-ai` | provider via `opencode auth login`, set in the wizard |
 
-# Google Gemini CLI
-npm install -g @google/gemini-cli
-# OAuth handled on first use
-```
+### Verify
 
-Login once with each CLI you intend to use — Aitne auto-detects them on the next session.
+```bash
+aitne status   # PIDs, uptime, connected platforms, today's spend
+aitne doctor   # install-health diagnostic (Node, ports, keychain, CLIs, native bindings)
+aitne logs -f  # tail the daemon log
+```
 
-### From source (git)
+### From source
 
-For contributors, or if you want to hack on the daemon directly. Requires Node ≥ 22 and pnpm 10.x.
+Contributors and anyone hacking 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
+pnpm dev          # foreground mode with full stdio
 ```
 
-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.
+Full walkthrough: [docs/setup-guide.md](docs/setup-guide.md).
 
 ---
 
@@ -124,8 +182,8 @@ flowchart LR
 
     subgraph LOCAL["Your laptop"]
         direction TB
-        DAEMON["Aitne daemon<br/>(always on)"]
-        BRAIN["AI session<br/>Claude / Codex / Gemini"]
+        DAEMON["Aitne daemon<br/>(always on, 127.0.0.1)"]
+        BRAIN["AI session<br/>Claude / Codex / Gemini / OpenCode"]
         MEMORY["Markdown memory<br/>plain files you own"]
         DAEMON --- BRAIN
         BRAIN --- MEMORY
@@ -138,62 +196,85 @@ flowchart LR
     DAEMON --- YOU
 ```
 
-The daemon runs two execution paths in parallel:
+Two execution paths run 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.
+- **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 is worth surfacing.
 
 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
+---
+
+## Backends
 
-A non-exhaustive catalogue — every entry below is backed by an implemented skill, route, or observer. Click to expand.
+Aitne abstracts four AI runtimes behind one `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.8**. The high tier is opt-in — no install-time surface defaults to it; pin it per row from `:8322/settings/models`.
 
-<details>
+| Backend | Implementation | Resume | Strengths |
+|---|---|---|---|
+| **Claude Code** | `@anthropic-ai/claude-agent-sdk` | ✓ | 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** | `opencode-ai` HTTP server + SDK client | ✓ | Multi-provider — routes to any `opencode auth login` provider |
+
+The router fails over to a configured fallback automatically on `BackendQuotaError` or decisive failure, re-materializing the fallback's instruction file and skill directories into the session workdir. Per-process tier defaults and routing are editable at `:8322/settings/models`.
+
+---
+
+## Integrations
+
+| 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:
+
+| 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 a live capability probe and a per-key flip lock.
+
+---
+
+## What you can do
+
+<details open>
 <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>
+<details open>
 <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>
@@ -201,817 +282,159 @@ 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
+- Per-repo cron triggers — "every Monday at 09:00, summarize merged PRs into the repo's daily journal"
 - 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
+<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 `identity/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>Reading, lifestyle, voice</b></summary>
+<summary><b>Bring your own toolkit</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
-</details>
-
-<details>
-<summary><b>Run your own tools</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
+- 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?"*
-
-**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.
+## Memory
 
-**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?
+Everything Aitne writes lives in `~/.personal-agent/context/`:
 
-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 --> SQL
-    SQL --> TODAY
-    TODAY --> JOURNAL
-    TODAY --> PROFILE
-    TODAY --> PROJECTS
-
-    PROFILE -.-> AI
-    TODAY -.-> AI
-    PROJECTS -.-> AI
-    JOURNAL -.-> AI
 ```
-
-**Key properties:**
-
-- **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
-
-The longer you use it, the better it gets. Not because the model improves — because the context does.
-
-```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
+context/
+├── state/
+│   ├── today.md            # Working view, always injected
+│   ├── yesterday.md        # Daemon-rotated archive
+│   ├── inbox/              # Captured snippets
+│   └── scratch/            # Short-lived agent notes (48h TTL)
+├── plans/
+│   ├── roadmap.md          # Long-term goals
+│   └── projects/           # One file per active project
+├── identity/              # profile.md, people.md, work.md, …
+├── policies/              # Management rules, MCP config, redaction, routines
+├── journal/
+│   ├── daily/YYYY-MM-DD.md # Synthesized daily journal
+│   ├── weekly/            # Weekly retrospectives
+│   └── agent.md           # Private agent self-reflection
+└── knowledge/             # wiki, per-repo overviews, entities, dossiers
 ```
 
-### The implicit feedback loop
+Context writes flow through `curl http://localhost:8321/api/context/<class>/<path>` — where `<class>` is one of `identity`, `state`, `plans`, `journal`, `knowledge`, `policies` — 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.
 
-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).
+Schema upgrades are forward-only and idempotent — the migration runner preserves your SQLite history and Markdown context across releases. (`aitne update` prints the `npm install -g @aitne-sh/aitne@latest` command; there is no self-updater.)
 
 ---
 
-## Talk to it like a person
+## Safety
 
-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.**
+Four independent layers, designed so the bottom layer holds even when upper layers are widened:
 
-| 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`.
+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
 
----
-
-## 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 vendor lock.
-
-```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
-```
-
-| 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. |
-
-**The growth flywheel:** Claude Code, Codex, or Gemini ships a new connector → Aitne picks it up on next session → you get it for free.
+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.
 
 ---
 
-## Multi-platform, multi-app
+## Cost
 
-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.
+| Control | Default | Effect when set |
+|---|---|---|
+| `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 |
 
-```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
-```
+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.
 
 ---
 
-## CLI reference
+## Operating Aitne
 
 ### 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, `-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>`
+| `aitne doctor [--json]` | Eight install-health checks + per-repo GitHub-link drift expansion |
+| `aitne audit [flags]` | Read the agent action log — `--since`, `--type`, `--result`, `--backend`, `--detail`, `--json` |
+| `aitne setup` | Re-open the `/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 |
 
----
+`aitne help [cmd]` for per-command details.
 
-## Architecture
+### Configuration
 
-```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.
-
-`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
-```
-
----
-
-## 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
-
-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).
-
----
-
-## Multi-backend
-
-Aitne abstracts three AI runtimes behind a single `IAgentCore` interface:
-
-| Backend | Implementation | Session 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 |
-
-### Per-process tier routing
-
-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.
-
----
-
-## 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
-
-Each integration runs in one of **four** 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 |
-
-`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`.
-
----
-
-## Safety model
-
-Aitne stacks **four** independent safety layers. The bottom layer holds even when the upper layers are widened by the user.
-
-### 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
-```
-
-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`)
-
-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)
-
-Every blocked attempt lands in `agent_actions` with `action_type='blocked_absolute'`.
-
-### Other guarantees
-
-- **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
-
----
-
-## Cost and quotas
-
-### Built-in controls
-
-| Control | Default | Configurable |
-|---|---|---|
-| `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) |
-
-### 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.
-
----
-
-## 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.
-
-### 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."*
+`.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 `:8322`, or via natural-language DMs to the agent.
 
 ---
 
 ## 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
-
-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
+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 the `LongPathsEnabled=1` registry key.
 
-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
-```
-
-### SQLite errors on startup
-
-The DB can be reset safely — your Markdown memory in `context/` is untouched. The `*` clears the WAL + SHM companion files:
-
-```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
+## Documentation
 
-```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
-```
-
-### Diagnostic dump
-
-```bash
-aitne audit --since 24h --result failed --detail
-```
-
----
-
-## 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 |
-
-### 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 |
+| Topic | Doc |
 |---|---|
-| 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` |
+| 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) |
 
 ---
 
-## 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.
+## Tech stack
 
-**Does it phone home?**
-No. The daemon binds to `127.0.0.1` only. There is no telemetry. Verify with `lsof` and `nettop`.
+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`
 
-**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/`.
+Dashboard: Next.js 16 · React 19 · Tailwind 4 · shadcn/ui · TanStack Query · Recharts · Monaco
 
-**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.
-
-**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.
-
-**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).
-
-**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, 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.
-
-**How do I uninstall?**
-`aitne uninstall`. It will offer to wipe `~/.personal-agent` or keep it for re-installation.
+Monorepo: pnpm 10 workspaces · Turborepo · TypeScript 5.8 · Vitest 3 (100% coverage gate on a curated pure-logic subset)
 
 ---
 
 ## 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).