@aitne-sh/aitne 0.1.1 → 0.1.2

package/README.md

@@ -1,357 +1,964 @@
-# Aitne — Always on. Always yours.
+<div align="center">
 
-A local-first, proactive personal AI agent that runs continuously on your machine.
+# Aitne
 
-A long-running **TypeScript daemon** acts as the nervous system — sensing events, managing schedules, and routing work. **Claude Code** (or Codex / Gemini CLI as alternate backends) acts as the brain — thinking, deciding, and acting. All memory lives in local Markdown files. No cloud state.
+### Always on. Always yours.
 
-## What it does
+**A local-first, proactive personal AI agent that runs continuously on your own machine — and gets smarter about *you* every day.**
 
-- **Proactive routines** — morning plan, evening review, weekly/monthly reviews, hourly observation digest driven by your Obsidian vault, Git repos, Notion, and Calendar
-- **Reactive messaging** — responds to DMs and mentions on Slack, Telegram, Discord, WhatsApp, and a built-in web dashboard
-- **Integrations** — Google Calendar, Gmail, Notion, Obsidian, GitHub, multi-provider mail (Outlook, Yahoo, iCloud, IMAP), and project-global MCP servers
-- **Structured memory** — user profile, today's plan, roadmap, project status, daily journal, review dossiers, and context index — all local Markdown, readable and editable by hand
-- **Multi-backend** — Claude (Opus/Sonnet/Haiku), OpenAI Codex, Google Gemini; per-process tier routing with automatic fallback
-
-## Architecture
+[![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)
 
+```bash
+npm install -g @aitne-sh/aitne@latest
+aitne start
 ```
-Messaging platforms          Dashboard (Next.js :3000)
-  Slack / Telegram /         Chat · Connections · Schedule
-  Discord / WhatsApp ─────────────── Analytics · Settings ──┐
-        │                                                    │
-        ▼                                                    ▼
-  ┌──────────────────────────────────────────────────────────────┐
-  │                     Daemon (Hono :8321)                       │
-  │  EventBus → Dispatcher → BackendRouter                       │
-  │  Observers (Git, Obsidian, Notion, Calendar, Mail)           │
-  │  Scheduler (cron + agent_schedule table)                     │
-  └───────────────────────────┬──────────────────────────────────┘
-                              │  Agent SDK / CLI subprocess
-                              ▼
-                    Claude Code / Codex / Gemini
-                        (reads skills, writes
-                         via Context File API)
+
+</div>
+
+---
+
+## The concept
+
+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.
+
+```mermaid
+flowchart LR
+    subgraph WORLD["Your digital life"]
+        direction TB
+        W1["💬 Messages"]
+        W2["📅 Calendar"]
+        W3["📧 Mail"]
+        W4["📦 Git"]
+        W5["📓 Notes"]
+    end
+
+    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"]
+
+    WORLD <--> DAEMON
+    DAEMON <--> YOU
 ```
 
-All agent-written state flows through `PUT/PATCH /api/context/*`. The daemon is the only process that writes to `~/.personal-agent/context/*.md` — the agent uses `curl` to the local API, not direct file writes.
+Three things make Aitne different:
+
+| | |
+|---|---|
+| 🌱 **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. |
 
 ---
 
-## Getting started
+## A day with Aitne (live demo)
 
-### Step 1 — Install prerequisites
+> A real walkthrough of one user's Tuesday.
 
-You need **Node.js ≥ 22**, **pnpm 10.x**, and at least one **AI backend CLI**.
+**04:00 — While you sleep.** Aitne reads yesterday's handoff, your calendar for today, the last 24 hours of mail across 4 accounts, new commits in 3 repos, and the 7 pending observations from Notion. It generates `today.md` and queues a Morning Briefing DM for after quiet hours end.
 
-#### macOS
+**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
-# Node.js via nvm (recommended — lets you switch versions easily)
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
-source ~/.zshrc   # or ~/.bashrc
-nvm install 22
-nvm use 22
-node --version    # should print v22.x.x
-
-# pnpm
-npm install -g pnpm
-pnpm --version    # should print 10.x.x
-
-# Claude Code CLI (AI backend — required unless you use Codex or Gemini instead)
-npm install -g @anthropic-ai/claude-code
-claude --version
+**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 Notion `people.md`, suggests Tartine. You confirm. Done.
+
+**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?"*
+
+**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 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.
+
+**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?
+
+That's a normal Tuesday. The point isn't any single trick — it's that **all of this happens without you opening an app.**
+
+---
+
+## What you can do with it
+
+A non-exhaustive list. Click any group to expand.
+
+<details>
+<summary><b>📅 Time, calendar, travel</b></summary>
+
+- Auto-generate `today.md` every morning with your real schedule
+- 15-min approach reminders for every calendar event, with travel time pre-computed via Google Maps
+- "Find me a 30-min slot with Sarah and Mark next week" — Aitne checks freebusy across calendars
+- 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>
+
+- Unified inbox across Gmail, Outlook, Yahoo, iCloud, and any IMAP server
+- Local FTS5 full-text search across **every** account ("find emails about acme last quarter")
+- Auto-classify, label, and archive (Gmail)
+- 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
+- Daily digest of unread mail in the morning briefing
+</details>
+
+<details>
+<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
+- Full Notion page & 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")
+</details>
+
+<details>
+<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
+- 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
+- Auto-detect when a coworker modified a file you're about to ship
+</details>
+
+<details>
+<summary><b>✅ Tasks, projects, life admin</b></summary>
+
+- Unified task view across GitHub Issues, mail-derived TODOs, and your own `today.md`
+- Per-project Markdown files with auto-maintained status, deadlines, and people
+- Long-term roadmap with quarterly milestones
+- "Carry this to tomorrow" — handoff between today.md, daily/, weekly/, monthly/
+- Auto-detect recurring chores and set up reminders
+</details>
+
+<details>
+<summary><b>📚 Reading, learning, lifestyle</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 Obsidian vault
+- Travel itinerary roll-up surfaced before each trip
+</details>
+
+<details>
+<summary><b>🤖 Self-management & 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
+- 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
+</details>
+
+---
+
+## How Aitne accumulates knowledge about you
+
+Every signal Aitne sees flows through the same pipeline: capture → short-term → long-term → injected back into every future conversation.
+
+```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
+
+    OB["⚙️ Observers & adapters<br/>(WebSocket · IDLE · polling)"]
+
+    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
+
+    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
+
+    AI(("🧠 Next session<br/>(any backend,<br/>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
 ```
 
-#### Linux (Ubuntu / Debian)
+**Key properties:**
 
-```bash
-# Node.js via nvm
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
-source ~/.bashrc
-nvm install 22
-nvm use 22
-node --version
+- **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 (the monthly review rolls it up). `agent/journal.md` keeps the most recent ~12 weekly + 24 monthly sections. SQLite-backed history (messages, agent_actions, dm_conversation_log) 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.
 
-# pnpm
-npm install -g pnpm
+---
 
-# Claude Code CLI
-npm install -g @anthropic-ai/claude-code
-claude --version
+## Compounding intelligence
+
+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
 
-# Optional: secret-tool for keychain support (falls back to file store if absent)
-sudo apt-get install libsecret-tools   # Debian/Ubuntu
-# sudo dnf install libsecret           # Fedora
-# sudo pacman -S libsecret             # Arch
+    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
 ```
 
-#### Windows 10 / 11
+### The implicit feedback loop
 
-Open **PowerShell as Administrator** and run:
+Every interaction shapes Aitne's understanding of you, *implicitly*. No buttons. No surveys. Just talk to it.
 
-```powershell
-# 1. Install nvm-windows
-winget install CoreyButler.NVMforWindows
-# Close and reopen PowerShell, then:
-nvm install 22
-nvm use 22
-node --version   # v22.x.x
-
-# 2. pnpm
-npm install -g pnpm
-pnpm --version   # 10.x.x
-
-# 3. Claude Code CLI
-npm install -g @anthropic-ai/claude-code
-claude --version
+```mermaid
+flowchart LR
+    A["📨 Pre-Action<br/>read user/profile.md<br/>inject preferences"] --> B["🤖 Action<br/>generate response<br/>in your style"]
+    B --> C["👁️ Post-Action<br/>Signal Detector logs:<br/>· ignored notifications<br/>(no reply within 30 min)<br/>· correction phrases<br/>(shorter, in Japanese, …)"]
+    C --> D["🌆 Evening Review<br/>raw signals → character<br/>or → user/profile.md<br/>Learned Context"]
+    D --> A
 ```
 
-> **Long paths (Windows):** if `pnpm install` fails with `ENAMETOOLONG`, run this in an elevated PowerShell and reboot:
-> ```powershell
-> Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1
-> ```
+The Signal Detector (`packages/daemon/src/core/signal-detector.ts`) appends raw entries to `user/profile.md`'s `## Raw Signals` section via the Context File API. The Evening Review (`routine.evening_review`, default `medium` tier — Sonnet) interprets the raw signals on the next pass and clears them.
+
+**Tone-class signals** (corrections like "be shorter", "no preamble") → updates the `character` runtime-config field, applied to the system prompt across all backends.
+**Attribute-class signals** (durable facts like "I'm allergic to nuts", "my partner's name is Mei") → updates `user/profile.md` Learned Context.
 
-> **Antivirus:** Windows Defender's real-time scanning can slow `pnpm install` by ~10×. Adding the project folder to the exclusion list is recommended.
+The Evening Review enforces the line between these: 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).
 
 ---
 
