@aitne-sh/aitne 0.1.5 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +16 -0
  2. package/agent-assets/agent-profiles/_safety.md +17 -2
  3. package/agent-assets/agent-profiles/routine-fetch-window.md +75 -40
  4. package/agent-assets/agent-profiles/wiki-agent.md +19 -0
  5. package/agent-assets/docs/features/messaging/bang-commands.md +161 -0
  6. package/agent-assets/docs/features/messaging/overview.md +3 -0
  7. package/agent-assets/docs/features/wiki/commands.md +222 -0
  8. package/agent-assets/docs/features/wiki/overview.md +145 -0
  9. package/agent-assets/docs/getting-started/03-what-can-this-do.md +18 -0
  10. package/agent-assets/docs/glossary.md +34 -0
  11. package/agent-assets/docs/guides/budget-and-cost-for-wiki.md +123 -0
  12. package/agent-assets/docs/guides/build-your-wiki.md +99 -0
  13. package/agent-assets/docs/guides/explore-with-trace-and-connect.md +169 -0
  14. package/agent-assets/docs/guides/maintain-wiki-health.md +168 -0
  15. package/agent-assets/docs/guides/multiple-wikis-for-multiple-domains.md +192 -0
  16. package/agent-assets/docs/guides/pause-the-agent.md +10 -3
  17. package/agent-assets/docs/guides/use-an-existing-obsidian-vault.md +156 -0
  18. package/agent-assets/docs/reference/cli-commands.md +24 -1
  19. package/agent-assets/docs/troubleshooting/wiki-ingest-full-blocked.md +96 -0
  20. package/agent-assets/docs/troubleshooting/wiki-write-failed.md +82 -0
  21. package/agent-assets/skills/context/SKILL.md +288 -17
  22. package/agent-assets/skills/external-services/SKILL.delegated.claude.md +2 -2
  23. package/agent-assets/skills/external-services/SKILL.delegated.codex.md +3 -3
  24. package/agent-assets/skills/external-services/SKILL.delegated.gemini.md +6 -6
  25. package/agent-assets/skills/external-services/SKILL.md +5 -3
  26. package/agent-assets/skills/external-services/SKILL.native.claude.md +49 -58
  27. package/agent-assets/skills/external-services/SKILL.native.codex.md +50 -58
  28. package/agent-assets/skills/external-services/SKILL.native.gemini.md +53 -56
  29. package/agent-assets/skills/mail/SKILL.md +5 -5
  30. package/agent-assets/skills/mail/SKILL.native.claude.md +57 -65
  31. package/agent-assets/skills/mail/SKILL.native.codex.md +73 -75
  32. package/agent-assets/skills/mail/SKILL.native.gemini.md +80 -75
  33. package/agent-assets/skills/management-task-register/SKILL.md +3 -3
  34. package/agent-assets/skills/notion/SKILL.native.claude.md +78 -82
  35. package/agent-assets/skills/notion/SKILL.native.codex.md +78 -80
  36. package/agent-assets/skills/notion/SKILL.native.gemini.md +91 -90
  37. package/agent-assets/skills/observations/SKILL.md +104 -14
  38. package/agent-assets/skills/roadmap/SKILL.md +19 -0
  39. package/agent-assets/skills/schedule/SKILL.md +44 -3
  40. package/agent-assets/skills/today/SKILL.md +25 -5
  41. package/agent-assets/skills/travel-time/SKILL.md +9 -0
  42. package/agent-assets/skills/wiki/wiki-ask/SKILL.md +32 -0
  43. package/agent-assets/skills/wiki/wiki-compile/SKILL.md +126 -0
  44. package/agent-assets/skills/wiki/wiki-connect/SKILL.md +75 -0
  45. package/agent-assets/skills/wiki/wiki-graduate/SKILL.md +45 -0
  46. package/agent-assets/skills/wiki/wiki-ingest/SKILL.md +182 -0
  47. package/agent-assets/skills/wiki/wiki-lint/SKILL.md +90 -0
  48. package/agent-assets/skills/wiki/wiki-trace/SKILL.md +72 -0
  49. package/agent-assets/skills/wiki/wiki-vault-rules/SKILL.md +145 -0
  50. package/agent-assets/task-flows/_partials/calendar-acquire.google_calendar.md +28 -9
  51. package/agent-assets/task-flows/_partials/calendar-acquire.outlook_calendar.md +26 -9
  52. package/agent-assets/task-flows/_partials/mail-acquire.gmail.md +51 -24
  53. package/agent-assets/task-flows/_partials/mail-acquire.outlook_mail.md +46 -16
  54. package/agent-assets/task-flows/_partials/notion-acquire.notion.md +29 -9
  55. package/agent-assets/task-flows/message.received.dm.md +35 -2
  56. package/agent-assets/task-flows/message.received.dm.native.claude.md +25 -26
  57. package/agent-assets/task-flows/message.received.dm.native.codex.md +30 -24
  58. package/agent-assets/task-flows/message.received.dm.native.gemini.md +36 -36
  59. package/agent-assets/task-flows/message.received.dm_first.md +43 -4
  60. package/agent-assets/task-flows/message.received.dm_first.native.claude.md +20 -20
  61. package/agent-assets/task-flows/message.received.dm_first.native.codex.md +22 -19
  62. package/agent-assets/task-flows/message.received.dm_first.native.gemini.md +28 -24
  63. package/agent-assets/task-flows/routine.fetch_window.md +51 -36
  64. package/agent-assets/task-flows/routine.morning_routine.md +12 -3
  65. package/agent-assets/task-flows/routine.morning_routine_initial.md +22 -1
  66. package/agent-assets/task-flows/scheduled.dm.md +477 -0
  67. package/agent-assets/task-flows/wiki.ask.md +11 -0
  68. package/agent-assets/task-flows/wiki.compile.md +28 -0
  69. package/agent-assets/task-flows/wiki.connect.md +12 -0
  70. package/agent-assets/task-flows/wiki.ingest_url.md +35 -0
  71. package/agent-assets/task-flows/wiki.lint.md +13 -0
  72. package/agent-assets/task-flows/wiki.trace.md +13 -0
  73. package/agent-assets/wiki-seeds/schemas/output.md +12 -0
  74. package/agent-assets/wiki-seeds/schemas/raw.md +13 -0
  75. package/agent-assets/wiki-seeds/schemas/wiki.md +12 -0
  76. package/agent-assets/wiki-seeds/taxonomy.md +13 -0
  77. package/package.json +21 -41
