Wiki
A wiki is a structured, indexed knowledge base organized as a folder tree with
_index.md files. Each folder has an index that links to its children
(subfolders and pages), and a content section below a *** delimiter for
user-authored notes.
Initialize a wiki in the current project and configure integrations:
wiki init — scaffold a new wiki with a root index
wiki config — install Obsidian plugins and the git merge driver
wiki trust — authorize a wiki to run its .wiki/wiki.py hook
Maintain indexes as files are added and removed:
wiki lint — validate structure and flag issues
wiki update — sync index links with the filesystem
wiki new — create an indexed folder with an authored desc and content
Browse structure, search across content, and read entries:
wiki map — print an indented tree overview
wiki search — rank relevant pages with SQLite FTS5
wiki match — match content with regex
wiki read — read a named entry
Usage
Install the CLI from PyPI if it is not already on your PATH:
pipx install plasma-wiki
(pip install or uv tool install work too.)
Then run commands directly:
wiki <command> ...
Run wiki --help for a list of commands, and wiki <command> --help for full
option descriptions.
Working at scale
A wiki is many small, independent pages, so wiki work parallelizes well and is
often too large for one context. Default to sub-agents and dynamic workflows
rather than authoring or auditing page by page yourself:
- Fan out sub-agents. When seeding or expanding a wiki, give each
independent page — or each source to research and digest — to its own
sub-agent, then run
wiki update once to stitch the new pages into the
indexes. Update adds and repairs index link rows and frontmatter only — it
never linkifies mentions in page prose, so author [[...]] cross-links by
hand.
- Drive sweeps with a dynamic workflow. When auditing, relinking, or
restructuring an existing wiki, pipeline its pages through a workflow so each
is read, revised, and verified on its own — slow pages never block fast ones.
Conventions
.wiki/ is the tool's namespace. Every root carries a .wiki/ directory
holding settings.json — the file that declares the wiki root; wiki init
writes it and wiki update restores a missing one — plus the derived
word-counts and ranked-search caches and the staged Obsidian config. Never
author content there; the walk skips dot-directories by construction.
- Exclusions are configurable. Beyond the built-ins (dot-paths, symlinks,
_index.md), gitignore-style globs in exclude.patterns in
.wiki/settings.json exclude whole subtrees from indexing — never walked,
scaffolded, or linted, though wiki read still serves them. The enclosing git
repository's ignore rules fence the same way, with no configuration: what the
repo ignores is not wiki content, so a stray driver output beside tracked
pages is never adopted, minted an _index.md, or linked — delete or fence
residue rather than letting update sweep it in. A wiki whose own root is
gitignored is exempt.
- Name validation is configurable. By default the wiki rejects only
structural characters (
/, \, *, [, ], |, #), a leading dot,
non-printable names, and the reserved _index stem — spaces, dashes, and
unicode all pass. Stricter rules (e.g. ASCII identifiers) are opt-in per wiki
via naming.validate in .wiki/settings.json (seed it at creation with
wiki init --settings); wiki init and wiki lint enforce whatever policy
is set.
- Timestamps are tool-owned and configurable.
wiki update writes both
stamps when a file gains frontmatter, keeps created: from then on, and
rewrites updated: on every actual write — never hand-edit them; an edit goes
undetected unless the value stops parsing under the configured format, which
wiki lint fails. created/updated default to UTC in %Y-%m-%dT%H:%M:%SZ;
set timestamp.timezone (an IANA name) and timestamp.format (a strftime
string) in .wiki/settings.json to change them — use %z rather than a
literal Z for a non-UTC zone.
- Names are path-derived; titles are authored.
wiki update sets each
page's name and H1 heading to the path-joined name (e.g. core/design) so
names stay consistent with the tree structure — to rename an entry, move its
file rather than editing name:. Any index or page may carry an optional
authored title: frontmatter field, which wins its H1 (wiki update keeps
the line directly under name:, and adding frontmatter to a bare page seeds
title: from its authored H1); without one, a hand-edited heading is still
rewritten to name. Unset a title by deleting the line or setting
title: null — update removes it, and lowercase null is the only reset
spelling (~/Null/NULL render literally as the heading). Keep titles on a
single line, quote a title containing : , and prefer plain text.
wiki match --field title matches only authored titles — an unset entry has
no line to match. Setting titles.required to true in .wiki/settings.json
demands a title everywhere: update seeds a title: null placeholder on every
index and page missing one, and lint fails each placeholder until a value is
authored.
- Categories are authored and optional. An index or page may carry a
category: frontmatter field; wiki update copies it into the parent index's
link label as a [category] name prefix, and wiki map --category filters by
it. Fresh frontmatter carries no category: line — unset one by deleting the
line or setting category: null (update removes the line; as with titles,
lowercase null is the only reset spelling). Keep categories on a single
line.
- Frontmatter order is tool-enforced.
wiki update keeps every block in
canonical order — name, title, desc, category, tags, sources,
created, updated — moving each field (with its block-scalar body) verbatim
into its slot. Custom keys are allowed: they keep their relative order below
the known fields, above the timestamps.
- Wikilinks stay inside the wiki. A wikilink (
[[...]]) must target another
page in the same wiki. Files outside the wiki (source files, configs, another
wiki's pages) can be referenced by name or in backticks, but never linked.
- Lint's output contract.
wiki lint prints issues to stdout and soft notes
to stderr; exit 1 means exactly "issues found" (0 clean, 2 a command error) —
notes never gate. A script must branch on the exit code or read
wiki lint --json (one JSON document on stdout carrying every finding typed:
an explicit issue/note severity, a machine kind, and per-kind payload
fields beside the prose text), never classify findings by scraping the prose
streams: a stderr note is not a blocking issue.
- Stale wikilinks are soft notes. A
[[...]] in index or page prose whose
target no longer exists draws a stderr note from wiki lint without failing
the run. Broken links in the generated index link block — the rows
wiki update maintains — are hard issues until the next update prunes them
(each removal announced, with the cause named when the target is merely
excluded rather than deleted), as is a prose wikilink naming a folder rather
than the folder's index page: link [[folder/_index]], never [[folder]].
- Descriptions end in a period.
wiki lint fails a desc (or an authored
link description) that lacks a trailing period; the seeded ... placeholder
only draws a soft note. Author the desc in the child page's frontmatter —
wiki update copies it onto the parent index's link line. A desc containing
: must be YAML-quoted; surrounding quotes are stripped when the value is
read. Never hand-wrap a desc mid-word or onto a list-marker start — let the
block scalar carry the breaks; lint fails the wrap artifacts (a hyphen dangle,
a phantom list item).
- Fill in auto-created index descs.
wiki update creates a missing
_index.md for every new directory with a desc: ... placeholder and
announces the batch in its condensed summary
(Created N new indexes (fill in their descs); run with --full for the
per-path New index: lines). Fill in the desc right after the update — lint
soft-notes the placeholder until you do. For a deliberate creation (an
adoption ceremony's mechanical step), prefer
wiki new <folder> --desc ... --content ...: it requires both authored inputs
— refusing blanks and placeholders outright, descs are never auto-stubbed —
and wires the folder's rows and the parent's new row in the same pass, so the
adoption lands lint-complete. The wiring is a scoped wiki update of the
parent subtree (the whole wiki for a top-level folder), so pending maintenance
in that scope — adoptions, prunes — lands in the same run.
- Bare pages are adopted loudly. A page with no frontmatter gains it on the
next
wiki update — with title: seeded from its authored H1, while a page
with no H1 gains the path-joined heading in its body, never a seeded title —
and each adoption is announced (Adopted N bare pages (frontmatter added) in
the condensed summary; --full prints the per-page lines). Until then
wiki lint names the page as a hard issue
(Bare page (no frontmatter); update will adopt it) alongside the adoption
diff.
- Suppress lint locally with a
no-lint region. A page that must display
otherwise-flagged content (sample conflict markers, stale link examples) wraps
those lines in <!-- start: no-lint --> ... <!-- end: no-lint -->, which
silences the positional rules — hard issues and soft notes alike — for just
that span. Regions never affect file-level checks, and a dangling or nested
marker is itself a hard lint issue.
- Give markdown formatters the wiki plugin. The
*** delimiter and
[[wikilinks]] are load-bearing syntax; mdformat/prettier-style hooks rewrite
*** to --- and escape the brackets, demoting the generated link block to
plain text. wiki update repairs a mangled index and wiki lint names the
damage signatures (escaped wikilinks, a thematic break standing where ***
belongs), but don't rely on the repair: for mdformat add the mdformat-wiki
plugin (under pre-commit, additional_dependencies: [mdformat-wiki] on the
hook, dropping a coexisting mdformat-frontmatter — both register a
frontmatter renderer and whichever is discovered first wins), which makes wiki
faces round-trip byte-identically; for formatters with no plugin lane (e.g.
prettier) exclude the wiki root instead (wiki/ in .prettierignore).
- The git merge driver resolves only the generated region. For
_index.md
files it normalizes the regenerated name/updated keys to ours (plus
created on an add/add merge, where both sides seeded it), resolves the link
block to the union of both sides' rows — ours' layout wins and rows present
only in theirs ride over with their desc continuations, appended above the
closing ***, so a merge never drops one side's additions — and three-way
merges everything authored — the remaining frontmatter fields
(title/desc/created/category/tags/sources) and the user content
below *** — which can still conflict for hand-resolution. A side missing its
*** entirely (formatter damage) can't be split into regions, so it conflicts
whole-file with a hint comment naming the repair — restore the *** on that
branch (wiki update does it), then redo the merge. Run wiki update after a
merge to re-sort the link rows and prune any carried row whose target is gone
from the merged filesystem — the H1 rides ours' link-block layout, so a
merged-in title: shows in its H1 only after that update. init/config
register the driver in local git config and write the **/_index.md glob to
.gitattributes in the working tree only — you stage and commit it yourself,
and each clone runs wiki config once to register the driver.
- Leave new-directory index bodies empty during concurrent work. When
sibling branches both create the same new directory, its two
_index.mds
merge add/add with no common ancestor: the generated region resolves
automatically — including the seeded created stamps, which are wiki update
churn on both sides — but body prose authored below *** on both sides
conflicts for hand-union (empty or identical bodies merge clean). Concurrent
cohorts should leave a new directory's index body empty until after the merge
wave, then author it once. The merge driver plants a one-line HTML-comment
hint above such add/add conflict markers naming this convention — delete it as
you resolve.
- A
.wiki/wiki.py hook needs explicit trust. A wiki may ship a
.wiki/wiki.py (a custom Wiki subclass) that runs code with the user's
privileges, so wiki refuses to load an untrusted hook — every command that
resolves the wiki fails, naming the hook and pointing at wiki trust. This is
a security decision for the human: surface the error and let the user run
wiki trust for a wiki they have vetted, rather than running it yourself or
working around the refusal. A hookless wiki needs no trust; trust is recorded
per resolved root in ~/.wiki/settings.json (WIKI_CONFIG_DIR overrides the
config home).
1---2name: wiki3description: Indexed knowledge bases with command-line tools for agents.4disable-model-invocation: true5metadata:6 source: https://skillmd.com/skills/plasma-ai/wiki7---89# Wiki1011A wiki is a structured, indexed knowledge base organized as a folder tree with12`_index.md` files. Each folder has an index that links to its children13(subfolders and pages), and a content section below a `***` delimiter for14user-authored notes.1516Initialize a wiki in the current project and configure integrations:1718- `wiki init` — scaffold a new wiki with a root index19- `wiki config` — install Obsidian plugins and the git merge driver20- `wiki trust` — authorize a wiki to run its `.wiki/wiki.py` hook2122Maintain indexes as files are added and removed:2324- `wiki lint` — validate structure and flag issues25- `wiki update` — sync index links with the filesystem26- `wiki new` — create an indexed folder with an authored desc and content2728Browse structure, search across content, and read entries:2930- `wiki map` — print an indented tree overview31- `wiki search` — rank relevant pages with SQLite FTS532- `wiki match` — match content with regex33- `wiki read` — read a named entry3435## Usage3637Install the CLI from PyPI if it is not already on your `PATH`:3839```bash40pipx install plasma-wiki41```4243(`pip install` or `uv tool install` work too.)4445Then run commands directly:4647```bash48wiki <command> ...49```5051Run `wiki --help` for a list of commands, and `wiki <command> --help` for full52option descriptions.5354## Working at scale5556A wiki is many small, independent pages, so wiki work parallelizes well and is57often too large for one context. Default to sub-agents and dynamic workflows58rather than authoring or auditing page by page yourself:5960- **Fan out sub-agents.** When seeding or expanding a wiki, give each61 independent page — or each source to research and digest — to its own62 sub-agent, then run `wiki update` once to stitch the new pages into the63 indexes. Update adds and repairs index link rows and frontmatter only — it64 never linkifies mentions in page prose, so author `[[...]]` cross-links by65 hand.66- **Drive sweeps with a dynamic workflow.** When auditing, relinking, or67 restructuring an existing wiki, pipeline its pages through a workflow so each68 is read, revised, and verified on its own — slow pages never block fast ones.6970## Conventions7172- **`.wiki/` is the tool's namespace.** Every root carries a `.wiki/` directory73 holding `settings.json` — the file that declares the wiki root; `wiki init`74 writes it and `wiki update` restores a missing one — plus the derived75 word-counts and ranked-search caches and the staged Obsidian config. Never76 author content there; the walk skips dot-directories by construction.77- **Exclusions are configurable.** Beyond the built-ins (dot-paths, symlinks,78 `_index.md`), gitignore-style globs in `exclude.patterns` in79 `.wiki/settings.json` exclude whole subtrees from indexing — never walked,80 scaffolded, or linted, though `wiki read` still serves them. The enclosing git81 repository's ignore rules fence the same way, with no configuration: what the82 repo ignores is not wiki content, so a stray driver output beside tracked83 pages is never adopted, minted an `_index.md`, or linked — delete or fence84 residue rather than letting update sweep it in. A wiki whose own root is85 gitignored is exempt.86- **Name validation is configurable.** By default the wiki rejects only87 structural characters (`/`, `\`, `*`, `[`, `]`, `|`, `#`), a leading dot,88 non-printable names, and the reserved `_index` stem — spaces, dashes, and89 unicode all pass. Stricter rules (e.g. ASCII identifiers) are opt-in per wiki90 via `naming.validate` in `.wiki/settings.json` (seed it at creation with91 `wiki init --settings`); `wiki init` and `wiki lint` enforce whatever policy92 is set.93- **Timestamps are tool-owned and configurable.** `wiki update` writes both94 stamps when a file gains frontmatter, keeps `created:` from then on, and95 rewrites `updated:` on every actual write — never hand-edit them; an edit goes96 undetected unless the value stops parsing under the configured format, which97 `wiki lint` fails. `created`/`updated` default to UTC in `%Y-%m-%dT%H:%M:%SZ`;98 set `timestamp.timezone` (an IANA name) and `timestamp.format` (a strftime99 string) in `.wiki/settings.json` to change them — use `%z` rather than a100 literal `Z` for a non-UTC zone.101- **Names are path-derived; titles are authored.** `wiki update` sets each102 page's `name` and H1 heading to the path-joined name (e.g. `core/design`) so103 names stay consistent with the tree structure — to rename an entry, move its104 file rather than editing `name:`. Any index or page may carry an optional105 authored `title:` frontmatter field, which wins its H1 (`wiki update` keeps106 the line directly under `name:`, and adding frontmatter to a bare page seeds107 `title:` from its authored H1); without one, a hand-edited heading is still108 rewritten to `name`. Unset a title by deleting the line or setting109 `title: null` — update removes it, and lowercase `null` is the only reset110 spelling (`~`/`Null`/`NULL` render literally as the heading). Keep titles on a111 single line, quote a title containing `: `, and prefer plain text.112 `wiki match --field title` matches only authored titles — an unset entry has113 no line to match. Setting `titles.required` to true in `.wiki/settings.json`114 demands a title everywhere: update seeds a `title: null` placeholder on every115 index and page missing one, and lint fails each placeholder until a value is116 authored.117- **Categories are authored and optional.** An index or page may carry a118 `category:` frontmatter field; `wiki update` copies it into the parent index's119 link label as a `[category] name` prefix, and `wiki map --category` filters by120 it. Fresh frontmatter carries no `category:` line — unset one by deleting the121 line or setting `category: null` (update removes the line; as with titles,122 lowercase `null` is the only reset spelling). Keep categories on a single123 line.124- **Frontmatter order is tool-enforced.** `wiki update` keeps every block in125 canonical order — `name`, `title`, `desc`, `category`, `tags`, `sources`,126 `created`, `updated` — moving each field (with its block-scalar body) verbatim127 into its slot. Custom keys are allowed: they keep their relative order below128 the known fields, above the timestamps.129- **Wikilinks stay inside the wiki.** A wikilink (`[[...]]`) must target another130 page in the same wiki. Files outside the wiki (source files, configs, another131 wiki's pages) can be referenced by name or in backticks, but never linked.132- **Lint's output contract.** `wiki lint` prints issues to stdout and soft notes133 to stderr; exit 1 means exactly "issues found" (0 clean, 2 a command error) —134 notes never gate. A script must branch on the exit code or read135 `wiki lint --json` (one JSON document on stdout carrying every finding typed:136 an explicit `issue`/`note` severity, a machine `kind`, and per-kind payload137 fields beside the prose `text`), never classify findings by scraping the prose138 streams: a stderr note is not a blocking issue.139- **Stale wikilinks are soft notes.** A `[[...]]` in index or page prose whose140 target no longer exists draws a stderr note from `wiki lint` without failing141 the run. Broken links in the generated index link block — the rows142 `wiki update` maintains — are hard issues until the next update prunes them143 (each removal announced, with the cause named when the target is merely144 excluded rather than deleted), as is a prose wikilink naming a folder rather145 than the folder's index page: link `[[folder/_index]]`, never `[[folder]]`.146- **Descriptions end in a period.** `wiki lint` fails a `desc` (or an authored147 link description) that lacks a trailing period; the seeded `...` placeholder148 only draws a soft note. Author the desc in the child page's frontmatter —149 `wiki update` copies it onto the parent index's link line. A desc containing150 `: ` must be YAML-quoted; surrounding quotes are stripped when the value is151 read. Never hand-wrap a desc mid-word or onto a list-marker start — let the152 block scalar carry the breaks; lint fails the wrap artifacts (a hyphen dangle,153 a phantom list item).154- **Fill in auto-created index descs.** `wiki update` creates a missing155 `_index.md` for every new directory with a `desc: ...` placeholder and156 announces the batch in its condensed summary157 (`Created N new indexes (fill in their descs)`; run with `--full` for the158 per-path `New index:` lines). Fill in the desc right after the update — lint159 soft-notes the placeholder until you do. For a deliberate creation (an160 adoption ceremony's mechanical step), prefer161 `wiki new <folder> --desc ... --content ...`: it requires both authored inputs162 — refusing blanks and placeholders outright, descs are never auto-stubbed —163 and wires the folder's rows and the parent's new row in the same pass, so the164 adoption lands lint-complete. The wiring is a scoped `wiki update` of the165 parent subtree (the whole wiki for a top-level folder), so pending maintenance166 in that scope — adoptions, prunes — lands in the same run.167- **Bare pages are adopted loudly.** A page with no frontmatter gains it on the168 next `wiki update` — with `title:` seeded from its authored H1, while a page169 with no H1 gains the path-joined heading in its body, never a seeded title —170 and each adoption is announced (`Adopted N bare pages (frontmatter added)` in171 the condensed summary; `--full` prints the per-page lines). Until then172 `wiki lint` names the page as a hard issue173 (`Bare page (no frontmatter); update will adopt it`) alongside the adoption174 diff.175- **Suppress lint locally with a `no-lint` region.** A page that must display176 otherwise-flagged content (sample conflict markers, stale link examples) wraps177 those lines in `<!-- start: no-lint -->` ... `<!-- end: no-lint -->`, which178 silences the positional rules — hard issues and soft notes alike — for just179 that span. Regions never affect file-level checks, and a dangling or nested180 marker is itself a hard lint issue.181- **Give markdown formatters the wiki plugin.** The `***` delimiter and182 `[[wikilinks]]` are load-bearing syntax; mdformat/prettier-style hooks rewrite183 `***` to `---` and escape the brackets, demoting the generated link block to184 plain text. `wiki update` repairs a mangled index and `wiki lint` names the185 damage signatures (escaped wikilinks, a thematic break standing where `***`186 belongs), but don't rely on the repair: for mdformat add the `mdformat-wiki`187 plugin (under pre-commit, `additional_dependencies: [mdformat-wiki]` on the188 hook, dropping a coexisting `mdformat-frontmatter` — both register a189 frontmatter renderer and whichever is discovered first wins), which makes wiki190 faces round-trip byte-identically; for formatters with no plugin lane (e.g.191 prettier) exclude the wiki root instead (`wiki/` in `.prettierignore`).192- **The git merge driver resolves only the generated region.** For `_index.md`193 files it normalizes the regenerated `name`/`updated` keys to *ours* (plus194 `created` on an add/add merge, where both sides seeded it), resolves the link195 block to the union of both sides' rows — ours' layout wins and rows present196 only in theirs ride over with their desc continuations, appended above the197 closing `***`, so a merge never drops one side's additions — and three-way198 merges everything authored — the remaining frontmatter fields199 (`title`/`desc`/`created`/`category`/`tags`/`sources`) and the user content200 below `***` — which can still conflict for hand-resolution. A side missing its201 `***` entirely (formatter damage) can't be split into regions, so it conflicts202 whole-file with a hint comment naming the repair — restore the `***` on that203 branch (`wiki update` does it), then redo the merge. Run `wiki update` after a204 merge to re-sort the link rows and prune any carried row whose target is gone205 from the merged filesystem — the H1 rides ours' link-block layout, so a206 merged-in `title:` shows in its H1 only after that update. `init`/`config`207 register the driver in local git config and write the `**/_index.md` glob to208 `.gitattributes` in the working tree only — you stage and commit it yourself,209 and each clone runs `wiki config` once to register the driver.210- **Leave new-directory index bodies empty during concurrent work.** When211 sibling branches both create the same new directory, its two `_index.md`s212 merge add/add with no common ancestor: the generated region resolves213 automatically — including the seeded `created` stamps, which are `wiki update`214 churn on both sides — but body prose authored below `***` on both sides215 conflicts for hand-union (empty or identical bodies merge clean). Concurrent216 cohorts should leave a new directory's index body empty until after the merge217 wave, then author it once. The merge driver plants a one-line HTML-comment218 hint above such add/add conflict markers naming this convention — delete it as219 you resolve.220- **A `.wiki/wiki.py` hook needs explicit trust.** A wiki may ship a221 `.wiki/wiki.py` (a custom `Wiki` subclass) that runs code with the user's222 privileges, so `wiki` refuses to load an untrusted hook — every command that223 resolves the wiki fails, naming the hook and pointing at `wiki trust`. This is224 a security decision for the human: surface the error and let the user run225 `wiki trust` for a wiki they have vetted, rather than running it yourself or226 working around the refusal. A hookless wiki needs no trust; trust is recorded227 per resolved root in `~/.wiki/settings.json` (`WIKI_CONFIG_DIR` overrides the228 config home).