@aitne-sh/aitne 0.1.8 → 0.1.9

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

@@ -10,13 +10,15 @@ aliases:
 category: guides
 summary: |
   Run more than one wiki workspace inside the same daemon. Address
-  them from DMs with `@<workspace>`, manage them independently from
-  /settings/wiki, and keep their file trees isolated on disk.
-section: multiple-wikis-for-multiple-domains
+  them from DMs with `@<workspace>`, create and configure additional
+  workspaces through the daemon API, and keep their file trees isolated
+  on disk.
+section: guides
 tags:
-  - guide
+  - guides
   - wiki
-  - multi-workspace
+  - workspaces
+  - knowledge
 status: stable
 ask_examples:
   - How do I run multiple wikis?
@@ -24,26 +26,49 @@ ask_examples:
   - What does `@research` do before a wiki command?
 locale: en-US
 created: 2026-05-12
-updated: 2026-05-12
+updated: 2026-05-28
 keywords:
   - multi-workspace
   - wiki workspace
   - default workspace
-  - @workspace token
+  - "@workspace token"
 related:
   - features/wiki/overview
+  - features/wiki/workspaces
   - features/wiki/commands
   - guides/build-your-wiki
   - guides/use-an-existing-obsidian-vault
+ui_anchors:
+  - /settings/wiki
+api_endpoints:
+  - /api/wiki/workspaces
+  - /api/wiki/workspaces/probe
+  - /api/wiki/workspaces/:workspace
+  - /api/wiki/workspaces/:workspace/archive
+process_keys:
+  - wiki.ingest_url
+  - wiki.compile
+  - wiki.ask
+  - wiki.lint
+  - wiki.trace
+  - wiki.connect
 ---
 
 # Multiple Wikis for Multiple Domains
 
-Phase 5 lifted Aitne's single-workspace ceiling. If you keep distinct
-knowledge bases — say, a research vault, a parenting journal, and an
-ops runbook — you can run each as its own wiki workspace inside the
-same daemon. The DM agent routes commands per workspace; the file
-trees never overlap.
+Aitne can run more than one wiki workspace inside the same daemon. If
+you keep distinct knowledge bases — say, a research vault, a parenting
+journal, and an ops runbook — each can be its own wiki workspace. The
+DM agent routes commands per workspace; the file trees never overlap.
+
+> **Where this lives today.** The multi-workspace machinery is real at
+> the daemon, API, and DM layers: you address any workspace from a DM
+> with an `@<workspace>` token, and each row carries its own per-
+> workspace settings. The dashboard's `/settings/wiki` page, however,
+> currently manages only the **one active workspace** — it has no
+> workspace picker and no "Add Workspace" button. Additional
+> workspaces are created and archived through the daemon API
+> (`POST /api/wiki/workspaces`), described below.
 
 ## Why you might want this
 
@@ -52,9 +77,9 @@ trees never overlap.
   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 a private
-  workspace in `$PA_DATA_DIR`. Per-workspace settings handle the
-  asymmetry.
+  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 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
@@ -62,21 +87,35 @@ trees never overlap.
 
 ## Creating a second workspace
 
