Bootstrap grouped home reef repo

.repo-classification.yaml

@@ -0,0 +1,20 @@
+repo_classification:
+  standard: Repo Classification Standard
+  version: "1.0"
+  classified_at: "2026-07-26"
+  classified_by: agent
+  category: project
+  domain: financials
+  secondary_domains:
+    - infotech
+  capability_tags:
+    - platform
+    - operations
+    - configuration
+    - governance
+  business_stake:
+    - technology
+    - operations
+  business_mechanics:
+    - coordination
+    - operation

AGENTS.md

@@ -0,0 +1,43 @@
+# reef-railiance — Agent Instructions
+
+## Repo Identity
+
+**Purpose:** Grouped Railiance home reef for substrate-boundary identity and
+binding facts.
+
+**Domain:** financials
+**Repo slug:** reef-railiance
+**Topic slug:** railiance
+**Workplan prefix:** `REEF-RAILIANCE-WP-`
+
+---
+
+## Session Protocol
+
+**Start:**
+1. Read `README.md`, `INTENT.md`, and `SCOPE.md`
+2. Review active work in `workplans/`
+3. Re-read the current reef declaration in `declarations/reef.yaml`
+
+**During work:**
+- Keep the boundary with `railiance-infra` explicit
+- Keep grouped reef membership and topology facts source-backed
+- Prefer reef-local declarations over implicit operator memory
+
+**Close:**
+1. Update workplan files to reflect progress
+2. Register or refresh the repo from `.repo-classification.yaml` when needed
+3. Run `statehub fix-consistency`
+
+---
+
+## Boundary Reminders
+
+- Do not move generic S1 inventory or provisioning ownership into this repo
+- Do not normalize generic rail or platform behavior here
+- Do not fall back to one-repo-per-machine duplication for grouped home
+  substrate members
+
+The canonical framework boundary lives in
+`railiance-master/docs/reef-first-wave-rollout.md` and
+`railiance-infra/docs/reef-first-wave-source-map.md`.

CLAUDE.md

@@ -0,0 +1,4 @@
+# reef-railiance — Claude Code Instructions
+
+@SCOPE.md
+@AGENTS.md

INTENT.md

@@ -0,0 +1,49 @@
+# INTENT
+
+## Why This Repo Exists
+
+`reef-railiance` exists so Railiance has a first-class home for the grouped
+home substrate boundary rather than treating each current or future Railiance
+server as a separate architectural repo by default.
+
+Before this repo, the relevant substrate facts lived only as source-backed S1
+inventory and runbook context in `railiance-infra`. That remains the canonical
+S1 authority, but it is the wrong long-term home for reef-local identity,
+bindings, and substrate-specific coordination.
+
+This repo establishes the durable answer to:
+
+- what the Railiance home substrate is called
+- which current servers are members of that grouped reef
+- which rails are hosted there by default
+- which workload bindings and substrate-local notes belong to that reef
+
+## What This Repo Must Protect
+
+This repo must keep the first-wave home reef grouped and explicit.
+
+That means:
+
+- protect the distinction between grouped substrate identity and S1 ownership
+- protect the distinction between reef-local bindings and generic rail behavior
+- avoid one-repo-per-machine duplication when the grouped home substrate is the
+  real boundary
+- keep future split criteria explicit if member servers later diverge
+
+## What This Repo Is Not
+
+This repo is not:
+
+- the canonical S1 inventory authority
+- the ownership home for Kubernetes runtime behavior
+- the ownership home for OpenBao, Forgejo, or any other single workload
+- proof that every Railiance server belongs in one reef forever
+
+## Initial Operating Context
+
+Wave 1 starts with `Railiance01` as the first current member of the grouped
+home reef.
+
+Future Railiance home servers should be represented here when they share the
+same lifecycle, access path, and workload-placement policy. If they stop
+sharing those traits, the grouped reef may need to split later.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Railiance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

SCOPE.md

