wiki

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# 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`:

```bash
pipx install plasma-wiki
```

(`pip install` or `uv tool install` work too.)

Then run commands directly:

```bash
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, root-relative inside the wiki.
- **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 and root
  `_index.md` are both 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. A name is checked as a link carries it: a page by its stem, any other
  file by its full name, extension included. So `identifier` rejects every
  non-Markdown file with an extension (`data.json`, `main.py`) unless
  `naming.allow` contains `.`, and a strict wiki that keeps data files or
  scripts beside its pages sets `"allow": "."`.
- **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 — and, inside a git repository, on a
  tracked file edited since its last commit, so run `wiki update` after a hand
  edit rather than restamping by hand (`wiki lint` does not flag the pending
  restamp; `wiki update --check` does). Never hand-edit a stamp; 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

From plasma-ai/wiki, Apache-2.0.