@aitne-sh/aitne 0.1.5 → 0.1.7

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

@@ -0,0 +1,145 @@
+---
+schema_version: 1
+slug: features/wiki/overview
+title: Wiki Overview
+id: wiki-overview
+aliases:
+  - wiki
+  - personal wiki
+  - knowledge vault
+  - wiki builder
+category: features
+summary: |
+  Aitne's opt-in personal wiki — a separate, LLM-maintained knowledge
+  vault used for durable research, references, and personal knowledge
+  that should compound over time. Distinct from Aitne's reactive memory.
+section: wiki
+tags:
+  - wiki
+  - knowledge
+status: stable
+ask_examples:
+  - What is the wiki?
+  - How is the wiki different from memory?
+  - Where does the wiki live on disk?
+  - Can I point the wiki at my Obsidian vault?
+locale: en-US
+created: 2026-05-12
+updated: 2026-05-12
+related:
+  - features/wiki/commands
+  - features/memory-files
+  - guides/build-your-wiki
+  - guides/use-an-existing-obsidian-vault
+  - guides/budget-and-cost-for-wiki
+  - troubleshooting/wiki-write-failed
+  - troubleshooting/wiki-ingest-full-blocked
+ui_anchors:
+  - /wiki
+  - /wiki/timeline
+  - /settings/wiki
+---
+
+# Wiki Overview
+
+## In One Sentence
+
+The wiki is an opt-in personal knowledge vault — separate from
+Aitne's reactive memory — that the agent grows from URLs you send it
+and questions you ask it.
+
+## What It Does
+
+- **URL ingest**: send `!ingest <url>` from a paired DM channel; the wiki
+  agent fetches the source, summarises it, and stores a raw note.
+- **Compile**: `!compile` (incremental) and `!compile full` (full
+  rebuild) turn raw notes into synthesised wiki articles with
+  cross-links and an `_index.md` catalogue.
+- **Ask**: `!ask <question>` searches the wiki and writes a cited
+  answer under `30_outputs/`.
+
+The wiki uses its own process keys (`wiki.ingest_url`, `wiki.compile`,
+`wiki.ask`) with independent backend / model / budget settings, so it
+never competes for budget with daily reactive memory.
+
+## Internal vs External
+
+Aitne offers two modes:
+
+- **Internal** (recommended starting point) — the daemon owns the
+  vault at `$PA_DATA_DIR/wiki`. No sandbox issues, daemon-managed
+  snapshots, isolated from iCloud sync conflicts.
+- **External** — you point the wiki at an existing Obsidian vault on
+  disk. The daemon writes directly when the filesystem allows, and
+  falls back to the official Obsidian CLI when the vault sits in a
+  sandboxed location (iCloud) and the Obsidian app is running.
+
+Path-collision rules: the external root must not overlap `dataDir`,
+your primary vault, or the external Obsidian vault path. Two wiki
+workspaces may not nest.
+
+## Layers
+
+- `00_inbox/` — human-only capture (the agent has read access but
+  cannot write here).
+- `10_raw/` — source-faithful raw notes (append-only).
+- `20_wiki/` — synthesised wiki articles + `_index.md` catalogue.
+- `30_outputs/` — answer / report artifacts written by `!ask`.
+- `90_meta/` — taxonomy, schemas, lint reports, and the
+  `import-<date>.md` migration record.
+- `log.md` — append-only operational log.
+
+The DM agent can read wiki search and index routes but only wiki
+process keys can write wiki layers.
+
+## Cost Safety
+
+`!compile full` rebuilds the entire wiki from raw notes and is the
+most expensive command. The dashboard banner shows the bracketed
+estimate ($0.5×–$2× the assumed input-token spend) before you run
+it. If the pessimistic estimate exceeds the per-workspace threshold
+(default $2.00), the command escalates to the dashboard `/approvals`
+queue and requires your explicit confirmation before the compile
+starts.
+
+On a git-tracked external vault, Aitne also runs
+`git add -A && git commit -m "aitne wiki: pre-compile snapshot <ts>"`
+on a clean working tree before the compile so you can roll back if
+the run produces a surprise. A dirty tree refuses the operation —
+commit or stash first.
+
+## Where it lives in the dashboard
+
+The wiki has two distinct surfaces in the dashboard. The split mirrors
+how Aitne organises the rest of the app — configuration lives under
+**Setup → Settings**, day-to-day content browsing lives under **My
+Life** next to Knowledge / Reading / Git / Trip / Finance / Health.
+
+| Page | Section | Use it for |
+|---|---|---|
+| `/wiki` | My Life | Workspace summary, the compiled `_index.md` catalogue, and the latest activity log. The page you open most often. |
+| `/wiki/timeline` | My Life | Full chronological activity log plus the latest `!lint` health report. Linked from `/wiki` and from settings. |
+| `/settings/wiki` | Setup → Settings | Enable / archive a workspace, switch between internal and external mode, pick an external vault path, language, dispatch mode, write strategy, git auto-commit, approval threshold, per-command model selectors. |
+
+The **My Life → Wiki** entry is always visible in the sidebar, even
+before you enable a workspace, so the feature is easy to find. The
+`/wiki` page itself renders an **Enable Wiki** call-to-action when no
+workspace is active — clicking it jumps you to `/settings/wiki` where
+the same internal / external choice surfaces.
+
+The wiki is off by default on a fresh install; nothing is written to
+disk until you opt in.
+
+### Settings page states
+
+`/settings/wiki` is two-state:
+
+- **Disabled** (no active workspace) — a single "Enable Internal
+  Workspace" CTA plus an external-path picker. The picker opens your
+  OS-native folder dialog (Finder on macOS, File Explorer on Windows,
+  the system folder dialog on Linux) and shows an inline validation
+  banner once you pick a path — see [guides/use-an-existing-obsidian-vault](../../guides/use-an-existing-obsidian-vault.md).
+- **Enabled** — full configuration: language, dispatch mode, write
+  strategy, git auto-commit toggle, approval threshold, per-command
+  model selectors, plus archive / delete. A "Browse wiki" link at the
+  top jumps you back to `/wiki`.