@@ -0,0 +1,125 @@
+# SCOPE
+
+> This file helps you quickly understand what this repository is about,
+> when it is relevant, and when it is not.
+> It is intentionally lightweight and may be incomplete.
+
+---
+
+## One-liner
+
+Grouped Railiance home reef for substrate identity, topology, and binding facts.
+
+---
+
+## Core Idea
+
+`reef-railiance` is the first concrete `reef-*` repo in Railiance.
+It exists to hold the grouped home-substrate boundary for current and future
+Railiance servers, starting with `Railiance01`, without turning S1 inventory
+or one-host naming into the reef model.
+
+---
+
+## In Scope
+
+- Grouped home-reef declaration and compatibility notes
+- Grouped substrate identity and topology facts
+- Hosted-rail and bound-`rapp` surfaces for this reef
+- Reef-local runbooks, overlays, and evidence as they appear
+- Migration compatibility guidance while reef extraction from S1 source facts is
+  still in progress
+
+---
+
+## Out of Scope
+
+- Generic server inventory authority
+- OS provisioning, hardening, and bootstrap logic
+- Kubernetes runtime ownership
+- Platform-service governance or workload packaging
+- One permanent repo per host
+
+---
+
+## Relevant When
+
+- Defining the Railiance home substrate as a grouped reef
+- Recording which servers belong to that grouped substrate
+- Clarifying which rails or `rapp`s attach to the home reef
+- Moving reef-local identity out of generic S1 ownership docs
+
+---
+
+## Not Relevant When
+
+- The work is purely S1 provisioning or hardening
+- The work is generic rail behavior
+- The work is workload-specific packaging or platform governance
+
+---
+
+## Current State
+
+- Status: active bootstrap
+- Implementation: declaration, initial grouped substrate files, and first
+  repo-local workplan are present
+- Stability: evolving
+- Usage: wave-1 home reef for the Railiance server group
+
+---
+
+## How It Fits
+
+- Upstream dependencies: `railiance-infra`, `railiance-master`
+- Downstream consumers: `rail-kubernetes`, future `rapp-*` repos, and Fabric
+  relation projection
+- Often used with: `railiance-cluster`, `railiance-platform`, `railiance-fabric`
+
+---
+
+## Terminology
+
+- Preferred terms: reef, grouped home substrate, substrate boundary, topology
+- Also known as: Railiance home reef
+- Potentially confusing terms: this repo defines a grouped reef boundary; it
+  does not replace `railiance-infra` as the S1 source of truth
+
+---
+
+## Related / Overlapping Repositories
+
+- `railiance-infra` — canonical S1 inventory and provisioning authority
+- `rail-kubernetes` — execution contract expected to be primary on this reef
+- `rapp-openbao` and future `rapp-*` repos — workload packages that may bind to
+  this reef
+- `railiance-master` — framework architecture and reef naming decisions
+
+---
+
+## Getting Oriented
+
+- Start with: `README.md`, `INTENT.md`
+- Key files / directories: `declarations/`, `substrate/`, `bindings/`, `docs/`,
+  `workplans/`
+- Entry points: `declarations/reef.yaml`, `substrate/identity.yaml`,
+  `docs/wave-1-contract.md`
+
+---
+
+## Provided Capabilities
+
+```capability
+type: governance
+title: Grouped home reef contract
+description: Defines the grouped Railiance home substrate boundary, hosted rails, and reef-local topology facts.
+keywords: [railiance, reef, substrate, topology, server-group]
+```
+
+---
+
+## Notes
+
+Keep this repo grouped and explicit. If a future Railiance server no longer
+shares the same substrate boundary, split the reef rather than forcing
+permanent ambiguity.

bindings/rails.yaml

@@ -0,0 +1,6 @@
+reef_id: reef-railiance
+hosted_rails:
+  - rail_id: rail-kubernetes
+    role: primary
+    status: active
+    notes: First-wave default execution rail for the grouped Railiance home reef.

bindings/rapps.yaml

@@ -0,0 +1,5 @@
+reef_id: reef-railiance
+bound_rapps: []
+notes:
+  - No grouped home-reef workload bindings are declared yet.
+  - Add `rapp` bindings here only when the substrate decision is explicit and source-backed.

declarations/reef.yaml

@@ -0,0 +1,24 @@
+kind: substrate-reef
+reef_id: reef-railiance
+repo: reef-railiance
+ownership_repo: railiance-infra
+substrate_kind: server-group
+lifecycle_state: active
+criticality: high
+primary_rail: rail-kubernetes
+hosted_rails:
+  - rail-kubernetes
+bound_rapps: []
+current_members:
+  - Railiance01
+source_documents:
+  - repo: railiance-master
+    path: docs/reef-first-wave-rollout.md
+  - repo: railiance-master
+    path: docs/reef-substrate-model.md
+  - repo: railiance-infra
+    path: docs/reef-first-wave-source-map.md
+compatibility_notes:
+  - Railiance01 is the first current member of the grouped home reef.
+  - Additional Railiance home servers should join this reef when they share the same substrate boundary.
+  - Split the grouped reef later if member lifecycle, access, or workload-placement policy diverges.

docs/README.md

@@ -0,0 +1,5 @@
+# reef-railiance Docs
+
+- `wave-1-contract.md` — current grouped home-reef contract and boundary summary
+- `source-backed-substrate-facts.md` — source-backed first-wave facts imported from S1
+- `source-import-plan.md` — source material and migration direction from existing repos

