Fidus

# Why it exists

Documentation goes stale for an ordinary reason: code changes through pull requests, and nobody’s job is to walk back through the docs after every merge. The README was accurate at launch, and a few months later it describes a system that no longer exists. A one-off generated snapshot is wrong again just as quickly.

I wanted documentation that reads like a textbook, with fundamentals first and advanced topics after them, and that keeps itself current the way a careful colleague would: by opening a pull request that a person reads and merges.

# How it works

Each night Fidus looks at the pull requests merged into your source repositories since its last run, and opens one rolling pull request against a separate docs repository.

• Map. Every changed file is matched to chapters through sources globs in a plain YAML outline. Files no glob covers are placed with a quick model call, and anything still unplaced is listed for a human instead of being dropped.
• Write. Each affected chapter gets its own agent session. The agent reads the pull requests, explores a fresh copy of the latest code, and makes the smallest correct edit, citing the files it relied on.
• Check. Every edit is validated: frontmatter, links between chapters, cited files, protected blocks, and no invented examples. Chapters run after their prerequisites, and when a fundamentals chapter renames a concept, the chapters built on it get a consistency pass.
• Publish. Everything lands in one pull request on a fidus/sync branch, with a table of what changed, why, and which source pull request caused it. Quiet nights open nothing.
• Audit. Once a week, every chapter is re-verified against the current code.

It runs as a CLI (pipx install fidus) plus a reusable GitHub Action on a cron schedule in the docs repo, with no hosted server. It works with Anthropic Claude, Google Gemini and any OpenAI-compatible endpoint, including open-weight models on Ollama, vLLM or OpenRouter. You bring your own key.

# Design decisions

• A person merges everything. Nothing reaches the default branch until someone reviews it, and closing the pull request means “skip these changes”.
• The structure is yours. The book’s outline is a YAML file that nightly runs never add to, remove from or reorder. Fidus writes the chapters and suggests restructuring, and you decide.
• State travels with the pull request. Progress is committed on the sync branch, so it only moves forward when you merge. There is no database and no server to keep alive.
• Edit, don’t rewrite. Lines people add to a chapter are found with git blame and preserved, and anything inside <!-- fidus:keep --> is never touched.
• Least privilege. The agent can read your source code and write only the chapter it is working on. It has no shell and no network tools, pull request text and diffs are treated as data rather than instructions, and every write is scanned for secrets.
• Thin model adapters of its own. Three provider families are supported without a wrapper library. Models that stumble over tool calls fall back automatically to a plain JSON protocol, which is what makes smaller open-weight models usable.
• Tested by simulation. A simulator runs the real CLI against a local stand-in for GitHub over eight scripted days: features shipping, a reviewer away, hand edits, a merge conflict, a rejected pull request, a new chapter and the weekly audit. A separate accuracy benchmark has a judge model check each chapter’s claims against the code it cites.

# Status

Alpha. Version 0.1.0 was released on 29 September 2026 on PyPI and as a GitHub Action, under the MIT license. It is young, so expect rough edges, and issues are welcome.