@aitne-sh/aitne 0.1.12 → 0.1.13

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

@@ -17,7 +17,6 @@ summary: |
   this directory, so re-register them after a restore.
 section: backup-and-restore
 tags:
-  - guides
   - operations
   - backup
 status: stable
@@ -27,7 +26,7 @@ ask_examples:
   - Why are my API keys gone after restoring a backup?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - backup
   - restore
@@ -46,12 +45,12 @@ related:
 
 ## Goal
 
-Capture all of Aitne's durable state in a single tar archive you can
-restore later — on this machine or a fresh one.
+Save everything Aitne keeps on disk into a single tar archive (a `.tgz`
+file) that you can restore later — on this machine or a new one.
 
 ## What's in the backup (and what isn't)
 
-Everything Aitne persists lives under `PA_DATA_DIR` (default
+Everything Aitne saves 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
@@ -72,8 +71,9 @@ Both are re-added through the dashboard after restore.
 
 ## Steps
 
-1. **Stop the daemon** so the SQLite write-ahead log is checkpointed and
-   the snapshot is consistent:
+1. **Stop the daemon** (Aitne's background service). This flushes any
+   pending database writes to disk — the SQLite write-ahead log is
+   checkpointed — so your snapshot is a clean, consistent copy:
 
    ```bash
    aitne stop
@@ -95,7 +95,8 @@ Both are re-added through the dashboard after restore.
    ```
 
    Schema migrations run automatically on the first boot (see below), so
-   an older DB is brought up to the current shape without extra steps.
+   Aitne upgrades an older database to the current shape without extra
+   steps.
 
 4. **Re-register secrets and re-pair messaging** through the dashboard —
    they were never in the tar.
@@ -109,16 +110,18 @@ Both are re-added through the dashboard after restore.
 ## If It Fails
 
 - **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.
+  migrations — they only ever upgrade a database, never downgrade it —
+  and applies them automatically at boot (see
+  [Schema Migration](../glossary.md#schema-migration)), so a restored
+  database 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 database (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.
+  (Step 4). The database and context restore fine without them.
 
 ## Moving to a different machine?
 

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

@@ -15,7 +15,6 @@ summary: |
   to tune the threshold.
 section: budget-and-cost-for-wiki
 tags:
-  - guides
   - wiki
   - cost
   - approval
@@ -27,7 +26,7 @@ ask_examples:
   - What does the pre-compile snapshot do?
 locale: en-US
 created: 2026-05-12
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - wiki budget
   - wiki cost
@@ -56,92 +55,86 @@ ui_anchors:
 
 # Wiki Budgets and Cost
 
-The wiki ships with three cost knobs you can tune in
-**Settings → Wiki** (`/settings/wiki`):
+This is the operator's walkthrough for keeping wiki spending under
+control. For the deep mechanics — exactly how the estimate is
+computed and how the approval gate decides — see
+[features/wiki/cost-and-approval](../features/wiki/cost-and-approval.md).
 
-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.
+The wiki gives you three cost knobs, all in **Settings → Wiki**
+(`/settings/wiki`):
+
+1. **Per-command model picker** — one model per wiki process. The
+   picker covers `wiki.ingest_url`, `wiki.compile`, and `wiki.ask`,
+   plus the operational trio `wiki.lint`, `wiki.trace`, and
+   `wiki.connect`. Each starts on your main backend at the medium
+   tier. If you ingest a lot of URLs, drop `wiki.ingest_url` to a lite
+   tier to save money.
 2. **Per-process budget cap** (`max_budget_usd` on each row). The
-   dispatcher's per-session budget envelope is the enforcer.
+   dispatcher's per-session budget envelope enforces it.
 3. **Per-workspace `!compile full` approval threshold** (default
-   $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.
+   $2.00, range $0–$100). The estimator brackets the likely spend at
+   0.5× / 1× / 2× the estimated input-token count; if the worst-case
+   (2×) number crosses the threshold, `!compile full` asks for
+   approval instead of running on its own.
 
 ## 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 (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 = total_estimated_input_tokens / 1000 × $0.003
-optimistic   = 0.5 × expected
-pessimistic  = 2.0 × expected
-```
-
-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 5's ~$3 /
-Mtoken standard input price. (An introductory $2 / Mtoken rate runs
+rebuild touches every raw note. Before it runs, a small piece of
+plain JavaScript estimates the cost — it never spawns an agent, since
+spawning one just to estimate would itself burn budget. It walks the
+`10_raw/` layer, approximates each file's token count from its size on
+disk, and reports a low/high bracket so you can weigh a worst case
+before you approve. For the exact character-to-token ratios and the
+0.5× / 2× bracket math, see
+[features/wiki/cost-and-approval](../features/wiki/cost-and-approval.md).
+
+The unit cost (`$0.003` per 1k tokens) matches Claude Sonnet 5's ~$3
+/ Mtoken standard input price. (An introductory $2 / Mtoken rate runs
 through 2026-08-31; the estimate lists the standard rate, while the
 SDK's billed `total_cost_usd` reflects the intro price during the
-window.) The bracket lets you see a worst case before approving.
+window.)
 
 > 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'`, 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.
+- **Below threshold**: the compile runs on its own, and you get a
+  completion DM with the actual spend.
+- **Above threshold**: the compile pauses. It inserts an
+  `agent_schedule` row with `task_type='approval'`, DMs you the
+  estimate, and waits. The request shows up as an **Approvals** card
+  on the dashboard home page (`/`); the `/settings/wiki` page also
+  points you there. When you click **Approve**, the row flips to
+  `task_type='approved_task'` and the scheduler picks it up — only
+  then does Aitne take the pre-compile git snapshot (see below) and
+  start the compile session.
 
-If you change your mind, hit **Deny** on the approval card — the row
-flips to `skipped`, no git commit is made, and no agent session is
-spawned.
+Changed your mind? Click **Deny** on the approval card. The row flips
+to `skipped`, no git commit is made, and no agent session runs.
 
 ## Git Pre-Compile Snapshot
 
 On an external workspace that is a git repo and has **Auto-commit
-before `!compile full`** enabled, Aitne runs:
-
-```
-git -C <vault> status --porcelain
-# must be empty — dirty trees refuse the operation entirely
-git -C <vault> add -A
-git -C <vault> commit --allow-empty -m "aitne wiki: pre-compile snapshot <ISO-8601-ts>"
-```
-
-before the compile session starts. The commit message is
-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.
+before `!compile full`** enabled, Aitne commits the vault
+(`git add -A && git commit`) just before the compile session starts,
+giving you a rollback point. If the compile produces a surprise,
+`git reset --hard HEAD~1` puts the vault back. A dirty working tree
+refuses the operation entirely — commit or stash first, then re-run.
+The commit runs your normal pre-commit hooks (the `--no-verify` flag
+is not used).
 
 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.
+you can add one yourself before approving.
+
+For the full state-by-state table of what the snapshot gate does in
+each workspace configuration, see
+[features/wiki/cost-and-approval](../features/wiki/cost-and-approval.md).
 
 ## Tuning the Threshold
 

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

@@ -14,7 +14,6 @@ summary: |
   notes, and ask a question against the vault.
 section: build-your-wiki
 tags:
-  - guide
   - wiki
   - knowledge
 status: stable
@@ -24,7 +23,7 @@ ask_examples:
   - How do I compile my ingested notes into wiki articles?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - wiki
   - build wiki
@@ -53,14 +52,14 @@ prerequisites:
 
 ## Goal
 
-Stand up the internal wiki, capture a URL, compile it into a wiki
-article, and run a question against the result.
+Turn on the internal wiki, capture a URL, compile it into a wiki
+article, and ask a question about the result.
 
 ## Prerequisites
 
 - A paired messaging channel (Telegram, Slack, Discord, WhatsApp, or
   dashboard chat) — see
-  [Pairing and the Magic Phrase](../messaging/pairing-and-magic-phrase.md).
+  [Pairing and the Magic Phrase](../features/messaging/pairing-and-magic-phrase.md).
 - The daemon is running and the dashboard is reachable.
 
 ## Where you'll work in the dashboard
@@ -71,8 +70,8 @@ browsing lives under **My Life**.
 
 - **My Life → Wiki** (`/wiki`) — your main entry point. Shows
   workspace stats, the compiled `_index.md`, and recent activity. When
-  the wiki is not enabled yet, this page renders an **Enable Wiki**
-  call-to-action.
+  the wiki is not enabled yet, this page shows an **Enable Wiki**
+  button instead.
 - **Setup → Settings → Wiki** (`/settings/wiki`) — workspace creation,
   internal/external mode, per-command model selectors, budgets,
   archive / delete.
@@ -101,8 +100,8 @@ you enable a workspace, so you do not need to remember the URL.
    number of URLs queued.
 5. Wait for the per-URL completion DMs (parallel mode) or the single
    summary reply (serial mode).
-6. Run `!compile` to compile raw captures into wiki articles. The
-   compile session synthesises `20_wiki/<slug>.md` files and updates
+6. Run `!compile` to turn your raw captures into wiki articles. The
+   compile session writes `20_wiki/<slug>.md` files and updates
    `20_wiki/_index.md`.
 7. Ask a question: `!ask What did this source say about X?`. The
    answer is written to `30_outputs/<YYYY-MM-DD>-<slug>.md` with
@@ -115,9 +114,9 @@ returns the command list.
 ## What to Try Next
 
 - **Send multiple URLs at once**: `!ingest https://a.com, https://b.com`
-  fans out in parallel by default. Switch to serial mode on
-  `/settings/wiki` when you care about ordering and rate
-  predictability.
+  processes them in parallel (all at once) by default. Switch to serial
+  mode on `/settings/wiki` when you want them handled one at a time, for
+  predictable ordering and request pacing.
 - **Point at an existing Obsidian vault** instead of the daemon-owned
   root — see [Use An Existing Obsidian Vault](use-an-existing-obsidian-vault.md).
 - **Tune the budget** for `wiki.compile` and `wiki.ingest_url` from

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

@@ -14,7 +14,6 @@ summary: |
   reasoning, or run a routine on Codex while Claude stays the default.
 section: change-which-model-handles-x
 tags:
-  - guide
   - backends
   - operations
   - routing
@@ -25,7 +24,7 @@ ask_examples:
   - Can I change the model for just one ProcessKey?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - per-process model
   - /settings/models
@@ -54,50 +53,53 @@ config_keys:
 
 ## Goal
 
-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.
+Change the backend or model tier for a **single** ProcessKey — the label
+the agent gives to one kind of work, such as `routine.evening_review` —
+without touching the global default. Reach for this when one job needs a
+stronger (or cheaper) model than the shipped default: pin the evening
+review to Opus (high tier), or push a noisy delegated routine onto Gemini
+to save your Claude quota.
 
 ## Steps
 
 1. Open `/settings/models`.
 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
+3. Set its **main backend** and **tier** explicitly. Each tier picks 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).
+   `high` → Opus-class. You can also set a **fallback** backend to use if
+   the main one is unavailable.
+4. Save. The row is now marked operator-edited, so it keeps 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 5. The
-execution budget for that run also scales with the tier (high tier
-carries a larger turn / cost envelope than medium).
+run then uses **Opus 4.8** instead of the default Sonnet 5. The run's
+budget scales with the tier too — high tier carries a larger turn and
+cost envelope than medium.
 
 ## Verification
 
-- The next fire of that ProcessKey shows the new backend and model in
-  the **Activity** event detail (after fallback resolution).
+- The next time that ProcessKey runs, its **Activity** event detail
+  shows the new backend and model (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.
+- **`dashboard.docs_qa` is tier-locked to `medium`** — the router
+  ignores a high or lite pin on that row. It also takes its backend from
+  whatever `message.dm` is pinned to.
+- **High tier is opt-in, never auto-selected.** No shipped surface
+  defaults to high. The only `high`-tagged ProcessKey out of the box is
+  `delegated_task_heavy`, and that stays behind the
+  `delegatedTaskHeavyEnabled` config flag. You can still pin any *other*
+  ProcessKey to high here.
+- **Codex and Gemini ship no separate high model.** On those backends
+  the high tier falls back to the medium model, so pinning them to high
+  changes nothing unless you also pick a specific higher model in the
+  row.
 - To change the backend for *every* ProcessKey at once, use the global
   default instead — see Related.
 

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

@@ -17,7 +17,6 @@ summary: |
   use an app password.
 section: connect-a-new-mail-account
 tags:
-  - guide
   - mail
   - integrations
 status: stable
@@ -27,7 +26,7 @@ ask_examples:
   - How do I connect an Outlook mailbox?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - mail
   - imap
@@ -62,17 +61,17 @@ 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:
+The mail registry supports exactly four provider kinds — `gmail`,
+`outlook`, `yahoo`, `icloud`. It sticks to these hosted providers on
+purpose, so there is no separate "generic IMAP server" kind. Each kind
+signs in 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). |
+| **Gmail** | Uses the same primary Google sign-in you set up for the app (`/config/google-auth`). Adding extra Gmail accounts beyond that main Google identity isn't supported yet. |
+| **Outlook** | OAuth (a browser sign-in flow). A headless machine — one with no browser, such as a server you reach over SSH — falls back to a device code you type in instead. |
+| **Yahoo** | App password (connects over IMAP). |
+| **iCloud** | App password (connects over IMAP). |
 
 ## Prerequisites
 
@@ -87,39 +86,41 @@ kind authenticates differently:
 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.
+     connections flow (`/config/google-auth`). It then shows up in your
+     mail view 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.
+     machine (one you reach over SSH or WSL, with no browser of its
+     own), use the device-code fallback, which shows a code to type in
+     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 account is picked up on the next mail poll tick (default every
-   180 seconds, configurable via `mailPollIntervalSeconds`).
+4. Save. The account saves whether or not its provider is turned on in
+   the enabled-providers setting (`enabledMailProviders`); it goes live
+   only when you flip its **Enable** toggle on the mail card.
+5. The agent picks up the account on the next mail poll (by default
+   every 180 seconds, which you can change with
+   `mailPollIntervalSeconds`).
 
 ## Verification
 
-- The account row turns healthy on the auth-health card.
+- The account row turns healthy (green) on the auth-health card.
 - The mail count updates on `/connections/mail`.
 
 ## If It Fails
 
-- **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 OAuth never returns** — the sign-in flow opens a temporary
+  local port on `127.0.0.1`, so a fixed-port redirect mismatch isn't
+  the cause. Check that the browser actually opened and finished 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.
+  you add the account.
 - **Yahoo / iCloud login rejected** — re-check the address and the app
-  password (not your normal account password); regenerate the app
+  password (not your normal account password); generate a fresh 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.
+  identity is supported today; extra Gmail accounts aren't available
+  yet.
 
 ## Related
 

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

@@ -16,10 +16,7 @@ summary: |
   <b>` to find bridges between two domains.
 section: guides
 tags:
-  - guides
   - wiki
-  - exploration
-  - bang-commands
 status: stable
 ask_examples:
   - How do I trace an idea across the wiki?
@@ -30,7 +27,7 @@ ask_examples:
   - How do I run !trace against a non-default wiki workspace?
 locale: en-US
 created: 2026-05-12
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - "!trace"
   - "!connect"
@@ -55,35 +52,36 @@ ui_anchors:
 
 # Explore Your Wiki with `!trace` and `!connect`
 
-`!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.
+`!trace` and `!connect` are the two wiki exploration commands. Each
+one writes a single new document to `30_outputs/` and never changes
+your raw or wiki notes. Think of them as short, cited essays built
+only from what your wiki already 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.
+You send both as bang commands (a message that starts with `!`) in a
+direct message to the agent. Both also accept an optional leading
+`@<workspace>` token to point at a wiki workspace other than your
+default — for example `!trace @research formal methods` or
+`!connect @research category theory, distributed systems`. Leave the
+token off and the command runs against your default workspace.
 
 ## `!trace <topic>` — Time-Based Exploration
 
 Use `!trace` when you want to see **how thinking about a topic has
-evolved**. The wiki agent searches every layer, orders the matches
-chronologically (preferring dates asserted in the content over
-file mtimes), and groups them into two-to-five phases of stable
-framing.
+evolved**. The wiki agent searches every layer, puts the matches in
+time order (preferring dates written inside a note over the file's
+last-modified time), and groups them into two-to-five phases, each
+holding a stretch where the framing stayed roughly the same.
 
 ```
 !trace quantum computing
 !trace formal methods in distributed systems
 ```
 
-The topic is free-form prose. The skill canonicalises against
-`90_meta/taxonomy.md` before deriving the output slug, so
-`!trace quantum computing` and `!trace quantum-computing` produce
-the same output filename if `quantum-computing` is your canonical
-topic.
+The topic is free-form prose. Before it builds the output filename,
+the skill maps your wording to its standard form using
+`90_meta/taxonomy.md`, so `!trace quantum computing` and
+`!trace quantum-computing` produce the same filename when
+`quantum-computing` is your canonical topic.
 
 ### Output
 
@@ -117,9 +115,9 @@ says so directly. No padding, no speculation.
 Use `!connect` to find honest overlaps between two domains in
 your wiki. The agent surfaces four kinds of bridges:
 
-1. **Shared terminology** — terms that mean the same (or
-   recognisably different) things in each domain, disambiguated
-   against `90_meta/taxonomy.md`.
+1. **Shared terminology** — terms that mean the same (or clearly
+   different) things in each domain, sorted out against
+   `90_meta/taxonomy.md`.
 2. **Common references** — the same URL, author, or wiki note
    linked from both sides.
 3. **Structural analogies** — recurring patterns of reasoning or
@@ -153,16 +151,16 @@ The output lands at:
 ```
 
 The double-hyphen (`--`) separates the two canonical slugs in the
-filename. Each report cites bridges with at least one path from
-each side — a one-sided match becomes a bridging candidate, not a
-bridge.
+filename. Each report only counts a bridge when it has at least one
+supporting note from each side — a match found on just one side
+becomes a bridging candidate, not a bridge.
 
 ### Honest "No Connection" Reports
 
-If your wiki contains nothing in common between the two domains,
-the report still writes — with `_(none)_` filling the empty
-sections and a `## Summary` that says so plainly. A negative
-finding is itself useful: it tells you where the wiki has gaps.
+If your wiki holds nothing in common between the two domains, the
+report is still written — with `_(none)_` filling the empty
+sections and a `## Summary` that says so plainly. An empty result
+is useful in itself: it tells you where the wiki has gaps.
 
 ### `!connect` Does Not Create Wiki Notes