@aitne-sh/aitne 0.1.7 → 0.1.9

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

@@ -0,0 +1,254 @@
+---
+schema_version: 1
+slug: features/wiki/workspaces
+title: Wiki Workspaces, Vaults, and Write Strategy
+id: wiki-workspaces
+aliases:
+  - wiki workspace
+  - wiki workspaces
+  - internal wiki
+  - external wiki
+  - multi-workspace wiki
+  - obsidian vault wiki
+  - wiki write strategy
+  - wiki language
+category: features
+summary: |
+  How wiki workspaces are organised — the difference between internal
+  and external mode, how multi-workspace addressing works (`@<name>`),
+  how Aitne picks between direct filesystem writes and the Obsidian CLI
+  on external vaults, and what each `/settings/wiki` toggle does to the
+  underlying `wiki_workspaces` row.
+section: wiki
+tags:
+  - wiki
+  - workspaces
+  - config
+  - core
+status: stable
+ask_examples:
+  - What is a wiki workspace?
+  - What is the difference between internal and external wiki?
+  - How do I add a second wiki workspace?
+  - How do I switch between wikis in a DM?
+  - Why is the wiki writing through the Obsidian CLI instead of directly?
+  - What is the wiki write strategy?
+  - Can the wiki language be different from my primary language?
+  - Can two wikis live in nested folders?
+locale: en-US
+created: 2026-05-21
+updated: 2026-05-28
+keywords:
+  - wiki workspace
+  - workspace
+  - internal mode
+  - external mode
+  - multi-workspace
+  - @workspace
+  - write strategy
+  - fs strategy
+  - cli strategy
+  - auto strategy
+  - obsidian-cli
+  - iCloud sandbox
+  - dispatch mode
+  - parallel
+  - serial
+  - concurrency_cap
+  - language
+  - dm_agent_write_enabled
+  - archive workspace
+related:
+  - features/wiki/overview
+  - features/wiki/commands
+  - features/wiki/dashboard
+  - guides/use-an-existing-obsidian-vault
+  - guides/multiple-wikis-for-multiple-domains
+  - troubleshooting/wiki-write-failed
+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
+config_keys:
+  - primaryVaultPath
+  - externalObsidianVaultPath
+---
+
+# Wiki Workspaces, Vaults, and Write Strategy
+
+A **wiki workspace** is one row in the `wiki_workspaces` table plus
+the directory tree it points at. Aitne ships with no active
+workspace; the first run of the Enable flow creates one named
+`default`. Phase 5 unlocked multi-workspace — you can run as many
+side-by-side wikis as you have distinct knowledge domains.
+
+## Internal vs external mode
+
+| | Internal (recommended) | External |
+|---|---|---|
+| Root path | `$PA_DATA_DIR/context/knowledge/wiki/<name>` (daemon-owned, inside the context vault) | Any path you pick (typically an existing Obsidian vault) |
+| Writes | Atomic local-fs writes | Atomic local-fs writes when permitted; Obsidian-CLI fallback for sandboxed paths |
+| Backup surface | `md_file_snapshots` table | git auto-commit (when the vault is git-tracked) + sibling backup mirror under `90_meta/health/pre-migrate-<date>/` |
+| iCloud-friendly | Yes (lives in `~/.personal-agent`) | Yes via the Obsidian CLI fallback (requires the Obsidian app running) |
+| Best for | First-time users, isolated wiki, no Obsidian dependency | Power users with an existing Obsidian vault they want the agent to extend |
+
+Path-collision rules apply to both modes:
+- The workspace root must not overlap `PA_DATA_DIR`.
+- It must not overlap your primary Obsidian vault (`primaryVaultPath`).
+- It must not overlap the external Obsidian vault (`externalObsidianVaultPath`).
+- Two wiki workspaces may not nest — neither root can be inside the other.
+
+The dashboard probe (`POST /api/wiki/workspaces/probe`) runs these
+checks live before the workspace row is written and surfaces a
+human-readable error if any rule trips.
+
+## The layered layout
+
+Every workspace, internal or external, lays out the same five
+top-level subdirectories plus a workspace-root `log.md`:
+
+| Layer | Owner | Purpose |
+|---|---|---|
+| `00_inbox/` | Human-only | Drop-zone for things you want the agent to read but not write to. The agent has read access. |
+| `10_raw/` | Wiki agent (append-only) | Source-faithful raw notes per URL ingested. |
+| `20_wiki/` | Wiki agent | Synthesised wiki articles plus `_index.md`. |
+| `30_outputs/` | Wiki agent | Answer / report artifacts from `!ask`, `!trace`, `!connect`. |
+| `90_meta/` | Wiki agent | Taxonomy (`taxonomy.md`), schemas, health reports (`90_meta/health/<date>.md`), migration records (`90_meta/health/pre-migrate-<date>/`). |
+| `log.md` | Wiki agent (append-only) | One line per write. Drives the dashboard timeline. |
+
+The DM agent can read wiki search and index routes, but only the
+wiki process keys (`wiki.ingest_url`, `wiki.compile`, `wiki.ask`,
+`wiki.lint`, `wiki.trace`, `wiki.connect`) can write into these
+layers. The chokepoint is `POST /api/wiki/:workspace/files/:path` —
+the route validates the layer the path resolves into and rejects
+writes to `00_inbox/` unconditionally.
+
+## Multi-workspace addressing
+
+Every wiki bang command accepts an optional `@<name>` token
+immediately after the bang to target a specific workspace. 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:
+
+```
+!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 —
+in practice the oldest active workspace (lowest id), which is the one
+named `default` on a fresh install, or the next-oldest active
+workspace if `default` has been archived.
+
+A workspace name after `@` must start with a letter or digit and then
+contain only letters, digits, `.`, `_`, or `-` (max 64 chars). An
+invalid token is rejected with a usage error rather than silently
+falling back to the default.
+
+See [guides/multiple-wikis-for-multiple-domains](../../guides/multiple-wikis-for-multiple-domains.md)
+for a walkthrough.
+
+## Write strategy (`fs` / `cli` / `auto`)
+
+`wiki_workspaces.write_strategy` controls how the daemon persists a
+write. Three values:
+
+- **`fs`** — atomic local-fs writes via `writeFileAtomically()`.
+  Internal-mode workspaces always use `fs`; the toggle is fixed on
+  the row but the column is read-only for internal workspaces.
+- **`cli`** — writes go through the official Obsidian CLI (the
+  Catalyst-only CLI shipped since 2026-02; requires the Obsidian app
+  running). Used for external vaults that live in sandboxed
+  locations (typically iCloud-synced vaults) where direct fs writes
+  fail with `EPERM` / `EACCES` / `EROFS` / `EBUSY`.
+- **`auto`** — the resolver tries `fs` first, falls back to `cli`
+  on those sandbox error codes, and persists the resolved value back
+  to the row so subsequent writes skip the probe.
+
+Internal workspaces are pinned to `fs`. External workspaces start in
+`auto` and self-tune. You can override the resolved value from
+`/settings/wiki` if you need to force one path or the other (e.g. to
+test the CLI path on a non-sandboxed vault).
+
+The resolved strategy is surfaced in the workspace API response and
+on the `/settings/wiki` row, so you can always see which path
+(`fs` or `cli`) `auto` settled on. The full design is in
+WIKI_BUILDER_DESIGN.md §P2.B / §8.
+
+## Dispatch mode (`parallel` / `serial`)
+
+`!ingest` honours the per-workspace **dispatch mode** in
+`/settings/wiki`:
+
+- **Parallel** (default): all URLs fan out simultaneously up to the
+  per-URL concurrency cap (`wiki_workspaces.concurrency_cap`, default
+  `3`, valid range 1–10). Fastest; small risk of bursting rate
+  limits at the URL host.
+- **Serial**: URLs are enqueued in submitted order; each agent
+  session starts only after the previous one completes. Slower but
+  predictable budget and rate.
+
+The acknowledgement DM tells you which mode ran
+(`in parallel` / `serially`).
+
+## Language
+
+`wiki_workspaces.language` is the workspace's content language. It
+defaults to `en` and is independent of `runtimeSettings.primaryLanguage`
+— see WIKI_BUILDER_DESIGN.md §14 Q2 for the reasoning. You can pick
+any language tag from the picker in `/settings/wiki`; the value is
+passed to the wiki skills as the target language for compiled
+articles, ask answers, and trace / connect outputs.
+
+The wiki language does **not** cascade from your primary language at
+seed time. A user who runs the dashboard in Japanese can keep their
+wiki in English, and vice versa.
+
+## Archive vs delete
+
+- **Archive** — flips `active=0` on the row but keeps the on-disk
+  data and the row's metadata. Bang commands cannot target an
+  archived workspace; the dashboard hides it from the active list
+  but surfaces it in an "Archived" collapsible. You can unarchive by
+  re-enabling the workspace.
+- **Delete** — drops the row. On-disk data is **not** removed for
+  external workspaces (the daemon never deletes the user's vault).
+  For internal workspaces, the disk tree is also left in place under
+  `$PA_DATA_DIR/context/knowledge/wiki/<name>` — recover by re-creating
+  a workspace at the same name.
+
+## Fields and defaults reference
+
+Quick map between the dashboard knobs and the `wiki_workspaces` row:
+
+| Setting | Column | Default |
+|---|---|---|
+| Workspace name | `name` | `default` |
+| Kind | `kind` | `internal` |
+| Root path | `root_path` | `$PA_DATA_DIR/context/knowledge/wiki/<name>` (internal) |
+| Language | `language` | `en` |
+| Dispatch mode | `dispatch_mode` | `parallel` |
+| Concurrency cap | `concurrency_cap` | `3` |
+| Write strategy | `write_strategy` | `fs` (internal) / `auto` (external) |
+| Pre-compile git auto-commit | `git_pre_compile_enabled` | `1` |
+| Full-compile approval threshold | `full_compile_approval_threshold_usd` | `2.00` |
+| DM-agent writes allowed | `dm_agent_write_enabled` | `0` |
+| Bridge feature | `bridge_enabled` | `0` |
+| Bridge measurement-only | `bridge_measurement_only` | `1` |
+| Bridge min confidence | `bridge_min_confidence` | `0.70` |
+| Active | `active` | `1` |
+
+`dm_agent_write_enabled=0` is the safe default — the DM agent can
+only call the read-side wiki routes; writes happen inside dedicated
+`wiki.*` sessions spawned by bang commands.

package/agent-assets/docs/getting-started/01-what-is-this.md

@@ -3,25 +3,51 @@ schema_version: 1
 slug: getting-started/01-what-is-this
 title: What is Aitne?
 id: what-is-this
+aliases:
+  - aitne
+  - what is aitne
+  - what is this
+  - introduction
+  - personal AI agent
 category: getting-started
 summary: |
   Aitne is a local-first proactive personal AI agent. It runs
-  as a daemon on your own machine, calls Claude / Codex / Gemini via
-  API keys you register (with the local CLI's subscription auth as a
-  fallback), and stores all memory as plain Markdown files.
+  as a daemon on your own machine, drives Claude / Codex / Gemini /
+  OpenCode via API keys you register (with the local CLI's
+  subscription auth as a fallback), and stores all memory as plain
+  Markdown files.
 section: getting-started
 tags:
   - core
   - getting-started
+  - backends
 status: stable
 ask_examples:
   - What is Aitne?
   - How is this different from ChatGPT?
   - Where does my data live?
   - What can Aitne actually do for me?
+  - Which backends can Aitne drive?
 locale: en-US
+ui_anchors:
+  - /
+  - /settings/models
+keywords:
+  - introduction
+  - overview
+  - what is aitne
+  - personal agent
+  - local-first
+  - proactive
+  - markdown memory
+  - backends
 created: 2026-04-25
-updated: 2026-04-27
+updated: 2026-05-28
+context_files:
+  - state/today.md
+  - plans/roadmap.md
+  - journal/agent.md
+  - identity/profile.md
 related:
   - getting-started/02-first-steps
   - getting-started/03-what-can-this-do
@@ -33,10 +59,11 @@ related:
 # What is Aitne?
 
 Aitne is a local-first personal AI agent. It runs as a long-running
-daemon on your own machine, drives Claude Code, Codex CLI, or Gemini
-CLI via provider API keys you register (with the CLI's local
-subscription login as a fallback), and keeps all of its memory as
-plain Markdown files under `~/.personal-agent/`.
+daemon on your own machine, drives Claude Code, Codex CLI, Gemini
+CLI, or OpenCode (`@opencode-ai/sdk` server) via provider API keys
+you register (with the CLI's local subscription login as a
+fallback), and keeps all of its memory as plain Markdown files under
+`~/.personal-agent/`.
 
 Unlike a chat assistant that only responds when you type, Aitne also
 runs on its own — on a schedule, in reaction to changes it sees in
@@ -51,7 +78,7 @@ By default:
 
 - Every morning, it reads your calendar, unread mail, open tasks, and
   recent notes, and writes today's plan into
-  [`today.md`](../features/memory-files/today.md).
+  [`state/today.md`](../features/memory-files/today.md).
 - Every evening, it reviews how the day went and updates
   [`journal.md`](../features/memory-files/agent-journal.md).
 - Once a week and once a month, it rolls those journals up.
@@ -99,9 +126,8 @@ decides what (if anything) is worth telling you about.
   [reading list](../features/lifestyle/reading.md),
   [receipts](../features/lifestyle/receipts.md), and
   [travel bookings](../features/lifestyle/travel-bookings.md).
-- [Calendar](../features/integrations/calendar.md) — including
-  [travel-time](../features/lifestyle/travel-time.md) lookups before
-  events.
+- [Calendar](../features/integrations/calendar.md) — pre-meeting
+  nudges and same-day briefing context.
 - [Obsidian](../features/integrations/obsidian.md) — watches a vault
   for new notes.
 - [Notion](../features/integrations/notion.md) — watches selected
@@ -116,43 +142,49 @@ Everything the agent learns about you is written as Markdown files
 you can read, edit, and version yourself. Nothing important lives in
 an opaque vector store.
 
-- [`user/profile.md`](../features/memory-files/user-profile.md) —
+- [`identity/profile.md`](../features/memory-files/user-profile.md) —
   what the agent knows about you.
-- [`projects/*.md`](../features/memory-files/projects.md) — one file
+- [`plans/projects/*.md`](../features/memory-files/projects.md) — one file
   per active project.
-- [`roadmap.md`](../features/memory-files/roadmap.md) — longer-term
+- [`plans/roadmap.md`](../features/memory-files/roadmap.md) — longer-term
   goals.
-- [`schedule/YYYY-MM-DD.md`](../features/memory-files/schedule.md) —
-  per-day plans.
-- [`today.md`](../features/memory-files/today.md) — today's plan.
-- [`agent/journal.md`](../features/memory-files/agent-journal.md) —
+- [`state/today.md`](../features/memory-files/today.md) — today's plan.
+- [`journal/daily/YYYY-MM-DD.md`](../features/memory-files/schedule.md) —
+  per-day archived plans.
+- [`journal/agent.md`](../features/memory-files/agent-journal.md) —
   what the agent did and noticed.
 
 → [Memory Model](../concepts/memory-model.md)
 
-### Drive Claude Code / Codex / Gemini via API keys
+### Drive Claude Code / Codex / Gemini / OpenCode via API keys
 
-Aitne drives Claude Code, Codex CLI, and Gemini CLI on your behalf.
-The recommended setup is to register a provider API key for each
-backend you want to use — this matches what Anthropic, OpenAI, and
-Google document for headless / programmatic agent use, and gives you
-predictable per-call billing that is unambiguously permitted.
+Aitne drives Claude Code, Codex CLI, Gemini CLI, and OpenCode on
+your behalf. The recommended setup is to register a provider API key
+for each backend you want to use — this matches what Anthropic,
+OpenAI, and Google document for headless / programmatic agent use,
+and gives you predictable per-call billing that is unambiguously
+permitted.
 
 - Claude — `ANTHROPIC_API_KEY` (via Claude Code)
 - Codex — `OPENAI_API_KEY` (via Codex CLI)
 - Gemini — `GEMINI_API_KEY` / `GOOGLE_API_KEY` (via Gemini CLI)
+- OpenCode — provider key (Anthropic / OpenAI / OpenRouter / …)
+  forwarded into the OpenCode server in Managed or Remote mode
 
 If you skip the API key, Aitne falls back to whatever local
 subscription login the CLI already has on your machine (`claude`,
 `codex login`, `gemini auth`). This fallback works mechanically, but
 most providers do not officially support running automated agents on
-a personal subscription — Anthropic currently prohibits using the
-Claude Agent SDK with a Claude Pro / Max subscription. The dashboard
-surfaces a warning whenever a backend is running on subscription
-auth.
-
-Each kind of work (heavy reasoning vs. a quick reply) is mapped to a
-backend; you can change the mapping any time.
+a personal subscription — Anthropic, for example, currently prohibits
+using the Claude Agent SDK with a Claude Pro / Max subscription. The
+dashboard surfaces a warning whenever a backend is running on
+subscription auth.
+
+Each kind of work is mapped to a backend and a tier — most work runs
+on medium (Claude Sonnet 4.6 by default) and quick triage on lite
+(Claude Haiku 4.5). The high tier (Claude Opus 4.8) is registered but
+left unseeded; you opt into it per task from the dashboard. You can
+change any of this mapping at any time.
 
 → [Backends and Tiers](../concepts/backends-and-tiers.md) ·
 [Costs and Quotas](../concepts/costs-and-quotas.md) ·

package/agent-assets/docs/getting-started/02-first-steps.md

@@ -3,6 +3,11 @@ schema_version: 1
 slug: getting-started/02-first-steps
 title: First Steps in the Dashboard
 id: first-steps
+aliases:
+  - first steps
+  - first time
+  - dashboard onboarding
+  - after install
 category: getting-started
 summary: |
   What to do the moment the dashboard opens — finish the setup wizard,
@@ -11,20 +16,33 @@ section: getting-started
 tags:
   - core
   - getting-started
+  - setup
 status: stable
 ask_examples:
   - I just opened the dashboard. What now?
   - How do I get the agent to talk to me?
   - Do I have to connect every integration?
+  - Where is the setup wizard?
 locale: en-US
+keywords:
+  - first steps
+  - setup wizard
+  - pair messaging
+  - dashboard onboarding
+  - health pill
 created: 2026-04-27
-updated: 2026-05-04
+updated: 2026-05-28
 related:
   - getting-started/01-what-is-this
   - getting-started/03-what-can-this-do
   - getting-started/04-first-day
   - guides/setup-wizard
-  - guides/use-cloud-providers
+ui_anchors:
+  - /setup
+  - /
+  - /activity
+  - /connections
+  - /settings/models
 ---
 
 # First Steps in the Dashboard
@@ -51,19 +69,19 @@ in (a backend, a messaging pair). Run through it once, top to bottom.
    [Messaging Overview](../features/messaging/overview.md) for the
    list of supported apps and what each one does well.
 3. **Pick a main backend and register an API key.** Pick the LLM
-   the agent uses for "think hard" turns (Claude / Codex / Gemini)
-   and paste a provider API key — the supported way to run a
-   headless agent. If you skip the key, the daemon falls back to
+   the agent uses for "think hard" turns (Claude / Codex / Gemini /
+   OpenCode) and paste a provider API key — the supported way to run
+   a headless agent. If you skip the key, the daemon falls back to
    whatever subscription login the matching CLI already has on your
    machine; the dashboard surfaces a warning when this happens
    because most providers do not support running agents on a
    personal subscription. The same picker also lets you point the
    backend at a cloud provider (Bedrock / Vertex / Foundry / Azure
-   OpenAI / Gemini-Vertex) instead of the direct API key — see
-   [Use a Cloud Provider for Models](../guides/use-cloud-providers.md).
-   Defaults are sensible and can be changed later from
-   `/settings/models`. Background:
-   [Backends and Tiers](../concepts/backends-and-tiers.md).
+   OpenAI / Gemini-Vertex) instead of the direct API key — the
+   provider dropdown on `/settings/models` is the single surface for
+   both direct keys and cloud-provider credentials. Defaults are
+   sensible and can be changed later from `/settings/models`.
+   Background: [Backends and Tiers](../concepts/backends-and-tiers.md).
 4. **Skip integrations you do not need yet.** Mail, calendar, git,
    Notion, Obsidian are all optional and re-runnable any time from
    `/connections`.

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

@@ -3,6 +3,11 @@ schema_version: 1
 slug: getting-started/03-what-can-this-do
 title: What This App Can Do
 id: what-can-this-do
+aliases:
+  - what can it do
+  - capabilities
+  - feature tour
+  - what features exist
 category: getting-started
 summary: |
   A tour of Aitne's capabilities at a beginner-friendly
@@ -11,25 +16,42 @@ section: getting-started
 tags:
   - core
   - getting-started
-  - overview
+  - routines
+  - messaging
+  - wiki
 status: stable
 ask_examples:
   - What can Aitne actually do?
   - What features should I try first?
   - How does the agent reach out to me?
+  - Can the agent transcribe my voice messages?
+  - Can the agent build me a personal wiki?
 locale: en-US
+keywords:
+  - capabilities
+  - feature tour
+  - overview
+  - voice transcription
+  - wiki
+  - lifestyle
 created: 2026-04-27
-updated: 2026-05-04
+updated: 2026-05-28
 related:
   - getting-started/01-what-is-this
   - getting-started/02-first-steps
   - getting-started/04-first-day
   - concepts/routines
   - concepts/memory-model
-  - features/messaging/voice-attachments
-  - features/operations/skill-self-optimization
+  - concepts/skills
+  - features/messaging/overview
   - features/wiki/overview
   - features/wiki/commands
+ui_anchors:
+  - /chat
+  - /connections/messaging
+  - /knowledge
+  - /wiki
+  - /settings/self-learning
 ---
 
 # What This App Can Do
@@ -40,8 +62,8 @@ the doc that goes deep.
 ## Plan your day, on its own
 
 The agent runs **routines** on a schedule. The morning routine builds
-`today.md` from your calendar, mail, tasks, and notes; the evening
-review writes a journal entry; weekly and monthly summaries roll up.
+`state/today.md` from your calendar, mail, tasks, and notes; the evening
+review writes a journal entry; the weekly review rolls up the week.
 
 - [Routines](../concepts/routines.md) — what runs and when.
 - [Morning Routine](../features/routines/morning-routine.md)
@@ -55,9 +77,8 @@ something comes up. Voice notes are transcribed locally with Whisper
 so you can talk to it the same way you'd type.
 
 - [Messaging Overview](../features/messaging/overview.md) — supported
-  apps and how pairing works.
-- [Voice Attachments](../features/messaging/voice-attachments.md) —
-  local transcription of inbound audio.
+  apps, how pairing works, and how voice notes get transcribed
+  locally with Whisper.
 - [Dashboard Chat](../features/messaging/dashboard-chat.md) — the
   in-dashboard chat surface.
 
@@ -81,10 +102,10 @@ them — the agent reads what's there next time it runs.
 
 - [Memory Model](../concepts/memory-model.md) — the layout and the
   rules around it.
-- [user/profile.md](../features/memory-files/user-profile.md) — what
+- [identity/profile.md](../features/memory-files/user-profile.md) — what
   the agent knows about you.
-- [today.md](../features/memory-files/today.md) — today's plan.
-- [agent/journal.md](../features/memory-files/agent-journal.md) —
+- [state/today.md](../features/memory-files/today.md) — today's plan.
+- [journal/agent.md](../features/memory-files/agent-journal.md) —
   what the agent did and what it noticed.
 
 ## Build a personal wiki from what you DM
@@ -105,13 +126,12 @@ API so the layout invariants hold.
 
 ## Help with the small lifestyle stuff
 
-Reading lists, receipts, travel bookings, travel-time estimates — the
-agent collects what arrives in mail and surfaces it in the right tab.
+Reading lists, receipts, travel bookings — the agent collects what
+arrives in mail and surfaces it in the right tab.
 
 - [Reading](../features/lifestyle/reading.md)
 - [Receipts](../features/lifestyle/receipts.md)
 - [Travel Bookings](../features/lifestyle/travel-bookings.md)
-- [Travel Time](../features/lifestyle/travel-time.md)
 
 ## Stay in control
 
@@ -127,13 +147,14 @@ operations keep the agent from doing anything you don't want.
 
 ## Get sharper over time
 
-A background self-optimization loop watches how your knowledge layout
-drifts (new folders, schema tweaks, vocabulary changes) and refines
-specific skill sections to match. The original SKILL.md files are
-never rewritten — overlays are reversible.
+A background skill-curation loop watches how your knowledge layout
+drifts (new folders, schema tweaks, vocabulary changes) and proposes
+JSON **overlays** that refine specific skill sections to match. The
+seed `SKILL.md` files are never rewritten — overlays are reversible.
+Review and approve proposals from **Settings → Self-learning**.
 
-- [Skill Self-Optimization](../features/operations/skill-self-optimization.md)
-  — the loop, the cadence, and the dashboard surface.
+- [Skills](../concepts/skills.md) — how skill curation, overlays, and
+  the self-learning review surface work.
 
 ## Related