refactoring a wiki

---

title: Refactoring a wiki type: guide

Refactoring a wiki

Renaming and reorganizing a wiki used to be risky — file-rename plus create-elsewhere left orphan pages and dead concepts/wikilinks. agents/mcp-tools makes it atomic.

Renaming a single page

move_page from="projects/foo" to="projects/bar"

What happens:

1. The file is renamed on disk.
2. The pages row is updated.
3. The links rows where source = "projects/foo" are rewritten to source = "projects/bar".
4. The concepts/backlinks (links rows where target = "projects/foo") are intentionally not rewritten — those rows reflect [[projects/foo]] text in other pages' source markdown. Rewriting them would make the index lie.

If you want those updates too, you have to do them yourself — search_pages "projects/foo" and update each source.

Bulk reorg

Move every page under one prefix:

# pseudocode
for page in list_pages(prefix="old/"):
    new_path = "new/" + page.path[len("old/"):]
    move_page(from=page.path, to=new_path)

Agents can do this in one tool-call sequence. Safe to interrupt — each move is atomic.

Why this isn't just mv

A naive shell rename:

mv ~/.mind-map/wiki/old.md ~/.mind-map/wiki/new.md

…works for the file, but on the next architecture/wiki-engine the engine will:

1. Notice old.md is gone and drop its index row.
2. Notice new.md appeared and add an index row.
3. Update links rows where source = "old" to source = "new" ✓
4. Leave links rows where target = "old" alone — but now those target a deleted page.

move_page does the same plus preserves the link table cleanly.

See also

• concepts/wikilinks
• concepts/backlinks
• agents/mcp-tools