-### Step 2 — Clone and install
+## Talk to it like a person
 
-```bash
-git clone https://github.com/your-org/aitne.git aitne
-cd aitne
-pnpm install
-```
+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.**
 
-> The `pnpm install` step downloads and compiles native binaries (`better-sqlite3`, `onnxruntime-node`, `ffmpeg-static`). No separate C++ toolchain is needed — prebuilt binaries are included for macOS (x64/arm64), Linux (x64/arm64), and Windows (x64).
+| 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 (~80 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 (automation triggers)
+
+Every change is journaled to `agent_actions` with `source_kind=user_directive`. You can audit what was changed and when via `aitne audit`.
 
 ---
 
-### Step 3 — Copy the env file
+## Bring your own harness (BYOH)
 
-```bash
-# macOS / Linux
-cp .env.example .env
+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.
 
-# Windows (PowerShell)
-Copy-Item .env.example .env
-```
+```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
 
-The defaults work for most setups. The only values you might want to change:
+    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
 
-```bash
-PA_DATA_DIR=~/.personal-agent   # where runtime data (SQLite, logs, context MD) lives
-PA_API_PORT=8321                # daemon port
-PA_LOG_LEVEL=info               # trace | debug | info | warn | error
+    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
+    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
 ```
 
-On **Windows**, use a full path instead of `~`:
+### What this means in practice
+
+| 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. |
+| 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. |
+| Skills you wrote for `~/.claude/skills/` | Imported on demand. |
 
+### The growth flywheel
+
+```
+Claude Code / Codex / Gemini ships a new feature
+         ↓
+New connectors, plugins, MCP servers, skills appear
+         ↓
+The backend Aitne controls gets more capable
+         ↓
+You get those capabilities in Aitne — with zero config change
 ```
-PA_DATA_DIR=C:\Users\YourName\.personal-agent
+
+Aitne is a *proxy* over the AI runtimes you already use. As they grow, you grow.
+
+---
+
+## Multi-platform, multi-app
+
+One agent, every surface.
+
+```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"]
+        SV2["📧 Gmail · Outlook · Yahoo · iCloud · IMAP"]
+        SV3["📓 Notion · Obsidian"]
+        SV4["📦 GitHub · local Git"]
+        SV5["🗺️ Google Maps"]
+        SV6["🔧 Custom MCP servers"]
+    end
+
+    AITNE(("🧠 Aitne"))
+
+    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 --> 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, … |
+| 🛡️ **Triple safety model** | SDK permission hooks · daemon API risk tiers · absolute-block layer |
+| 🪪 **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. |
+
+---
+
+## 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)
+
 ---
 
-### Step 4 — Build and launch
+## Quick start
+
+### 1. Install
+
+```bash
+npm install -g @aitne-sh/aitne@latest
+```
+
+This 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
-pnpm start
+# 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
 ```
 
-This compiles all packages (shared → daemon → dashboard) if the build is stale, then launches the daemon and dashboard as background processes.
+Login once with each CLI you intend to use — Aitne auto-detects them.
 
-Verify everything is running:
+### 3. Start
 
 ```bash
-pnpm status
+aitne start
 ```
 
-Expected output:
+The daemon (`:8321`) and dashboard (`:3000`) launch in the background and your browser opens to the setup wizard.
+
+### 4. Confirm
+
+```bash
+aitne status
+```
 
 ```
-Aitne  v0.1.0
+Aitne  v0.1.1
   Daemon     running  pid 12345  uptime 0:00:12  port 8321
   Dashboard  running  pid 12346  uptime 0:00:11  port 3000
+  Today's spend  $0.04
+  Next scheduled  routine.morning_routine  in 6h 12m
 ```
 
-If there are errors, run `pnpm doctor` to diagnose common issues.
+That's it. Open `http://localhost:3000` and finish the wizard.
 
 ---
 
-### Step 5 — Make `aitne` available system-wide
+## Setup guide
 
-From inside the repo you can always run `pnpm <command>`. To use the `aitne` command from any directory, link it globally:
+### Prerequisites
 
-#### macOS / Linux
+| 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) |
 