@@ -0,0 +1,168 @@
1
+ ---
2
+ schema_version: 1
3
+ slug: guides/maintain-wiki-health
4
+ title: Maintain Wiki Health
5
+ id: maintain-wiki-health
6
+ aliases:
7
+ - "!lint"
8
+ - wiki health
9
+ - wiki lint
10
+ - wiki orphans
11
+ - wiki taxonomy candidates
12
+ category: guides
13
+ summary: |
14
+ How to run `!lint`, read the health report, act on action items,
15
+ and review taxonomy candidates the wiki agent surfaces for owner
16
+ approval before promoting them.
17
+ section: maintain-wiki-health
18
+ tags:
19
+ - guide
20
+ - wiki
21
+ - health
22
+ status: stable
23
+ ask_examples:
24
+ - How do I run a wiki health check?
25
+ - What does the wiki health report contain?
26
+ - Where do I see the latest health report?
27
+ - How often should I run !lint?
28
+ - What is a taxonomy candidate?
29
+ locale: en-US
30
+ created: 2026-05-12
31
+ updated: 2026-05-12
32
+ related:
33
+ - features/wiki/overview
34
+ - features/wiki/commands
35
+ - guides/explore-with-trace-and-connect
36
+ ui_anchors:
37
+ - /wiki
38
+ - /wiki/timeline
39
+ - /settings/wiki
40
+ ---
41
+
42
+ # Maintain Wiki Health
43
+
44
+ The wiki is a living artifact. Notes accumulate, sources drift,
45
+ slugs collide, and the taxonomy slowly diverges from the vocabulary
46
+ your raw notes actually use. `!lint` is the periodic audit pass
47
+ that surfaces all of this in one report — without changing your
48
+ notes itself.
49
+
50
+ ## When to Run
51
+
52
+ `!lint` is cheap (Sonnet medium tier, default $0.50 envelope) and
53
+ non-destructive. Run it whenever you want a snapshot of wiki
54
+ health. A practical cadence:
55
+
56
+ - **Weekly**, after a busy ingest week, to catch orphans early.
57
+ - **Before promoting a candidate** to the taxonomy or graduating
58
+ an inbox note — you want the audit fresh.
59
+ - **After a bulk import** (Phase 2 migration or a backlog
60
+ `!ingest` batch) to verify the merge didn't introduce drift.
61
+
62
+ You don't need to schedule `!lint`; send it from a DM:
63
+
64
+ ```
65
+ !lint
66
+ ```
67
+
68
+ The wiki agent replies with the workspace name and tells you the
69
+ report will land at `90_meta/health/<today>.md`.
70
+
71
+ ## What the Report Contains
72
+
73
+ The report is a Markdown file at `90_meta/health/<YYYY-MM-DD>.md`
74
+ with a fixed section order:
75
+
76
+ 1. **Summary** — one-line tallies (`3 orphans, 1 broken link, 2
77
+ taxonomy candidates`).
78
+ 2. **Action items** — concrete fixes you can take, each naming
79
+ the affected file and the proposed change.
80
+ 3. **Orphans** — wiki notes with no incoming links.
81
+ 4. **Broken wikilinks** — `[[slug]]` references pointing at files
82
+ that no longer exist.
83
+ 5. **Missing frontmatter** — notes that don't satisfy the schema
84
+ in `90_meta/schemas/`.
85
+ 6. **Stale content** — wiki notes whose newest source link is
86
+ older than 90 days.
87
+ 7. **Term inconsistencies** — slugs that look like the same
88
+ concept under different names.
89
+ 8. **Taxonomy candidates** — recurring concepts that aren't yet
90
+ in `90_meta/taxonomy.md` (three or more raw notes, or two or
91
+ more wiki notes).
92
+ 9. **Index drift** — `20_wiki/_index.md` mismatches against disk.
93
+
94
+ Empty sections render as `_(none)_` so a diff between two reports
95
+ makes the change visible.
96
+
97
+ ## Reading the Report on the Dashboard
98
+
99
+ Open **My Life → Wiki → Timeline & health** (`/wiki/timeline`). The
100
+ page is also reachable from a button at the top of `/settings/wiki`,
101
+ and the legacy `/settings/wiki/timeline` URL redirects here so old
102
+ bookmarks still work. The most-recent report is parsed and rendered
103
+ with:
104
+
105
+ - A coloured date badge.
106
+ - The `## Summary` bullets.
107
+ - The `## Action items` list (this is the part you actually act on).
108
+ - A "View full report" expander showing the raw Markdown for
109
+ every section.
110
+
111
+ The same page hosts the activity timeline (see below) so you can
112
+ correlate a health finding with the ingest / compile / ask runs
113
+ that produced the state.
114
+
115
+ ## Acting on Action Items
116
+
117
+ The audit never modifies content layers itself. For each action
118
+ item:
119
+
120
+ - **Orphan** → either link the note from `20_wiki/_index.md` and
121
+ related notes, or archive it. From a DM you can run `!ask` to
122
+ decide whether the note's content has been superseded.
123
+ - **Broken wikilink** → edit the linking note via `!compile` (so a
124
+ fresh `wiki.compile` resolves the reference) or trace the
125
+ history with `!trace` to recover what the missing target used
126
+ to be.
127
+ - **Stale content** → re-ingest authoritative sources with `!ingest`,
128
+ then run `!compile` to re-synthesize.
129
+ - **Term inconsistencies** → decide on the canonical slug, then
130
+ update `90_meta/taxonomy.md` manually so future ingests pick the
131
+ right name.
132
+
133
+ ## Taxonomy Candidates
134
+
135
+ When `!lint` finds a concept appearing repeatedly that isn't yet
136
+ in the taxonomy, it appends a `# Candidates` section to
137
+ `90_meta/taxonomy.md`:
138
+
139
+ ```
140
+ # Candidates
141
+ - quantum-computing — referenced by 4 raw / 0 wiki
142
+ - formal-methods — referenced by 3 raw / 1 wiki
143
+ ```
144
+
145
+ **The wiki agent never promotes a candidate into the main `##
146
+ Topics` section itself.** Promotion is an owner act because once a
147
+ slug is canonical, every future ingest and compile pass will route
148
+ toward it. To promote, edit `90_meta/taxonomy.md` directly:
149
+
150
+ 1. Move the candidate line into the `## Topics` section.
151
+ 2. Delete the corresponding line from `# Candidates`.
152
+ 3. Optionally add aliases for spelling variants the raw notes use.
153
+
154
+ The next `!compile` will reconcile existing notes against the new
155
+ canonical slug.
156
+
157
+ ## Where the Report Lives
158
+
159
+ The report is a regular wiki file written via the standard
160
+ chokepoint, so:
161
+
162
+ - It's visible to `!ask` (you can literally ask "what did the last
163
+ lint find?").
164
+ - The DM read-only surface (`/api/wiki/.../files/90_meta/health/...`)
165
+ serves it back to a DM-agent for follow-up questions.
166
+ - Internal-mode workspaces snapshot the previous version into
167
+ `.snapshots/` before each rewrite; external-mode relies on your
168
+ git or cloud sync.
@@ -0,0 +1,192 @@
1
+ ---
2
+ schema_version: 1
3
+ slug: guides/multiple-wikis-for-multiple-domains
4
+ title: Multiple Wikis for Multiple Domains
5
+ id: multiple-wikis-for-multiple-domains
6
+ category: guides
7
+ summary: |
8
+ Run more than one wiki workspace inside the same daemon. Address
9
+ them from DMs with `@<workspace>`, manage them independently from
10
+ /settings/wiki, and keep their file trees isolated on disk.
11
+ section: multiple-wikis-for-multiple-domains
12
+ tags:
13
+ - guide
14
+ - wiki
15
+ - multi-workspace
16
+ status: stable
17
+ ask_examples:
18
+ - How do I run multiple wikis?
19
+ - How do I target a specific wiki from a DM?
20
+ - What does `@research` do before a wiki command?
21
+ locale: en-US
22
+ created: 2026-05-12
23
+ updated: 2026-05-12
24
+ related:
25
+ - features/wiki/overview
26
+ - features/wiki/commands
27
+ - guides/build-your-wiki
28
+ - guides/use-an-existing-obsidian-vault
29
+ ---
30
+
31
+ # Multiple Wikis for Multiple Domains
32
+
33
+ Phase 5 lifted Aitne's single-workspace ceiling. If you keep distinct
34
+ knowledge bases — say, a research vault, a parenting journal, and an
35
+ ops runbook — you can run each as its own wiki workspace inside the
36
+ same daemon. The DM agent routes commands per workspace; the file
37
+ trees never overlap.
38
+
39
+ ## Why you might want this
40
+
41
+ - **Topic isolation.** A query against your research wiki should not
42
+ pull from your parenting journal. Separate workspaces give you
43
+ separate `_index.md` and `20_wiki/` trees so the agent never has to
44
+ filter across domains.
45
+ - **Different audiences.** A workspace synced via Obsidian to a shared
46
+ iCloud folder for a team is governed differently from a private
47
+ workspace in `$PA_DATA_DIR`. Per-workspace settings handle the
48
+ asymmetry.
49
+ - **Different cadences.** A "current project" wiki gets multiple
50
+ ingests per day; a long-term commonplace book may compile weekly.
51
+ Per-workspace dispatch / cost / approval thresholds let you tune
52
+ each.
53
+
54
+ ## Creating a second workspace
55
+
56
+ 1. Open `/settings/wiki`. You will see your current (default)
57
+ workspace.
58
+ 2. Scroll to **Add Workspace** (Phase 5 surface). Choose either:
59
+ - **Internal**, which lives under `$PA_DATA_DIR/wiki-<name>/`. Best
60
+ for private notes you never sync to another device.
61
+ - **External**, which points at an existing folder on disk (your
62
+ Obsidian vault, an iCloud-synced directory, a git working copy).
63
+ 3. Pick a unique `name` (lowercase letters, digits, `.`, `_`, `-`). The
64
+ name is what you address from DMs.
65
+ 4. The wizard probes the candidate path against §2.1.1 collision rules
66
+ — it refuses to nest a wiki inside your primary vault, the data
67
+ directory, or another active wiki. Iterate until the probe is green.
68
+ 5. Click **Create**. The vault skeleton (`00_inbox/`, `10_raw/`,
69
+ `20_wiki/`, `30_outputs/`, `90_meta/`) is seeded and the workspace
70
+ joins the active set.
71
+
72
+ ## Addressing a workspace from DMs
73
+
74
+ Every wiki bang command accepts an optional `@<workspace>` token
75
+ immediately after the bang:
76
+
77
+ !ingest @research https://arxiv.org/abs/2401.02954
78
+ !compile @research full
79
+ !ask @research what did I conclude about retrieval-augmented LMs?
80
+ !lint @parenting
81
+ !trace @ops "incident 2026-05-02"
82
+ !connect @research "diffusion models" "score matching"
83
+
84
+ Omit `@<workspace>` and the command targets the default workspace
85
+ (the one named `default`, set during initial setup).
86
+
87
+ The `@<token>` syntax is parsed before the command's own argument
88
+ parser sees the rest, so you can keep using multi-word topics and
89
+ comma-separated arguments verbatim.
90
+
91
+ ## What the agent sees per workspace
92
+
93
+ Each session is materialised against a single workspace's tree. The
94
+ `wiki-vault-rules` skill loaded for the session names that workspace's
95
+ language, dispatch mode, layer invariants, and frontmatter
96
+ conventions. Layer authorisation in the daemon API is workspace-scoped
97
+ — a `wiki.ask` session against `@research` cannot reach into
98
+ `@parenting`'s `10_raw/` even if the agent attempts it.
99
+
100
+ ## `!wiki` status with multiple workspaces
101
+
102
+ `!wiki` (no token) lists every active workspace in a compact form:
103
+
104
+ 3 active wiki workspaces:
105
+ - `default` (default) — 12r/8w/3o (internal)
106
+ - `research` — 84r/41w/12o (external)
107
+ - `parenting` — 7r/2w/0o (external)
108
+
109
+ Target a non-default workspace with `@<name>` (e.g. `!ask @research <question>`).
110
+
111
+ `r/w/o` are raw / wiki / output counts. The `(default)` marker tells
112
+ you which workspace `!ask` (with no `@`) will route to.
113
+
114
+ ## Configuring each workspace independently
115
+
116
+ `/settings/wiki` shows a workspace picker at the top once you have
117
+ more than one. Each workspace's panel carries its own:
118
+
119
+ - language (`en`, `ja`, …)
120
+ - dispatch mode (parallel / serial) and concurrency cap
121
+ - write strategy (`fs` / `cli` / `auto`) — external mode only
122
+ - full-compile approval threshold (USD)
123
+ - git pre-compile auto-commit toggle (external git vaults only)
124
+ - bridge feature gate + measurement mode + min confidence (Phase 5)
125
+ - DM-agent bridge write toggle
126
+
127
+ `POST /api/backends/apply-defaults` re-seeds the per-process backend /
128
+ model / budget rows but leaves the per-workspace columns alone — those
129
+ are operator preferences, not install defaults.
130
+
131
+ ## Per-workspace `/settings/models` rows
132
+
133
+ `/settings/models` lists the wiki process keys
134
+ (`wiki.ingest_url`, `wiki.compile`, `wiki.ask`, `wiki.lint`,
135
+ `wiki.trace`, `wiki.connect`) once each. The backend / model / budget
136
+ bound to each key applies across all workspaces — they share the
137
+ binding because the daemon resolves the row by process key, not by
138
+ workspace.
139
+
140
+ If you need a research vault on Opus 4.7 and a parenting journal on
141
+ Haiku 4.5 at the same time, the supported path today is:
142
+
143
+ - Bind `wiki.ask` to medium-tier Sonnet (a sensible cross-workspace
144
+ default).
145
+ - Use the workspace-aware `!ask @research` for the research vault and
146
+ rely on per-workspace token budgets via the cost ceiling.
147
+
148
+ A future enhancement is per-workspace model bindings; the present
149
+ shape was chosen to keep `/settings/models` legible without a
150
+ workspace dimension.
151
+
152
+ ## Archiving a workspace
153
+
154
+ The dashboard's **Archive** button on a workspace card flips its
155
+ `active` column to `0`. Archived workspaces:
156
+
157
+ - disappear from `!wiki` listings,
158
+ - reject all daemon API requests with `wiki_not_enabled`,
159
+ - drop out of `/search` and `/index`,
160
+ - keep their files on disk (you can re-activate later with no data
161
+ loss),
162
+ - have their `fts_wiki` rows cleared eagerly so a same-id re-enable
163
+ re-indexes from disk.
164
+
165
+ `DELETE /wiki/workspaces/:name` removes the row entirely (filesystem
166
+ contents are preserved — the daemon never deletes vault content). Use
167
+ this when you are sure you will not re-enable.
168
+
169
+ ## Path collision rules (recap)
170
+
171
+ Two active wiki workspaces cannot point at overlapping paths. Neither
172
+ can overlap:
173
+
174
+ - `primaryVaultPath` — your reactive-memory vault (`knowledge/`,
175
+ `today.md`, etc.).
176
+ - `externalObsidianVaultPath` — your owner-facing Obsidian vault.
177
+ - `$PA_DATA_DIR` — the daemon's data home.
178
+
179
+ The wizard's pre-create probe enforces this; PATCH cannot widen past
180
+ it. If you want to migrate a workspace to a new disk location, archive
181
+ the old row, create a fresh row pointing at the new path, then
182
+ manually copy the vault contents.
183
+
184
+ ## See also
185
+
186
+ - `docs/design/23-wiki-builder.md` — Phase summary table for the
187
+ overall wiki feature.
188
+ - `docs/design/appendices/wiki-external-vault.md` — write strategy,
189
+ iCloud handling, snapshot exclusion.
190
+ - `docs/design/appendices/wiki-bridge-mechanism.md` — Phase 5 bridge
191
+ capture from DMs into a workspace's raw layer.
192
+ - `docs/user/features/wiki/commands.md` — full bang command reference.
@@ -23,6 +23,7 @@ created: 2026-04-25
23
23
  updated: 2026-04-25
