Wiki Conventions

A wiki that nobody prunes becomes a wiki that nobody trusts, and a wiki nobody trusts is worse than no wiki — agents read it, believe it, and act on stale information with full confidence.

These are the conventions that keep that from happening.

Paths

Lowercase, hyphen-separated, / for hierarchy, no .md extension:

concepts/llm-wiki
architecture/multi-tenancy
decisions/why-postgres
troubleshooting/mcp-connection

The first segment is a category. A conventional set:

Adopt whatever taxonomy fits, but adopt one. Consistent prefixes make wiki_listPages({prefix: "..."}) a precise instrument instead of a guess.

There is no rename operation. Writing to a new path creates a new page, so a rename is really write-then-delete — and every link to the old path is dead until you fix it. Get the path right the first time where you can, and run wiki_lint when you can't.

Wikilinks

[[architecture/auth]]
[[architecture/auth|how we handle tokens]]

The second form lets the prose read naturally while still pointing at a real path. Use it — sentences built around raw paths are painful to read.

What does and doesn't become a graph edge:

• Links inside inline code or fenced blocks are ignored, so documenting the syntax doesn't pollute the graph
• Duplicates collapse; first occurrence wins
• Self-links are dropped
• Targets need not exist. A link to a page you haven't written yet is a redlink, and wiki_lint will list it

That last point is a feature. Linking to the page you wish existed turns lint into a to-do list that writes itself.

Link generously. The graph powers /graph, the backlinks in the page gutter, and orphan detection. An unlinked page is one nobody — human or agent — will stumble across.

Diagrams

Use mermaid, in a fenced mermaid block. It renders in the app, adapts to the active theme, and stays diffable as text:

graph TD
  Client -->|bearer| API
  API --> Postgres
  API --> S3

Page scope

One topic per page.

The test: can you write a one-sentence description of the page that doesn't contain "and"? If not, it's two pages. Narrow pages are easier to keep accurate, easier to link precisely, and much less likely to end up half-true — the state where half the content is current and half is two months stale, with nothing marking which is which.

Structure inside a page: title as h1, sections as h2, and the summary near the top. Agents frequently read only the first part of a long page, so front-load the conclusion rather than building to it.

Write decisions, not descriptions

The highest-value page records a choice and its reasoning: we chose X over Y because Z, and we'd revisit it if W changed.

That survives contact with the future. A page that restates what the code already says goes stale the moment the code moves, and it competes with the code for authority while losing.

The read-before-write loop

wiki_updatePage replaces the entire page. No merge, no patch.

wiki_getPage → reconcile → wiki_updatePage

Skipping the read silently destroys whatever you didn't know was there. When new information contradicts what's on the page, reconcile it explicitly — say what changed and why — rather than quietly overwriting. The contradiction is often the most valuable thing on the page.

Maintenance

• wiki_lint after batches of edits. Target zero dead links. A few orphans are fine; a lot means your index and cross-links have stopped keeping up.
• wiki_rebuildGraph after structural churn — bulk renames, or deleting a heavily-linked page. Normal edits keep the graph current on their own, so this is a repair tool.
• Keep the index current. It's how agents orient. Stale index, duplicate pages.
• Prefer merging to deleting. Two thin overlapping pages should become one good page, not one survivor and one casualty.
• Log meaningful work with wiki_appendLog. The log captures intent, which page diffs never do.

Anti-patterns