@aitne-sh/aitne 0.1.5 → 0.1.6

package/README.md

@@ -131,6 +131,20 @@ A non-exhaustive list. Click any group to expand.
 - Auto-link new notes to existing concepts ("this is related to your `agent-architecture.md` from March")
 </details>
 
+<details>
+<summary><b>🧠 Build a personal wiki from anything you DM</b></summary>
+
+- Send a URL with `!ingest https://...` — the agent fetches, summarises, and saves a raw note in `10_raw/`
+- Run `!compile` to synthesise raw notes into linked wiki articles in `20_wiki/` with an auto-maintained `_index.md`
+- `!compile --preview` shows added / modified / unchanged pages plus cost and ETA *before* you spend tokens
+- `!compile full` rebuilds everything — cost-gated, with a dashboard approval queue and an optional git pre-compile snapshot for external vaults
+- `!ask <question>` answers from your own wiki and writes the cited reply to `30_outputs/`
+- `!lint` audits for orphans, broken links, schema drift, and taxonomy candidates → dated health report
+- `!trace <topic>` and `!connect A B` reconstruct how an idea evolved and find shared structure across domains
+- Run multiple workspaces (`!ingest @research ...`, `!compile @ops full`) — the default workspace falls through when the `@` token is omitted
+- Workspaces can be internal (`~/.personal-agent/wiki/`) or an external Obsidian vault you already keep
+</details>
+
 <details>
 <summary><b>📦 Code, Git, GitHub</b></summary>
 
@@ -410,6 +424,7 @@ flowchart TB
 | 🧠 **Multi-backend brain** | Claude (Opus 4.7 / Sonnet 4.6 / Haiku 4.5) · Codex CLI · Gemini CLI |
 | 📝 **MD-centric memory** | Plain Markdown you own — `today.md` · `roadmap.md` · `projects/*` · `daily/` · `weekly/` · `monthly/` |
 | 🔌 **23 built-in skills** | Calendar, mail, Notion, Obsidian, schedule, roadmap, receipts, travel, reading, voice, … |
