Bootstrap grouped home reef repo

README.md

@@ -1,3 +1,46 @@
 # reef-railiance
 
-The railiance repo to represent its own home reef
+Wave-1 grouped home reef for Railiance-managed server substrates.
+
+## Purpose
+
+`reef-railiance` is the first concrete `reef-*` repo in Railiance.
+It owns the grouped home-substrate boundary that should describe current and
+future Railiance home servers without creating one repo per machine.
+
+This repo exists to hold:
+
+- the source-controlled reef declaration for the Railiance home substrate
+- grouped substrate identity and topology facts
+- rail and workload binding surfaces for this reef
+- the migration path from source-backed S1 facts in `railiance-infra`
+
+## Boundary
+
+`reef-railiance` does not own:
+
+- generic S1 provisioning, hardening, or server inventory authority
+- generic Kubernetes runtime ownership
+- platform-service governance or workload packaging
+- one permanent repo per host in the Railiance home substrate
+
+Those concerns stay with `railiance-infra`, `railiance-cluster`,
+`railiance-platform`, or the relevant `rapp-*` repo.
+
+## Current Status
+
+This repo is in first-wave bootstrap.
+
+The boundary and source material come from:
+
+- `railiance-master/docs/reef-first-wave-rollout.md`
+- `railiance-master/docs/reef-substrate-model.md`
+- `railiance-infra/docs/reef-first-wave-source-map.md`
+
+## Initial Layout
+
+- `declarations/reef.yaml` — source-controlled reef contract
+- `substrate/` — grouped substrate identity and topology facts
+- `bindings/` — rail and `rapp` binding surfaces for this reef
+- `docs/` — wave-1 contract and source import plan
+- `workplans/` — repo-local execution work