Catryna Wikinelli

A local-first code wiki that your AI coding agent writes and your team reads — docs live as MDX files in a .docs/ folder, versioned with your code.

Part of Sothis, the local-first suite for running a fleet of AI coding agents on one repo (suite repo). Catryna is its documentation layer.

Every project accumulates knowledge that lives nowhere: why the auth flow works the way it does, which module owns what, the diagram someone drew once on a whiteboard. Wikis in Notion or Confluence drift out of date because updating them is a separate chore from writing code. Catryna fixes the incentive problem: your coding agent (Claude Code, or anything that speaks MCP) creates and updates the docs as part of the coding session, and because the docs are plain files in your repo, the agent also reads them back before touching code — so the knowledge actually gets used, and stale docs get caught in review like any other diff.

How it works

• Docs are .mdx files with YAML frontmatter in .docs/ at your project root — no database, no cloud, git-versioned with your code.
• Agents read docs directly as files (Read .docs/backend/storage.mdx) — no tool round-trip needed.
• Agents write docs via MCP tools (create_doc, update_doc, search_docs, coverage reports, diagrams).
• Catryna tells you which docs the code has outgrown. Each doc anchors to the source files it describes; catryna drift diffs those files since the doc was last verified and reports exactly which docs are now contradicted — then hands an agent the doc plus the diffs so it can propose the fix.
• Humans browse the same docs in a local React viewer at http://localhost:1307, with search, Mermaid/React Flow diagrams, whiteboards, and a doc-coverage report.

Quickstart

Prerequisites: Bun v1.0+ and Git.

Claude Code plugin (recommended)

Inside Claude Code:

/plugin marketplace add Davidb3l/Catryna-Wikinelli
/plugin install catryna@catryna-wikinelli

This registers the MCP server (it installs its own dependencies on first run and stores docs in the .docs/ folder of whichever project you're working in), an Agent Skill that teaches Claude to search .docs/ before coding and update docs after changing code, and a /catryna:viewer command that starts the human viewer.

Restart Claude Code, then run /mcp — you should see catryna connected.

Manual install (other MCP clients / development)

git clone https://github.com/Davidb3l/Catryna-Wikinelli.git
cd Catryna-Wikinelli
bun install

Register the server with your MCP client. For Claude Code, add .mcp.json to your project root (or the same block to ~/.claude.json for all projects):

{
  "mcpServers": {
    "catryna": {
      "command": "bun",
      "args": ["run", "/path/to/Catryna-Wikinelli/src/index.ts"]
    }
  }
}

The server stores docs in .docs/ under the directory it's launched from (your project), creating it on first write.

Human viewer

cd Catryna-Wikinelli/frontend
bun install
bun run dev   # http://localhost:1307

The viewer scans for sibling projects with .docs/ folders (set PROJECTS_ROOT to point it elsewhere) and lets you switch between them.

What a session looks like

> search_docs query="storage"
  { results: [{ file: ".docs/backend/storage.mdx", title: "Storage Layer",
    snippet: "...file-based storage resolves .docs/ from cwd..." }], count: 1 }

> Read .docs/backend/storage.mdx        # plain file read, no MCP call

  ... make code changes ...

> update_doc path="backend/storage" content=[...]
  { success: true, file: ".docs/backend/storage.mdx" }

> get_doc_coverage
  { documentedModules: 12, totalModules: 18, coveragePercent: 67,
    undocumentedFiles: ["src/tools/diagrams.ts", ...] }

Each doc is an MDX file your whole team can read, diff, and edit by hand:

---
title: "Storage Layer"
path: "backend/storage"
tags: ["backend"]
relatedFiles: ["src/storage.ts"]
---

# Storage Layer
Docs are written as blocks (text, code, mermaid, react-flow, whiteboard, ...)

Keeping docs true

Generating docs is solved; keeping them correct isn't. A doc that contradicts the code is worse than no doc, because an agent will believe it.

Every doc records the commit it was last verified against. catryna drift compares each doc's anchored source files against that baseline:

catryna drift                 # clean / drifted / broken / unverified — exit 3 if anything is wrong
catryna repair <path>         # that doc's content + the git diff of each changed anchor
catryna verify <path>         # re-baseline once the doc is accurate again

• broken — an anchored file was deleted or renamed away (highest severity).
• drifted — anchored code changed since the doc was verified.
• Anchors can be whole files, or precise: {"file":"src/auth.ts","symbol":"login"} so only changes to that symbol count.
• Exits 3 on drift, so it drops straight into CI. A Stop hook also reminds you at the end of any session that left docs drifted.
• Adopting an existing corpus that was never verified? Give it a starting point: catryna drift --since 2026-02-18. See .docs/guides/drift-adoption-playbook.mdx.

If Hayvenhurst is running, drift uses its code graph for symbol-level precision; otherwise it falls back to plain git-diff. Zero dependencies either way.

MCP tools

Tool	Description
create_doc / update_doc / delete_doc	Write docs as .docs/{path}.mdx
get_doc / list_docs	Fetch one doc as blocks / browse and filter all docs
search_docs	Full-text search, returns paths + snippets
check_drift / verify_doc / propose_doc_repair	Find drifted docs, re-baseline them, get repair context
create_mermaid_diagram / create_diagram	Mermaid or React Flow architecture diagrams
create_whiteboard	Freeform whiteboard canvas
get_doc_coverage / get_undocumented_modules	Which source files have docs, which don't

The catryna CLI exposes the same drift workflow plus catryna doctor (health and suite discovery) and catryna consume — all with --json for scripting.

Docs

This repo documents itself with Catryna — browse .docs/ for real examples:

• .docs/getting-started.mdx — intro walkthrough
• .docs/architecture/overview.mdx — system architecture
• .docs/backend/ — MCP server, storage, and tools internals
• skills/catryna/SKILL.md — the Agent Skill shipped with the plugin
• CLAUDE.md — block types reference and troubleshooting

Platform support

Tested on macOS and Windows. .docs/ travels between machines, so anchor paths always use forward slashes (git's format on every OS) and CRLF checkouts are handled on read. Linux is expected to work and is on the roadmap for official support and testing.

Status & license

Early-stage (v1.3.0) and moving fast; issues and PRs welcome. MIT licensed.