@aitne-sh/aitne 0.1.11 → 0.1.13

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
 

package/agent-assets/docs/guides/import-knowledge-file.md

@@ -15,9 +15,7 @@ summary: |
   recipes for exporting your existing profile out of ChatGPT and Gemini.
 section: import-knowledge-file
 tags:
-  - guides
   - knowledge
-  - import
   - memory
 status: stable
 ask_examples:
@@ -27,7 +25,7 @@ ask_examples:
   - What format does the Knowledge upload accept?
 locale: en-US
 created: 2026-04-28
-updated: 2026-05-28
+updated: 2026-07-01
 ui_anchors:
   - /knowledge
 keywords:
@@ -58,9 +56,10 @@ Bring a single Markdown (`.md`, `.markdown`) or plain-text (`.txt`)
 file you wrote elsewhere — a hand-written profile, an Obsidian or
 Notion export, or a summary you produced in ChatGPT / Gemini — into
 Aitne's `identity/*.md` Context Files. The agent reads the file once
-and appends each fact verbatim into the right topic file. Existing
-bullets are never overwritten; identity-class facts are deferred for
-your explicit confirmation.
+and appends each fact, word for word, into the right topic file. It
+never overwrites bullets you already have, and it holds back
+identity-class facts — things like your legal name or timezone — until
+you confirm them yourself.
 
 ## Prerequisites
 
@@ -130,8 +129,8 @@ date inline, so you can resolve them later without losing data.
 - **`415 unsupported_extension`** — the file is not `.md`,
   `.markdown`, or `.txt`. Convert PDFs / DOCX / HTML to plain
   Markdown first.
-- **`413 file_too_large`** — exceed 64 KB. Split the file into
-  smaller chunks and upload each separately.
+- **`413 file_too_large`** — the file is over 64 KB. Split it into
+  smaller chunks and upload each one separately.
 - **`400 secret_shape_detected`** — the route found content shaped
   like a private key or token. Remove the offending lines and re-
   upload.
@@ -152,8 +151,8 @@ following two paths produce a file that uploads cleanly.
 ### Recommended: ask ChatGPT to write it for you (≈ 2 min)
 
 Works against ChatGPT's *Memory* feature — the model already holds a
-list of personal facts about you. This procedure asks it to dump them
-in the exact format the upload expects.
+list of personal facts about you. This recipe asks it to write those
+out in the exact format the upload expects.
 
 1. Open <https://chatgpt.com> and start a **new conversation**. (Use
    a model with Memory enabled — GPT-4o, GPT-5, etc.)

package/agent-assets/docs/guides/install-and-run.md

@@ -15,12 +15,10 @@ summary: |
   start the daemon and dashboard, and open the dashboard at :8322.
 section: install-and-run
 tags:
-  - core
-  - guides
   - getting-started
-  - install
   - setup
   - operations
+  - migration
 status: stable
 ask_examples:
   - How do I install Aitne?
@@ -29,7 +27,7 @@ ask_examples:
   - How do I install the aitne npm package?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - install
   - first run
@@ -90,10 +88,10 @@ pnpm install
 pnpm start
 ```
 
-`pnpm start` builds first when the source is stale (mtime check against
-`.buildstamp`), then launches the daemon + dashboard detached. The
-`pnpm <cmd>` scripts are thin aliases that forward to
-`node bin/aitne.mjs <cmd>`.
+`pnpm start` builds first if the source has changed since the last build
+(a modified-time check against `.buildstamp`), then launches the daemon
+and dashboard in the background. The `pnpm <cmd>` scripts are thin aliases
+that forward to `node bin/aitne.mjs <cmd>`.
 
 ### Then, for both paths
 
@@ -101,8 +99,9 @@ Open `http://localhost:8322` and follow the setup wizard.
 
 ## Verification
 
-- `aitne status` (or `pnpm status` from a clone) shows two PIDs (daemon
-  + dashboard), uptime, connected backends, and a green health pill.
+- `aitne status` (or `pnpm status` from a clone) shows two process IDs
+  (one for the daemon, one for the dashboard), uptime, connected backends,
+  and a green health pill.
 - `~/.personal-agent/` has been created, containing
   `data/personal_agent.db`, `context/`, and `logs/`.
 

