Start rail/rapp/reef fabric adaptation

docs/declaration-schema.md

@@ -87,6 +87,13 @@ Optional relationship fields:
 
 Schema: `schemas/service.schema.yaml`
 
+Recommended compatibility-first `spec.service_type` values for the new
+Railiance repo families are:
+
+- `execution-rail`
+- `managed-workload-package`
+- `substrate-boundary`
+
 ### CapabilityDeclaration
 
 A stable semantic ability that consumers depend on.
@@ -163,6 +170,22 @@ Schema: `schemas/dependency.schema.yaml`
 type catalogs. Unknown types are allowed by the document schema but should fail
 graph validation.
 
+## Repository-Family Starter Guidance
+
+Until stronger repo-family metadata exists in registry and export projections,
+future repo-local declarations should start with these minimal shapes:
+
+- `rail-*`: one `ServiceDeclaration` using `spec.service_type:
+  execution-rail`, plus one `CapabilityDeclaration` using
+  `spec.capability_type: workload-execution-contract`
+- `rapp-*`: one `ServiceDeclaration` using `spec.service_type:
+  managed-workload-package`
+- `reef-*`: one `ServiceDeclaration` using `spec.service_type:
+  substrate-boundary`
+
+This is a compatibility-first convention, not a claim that the full repo-family
+graph model is complete.
+
 ### BindingAssertion
 
 A source-controlled assertion that resolves a dependency to a provider

docs/rail-rapp-reef-adaptation.md

@@ -0,0 +1,100 @@
+# Rail Rapp Reef Adaptation
+
+Date: 2026-07-25
+
+## Purpose
+
+Define the first compatibility-first Fabric conventions for the new
+`rail-*`, `rapp-*`, and `reef-*` repo families without pretending the registry
+or export model is already fully adapted.
+
+This document is intentionally narrower than the framework architecture in
+`railiance-master`. It answers one question:
+
+> What should Fabric accept and publish first so the new repo families can
+> start existing as graph entities?
+
+## Immediate Compatibility Stance
+
+The first adaptation wave is deliberately small:
+
+- onboard the missing current Railiance repos in the seed manifest
+- add the first rail-specific capability type
+- define canonical `service_type` values for future declarations
+- avoid inventing full repo-family metadata or new export relations before the
+  first repos exist
+
+This keeps Fabric aligned with the architecture without forcing a premature
+schema redesign.
+
+## Canonical First-Use Conventions
+
+### `rail-*`
+
+Initial Fabric shape:
+
+- one `ServiceDeclaration` with `spec.service_type: execution-rail`
+- one `CapabilityDeclaration` with
+  `spec.capability_type: workload-execution-contract`
+
+Typical evidence should describe:
+
+- the execution architecture
+- substrate prerequisites
+- rollout modes or workload lifecycle expectations
+- which ownership repo governs the rail
+
+### `rapp-*`
+
+Initial Fabric shape:
+
+- one `ServiceDeclaration` with `spec.service_type: managed-workload-package`
+
+Optional follow-on declarations may later capture runtime dependencies,
+verification interfaces, or artifact evidence, but the first requirement is
+simply to make the package queryable as a distinct ecosystem entity.
+
+### `reef-*`
+
+Initial Fabric shape:
+
+- one `ServiceDeclaration` with `spec.service_type: substrate-boundary`
+
+The first declarations should make the substrate boundary visible before Fabric
+tries to model every machine or placement relation in detail.
+
+## First New Capability Type
+
+Fabric now reserves:
+
+- `workload-execution-contract`
+
+Meaning:
+
+- a stable execution contract that workloads depend on
+- usually published by a `rail-*` repo
+- expected to expose Kubernetes-, rollout-, or runtime-facing interfaces over
+  time
+
+This is intentionally rail-focused. `rapp-*` and `reef-*` can start with
+service-level visibility before they need their own dedicated capability types.
+
+## What Is Still Missing
+
+The following are not done by this adaptation slice:
+
+- repo-level `repo_family` metadata in the registry
+- `ownership_repo`, `supported_rails`, `primary_rail`, or `substrate_kind`
+  registry metadata
+- export relations such as `supports_rail`, `hosts_rail`, `binds_rapp`, or
+  `governed_by`
+- validator rules for repo-family-specific declaration completeness
+
+Those require a second wave after the first real `rail-*`, `rapp-*`, and
+`reef-*` repos exist.
+
+## Outcome
+
+Fabric can now move from "the new repo families exist only in architecture
+docs" to "the registry and declaration guidance are ready for the first repo
+instances" without overcommitting to a premature graph redesign.

docs/registry-onboarding.md

@@ -54,6 +54,10 @@ repositories:
 `declaration_paths` is optional; when omitted, the repo path is scanned for a
 `fabric/` directory. Relative paths are resolved from the manifest file.
 
+`state_hub_repo_id` is optional. Include it when known so registry consumers can
+link back to State Hub repo views, but do not block onboarding when a repo is
+registered in Fabric before that ID is wired in here.
+
 `sbom` or `sboms` may point to CycloneDX JSON/YAML files. When present, the
 command ingests them as queryable library inventory after repository
 registration.

docs/type-catalog.md

@@ -25,6 +25,7 @@ Machine-readable catalog files:
 | `redis-compatible-cache` | active | medium | internal | `database-connection`, `kubernetes-secret` |
 | `object-storage` | planned | high | confidential | `object-storage-bucket`, `http-api` |
 | `object-storage-credential-vending` | planned | high | secret | `http-api`, `openbao-dynamic-credential-role`, `sts-token` |
+| `workload-execution-contract` | planned | high | internal | `kubernetes-api`, `kubernetes-crd`, `helm-release` |
 | `audit-event-sink` | planned | high | confidential | `event-stream`, `http-api` |
 | `scope-generation` | active | medium | internal | `cli`, `http-api` |
 | `coordination-read-model` | active | high | internal | `http-api`, `event-stream` |