railiance-fabric/docs/registry-onboarding.md

Registry Onboarding

Multi-repo onboarding uses an operator-owned manifest to register ecosystem repositories with a running Railiance Fabric registry and to push graph and library inventory when the local checkout has the required inputs.

Repo-local declarations remain useful self-description evidence. They should not be treated as the default authority for external fabric membership, ownership, tenant boundaries, or cross-boundary utility relations. Those belong to the accountability-root discovery model described in docs/FabricDiscoveryAndUpdate.md.

Run The Railiance Manifest

Start the registry:

railiance-fabric-registry --db .railiance-fabric/registry.sqlite3 --port 8765

Sync the known local Railiance ecosystem repos:

railiance-fabric registry sync-manifest registry/railiance-repos.yaml

Sync every active State Hub repo that is available on this local host:

railiance-fabric registry sync-manifest registry/local-repos.yaml

Use --json for automation and --strict when unavailable repos or invalid inputs should fail the command.

Manifest Shape

apiVersion: railiance.fabric/v1alpha1
kind: RegistryOnboardingManifest
registry_url: http://127.0.0.1:8765
repositories:
  - slug: railiance-fabric
    name: railiance-fabric
    path: ..
    default_branch: main
    state_hub_repo_id: 2c0de614-e468-4eb6-8157-470649ac8c05
    repo_family: ownership
    declaration_paths:
      - ..
    sbom: bom.json

path is the local checkout used for git metadata, default graph discovery, and repo-family relation projection when the registry later needs to reopen repo-local rail, rapp, or reef files. 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.

The following repo-family metadata fields are also optional:

• repo_family: ownership, rail, rapp, or reef
• ownership_repo: canonical owning railiance-* repo when the registered repo is not itself an ownership repo
• primary_rail: default rail for a reef or package when one is explicitly declared
• supported_rails: array of supported rail ids for rapp-* repos
• substrate_kind: grouped substrate category such as server, server-group, workstation-group, or cluster

sbom or sboms may point to CycloneDX JSON/YAML files. When present, the command ingests them as queryable library inventory after repository registration.

Onboarding Behavior

Each repository entry is registered first. If the checkout is unavailable or has no Fabric declarations yet, the command leaves the repo registered and reports a warning. This lets the registry represent known repos before every repo has published local evidence.

For rail-*, rapp-*, and reef-* repos, registration-only entries still matter: the registry stores the checkout path and repo-family metadata, and the graph export can use the conventional repo-local declaration files to project first-wave governed_by, supports_rail, hosts_rail, and binds_rapp edges even when the repo does not yet publish native Fabric declarations.

When declarations exist, the command validates them, builds a graph snapshot, and posts it to:

POST /repositories/{repo_slug}/snapshots

The first Railiance manifest keeps the seed ecosystem graph in railiance-fabric and registers adjacent repos as known sources. As discovery roots mature, adjacent repos can contribute local evidence without making each repo responsible for the whole external fabric relation model.

registry/local-repos.yaml is a broader local-host manifest. It is generated from active State Hub repo records whose local path exists on the current WSL host. It registers cross-domain local repos into the Fabric registry while only syncing graph snapshots for repos that already have Fabric declarations.

When two active repo records point at the same checkout path, accountability root discovery treats them as aliases of one repository identity. The canonical identity can be declared with canonical_slug; otherwise discovery prefers the slug matching the checkout directory name and then the entry with a remote URL. Use split_identity: true only when shared paths are intentional and should remain separate review candidates.