-```bash
-# Inside the repo directory:
-npm link
+### Step 1 — Install Aitne
 
-# Verify from any directory
-aitne version
+```bash
+npm install -g @aitne-sh/aitne@latest
 ```
 
-If `aitne` is not found after linking, add the npm global bin directory to your PATH:
+> Want to hack on the source? See [Development](#development).
 
-```bash
-# Find the directory
-npm config get prefix
-# e.g. /usr/local or /Users/you/.npm-global
+### Step 2 — Install at least one backend CLI
 
-# Add its bin to PATH (replace with your actual prefix)
-echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
-source ~/.zshrc
-```
+#### Claude Code (recommended)
 
-#### Windows (PowerShell)
+```bash
+npm install -g @anthropic-ai/claude-code
+claude --version
+claude auth login --claudeai      # uses your Claude subscription
+```
 
-```powershell
-# Inside the repo directory:
-npm link
+#### OpenAI Codex CLI
 
-# Verify from any directory
-aitne version
+```bash
+npm install -g @openai/codex
+codex --version
+codex login --device-auth         # device-flow OAuth
 ```
 
-If `aitne` is not found, check the npm global prefix and add it to your PATH:
+#### Google Gemini CLI
 
-```powershell
-npm config get prefix
-# e.g. C:\Users\YourName\AppData\Roaming\npm
+```bash
+npm install -g @google/gemini-cli
+gemini --version
+# OAuth handled automatically on first use
 ```
 
-Open **System Properties → Advanced → Environment Variables**, find `PATH` under User variables, and append the npm prefix path (e.g. `C:\Users\YourName\AppData\Roaming\npm`). Then reopen your terminal.
+You can install all three. Per-process tier routing lets you mix-and-match: Sonnet for hourly checks, Opus for the morning routine, Codex for code-heavy tasks, Gemini for free-tier summarization.
 
----
+### Step 3 — Launch and run the wizard
 
-### Step 6 — Complete the setup wizard
+```bash
+aitne start
+```
+
+Aitne builds (if needed), launches both processes, and opens `http://localhost:3000/setup`. The wizard walks through:
 