-1. Open `/settings/wiki`. You will see your current (default)
-   workspace.
-2. Scroll to **Add Workspace** (Phase 5 surface). Choose either:
-   - **Internal**, which lives under `$PA_DATA_DIR/wiki-<name>/`. Best
-     for private notes you never sync to another device.
-   - **External**, which points at an existing folder on disk (your
-     Obsidian vault, an iCloud-synced directory, a git working copy).
-3. Pick a unique `name` (lowercase letters, digits, `.`, `_`, `-`). The
-   name is what you address from DMs.
-4. The wizard probes the candidate path against §2.1.1 collision rules
-   — it refuses to nest a wiki inside your primary vault, the data
-   directory, or another active wiki. Iterate until the probe is green.
-5. Click **Create**. The vault skeleton (`00_inbox/`, `10_raw/`,
-   `20_wiki/`, `30_outputs/`, `90_meta/`) is seeded and the workspace
-   joins the active set.
+The first workspace — the one named `default` — can be **internal**
+(managed by the daemon under its own data directory at
+`<contextDir>/knowledge/wiki/`) or **external** (an existing folder you
+own). You pick that during initial setup on `/settings/wiki`.
+
+Every *additional* workspace must be **external** — it points at a
+folder on disk (an Obsidian vault, an iCloud-synced directory, a git
+working copy). Only `default` is internal. Create a second workspace by
+POSTing to the daemon API:
+
+    curl -X POST http://localhost:8321/api/wiki/workspaces \
+      -H 'content-type: application/json' \
+      -d '{"kind":"external","name":"research","rootPath":"/Users/you/vaults/research"}'
+
+- **`name`** — unique, 1–64 chars matching `[A-Za-z0-9][A-Za-z0-9._-]*`
+  (letters, digits, `.`, `_`, `-`). This is what you address from DMs.
+- **`rootPath`** — required for external workspaces. The daemon
+  validates it before creating the row: it refuses to nest a wiki
+  inside your primary vault, the data directory, or another active wiki
+  (see [Path collision rules](#path-collision-rules-recap)). A failed
+  validation returns a `4xx` with the collision reason — fix the path
+  and retry.
+- **`language`** (optional) — defaults to the daemon's wiki language.
+
+Use `POST /api/wiki/workspaces/probe` with `{ "rootPath": "…" }` first
+if you want the read-only collision diagnostics before committing the
+row. On success the vault skeleton (`00_inbox/`, `10_raw/`, `20_wiki/`,
+`30_outputs/`, `90_meta/`) is seeded into the folder and the workspace
+joins the active set.
 
 ## Addressing a workspace from DMs
 
@@ -122,17 +161,23 @@ you which workspace `!ask` (with no `@`) will route to.
 
 ## Configuring each workspace independently
 
-`/settings/wiki` shows a workspace picker at the top once you have
-more than one. Each workspace's panel carries its own:
+Each workspace row carries its own settings:
 
 - language (`en`, `ja`, …)
 - dispatch mode (parallel / serial) and concurrency cap
 - write strategy (`fs` / `cli` / `auto`) — external mode only
 - full-compile approval threshold (USD)
 - git pre-compile auto-commit toggle (external git vaults only)
-- bridge feature gate + measurement mode + min confidence (Phase 5)
+- bridge feature gate + measurement mode + min confidence
 - DM-agent bridge write toggle
 
+The dashboard's `/settings/wiki` page edits these for the single active
+workspace it surfaces. For any other workspace, PATCH the row directly:
+
+    curl -X PATCH http://localhost:8321/api/wiki/workspaces/research \
+      -H 'content-type: application/json' \
+      -d '{"dispatchMode":"serial","fullCompileApprovalThresholdUsd":2.0}'
+
 `POST /api/backends/apply-defaults` re-seeds the per-process backend /
 model / budget rows but leaves the per-workspace columns alone — those
 are operator preferences, not install defaults.
@@ -146,34 +191,38 @@ bound to each key applies across all workspaces — they share the
 binding because the daemon resolves the row by process key, not by
 workspace.
 
-If you need a research vault on Opus 4.7 and a parenting journal on
-Haiku 4.5 at the same time, the supported path today is:
+There is no per-workspace model binding today. If you want a research
+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 medium-tier Sonnet (a sensible cross-workspace
-  default).
-- Use the workspace-aware `!ask @research` for the research vault and
-  rely on per-workspace token budgets via the cost ceiling.
+- Bind `wiki.ask` to its medium-tier default (Sonnet 4.6), 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).
 
-A future enhancement is per-workspace model bindings; the present
-shape was chosen to keep `/settings/models` legible without a
-workspace dimension.
+Per-workspace model bindings are a possible future enhancement; the
+present shape keeps `/settings/models` legible without a workspace
+dimension.
 
 ## Archiving a workspace
 
-The dashboard's **Archive** button on a workspace card flips its
-`active` column to `0`. Archived workspaces:
+`POST /api/wiki/workspaces/<name>/archive` flips a workspace's `active`
+column to `0`. (The dashboard exposes a Stop/Remove control for the one
+active workspace it surfaces; other workspaces are archived via the API
+call.) Archived workspaces:
 
 - disappear from `!wiki` listings,
-- reject all daemon API requests with `wiki_not_enabled`,
+- reject daemon API requests with `wiki_not_enabled`,
 - drop out of `/search` and `/index`,
 - keep their files on disk (you can re-activate later with no data
   loss),
 - have their `fts_wiki` rows cleared eagerly so a same-id re-enable
   re-indexes from disk.
 
-`DELETE /wiki/workspaces/:name` removes the row entirely (filesystem
-contents are preserved — the daemon never deletes vault content). Use
-this when you are sure you will not re-enable.
+`DELETE /api/wiki/workspaces/<name>` removes the row entirely
+(filesystem contents are preserved — the daemon never deletes vault
+content). Use this when you are sure you will not re-enable.
 
 ## Path collision rules (recap)
 
@@ -181,21 +230,23 @@ Two active wiki workspaces cannot point at overlapping paths. Neither
 can overlap:
 
 - `primaryVaultPath` — your reactive-memory vault (`knowledge/`,
-  `today.md`, etc.).
+  `state/today.md`, etc.).
 - `externalObsidianVaultPath` — your owner-facing Obsidian vault.
 - `$PA_DATA_DIR` — the daemon's data home.
 
