About these docs

A short note on how this site is organised, so you know what to expect and where to look.

Four layers

The documentation is layered. Each layer answers a different question:

  • Getting Started — how do I install it and see it work?
  • Guides — how do I do X with it?
  • Concepts — how does it work? Why is it built this way?
  • Reference — what are the canonical rules? (Schema, principles, state machines.)

A first-touch reader walks from the top. A returning reader jumps to whichever layer answers the question in hand.

Dependency direction

docs/ cites deeper; never the reverse.

Concrete consequences:

  • Concepts cites Reference. Concepts pages explain how it works in prose. When a normative claim is needed (a column constraint, a state-machine edge, a principle statement), Concepts links to the relevant Reference page instead of restating.
  • Guides cites Concepts. Guides explain how to do X. When background is needed, the Guide links to a Concepts page, not to Reference.
  • Getting Started cites Guides. The Quickstart points at the most relevant Guides for next steps.
  • Reference is the leaf. Reference pages never cite Guides or Getting Started. They may cross-cite each other.

The rule prevents the docs from becoming a circular graph where any change reverberates in unpredictable directions.

Drift policy

Reference is canonical. Concepts may link to Reference for normative claims but never restates them.

If a fact appears in both a Concepts page and a Reference page in two slightly different forms, one of them is wrong and they will drift further over time. The cure is to delete the Concepts copy and replace it with a link to Reference, not to keep them in sync by hand. A runnable grep-check (documented below) reports any section heading duplicated between sibling Concepts and Reference pages; promoting it to a CI gate is a follow-up.

  • Sibling-relative paths inside docs/: [Phases](../reference/action-lifecycle.md#phases). Not absolute, not site-root.
  • Keep .md URL extensions in prose — both GitHub render and Jekyll’s jekyll-relative-links plugin handle them; the plugin rewrites foo.md to its permalink (foo/ under permalink: pretty) at build time. Bare paths like [X](foo) work on neither.
  • Absolute GitHub URLs only in README.md — badges and external project links. The site itself is internal; consumers reach pages via the sidebar or in-doc links.

Repo-specific carve-outs

  • docs/reference/api/ is the YARD-generated Markdown (Jekyll renders it to HTML), regenerated by rake docs:generate (yardoc --format markdown). Never edited by hand. The defaults: block in _config.yml applies nav_exclude: true / search_exclude: true to all files under reference/api/; the index page explicitly overrides those, so it appears in the sidebar as the “API Reference” entry under Reference while the per-class pages stay out of the sidebar and search index. Per-class pages are reachable via this index.
  • docs/reference/drafts/ holds outbound BRC drafts authored here but destined for an upstream repo. URL-addressable but omitted from nav: to avoid presenting drafts as gem behaviour.
  • docs/reference/external/ holds vendored upstream specs (e.g. BRC-100). Each carries an admonition stating where it was vendored from and at which ref.

The broader strategy these decisions sit inside is documented at ~/.claude/docs/documentation-strategy.md (the author’s dotfiles, applied across Ruby projects). This page is the wallet-specific application.

Drift policy check

The check the drift policy referenced above codifies, runnable as a shell one-liner from the repo root:

for f in docs/concepts/*.md; do
  base=$(basename $f)
  ref="docs/reference/$base"
  if [ -f "$ref" ]; then
    common=$(comm -12 <(grep '^## ' "$f" | sort -u) <(grep '^## ' "$ref" | sort -u) \
               | grep -v '^## Related$')
    if [ -n "$common" ]; then
      echo "DRIFT WARNING in $base:"
      echo "$common"
    fi
  fi
done

It walks every docs/concepts/X.md that has a sibling docs/reference/X.md and prints any H2 headings present in both — a literal restatement of a canonical section is the structural signature of drift. The expected output is empty, with one allowed exception: a shared ## Related heading (the “see also” navigation aid at the foot of pages, common to both layers as a convention, not a content restatement). Any other shared heading is a build-failing drift event: the cure is to delete the Concepts copy and link to Reference.

This site uses Just the Docs, a documentation theme for Jekyll.