docs/source-backed-substrate-facts.md

@@ -0,0 +1,33 @@
+# Source-Backed Substrate Facts
+
+## Purpose
+
+Record the first source-backed facts imported into `reef-railiance` for the
+grouped home reef bootstrap.
+
+## Imported Facts
+
+From `railiance-infra/inventory/servers.yaml`:
+
+- current first member: `Railiance01`
+- member IP: `92.205.62.239`
+- member SSH user: `tegwick`
+
+From `railiance-infra/docs/reef-first-wave-source-map.md`:
+
+- this repo represents the grouped Railiance home reef rather than a singleton
+  host repo
+- `rail-kubernetes` is the first primary rail stance
+- additional Railiance home servers should join this reef when they share the
+  same lifecycle and workload-placement boundary
+
+From `railiance-infra/docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md`:
+
+- Forgejo production and the in-cluster Actions runner already use
+  `railiance01` as a Kubernetes-first operational substrate
+
+## Explicit Gaps
+
+- only one source-backed member is declared today
+- there is still no dedicated `host_vars/Railiance01.yml`
+- future grouped members and split criteria remain explicit follow-up work

docs/source-import-plan.md

@@ -0,0 +1,40 @@
+# Source Import Plan
+
+## Purpose
+
+Record which reviewed source materials are expected to seed this repo.
+
+## Imported In The Current Wave
+
+Imported source documents from `railiance-master`:
+
+- `docs/reef-first-wave-rollout.md`
+- `docs/reef-substrate-model.md`
+- `docs/repo-family-bootstrap-contract.md`
+
+Imported source documents from `railiance-infra`:
+
+- `docs/reef-first-wave-source-map.md`
+- `inventory/servers.yaml`
+- `docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md`
+
+## Pending First-Wave Imports
+
+Expected future source surfaces from `railiance-infra`:
+
+- reef-localized runbooks once they stop being generic S1 ownership material
+- any additional source-backed member facts for future Railiance home servers
+- explicit grouped `rapp` binding decisions when they become substrate-local
+
+## Deferred Migration Debt
+
+Do not import these into `reef-railiance` as part of wave 1:
+
+- generic S1 provisioning or inventory ownership
+- generic Kubernetes runtime behavior
+- workload packaging or platform governance
+
+## Rule
+
+Imports into this repo should preserve the grouped home-reef boundary already
+reviewed in `railiance-master` and `railiance-infra`.

docs/wave-1-contract.md

@@ -0,0 +1,57 @@
+# Wave-1 Railiance Home Reef Contract
+
+## Purpose
+
+Summarize the initial grouped home-reef contract `reef-railiance` owns in wave
+1.
+
+This repo starts from already-reviewed source documents rather than inventing a
+new substrate model:
+
+- `railiance-master/docs/reef-first-wave-rollout.md`
+- `railiance-master/docs/reef-substrate-model.md`
+- `railiance-infra/docs/reef-first-wave-source-map.md`
+
+## What `reef-railiance` Owns
+
+Wave 1 assigns these concerns to the reef:
+
+- the grouped Railiance home-substrate identity
+- current member and topology facts for that grouped reef
+- the default hosted-rail statement for the home substrate
+- future grouped `rapp` bindings for that substrate
+- reef-local runbooks, overlays, and evidence when they become substrate-owned
+
+## What Stays In `railiance-infra`
+
+Wave 1 keeps these concerns in the canonical S1 ownership repo:
+
+- server inventory authority
+- OS provisioning and hardening logic
+- SSH key and convergence mechanics
+- source-backed server facts that are not yet reef-localized
+- future split criteria that still depend on broader S1 review
+
+## Published Substrate Assumptions
+
+Wave 1 `reef-railiance` may assume:
+
+- `Railiance01` is the first current member
+- `rail-kubernetes` is the first primary rail stance
+- additional Railiance home servers may join when they share the same grouped
+  substrate boundary
+
+Wave 1 `reef-railiance` must not assume:
+
+- that every future Railiance server belongs here automatically
+- that platform or workload ownership moves into this repo
+- that grouped membership is permanent if lifecycle or security boundaries split
+
+## Migration Constraint
+
+Until the extraction is complete, `railiance-infra` remains the canonical S1
+source of truth.
+
+`reef-railiance` should become the durable grouped substrate home first. Only
+then should additional bindings, runbooks, and substrate-local overlays move
+here in a migration-safe sequence.

substrate/identity.yaml

