@aitne-sh/aitne 0.1.7 → 0.1.9

package/agent-assets/docs/guides/backup-and-restore.md

@@ -3,22 +3,40 @@ schema_version: 1
 slug: guides/backup-and-restore
 title: Backup and Restore
 id: backup-and-restore
+aliases:
+  - backup
+  - restore
+  - tarball backup
+  - context backup
 category: guides
 summary: |
-  Aitne's data lives in two places — the SQLite database and
-  the context Markdown files. Back both up and restoration is a tar
-  extract.
+  Aitne's durable state lives in one directory — PA_DATA_DIR
+  (~/.personal-agent), holding the SQLite database and the context
+  Markdown vault. Back it up with a tar after stopping the daemon;
+  restoring is a tar extract. Secrets live in the OS keychain, not
+  this directory, so re-register them after a restore.
 section: backup-and-restore
 tags:
-  - guide
+  - guides
   - operations
+  - backup
 status: stable
 ask_examples:
   - How do I back up Aitne?
   - Can I restore on a new machine?
+  - Why are my API keys gone after restoring a backup?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - backup
+  - restore
+  - tarball
+  - PA_DATA_DIR
+  - snapshot
+  - keychain
+  - secrets
+  - SQLite
 related:
   - guides/reinstall-cleanly
   - guides/migrate-machines
@@ -28,25 +46,85 @@ related:
 
 ## Goal
 
-Capture all Aitne state in a tar that you can restore later.
+Capture all of Aitne's durable state in a single tar archive you can
+restore later — on this machine or a fresh one.
+
+## What's in the backup (and what isn't)
+
+Everything Aitne persists lives under `PA_DATA_DIR` (default
+`~/.personal-agent`), so backing up that one directory captures it all:
+
+- `data/personal_agent.db` — sessions, actions, observations, FTS index
+  (plus the `-wal` / `-shm` companion files while the daemon runs).
+- `context/` — the Markdown memory vault (today, roadmap, journal,
+  knowledge, identity, policies, …).
+- Logs, PID files, and prompts.
+
+**Not in the tar — re-register these after a restore:**
+
+- **Secrets** (Anthropic / OpenAI / Google API keys, etc.) live in the
+  OS keychain, *not* under `~/.personal-agent`, so a tar never includes
+  them.
+- **Messaging pairings** (Slack / Telegram / Discord / WhatsApp tokens)
+  are likewise keychain-backed.
+
+Both are re-added through the dashboard after restore.
 
 ## Steps
 
-1. `pa stop`.
-2. `tar -czf personal-agent-backup-$(date +%F).tgz ~/.personal-agent/`.
-3. To restore: extract the tar to your home directory, then `pa start`.
+1. **Stop the daemon** so the SQLite write-ahead log is checkpointed and
+   the snapshot is consistent:
+
+   ```bash
+   aitne stop
+   ```
+
+2. **Create the archive** (capturing the whole data directory in one
+   shot):
+
+   ```bash
+   tar -czf personal-agent-backup-$(date +%F).tgz ~/.personal-agent/
+   ```
+
+3. **Restore** by extracting the tar to your home directory, then
+   starting the daemon:
+
+   ```bash
+   tar -xzf personal-agent-backup-2026-05-28.tgz -C ~/
+   aitne start
+   ```
+
+   Schema migrations run automatically on the first boot (see below), so
+   an older DB is brought up to the current shape without extra steps.
+
+4. **Re-register secrets and re-pair messaging** through the dashboard —
+   they were never in the tar.
 
 ## Verification
 
-- Activity feed shows historical rows after restore.
+- `aitne status` reports the daemon healthy.
+- The Activity feed shows your historical rows after restore.
 - Context files match the originals.
 
 ## If It Fails
 
