Documentation Model

The single most important concept in Glyph: a documentation entry is keyed by (project_id, file_path, commit_sha). Three pieces, not two.

This is the difference between Glyph and a wiki - and the reason your documentation will still make sense in three years.

The naive approach (what Glyph does NOT do)

Most documentation tools key by (project, file_path). There's exactly one doc per file. Edit it, and the previous version is gone (or sitting in an obscure history page nobody looks at).

When the file is renamed, refactored, or split, the doc breaks. The author writes a TODO. The TODO outlives the company.

The Glyph approach

Each (file_path, commit_sha) pair has its own doc. Practically:

• You open auth.py at the latest commit. The doc you see is what was attached to (auth.py, <latest_sha>).
• You scrub back to the version of auth.py from six months ago. The doc you see is what was attached to (auth.py, <old_sha>) - possibly empty if no one wrote one then.
• You write a new doc on the latest version. It's stored against (auth.py, <latest_sha>). The old doc is untouched.

This makes the doc a time-stamped artifact that travels with the code at that exact point in history.

Inheritance

Reading the latest commit, but no doc was written specifically for it? Glyph inherits from the most recent ancestor commit that has a doc. So you don't need to copy-paste docs forward.

When you make an edit on the latest commit, the inherited doc is forked - a new entry is written for the new commit. The ancestor stays unchanged.

This means:

• Reading is cheap and "always shows something useful"
• Writing is explicit - you're declaring "this is the doc as of this commit"

Implications

Refactors don't break docs

Rename a file? The old (file_path, sha) entries still exist. They're visible when viewing old commits.

Reviews are time-aware

A doc reviewer in 2027 looking at a 2025 commit sees the 2025 doc - the one that matched the code as it was. They're not confused by a 2027 doc that talks about features that didn't exist yet.

Audit trail is built-in

Every doc edit is a write to a specific (file_path, sha). With database backups, you have a full history of what was documented when.

Limits and trade-offs

• Storage - many docs across many commits is more storage than a single wiki page. Mitigated by the fact that most files aren't documented for most commits.
• Discoverability - searching across all versions of all docs can return many similar results. Glyph's search is scoped to the current commit by default.
• Renames - when a file is renamed, Glyph treats the new path as a new file. Manual cross-linking is needed if you want to point readers at the rename.

Comments and references too

Comments and code references follow the same model:

• A comment is attached to (file_path, commit_sha) - old commits show old comment threads
• A code reference's line range is interpreted against the commit it was created on

This consistency means time-travel is uniform across the entire app: switch the commit, everything shifts together.