diff --git a/.repo-classification.yaml b/.repo-classification.yaml new file mode 100644 index 0000000..9e4a6f1 --- /dev/null +++ b/.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 diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..2802c86 --- /dev/null +++ b/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`. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..f3dce45 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,4 @@ +# reef-railiance — Claude Code Instructions + +@SCOPE.md +@AGENTS.md diff --git a/INTENT.md b/INTENT.md new file mode 100644 index 0000000..417e1d3 --- /dev/null +++ b/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. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2711464 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index cc5b0e2..0ddda00 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,46 @@ # reef-railiance -The railiance repo to represent its own home reef \ No newline at end of file +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 diff --git a/SCOPE.md b/SCOPE.md new file mode 100644 index 0000000..048e60d --- /dev/null +++ b/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. diff --git a/bindings/rails.yaml b/bindings/rails.yaml new file mode 100644 index 0000000..f140d06 --- /dev/null +++ b/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. diff --git a/bindings/rapps.yaml b/bindings/rapps.yaml new file mode 100644 index 0000000..d8df8c4 --- /dev/null +++ b/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. diff --git a/declarations/reef.yaml b/declarations/reef.yaml new file mode 100644 index 0000000..7f92ead --- /dev/null +++ b/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. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..7b5eb75 --- /dev/null +++ b/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 diff --git a/docs/source-backed-substrate-facts.md b/docs/source-backed-substrate-facts.md new file mode 100644 index 0000000..09604db --- /dev/null +++ b/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 diff --git a/docs/source-import-plan.md b/docs/source-import-plan.md new file mode 100644 index 0000000..2105efe --- /dev/null +++ b/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`. diff --git a/docs/wave-1-contract.md b/docs/wave-1-contract.md new file mode 100644 index 0000000..f0085ce --- /dev/null +++ b/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. diff --git a/substrate/identity.yaml b/substrate/identity.yaml new file mode 100644 index 0000000..1e6b5ec --- /dev/null +++ b/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 diff --git a/substrate/topology.yaml b/substrate/topology.yaml new file mode 100644 index 0000000..eae43cc --- /dev/null +++ b/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? diff --git a/workplans/REEF-RAILIANCE-WP-0001-bootstrap-and-wave1-import.md b/workplans/REEF-RAILIANCE-WP-0001-bootstrap-and-wave1-import.md new file mode 100644 index 0000000..9f5e205 --- /dev/null +++ b/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