{{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
• 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:
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.

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.

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.