Quick start

The whole loop in four steps: reference some code from a doc, let docref pin the hash, and let check tell you when it drifts.

Reference code from a doc

In a markdown file, point a fenced code block at a symbol with docref=, or tie a paragraph to code with a claim comment. Don't type the hash; the tool fills it in. Generate a paste-ready block from the CLI:

docref snippet src/server/markdown.ts#applyFootnotes   # a materialized code fence
docref claim   src/api/handler.go#VerifySignature      # a claim block to wrap prose

Pin it

docref refresh fills snippet bodies and their :sha; docref approve <doc> records a claim's hash after you've read the prose against the code. Either way, the reference now carries the content hash of what you saw.

Check

docref check resolves every reference and reports its state, writing nothing:

docref check

It exits 0 when everything is up to date, 1 on a stale reference, and 2 on a broken one, so it doubles as a CI gate.

Keep it honest as the code changes

After editing code, see what you endangered and fix it in the same change:

docref affected --since <merge-base>   # which docs your change touches
docref refresh                          # rewrite stale snippets (mechanical)
docref approve <doc>                    # re-approve claims you've re-read
docref check                            # must be green before you're done

In the editor

The VS Code extension does all of this inline: referenced-by CodeLens, stale/broken squiggles with quick fixes, autocomplete that attaches the hash, and a claim-block scaffold. See the extension page.

Next: the normative Format specification, the full Tooling & CLI reference, or the Internals.