@aitne-sh/aitne 0.1.8 → 0.1.9

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,68 +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
 
@@ -106,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

@@ -21,22 +21,32 @@ 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
+  - "!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
@@ -49,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
@@ -74,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,49 +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
-  - models
+  - 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

@@ -11,8 +11,10 @@ aliases:
   - 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
@@ -22,9 +24,10 @@ 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
@@ -34,41 +37,87 @@ keywords:
   - 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
 

package/agent-assets/docs/guides/explore-with-trace-and-connect.md

@@ -14,11 +14,12 @@ summary: |
   How to use `!trace <topic>` to reconstruct the evolution of an
   idea across your raw / wiki / outputs layers, and `!connect <a>
   <b>` to find bridges between two domains.
-section: explore-with-trace-and-connect
+section: guides
 tags:
-  - guide
+  - guides
   - wiki
   - exploration
+  - bang-commands
 status: stable
 ask_examples:
   - How do I trace an idea across the wiki?
@@ -26,19 +27,27 @@ ask_examples:
   - How do I find connections between two topics?
   - Where does the !trace output land?
   - Can I use multi-word topics with !connect?
+  - How do I run !trace against a non-default wiki workspace?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
 keywords:
-  - !trace
-  - !connect
+  - "!trace"
+  - "!connect"
   - wiki exploration
   - topic history
   - topic bridges
+  - bridging domains
+prerequisites:
+  - guides/build-your-wiki
 related:
   - features/wiki/overview
   - features/wiki/commands
   - guides/maintain-wiki-health
+  - features/messaging/bang-commands
+process_keys:
+  - wiki.trace
+  - wiki.connect
 ui_anchors:
   - /wiki/timeline
   - /settings/wiki
@@ -46,10 +55,16 @@ ui_anchors:
 
 # Explore Your Wiki with `!trace` and `!connect`
 
-`!trace` and `!connect` are the two Phase 3 exploration commands.
-Both produce a one-off output document in `30_outputs/` and never
-touch your raw or wiki notes. Think of them as cited essays
-written from what your wiki actually contains.
+`!trace` and `!connect` are the two wiki exploration commands. Both
+produce a one-off output document in `30_outputs/` and never touch
+your raw or wiki notes. Think of them as cited essays written from
+what your wiki actually contains.
+
+Both run as owner-DM bang commands. Both also accept an optional
+leading `@<workspace>` token to target a non-default wiki workspace
+— for example `!trace @research formal methods` or
+`!connect @research category theory, distributed systems`. Omit the
+token and the command runs against your default workspace.
 
 ## `!trace <topic>` — Time-Based Exploration
 
@@ -114,13 +129,15 @@ your wiki. The agent surfaces four kinds of bridges:
 
 ### Argument Forms
 
-`!connect` requires exactly two topics. Whitespace separates them
-by default; a comma lets you use multi-word topics:
+`!connect` requires exactly two topics (after any optional
+`@<workspace>` token). Whitespace separates them by default; a
+comma lets you use multi-word topics:
 
 ```
 !connect quantum gravity
 !connect quantum computing, classical computing
 !connect category theory, distributed systems
+!connect @research category theory, distributed systems
 ```
 
 The handler rejects a single topic, three-or-more topics, a