What your agent gets back

One question, one call. wiki0 returns the best sections, one per document and five by default, each with the file and lines it came from. This is the first result for our question, from this repo's docs.

wiki0 search "index in the project folder"

{
  "citation": "wiki/decisions/0006-index-in-user-cache.md:9-16",
  "breadcrumb": [
    "Index in the user cache",
    "Decision"
  ],
  "status": "accepted",
  "doc_type": "decision",
  "date": "2026-10-14",
  "snippet": "…the index lives in the user cache, keyed per worktree: `~/.cache/wiki0/<folder>-<hash>/index.db`. Nothing is written to the project. A project…",
  "score": 0.9544,
  "superseded_by": null
}

2 wiki/reference/storage.md:7-16
3 wiki/index.md:30-43
4 packages/cli/README.md:12-37
5 wiki/decisions/0002-index-in-project-folder.md:9-14 superseded by 0006-index-in-user-cache.md

Trimmed to the fields explained here. A full result has more, such as match positions, the score's parts and a heading anchor.

It indexes the docs you already have

wiki0 index splits each Markdown file at its headings into sections that keep their exact line ranges. Frontmatter such as status and supersedes becomes data search can use. Nothing is written to your repo; the index lives in your user cache.

wiki/decisions/0006-index-in-user-cache.md

1 ---
2 title: Index in the user cache
3 type: decision
4 status: accepted
5 supersedes: [wiki/decisions/0002-index-in-project-folder.md]
6 date: 2026-10-14
7 ---

type: decision
status: accepted
supersedes: 0002

:9-16 Decision, 72 tokens

9 # Index in the user cache
10
11 ## Decision
12
13 By default the index lives in the user cache, keyed per worktree:
14 `~/.cache/wiki0/<folder>-<hash>/index.db`. Nothing is written to the
15 project. A project can opt into `.wiki0/index.db` with `wiki0.toml`.
16 Details: [Storage](../reference/storage.md).

:18-25 Why, 71 tokens

18 ## Why
19
20 - wiki0 has to work on repos it does not own without adding files or
21 editing `.gitignore`.
22 - The index is a rebuildable cache, which is what the cache directory
23 is for.
24 - Keying by worktree keeps branches in separate worktrees from sharing
25 an index of different files.

:27-32 Consequences, 67 tokens

27 ## Consequences
28
29 - The index is invisible, so `wiki0 status` prints its path.
30 - The CLI and an MCP server can run with different environments and
31 resolve different paths; `WIKI0_INDEX` pins one file for both.
32 - Moving a repo leaves its old index behind in the cache.

Every section of the 12 largest documents in this repo, as tall as its tokens. Search returns one of these, not the whole row.

Current docs rank first

Text match alone puts the replaced decision first: its title is the question, word for word. wiki0 then weighs each result by its status, its type and how many docs link to it. A superseded doc keeps 30% of its score and points to the doc that replaced it.

wiki0 search "index in the project folder"

Select a result to see why it ranks where it does.

Agents read the cited lines

Each result is a citation: wiki/decisions/0006-index-in-user-cache.md:9-16. wiki0 show returns exactly those lines from the current file, within a token budget, and says where to read next when a section runs long. You can check every quote against the file.

1 ---
2 title: Index in the user cache
3 type: decision
4 status: accepted
5 supersedes: [wiki/decisions/0002-index-in-project-folder.md]
6 date: 2026-10-14
7 ---
8
9 # Index in the user cache
10
11 ## Decision
12
13 By default the index lives in the user cache, keyed per worktree:
14 `~/.cache/wiki0/<folder>-<hash>/index.db`. Nothing is written to the
15 project. A project can opt into `.wiki0/index.db` with `wiki0.toml`.
16 Details: [Storage](../reference/storage.md).
17
18 ## Why
19
20 - wiki0 has to work on repos it does not own without adding files or
21 editing `.gitignore`.
22 - The index is a rebuildable cache, which is what the cache directory
23 is for.
24 - Keying by worktree keeps branches in separate worktrees from sharing
25 an index of different files.
26
27 ## Consequences
28
29 - The index is invisible, so `wiki0 status` prints its path.
30 - The CLI and an MCP server can run with different environments and
31 resolve different paths; `WIKI0_INDEX` pins one file for both.
32 - Moving a repo leaves its old index behind in the cache.

wiki0 show wiki/decisions/0006-index-in-user-cache.md:9-16

Source: wiki/decisions/0006-index-in-user-cache.md:9-16

# Index in the user cache

## Decision

By default the index lives in the user cache, keyed per worktree:
`~/.cache/wiki0/<folder>-<hash>/index.db`. Nothing is written to the
project. A project can opt into `.wiki0/index.db` with `wiki0.toml`.
Details: [Storage](../reference/storage.md).

80 tokens, read from the current file

Links resolve, and lint finds the broken ones

wiki0 resolves Markdown links and [[wikilinks]], down to the heading. That's how the replaced decision points to the one that replaced it, and why docs that others link to rank a little higher.

32 documents

45 links

0 broken

This repo's docs, drawn outward from the current decision.

wiki0 lint reports every link that points nowhere with its file and line, and suggests the heading you probably meant. This repo's docs have no broken links, so here it is on a two-file example.

wiki0 lint

# Runbook

If a release breaks, follow [roll back](deploys.md#roll-back).

Access is set up in [[onboarding]].

missing-heading runbook.md:3 did you mean #rolling-back?
missing-file runbook.md:5 no such file

“Show me the docs”

To read what your agent cites, ask it to show you. It runs wiki0 ui, which starts a local docs browser and prints its address. Every doc is rendered with working links, search opens a result at its cited lines, and the health area shows the index, lint and the link graph.

Use pnpx @wiki0/cli and show me the docs.

$ pnpx @wiki0/cli ui http://127.0.0.1:4100/#token=…

Use it

Ask your coding agent. It runs wiki0 for you, reads the cited section and tells you where it came from.

Use pnpx @wiki0/cli to find where we decided how deploys work.
Use pnpx @wiki0/cli and show me the docs.
Use pnpx @wiki0/cli lint and fix the broken links in our docs.

# Index the project docs
npx @wiki0/cli index

# One cited section per document
npx @wiki0/cli search "how do deploys work"

# Read a cited section
npx @wiki0/cli show docs/deploys.md:12-40

# Broken links and anchors
npx @wiki0/cli lint

# Open the local docs browser
npx @wiki0/cli ui

For MCP clients, add @wiki0/mcp. The agent gets search, show, lint, index and the link graph as tools.

{
  "mcpServers": {
    "wiki0": {
      "command": "npx",
      "args": [
        "-y",
        "@wiki0/mcp"
      ]
    }
  }
}

Never calls an LLM: Search is SQLite full-text search with ranking rules you can read.
Never changes your files: It reads your docs. The index lives in your user cache.
No folder layout to adopt: It works with the Markdown you already have. Frontmatter is optional.
Runs on your machine: The docs browser listens on 127.0.0.1 and needs a token.

Docs search for your coding agent.

Use it