24
24
  related:
25
25
  - features/operations/quiet-hours
26
+ - features/messaging/bang-commands
26
27
  - concepts/routines
27
28
  ---
28
29
 
@@ -39,15 +40,19 @@ losing your install.
39
40
 
40
41
  ## Steps
41
42
 
42
- 1. **Disable the hourly check** from `/settings/routines` toggle
43
+ 1. **For a short pause from your phone**: DM `!stop` to the agent on
44
+ any paired messaging app. Autonomous work pauses immediately; the
45
+ daemon keeps running so you can `!start` to resume. See
46
+ [Bang Commands](../features/messaging/bang-commands.md).
47
+ 2. **Disable the hourly check** from `/settings/routines` — toggle
43
48
  `hourlyCheckEnabled` off. Morning, evening, weekly, and monthly
44
49
  reviews fire at fixed times in code, so they cannot be toggled
45
50
  from the dashboard; the most reliable mute is `pa stop`.
46
- 2. **Set an extended quiet hours window** on `/settings/schedule` —
51
+ 3. **Set an extended quiet hours window** on `/settings/schedule` —
47
52
  e.g. `quietHoursStart: "00:00"`, `quietHoursEnd: "23:59"`. Both
48
53
  fields take an `HH:MM` string. This silences notifications while