-- A schema-version mismatch: Aitne's policy is "clean
-  reinstall, no data migration" — if the restored DB is from an
-  older daemon version, drop the DB and re-seed from the context
-  files.
+- **Schema mismatch on restore.** Aitne ships forward-only schema
+  migrations applied automatically at boot (see
+  [Schema Migration](../glossary.md#schema-migration)), so a restored DB
+  from an older daemon version usually just works — the migration runner
+  brings it up to the current shape on the next start. Only fall back to
+  dropping the DB (see [Reinstall Cleanly](reinstall-cleanly.md)) if the
+  daemon refuses to start *after* you've checked the log
+  (`aitne logs`) for a real migration error.
+- **The agent can't reach its backends after restore.** That's the
+  missing keychain secrets — re-add your API keys in the dashboard
+  (Step 4). The DB and context restore fine without them.
+
+## Moving to a different machine?
+
+This guide backs up and restores in place. To copy state to another host
+(including the keychain re-registration walkthrough), follow
+[Migrate Machines](migrate-machines.md).
 
 ## Related
 

package/agent-assets/docs/guides/budget-and-cost-for-wiki.md

@@ -15,9 +15,10 @@ summary: |
   to tune the threshold.
 section: budget-and-cost-for-wiki
 tags:
-  - guide
+  - guides
   - wiki
   - cost
+  - approval
 status: stable
 ask_examples:
   - How much does !compile full cost?
@@ -26,62 +27,95 @@ ask_examples:
   - What does the pre-compile snapshot do?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
+keywords:
+  - wiki budget
+  - wiki cost
+  - wiki cost gate
+  - wiki approval
+  - compile cost
+  - compile full
 related:
   - features/wiki/overview
   - features/wiki/commands
+  - features/wiki/cost-and-approval
   - concepts/costs-and-quotas
   - troubleshooting/wiki-ingest-full-blocked
+process_keys:
+  - wiki.compile
+  - wiki.ingest_url
+  - wiki.ask
+api_endpoints:
+  - PATCH /api/wiki/workspaces/:workspace
+  - POST /api/approvals/:id/approve
+  - POST /api/approvals/:id/deny
 ui_anchors:
   - /settings/wiki
-  - /approvals
+  - /
 ---
 
 # Wiki Budgets and Cost
 
 The wiki ships with three cost knobs you can tune in
-**Settings → Wiki**:
-
-1. **Per-command model selector** for each of the three wiki
-   processes (`wiki.ingest_url`, `wiki.compile`, `wiki.ask`).
-   Defaults to your main backend at the medium tier; downgrade
-   `wiki.ingest_url` to a lite tier if you ingest a lot of URLs.
+**Settings → Wiki** (`/settings/wiki`):
+
+1. **Per-command model selector** for each wiki process. The model
+   picker covers the full set: `wiki.ingest_url`, `wiki.compile`,
+   `wiki.ask`, plus the operational triad `wiki.lint`, `wiki.trace`,
+   `wiki.connect`. Each defaults to your main backend at the medium
+   tier; downgrade `wiki.ingest_url` to a lite tier if you ingest a
+   lot of URLs.
 2. **Per-process budget cap** (`max_budget_usd` on each row). The
    dispatcher's per-session budget envelope is the enforcer.
 3. **Per-workspace `!compile full` approval threshold** (default
-   $2.00). The dashboard cost estimator brackets the expected spend
-   at 0.5× / 1× / 2× the assumed input-token count; if the
-   pessimistic estimate breaches the threshold, the bang handler
+   $2.00, range $0–$100). The cost estimator brackets the expected
+   spend at 0.5× / 1× / 2× the estimated input-token count; if the
+   pessimistic (2×) estimate breaches the threshold, the bang handler
    escalates to the approval queue instead of running autonomously.
 
 ## What the Estimator Does
 
 `!compile full` is the most expensive wiki command because a full
 rebuild touches every raw note. The estimator is **pure JS** — it
-does not spawn an agent — and computes:
+does not spawn an agent (spawning one to estimate would itself burn
+budget). It walks the `10_raw/` layer, approximates each file's token
+count from its on-disk character count, sums the total, and brackets:
 
 ```
-expected_usd = raw_count × avg_input_tokens_per_raw × $0.003 / 1k tokens
+expected_usd = total_estimated_input_tokens / 1000 × $0.003
 optimistic   = 0.5 × expected
 pessimistic  = 2.0 × expected
 ```
 
-Defaults: `avg_input_tokens_per_raw = 1500`, the unit cost matches
-Sonnet 4.6's $3 / Mtoken input price. The bracket lets you see a
-worst-case before approving.
+Per-file token approximation is script-aware: ~4 characters per token
+for Latin/prose, ~1.5 for majority-CJK files, with a 200-token floor
+per file so empty or one-line stubs still account for the fixed
+per-call overhead (system prompt, skills bundle, tool docs). The unit
+cost (`$0.003` per 1k tokens) matches Claude Sonnet 4.6's ~$3 /
+Mtoken input price. The bracket lets you see a worst case before
+approving.
+
+> The dashboard surfaces the top raw files by estimated token count,
+> so you can see which sources dominate the bill before approving.
+> An older flat heuristic (`raw_count × 1500 tokens`) survives as an
+> opt-in fallback for deterministic banner copy, but the default is
+> the per-file character scan described above.
 
 ## Where the Gate Fires
 
 - **Below threshold**: the compile runs autonomously and you get a
   completion DM with actual spend.
 - **Above threshold**: the bang handler inserts an `agent_schedule`
-  row with `task_type='approval'` and DMs the estimate. The
-  dashboard `/approvals` view (also reachable from Notifications)
-  is where you click **Approve** — that flips the row to
-  `approved_task` and the scheduler picks it up.
+  row with `task_type='approval'`, DMs you the estimate, and pauses.
+  The request shows up as an **Approvals** card on the dashboard home
+  page (`/`); the `/settings/wiki` page also points you there.
+  Clicking **Approve** flips the row to `task_type='approved_task'`
+  and the scheduler picks it up — only then is the pre-compile git
+  snapshot taken (see below) and the compile session spawned.
 
 If you change your mind, hit **Deny** on the approval card — the row
-flips to `skipped` and no agent session is spawned.
+flips to `skipped`, no git commit is made, and no agent session is
+spawned.
 
 ## Git Pre-Compile Snapshot
 
@@ -100,9 +134,12 @@ deterministic so you can roll back with `git reset --hard HEAD~1` if
 the compile produces a surprise. The `--no-verify` flag is not used —
 your pre-commit hooks run as normal.
 
-If your vault is not a git repo, the approval-gate DM appends
-"no git backup taken" so you can decide whether to add one before
-approving.
+The estimate DM tells you which snapshot path applies:
+**"will commit before compile starts"** (clean repo), **"not taken
+(no git repo)"**, **"disabled by setting"** (auto-commit off), or
+**"not applicable"** for internal-mode workspaces — those recover via
+`md_file_snapshots` instead of git. When no git backup will be taken,
+you can decide whether to add one before approving.
 
 ## Tuning the Threshold
 

package/agent-assets/docs/guides/build-your-wiki.md

@@ -3,6 +3,11 @@ schema_version: 1
 slug: guides/build-your-wiki
 title: Build Your Wiki
 id: build-your-wiki
+aliases:
+  - build wiki
+  - wiki walkthrough
+  - first wiki
+  - ingest compile
 category: guides
 summary: |
   Enable the internal wiki, send your first URL, compile the raw
@@ -11,18 +16,37 @@ section: build-your-wiki
 tags:
   - guide
   - wiki
+  - knowledge
 status: stable
 ask_examples:
   - How do I start using the wiki?
   - How do I add my first source to the wiki?
+  - How do I compile my ingested notes into wiki articles?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
+keywords:
+  - wiki
+  - build wiki
+  - "!ingest"
+  - "!compile"
+  - "!ask"
+  - workspace
+  - first day wiki
+ui_anchors:
+  - /wiki
+  - /settings/wiki
+process_keys:
+  - wiki.ingest_url
+  - wiki.compile
+  - wiki.ask
 related:
   - features/wiki/overview
   - features/wiki/commands
   - guides/use-an-existing-obsidian-vault
   - guides/budget-and-cost-for-wiki
+prerequisites:
+  - features/messaging/pairing-and-magic-phrase
 ---
 
 # Build Your Wiki
@@ -35,7 +59,8 @@ article, and run a question against the result.
 ## Prerequisites
 
 - A paired messaging channel (Telegram, Slack, Discord, WhatsApp, or
-  dashboard chat).
+  dashboard chat) — see
+  [Pairing and the Magic Phrase](../messaging/pairing-and-magic-phrase.md).
 - The daemon is running and the dashboard is reachable.
 
 ## Where you'll work in the dashboard