-The wizard's pre-create probe enforces this; PATCH cannot widen past
-it. If you want to migrate a workspace to a new disk location, archive
-the old row, create a fresh row pointing at the new path, then
-manually copy the vault contents.
+The pre-create validation (`POST /api/wiki/workspaces` and the
+`/probe` endpoint) enforces this, and PATCH cannot widen past it. If
+you want to migrate a workspace to a new disk location, archive the old
+row, create a fresh row pointing at the new path, then manually copy
+the vault contents.
 
 ## See also
 
-- `docs/design/23-wiki-builder.md` — Phase summary table for the
-  overall wiki feature.
-- `docs/design/appendices/wiki-external-vault.md` — write strategy,
-  iCloud handling, snapshot exclusion.
-- `docs/design/appendices/wiki-bridge-mechanism.md` — Phase 5 bridge
-  capture from DMs into a workspace's raw layer.
-- `docs/user/features/wiki/commands.md` — full bang command reference.
+- **features/wiki/overview** — what the wiki feature is and the four
+  vault layers.
+- **features/wiki/workspaces** — workspace lifecycle, internal vs
+  external, and per-workspace settings in depth.
+- **features/wiki/commands** — full bang-command reference, including
+  the `@<workspace>` token.
+- **guides/use-an-existing-obsidian-vault** — pointing a workspace at a
+  folder you already own.

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

@@ -8,31 +8,41 @@ aliases:
   - disable routines
 category: guides
 summary: |
-  Stop the agent from acting (without uninstalling it) by disabling
-  routines and entering an extended quiet hours window.
+  Stop the agent from acting without uninstalling it — DM !stop to pause
+  every routine, or use dashboard toggles and quiet hours for finer control.
 section: pause-the-agent
 tags:
-  - guide
+  - guides
   - operations
   - messaging
+  - autonomous
+  - scheduler
 status: stable
 ask_examples:
   - How do I pause the agent without uninstalling?
   - Can I disable everything for a week?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - pause agent
   - stop agent
-  - !stop
-  - !start
+  - "!stop"
+  - "!start"
   - disable autonomous
   - go silent
 related:
   - features/operations/quiet-hours
   - features/messaging/bang-commands
   - concepts/routines
+ui_anchors:
+  - /settings/schedule
+  - /settings/routines
+config_keys:
+  - hourlyCheckEnabled
+  - monthlyReviewEnabled
+  - quietHoursStart
+  - quietHoursEnd
 ---
 
 # Pause the Agent