package/agent-assets/docs/guides/maintain-wiki-health.md

@@ -16,7 +16,6 @@ summary: |
   approval before promoting them.
 section: maintain-wiki-health
 tags:
-  - guides
   - wiki
   - health
 status: stable
@@ -28,7 +27,7 @@ ask_examples:
   - What is a taxonomy candidate?
 locale: en-US
 created: 2026-05-12
-updated: 2026-06-07
+updated: 2026-07-01
 keywords:
   - wiki health
   - wiki lint
@@ -59,11 +58,12 @@ ui_anchors:
 
 # Maintain Wiki Health
 
-The wiki is a living artifact. Notes accumulate, sources drift,
-slugs collide, and the taxonomy slowly diverges from the vocabulary
-your raw notes actually use. `!lint` is the periodic audit pass
-that surfaces all of this in one report — without changing your
-notes itself.
+The wiki is a living thing. Notes pile up, sources go stale,
+slugs (the short id each note is filed under) collide, and the
+taxonomy — the list of canonical topic names your notes are filed
+under — slowly drifts away from the words your raw notes actually
+use. `!lint` is the periodic audit that surfaces all of this in one
+report, without changing any of your notes.
 
 ## When to Run
 
@@ -120,7 +120,7 @@ page is also reachable from a button at the top of `/settings/wiki`,
 and the same view is mirrored under `/settings/wiki/timeline`. The
 most-recent report is parsed and rendered with:
 
-- A coloured date badge.
+- A colored date badge.
 - The `## Summary` bullets.
 - The `## Action items` list (this is the part you actually act on).
 - A "View full report" expander showing the raw Markdown for
@@ -132,8 +132,8 @@ that produced the state.
 
 ## Acting on Action Items
 
-The audit never modifies content layers itself. For each action
-item:
+The audit never edits your notes itself — it only reports. For each
+action item:
 
 - **Orphan** → either link the note from `20_wiki/_index.md` and
   related notes, or archive it. From a DM you can run `!ask` to

package/agent-assets/docs/guides/migrate-machines.md

@@ -15,7 +15,6 @@ summary: |
   because schema migrations auto-forward at boot.
 section: migrate-machines
 tags:
-  - guides
   - operations
   - migration
   - backup
@@ -25,7 +24,7 @@ ask_examples:
   - Will my DB still work after upgrading on the new machine?
 locale: en-US
 created: 2026-04-25
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - migrate
   - move install
@@ -50,22 +49,25 @@ context-file history or activity logs.
 | `~/.personal-agent/data/personal_agent.db` (sessions, actions, observations, FTS) | Messaging pairing tokens (Slack / Telegram / Discord / WhatsApp) |
 | `~/.personal-agent/logs/` (optional — for reference) | Integration OAuth grants (Gmail / Google Calendar / Notion) |
 
-The DB carries cleanly even across daemon versions: at boot, Aitne
-runs forward-only migrations from `packages/daemon/src/db/migrations.ts`
-that bring older schemas up to the current shape. As long as you're
-upgrading (not downgrading), the same DB works.
+The database carries cleanly even across daemon versions. Each time it
+starts, Aitne runs forward-only migrations from
+`packages/daemon/src/db/migrations.ts` — one-way updates that bring an
+older database up to the current shape. As long as you're upgrading
+(not downgrading), the same database works.
 
 ## Steps
 
-1. **On the old machine:** stop the daemon.
+1. **On the old machine:** stop the daemon (the background Aitne process).
    ```bash
    aitne stop
    ```
-2. **Copy the data directory** to the new machine — context plus DB.
+2. **Copy the data directory** to the new machine — the context files
+   plus the database. The command below uses `rsync`, a standard
+   file-copy tool.
    ```bash
    rsync -av ~/.personal-agent/ user@new-host:~/.personal-agent/
    ```