@@ -60,10 +85,12 @@ you enable a workspace, so you do not need to remember the URL.
 1. Click **My Life → Wiki** in the sidebar (`/wiki`). The page shows
    a "Wiki not enabled" card with an **Enable Wiki** button —
    clicking it jumps you to `/settings/wiki`.
-2. On the settings page, click **Enable Internal Workspace**. The
-   daemon creates `$PA_DATA_DIR/wiki/` and seeds `90_meta/taxonomy.md`
-   plus the schema templates. (To point at an existing Obsidian
-   vault instead, follow
+2. On the settings page, click **Enable internal wiki**. The daemon
+   creates the workspace under your context vault at
+   `knowledge/wiki/` (the daemon-owned default root) and seeds the
+   skeleton: `10_raw/`, `20_wiki/`, `30_outputs/`, `90_meta/` plus
+   `90_meta/taxonomy.md` and the schema templates. (To point at an
+   existing Obsidian vault instead, follow
    [Use An Existing Obsidian Vault](use-an-existing-obsidian-vault.md).)
 3. The sidebar's **My Life → Wiki** entry now lands on a workspace
    summary instead of the disabled CTA. Open it to confirm the root

package/agent-assets/docs/guides/change-which-model-handles-x.md

@@ -6,42 +6,103 @@ id: change-which-model-handles-x
 aliases:
   - per-process tier
   - per-process model
+  - pin a process key
 category: guides
 summary: |
-  Pin a specific ProcessKey to a non-default backend / tier — for
-  example, run morning routine on Sonnet to save Opus tokens.
+  Pin a single ProcessKey to a non-default backend or model tier — for
+  example, move the evening review onto Opus (high tier) for deeper
+  reasoning, or run a routine on Codex while Claude stays the default.
 section: change-which-model-handles-x
 tags:
   - guide
   - backends
+  - operations
+  - routing
 status: stable
 ask_examples:
-  - How do I make my morning routine use Sonnet instead of Opus?
+  - How do I make one routine use Opus instead of Sonnet?
+  - How do I pin the evening review to a different backend?
+  - Can I change the model for just one ProcessKey?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - per-process model
+  - /settings/models
+  - process binding
+  - tier override
+  - change model
+  - pin process key
 related:
   - guides/switch-default-backend
   - concepts/backends-and-tiers
+  - concepts/process-keys
+ui_anchors:
+  - /settings/models
+  - /activity
+process_keys:
+  - routine.morning_routine
+  - routine.evening_review
+  - message.dm
+  - dashboard.docs_qa
+  - delegated_task_heavy
+config_keys:
+  - delegatedTaskHeavyEnabled
 ---
 
 # Change Which Model Handles X
 
 ## Goal
 
-Override the default tier or backend on a single ProcessKey.
+Override the default backend or model tier for a **single** ProcessKey
+without changing the global default. Use this when one surface needs a
+stronger (or cheaper) model than the seeded default — for example,
+pinning the evening review to Opus (high tier), or pushing a noisy
+delegated routine onto Gemini to save Claude quota.
 
 ## Steps
 
 1. Open `/settings/models`.
-2. Find the ProcessKey row in the table.
-3. Pick its main backend and tier explicitly.
-4. Save.
+2. Find the ProcessKey row in the per-process table (e.g.
+   `routine.evening_review`).
+3. Set its **main backend** and **tier** explicitly. The tier maps to a
+   model class — `lite` → Haiku-class, `medium` → Sonnet-class,
+   `high` → Opus-class. Optionally set a **fallback** backend too.
+4. Save. The row is now marked operator-edited and will keep your pin
+   through a defaults reset (only an install-time `force` re-seed
+   overwrites it).
+
+## Concrete Example
+
+To give the evening review deeper reasoning, set
+`routine.evening_review` → main `claude`, tier `high`. The next evening
+run resolves to **Opus 4.8** instead of the default Sonnet 4.6. The
+execution budget for that run also scales with the tier (high tier
+carries a larger turn / cost envelope than medium).
 
 ## Verification
 
-- The next fire of that ProcessKey shows the new model in Activity.
+- The next fire of that ProcessKey shows the new backend and model in
+  the **Activity** event detail (after fallback resolution).
+
+## Caveats
+
+- **`dashboard.docs_qa` is tier-locked to `medium`** — a high/lite pin
+  on that row is ignored by the router. It also inherits its backend
+  from `message.dm`'s pin.
+- **High tier is opt-in, not auto-selected.** No install-time-seeded
+  surface defaults to high; the only `high`-tagged ProcessKey shipped is
+  `delegated_task_heavy`, gated behind the `delegatedTaskHeavyEnabled`
+  config flag. Any *other* ProcessKey can still be pinned to high here.
+- **On Codex and Gemini there is no separately-seeded high model** —
+  their high tier collapses to the medium model, so pinning those
+  backends to high won't change the model unless you pick a specific
+  higher model in the row.
+- To change the backend for *every* ProcessKey at once, use the global
+  default instead — see Related.
 
 ## Related
 
 - [Switch the Default Backend](switch-default-backend.md)
+- [Backends and Tiers](../concepts/backends-and-tiers.md)
+- [Process Keys](../concepts/process-keys.md)

package/agent-assets/docs/guides/connect-a-new-mail-account.md

@@ -3,56 +3,121 @@ schema_version: 1
 slug: guides/connect-a-new-mail-account
 title: Connect a New Mail Account
 id: connect-a-new-mail-account
+aliases:
+  - connect mail
+  - add mail account
+  - imap setup
+  - gmail setup
+  - outlook setup
 category: guides
 summary: |
-  Add a Gmail / Outlook / Yahoo / iCloud account to the mail
-  integration. Each provider has its own credential shape.
+  Add a Gmail, Outlook, Yahoo, or iCloud mailbox to the mail
+  integration. Each provider authenticates differently: Gmail rides
+  the primary Google sign-in, Outlook uses OAuth, and Yahoo/iCloud
+  use an app password.
 section: connect-a-new-mail-account
 tags:
   - guide
   - mail
+  - integrations
 status: stable
 ask_examples:
   - How do I add another Gmail account?
   - What mail providers does Aitne support?
+  - How do I connect an Outlook mailbox?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
+keywords:
+  - mail
+  - imap
+  - gmail
+  - outlook
+  - yahoo
+  - icloud
+  - mail provider
+  - OAuth
+  - app password
 related:
   - features/integrations/mail
+ui_anchors:
+  - /connections/mail
+api_endpoints:
+  - /api/mail/accounts
+  - /api/mail/accounts/device-code
+  - /api/config/mail/app-password
+config_keys:
+  - enabledMailProviders
+context_files:
+  - state/today.md
 ---
 
 # Connect a New Mail Account
 
 ## Goal
 
-Wire a new mailbox into Aitne so the agent can read, label,
+Wire a new mailbox into Aitne so the agent can read, label, classify,
 and search it.
 
+## Supported providers
+
+The mail registry recognizes exactly four provider kinds — `gmail`,
+`outlook`, `yahoo`, `icloud`. It deliberately stops at hosted
+providers, so there is no separate "generic IMAP server" kind. Each
+kind authenticates differently:
+
+| Provider | How it connects |
+|---|---|
+| **Gmail** | Rides the primary Google sign-in (`/config/google-auth`). Extra Gmail accounts beyond the primary identity are not implemented yet. |
+| **Outlook** | OAuth — a browser loopback flow, with a device-code fallback for headless machines. |
+| **Yahoo** | App password (IMAP). |
+| **iCloud** | App password (IMAP). |
+
 ## Prerequisites
 
-- The provider's OAuth or app password is available.
+- For **Outlook**: the Outlook client config must already be set
+  (`PUT /api/config/mail/outlook/client-config`).
+- For **Yahoo / iCloud**: generate a provider-specific app password
+  first — your regular login password will not work over IMAP.
 
 ## Steps
 
 1. Open `/connections/mail`.
-2. Click "Add account".
-3. Pick the provider kind. The supported set is `gmail`, `outlook`,
-   `yahoo`, `icloud` — the registry deliberately stops at hosted
-   providers, so a generic IMAP server is not a separate kind.
-4. Step through the OAuth flow (Gmail / Outlook) or paste the
-   provider-specific app password (Yahoo / iCloud).
-5. Save. The first poll runs within a minute.
+2. Click "Add account" and pick the provider kind.
+3. Authenticate for that kind:
+   - **Gmail** — connect the primary Google account from the setup or
+     connections flow (`/config/google-auth`). It then appears on the
+     unified mail surface automatically; you do not add it as a
+     separate mail account.
+   - **Outlook** — step through the OAuth browser flow. On a headless
+     machine (SSH / WSL), use the device-code fallback, which prints a
+     code to enter at a verification URL.
+   - **Yahoo / iCloud** — paste the email address and the app password.
+4. Save. Registration succeeds regardless of the enabled-providers
+   setting (`enabledMailProviders`); the account goes live only when
+   you flip its **Enable** toggle on the mail card.
+5. The first poll runs within a minute of being enabled.
 
 ## Verification
 
-- The account row turns green on the auth-health card.
+- The account row turns healthy on the auth-health card.
 - The mail count updates on `/connections/mail`.
 
 ## If It Fails
 
-- OAuth that does not return: confirm the redirect URL matches the
-  daemon's API port (default 8321).
+- **Outlook OAuth never returns** — the loopback flow binds an
+  ephemeral port on `127.0.0.1`, so a fixed-port redirect mismatch is
+  not the cause. Confirm the browser actually opened and completed the
+  redirect; on a headless host switch to the device-code flow instead.
+- **Outlook add returns "client config missing"** — set the Outlook
+  client config (`PUT /api/config/mail/outlook/client-config`) before
+  adding the account.
+- **Yahoo / iCloud login rejected** — re-check the address and the app
+  password (not your normal account password); regenerate the app
+  password if it still fails.
+- **Adding a second Gmail account fails** — only the primary Google
+  identity is supported today; additional Gmail accounts are not yet
+  implemented.
 
 ## Related