From 883533ed8af1703cc9bb4a2b24137e325bbbda47 Mon Sep 17 00:00:00 2001
From: codex <codex@local>
Date: Tue, 18 Aug 2026 22:35:47 +0200
Subject: [PATCH] Add first-wave Railiance arc42 stub

Chapters 1, 3 and 9 are real. Chapter 9 indexes the eight published
RMASTER ADRs. policy-nexus will register the document.
---
 docs/architecture/railiance_v0.1.md | 146 ++++++++++++++++++++++++++++
 1 file changed, 146 insertions(+)
 create mode 100644 docs/architecture/railiance_v0.1.md

diff --git a/docs/architecture/railiance_v0.1.md b/docs/architecture/railiance_v0.1.md
new file mode 100644
index 0000000..4da676c
--- /dev/null
+++ b/docs/architecture/railiance_v0.1.md
@@ -0,0 +1,146 @@
+---
+id: railiance-architecture
+title: "Railiance architecture"
+status: proposed
+owner: railiance-master
+revision: "draft-1"
+version: "0.1"
+last_reviewed: "2026-08-18"
+review_interval: 6m
+---
+
+# Railiance — Software Architecture Documentation (arc42)
+
+## About this document
+
+First-wave arc42 for the Railiance runtime substrate. Deeper chapters
+belong to follow-on work in this repo. Chapter 9 lists the ADRs this
+repo already publishes; it does not paste them.
+
+---
+
+## 1. Introduction and Goals
+
+Railiance-master is the authoritative source for Railiance framework
+architecture: repo families, workload models, and substrate boundaries
+that implementation repos must not invent locally.
+
+### 1.1 Requirements Overview
+
+- Name the rails, reefs, and rApps and who owns each boundary.
+- Keep those decisions in `docs/adr/` with publication-grade metadata.
+- Consume platform packages; do not fork identity or tenancy.
+
+### 1.2 Quality Goals
+
+1. Reviewable boundary decisions.
+2. Private-by-default exposure until admission.
+3. Derived rails compose; they do not fork policy.
+
+### 1.3 Stakeholders
+
+| Role | Concern |
+| --- | --- |
+| railiance-master | Framework language and first-wave rApp set. |
+| railiance-platform | S3, placement, substrate services. |
+| railiance-apps | Production digest bindings. |
+| NetKingdom | Identity and tenancy posture of workloads. |
+
+---
+
+## 2. Architecture Constraints
+
+N/A for this stub.
+
+---
+
+## 3. System Scope and Context
+
+**In:** rails, reefs, rApp packaging, admission, exposure defaults.
+**Out:** tenant identity semantics (NetKingdom), publication of policy
+(policy-nexus), OS baseline (railiance-hosts).
+
+### 3.1 Business Context
+
+Implementation repos solve immediate cluster problems. This system
+holds the shared meaning so those repos do not drift.
+
+### 3.2 Technical Context
+
+Neighbours: `railiance-platform`, `railiance-apps`, `rapp-*` packages,
+the reef (Traefik, cert-manager), Forgejo, NetKingdom, policy-nexus.
+
+---
+
+## 4. Solution Strategy
+
+N/A for this stub — repository-prefix architecture and rapp-first wave
+are already in the ADRs in §9.
+
+---
+
+## 5. Building Block View
+
+### 5.1 Level 1 – System/Top-Level
+
+N/A for this stub.
+
+---
+
+## 6. Runtime View
+
+N/A for this stub.
+
+---
+
+## 7. Deployment View
+
+N/A for this stub.
+
+---
+
+## 8. Cross-Cutting Concepts
+
+N/A for this stub.
+
+---
+
+## 9. Architecture Decisions
+
+Published on policy.coulomb.social from this repo:
+
+| Id | Status | Decision |
+| --- | --- | --- |
+| `RMASTER-ADR-0001` | accepted | Repository prefix architecture |
+| `RMASTER-ADR-0002` | accepted | Wave 1 rail-kubernetes boundary |
+| `RMASTER-ADR-0003` | accepted | First-wave rapp selection |
+| `RMASTER-ADR-0004` | accepted | First-wave reef rollout |
+| `RMASTER-ADR-0005` | accepted | Derived rail composition |
+| `RMASTER-ADR-0006` | accepted | Reef production admission |
+| `RMASTER-ADR-0007` | accepted | Rapp declaration contract |
+| `RMASTER-ADR-0008` | accepted | Private-by-default exposure |
+
+Unresolved: identical accepted ADR-003/004 copies in railiance-hosts
+and railiance-infra. Not listed as current here until those owners rule.
+
+---
+
+## 10. Quality Requirements
+
+N/A for this stub.
+
+---
+
+## 11. Risks and Technical Debt
+
+N/A for this stub.
+
+---
+
+## 12. Glossary
+
+| Term | Meaning |
+| --- | --- |
+| Rail | A composed runtime path. |
+| Reef | The production admission environment. |
+| rApp | A packaged workload bound by a declaration contract. |