@@ -46,32 +56,63 @@ losing your install.
 
 - Daemon running.
 
-## Steps
-
-1. **For a short pause from your phone**: DM `!stop` to the agent on
-   any paired messaging app. Autonomous work pauses immediately; the
-   daemon keeps running so you can `!start` to resume. See
-   [Bang Commands](../features/messaging/bang-commands.md).
-2. **Disable the hourly check** from `/settings/routines` — toggle
-   `hourlyCheckEnabled` off. Morning, evening, and weekly reviews
-   fire at fixed times in code, so they cannot be toggled from the
-   dashboard; the most reliable mute is `aitne stop`.
-3. **Set an extended quiet hours window** on `/settings/schedule` —
-   e.g. `quietHoursStart: "00:00"`, `quietHoursEnd: "23:59"`. Both
-   fields take an `HH:MM` string. This silences notifications while
-   keeping routines running.
-4. **Optionally** stop the daemon entirely with `aitne stop`. This is
-   the only way to fully suppress the fixed-schedule routines.
+## 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:
+
+- It pauses **every** cron-driven routine — morning, evening, weekly,
+  monthly, and the hourly check — 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.
+
+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, use
+`/settings/schedule`:
+
+1. **Disable the hourly check** — toggle `hourlyCheckEnabled` off. This
+   leaves the morning, evening, weekly, and monthly routines running.
+2. **Disable the monthly review** — toggle `monthlyReviewEnabled` off
+   (it ships off by default).
+3. **Silence notifications without pausing work** — set an extended
+   quiet hours window: e.g. `quietHoursStart: "00:00"`,
+   `quietHoursEnd: "23:59"`. Both fields 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 18:00) reviews have no per-routine enable toggle in the
+dashboard — to stop them, use `!stop` above. You can still edit each
+routine's instructions on `/settings/routines`, but that page does not
+turn them on or off.
+
+## 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`.
 
 ## Verification
 
 - The Activity feed shows no new routine fires.
 - No notifications arrive.
+- A DM to a paused agent is declined with a "paused" notice.
 
 ## If It Fails
 
-- A routine that still fires: confirm the toggle saved on
-  `/settings/routines`. The dashboard's "Save" button must be clicked.
+- A routine still fires after `!stop`: confirm the pause registered by
+  checking `!help` or the dashboard banner; re-send `!stop`.
+- A toggle on `/settings/schedule` did not take effect: confirm it
+  saved — the dashboard's "Save" button must be clicked.
 
 ## Related
 

package/agent-assets/docs/guides/reinstall-cleanly.md

@@ -11,21 +11,26 @@ aliases:
   - fresh install
 category: guides
 summary: |
-  Aitne's policy is "clean reinstall, no data migration".
-  Stop the daemon, delete the data directory, re-launch — the setup
-  wizard re-seeds.
+  Last-resort escape hatch — stop the daemon, delete the database, re-launch.
+  Almost never needed; Aitne upgrades via forward-only schema migrations
+  applied automatically at boot. Use this only when migrations fail or the
+  DB is genuinely corrupt.
 section: reinstall-cleanly
 tags:
   - guide
   - operations
   - reinstall
+  - migration
+  - backup
 status: stable
 ask_examples:
   - How do I reinstall Aitne?
+  - My DB seems corrupt — how do I start over?
   - What does a clean reinstall delete?
+  - Do I need to wipe the DB to upgrade Aitne?
 locale: en-US
 created: 2026-04-25
-updated: 2026-04-25
+updated: 2026-05-28
 keywords:
   - reinstall
   - factory reset
@@ -33,35 +38,100 @@ keywords:
   - fresh install
   - PA_DATA_DIR
   - aitne uninstall
+  - schema migration
+  - corrupt database
+  - clean-context
 related:
   - guides/backup-and-restore
+  - guides/migrate-machines
+  - guides/pause-the-agent
+  - glossary
 ---
 
 # Reinstall Cleanly
 
-## Goal
+## You Almost Never Need This
 