-   (Or rsync just `context/` and `data/` if you want to skip logs.)
+   (Or copy just `context/` and `data/` if you want to skip the logs.)
 3. **On the new machine:** install per [Install and Run](install-and-run.md).
 4. **Re-register secrets and re-pair messaging** through the dashboard:
    - Re-register each backend's API key, or re-run its CLI auth flow for
@@ -73,16 +75,16 @@ upgrading (not downgrading), the same DB works.
      Gemini run `gemini` and choose **Sign in with Google**.
    - Walk the setup wizard's messaging pairing steps for each app you
      had paired.
-   - Re-authorize each integration's OAuth grant (Gmail / Calendar /
-     Notion are the common ones).
+   - Re-authorize each integration's OAuth grant — the access you
+     approved for Gmail, Calendar, and Notion (the common ones).
 5. Start the daemon.
    ```bash
    aitne start
    ```
 
-On first boot the migration runner brings the carried DB up to the
-new daemon's schema. Check the daemon log if you want to see exactly
-which migrations applied:
+On first boot the migration runner brings the carried database up to
+the new daemon's schema. Check the daemon log if you want to see
+exactly which migrations applied:
 
 ```bash
 aitne logs -n 200 | grep -i migration

package/agent-assets/docs/guides/multiple-wikis-for-multiple-domains.md

@@ -15,7 +15,6 @@ summary: |
   on disk.
 section: guides
 tags:
-  - guides
   - wiki
   - workspaces
   - knowledge
@@ -26,7 +25,7 @@ ask_examples:
   - What does `@research` do before a wiki command?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-28
+updated: 2026-07-01
 keywords:
   - multi-workspace
   - wiki workspace
@@ -76,10 +75,10 @@ DM agent routes commands per workspace; the file trees never overlap.
   pull from your parenting journal. Separate workspaces give you
   separate `_index.md` and `20_wiki/` trees so the agent never has to
   filter across domains.
-- **Different audiences.** A workspace synced via Obsidian to a shared
-  iCloud folder for a team is governed differently from the daemon's
-  internal workspace under its data directory. Per-workspace settings
-  handle the asymmetry.
+- **Different audiences.** A workspace that Obsidian syncs to a shared
+  iCloud folder for a team needs different handling from the daemon's
+  own internal workspace under its data directory. Per-workspace
+  settings let you treat each one on its own terms.
 - **Different cadences.** A "current project" wiki gets multiple
   ingests per day; a long-term commonplace book may compile weekly.
   Per-workspace dispatch / cost / approval thresholds let you tune
@@ -138,12 +137,12 @@ comma-separated arguments verbatim.
 
 ## What the agent sees per workspace
 
-Each session is materialised against a single workspace's tree. The
-`wiki-vault-rules` skill loaded for the session names that workspace's
-language, dispatch mode, layer invariants, and frontmatter
-conventions. Layer authorisation in the daemon API is workspace-scoped
-— a `wiki.ask` session against `@research` cannot reach into
-`@parenting`'s `10_raw/` even if the agent attempts it.
+Each session works against a single workspace's file tree. The
+`wiki-vault-rules` skill loaded for the session spells out that
+workspace's language, dispatch mode, layer rules, and frontmatter
+conventions. Access to vault layers is workspace-scoped in the daemon
+API: a `wiki.ask` session against `@research` cannot reach into
+`@parenting`'s `10_raw/`, even if the agent tries.
 
 ## `!wiki` status with multiple workspaces
 
@@ -196,7 +195,7 @@ vault on Opus 4.8 and a parenting journal on Haiku 4.5 at the same
 time, you cannot — the `wiki.ask` row resolves to one backend/model for
 every workspace. The pragmatic shape is:
 
-- Bind `wiki.ask` to its medium-tier default (Sonnet 4.6), a sensible
+- Bind `wiki.ask` to its medium-tier default (Sonnet 5), a sensible
   cross-workspace balance of cost and quality.
 - Keep cost differences per workspace through each workspace's own
   full-compile approval threshold (see above).

package/agent-assets/docs/guides/pause-the-agent.md

@@ -12,7 +12,6 @@ summary: |
   every routine, or use dashboard toggles and quiet hours for finer control.
 section: pause-the-agent
 tags:
-  - guides
   - operations
   - messaging
   - autonomous
@@ -23,7 +22,7 @@ ask_examples:
   - Can I disable everything for a week?
 locale: en-US
 created: 2026-04-25
-updated: 2026-06-10
+updated: 2026-07-01
 keywords:
   - pause agent
   - stop agent
@@ -58,24 +57,25 @@ losing your install.
 
 ## The fastest pause: `!stop`
 
-DM `!stop` to the agent on any paired messaging app. This is the
-recommended way to go silent and the only one you need for most cases:
+DM `!stop` to the agent on any paired messaging app (any chat app you
+have connected). This is the recommended way to go silent, and the only
+step you need for most cases:
 
-- It pauses **every** cron-driven routine — morning, evening, weekly,
+- It pauses **every** scheduled routine — morning, evening, weekly,
   monthly, and the activity scan — not just one of them.
-- Non-command DMs are declined with a paused notice (no LLM cost)
-  until you resume.
-- The paused state is persisted, so a daemon restart does **not**
-  silently resume autonomous work.
-- In-flight runs are not aborted; the pause takes effect from the next
-  scheduled tick.
+- While paused, a plain (non-command) DM gets a short "paused" reply
+  instead of an answer, so it costs nothing to run.
+- The pause is saved to disk, so restarting the daemon does **not**
+  quietly start the agent working again.
+- A run that is already in progress keeps going; the pause applies from
+  the next scheduled run onward.
 
 Resume with `!start` whenever you want the agent active again. See
 [Bang Commands](../features/messaging/bang-commands.md).
 
 ## Finer-grained control from the dashboard
 
-If you want to mute specific behaviour rather than pause everything:
+If you want to quiet one specific behavior rather than pause everything:
 
 1. **Disable the activity scan** — open `/agents/activity-scan` and click
    **Disable**. This leaves the morning, evening, weekly, and monthly
@@ -90,22 +90,22 @@ If you want to mute specific behaviour rather than pause everything:
    take an `HH:MM` string. Routines still run; they just don't notify
    you.
 
-Morning (fires at the day boundary, default 04:00), evening (18:00),
-and weekly (Fri 19:00) reviews each have a per-routine Enable/Disable
-toggle on the `/agents` page — open `/agents/<slug>` (e.g.
-`/agents/weekly-review`) and click Disable (a stop-warning confirmation
-appears for these system agents). To halt all of them at once, use
-`!stop` above instead. Each routine's instructions (its rulebook) are
-edited on the same page's **Rulebook** tab
-(`/agents/<slug>?tab=rulebook`).
+The morning review (fires at the day boundary — the moment "today"
+rolls over, 04:00 by default), evening (18:00), and weekly (Fri 19:00)
+reviews each have their own Enable/Disable toggle on the `/agents`
+page. Open `/agents/<slug>` (e.g. `/agents/weekly-review`) and click
+Disable; a stop-warning confirmation appears for these system agents.
+To halt all of them at once, use `!stop` above instead. To edit a
+routine's instructions (its rulebook), use the same page's **Rulebook**
+tab (`/agents/<slug>?tab=rulebook`).
 
 ## Last resort: stop the daemon
 
-`aitne stop` shuts the daemon down entirely (graceful SIGTERM, then
-SIGKILL after 10 seconds). Nothing runs — no routines, no messaging, no
-dashboard. Use this only when you want the agent fully offline; for a
-temporary pause that survives across days, prefer `!stop`. Restart with
-`aitne start`.
+`aitne stop` shuts the daemon down entirely: it asks the process to
+quit (SIGTERM), then forces it (SIGKILL) after 10 seconds. Nothing
+runs — no routines, no messaging, no dashboard. Use this only when you
+want the agent fully offline. For a temporary pause that survives across
+days, prefer `!stop`. Restart with `aitne start`.
 
 ## Verification