Indexion Wiki

# indexion wiki

indexion's wiki system maintains a knowledge base at `.indexion/wiki/` as a collection of
Markdown files governed by a `wiki.json` manifest.

## A wiki page is not just a `.md` file

A wiki page consists of **four synchronized artifacts**:

| Artifact | File | Updated by |
|----------|------|------------|
| Page content | `<id>.md` | `wiki pages add`, `wiki pages update` |
| Manifest entry | `wiki.json` | `wiki pages add`, `wiki pages update` |
| Search index | `vectors.db`, `search-sections.json`, `tfidf-vocabulary.json` | `wiki pages update`, `wiki index build --full` |
| Audit log | `log.json` | Every wiki-modifying command |

**`wiki pages update` updates all four at once.** Editing the `.md` file directly updates
only the first. The other three become stale — search returns old results, the manifest
carries wrong provenance, and the log has no record of the change.

If you edit a `.md` directly (e.g. via `Edit` tool), you **must** immediately follow up:

```bash
indexion wiki pages update \
  --id=<page-id> \
  --content=.indexion/wiki/<page-id>.md \
  --sources="<comma-separated sources from wiki.json>" \
  --provenance=synthesized \
  --actor="agent:claude" \
  --wiki-dir=.indexion/wiki
```

Every wiki page also carries two provenance fields in the manifest:
- `provenance`: `"extracted"` | `"synthesized"` | `"manual"`
- `last_actor`: `"indexion"` | `"agent:<name>"` | `"user"`

## Command Structure

```
indexion wiki
  ├── pages
  │   ├── plan    -- propose page structure (init-like)
  │   ├── add     -- create a new page (writes .md + manifest + index + log)
  │   ├── update  -- update an existing page (writes .md + manifest + index + log)
  │   └── ingest  -- detect stale pages by hashing sources
  ├── index
  │   └── build   -- rebuild index.md (and optionally vectors.db)
  ├── lint        -- structural integrity checks (no LLM needed)
  ├── export      -- export to GitHub/GitLab wiki format
  ├── import      -- import from GitHub/GitLab wiki format
  └── log         -- operation audit trail
```

## Navigating the Wiki (as an agent)

Before reading individual pages, start with the index:

```bash
# Generate or regenerate index.md — the entry point for navigation
indexion wiki index build --wiki-dir=.indexion/wiki

# Then read it
cat .indexion/wiki/index.md
```

`index.md` lists pages by category and identifies **hub pages** (most-linked pages).
Hub pages are the best starting points for understanding an unfamiliar codebase.

## Writing a New Page

```bash
# 1. Write content to a temp file
cat > /tmp/my-page.md << 'EOF'
# My Page Title
...content...
EOF

# 2. Register it — this writes .md, updates wiki.json, updates search index, appends log
indexion wiki pages add \
  --id=my-page \
  --title="My Page Title" \
  --content=/tmp/my-page.md \
  --sources="src/my-module/" \
  --provenance=synthesized \
  --actor="agent:claude" \
  --wiki-dir=.indexion/wiki
```

The `--sources` field links the page to source files for change tracking.
Always specify it — pages without sources are invisible to `wiki pages ingest`.

## Updating an Existing Page

```bash
# 1. Write new content to a temp file
cat > /tmp/updated.md << 'EOF'
# Updated Page
...new content...
EOF

# 2. Update — this overwrites .md, updates wiki.json metadata,
#    incrementally updates the search index, and appends to log.json
indexion wiki pages update \
  --id=existing-page \
  --content=/tmp/updated.md \
  --sources="src/my-module/,src/other/" \
  --provenance=synthesized \
  --actor="agent:claude" \
  --wiki-dir=.indexion/wiki
```

Expected output: `Updated page 'existing-page' (search index updated)`

## Detecting What Needs Updating

```bash
# Find pages