49
54
  keeping routines running.
50
- 3. **Optionally** stop the daemon entirely with `pa stop`. This is
55
+ 4. **Optionally** stop the daemon entirely with `pa stop`. This is
51
56
  the only way to fully suppress the fixed-schedule routines.
52
57
 
53
58
  ## Verification
@@ -62,4 +67,6 @@ losing your install.
62
67
 
63
68
  ## Related
64
69
 
70
+ - [Bang Commands](../features/messaging/bang-commands.md) — `!stop` /
71
+ `!start` from any paired DM.
65
72
  - [Quiet Hours](../features/operations/quiet-hours.md)
@@ -0,0 +1,156 @@
1
+ ---
2
+ schema_version: 1
3
+ slug: guides/use-an-existing-obsidian-vault
4
+ title: Use an Existing Obsidian Vault
5
+ id: use-an-existing-obsidian-vault
6
+ aliases:
7
+ - external wiki
8
+ - obsidian vault as wiki
9
+ - external mode
10
+ category: guides
11
+ summary: |
12
+ Point Aitne's wiki at an Obsidian vault you already maintain. The
13
+ setup wizard probes the path, classifies the layout, and walks you
14
+ through Adopt vs Migrate vs Split.
15
+ section: use-an-existing-obsidian-vault
16
+ tags:
17
+ - guide
18
+ - wiki
19
+ - obsidian
20
+ status: stable
21
+ ask_examples:
22
+ - Can the wiki use my existing Obsidian vault?
23
+ - How does the iCloud-sandbox fallback work?
24
+ - What does Adopt vs Migrate mean?
25
+ locale: en-US
26
+ created: 2026-05-12
27
+ updated: 2026-05-12
28
+ related:
29
+ - features/wiki/overview
30
+ - guides/build-your-wiki
31
+ - guides/budget-and-cost-for-wiki
32
+ - troubleshooting/wiki-write-failed
33
+ ---
34
+
35
+ # Use an Existing Obsidian Vault
36
+
37
+ ## Goal
38
+
39
+ Aitne can point the wiki subsystem at a vault you already maintain
40
+ in Obsidian, instead of creating its own at `$PA_DATA_DIR/wiki`.
41
+ This is "external mode", and the setup wizard walks you through
42
+ three decisions: **probe**, **classify**, then **Adopt vs Migrate
43
+ vs Split**.
44
+
45
+ ## Step 1 — Open Settings → Wiki
46
+
47
+ Click **Setup → Settings → Wiki** in the dashboard sidebar (or open
48
+ `/wiki` and follow the **Enable Wiki** button — both land on the same
49
+ page). If you have no workspace yet, the page shows two CTAs:
50
+
51
+ - **Enable Internal Workspace** — uses the daemon-owned root.
52
+ - **Probe & Create External** — points at the path you choose with
53
+ the folder picker.
54
+
55
+ ### Picking the path
56
+
57
+ The path field uses your OS-native folder dialog so you do not have
58
+ to type the path by hand or worry about typos:
59
+
60
+ - **macOS** — Finder's "choose folder" sheet opens.
61
+ - **Windows** — File Explorer's folder picker opens.
62
+ - **Linux** — one of `zenity`, `kdialog`, or `yad` opens (whichever
63
+ is installed on your system).
64
+
65
+ If you prefer to paste a path you already have on the clipboard, the
66
+ text field accepts that too — typing or pasting and clicking the
67
+ folder button are equivalent. Aitne refuses paths that overlap
68
+ `dataDir`, your primary vault, or the external Obsidian vault path so
69
+ two writers never claim the same files.
70
+
71
+ ### Inline validation banner
72
+
73
+ Once you pick a directory, Aitne immediately calls `GET /api/fs/probe`
74
+ and renders a banner under the input. The banner has three severity
75
+ levels:
76
+
77
+ - **Error (red)** — save is blocked. The most common cause is a
78
+ collision with another vault (primary, external Obsidian, dataDir,
79
+ or another wiki workspace); the second is a path under a system
80
+ prefix (`/etc`, `/var`, `/usr`, …) or matching a known secret-file
81
+ pattern (`.ssh`, `.env`, `Library/Keychains`, …).
82
+ - **Warning (amber)** — save is allowed but something needs your
83
+ attention. The most common case is "directory is not writable from
84
+ the daemon" — Aitne will fall back to the Obsidian CLI at runtime,
85
+ and you should leave Obsidian running.
86
+ - **Info (blue)** — nothing wrong. Used for "directory will be
87
+ created on save" (the path does not exist yet) and for "Obsidian
88
+ vault detected" / "existing LLM-Wiki layout detected" hints. When
89
+ an existing wiki layout is detected, the wizard will surface the
90
+ Adopt / Migrate decision in Step 3.
91
+
92
+ The **Probe & Create External** button is greyed out while the banner
93
+ is an error so you cannot fire a workspace-create that the daemon
94
+ already knows will fail.
95
+
96
+ ## Step 2 — Probe Classifies the Vault
97
+
98
+ The wizard calls `POST /api/wiki/workspaces/probe` and one of three
99
+ classifications comes back:
100
+
101
+ - **empty** — no markdown files anywhere. Aitne creates the layered
102
+ skeleton (`00_inbox/`, `10_raw/`, `20_wiki/`, `30_outputs/`,
103
+ `90_meta/`) and seeds `90_meta/taxonomy.md` + the schema templates.
104
+ - **partial** — fewer than two layer directories. This usually means
105
+ the directory holds unrelated notes. The wizard nudges you to
106
+ inspect before continuing so Aitne does not silently take over a
107
+ foreign vault.
108
+ - **wiki** — two or more layer directories. The wizard surfaces
109
+ schema deltas and the top `type:` values it detected, then offers
110
+ Adopt / Migrate / Split.
111
+
112
+ ## Step 3 — Adopt / Migrate / Split
113
+
114
+ | Option | What it does |
115
+ |---|---|
116
+ | **Adopt** | Keeps your existing schema and subdirectory layout verbatim. Aitne's wiki agent gets a workspace-specific addendum so it follows your conventions. |
117
+ | **Migrate** | Flattens type-based subdirectories (`20_wiki/concepts/x.md → 20_wiki/x.md`) and renames legacy frontmatter keys (`topic → title`, `source_url → url`, …) to Aitne's Bases-era schema. Always writes a backup mirror under `90_meta/health/pre-migrate-<date>/` first. |
118
+ | **Split** | Refuses to touch the existing vault and creates a sibling workspace instead. Available once multi-workspace lands. |
119
+
120
+ When you pick **Migrate**, the dashboard renders the plan — files
121
+ that will be moved, frontmatter renames per file, slug collisions to
122
+ resolve — before any write hits disk. Apply only once the plan looks
123
+ right; the report lands at `90_meta/health/import-<date>.md`.
124
+
125
+ ## Step 4 — First Compile
126
+
127
+ After the workspace is created (and migrated, if you chose that
128
+ path), you can:
129
+
130
+ - Run `!compile` for an incremental compile of any pre-existing raw
131
+ notes.
132
+ - Run `!compile full` for a one-shot full rebuild — but check the
133
+ cost estimate banner first. Above the per-workspace threshold
134
+ (default $2.00) the command queues an approval in the dashboard
135
+ rather than spending autonomously.
136
+
137
+ If your external vault is also a git repo, Aitne automatically
138
+ commits a `pre-compile snapshot` on a clean working tree before
139
+ `!compile full` so you can roll back if the result surprises you. A
140
+ dirty tree refuses the operation entirely — commit or stash first.
141
+
142
+ ## iCloud-Sandboxed Vaults
143
+
144
+ When Aitne's direct filesystem writes return `EPERM` (typical for
145
+ iCloud and other sandboxed locations), the daemon falls back to the
146
+ official Obsidian CLI. Requirements:
147
+
148
+ - Obsidian 1.12 or later installed.
149
+ - **Settings → General → Command line interface** enabled inside
150
+ Obsidian.
151
+ - The Obsidian app must be running (the CLI talks to the live
152
+ process).
153
+
154
+ The resolved write strategy is persisted into the workspace row so
155
+ the probe only runs once. The dashboard write-strategy dropdown lets
156
+ you pin `fs` or `cli` explicitly when you trust your own answer.
@@ -31,6 +31,7 @@ keywords:
31
31
  related:
32
32
  - guides/install-and-run
33
33
  - guides/reinstall-cleanly
34
+ - features/wiki/commands
34
35
  ---
35
36
 
36
37
  # CLI Commands
@@ -50,7 +51,7 @@ tables below show both forms.
50
51
  |---|---|
51
52
  | `aitne start` / `pnpm start` | Build (if stale), then launch daemon + dashboard in the background. |
52
53
  | `aitne stop` / `pnpm stop` | Graceful shutdown (SIGTERM → SIGKILL after 10s) of both processes. |
53
- | `aitne restart` / `pnpm restart` | `stop` then `start`. `--clean-context` wipes `context/` after a tarball backup. |
54
+ | `aitne restart` | `stop` then `start`. `--clean-context` wipes `context/` after a tarball backup. (Prefer the bin over `pnpm restart` / `npm restart`: those run the npm `stop` → `restart` → `start` lifecycle, which would re-fire each step.) |
54
55
  | `aitne status` / `pnpm status` | PIDs, uptime, integrations, today's spend, last action timestamp, next scheduled item. |
55
56
  | `aitne dev` / `pnpm dev` | Foreground mode — runs the daemon + dashboard with full stdio. |
56
57
 
@@ -86,6 +87,28 @@ tables below show both forms.
86
87
  | `pnpm lint` | Run eslint per package. |