@@ -0,0 +1,16 @@
+reef_id: reef-railiance
+display_name: Railiance Home Reef
+substrate_kind: server-group
+ownership_repo: railiance-infra
+lifecycle_state: active
+criticality: high
+primary_rail: rail-kubernetes
+current_members:
+  - Railiance01
+current_role: Grouped home substrate for Kubernetes-first Railiance workloads.
+source_of_truth:
+  repo: railiance-infra
+  paths:
+    - inventory/servers.yaml
+    - docs/reef-first-wave-source-map.md
+    - docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md

substrate/topology.yaml

@@ -0,0 +1,22 @@
+reef_id: reef-railiance
+membership_policy: Add Railiance home servers here when they share one durable home-substrate boundary.
+members:
+  - member_id: Railiance01
+    role: first-current-member
+    provider: HostEurope
+    ip: 92.205.62.239
+    ssh_user: tegwick
+    evidence:
+      - repo: railiance-infra
+        path: inventory/servers.yaml
+      - repo: railiance-infra
+        path: docs/adr/ADR-004-forgejo-in-cluster-actions-runner.md
+access_surfaces:
+  - type: ssh
+    member: Railiance01
+    user: tegwick
+  - type: kubernetes-runtime
+    rail: rail-kubernetes
+unresolved_questions:
+  - Which future Railiance servers should join this grouped home reef first?
+  - At what point would member divergence justify splitting this reef?

workplans/REEF-RAILIANCE-WP-0001-bootstrap-and-wave1-import.md

@@ -0,0 +1,107 @@
+---
+id: REEF-RAILIANCE-WP-0001
+type: workplan
+title: "Bootstrap reef-railiance and import the wave-1 grouped substrate surface"
+domain: financials
+repo: reef-railiance
+status: active
+owner: codex
+topic_slug: railiance
+created: "2026-07-26"
+updated: "2026-07-26"
+---
+
+# REEF-RAILIANCE-WP-0001 - Bootstrap reef-railiance and import the wave-1 grouped substrate surface
+
+## Goal
+
+Turn `reef-railiance` into the concrete home of the first grouped Railiance
+home reef.
+
+## Boundaries
+
+This workplan may bootstrap the repo, publish the initial reef declaration,
+and import the first source-backed grouped substrate facts from
+`railiance-infra`.
+
+It must not:
+
+- absorb generic S1 provisioning or inventory ownership from `railiance-infra`
+- pretend one repo per server is the default reef model
+- normalize generic rail or platform behavior into this repo
+
+## T01 - Establish the repo baseline and reef declaration
+
+```task
+id: REEF-RAILIANCE-WP-0001-T01
+status: done
+priority: high
+```
+
+Create the baseline repo files, the initial reef declaration, and the first
+wave-1 contract summary.
+
+Acceptance:
+
+- baseline repo files exist
+- `declarations/reef.yaml` exists
+- the repo states its boundary with `railiance-infra`
+
+2026-07-26: Created the initial repo baseline, grouped reef declaration, and
+wave-1 contract summary.
+
+## T02 - Import the first source-backed grouped substrate facts
+
+```task
+id: REEF-RAILIANCE-WP-0001-T02
+status: done
+priority: high
+```
+
+Bring the reviewed first grouped-substrate fact set into this repo in a
+migration-safe sequence.
+
+Acceptance:
+
+- the import sequence is anchored in the reviewed S1 source map
+- imported material stays reef-local rather than generic S1 ownership
+- the repo becomes a real grouped home reef rather than only a shell
+
+2026-07-26: Imported the first grouped substrate facts from `railiance-infra`,
+including the current member identity from `inventory/servers.yaml`, the
+grouped home-reef rollout stance from `docs/reef-first-wave-source-map.md`,
+and the operational substrate evidence from ADR-004.
+
+## T03 - Prepare the retained S1 handoff from `railiance-infra`
+
+```task
+id: REEF-RAILIANCE-WP-0001-T03
+status: wait
+priority: medium
+```
+
+Define the thin compatibility path that keeps current operators functional
+while reef-localization proceeds.
+
+Acceptance:
+
+- the retained S1 surface is explicit
+- current operators do not need a flag day
+- the retained S1 surface stays narrow and temporary
+
+## T04 - Register `reef-railiance` in State Hub and Fabric
+
+```task
+id: REEF-RAILIANCE-WP-0001-T04
+status: wait
+priority: medium
+```
+
+Register the repo from classification and add it to the Fabric repository
+registry with `reef`-family metadata.
+
+Acceptance:
+
+- State Hub recognizes the repo and its workplan
+- Fabric recognizes the repo as `repo_family: reef`
+- ownership, primary-rail, and substrate-kind metadata are visible