shihwesley-chronicler

Chronicler

Automated .tech.md generation for codebases. Crawl a repo, draft structured technical documentation with an LLM, and track when those docs go stale — all from the command line.

This is Chronicler Lite — built for vibe coders, indie developers, and small teams who want their codebase documented without the overhead. An enterprise version with org-wide governance, CI/CD enforcement, and team-scoped access control is on the way.

Obsidian user? Check out obsidian-chronicler — a plugin that auto-discovers your .chronicler/ folders, renders agent:// links as clickable navigation, and gives you dependency graphs + health dashboards right in your vault.

Why this exists

Most technical documentation is written once and forgotten. The author moves on, the codebase changes, and six months later a new engineer opens the doc to find a half-finished description of an architecture that no longer exists.

This happens everywhere — startups, enterprises, open source. A developer gets assigned to modify a pipeline or extend a feature. They open the tech doc. The doc has a one-paragraph overview, a diagram from two versions ago, and no information about why the system was built that way. The developer ends up reading source code for hours, reconstructing context that someone already had and didn't write down.

Chronicler tries to fix that. It generates standardized, structured Markdown documentation from your actual codebase, keeps it in sync with your source files, and formats it so both humans and AI agents can use it without guessing.

Why Markdown

Previous approaches to technical documentation stored knowledge in Google Docs, Confluence pages, PDFs, or Word files. These formats have a shared problem: they're hard for machines to parse and easy to lose track of.

Chronicler writes .tech.md files — plain Markdown with YAML frontmatter. The reasons:

• Lives with the code. Docs sit in a .chronicler/ directory in your repo. They go through the same PR review, branching, and history as your source files.
• AI-native format. LLMs read Markdown natively. No conversion step, no extraction pipeline. An AI agent can read a .tech.md file and know what a component does, what it depends on, and what will break if you change it.
• RAG-ready. The structured YAML frontmatter and consistent section format make these files easy to chunk and index. Chronicler's companion project, Mnemon, consumes this output for 3D knowledge-graph visualization and semantic search.
• Human-readable everywhere. Obsidian, VS Code's Markdown preview, GitHub's web view, any text editor. No proprietary viewer required.

How it works

Chronicler has a four-stage pipeline:

1. Crawl     →  Connect to GitHub, clone the file tree, collect key files
2. Draft     →  Send structured context to an LLM, get back a .tech.md
3. Validate  →  Check the output against the frontmatter schema
4. Track     →  Hash source files into a merkle tree, detect drift over time

Crawl

The VCS crawler connects to GitHub (Azure DevOps and GitLab planned), pulls repo metadata, the file tree, and the contents of key files (README, package manifests, config files, entry points). It also converts PDFs, DOCX, and PPTX files it finds into Markdown for inclusion.

Draft

The drafter builds a prompt context from the crawl data — file tree, dependencies, key file contents — and sends it to an LLM. The system prompt is explicit: strictly technical, no marketing language, no fluff. If the LLM can't determine something from the repo data, it writes "unknown" instead of guessing.

The output follows a fixed structure:

• YAML frontmatter (component ID, owner team, layer, edges, security level, governance metadata)
• Architectural intent (what this does, why it exists, key responsibilities)
• Connectivity graph (Mermaid diagram of dependencies)
• Links to satellite docs (QA blueprints, audit logs, invariants)

A word-count guard flags any draft that exceeds 1,500 words. The goal is density, not volume.

Validate

chronicler validate checks every .tech.md file in your .chronicler/ directory against the frontmatter schema. Strict mode (the default) fails on missing required fields. You can run this in CI to block PRs that ship without valid docs.

Track freshness with merkle trees

This is where Chronicler differs from "run the doc generator once and forget about it."

Every source file in your repo gets SHA-256 hashed and placed into a merkle tree (stored as .chronicler/.merkle.json). When you run chronicler check, it recomputes hashes and compares them against the stored tree. Files whose hashes changed but whose corresponding .tech.md hasn't been updated are flagged as stale.

chronicler check
# Shows a table of files with ok/stale status