-Open `http://localhost:3000` in your browser (the dashboard opens automatically on `pnpm start`).
+1. **Backend** — default backend (Claude / Codex / Gemini)
+2. **Vault mode** — plain (`~/.personal-agent/context/`) or your existing Obsidian vault
+3. **Execution mode** — *Safe* (strict) or *Allow* (relaxed for plugins/MCP). Absolute-block layer holds in both.
+4. **Google** — OAuth for Gmail and Calendar (optional)
+5. **Messaging platforms** — Slack, Telegram, Discord, WhatsApp (optional)
+6. **Integrations** — `direct` / `delegated` / `disabled` per service
+7. **Character** — free-form 1,000-char tone & style description
 
-The setup wizard walks through:
+After the wizard, every option has a settings page in the sidebar.
 
-1. **Backend** — enter your `ANTHROPIC_API_KEY` (or `OPENAI_API_KEY` / `GEMINI_API_KEY`). API keys are required for headless agent use; the wizard flags any backend that falls back to a CLI subscription login.
-2. **Vault mode** — choose a plain filesystem context directory or point to your Obsidian vault.
-3. **Execution mode** — Safe (strict permission checks) vs. Allow (enables plugins and MCP servers). Destructive ops are blocked in both modes.
-4. **Google** — connect Gmail and Google Calendar via OAuth if needed.
-5. **Integrations** — Mail, Notion, GitHub, messaging platforms (Slack, Telegram, Discord, WhatsApp).
+### Step 4 — Verify
 
-After the wizard you can reach any settings page via the sidebar.
+```bash
+aitne status         # PIDs, uptime, integrations, today's spend
+aitne doctor         # 8-point install diagnostic
+aitne logs -f        # tail the daemon log
+```
 
 ---
 
 ## CLI reference
 
-All commands work both as `aitne <cmd>` (after `npm link`) and as `pnpm <cmd>` (from inside the repo).
-
 ### Lifecycle
 
-| Command | Description |
-|---------|-------------|
-| `aitne start [--no-open]` | Build if stale, then 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, integrations, today's spend, last action, next scheduled item |
-| `aitne logs [-f] [-n N] [-d]` | Tail daemon log (`-d` for dashboard log, `-f` to follow, `-n N` for last N lines) |
-| `aitne dev` | Foreground mode with full stdio (development) |
-| `aitne build` | Compile all packages explicitly |
+| 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 [--clean-context]` | Stop then start. `--clean-context` wipes `context/` after a tarball backup. |
+| `aitne status` | PIDs, uptime, integrations, 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). |
 
 ### Operations
 
-| Command | Description |
-|---------|-------------|
-| `aitne setup` | (Re-)open the dashboard `/setup` wizard; auto-starts the daemon if needed |
-| `aitne open` | Open the dashboard in your browser |
-| `aitne doctor` | Diagnose install: Node, ports, OS keychain, backend CLIs, native bindings, agent-assets |
-| `aitne audit [--since 24h] [--type X] [--result failed]` | View the agent action log (`--json` for machine-readable) |
-| `aitne version [--json]` | Print 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, then offer to wipe `~/.personal-agent` |
-
-### Development / testing
-
-| Command | Description |
-|---------|-------------|
-| `pnpm test` | Run unit tests (vitest) |
-| `pnpm test:watch` | Watch mode |
-| `pnpm lint` | ESLint across all packages |
-| `pnpm clean` | Remove all build artifacts and node_modules |
+| 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` | 8-point install diagnostic. |
+| `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 (e.g. `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. |
+
+### `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 to `--version`
+6. `~/.personal-agent` exists and is writable
+7. `better-sqlite3` native binding loads
+8. `agent-assets/skills/` is reachable
 
 ---
 