-Reset Aitne's state without losing your context files.
+Aitne upgrades through **forward-only schema migrations** applied at
+daemon boot — your DB and context files survive every
+`npm install -g @aitne-sh/aitne@latest` upgrade. If you're reading this
+because you just upgraded, **don't run the steps below**; restart the
+daemon and let the migration runner do its job.
 
-## Prerequisites
+This guide is the last-resort escape hatch for:
 
-- A backup of `~/.personal-agent/context/` if you want it back.
+- The DB is genuinely corrupt and `aitne start` fails with a SQLite
+  error you can't recover.
+- You want to start over with a fresh setup wizard pass for an
+  unrelated reason (handing the install to someone else, debugging a
+  reproducible setup bug).
 
-## Steps
+For everything else, prefer:
 
-1. `aitne stop`.
-2. `cp -R ~/.personal-agent/context backup/` (optional).
-3. `rm ~/.personal-agent/data/personal_agent.db*` (the SQLite file
-   lives inside `data/`, not at the top of the data dir; the `*`
-   also clears the `-shm`/`-wal` companions left behind by WAL mode).
-4. `aitne start`.
-5. Walk the setup wizard again.
+- **Moving to a new machine** → [Migrate Machines](migrate-machines.md).
+- **Recovering from accidental edits** →
+  [Backup and Restore](backup-and-restore.md).
+- **Just pausing the agent** → [Pause the Agent](pause-the-agent.md).
 
-## Verification
+## Pick the Right Reset
+
+This guide wipes **only the SQLite database** (sessions, actions,
+observations) and keeps your context Markdown. Three other resets exist
+with different scopes — make sure you're running the one you mean:
+
+| You want to… | Run | Wipes |
+|---|---|---|
+| Reset the DB, keep memory | this guide (`rm …/personal_agent.db*`) | SQLite only |
+| Reset memory, keep the DB | `aitne restart --clean-context` | `context/` + `md_file_snapshots` (tarball backup first; type `CLEAN` to confirm) |
+| Remove Aitne entirely | `aitne uninstall --wipe-data` | the whole `~/.personal-agent` data dir |
+| Keep all data, just remove the binary | `aitne uninstall --keep-data` | nothing under the data dir |
+
+## Before You Wipe
+
+1. **Read the daemon log** (`aitne logs -n 200`) and copy the failing
+   line. If it's a migration error, the fix is usually upstream — file
+   an issue rather than wiping the DB and losing your history.
+2. **Back up context.**
+   ```bash
+   cp -R ~/.personal-agent/context backup/
+   ```
+   Context Markdown is what makes the agent know who you are; the DB is
+   recoverable, context is not.
+3. **Back up the DB** if there's any chance you'll want to recover it
+   later:
+   ```bash
+   cp ~/.personal-agent/data/personal_agent.db backup/
+   ```
+
+## The Reset
+
+1. Stop the daemon.
+   ```bash
+   aitne stop
+   ```
+2. Delete the SQLite file and its WAL/SHM companions.
+   ```bash
+   rm ~/.personal-agent/data/personal_agent.db*
+   ```
+   (The `*` glob clears `-shm` / `-wal` left behind by WAL mode. The DB
+   lives inside `data/`, not at the top of the data dir.)
+3. Start the daemon.
+   ```bash
+   aitne start
+   ```
+4. Walk the setup wizard again. Your context files are still there;
+   the wizard re-pairs messaging, re-registers backends, and re-seeds
+   the schema from scratch.
+
+## Verify
 
 - A new `data/personal_agent.db` is created on launch.
-- Setup wizard prompts you for credentials and pairing again.
+- `aitne status` shows the daemon and dashboard both running.
+- The setup wizard prompts you for credentials and pairing again.
 
 ## Related
 
 - [Backup and Restore](backup-and-restore.md)
+- [Migrate Machines](migrate-machines.md)
+- [Schema Migration](../glossary.md#schema-migration) — the boring
+  alternative to this guide that runs automatically on every boot.