Codocia

Keep docs true as code changes.

Codocia is a docs-maintenance skill and documentation drift checker for AI coding agents such as Codex, Claude Code, OpenCode, and similar terminal agent tools.

The problem: code changes quickly, but docs usually lag behind. Codocia makes that drift visible by binding Markdown pages to the code files they explain and giving coding agents a repeatable loop for generating or updating docs from code changes.

Codocia does not generate prose from source comments. The docs/ directory is the source of truth. Codocia records which files each page covers, snapshots their content hashes, and later checks whether those files changed.

Quickstart

Create the docs workspace:

codocia init

Write a Markdown page with covers metadata:

---
title: Runtime
covers:
  - crates/runtime/**
  - python/skrun/runtime.py
---

# Runtime

This page explains the runtime module.

Record the current code snapshot:

codocia snapshot

Review the generated repository policy in codocia.md, then commit the docs and Codocia changes:

git add codocia.md docs
git commit -m "docs: add runtime coverage"

Later, after code changes, check whether docs are stale:

codocia check --base main

How It Works

Each docs page declares the code paths it covers:

covers:
  - crates/runtime/**
  - python/skrun/runtime.py

codocia snapshot expands those patterns, hashes the matched files, and writes the result to docs/.codocia-snapshot.json:

{
  "commit": "abc123",
  "docs": {
    "docs/runtime.md": {
      "covers": ["crates/runtime/**", "python/skrun/runtime.py"],
      "files": {
        "crates/runtime/src/lib.rs": "9f2a...",
        "python/skrun/runtime.py": "81bc..."
      }
    }
  }
}

codocia check compares the stored hashes in docs/.codocia-snapshot.json with the current files. If a covered file changed, the page is stale.

When --base main is provided, Codocia also reads git diff information from:

• committed changes in main...HEAD;
• staged changes;
• unstaged changes.

That lets Codocia report changed source files that have no docs coverage and include diff excerpts for files that need documentation review.

Commands

codocia init

Creates codocia.md and docs/index.md if they do not exist. Existing files are not overwritten.

codocia.md is an agent-readable documentation policy with the repository's default density, metrics, and page defaults. The code keeps the runtime defaults in the CLI and library.

codocia
codocia skill

Prints the Codocia docs skill from SKILL.md to stdout. This is intended for AI agents that need the operating rules without Codocia writing a local skill folder.

codocia snapshot

Updates docs/.codocia-snapshot.json for every docs page with covers. It does not rewrite Markdown pages.

codocia check --base main

Checks documentation coverage and freshness. It exits with a non-zero status when docs are stale, covers are broken, or changed source files are uncovered. When changed files are available from git, the failure output includes a git diff review section with committed, staged, and unstaged diff excerpts.

Use --docs <path> only when the documentation directory is not docs.

Failure Types

broken covers

A docs page declares a covers pattern that matches no files.

stale docs

A docs page covers a file whose current content hash no longer matches the stored snapshot.

missing covered files

A docs page snapshot references a file that no longer exists.

changed code without docs coverage

A source file changed in git diff, but no docs page covers it.

uncovered code files

A source file exists in the workspace, but no docs page covers it. Codocia recognizes common implementation extensions, including Rust, Python, JavaScript, TypeScript, TSX/JSX, Vue, Svelte, Go, Java, Kotlin, Swift, C/C++, C#, Ruby, PHP, shell, Lua, R, and SQL.

AI Agent Workflow

If you are an AI agent maintaining docs for a repository using Codocia, follow this loop:

1. Run codocia check --base main.
2. Read codocia.md when present so you know the repository's density, metrics, and page defaults.
3. For every stale doc, read the stale docs page and the git diff review excerpts for the changed files it covers.
4. Update the Markdown body only when the diff changes documented behavior.
5. If a changed source file is uncovered, either add it to an existing page's covers list or create a new docs page.
6. Run codocia snapshot.
7. Run codocia check --base main again.
8. Do not edit generated site output. Only edit docs source files.

Important rules:

• Docs are source of truth.
• Do not add # codocia blocks to source comments.
• Do not update snapshot metadata before updating the human-readable docs body.
• If a hash changed but the diff is formatting-only, test-only, comment-only, or otherwise not documentation-impacting, leave the prose unchanged and refresh the snapshot to record that the docs were reviewed.
• A passing check means the docs snapshot is current, not that the prose is perfect.

CI Example

name: docs

on:
  pull_request:

jobs:
  codocia:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: dtolnay/rust-toolchain@stable
      - run: cargo install codocia
      - run: codocia check --base origin/main

MVP Scope

• Markdown frontmatter declares covers.
• docs/.codocia-snapshot.json stores expanded file hashes.
• Common source extensions are treated as code files for uncovered-file checks.
• File freshness uses deterministic content hashes.
• Git diff is used only when --base is provided.
• No AI calls, HTML generation, llms output, or source-comment extraction in the MVP.