URL scheme

Some links are cheap to fix and some are not. A link in a README is a pull request; a link inside a released binary’s error message is there until somebody upgrades, which for a compliance tool can be years. This page says which OpenRegs documentation URLs carry which promise, so that whoever writes the link knows what they are relying on.

Everything below describes docs.openregs.io. The host is not serving yet — DNS and TLS wait on a hosting provider being chosen. The scheme is fixed now regardless, because the links that are hardest to change are the ones being written today.

The three tiers

Permalinks — safe to embed anywhere

A short path this site promises to keep working for ever. The page it lands on may be renamed, merged into another, or rewritten from scratch; the permalink follows it. Treat one as API surface: it is fine in a shipped binary, an error string, a printed slide, a QR code.

Permalink	Lands on	Written for
/quickstart/	/guides/quickstart/	The first thing anyone should be told to read
/cli/	/reference/cli/	openregs --help and every subcommand epilog
/schema/	/reference/schema-compatibility/	schema_version mismatch errors

The set is deliberately tiny and grows slowly. A permalink is a promise nobody can withdraw, so a new one needs a reason of the same kind: a URL that will be baked into something unfixable. Everything else should link to the real path.

Permalinks live in redirects.json with the reason each one exists.

Section paths — stable, and moves are caught

The ordinary documentation URLs:

/overview/                      what OpenRegs is
/architecture/                  how it fits together
/glossary/                      vocabulary
/guides/<topic>/                task-shaped instructions
/integrations/<system>/         CI and platform wiring
/reference/cli/<command>/       generated from the CLI parser
/reference/<topic>/             schemas, queries, compatibility
/runbooks/<procedure>/          operating and contributing procedures
/contributing/                  how to contribute, governance, security policy
/decisions/<id>-<slug>/         architecture decision records

These are stable in practice rather than by promise: a restructure may move one, but it cannot silently break it. Every route the site has ever served is recorded in routes.lock.json, and CI fails a build where a recorded route has stopped resolving and redirects.json does not say where it went. So an old section path either still serves the page or forwards to wherever the page went.

Link to these freely from anything you can edit — READMEs, issues, comments, other docs. Prefer a permalink only where editing later is impossible.

Version paths — pinned, and frozen on purpose

/                               latest: the current documentation
/v/<version>/                   a frozen version, cut at an engine release

latest tracks the engine’s main and changes as core changes. A frozen version renders one specific engine commit and never changes again — it is the documentation for what somebody is actually running. Every page of one carries a banner saying so, and the version switcher above the navigation moves between them.

Version paths behave in a way the others do not: a page that exists in latest need not exist in a frozen version, because it may document something released after that version was cut. Use /v/<version>/… when the version is the point (a release note, a support answer about a specific build). Otherwise link to the unprefixed path so the reader gets the current documentation.

Rules that hold everywhere

• Trailing slashes. Every documentation URL ends in /. The build emits directory-style routes and canonical links with the slash; write it that way and the link resolves without a redirect hop.
• Lowercase, hyphenated. Path segments are lowercase with hyphens between words. release-publish, never releasePublish or release_publish.
• Fragments are heading ids. #verifying-a-release is the slug of the heading text. Fragments are checked in CI along with the links, so a fragment that stops existing fails the build rather than scrolling to nowhere.
• No query strings. Nothing on this site is addressed by query parameter, so none should appear in a link to it.

Where a page’s content actually lives

Most pages here render Markdown from openregs/openregs at a pinned commit — documentation is written next to the code it describes and this site is the renderer. The footer of every such page names the exact file and commit it was rendered from, and “Edit this page” opens that file in the engine repository. A URL on this site is therefore not a place to send a documentation fix; the footer link is.