Establish Railiance architecture home

docs/reef-first-wave-rollout.md

@@ -0,0 +1,183 @@
+# First-Wave `reef-*` Rollout
+
+Date: 2026-07-25
+
+## Purpose
+
+Apply the `reef-*` model to the current Railiance substrate reality and choose
+the first actual reef rollout.
+
+This document intentionally decides both:
+
+- which reefs should exist first
+- and which current repo should remain the canonical S1 ownership home while
+  reefs are introduced
+
+## Current Substrate Reality
+
+Railiance currently has three clearly different substrate realities:
+
+### `RAILIANCE01`
+
+- HostEurope server at `92.205.62.239`
+- the most mature current home for new Kubernetes-first workloads
+- already hosts Forgejo and overlapping platform services
+- likely seed of a future multi-server Railiance home substrate
+
+### `COULOMBCORE`
+
+- HostEurope server at `92.205.130.254`
+- older, mixed-purpose, still actively used
+- retains current Gitea fallback and other legacy or transitional runtime
+  realities
+- not yet fully integrated into the newer operating model
+
+### operator workstation
+
+- edge/operator compute, not the same kind of substrate as the servers
+- hosts operator tools, local keys, bridges, kubeconfig usage, and attended
+  control-plane work
+- likely to become a class of substrates rather than a forever-singleton machine
+
+## Decision
+
+The first-wave reef rollout is:
+
+1. `reef-railiance01`
+2. `reef-coulombcore`
+3. `reef-ops-workstations`
+
+Do **not** create `reef-workstation` as a singleton first-wave repo.
+
+## Why These Three
+
+### `reef-railiance01`
+
+This should be the first canonical reef.
+
+Why:
+
+- it is already the clearest purpose-bound substrate
+- it is the default home for new Kubernetes-oriented Railiance workloads
+- it is the likely seed of the future Railiance home reef
+- its lifecycle, access path, and workload-placement decisions are already
+  distinct enough to justify a dedicated reef
+
+Primary rail stance:
+
+- primary rail: `rail-kubernetes`
+- temporary multi-rail reality is acceptable here during early growth
+- later `rail-knative` may coexist on this reef if that is the most pragmatic
+  path for early workloads such as `qonto-assistent`
+- if criticality or security pressure grows, reassess whether a broader grouped
+  home reef or a rail-specific separation is required
+
+### `reef-coulombcore`
+
+This should exist, but explicitly as a transitional reef.
+
+Why:
+
+- COULOMBCORE is still a real operational boundary
+- it has its own access path, operational evidence, fallback responsibilities,
+  and recovery decisions
+- it is exactly the kind of substrate that should be described honestly even if
+  its long-term role is not yet clean
+
+Interpretation:
+
+- treat it as a mixed-purpose, legacy, or transition reef
+- allow multi-rail and compatibility realities here without pretending they are
+  the preferred long-term production pattern
+- use the reef to make drain, cleanup, fallback, and migration decisions visible
+
+Do not force a permanent taxonomy label such as "associate", "sidecar", or
+"comet" yet. Those labels may become useful later, but the operational pattern
+is not stable enough to canonize.
+
+### `reef-ops-workstations`
+
+Use a grouped reef for operator workstations.
+
+Why:
+
+- the workstation role is clearly a different substrate class from the servers
+- the machine count is likely to grow or vary over time
+- one repo per laptop would create exactly the duplication the reef model is
+  supposed to prevent
+
+Interpretation:
+
+- treat current workstation reality as the first member of an operator/edge
+  compute reef class
+- keep machine-specific details inside the reef topology, not in separate repos
+
+## Singleton Versus Grouped Rule Applied
+
+Applying the reef rules to the current hosts yields:
+
+- `RAILIANCE01`: singleton reef now, because the machine itself is the current
+  durable substrate boundary
+- `COULOMBCORE`: singleton reef now, because it remains an independent
+  operational and fallback boundary
+- workstation: grouped reef, because the substrate concept is "operator edge
+  compute" rather than one permanently special laptop
+
+If Railiance01 later becomes one node in a clearly unified multi-node home
+substrate with shared lifecycle and placement policy, reassess whether the
+right target becomes a grouped reef such as `reef-railiance-home`.
+
+Until then, `reef-railiance01` is the cleaner decision.
+
+## `railiance-hosts` Versus `railiance-infra`
+
+Current reality:
+
+- `railiance-hosts` and `railiance-infra` are functionally duplicate S1 repos
+- both describe the same S1 provisioning and baseline responsibility
+- both contain the same authoritative-looking server inventory path
+- Fabric onboarding already uses `railiance-infra`
+
+Decision:
+
+- `railiance-infra` is the canonical S1 ownership repo going forward
+- `railiance-hosts` should be treated as a predecessor or migration duplicate,
+  not as the long-term authority for new architecture work
+
+What this means:
+
+- new framework architecture should anchor on `railiance-infra`
+- reef introduction should not preserve the `hosts` naming line as a second S1
+  authority
+- later cleanup should either retire `railiance-hosts` or reduce it to an
+  explicit compatibility/archive role
+
+## Practical Rollout Sequence
+
+The reef rollout should happen in this order:
+
+1. create `reef-railiance01` as the first canonical home reef seed
+2. create `reef-coulombcore` as the transitional legacy/fallback reef
+3. create `reef-ops-workstations` as the grouped operator-edge reef
+4. document `railiance-infra` as canonical S1 and plan the `railiance-hosts`
+   retirement or freeze direction
+
+## Risks To Watch
+
+- If `reef-coulombcore` is described as if it were the preferred long-term
+  production substrate, the reef model will normalize transitional mess instead
+  of making it visible.
+- If `reef-workstation` is created first, the framework will drift toward
+  one-repo-per-machine duplication.
+- If `railiance-hosts` and `railiance-infra` remain equally canonical, reef
+  ownership will rest on an unstable S1 base.
+
+## Outcome
+
+Railiance now has a concrete first reef rollout:
+
+- `reef-railiance01` as the primary home-reef seed
+- `reef-coulombcore` as the transitional legacy/fallback reef
+- `reef-ops-workstations` as the grouped operator-edge reef
+
+That is enough to move from reef theory into practical repo planning.