{{PROJECT_NAME}}

{{PROJECT_DESCRIPTION}}

Important

This file is a template. You are reading README.adoc from the RSR template repo (or a freshly-cloned copy of it). Run just repo-init to replace every {{PLACEHOLDER}} token with your project’s details, then delete this admonition. Until you do, the {{…​}} markers below are intentional placeholders, not content.

Table of Contents

• What this is
• Quick start
• AI-Assisted Installation (Recommended)
  • Just say it
  • What you will be asked
  • Privacy and security
  • Minting without a terminal
  • Troubleshooting
• What you get
• Governance badges
• Repository map
• Where to go next
• Licence

What this is

A new repository scaffolded from 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 — all wired and passing the RSR validators on day one.

Replace this section with a description of your project once initialised.

Quick start

# 1. Create a repo from this template (or clone it), then from the repo root:
mise trust                    # allow this repository's mise.toml (needed without a TTY)
mise install                  # the toolchain, including the yq repo-init needs
mise exec -- just repo-init   # interactive bootstrap: fills every {{PLACEHOLDER}}

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

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

mise exec -- puts the toolchain on PATH for that one command. Once mise is activated in your shell (eval "$(mise activate bash)", or your shell’s equivalent), plain just works and the prefix can be dropped.

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.

AI-Assisted Installation (Recommended)

Just say it

Say this to any AI assistant that can read a URL and run commands (or give you commands to paste):

Create a new repository from https://github.com/hyperpolymath/rsr-template-repo

The URL is the key: it leads the assistant to docs/AI_INSTALLATION_GUIDE.adoc, the complete step-by-step recipe. The assistant checks your system, installs the prerequisites, instantiates the template with just repo-init, and verifies the result with just doctor.

• "Set up rsr-template-repo so I can work on the template itself — https://github.com/hyperpolymath/rsr-template-repo"

• ./launcher.sh --ai-setup (or just ai-setup) prints the line and the guide path.

What you will be asked

1. Your operating system (Linux, macOS, or Windows via WSL2).

2. The new project’s name, owner, author and licence contact (the values listed in .machine_readable/ai/PLACEHOLDERS.adoc).

3. To confirm the privacy notice below.

Privacy and security

Important

Setting up rsr-template-repo clones this repository and installs its developer tools per-user with mise (no administrator rights, nothing sent anywhere). just repo-init rewrites files only inside the new checkout; it creates no remote repository and pushes nothing until you do.

Minting without a terminal

Agents and CI can mint non-interactively: set RSR_NON_INTERACTIVE=1 and pass the answers as environment variables named like the prompts' variables in build/just/repo-init.just (PROJECT_NAME, REPO, OWNER, AUTHOR and AUTHOR_EMAIL are required; any other answer left unset is blank or takes its default). Piping the answers to stdin in prompt order also works.

Troubleshooting

Run just doctor; each FAIL carries a code explained in docs/SETUP.adoc §Troubleshooting, and just heal applies the automatic fixes. Prefer to do it yourself? The full manual route is docs/SETUP.adoc; developers and maintainers can brief an AI with just ai-warmup dev / just ai-warmup maintainer.

What you get

• Machine-readable metadata (.machine_readable/descriptiles/) — STATE, META, ECOSYSTEM, PLAYBOOK, AGENTIC, NEUROSYM, CLADE, and anchors/ANCHOR, in deed, so tools and agents can read the project’s state and boundaries.

• AI gatekeeper protocol — rsr-template-repo_chora.deed (the repo deed) is the universal entry point that tells an AI agent how to work in this repo before it touches anything; it carries the AI allocation policy and the ply directory tree.

• Typed ABI/FFI seam — src/interface/Abi/ (Idris2 type + 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 & reproducibility — container layering (stapeln), Guix shells, SBOM, and signing hooks.

• Governance — GOVERNANCE.adoc, MAINTAINERS.adoc, .github/ community health files, and a release AUDIT.adoc gate.

Governance badges

The K9 conformance badge in the row at the top becomes live after just repo-init replaces the {{OWNER}} and {{REPO}} placeholders in its URL and an eligible push to main publishes it. It is published by .github/workflows/dogfood-gate.yml to a generated orphan branch called governance-badges, and read back through the shields endpoint.

Badge	What it means
green success	The K9 lane ran for that commit on main and passed.
red failure	The K9 lane ran for that commit on main and failed.
grey skipped, cancelled, unavailable, unknown	That commit produced no trustworthy K9 result. Grey is not "pending" and not a stale green: a skipped, cancelled or unavailable lane replaces an earlier green badge with grey.

• governance-badges is generated output. It deliberately has no common ancestor with main, it has no pull request, and it must never be merged. Recent pushes to it are ordinary badge refreshes.

• A run that would publish the same bytes makes no commit at all.

• Nothing in the badge pipeline can turn a failing validation green: only a lane that ran and passed, with its artifact present, renders brightgreen.

The full operational contract - the exact state table, how API errors are classified, how concurrent publications are serialised, and how to repair a bad file - is in .github/workflows/README.adoc.

Repository map

The authoritative map is generated, so it cannot drift from the tree: docs/architecture/REPOSITORY-MAP.adoc (regenerate 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.
build/, Justfile	Every task runs through just; phases live in build/just/.
ci/, .github/	CI configuration; GitHub reads .github/ and no other path.

Where to go next

• The repository map — generated; what every directory is for.

• EXPLAINME — the engineering deep-dive: how the pieces actually work.

• AFFIRMATION — the dated, signed honesty snapshot of the repo’s true state.

• AUDIT — the release audit gate.

• AI installation guide — for agents instantiating this template.

• PLACEHOLDERS — the full placeholder reference.

Licence

Code, configuration and scripts are Mozilla Public License 2.0 (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 the Quantum-Safe Provenance exhibit.