= RSR Template Repository

image:[Palimpsest-MPL-1.0,link="https://github.com/hyperpolymath/palimpsest-license"] image:[Palimpsest,link="https://github.com/hyperpolymath/palimpsest-license"]
:toc:
:sectnums:

// Badges
image:https://img.shields.io/badge/RSR-Infrastructure-cd7f32[RSR Infrastructure]
image:https://img.shields.io/badge/Phase-Maintenance-brightgreen[Phase]
image:https://img.shields.io/badge/Guix-Primary-purple?logo=gnu[Guix]

== Overview

**The canonical template for RSR (Rhodium Standard Repository) projects.**

This repository provides the standardized structure, configuration, and tooling for all 139 repos in the hyperpolymath ecosystem. Use it to:

* Bootstrap new projects with RSR compliance
* Reference the standard directory structure
* Copy configuration templates (Justfile, STATE.scm, etc.)

== Quick Start

[source,bash]
----
# Clone the template
git clone https://github.com/hyperpolymath/RSR-template-repo my-project
cd my-project

# Remove template git history
rm -rf .git
git init

# Customize
sed -i 's/RSR-template-repo/my-project/g' Justfile guix.scm README.adoc

# Enter development environment
guix shell -D -f guix.scm

# Validate compliance
just validate-rsr
----

== What's Included

[cols="1,3"]
|===
|File/Directory |Purpose

|`.editorconfig`
|Editor configuration (indent, charset)

|`.gitignore`
|Standard ignore patterns

|`.guix-channel`
|Guix channel definition

|`.well-known/`
|RFC-compliant metadata (security.txt, ai.txt, humans.txt)

|`docs/`
|Documentation directory

|`guix.scm`
|Guix package definition

|`justfile`
|Task runner with 50+ recipes

|`LICENSE.txt`
|AGPL + Palimpsest dual license

|`README.adoc`
|This file

|`RSR_COMPLIANCE.adoc`
|Compliance tracking

|`STATE.scm`
|Project state checkpoint
|===

== Justfile Features

The template Justfile provides:

* **~10 billion recipe combinations** via matrix recipes
* **Cookbook generation**: `just cookbook` → `docs/just-cookbook.adoc`
* **Man page generation**: `just man` → `docs/man/project.1`
* **RSR validation**: `just validate-rsr`
* **STATE.scm management**: `just state-touch`, `just state-phase`
* **Container support**: `just container-build`, `just container-push`
* **CI matrix**: `just ci-matrix [stage] [depth]`

=== Key Recipes

[source,bash]
----
just                # Show all recipes
just help <recipe>  # Detailed help
just info           # Project info
just combinations   # Show matrix options

just build          # Build (debug)
just test           # Run tests
just quality        # Format + lint + test
just ci             # Full CI pipeline

just validate       # RSR + STATE validation
just docs           # Generate all docs
just cookbook       # Generate Justfile docs

just guix-shell     # Guix dev environment
just container-build # Build container
----

== Directory Structure

[source]
----
project/
├── .editorconfig          # Editor settings
├── .gitignore             # Git ignore
├── .guix-channel          # Guix channel
├── .well-known/           # RFC metadata
│   ├── ai.txt
│   ├── humans.txt
│   └── security.txt
├── config/                # Nickel configs (optional)
├── docs/                  # Documentation
│   ├── generated/
│   ├── man/
│   └── just-cookbook.adoc
├── guix.scm               # Guix package
├── Justfile               # Task runner
├── LICENSE.txt            # Dual license
├── README.adoc            # Overview
├── RSR_COMPLIANCE.adoc    # Compliance
├── src/                   # Source code
├── STATE.scm              # State checkpoint
└── tests/                 # Tests
----

== RSR Compliance

=== Language Tiers

* **Tier 1** (Gold): Rust(+SPARK), Elixir, Zig, Ada, Haskell, AffineScript, Agda
* **Tier 2** (Silver): Nickel, Racket, Guile Scheme, Nix
* **Infrastructure**: Guix channels, derivations

=== Required Files

* `.editorconfig`
* `.gitignore`
* `justfile`
* `README.adoc`
* `RSR_COMPLIANCE.adoc`
* `LICENSE.txt` (AGPL + Palimpsest)
* `.well-known/security.txt`
* `.well-known/ai.txt`
* `.well-known/humans.txt`
* `guix.scm` OR `flake.nix`

=== Prohibited

* Python outside `salt/` directory
* TypeScript/JavaScript/ReScript (use AffineScript)
* CUE (use Guile/Nickel)
* `Dockerfile` (use `Containerfile`)

== STATE.scm

The STATE.scm file tracks project state:

[source,scheme]
----
(define state
  `((metadata
     (project . "my-project")
     (updated . "2025-12-10"))
    (position
     (phase . implementation)  ; design|implementation|testing|maintenance|archived
     (maturity . beta))        ; experimental|alpha|beta|production|lts
    (ecosystem
     (part-of . ("RSR Framework"))
     (depends-on . ()))))
----

== Badge Schema

Generate badges from STATE.scm:

[source,bash]
----
just badges standard
----

See `docs/BADGE_SCHEMA.adoc` for the full badge taxonomy.

== Ecosystem Integration

This template is part of:

* **STATE.scm Ecosystem**: Conversation checkpoints
* **RSR Framework**: Repository standards
* **Consent-Aware-HTTP**: .well-known compliance

== License

SPDX-License-Identifier: MPL-2.0

== Links

* https://github.com/hyperpolymath/elegant-STATE[elegant-STATE] - STATE.scm tooling
* https://github.com/hyperpolymath/conative-gating[conative-gating] - Policy enforcement
* https://rhodium.sh[Rhodium Standard] - RSR documentation
