Establish Railiance architecture home

docs/adr/ADR-0001-repository-prefix-architecture.md

@@ -0,0 +1,133 @@
+# ADR-0001: Repository Prefix Architecture
+
+Date: 2026-07-25
+Status: Accepted
+
+## Context
+
+Railiance already has a meaningful set of ownership repos such as
+`railiance-infra`, `railiance-cluster`, `railiance-platform`,
+`railiance-enablement`, `railiance-apps`, `railiance-forge`, and
+`railiance-fabric`.
+
+That structure is useful, but it does not by itself capture all of the
+dimensions Railiance now needs.
+
+In particular, the architecture needs clear source-controlled homes for:
+
+- workload execution contracts across different operations architectures,
+- managed workload packages as first-class repos,
+- and concrete substrate boundaries such as named servers, workstations, or
+  grouped environments.
+
+Without that separation, Kubernetes-specific workload semantics remain mixed
+into `railiance-cluster`, workload wrappers remain mixed into ownership repos,
+and concrete substrates remain under-described.
+
+Railiance also operates inside a wider ecosystem around Railiance, Net Kingdom,
+and the Helix Forge software factory. That wider context needs architecture
+that can support both exploratory operation and production-grade evolution
+without leaving key responsibilities ambiguous.
+
+## Decision
+
+Railiance adopts four canonical repository families:
+
+1. `railiance-*` for ownership and responsibility areas
+2. `rail-*` for workload execution contracts
+3. `rapp-*` for Railiance-managed workload packages
+4. `reef-*` for durable substrate boundaries
+
+The current implementation wave is explicitly centered on `rail-kubernetes` as
+the default base rail. Additional rails are introduced only when a concrete
+workload has a sound reason to run on a distinct execution architecture.
+
+`rail-knative` is the first expected follow-on rail, motivated by the need to
+support `qonto-assistent`, but it should follow the `rail-kubernetes` boundary
+cleanup rather than bypass it.
+
+## Meaning Of Each Family
+
+### `railiance-*`
+
+Owns major architectural responsibilities, shared policies, and durable layer
+boundaries.
+
+### `rail-*`
+
+Owns how workloads run on a specific execution architecture such as Kubernetes,
+Knative, KEDA, Fission, or Nuclio.
+
+In the current phase, `rail-kubernetes` is the default path for platform
+services and managed applications.
+
+### `rapp-*`
+
+Owns the managed workload package for one service or application, whether it is
+an internal workload or a wrapped upstream product.
+
+Its role is to provide the managed wrapper and scaffolding needed to run that
+workload in the Railiance and Net Kingdom context. It does not replace
+responsibility ownership.
+
+### `reef-*`
+
+Owns the concrete substrate reality where rails and `rapp`s are bound, such as
+a named server, cluster, workstation, or grouped substrate class.
+
+A reef is about purpose-bound compute resources, not merely about individual
+machines.
+
+## Consequences
+
+### Positive
+
+- Ownership, execution, workload identity, and substrate identity become
+  separate concerns.
+- Railiance can support multiple execution architectures without forcing all
+  workload semantics into `railiance-cluster`.
+- Platform services and applications can both become first-class managed
+  workload packages where appropriate.
+- Concrete substrates gain a clear architectural home without overloading the
+  ownership repos.
+- The framework gains a disciplined default path for introducing new rails
+  instead of proliferating them speculatively.
+
+### Required Follow-On Work
+
+- Define the initial `rail-*` contracts, starting with `rail-kubernetes`.
+- Evolve the current `railiance/app.toml` and overlay pattern into a
+  rail-aware, eventually rail-neutral workload packaging contract.
+- Identify which current workloads should become `rapp-*` repos.
+- Extend `railiance-fabric` so rails, `rapp`s, and reefs become graph-native.
+- Define when mixed-rail reefs are acceptable and when clearer substrate
+  separation should be preferred.
+
+### Constraints
+
+- `reef-*` must not become a default one-repo-per-machine pattern.
+- Generic logic stays in the appropriate ownership repo.
+- A named machine gets its own reef only when that machine is itself a durable
+  substrate boundary.
+- `rapp-*` repos must not become shadow ownership repos.
+- Transitional substrate labels should not be canonized before the pattern is
+  operationally stable.
+
+## Current Interpretation For Existing Repos
+
+- `railiance-*` repos remain the primary ownership axis.
+- Current workload-execution logic in `railiance-cluster` is a candidate to
+  migrate into `rail-kubernetes`.
+- Current workload wrappers inside `railiance-apps`, `railiance-platform`, or
+  `railiance-forge` may evolve into `rapp-*` repos over time.
+- Current named substrates such as COULOMBCORE, RAILIANCE01, and WORKSTATION
+  may justify `reef-*` repos when they represent real operational boundaries.
+- A reef may host more than one rail in early or mixed environments, but
+  production-critical substrates should prefer clearer purpose and primary-rail
+  boundaries unless a mixed design is justified.
+
+## Notes
+
+This ADR defines the repository taxonomy. It does not yet mandate a full
+migration or rename of existing repos. Migration should happen when it produces
+clearer ownership and lower ambiguity, not merely for naming purity.

docs/adr/ADR-0002-rail-kubernetes-wave-1-boundary.md