-## Troubleshooting
+## Architecture
 
-### `pnpm start` fails with "dist not found"
+```mermaid
+flowchart TB
+    subgraph PLAT["📱 Input platforms"]
+        direction LR
+        P1[Slack]
+        P2[Telegram]
+        P3[Discord]
+        P4[WhatsApp]
+        P5[Dashboard]
+    end
+
+    subgraph DAEMON["⚙️ Aitne daemon (Hono :8321)"]
+        direction TB
+        EB[EventBus<br/>priority heap]
+        DI[Dispatcher<br/>semaphore: 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]
+    end
+
+    subgraph BACKENDS["🧠 AI runtimes"]
+        direction LR
+        BC[Claude Code SDK]
+        BX[Codex CLI subprocess]
+        BG[Gemini CLI subprocess]
+    end
+
+    subgraph DATA["💾 Local data"]
+        direction LR
+        SQL[(SQLite<br/>WAL + FTS5)]
+        MD["📝 Markdown memory<br/>~/.personal-agent/context/"]
+        KC[OS Keychain]
+    end
+
+    PLAT --> EB
+    SC --> EB
+    OB --> SQL
+    SQL -- "hourly check pulls" --> EB
+    EB --> DI
+    DI --> BR
+    BR --> AC
+    AC --> BC
+    AC --> BX
+    AC --> BG
+    AC <-->|curl localhost API| DAEMON
+    DAEMON <--> SQL
+    DAEMON <--> MD
+    DAEMON <--> KC
+```
 
-The build did not complete. Run `pnpm build` explicitly and check for TypeScript errors.
+### Two execution paths
 
-### Port already in use
+**Reactive path** — owner DMs/mentions, cron routines, calendar approach events, scheduled tasks
+→ Event source → EventBus → Dispatcher → BackendRouter → Agent → output to user
 
-Change `PA_API_PORT` in `.env` if port 8321 conflicts. To find the conflicting process:
+**Polling path** — Obsidian, Git, GitHub, Notion, Calendar, Mail change detection
+→ Observer → `observations` table (UPSERT, with `actor='user'|'agent'`)
+… time passes …
+→ Hourly cron → Dispatcher.triggerHourlyCheck → agent reads pending → updates today.md / roadmap.md → notifies if needed
 
-```bash
-# macOS / Linux
-lsof -i :8321
+The `AgentWriteTracker` prevents agent → observer → agent loops by tagging the agent's own writes so the hourly check filters them out.
+
+### Repo layout
 
-# Windows (PowerShell)
-netstat -ano | findstr :8321
 ```
+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
 
-### `aitne` command not found after `npm link`
+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 API, Calendar, Mail, …)
+├── task-flows/      # Per-event prompt templates (one per event type)
+└── templates/       # Scaffold MD copied to context/ on first run
 
-Run `npm config get prefix` to find the global bin directory and ensure it is on your `PATH`.
+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
+```
 
-### SQLite errors on startup
+---
 
-If you see `SQLITE_CORRUPT` or similar, the database can be reset safely — all agent memory is in `~/.personal-agent/context/` which is untouched:
+## Memory layout
 
-```bash
-aitne stop
-# macOS / Linux
-rm ~/.personal-agent/data/personal_agent.db*
-# Windows (PowerShell)
-Remove-Item "$env:USERPROFILE\.personal-agent\data\personal_agent.db*"
+Everything the agent writes lives under `PA_DATA_DIR` (default `~/.personal-agent`):
 
-aitne start
+```
+~/.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 (90 d retention)
+│   ├── weekly/<YYYY-Www>.md   # Weekly review (1 yr)
+│   ├── monthly/<YYYY-MM>.md   # Monthly review (3 yr)
+│   ├── 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 (`<name>.enc`); empty when OS keychain is used
+└── run/                       # PID files for daemon + dashboard
 ```
 
-### Windows: `node` not found in a new terminal
+### Always-injected context
 