+| 🧠 **Personal wiki builder** | DM `!ingest <url>` to capture, `!compile` to synthesise, `!ask` / `!lint` / `!trace` / `!connect` to operate — across one or many workspaces |
 | 🔁 **4-mode integration framework** | `direct` (daemon polls) · `delegated` (backend's connector) · `native` (main backend MCP on demand) · `disabled` |
 | 🛡️ **Four-layer safety** | SDK allowlist · PreToolUse hooks · daemon API risk tiers · absolute-block layer that holds even in Allow mode |
 | 🪪 **Local-first & private** | Binds to `127.0.0.1`. No telemetry. Secrets in OS Keychain. Zero cloud state. |
@@ -823,6 +838,7 @@ Local FTS5 full-text search runs across **every** account via `GET /api/mail/sea
 
 - **Obsidian** — read directly via `Read`; write via the official Obsidian CLI (`obsidian create`, `obsidian append`, `obsidian daily:append`, …); `chokidar` watches the vault for user edits
 - **Notion** — `@notionhq/client` REST API; full page + database CRUD
+- **Wiki builder** — per-workspace ingest / compile / ask / lint / trace / connect surface backed by `packages/daemon/src/core/wiki/` (cost-gated full rebuilds, approval queue, compile preview, optional git pre-compile snapshot, dispatch-mode fan-out). One internal workspace or any number of external Obsidian vaults; addressed with `@<workspace>` on every bang command. See `agent-assets/docs/features/wiki/overview.md`.
 - **Custom MCP servers** — register via `/api/mcp/servers`; materialized into the per-session workdir so backends use them transparently
 
 ### Code

package/agent-assets/agent-profiles/_safety.md

@@ -24,12 +24,27 @@
 - **Read-before-write**: PATCH `mode=replace` replaces the entire section.
   Always GET first, merge your changes into the existing content, then PATCH.
   Prefer `mode=append` when simply adding new entries.
+- **Every Bash invocation that hits the daemon API MUST begin with the
+  literal `curl` token.** The session's allow-list is `Bash(curl *)`,
+  prefix-matched against the FULL command string under `dontAsk`. Any
+  wrapping shape is silently denied (no tool result, no error — the
+  call simply does not run):
+  - `echo '{...}' | curl ...` → starts with `echo` → denied
+  - `cat <<JSON | curl -d @-` → starts with `cat` → denied
+  - `bash -c "curl ..."` / `( curl ... )` / `var=x curl ...` → denied
+  - `curl ... ; curl ...` / `curl ... && curl ...` → chained-curl denied
+  Write a single, flat curl call. If you see no response from Bash at
+  all (no stdout, no stderr, no `PA_API_ERROR`), your command was
+  silently denied — rewrite it to start with literal `curl`.
 - **Daemon-API body submission** (`curl -d` on `/api/context/*`,
   `/api/observations`, `/api/schedule`, etc.). Two safe shapes:
   - Inline JSON — `-d '{"key":"value"}'`. Use for small / single-line
     bodies. Escape internal newlines as `\n`.
-  - Stdin heredoc — `-d @- <<'JSON' … JSON`. Use for multi-line or
-    large bodies. `@-` is curl's stdin marker (a literal two-character
+  - Stdin heredoc on the SAME curl line — `curl ... -d @- <<'JSON'`
+    + body + `JSON`. Note: the heredoc is redirected into `curl`'s
+    stdin so the command still STARTS with `curl`; do NOT pipe from
+    `cat <<JSON | curl …` (that starts with `cat` and is silently
+    denied). `@-` is curl's stdin marker (a literal two-character
     token), distinct from the file-read forms below.
 
   Never use `-d @<filepath>` / `--data-raw '@<filepath>'` /

package/agent-assets/agent-profiles/routine-fetch-window.md

@@ -7,7 +7,9 @@ mechanical.
 ## Principles
 - **Fetch, don't think.** Read the `<acquisition-plan>` block in your prompt.
   It enumerates `(integration, mode, window, account?)` tuples. For each row,
-  perform the matching fetch and POST results to `/api/observations`.
+  perform the matching fetch and POST results to `/api/observations/batch`
+  in a **single** call per window (the contract is in the integration
+  partial below).
 - **Trust the routing the daemon resolved for you.** The plan already encodes
   the per-(integration, mode) path. Do not second-guess: do not probe MCP
   registries, do not list "common tool names", do not guess. The integration
@@ -18,6 +20,13 @@ mechanical.
   `/api/observations` after you return and populates `summary_text` /
   `novelty_score`. Do not summarize, rank, or filter — your output is the
   raw payload.
+- **Batch in one curl per window.** Each acquired window goes out as a
+  single `POST /api/observations/batch` call with up to 200 observations
+  in the `observations[]` array. Do NOT loop over items in a shell `for`,
+  do NOT write a script under `/tmp/` and pipe / source / bash it, do NOT
+  chain multiple `curl` invocations in one Bash call. Those shapes are
+  blocked by the daemon's Bash hooks and burn pre-pass turns to no
+  effect. One window → one curl → one JSON body with an array.
 - **Never write to context MD files.** today.md, weekly/, journal, schedule —
   all of that belongs to the parent routine session, not to you.
 - **Single JSON line on stdout.** When done, print exactly one JSON object
@@ -27,8 +36,15 @@ mechanical.
 
 ## Fetch routing summary
 
-For each `<fetch integration="…" mode="…" window="…" account="…">` row in
-`<acquisition-plan>`, route by `mode`:
+For each `<fetch integration="…" mode="…" window="…" [account="…"]>` row in
+`<acquisition-plan>`, route by `mode`. The `account` attribute is only
+present in `direct` mode (where the daemon stores per-account OAuth
+tokens); in `delegated-same` / `delegated-cross` / `native` modes the bound
+MCP authenticates as a single user, so the dispatcher emits a single row
+without an `account` attribute and the partial substitutes `"default"`
+wherever the observation source / providerId references `<accountId>`.
+
+Route by `mode`:
 
 - **direct** — call the daemon REST endpoint named by the integration
   partial (`/api/mail/...`, `/api/calendar/events`, `/api/notion/...`,
@@ -47,44 +63,55 @@ For each `<fetch integration="…" mode="…" window="…" account="…">` row i
 If the partial for an integration is missing or the row has no usable
 surface (e.g. user picked native for Outlook Mail without binding any
 Outlook surface), record
-`{"type":"no-surface","integration":"<key>","account":"<id>"}` in `errors`
-and continue. Never halt the pre-pass — the parent routine continues
-with whatever observations the rest of the plan produced.
+`{"type":"no-surface","integration":"<key>","account":"<id>"}` in
+`errors` (use the literal string `"default"` for `account` when the
+`<fetch>` row has no `account` attribute) and continue. Never halt the
+pre-pass — the parent routine continues with whatever observations the
+rest of the plan produced.
 
 ## Observation POST contract
 
-For every fetched item, POST to `/api/observations`:
+For every fetched window, POST a batched array to
+`/api/observations/batch` (one curl per window, up to 200 items per call):
 
 ```json
 {
-  "source":     "<integrationKey>:<accountOrScope>",
-  "ref":        "<provider-side stable id>",
-  "changeType": "created",
-  "actor":      "agent",
-  "payload": {
-    "kind":       "mail" | "calendar" | "notion",
-    "providerId": "<account id>",
-    "raw":        { /* compact subset: subject/from/snippet/date for mail,
-                        title/start/end/attendees for calendar,
-                        title/last_edited/parent for notion */ }
-  }
+  "observations": [
+    {
+      "source":     "<integrationKey>:<accountOrScope>",
+      "ref":        "<provider-side stable id>",
+      "changeType": "created",
+      "actor":      "agent",
+      "payload": {
+        "kind":       "mail" | "calendar" | "notion",
+        "providerId": "<account id>",
+        "raw":        { /* compact subset: subject/from/snippet/date for mail,
+                            title/start/end/attendees for calendar,
+                            title/last_edited/parent for notion */ }
+      }
+    },
+    …
+  ]
 }
 ```
 
-- `actor` MUST be `"agent"`. The server rejects `"user"`.
+- `actor` on every element MUST be `"agent"`. The server rejects `"user"`.
 - Do NOT compute or supply a dedup hash; the server computes
-  `contentHash` from `(source, payload)` and returns it in the
-  response.
-- The response distinguishes three outcomes via `action` (on 200) or
-  `error` (on 409). Count each into the report:
-  - `200 {action: "created"}`  → `posted++`
-  - `200 {action: "modified"}` → `posted++` (server updated the
-    existing `(source, ref)` pending row with a different payload)
-  - `409 {error: "duplicate"}` → `duplicates++` (identical payload
-    already pending — no row was written, no summarizer re-enqueue)
-  - `409 {error: "integration_flip_in_progress"}` → append
-    `{type:"flip-locked", integration:"<key>", …}` to `errors` and
-    move on; do NOT retry inline (the next routine tick will).
+  `contentHash` from `(source, payload)` and returns it per item.
+- The batch endpoint always returns `200` with envelope
+  `{ "results": [{index, status, ref, source, contentHash?, id?, error?}, …],
+    "fetched": N, "posted": N, "duplicates": N, "errors": N }`. Roll the
+  envelope's `posted` / `duplicates` into your running totals; for each
+  `results[*].status` other than `"created"` / `"modified"` / `"duplicate"`,
+  append the appropriate `errors[]` entry per the partial.
+  - `"created"` / `"modified"` → already in envelope's `posted`.
+  - `"duplicate"`              → already in envelope's `duplicates`.
+  - `"flip_locked"` → append
+    `{type:"flip-locked", integration:"<key>", …}` to `errors`; do NOT
+    retry inline (the next routine tick will).
+  - `"validation_error"` → append
+    `{type:"validation-error", integration:"<key>", ref:"<ref>",
+      detail:"<results[*].error>"}` to `errors`.
 - For an item whose payload differs from a prior pending row with the
   same `(source, ref)`, send `changeType: "modified"` — the server
   detects identical payloads via the canonical contentHash regardless
@@ -92,6 +119,9 @@ For every fetched item, POST to `/api/observations`:
   consumers, not part of the dedup signal.
 - For a deletion, send `changeType: "deleted"` with a minimal payload
   (`{"kind":"…","providerId":"…","raw":{"deletedAt":"<iso>"}}`).
+- If the upstream call returns more than 200 items for a single window,
+  split into multiple `POST /api/observations/batch` calls of at most
+  200 entries each.
 
 ## Boundaries
 - Do NOT call `/api/context/*` (write or read) — that surface belongs to
@@ -113,16 +143,21 @@ Print exactly one JSON line on stdout, then terminate:
 
 Field semantics:
 - `fetched`    — total items returned by upstream APIs across all rows.
-- `posted`     — count of 200 responses (`action ∈ {created, modified}`).
-- `duplicates` — count of `409 {error:"duplicate"}` responses
-  (canonical `(source, payload)` already pending).
+- `posted`     — sum of the batch endpoint's envelope-level `posted`
+  counter across every `POST /api/observations/batch` call you make
+  (i.e. `results[*].status ∈ {"created","modified"}`).
+- `duplicates` — sum of the batch endpoint's envelope-level `duplicates`
+  counter (i.e. `results[*].status == "duplicate"`).
 - `errors`     — array of `{type, ...}` records. Common types:
-  - `no-surface`     — the row points at an in-session connector that
-    isn't bound on this backend.
-  - `flip-locked`    — `409 {error:"integration_flip_in_progress"}`;
-    the integration is mid-flip and the write was rejected.
-  - `unexpected-row` — `mode="disabled"` slipped past the daemon filter.
-  - `fetch-failed`   — upstream API returned non-2xx;
+  - `no-surface`       — the row points at an in-session connector
+    that isn't bound on this backend.
+  - `flip-locked`      — `results[*].status == "flip_locked"`; the
+    integration is mid-flip. Do NOT retry inline — the next routine
+    tick reaps it.
+  - `validation-error` — `results[*].status == "validation_error"` for
+    a malformed item; copy `detail` from `results[*].error`.
+  - `unexpected-row`   — `mode="disabled"` slipped past the daemon filter.
+  - `fetch-failed`     — upstream API returned non-2xx;
     `{type, integration, account?, status, message}`.
   - `budget-exhausted` — hit the configured `max_turns` /
     `max_budget_usd` for `routine.fetch_window`.

package/agent-assets/agent-profiles/wiki-agent.md

@@ -0,0 +1,19 @@
+# Wiki Agent
+
+You maintain the operator's internal wiki workspace.
+
+## Principles
+
+- **Bash invocations that hit the daemon API MUST start with the literal `curl` token.** The session's allow-list is `Bash(curl *)`, prefix-matched under `dontAsk`. Anything starting with `echo`, `cat`, `bash`, `(`, a variable assignment, or chaining two curls with `;` / `&&` / `|` is silently denied — no error, no body, the call simply does not run. For multi-KB bodies use a heredoc redirected into curl on the same line: `curl ... -d @- <<'JSON' … JSON` — the command still starts with `curl`, and the shim reads stdin via `-d @-`. See `wiki-vault-rules` for the canonical shapes.
+- Treat the wiki vault as durable user data. Preserve source fidelity and make uncertainty visible.
+- Write only through the daemon Wiki API (`/api/wiki/{{workspace_name}}/files/...`). The `Write` and `Edit` tools are stripped from this session's allow-list and are silently denied under `dontAsk`; do not try to "make them work" via path rewriting. `Bash(find ...)`, `Bash(ls ...)`, `Bash(cat ...)` and other shell utilities are also denied — only `Bash(curl *)` and `Bash(jq *)` are on the allow-list, so enumerate the vault via `GET /api/wiki/{{workspace_name}}/index`, not from disk. A file appears in the vault only after the daemon returns `{"ok":true,"path":"<path>"}` to your POST/PATCH.
+- Follow the layer contract from the loaded wiki skills. If an API write is rejected, fix the target path or payload; do not bypass the route.
+- **Do not invent daemon endpoints.** The complete write surface is what `wiki-vault-rules` lists. Routes like `/api/send-message`, `/api/whatsapp/send`, `/api/notify-user`, `/api/dm` do not exist; calls there return 401/404 and do nothing. Your completion DM is your final assistant TEXT message — the daemon forwards it automatically.
+- **Never claim a write happened without the daemon's 200 receipt.** A successful POST returns JSON containing `"ok":true` and the canonical `"path"`; the success DM must cite that exact path byte-for-byte. If the response is anything else, the write failed — emit the failure DM.
+- Output language for durable prose is `{{language}}` unless source fidelity requires preserving quoted source text.
+
+## Workspace
+
+- Workspace: `{{workspace_name}}`
+- Vault path: `{{vault_path}}`
+- Schema version: `{{schema_version}}`

package/agent-assets/docs/features/messaging/bang-commands.md

@@ -0,0 +1,161 @@
+---
+schema_version: 1
+slug: features/messaging/bang-commands
+title: Bang Commands
+id: bang-commands
+aliases:
+  - "!stop"
+  - "!start"
+  - "!cost"
+  - "!report"
+  - "!help"
+  - exclamation commands
+  - chat commands
+category: features
+summary: |
+  Short owner-only commands typed in any paired DM (Slack, Telegram,
+  Discord, WhatsApp, dashboard chat) that the daemon answers directly,
+  with no agent backend involved and no cost. Use them to pause /
+  resume, check spend, see recent failures, and list every command.
+section: messaging
+tags:
+  - core
+  - messaging
+  - operations
+status: stable
+ask_examples:
+  - How do I pause the agent from my phone?
+  - What can I type in the DM to control Aitne?
+  - How do I list all the commands?
+  - Where do I see how much the agent spent this week?
+locale: en-US
+created: 2026-05-12
+updated: 2026-05-12
+keywords:
+  - bang command
+  - "!stop"
+  - "!start"
+  - "!cost"
+  - "!report"
+  - "!help"
+  - pause
+  - resume
+related:
+  - features/messaging/overview
+  - features/messaging/pairing-and-magic-phrase
+  - guides/pause-the-agent
+  - features/operations/cost-tracking
+ui_anchors:
+  - /settings/commands
+---
+
+# Bang Commands
+
+## In One Sentence
+
+DM the agent a short word starting with `!` and the daemon answers
+directly — no LLM call, no cost, no session opened.
+
+## Who Can Use Them
+
+Only the **paired owner channel**. A bang from any other sender is
+dropped by the same single-owner filter that drops every other DM.
+Pair your messaging app first; see
+[Pairing & Magic Phrase](pairing-and-magic-phrase.md).
+
+## Available Commands
+
+| Command | What it does |
+|---|---|
+| `!help` | Lists every command currently registered — built-ins plus any custom user commands. |
+| `!stop` | Pauses cron-driven autonomous work (hourly check, morning / evening / weekly / monthly routines, scheduled tasks). In-flight runs are **not** aborted. |
+| `!start` | Resumes autonomous work after `!stop`. |
+| `!cost` | Last-7-day spend across all backends. |
+| `!cost claude` / `!cost codex` / `!cost gemini` | Spend for a single backend. |
+| `!report` | Recent agent failures (last 7 days, top groups, most recent sample). |
+
+Custom commands added at `/settings/commands` show up in `!help`
+automatically — no restart needed.
+
+## How They Look
+
+Every reply leads with a `[SYSTEM · <command>]` marker so you can tell
+at a glance it came from the daemon, not the agent:
+
+```
+[SYSTEM · !cost · last 7d]
+Total: $1.42 (37 sessions)
+
+- claude: $1.10 (29 sessions)
+- codex:  $0.32 ( 8 sessions)
+- gemini: $0.00 ( 0 sessions)
+```
+
+`!help` lists each entry with the name on its own line and the
+description indented:
+
+```
+[SYSTEM · !help]
+
+Built-in:
+
+!cost
+  Show last-7-day Claude / Codex / Gemini spend.
+
+!help
+  Show every registered command.
+
+!report
+  Show recent agent failures.
+
+!start
+  Resume autonomous work after !stop.
+
+!stop
+  Pause cron-driven autonomous work. In-flight runs are not aborted.
+```
+
+The `Custom:` section appears below the built-ins when you have
+enabled user commands at `/settings/commands`.
+
+## How They Behave
+
+- **Exact match.** `!stop`, `!cost`, `!cost claude` are recognised;
+  `!stop now please` is not — it falls through to the agent path.
+- **DM only.** Bangs typed into a shared channel are ignored.
+- **No cost.** No LLM is invoked; no `conversation_sessions` row is
+  opened. Every invocation writes one `bang_command` row to
+  `agent_actions` for the activity log.
+- **While paused**, any DM (bang or not) replies with the paused
+  notice; only `!start`, `!cost`, `!report`, and `!help` continue to
+  run.
+- **Replies land where the command did** — same platform, same
+  channel, same thread.
+
+## Pause vs. `aitne stop`
+
+`!stop` pauses **autonomous** work; the daemon stays up so it can
+receive `!start`. It is the right tool for "be quiet for a bit".
+
+`aitne stop` (CLI) shuts the daemon down entirely. Use it when you
+want everything off, including the message receivers. See
+[Pause the Agent](../../guides/pause-the-agent.md) for the longer-
+window version.
+
+## When Something Goes Wrong
+
+- **No reply at all.** The DM is probably hitting an unpaired channel
+  — pair first. See [Messaging Overview](overview.md).
+- **The reply lists fewer commands than you expect.** `!help` only
+  lists *enabled* user commands. Toggle the row on at
+  `/settings/commands`.
+- **`!cost foo` says "unknown command".** Only `claude`, `codex`,
+  `gemini` are valid backend arguments today. Plain `!cost` (no
+  argument) covers all three.
+
+## Related
+
+- [Messaging Overview](overview.md)
+- [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
+- [Pause the Agent](../../guides/pause-the-agent.md)
+- [Cost Tracking](../operations/cost-tracking.md)

package/agent-assets/docs/features/messaging/overview.md

@@ -44,6 +44,7 @@ related:
   - features/messaging/whatsapp
   - features/messaging/dashboard-chat
   - features/messaging/voice-attachments
+  - features/messaging/bang-commands
   - features/operations/notifications
   - features/operations/quiet-hours
 ui_anchors:
@@ -114,6 +115,8 @@ adapter and the dispatcher both check).
 ## Related
 
 - [Pairing & Magic Phrase](pairing-and-magic-phrase.md)
+- [Bang Commands](bang-commands.md) — `!stop` / `!start` / `!cost` /
+  `!report` / `!help` for mobile-first daemon control.
 - [Voice Attachments](voice-attachments.md) — local Whisper
   transcription for inbound audio.
 - [Dashboard Chat](dashboard-chat.md) — the in-browser equivalent.

package/agent-assets/docs/features/wiki/commands.md

@@ -0,0 +1,222 @@
+---
+schema_version: 1
+slug: features/wiki/commands
+title: Wiki Commands
+id: wiki-commands
+aliases:
+  - "!ingest"
+  - "!compile"
+  - "!ask"
+  - "!wiki"
+  - "!lint"
+  - "!trace"
+  - "!connect"
+  - bang commands wiki
+category: features
+summary: |
+  Reference for the wiki bang commands — `!ingest`, `!compile`,
+  `!compile full`, `!ask`, `!wiki`, plus the Phase 3 operational
+  triad `!lint`, `!trace`, `!connect` — including the dispatch-mode
+  and approval-gate semantics.
+section: wiki
+tags:
+  - wiki
+  - bang-commands
+status: stable
+ask_examples:
+  - How do I send a URL to the wiki?
+  - What is the difference between `!compile` and `!compile full`?
+  - Why did `!compile full` ask for approval?
+  - What does serial dispatch mode change?
+  - How do I run a wiki health check?
+  - What does `!trace` do?
+  - How do I bridge two domains with `!connect`?
+locale: en-US
+created: 2026-05-12
+updated: 2026-05-12
+related:
+  - features/wiki/overview
+  - features/messaging/bang-commands
+  - guides/budget-and-cost-for-wiki
+  - guides/maintain-wiki-health
+  - guides/explore-with-trace-and-connect
+  - troubleshooting/wiki-ingest-full-blocked
+ui_anchors:
+  - /wiki
+  - /wiki/timeline
+  - /settings/wiki
+  - /approvals
+---
+
+# Wiki Commands
+
+Use these from a paired DM channel after enabling the wiki — open
+**Setup → Settings → Wiki** to enable, then browse from **My Life →
+Wiki**.
+
+| Command | Effect |
+|---|---|
+| `!ingest [@<workspace>] <url> [url...]` | Queues one `wiki.ingest_url` event per URL. |
+| `!compile [@<workspace>]` | Queues an incremental `wiki.compile` run. |
+| `!compile [@<workspace>] --preview` | Dry-run preview: lists pages that would be added / modified / unchanged plus cost and ETA. Aliases: `--dry-run`. No agent session runs. |
+| `!compile [@<workspace>] full` | Queues a full rebuild. Cost-gated; estimates above the threshold need dashboard approval first. |
+| `!compile [@<workspace>] full --preview` | Dry-run preview of the full rebuild. Same shape as the incremental preview. |
+| `!ask [@<workspace>] <question>` | Queues a `wiki.ask` answer run and writes to `30_outputs/`. |
+| `!lint [@<workspace>]` | Audits the wiki for orphans, broken links, schema drift, taxonomy candidates, and stale notes. Writes `90_meta/health/<YYYY-MM-DD>.md`. |
+| `!trace [@<workspace>] <topic>` | Reconstructs how an idea has evolved across raw / wiki / outputs. Writes `30_outputs/<YYYY-MM-DD>-trace-<slug>.md`. |
+| `!connect [@<workspace>] <a> <b>` | Finds bridges (shared terms, references, structural analogies) between two domains. Writes `30_outputs/<YYYY-MM-DD>-connect-<slug-a>--<slug-b>.md`. |
+| `!wiki` | Shows workspace status and counts. One line per workspace when multiple are active. |
+| `!wiki help` | Shows the command list. |
+
+`!ingest` accepts only `http://` and `https://` URLs and caps each
+batch at 10 URLs.
+
+## `@<workspace>` — addressing a non-default workspace
+
+If you run more than one wiki workspace (Phase 5), every bang command
+accepts an optional `@<name>` token immediately after the bang. The
+token is parsed before the command's own argument parser sees the
+rest, so multi-word topics and comma-separated arguments work as
+normal:
+
+    !compile @research full
+    !ask @parenting what did the pediatrician recommend?
+    !connect @research diffusion models, score matching
+
+Omit the token and the command targets the **default** workspace.
+See `agent-assets/docs/guides/multiple-wikis-for-multiple-domains.md`
+for a walkthrough.
+
+## `!compile --preview` — the dry run
+
+Use `!compile --preview` (or `--dry-run`) when you want to see what
+`!compile` would do without spending tokens:
+
+- **added** — wiki pages that would be created (raws with no
+  existing wiki match).
+- **modified** — wiki pages that would be rewritten (raws whose
+  slug matches an existing wiki page).
+- **unchanged** — wiki pages the compile is expected to skip.
+- **est. cost** — Optimistic / pessimistic bracket plus expected
+  spend.
+- **est. duration** — Rough wall-clock estimate (intentionally
+  pessimistic).
+
+The preview is an upper bound. The compile is an LLM and may
+merge or skip pages inside the agent loop; the preview cannot
+predict that exactly, but it will not undercount the touch set.
+Reply `!compile` (or `!compile full`) to actually run the compile.
+
+## Dispatch Mode for `!ingest`
+
+`!ingest` honours the per-workspace **dispatch mode** in
+Settings → Wiki:
+
+- **Parallel** (default): all URLs fan out simultaneously up to the
+  per-URL concurrency cap. Fastest; small risk of bursting rate
+  limits at the URL host.
+- **Serial**: URLs are enqueued in submitted order; each agent
+  session starts only after the previous one completes. Slower but
+  predictable budget and rate.
+
+The acknowledgement DM tells you which mode ran
+(`in parallel` / `serially`).
+
+## `!compile full` — the Cost Gate
+
+Full rebuilds touch every wiki note and are the most expensive
+command in the wiki surface. The flow:
+
+1. The bang handler estimates the cost (raw count × assumed input
+   tokens × Sonnet unit cost, bracketed at 0.5× / 1× / 2×).
+2. On an external git-tracked vault with **Auto-commit before
+   `!compile full`** enabled and a clean working tree, Aitne runs
+   `git add -A && git commit -m "aitne wiki: pre-compile snapshot <ts>"`
+   before continuing. A dirty tree refuses the operation — commit or
+   stash first.
+3. If the pessimistic estimate exceeds your per-workspace approval
+   threshold (default $2.00), the run is queued under **Approvals**
+   in the dashboard. Approve from `/approvals` to start the compile.
+4. Otherwise, the run starts autonomously and you receive a
+   completion DM with actual spend.
+
+The same estimate is shown live in **Settings → Wiki** so you can
+see what the next `!compile full` will cost before you run it.
+
+## Operational Triad — `!lint`, `!trace`, `!connect`
+
+These three commands round out the wiki surface for ongoing
+maintenance and exploration. None of them write to the content
+layers (`10_raw/`, `20_wiki/`); they only produce health reports
+(`90_meta/health/`) or output documents (`30_outputs/`).
+
+### `!lint`
+
+Run periodically (weekly is a sensible cadence) to audit the wiki
+for:
+
+- Orphaned wiki notes (no incoming links).
+- Broken `[[wikilinks]]` pointing at missing files.
+- Notes that violate the schema declared in
+  `90_meta/schemas/{raw,wiki,output}.md`.
+- Stale wiki notes whose newest source is more than 90 days old.
+- Slug/title variants that look like the same concept.
+- Recurring concepts that should be promoted into `90_meta/taxonomy.md`.
+- Drift between `20_wiki/_index.md` and the files on disk.
+
+The output is one Markdown report at
+`90_meta/health/<YYYY-MM-DD>.md` with a `## Summary` line, a
+`## Action items` list, and one section per check. When taxonomy
+candidates are found, `!lint` also appends a `# Candidates` section
+to `90_meta/taxonomy.md` for your review — it never promotes the
+candidates itself; you decide which to keep.
+
+The latest report is rendered prominently on **My Life → Wiki →
+Timeline & health** (`/wiki/timeline`).
+
+### `!trace <topic>`
+
+Reconstructs the chronological evolution of an idea across every
+wiki layer. Use a free-form topic — the skill canonicalises against
+`90_meta/taxonomy.md` before deriving the output slug:
+
+```
+!trace quantum computing
+!trace formal methods in distributed systems
+```
+
+The output is a timeline at
+`30_outputs/<YYYY-MM-DD>-trace-<slug>.md` grouped into two to five
+phases with cited evidence and an explicit gap list. If the wiki
+has fewer than two sources on the topic, the report says so
+directly — no speculative filler.
+
+### `!connect <a> <b>`
+
+Bridges two domains by surfacing shared terminology, common
+references, structural analogies, and proposed bridging concepts.
+Pass exactly two topics separated by whitespace or by a comma; the
+comma form supports multi-word topics:
+
+```
+!connect quantum gravity
+!connect quantum computing, classical computing
+```
+
+A single argument, three or more arguments, an empty input, or a
+trailing comma all return a usage message — pick a topic for each
+side. The output lands at
+`30_outputs/<YYYY-MM-DD>-connect-<slug-a>--<slug-b>.md`. When no
+genuine bridges exist, the report still writes — a "no connection"
+finding is itself useful.
+
+## Disabled-State Behaviour
+
+When no active wiki workspace exists, every `wiki.*`-routed bang
+command (`!ingest`, `!compile`, `!ask`, `!lint`, `!trace`, `!connect`)
+replies with:
+
+> Wiki is not enabled. Open `/settings/wiki` to enable.
+
+`!wiki help` is exempt — it returns the command list regardless of
+enablement so you can discover the surface before opting in.