87
88
  | `pnpm clean` | Remove `node_modules`, `dist`, `.buildstamp`. |
88
89
 
90
+ ## Wiki bang commands
91
+
92
+ Sent as DMs from a paired channel, not from the shell. Every command
93
+ accepts an optional `@<workspace>` token immediately after the bang to
94
+ target a non-default workspace. See
95
+ [Wiki Commands](../features/wiki/commands.md) for the full reference
96
+ and the cost-gate / approval semantics.
97
+
98
+ | Command | What it does |
99
+ |---|---|
100
+ | `!ingest [@<ws>] <url> [url...]` | Capture one or more URLs into the workspace's `10_raw/` layer. Caps at 10 URLs per batch; parallel or serial fan-out per the workspace's dispatch mode. |
101
+ | `!compile [@<ws>]` | Incremental compile — synthesises only raw notes touched since the last run into `20_wiki/`. |
102
+ | `!compile [@<ws>] --preview` | Dry-run touch list (added / modified / unchanged) plus cost and ETA. No agent session runs. Alias: `--dry-run`. |
103
+ | `!compile [@<ws>] full` | Full rebuild. Cost-gated: estimates above the per-workspace threshold queue a dashboard approval. On a clean external git vault, an automatic pre-compile snapshot is committed first. |
104
+ | `!compile [@<ws>] full --preview` | Dry-run of the full rebuild. |
105
+ | `!ask [@<ws>] <question>` | Cited answer from the workspace, written to `30_outputs/`. |
106
+ | `!lint [@<ws>]` | Audit orphans, broken links, schema drift, taxonomy candidates, stale notes. Writes `90_meta/health/<YYYY-MM-DD>.md`. |
107
+ | `!trace [@<ws>] <topic>` | Reconstruct how an idea has evolved across `10_raw` / `20_wiki` / `30_outputs`. |
108
+ | `!connect [@<ws>] <A>, <B>` | Find shared structure and bridges between two areas. |
109
+ | `!wiki` | Workspace status (per-workspace counts when multiple are active). |
110
+ | `!wiki help` | Wiki command list. |
111
+
89
112
  ## Environment overrides
90
113
 
91
114
  | Variable | Default | What it controls |