package/agent-assets/docs/getting-started/03-what-can-this-do.md

@@ -28,6 +28,8 @@ related:
   - concepts/memory-model
   - features/messaging/voice-attachments
   - features/operations/skill-self-optimization
+  - features/wiki/overview
+  - features/wiki/commands
 ---
 
 # What This App Can Do
@@ -85,6 +87,22 @@ them — the agent reads what's there next time it runs.
 - [agent/journal.md](../features/memory-files/agent-journal.md) —
   what the agent did and what it noticed.
 
+## Build a personal wiki from what you DM
+
+A workspace-scoped builder turns URLs, pastes, and notes you send into a
+linked Markdown wiki. The raw capture, the synthesised article, and the
+cited answer all stay on disk and the agent only writes via the daemon
+API so the layout invariants hold.
+
+- [Wiki Overview](../features/wiki/overview.md) — the workspace concept,
+  the `00_inbox` / `10_raw` / `20_wiki` / `30_outputs` layers, and the
+  approval gate on full rebuilds.
+- [Wiki Commands](../features/wiki/commands.md) — `!ingest` (capture
+  URLs), `!compile` (synthesise), `!ask` (cited Q&A), `!lint` /
+  `!trace` / `!connect` (audit, history, bridges), `!wiki` (status).
+- [Build Your Wiki](../guides/build-your-wiki.md) — the first-day
+  walkthrough from empty workspace to first answered question.
+
 ## Help with the small lifestyle stuff
 
 Reading lists, receipts, travel bookings, travel-time estimates — the

package/agent-assets/docs/glossary.md

@@ -114,3 +114,37 @@ The current agent day's main memory file under
 `~/.personal-agent/context/today.md`. Rebuilt once per day by the
 morning routine and edited by every DM, observation, and routine that
 needs to record state for the day.