@@ -0,0 +1,64 @@
+# ADR-0002: Wave 1 `rail-kubernetes` Boundary
+
+Date: 2026-07-25
+Status: Accepted
+
+## Context
+
+Railiance wants `rail-*` repos to represent workload execution contracts rather
+than abstract naming ideas.
+
+Today, the concrete Kubernetes workload contract already exists, but it is
+embedded in `railiance-cluster`. That repo currently owns both:
+
+- the S2 Kubernetes substrate
+- and the generic workload lifecycle and tooling that run on top of it
+
+That mixed ownership is the main blocker to introducing the first real rail.
+
+## Decision
+
+Railiance will treat `rail-kubernetes` as the wave-1 base rail.
+
+The boundary is:
+
+- `railiance-cluster` owns the Kubernetes substrate and its prerequisites
+- `rail-kubernetes` owns the generic workload-on-Kubernetes execution contract
+
+Workload-specific helper flows currently living in `railiance-cluster` are
+temporary exceptions and must be rehomed rather than carried forward as part of
+the generic rail.
+
+## Consequences
+
+### Positive
+
+- The first real rail gains a concrete ownership boundary.
+- `railiance-cluster` can return to a clean S2 substrate identity.
+- Future rails such as `rail-knative` get a stable base boundary to extend from.
+- `rapp-*` repos gain a clearer execution-contract home for Kubernetes-managed
+  workloads.
+
+### Required Follow-On Work
+
+- Create the detailed `rail-kubernetes` boundary contract and migration map.
+- Split generic lifecycle docs, schema, examples, and Stage 1-3 tooling out of
+  `railiance-cluster`.
+- Leave a compatibility path so current users of the cluster repo are not
+  broken during the migration.
+- Rehome workload-specific helpers that do not belong in either boundary.
+
+### Constraints
+
+- `rail-kubernetes` must not take ownership of cluster bootstrap, operators, or
+  kubeconfig management.
+- `railiance-cluster` must not continue as the owner of generic workload
+  promotion semantics after the split.
+- `rail-knative` should follow this cleanup, not bypass it.
+
+## Notes
+
+This ADR does not require all current files to move immediately.
+
+It requires the ownership line to be explicit now, so practical repo separation
+can proceed without ambiguity.

docs/adr/ADR-0003-rapp-first-wave-selection.md

@@ -0,0 +1,57 @@
+# ADR-0003: First-Wave `rapp-*` Selection
+
+Date: 2026-07-25
+Status: Accepted
+
+## Context
+
+Railiance wants `rapp-*` repos to represent managed workload packages rather
+than new ownership layers.
+
+The current workload surfaces already suggest several candidates:
+
+- OpenBao in `railiance-platform`
+- the forge workload in `railiance-forge`
+- multiple S5 workloads in `railiance-apps`
+
+But they are not equally ready for first extraction.
+
+## Decision
+
+The first-wave `rapp-*` order is:
+
+1. `rapp-openbao`
+2. `rapp-vergabe-teilnahme`
+3. later `rapp-forgejo` after the forge runtime target stabilizes
+
+The forge workload is explicitly deferred from the first wave because current
+Gitea operation and future Forgejo direction are both active realities.
+
+## Consequences
+
+### Positive
+
+- The first `rapp-*` extraction proves the third-party platform-service wrapper
+  model.
+- The second proves the user-facing self-built app wrapper model.
+- The deferred forge wrapper avoids immediate rename churn and packaging
+  ambiguity.
+
+### Required Follow-On Work
+
+- Write repo-local extraction work for `rapp-openbao`.
+- Write repo-local extraction work for `rapp-vergabe-teilnahme`.
+- Reassess the forge wrapper when the production package target is no longer
+  split between current Gitea and future Forgejo.
+
+### Constraints
+
+- `rapp-*` repos must stay packaging-focused and must not become shadow
+  ownership repos.
+- Shared S3 policy stays in `railiance-platform`.
+- Shared S5 release patterns stay in `railiance-apps`.
+
+## Notes
+
+This ADR chooses sequence, not a mandatory destination for every workload in the
+ecosystem.

docs/adr/ADR-0004-first-wave-reef-rollout.md

@@ -0,0 +1,61 @@
+# ADR-0004: First-Wave `reef-*` Rollout
+
+Date: 2026-07-25
+Status: Accepted
+
+## Context
+
+Railiance now has a reef model, but it needs a concrete first rollout.
+
+The current substrate reality is not uniform:
+
+- Railiance01 is the clearest new-workload home
+- CoulombCore is still active but transitional
+- the workstation role is operator edge compute rather than server substrate
+
+At the same time, S1 ownership is ambiguous because `railiance-hosts` and
+`railiance-infra` duplicate each other.
+
+## Decision
+
+The first-wave reef rollout is:
+
+1. `reef-railiance01`
+2. `reef-coulombcore`
+3. `reef-ops-workstations`
+
+`railiance-infra` is the canonical S1 ownership repo going forward.
+
+`railiance-hosts` is treated as predecessor or duplicate state to be retired,
+frozen, or reduced later rather than as a second canonical S1 architecture home.
+
+## Consequences
+
+### Positive
+
+- Railiance gets a primary home-reef seed without waiting for a multi-node
+  future.
+- Transitional CoulombCore reality is acknowledged without being treated as the
+  long-term preferred production pattern.
+- Operator edge compute is modeled without defaulting to one repo per machine.
+- Reef planning now rests on one canonical S1 ownership line.
+
+### Required Follow-On Work
+
+- Create repo-local rollout work for the first reef repos.
+- Decide whether Railiance01 later remains a singleton reef or becomes part of
+  a grouped home reef.
+- Plan the `railiance-hosts` cleanup direction relative to `railiance-infra`.
+
+### Constraints
+
+- Multi-rail reefs are acceptable early, especially on transitional substrates.
+- Production-grade separation should still prefer clearer purpose and primary
+  rail boundaries as criticality rises.
+- Transitional substrate nicknames should remain provisional until the pattern
+  is stable enough to canonize.
+
+## Notes
+
+This ADR chooses the first rollout set. It does not require that every future
+substrate be modeled the same way.