-Run `nvm use 22` — nvm-windows must be activated per terminal until you set a default: `nvm alias default 22`.
+Every session starts with `user/profile.md` + `rules/management.md` + `today.md` injected. The agent never has to "search for context."
 
-### Linux: secret storage warnings
+### Write chokepoint
 
-Install `libsecret-tools` (see [Step 1](#step-1--install-prerequisites)) or set a master password for the file-based fallback:
+Context-MD writes go through `curl http://localhost:8321/api/context/<path>` rather than the SDK's `Edit`/`Write` tools. This is enforced by skill instructions plus the absolute-block path globs that deny SDK writes to secret paths (`.env`, `~/.ssh`, `~/.aws`, `~/.personal-agent/secrets/**`, …). Routing context writes through the daemon API gives a single chokepoint for locks (`today.md` write lock), frontmatter validation, and snapshots (30-day `md_file_snapshots` retention).
 
-```bash
-export PA_MASTER_PASSWORD='use-a-long-random-string'
-```
+---
+
+## Multi-backend
+
+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 |
+
+### 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 | Observation aggregation |
+| `routine.hourly_check.triage` | lite | Stage 2 triage gate (escalate vs log-only) |
+| `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 |
+| `observation.summarize` | lite | Per-observation classification |
+
+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`.
 
 ---
 
-## Platform notes
+## Integrations
 
-| Concern | macOS | Linux | Windows |
+### Messaging
+
+| Platform | Library | Mode | Setup |
 |---|---|---|---|
-| Secret storage | Keychain (`security`) | `secret-tool` (libsecret); AES file store fallback | DPAPI via `powershell.exe`; AES file store fallback |
-| Folder picker | `osascript` | `zenity` / `kdialog` / `yad` | `System.Windows.Forms.FolderBrowserDialog` |
-| Process tree kill | POSIX process group | POSIX process group | `taskkill /T /F` |
-| Log tailing (`-f`) | Node tailer | Node tailer | Node tailer — no `tail` binary needed |
-| Console windows | n/a | n/a | Background spawns hide the console window |
+| 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 |
+| 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 |
+| **Outlook** | `@azure/msal-node` Graph API | Read · send · drafts · folders |
+| **Yahoo** | IMAP + OAuth2 | Read · send |
+| **iCloud** | IMAP + app password | Read · send |
+| **Generic IMAP** | username + password | Read |
+
+Local FTS5 full-text search runs across **every** account via `GET /api/mail/search?q=...`.
+
+### Knowledge & docs
+
+- **Obsidian** — read directly via `Read`; write via the official Obsidian CLI 1.12+ (`obsidian create`, `obsidian append`, `obsidian daily:append`, …); chokidar watches the vault for user edits
+- **Notion** — `@notionhq/client` REST API; full page + database CRUD
+- **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`
+
+### Calendar & travel
+
+- **Google Calendar** — full event CRUD, freebusy, calendar list, 15-min approaching reminders
+- **Google Maps** — Directions API for travel-time estimation tied to calendar events
+
+### Lifestyle
+
+- **Receipts** — auto-extracts PDF/image attachments from Gmail with category detection
+- **Travel bookings** — auto-extracts flight, hotel, restaurant, train confirmations
+- **Reading** — Kindle My Clippings importer; reading-taste profile; weekly book recommendations
+
+### Integration delegation modes
+
+Each integration runs in one of three modes:
+
+| Mode | Auth held by | Setup cost | Capabilities |
+|---|---|---|---|
+| **`direct`** | Daemon (OAuth in OS Keychain) | 5–6 vendor-console steps | Full feature set |
+| **`delegated`** | Backend's connector | None | Reduced (whatever the connector exposes) |
+| **`disabled`** | — | — | Off |
+
+Delegated mode lets you skip OAuth setup entirely if your backend already has a connector for the service. Aitne handles `same-backend` (no daemon hop) and `cross-backend` (daemon spawns a one-shot subprocess of the delegated backend) transparently.
+
+---
+
+## Safety model
+
+Aitne uses three independent safety layers that hold in **every** execution mode:
+
+### Layer 1 — SDK permission model
+
+```typescript
+// strict (Safe) mode — packages/daemon/src/core/backends/claude-code-core.ts
+permissionMode: "dontAsk"
+allowedTools:    ["Read", "Glob", "Grep", "Write", "Edit", "Skill",
+                  "Bash(curl *)", "Bash(git *)", "Bash(jq *)"]
+disallowedTools: DEFAULT_DISALLOWED_TOOLS  // ALWAYS_DISALLOWED + chmod/chown/git --force/reset --hard/clean
+// Write/Edit on secret paths (.env, ~/.ssh, ~/.aws, ~/.personal-agent/secrets, …)
+// are blocked by path-glob entries in the absolute-block layer.
+```
+
+### Layer 1.5 — PreToolUse hooks
 
-### WSL (Windows Subsystem for Linux)
+Every `curl` invocation has its destination URL parsed and checked. Anything that isn't `http://localhost:8321` is denied. Variable expansion (`$URL`) is resolved before the check.
 
-Under WSL the daemon detects the Linux kernel and uses the file-based secret store because GNOME Keyring / D-Bus are typically unavailable. Set `PA_MASTER_PASSWORD` or write it to `~/.personal-agent/secrets/.master-key` (`chmod 600`).
+### Layer 2 — Daemon API risk tiers
+
+| Tier | Examples | Auth required |
+|---|---|---|
+| **Autonomous** | `GET /api/context/*`, `POST /api/notify`, `POST /api/schedule` | 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` | Bearer |
+
+### Absolute-block layer (`ALWAYS_DISALLOWED_TOOLS`)
+
+Hard-blocked in **both Safe and Allow** modes. Even `bypassPermissions` cannot widen past this:
+
+- Recursive delete: `rm -rf *`, `rm -r *`
+- 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/**`
+
+### 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 & 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` `maxBudgetUsd` hard cap | $0.50 | no (compile-time) |
+
+### Typical day's spend
+
+```
+04:00  Morning Routine  (Opus / 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      (Opus)            ~$0.10
+18:00  Evening Review   (Sonnet)          ~$0.15
+─────────────────────────────────────────────────
+Total                                     ~$0.51
+```
+
+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 a **bootstrap-only** file. Runtime settings (notification limits, model tiers, quiet hours, active windows, etc.) are managed through the dashboard after first launch. Secrets (API keys, tokens) are stored in the OS-native credential store — never in `.env`.
+`.env` is **bootstrap-only**. Everything else is editable from the dashboard at runtime — or via natural-language DMs to the agent.
 
-Messaging platforms can be pre-configured via env vars before first launch:
+### `.env` (bootstrap)
+
+```bash
+PA_DATA_DIR=~/.personal-agent     # macOS / Linux
+# PA_DATA_DIR=C:\Users\You\.personal-agent  # Windows
+PA_API_PORT=8321
+PA_DASHBOARD_PORT=3000
+PA_LOG_LEVEL=info                 # trace | debug | info | warn | error
+```
+
+### Pre-seeding messaging via env (optional)
 
 ```bash
 # Slack
@@ -373,92 +980,218 @@ PA_GIT_REPOS='["/path/to/repo1"]'
 PA_GITHUB_REPOS='["owner/repo"]'
 ```
 
-Google Calendar, Gmail, and Notion are connected via the dashboard OAuth / token flow after startup.
+Google services (Gmail, Calendar) and Notion are connected via OAuth from the dashboard `/connections` page after first launch — no env vars required.
+
+### Runtime settings
+
+The dashboard `/settings` tree exposes ~80 runtime keys. The headline ones:
+
+- **Schedule** — `timezone`, `dayBoundaryHour`, hourly check window & 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
+
+…or just DM the agent: *"Don't run hourly checks on weekends."*
 
 ---
 
-## Runtime data
+## Platform support
 
-Everything lives under `PA_DATA_DIR` (default `~/.personal-agent`):
+| Concern | 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` |
+| **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
+
+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
 ```
-~/.personal-agent/
-├── context/                    # Agent memory — edit any file by hand at any time
-│   ├── context-index.md        # Living index of every context file (auto-maintained)
-│   ├── today.md                # Today's plan + agent log
-│   ├── roadmap.md              # Long-term goals and upcoming milestones
-│   ├── user/
-│   │   ├── profile.md          # Your profile (background, preferences, style)
-│   │   ├── people.md           # People the agent should know about
-│   │   └── …                   # goals.md, expertise.md, personal.md, work.md
-│   ├── rules/                  # Policy files (agent + user co-authored)
-│   ├── routines/               # Per-cadence checklist rulebooks
-│   ├── dossiers/               # Per-routine carry-forward state
-│   ├── daily/                  # Synthesized daily journals (YYYY-MM-DD.md)
-│   ├── projects/               # One file per active project
-│   ├── weekly/                 # Weekly review archives
-│   └── monthly/                # Monthly review archives
-├── data/
-│   └── personal_agent.db       # SQLite: sessions, schedule, observations, cost
-├── logs/
-│   ├── daemon.log
-│   └── dashboard.log
-└── bin/
-    └── auth.token              # Bearer token for dashboard API access
-```
-
-The agent reads and writes `context/` exclusively through the daemon API. You can edit any file by hand at any time; the agent picks up changes on the next routine run.
 
 ---
 
-## Repo structure
+## 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` in `.env`. To find the conflicting process:
 
+```bash
+# macOS / Linux
+lsof -i :8321
+
+# Windows
+netstat -ano | findstr :8321
 ```
-packages/
-├── daemon/      # Node.js daemon — event bus, scheduler, adapters, API (Hono)
-├── dashboard/   # Next.js 16 + React 19 + Tailwind 4 + shadcn/ui
-└── shared/      # Types, Zod schemas, date utilities (no runtime deps)
 
-agent-assets/
-├── agent-profiles/   # Agent persona definitions (per-backend: CLAUDE.md / AGENTS.md / GEMINI.md)
-├── skills/           # Built-in skill docs (Context API, Calendar, Gmail, MCP, roadmap, …)
-├── task-flows/       # Per-event prompt templates (morning routine, hourly check, DM, …)
-└── templates/        # Scaffold files copied to context/ on first run
+### `aitne` not found after `npm install -g`
 
-docs/design/          # Architecture and design docs (v4.15)
-scripts/              # Build and run helpers
-bin/aitne.mjs         # CLI entry point
+```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:
+
+```bash
+aitne stop
+rm ~/.personal-agent/data/personal_agent.db*           # macOS / Linux
+# Remove-Item "$env:USERPROFILE\.personal-agent\data\personal_agent.db*"  # Windows
+aitne start
+```
+
+### Backend auth expired
+
+```bash
+aitne doctor                           # confirms which backend failed
+claude auth login --claudeai           # 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
 
+For contributors:
+
 ```bash
-pnpm dev              # run daemon + dashboard in foreground (full stdio)
-pnpm test             # vitest — unit tests across packages/*
-pnpm test:watch       # watch mode
-pnpm lint             # ESLint
-pnpm --filter @personal-agent/daemon build   # build one package
-pnpm clean            # remove all build artifacts and node_modules
+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
 ```
 
-Tests live alongside source as `foo.ts` + `foo.test.ts`. Coverage thresholds are enforced on pure-logic modules. Integration-heavy files (adapters, I/O, framework glue) are explicitly excluded from thresholds.
+### Tech stack
+
+| Layer | Stack |
+|---|---|
+| **Daemon** | Node.js 22 · Hono · `@anthropic-ai/claude-agent-sdk` · `@slack/bolt` · `telegraf` · `discord.js` · `baileys` · `googleapis` · `@notionhq/client` · `@octokit/rest` · `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 |
+| **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 (v4.16) is the authoritative spec; `packages/daemon/src/` is the source of truth when they diverge
+
+### Source-of-truth pointers
+
+| If you need to… | Start in |
+|---|---|
+| Understand startup order | `packages/daemon/src/index.ts` |
+| Change event routing | `src/core/dispatcher.ts` + `src/core/event-bus.ts` |
+| Add a backend or change tier mapping | `packages/shared/src/process-key.ts` + `src/core/backends/backend-router.ts` |
+| Add an API route | `src/api/routes/` + register in `src/api/server.ts` |
+| Add an integration | `src/services/<name>/` + `src/observers/` (if polling) + `src/api/routes/` |
+| 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 auth health / recovery | `src/core/backends/auth-health-monitor.ts` + `auth-recovery.ts` |
 
 ---
 
-## Safety
+## FAQ
+
+**Is Aitne a chatbot?**
+No. It's a daemon. It also responds to chat, but the more interesting half is what it does *while you're not looking at it*.
+
+**Does it phone home?**
+No. The daemon binds to `127.0.0.1` only. There is no telemetry. Verify with `lsof` and `nettop`.
 
-The agent operates within strict guardrails:
+**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/`.
 
-- **Context write chokepoint** — the agent writes context files only via `curl /api/context/*`. Direct file writes into the context directory are blocked by SDK hooks regardless of execution mode.
-- **Localhost-only API** — the daemon binds to `127.0.0.1`; SDK hooks reject any `curl` call to a host other than `localhost:8321`.
-- **Risk tiers** — every endpoint is classified: Autonomous / ReadSensitive / Notify / Approve. The dashboard requires a Bearer token; all agent calls are localhost-only.
-- **Disallowed tools** — `rm -rf`, `sudo`, force-push, and reads of `~/.ssh`, `~/.aws`, `.env`, and OS Keychain files are hard-blocked regardless of permission mode.
-- **No financial transactions, no automated social posting, no multi-user access.**
+**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?**
+You don't need a metered API key — 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-byoh).
+
+**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 agent's internal Markdown memory is multilingual; what's stored is what you say.
+
+**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.
 
 ---
 
 ## 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>