+
+## Wiki Workspace
+
+A single named root the wiki feature writes into. Either **internal**
+(`~/.personal-agent/wiki/`) or **external** (a path you point at, often
+an existing Obsidian vault). Every wiki bang command targets a
+workspace; omitting the `@<workspace>` token addresses the default.
+See [Wiki Overview](features/wiki/overview.md) and
+[Multiple Wikis](guides/multiple-wikis-for-multiple-domains.md).
+
+## Wiki Layers
+
+The four directories every workspace contains:
+
+- `00_inbox/` — agent-readable but agent-unwritable; for hand-drops
+  destined for graduation.
+- `10_raw/` — captured sources from `!ingest <url>` and other intake.
+- `20_wiki/` — synthesised articles produced by `!compile`, plus
+  `_index.md`.
+- `30_outputs/` — derived artefacts (`!ask` answers, `!lint` reports,
+  `!trace` and `!connect` outputs).
+
+Dataflow is single-direction: `00_inbox` → `10_raw` → `20_wiki` →
+`30_outputs`. Skills enforce the invariant; the daemon's Wiki API is
+the only legal write path.
+
+## Compile Preview
+
+The dry-run touch list `!compile --preview` (alias `--dry-run`) produces
+before any agent session runs. Lists pages that would be **added**,
+**modified**, or **unchanged**, plus the bracketed cost estimate and
+ETA. The compile is an LLM and may diverge inside the loop; the preview
+is an upper bound on the touch set. Computed purely in JS — no tokens
+spent.

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

@@ -0,0 +1,123 @@
+---
+schema_version: 1
+slug: guides/budget-and-cost-for-wiki
+title: Wiki Budgets and Cost
+id: budget-and-cost-for-wiki
+aliases:
+  - wiki cost
+  - wiki budget
+  - "!compile full approval"
+  - wiki approval threshold
+category: guides
+summary: |
+  How the wiki estimates `!compile full` cost, when the approval gate
+  fires, how the git pre-compile snapshot interacts with it, and how
+  to tune the threshold.
+section: budget-and-cost-for-wiki
+tags:
+  - guide
+  - wiki
+  - cost
+status: stable
+ask_examples:
+  - How much does !compile full cost?
+  - Why did !compile full need approval?
+  - How do I raise the wiki approval threshold?
+  - What does the pre-compile snapshot do?
+locale: en-US
+created: 2026-05-12
+updated: 2026-05-12
+related:
+  - features/wiki/overview
+  - features/wiki/commands
+  - concepts/costs-and-quotas
+  - troubleshooting/wiki-ingest-full-blocked
+ui_anchors:
+  - /settings/wiki
+  - /approvals
+---
+
+# Wiki Budgets and Cost
+
+The wiki ships with three cost knobs you can tune in
+**Settings → Wiki**:
+
+1. **Per-command model selector** for each of the three wiki
+   processes (`wiki.ingest_url`, `wiki.compile`, `wiki.ask`).
+   Defaults to your main backend at the medium tier; downgrade
+   `wiki.ingest_url` to a lite tier if you ingest a lot of URLs.
+2. **Per-process budget cap** (`max_budget_usd` on each row). The
+   dispatcher's per-session budget envelope is the enforcer.
+3. **Per-workspace `!compile full` approval threshold** (default
+   $2.00). The dashboard cost estimator brackets the expected spend
+   at 0.5× / 1× / 2× the assumed input-token count; if the
+   pessimistic estimate breaches the threshold, the bang handler
+   escalates to the approval queue instead of running autonomously.
+
+## 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 — and computes:
+
+```
+expected_usd = raw_count × avg_input_tokens_per_raw × $0.003 / 1k tokens
+optimistic   = 0.5 × expected
+pessimistic  = 2.0 × expected
+```
+
+Defaults: `avg_input_tokens_per_raw = 1500`, the unit cost matches
+Sonnet 4.6's $3 / Mtoken input price. The bracket lets you see a
+worst-case before approving.
+
+## 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'` and DMs the estimate. The
+  dashboard `/approvals` view (also reachable from Notifications)
+  is where you click **Approve** — that flips the row to
+  `approved_task` and the scheduler picks it up.
+
+If you change your mind, hit **Deny** on the approval card — the row
+flips to `skipped` and no agent session is spawned.
+
+## 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 -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.
+
+If your vault is not a git repo, the approval-gate DM appends
+"no git backup taken" so you can decide whether to add one before
+approving.
+
+## Tuning the Threshold
+
+The default $2.00 threshold suits a small-to-medium personal wiki
+(around 100–500 raw notes). If your wiki grows much larger, raise
+the threshold so routine recompiles don't queue an approval every
+time — or downgrade `wiki.compile` to the lite tier so the actual
+spend stays low.
+
+## When to Use `!compile` vs `!compile full`
+
+- **`!compile` (default)**: incremental — touches only new and
+  modified raw notes. Cheap, fast, runs autonomously. Use this in
+  normal operation.
+- **`!compile full`**: rebuilds everything. Use when you've changed
+  the wiki schema, ingested a large batch of historical raw notes,
+  or want to force a from-scratch synthesis after editing
+  `90_meta/taxonomy.md`.

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

