# 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: bootstrapped first-wave grouped reef home
- Implementation: declaration, grouped substrate files, and retained-S1
  compatibility handoff are present
- Stability: evolving, with the migration-window split now explicit
- 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.