@aitne-sh/aitne 0.1.11 → 0.1.13

package/agent-assets/docs/features/routines/activity-scan.md

@@ -20,7 +20,6 @@ tags:
   - autonomous
   - observations
   - polling
-  - activity-scan
 status: stable
 ui_anchors:
   - /agents/activity-scan
@@ -34,7 +33,7 @@ ask_examples:
   - How do I tune the gate's freshness window?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - hourly
   - observations
@@ -70,11 +69,13 @@ config_keys:
 
 # Activity Scan
 
-A medium-tier routine that drains the observations queue every interval
-during active hours and decides whether the accumulated change
-pattern warrants notifying you or appending to `state/today.md`. The
-"decide" step is a four-layer gate designed to keep quiet days quiet
-without missing the moment when something piles up.
+A medium-tier routine that runs every interval during your active
+hours (the daily window when the agent is allowed to work). Each run
+empties the pending observations queue and decides whether the changes
+that piled up are worth notifying you about or just worth logging to
+`state/today.md`. That "decide" step is a four-layer gate, built to
+keep quiet days quiet without missing the moment something actually
+matters.
 
 ## When It Runs
 
@@ -89,7 +90,8 @@ The legacy `activityScan*` config keys are deprecated fallbacks (see
   (recoverable — the dispatcher enqueues a `queueMorningRoutineWake`
   self-recovery and the activity scan resumes after the morning
   routine succeeds).
-- **Skips** when another activity scan is in flight (atomic flag).
+- **Skips** when another activity scan is already running (an atomic
+  in-flight flag stops two runs from overlapping).
 - **Skips** when accumulated signal is below the agent's **min
   observations** threshold and the heartbeat window
   (`activityScanHeartbeatHours`) hasn't elapsed.
@@ -119,9 +121,10 @@ Telemetry: `agent_actions.detail.harvest_ran` /
 
 ### Layer 2 — Signal compute
 
-`computeActivityScanSignals` reads the observation table mode-blind —
-it filters by source-prefix sets derived from
-`INTEGRATION_DESCRIPTORS`, never by `actor`. Signal categories
+`computeActivityScanSignals` reads the observation table mode-blind
+(it does not care which integration mode wrote a row) — it filters by
+source-prefix sets derived from `INTEGRATION_DESCRIPTORS`, never by
+`actor`. Signal categories
 include unread-mail / event-change / repo-change / browser-history
 clusters; each category produces a (count, last-seen, summary)
 tuple. The pre-pass freshness gate from Layer 1 is what guarantees

package/agent-assets/docs/features/routines/custom-routines.md

@@ -22,7 +22,6 @@ tags:
   - agents
   - autonomous
   - scheduler
-  - advanced
 status: deprecated
 ask_examples:
   - What happened to my custom routines?
@@ -31,7 +30,7 @@ ask_examples:
   - How do I create a recurring task now?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - custom routine
   - routine.custom.<slug>
@@ -73,19 +72,21 @@ once, at the first daemon start after the upgrade.
 - Recurring work you define is now an **Agent**: a
   `policies/agents/<slug>/agent.md` file that appears on the
   **Agents** page (`/agents`) with its schedule, an enable toggle, run
-  metrics, execution history, and a **Run now** button — surfaces
+  metrics, execution history, and a **Run now** button — features
   custom routines never had. See
   [Create a Recurring Agent](../../guides/add-a-custom-routine.md).
 
 ## The One-Time Migration
 
-At the first daemon start after the upgrade — and only once, guarded
-by a persisted flag — every file under `policies/routines/custom/` is
+The first time the daemon (Aitne's background service) starts after
+the upgrade — and only that once, guarded by a saved flag so it can
+never run twice — every file under `policies/routines/custom/` is
 examined:
 
 - A **valid routine becomes a user Agent** at
   `policies/agents/<slug>/agent.md` carrying over:
-  - the same **cron expression** (pinned to your configured timezone),
+  - the same **cron expression** (the schedule rule, pinned to your
+    configured timezone),
   - the same **model tier** (`backend_tier` → the Agent's tier),
   - the same **per-run budget** (`max_budget_usd`),
   - the same **enabled state** — a disabled routine migrates disabled.
@@ -95,7 +96,8 @@ examined:
   it came from (`Migrated from custom routine "<slug>".`).
 - The **source file is never deleted.** It is rewritten in place with
   `enabled: false` and a `migrated_to_agent: <slug>` marker in its
-  frontmatter, so it is visibly inert while your content is preserved.
+  frontmatter, so you can plainly see it no longer runs while your
+  original content is preserved.
 
 ### Collisions and invalid files
 

package/agent-assets/docs/features/routines/evening-review.md

@@ -17,8 +17,6 @@ section: routines
 tags:
   - routines
   - autonomous
-  - daily
-  - core
 status: stable
 ask_examples:
   - When does the evening review run?
@@ -27,7 +25,7 @@ ask_examples:
   - How do I disable the evening review?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - evening review
   - retro
@@ -89,10 +87,11 @@ rather than producing a chatty end-of-day report.
 
 ## When It Runs / How It Is Triggered
 
-Every day at **18:00 local time**, exactly once. The cron expression
-(`0 18 * * *`) is fixed in `packages/daemon/src/core/scheduler.ts`; the
-fire time is not operator-configurable. Like every autonomous cron, the
-run is skipped while the agent is paused (`!stop`) or setup is incomplete.
+Every day at **18:00 local time**, exactly once. The schedule — a cron
+expression (`0 18 * * *`, the standard five-field way to write "18:00 every
+day") — is fixed in `packages/daemon/src/core/scheduler.ts`, so you can't
+change the fire time. Like every autonomous routine, the run is skipped
+while the agent is paused (`!stop`) or setup is not finished.
 
 ## What It Outputs
 

package/agent-assets/docs/features/routines/morning-routine.md

@@ -16,8 +16,7 @@ section: routines
 tags:
   - routines
   - autonomous
-  - daily
-  - core
+  - scheduler
 status: stable
 ask_examples:
   - When does morning routine run?
@@ -26,7 +25,7 @@ ask_examples:
   - What model does morning routine use?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - morning
   - day plan
@@ -63,9 +62,10 @@ context_files:
 
 ## In One Sentence
 
-Once per agent day, at `dayBoundaryHour` local time, Aitne
-rebuilds `state/today.md` and the day's schedule from your calendar, mail,
-roadmap, and recent observations.
+Once per agent day (the daily window that starts when "today" rolls
+over), at `dayBoundaryHour` local time, Aitne rebuilds `state/today.md`
+and the day's schedule from your calendar, mail, roadmap, and recent
+observations.
 
 ## What It Does
 
@@ -74,16 +74,17 @@ It runs as a **two-stage pipeline**, with both stages dispatched in
 parallel:
 
 - **Stage A** (`routine.morning_routine_today`, medium tier) rebuilds
-  `state/today.md`, walks the roadmap, fans out the day's schedule, and
-  self-reports structured metadata.
-- **Stage B** (`routine.morning_routine_journal`, lite tier) authors
+  `state/today.md`, walks the roadmap, fans out the day's schedule (queues
+  each of today's scheduled tasks), and reports structured metadata about
+  the run.
+- **Stage B** (`routine.morning_routine_journal`, lite tier) writes
   yesterday's daily journal at `journal/daily/<yesterday>.md` from a
-  daemon-prepared skeleton, then drops the run's audit-trail paragraph
-  into `journal/agent.md`.
+  daemon-prepared skeleton, then appends the run's audit-trail paragraph
+  to `journal/agent.md`.
 
-Every downstream routine for the next 24 hours reads Stage A's output,
-so a bad morning briefing degrades the entire day — hence the
-medium-tier ceiling on Stage A even after the split.
+Every routine that runs over the next 24 hours reads Stage A's output, so
+a bad morning briefing drags down the whole day. That is why Stage A stays
+capped at the medium tier even after the split.
 
 Within Stage A, the work proceeds in this order:
 
@@ -103,12 +104,12 @@ so a post-midnight install does not run two morning routines back-to-back.
 There is no separate `morningRoutineHour` — the morning routine and the
 agent-day rollover are the same instant.
 
-There is no separate "initial" process key. The first morning after
-setup is detected inline by Stage A from the absence of `state/yesterday.md`;
-the daemon injects a `<roadmap_skeleton>` block carrying the pre-aggregated
-Annual Goals / Quarterly Focus / Preparation Timeline facts so Stage A
-can populate the wizard's placeholder roadmap on medium tier instead of
-paying for a one-shot high-tier session. (The dedicated
+There is no separate "initial" process key. Stage A detects the first
+morning after setup on its own, from the missing `state/yesterday.md` file.
+The daemon then injects a `<roadmap_skeleton>` block carrying the
+pre-aggregated Annual Goals / Quarterly Focus / Preparation Timeline facts,
+so Stage A can fill in the wizard's placeholder roadmap on the medium tier
+instead of paying for a one-shot high-tier session. (The dedicated
 `routine.morning_routine_initial` process key — along with its high-tier
 seed — was retired in Phase 7, 2026-05-16; the first-run branch now flows
 through the parent `routine.morning_routine` envelope.)
@@ -133,9 +134,9 @@ through the parent `routine.morning_routine` envelope.)
 | Setting | Default | Notes |
 |---|---|---|
 | `dayBoundaryHour` | `4` | Both the agent-day boundary and the morning-routine fire time. See [Agent Day](../../concepts/agent-day.md). |
-| Stage A tier (`routine.morning_routine_today`) | medium (Sonnet 4.6) | Synthesises `state/today.md` + the day's roadmap fan-out. Adjustable per-row in Settings → Models. |
+| Stage A tier (`routine.morning_routine_today`) | medium (Sonnet 5) | Synthesises `state/today.md` + the day's roadmap fan-out. Adjustable per-row in Settings → Models. |
 | Stage B tier (`routine.morning_routine_journal`) | lite (Haiku 4.5) | Authors `journal/daily/<date>.md` and the `journal/agent.md` audit paragraph. |
-| Stage A max turns / budget | 50 turns / $1.50 | Per-execute envelope for `routine.morning_routine_today`. Adjustable in Settings → Models. |
+| Stage A max turns / budget | 50 turns / $2.00 | Per-execute envelope for `routine.morning_routine_today`. Adjustable in Settings → Models. |
 | Stage B max turns / budget | 20 turns / $0.30 | Per-execute envelope for `routine.morning_routine_journal`. |
 
 The parent `routine.morning_routine` key keeps its own envelope (50 turns / $2.00) for the pipeline entry point. Codex and Gemini backends scale the dollar caps by a per-tier factor (lite ×2.5, medium ×1.5); the router enforces the cap before token costs accumulate.

package/agent-assets/docs/features/routines/weekly-review.md

@@ -19,7 +19,6 @@ tags:
   - routines
   - autonomous
   - journal
-  - reflection
 status: stable
 ask_examples:
   - When does the weekly review run?
@@ -27,7 +26,7 @@ ask_examples:
   - Where do weekly retros get stored?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - weekly review
   - Friday review
@@ -58,49 +57,54 @@ context_files:
 
 ## In One Sentence
 
-A medium-tier weekly retro fires every Friday evening and writes a
-synthesis into `journal/weekly/YYYY-Www.md` (ISO week), whose
-**Carry Over / Next Week Focus / Lessons** sections are then lifted
-into every morning routine of the following ISO week.
+Every Friday evening, a medium-tier weekly retrospective (a look back
+over the week) runs and writes a summary into
+`journal/weekly/YYYY-Www.md` — one file per ISO week (the standard
+Mon–Sun week numbering). Its **Carry Over / Next Week Focus /
+Lessons** sections are then copied into every morning routine of the
+following ISO week.
 
 ## What It Does
 
 - Reads each `journal/daily/YYYY-MM-DD.md` for the current ISO week,
   the week's calendar retrospective, the roadmap, and active projects.
-- Synthesizes three axes — Outcomes, Forward items, Behavioral
-  Lessons — and writes the user-facing snapshot.
-- Appends an agent-internal block to `journal/agent.md` for
+- Pulls this together along three lines — Outcomes, Forward items,
+  and Behavioral Lessons — and writes the summary you read.
+- Adds a private, agent-only block to `journal/agent.md` covering
   self-critique, filter quality, and improvement ideas.
-- Feeds the learning loop: for each concrete, actionable system
-  improvement idea it identifies, it also posts a `source=self_critique`
-  feedback signal (in addition to the `journal/agent.md` prose), so the
-  idea is consolidated into the [agent lessons](../memory-files/agent-lessons.md)
-  rather than only living in the journal.
-- Judges the daemon's self-tuning recommendations: when the weekly
-  pre-step finds a cost knob worth changing (e.g. raising the mail
-  pre-pass freshness window because most fetches came back empty), it
-  injects up to three bounded proposals and the review records an
-  apply / reject / defer verdict for each. While `selfTuningEnabled` is
-  `false` (the default) nothing is ever changed automatically — verdicts
-  are recorded for the owner to review (shadow mode). With the flag on,
-  an apply verdict is actuated immediately by the daemon within hard
-  per-key bounds; the owner gets a one-line DM per applied change
-  (`!revert tuning` undoes the latest one) and a daily monitor
-  auto-reverts any change whose 7-day follow-up metrics regressed.
-- Sends a brief Friday-evening notification by default (the silence
-  gate triggers only on an essentially blank week).
-- Refreshes `identity/reading-taste.md` and Book Candidates when
-  enough new highlights have accumulated.
+- Feeds the learning loop: for each concrete, actionable improvement
+  idea it finds, it also posts a `source=self_critique` feedback
+  signal (on top of the `journal/agent.md` note), so the idea gets
+  folded into the [agent lessons](../memory-files/agent-lessons.md)
+  instead of only living in the journal.
+- Reviews the daemon's self-tuning suggestions: when the weekly
+  pre-step spots a cost setting worth changing (for example, widening
+  the mail pre-pass freshness window because most fetches came back
+  empty), it puts forward up to three bounded proposals, and the
+  review records an apply / reject / defer verdict for each. While
+  `selfTuningEnabled` is `false` (the default), nothing changes
+  automatically — the verdicts are only recorded for the owner to
+  review (this is called shadow mode). With the flag on, an apply
+  verdict takes effect immediately, kept inside hard per-key limits;
+  the owner gets a one-line DM for each applied change
+  (`!revert tuning` undoes the most recent one), and a daily monitor
+  automatically rolls back any change whose 7-day follow-up metrics
+  got worse.
+- Sends a short Friday-evening notification by default. It stays quiet
+  (the silence gate) only when the week was essentially blank.
+- Refreshes `identity/reading-taste.md` and your Book Candidates once
+  enough new highlights have piled up.
 
 ## When It Runs / How It Is Triggered
 
-Every **Friday at 19:00 local time** (one hour after `evening_review`).
-The schedule is fixed in `packages/daemon/src/core/scheduler.ts` and is
-not operator-configurable. If the Friday fire misses (daemon outage),
-the **Fri / Sat / Sun catch-up window** in `schedule-helpers.ts` fires
-the retro when the daemon recovers, before the new ISO week begins —
-a Mon–Thu catch-up is intentionally out of scope so the next week's
-`<previous_week>` injection stays stable Mon–Sun.
+It runs every **Friday at 19:00 local time**, one hour after
+`evening_review`. The schedule is fixed in
+`packages/daemon/src/core/scheduler.ts` and can't be changed. If the
+Friday run is missed (say, the daemon was down), the **Fri / Sat / Sun
+catch-up window** in `schedule-helpers.ts` runs the retro as soon as
+the daemon recovers, before the new ISO week begins. A Mon–Thu
+catch-up is left out on purpose, so the next week's `<previous_week>`
+injection stays a stable Mon–Sun.
 
 ## What It Outputs
 
@@ -111,25 +115,27 @@ a Mon–Thu catch-up is intentionally out of scope so the next week's
 
 ## Configuration
 
-The fire time (Friday 19:00 local) and day-of-week are fixed in code
-and are not operator-tunable. The backend and model that handle this
-routine, however, are configurable: `routine.weekly_review` is a
-configurable process key (default **medium** tier — Sonnet on Claude)
-that you can repoint from **Settings → Models**. The weekly rulebook
+The run time (Friday 19:00 local) and the day of the week are fixed in
+code and can't be changed. What you *can* change is the backend and
+model behind this routine: `routine.weekly_review` is a configurable
+process key (default **medium** tier — Sonnet on Claude) that you can
+repoint from **Settings → Models**. The weekly rulebook
 (`policies/routines/weekly.md`) is edited on the weekly-review agent's
-Rulebook tab (`/agents/weekly-review?tab=rulebook`), where the agent
-can also be enabled or disabled.
+Rulebook tab (`/agents/weekly-review?tab=rulebook`), where you can also
+enable or disable the agent.
 
 ## When Something Goes Wrong
 
-- The retro **doesn't fire on Friday**: the Fri–Sun catch-up window
-  retries on Saturday and Sunday agent-days. A full Fri–Sun outage
-  results in a missing weekly file; the next week's morning routines
-  proceed without the `<previous_week>` block.
-- The retro **runs but the file is empty** (silence gate): legitimate
-  for a blank week — the file is still written with empty sections,
-  and the next week's morning routine sees `(none recorded)` sub-
-  blocks, which is the deliberate downstream signal.
+- The retro **doesn't run on Friday**: the Fri–Sun catch-up window
+  retries on the Saturday and Sunday agent-days (the agent's own day,
+  which rolls over at `dayBoundaryHour` rather than at midnight). If
+  the daemon is down for the whole Fri–Sun window, the weekly file is
+  never written, and the next week's morning routines simply carry on
+  without the `<previous_week>` block.
+- The retro **runs but the file is empty** (the silence gate): this is
+  fine for a genuinely blank week — the file is still written, just
+  with empty sections, and the next week's morning routine sees
+  `(none recorded)` sub-blocks. That is the intended signal, not a bug.
 
 ## Related
 

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

@@ -21,8 +21,6 @@ summary: |
 section: wiki
 tags:
   - wiki
-  - bang-commands
-  - core
 status: stable
 ask_examples:
   - How do I send a URL to the wiki?
@@ -34,7 +32,7 @@ ask_examples:
   - How do I bridge two domains with `!connect`?
 locale: en-US
 created: 2026-05-12
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - !ingest
   - !compile
@@ -48,6 +46,7 @@ keywords:
 related:
   - features/wiki/overview
   - features/messaging/bang-commands
+  - features/wiki/cost-and-approval
   - guides/budget-and-cost-for-wiki
   - guides/maintain-wiki-health
   - guides/explore-with-trace-and-connect
@@ -67,9 +66,10 @@ ui_anchors:
 
 # Wiki Commands
 
-Use these from a paired DM channel after enabling the wiki. Open
+These are bang commands — chat messages that start with `!`. Send
+them from a paired DM channel once the wiki is turned on. Open
 **Settings → Wiki** (`/settings/wiki`) to enable a workspace, then
-browse the result from **My Life → Wiki** (`/wiki`).
+read the results under **My Life → Wiki** (`/wiki`).
 
 | Command | Effect |
 |---|---|
@@ -91,17 +91,17 @@ 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:
+accepts an optional `@<name>` token right after the bang. Aitne reads
+this token first and removes it before the command parses the rest of
+your message, so multi-word topics and comma-separated arguments still
+work as usual:
 
     !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`
+See [guides/multiple-wikis-for-multiple-domains](../../guides/multiple-wikis-for-multiple-domains.md)
 for a walkthrough.
 
 ## `!compile --preview` — the dry run
@@ -119,14 +119,15 @@ Use `!compile --preview` (or `--dry-run`) when you want to see what
 - **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.
+Treat the preview as an upper bound. The real compile runs an LLM,
+which may merge or skip pages as it works, so the preview cannot
+predict the outcome exactly — but it will never undercount the pages
+it touches. Reply `!compile` (or `!compile full`) to run the compile
+for real.
 
 ## Dispatch Mode for `!ingest`
 
-`!ingest` honours the per-workspace **dispatch mode** in
+`!ingest` follows the per-workspace **dispatch mode** set in
 Settings → Wiki:
 
 - **Parallel** (default): all URLs fan out simultaneously up to the
@@ -142,11 +143,11 @@ The acknowledgement DM names the mode that ran (`in parallel` /
 
 ## `!compile full` — the Cost Gate
 
-Full rebuilds touch every wiki note and are the most expensive
-command in the wiki surface. The flow:
+Full rebuilds touch every wiki note, so they are the most expensive
+command in the wiki surface. Here is what happens when you run one:
 
 1. The bang handler estimates the cost (per raw note, an on-disk
-   char→token approximation × Sonnet 4.6 input price, bracketed
+   char→token approximation × Sonnet 5 input price, bracketed
    optimistic 0.5× / expected 1× / pessimistic 2×).
 2. On an external git-tracked vault with **Auto-commit before
    `!compile full`** enabled and a clean working tree, Aitne runs
@@ -160,15 +161,20 @@ command in the wiki surface. The flow:
 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.
+The same estimate is shown live in **Settings → Wiki**, so you can
+see what the next `!compile full` will cost before you run it. See
+[features/wiki/cost-and-approval](cost-and-approval.md) for the full
+cost-estimation and approval reference.
 
 ## 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/`).
+(`90_meta/health/`) or output documents (`30_outputs/`). This
+section is the command reference; for the step-by-step workflows,
+see [guides/maintain-wiki-health](../../guides/maintain-wiki-health.md)
+and [guides/explore-with-trace-and-connect](../../guides/explore-with-trace-and-connect.md).
 
 ### `!lint`
 
@@ -197,7 +203,7 @@ 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
+wiki layer. Use a free-form topic — the skill matches it against
 `90_meta/taxonomy.md` before deriving the output slug:
 
 ```

package/agent-assets/docs/features/wiki/cost-and-approval.md

@@ -25,7 +25,6 @@ tags:
   - cost
   - approval
   - safety
-  - core
 status: stable
 ask_examples:
   - How does !compile full estimate cost?
@@ -39,7 +38,7 @@ ask_examples:
   - Can I see the cost before running !compile full?
 locale: en-US
 created: 2026-05-21
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - cost estimate
   - cost bracket
@@ -106,26 +105,30 @@ The same estimator backs four surfaces so the numbers cannot drift:
 
 ## How the estimator works
 
-Pure JS, no agent session, no SDK call. The estimator
-(`packages/daemon/src/core/wiki/cost-estimate.ts`) opens each raw
-note under `10_raw/`, approximates its token count from on-disk
-content, then multiplies the total by the tier unit cost and
-brackets with 0.5×/2× multipliers.
+The estimate is plain JavaScript math — it never starts an agent or
+calls the model, so it costs nothing and returns instantly. The
+estimator (`packages/daemon/src/core/wiki/cost-estimate.ts`) opens
+each raw note under `10_raw/`, approximates its token count from the
+text on disk, then multiplies the total by the tier unit cost and
+wraps it in a 0.5×/2× bracket (a low/high range).
 
 ### Character → token approximation
 
-- **Latin / English content** — ~4 chars per token. The well-known
-  OpenAI rule-of-thumb; matches Anthropic's tokenizer within ±15%
-  for prose; confirmed against the gpt-tokenizer dist.
-- **CJK content** — ~1.5 chars per token. BPE merges short CJK runs
-  but not as aggressively as Latin word fragments.
-
-The classifier counts Unicode code points whose script is one of
-Han, Hiragana, Katakana, Hangul, Bopomofo. If the document is
-majority-CJK we apply the CJK divisor to the entire file; otherwise
-Latin. A per-script split per file would be marginally more accurate
-but adds 30% code for a sub-percent gain on typical mixed-script
-files.
+- **Latin / English content** — about 4 characters per token. This
+  is the well-known OpenAI rule-of-thumb; it matches Anthropic's
+  tokenizer within ±15% for prose, confirmed against the
+  gpt-tokenizer package.
+- **CJK content** (Chinese, Japanese, Korean) — about 1.5 characters
+  per token. The tokenizer merges short CJK runs, but not as
+  aggressively as it merges Latin word fragments, so each character
+  carries more weight.
+
+To pick a ratio, the classifier counts the Unicode code points whose
+script is one of Han, Hiragana, Katakana, Hangul, or Bopomofo. If a
+file is majority-CJK, the CJK ratio applies to the whole file;
+otherwise the Latin ratio does. Splitting each file script-by-script
+would be slightly more accurate, but it adds 30% more code for a
+sub-percent gain on typical mixed-script files, so we don't.
 
 ### The 0.5×/2× bracket
 
@@ -188,7 +191,8 @@ estimate landed to the actual cost.
 
 ## The pre-compile git snapshot
 
-Only meaningful on an **external + git-tracked** vault. The gate
+This only matters for an **external + git-tracked** vault — a vault
+stored outside Aitne whose folder is a git repository. The gate
 decides:
 
 | Workspace state | Outcome |
@@ -202,9 +206,10 @@ decides:
 The snapshot is your rollback target if `!compile full` produces a
 surprise — `git reset --hard <snapshot-commit>` puts the vault back.
 
-The pre-compile commit uses no special author identity; it lands
-under whatever git is configured to use. If you co-author with
-Aitne, you'll want to set that up at the git config level.
+The pre-compile commit uses no special author identity — it lands
+under whatever name and email your git is already configured to use.
+If you want to credit Aitne as a co-author, set that up in your git
+config.
 
 ## The `--preview` dry-run