@@ -0,0 +1,99 @@
+---
+schema_version: 1
+slug: guides/build-your-wiki
+title: Build Your Wiki
+id: build-your-wiki
+category: guides
+summary: |
+  Enable the internal wiki, send your first URL, compile the raw
+  notes, and ask a question against the vault.
+section: build-your-wiki
+tags:
+  - guide
+  - wiki
+status: stable
+ask_examples:
+  - How do I start using the wiki?
+  - How do I add my first source to the wiki?
+locale: en-US
+created: 2026-05-12
+updated: 2026-05-12
+related:
+  - features/wiki/overview
+  - features/wiki/commands
+  - guides/use-an-existing-obsidian-vault
+  - guides/budget-and-cost-for-wiki
+---
+
+# Build Your Wiki
+
+## Goal
+
+Stand up the internal wiki, capture a URL, compile it into a wiki
+article, and run a question against the result.
+
+## Prerequisites
+
+- A paired messaging channel (Telegram, Slack, Discord, WhatsApp, or
+  dashboard chat).
+- The daemon is running and the dashboard is reachable.
+
+## Where you'll work in the dashboard
+
+The wiki has two pages, mirroring how the rest of the dashboard is
+split: configuration lives under **Setup → Settings**, content
+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.
+- **Setup → Settings → Wiki** (`/settings/wiki`) — workspace creation,
+  internal/external mode, per-command model selectors, budgets,
+  archive / delete.
+
+The **My Life → Wiki** sidebar entry is always visible, even before
+you enable a workspace, so you do not need to remember the URL.
+
+## Steps
+
+1. Click **My Life → Wiki** in the sidebar (`/wiki`). The page shows
+   a "Wiki not enabled" card with an **Enable Wiki** button —
+   clicking it jumps you to `/settings/wiki`.
+2. On the settings page, click **Enable Internal Workspace**. The
+   daemon creates `$PA_DATA_DIR/wiki/` and seeds `90_meta/taxonomy.md`
+   plus the schema templates. (To point at an existing Obsidian
+   vault instead, follow
+   [Use An Existing Obsidian Vault](use-an-existing-obsidian-vault.md).)
+3. The sidebar's **My Life → Wiki** entry now lands on a workspace
+   summary instead of the disabled CTA. Open it to confirm the root
+   path, counts, and quick links to **Timeline & health** and
+   **Configuration**.
+4. From a paired DM, send `!ingest https://example.com/article`. You
+   will get an acknowledgement reply naming the workspace and the
+   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
+   `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
+   citations back to the source articles. Refresh **My Life → Wiki**
+   to see the updated activity log.
+
+Use `!wiki` any time to see counts and workspace status. `!wiki help`
+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.
+- **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
+  the per-command model selector on `/settings/wiki`. See
+  [Wiki Budgets and Cost](budget-and-cost-for-wiki.md) for the
+  approval gate.

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

@@ -0,0 +1,169 @@
+---
+schema_version: 1
+slug: guides/explore-with-trace-and-connect
+title: Explore Your Wiki with !trace and !connect
+id: explore-with-trace-and-connect
+aliases:
+  - "!trace"
+  - "!connect"
+  - wiki trace
+  - wiki connect
+  - bridging domains
+category: guides
+summary: |
+  How to use `!trace <topic>` to reconstruct the evolution of an
+  idea across your raw / wiki / outputs layers, and `!connect <a>
+  <b>` to find bridges between two domains.
+section: explore-with-trace-and-connect
+tags:
+  - guide
+  - wiki
+  - exploration
+status: stable
+ask_examples:
+  - How do I trace an idea across the wiki?
+  - What does !connect do?
+  - How do I find connections between two topics?
+  - Where does the !trace output land?
+  - Can I use multi-word topics with !connect?
+locale: en-US
+created: 2026-05-12
+updated: 2026-05-12
+related:
+  - features/wiki/overview
+  - features/wiki/commands
+  - guides/maintain-wiki-health
+ui_anchors:
+  - /wiki/timeline
+  - /settings/wiki
+---
+
+# Explore Your Wiki with `!trace` and `!connect`
+
+`!trace` and `!connect` are the two Phase 3 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 <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.
+
+```
+!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.
+
+### Output
+
+The output lands at:
+
+```
+30_outputs/<YYYY-MM-DD>-trace-<slug>.md
+```
+
+Each report has:
+
+- A one-paragraph synthesis of the arc.
+- One section per phase with the dominant question, new evidence,
+  and what changed compared to the previous phase.
+- A `## Gaps` list of questions your wiki cannot yet answer — a
+  pointer to where the next `!ingest` run should focus.
+
+If your wiki has fewer than two sources on the topic, the report
+says so directly. No padding, no speculation.
+
+### When to Reach for `!trace`
+
+- Before writing about a topic externally — get the lineage right.
+- After a long ingest run on one area — see whether the phases
+  changed or just thickened.
+- When a wiki note feels stale — `!trace` will surface the dated
+  evidence and the gap list will tell you what to refresh.
+
+## `!connect <a> <b>` — Bridge Two Domains
+
+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`.
+2. **Common references** — the same URL, author, or wiki note
+   linked from both sides.
+3. **Structural analogies** — recurring patterns of reasoning or
+   tradeoffs, even when the surface vocabulary differs.
+4. **Bridging concept candidates** — proposals for a new wiki
+   note that would naturally sit between the two areas.
+
+### Argument Forms
+
+`!connect` requires exactly two topics. Whitespace separates them
+by default; a comma lets you use multi-word topics:
+
+```
+!connect quantum gravity
+!connect quantum computing, classical computing
+!connect category theory, distributed systems
+```
+
+The handler rejects a single topic, three-or-more topics, a
+trailing comma, or empty input with a usage message — pick a
+topic for each side.
+
+### Output
+
+The output lands at:
+
+```
+30_outputs/<YYYY-MM-DD>-connect-<slug-a>--<slug-b>.md
+```
+
+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.
+
+### 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.
+
+### `!connect` Does Not Create Wiki Notes
+
+The "bridging concept candidates" section is a **proposal** for
+`wiki.compile` (or you, manually) to pick up later. `!connect`
+never writes to `20_wiki/` — the safety boundary is the same as
+`!ask` and `!trace`: read everywhere, write only to
+`30_outputs/`.
+
+## Finding Past Reports
+
+Every report is a regular wiki file under `30_outputs/`. You can:
+
+- Open **My Life → Wiki → Timeline & health** (`/wiki/timeline`)
+  — the timeline shows every wiki write with a process-key
+  filter, so filtering by `wiki.trace` or `wiki.connect` lists
+  past reports in reverse-chronological order.
+- Use `!ask` to fold a past trace or connect into a new answer.
+- Browse the files on disk (the wiki vault root path is shown on
+  **My Life → Wiki** and on `/settings/wiki`).
+
+## Cost Envelope
+
+Both commands run at Sonnet medium tier with a default $1.00
+spend cap per run, identical to `!ask`. The 7-day cost rollup on
+**Settings → Wiki** breaks the spend out per command so you can
+see where the budget went.