---
category: reference
tags: [meta]
last_updated: 2026-03-12
confidence: high
---

# Wiki Usage Guide for Agents

## What this is

This wiki tracks the development of wikibot.io — a serverless wiki-as-a-service platform. Both human developers and Claude agents (phase managers) read and write to this wiki. It serves as the persistent state store across agent sessions, tracking what's been built, what decisions were made, and what's next.

The wiki is backed by Git. Every edit is a commit with full version history.

## Available tools

You have 12 MCP tools, prefixed with "dev-wiki" in Claude Code.

### Reading

**`read_note(path)`** — Read a single page. Returns frontmatter, content, and WikiLinks (outgoing and incoming). Use `revision` to read a historical version.

### Navigating

**`list_notes()`** — List all pages. Returns name, path, category, tags, word count, and last updated date. All filters are optional and compose with AND: `prefix`, `category`, `tag`, `updated_since`.

**`get_links(path)`** — Get incoming and outgoing WikiLinks for a page.

**`get_recent_changes(limit=20)`** — Git changelog across all pages.

**`find_orphaned_notes()`** — Pages not linked from any index page.

### Searching

**`search_notes(query)`** — Full-text keyword search.

**`semantic_search(query, n=5)`** — Conceptual similarity search.

### Writing

**`write_note(path, content, commit_message, revision?)`** — Create or overwrite a page. Omit `revision` for new pages. Supply `revision` from `read_note` when updating (optimistic locking).

**`edit_note(path, revision, old_string, new_string, commit_message?)`** — Targeted find-and-replace within a page. `old_string` must match exactly once.

**`rename_note(path, new_path, commit_message?)`** — Rename/move a page. Updates all incoming WikiLinks atomically.

**`delete_note(path, commit_message)`** — Delete a page.

### History

**`get_history(path, limit=10)`** — Revision history for a page.

## Session start protocol (for phase managers)

At the beginning of every session:

1. **`read_note("Home")`** — Load the master index. See what exists.
2. **`read_note("Dev/Phase N Status")`** — Resume state from the last session.
3. **`get_recent_changes(limit=10)`** — See if the human made changes since last session.
4. Load the relevant spec pages for your phase (Agent Conventions, Task Graph).
5. Proceed with work.

## Page conventions

### Frontmatter

Every page should have YAML frontmatter:

```yaml
---
category: spec | dev | reference | index | meta
tags: [relevant, tags]
last_updated: 2026-03-12
confidence: high
---
```

**Categories for this wiki:**
- `spec` — Design specifications and implementation guides
- `dev` — Development status tracking and decision logs
- `reference` — Project documents (PRDs, external references)
- `index` — The Home page and navigation pages
- `meta` — Wiki usage and conventions

### Page organization

```
Home                          — master index
Specs/                        — implementation specs
  Agent Conventions           — how agents work
  Task Graph                  — work units and dependencies
  Phase Gates                 — exit criteria per phase
Docs/                         — project documents
  PRD                         — serverless SaaS PRD
  Original PRD                — single-tenant system PRD
Dev/                          — development tracking
  Phase N Status              — living status per phase
  Phase N Summary             — final summary per phase
  Decision Log                — architectural decisions
Meta/                         — wiki meta
  Wiki Usage Guide            — this page
```

### Cross-references

Use WikiLinks: `[[Page Path]]` or `[[Page Path|display text]]`. Target path comes first, display text second.

### Commit messages

Format: `[source] action: description`

Sources:
- `[system]` — automated/setup operations
- `[P0]` through `[P4]` — phase-specific work
- `[manager]` — phase manager status updates

## Dev tracking conventions

### Status pages (`Dev/Phase N Status`)

Living document updated each session. Contains:
- Current state (tasks complete, in progress, blocked)
- Active decisions or blockers
- Next parallelism group to execute

### Summary pages (`Dev/Phase N Summary`)

Written once when the phase completes:
- What was implemented (repo/branch references)
- Decisions made and rationale
- Deviations from the task graph
- New tasks discovered
- Lessons learned

### Decision log (`Dev/Decision Log`)

Append-only. Each entry: date, decision, context, alternatives considered, rationale.

## Things to watch out for

**Optimistic locking.** Always read before writing. Supply the `revision` SHA when updating. If someone else edited since your read, you'll get a conflict — re-read and retry.

**Choose `edit_note` vs `write_note` carefully.** `edit_note` for small changes. `write_note` for structural rewrites. For multi-part updates, multiple `edit_note` calls are safer.

**Keep Home current.** When you create a new page, update Home in the same session.

**Semantic search may lag** web UI edits by up to 60 seconds. Full-text `search_notes` is always current.

## Quick reference

| I want to... | Use... |
|---|---|
| Start a session | `read_note("Home")` then `read_note("Dev/Phase N Status")` |
| Find a page by topic | `semantic_search(query="...")` |
| Find a page by keyword | `search_notes(query="...")` |
| See what changed recently | `get_recent_changes(limit=10)` |
| See all specs | `list_notes(prefix="Specs/")` |
| See dev status | `list_notes(prefix="Dev/")` |
| Create a new page | `write_note(path, content, commit_message)` |
| Update an existing page | `read_note` then `write_note` with revision SHA |
| Make a small targeted edit | `edit_note(path, revision, old_string, new_string)` |
| Check a page's history | `get_history(path, limit=10)` |
| Find unindexed pages | `find_orphaned_notes()` |