Home

RSR Template Repo

The Rhodium Standard Repository (RSR) template: a batteries-included starting point that ships with CI/CD, machine-readable project metadata, an AI-agent gatekeeper protocol, a formally-typed ABI/FFI seam (Idris2 + Zig), container and reproducible-build scaffolding, and governance infrastructure — wired and passing the RSR validators on day one.

⚠️ The README you are looking at is a template

README.adoc in this repository is itself a template full of {{PLACEHOLDER}} tokens. Run just repo-init to substitute them. Until you do, the {{...}} markers are intentional placeholders, not content or errors.

Quick start

# 1. Create a repo from this template (or clone it), then from the repo root:
just repo-init      # interactive bootstrap: fills every {{PLACEHOLDER}}

# 2. See the available tasks:
just                # lists all phases (build, test, validate, audit, ...)

# 3. Check the repo still satisfies the RSR shape:
just validate       # structure + metadata checks

just repo-init prompts for the project name, owner, author, licence contact and the other values listed in .machine_readable/ai/PLACEHOLDERS.adoc, substitutes them across the tree, validates the result, and — if available — runs the k9-svc checks.

⚠️ The one trap worth knowing

Do not set RSR_NON_INTERACTIVE=1.

It stubs the shell builtin read, which also disables the loops that perform token substitution. The result is that the run never terminates and substitutes nothing.

If you need a non-interactive bootstrap, pipe answers to stdin instead.

What you get

Machine-readable metadata — .machine_readable/descriptiles/ holds STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM, CLADE, and anchors/ANCHOR, so tools and agents can read the project's state and boundaries.
AI gatekeeper protocol — 0-AI-MANIFEST.a2ml is the universal entry point telling an AI agent how to work in the repo before it touches anything.
Typed ABI/FFI seam — src/interface/Abi/ (Idris2 type and layout proofs) over src/interface/ffi/ (Zig implementation), with generated C headers.
CI/CD — GitHub Actions for quality, security (CodeQL, Scorecard, secret scanning), multi-forge mirroring, and RSR anti-pattern enforcement.
Supply-chain and reproducibility — container layering (stapeln), Guix shells, SBOM, and signing hooks.
Governance — docs/GOVERNANCE.adoc, docs/MAINTAINERS.adoc, .github/ community health files, and a release AUDIT.adoc gate.
Site-operations template — www/ is the canonical home of .well-known/ and the publishable tree (www/public/); a publication-boundary check proves nothing outside www/public/ + www/.well-known/ is servable, and consent-aware profiles are declare-only by default (added 2026-09-17, issue #53 stages 1–4).

Repository map

The authoritative map is generated, so it cannot drift from the tree: docs/architecture/REPOSITORY-MAP.adoc. Regenerate it with just repo-map; CI fails if it is stale.

The short version:

Path	What lives there
`README.adoc`, `CLAUDE.md`	Start here — humans and AI agents respectively
`src/`, `tests/`	The code and its tests
`docs/`	Human documentation, including the full map above
`.machine_readable/`	Manifests, contractiles and policies that tools read
`www/`	Site-operations template: canonical `.well-known/`, publishable `public/` tree, DNS + TLS profiles
`build/`, `Justfile`	Every task runs through `just`; phases live in `build/just/`
`ci/`, `.github/`	CI configuration; GitHub reads `.github/` and no other path

Note the directory was renamed machine-readable/ → .machine_readable/ on 2026-09-17 (PR #107, "one canonical spelling"). Some other estate repos may still carry the old hyphenated spelling until the sweep reaches them; in this repo, .machine_readable/ is canonical.

Where to go next

docs/architecture/REPOSITORY-MAP.adoc — generated; what every directory is for
docs/EXPLAINME.adoc — the engineering deep-dive: how the pieces actually work
docs/AFFIRMATION.adoc — the dated, signed honesty snapshot of the repo's true state
docs/AUDIT.adoc — the release audit gate
docs/AI_INSTALLATION_GUIDE.adoc — for agents instantiating this template
.machine_readable/ai/PLACEHOLDERS.adoc — the full placeholder reference

Where it sits in the stack

standards → rsr-template-repo → scaffoldia → (designed / retrofitted repos)

standards defines the RSR canon; this repository operationalises it as a GitHub template with a just repo-init scaffolder; scaffoldia is the full-featured designer that treats variation as data.

Variant templates declare a variant contract (VARIANT.a2ml: parent pin plus declared path divergences) so that GitHub's "Use this template" path and the composed path cannot silently diverge. See ADR-0002 here, and the reference implementation in rsr-julia-library-template-repo.

The format is being renamed

The metadata files are written in A2ML, being renamed to DEED with extension .deed (ruled final 2026-09-03). A formal DEED grammar is under review as standards#752 and has not yet merged. Separately, CLADE is to be replaced by a facet scheme.

Neither change has been applied here: .a2ml paths and CLADE remain current and correct in this repository.

Licence

Code, configuration and scripts are MPL-2.0; prose documentation is CC-BY-SA-4.0. Both texts live in LICENSES/, and per-file SPDX-License-Identifier headers are authoritative. The GitHub-detected licence is MPL-2.0 (the root LICENSE). Long-term attribution uses Quantum-Safe Provenance — see docs/legal/EXHIBIT-B-QUANTUM-SAFE.txt.

Navigation Menu

Repository navigation