Establish Railiance Fabric graph model

SCOPE.md

@@ -0,0 +1,139 @@
+# 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
+
+Defines the Railiance ecosystem graph model so repos can declare services,
+capabilities, interfaces, dependencies, and bindings in source-controlled files.
+
+---
+
+## Core Idea
+
+Railiance Fabric turns implicit cross-repo dependencies into a reviewable graph.
+Participating repos remain the source of truth for what they provide and
+consume; this repo owns the shared schema, validation rules, graph construction,
+query tooling, seed examples, and export format that State Hub can ingest as a
+read model.
+
+---
+
+## In Scope
+
+- YAML declaration schemas for services, capabilities, interfaces,
+  dependencies, and binding assertions.
+- Capability and interface type catalogs for the Railiance ecosystem.
+- Seed declarations for core Railiance providers and consumers.
+- Local graph loading, validation, discovery queries, and export tooling.
+- State Hub ingestion contract for graph exports.
+- Adoption guidance for adding declarations to other repos.
+
+---
+
+## Out of Scope
+
+- Deployment orchestration or GitOps ownership.
+- Replacing State Hub workstreams, tasks, decisions, or progress events.
+- Replacing repo-scoping, SCOPE.md, ADRs, service meshes, secret managers, or
+  authorization engines.
+- Making State Hub the authoring surface for capability declarations.
+- Runtime traffic discovery that bypasses repo-owned declarations.
+
+---
+
+## Relevant When
+
+- You need to declare what a Railiance repo provides or consumes.
+- You need to ask which services depend on a capability or interface.
+- You need to validate missing providers, stale interfaces, or compatibility
+  issues before sequencing work.
+- You need a graph export that State Hub can display without owning the source
+  declarations.
+
+---
+
+## Not Relevant When
+
+- You are deploying infrastructure rather than modeling its ecosystem contract.
+- You need to manage State Hub tasks, decisions, messages, or progress events.
+- You need service-specific implementation details owned by another repo.
+- You need an authorization, secret-management, or package-registry runtime.
+
+---
+
+## Current State
+
+- Status: active planning
+- Implementation: intent and first workplan present
+- Stability: evolving
+- Usage: internal Railiance ecosystem modeling
+
+The first workplan is `RAIL-FAB-WP-0001`, which establishes vocabulary, schema,
+seed examples, validator/query tooling, and State Hub integration.
+
+---
+
+## How It Fits
+
+- Upstream dependencies: repo-owned declarations in participating Railiance
+  repos.
+- Downstream consumers: State Hub read model, documentation, dashboards, and
+  agent planning flows.
+- Often used with: `repo-scoping`, `the-custodian/state-hub`,
+  `railiance-platform`, `net-kingdom`, `flex-auth`, and `artifact-store`.
+
+---
+
+## Terminology
+
+- Preferred terms: repository, service, capability, interface, dependency,
+  binding.
+- Also known as: ecosystem graph, capability graph, dependency graph.
+- Potentially confusing terms: State Hub is the read/cache/index layer here,
+  not the authoring source for declarations.
+
+---
+
+## Related / Overlapping Repositories
+
+- `repo-scoping` — explains what a repo is useful for; Railiance Fabric models
+  what repos provide and consume.
+- `the-custodian/state-hub` — coordinates domains, workstreams, tasks, and
+  progress; it should ingest Fabric graph exports as a read model.
+- `railiance-platform` — deploys shared platform services that should become
+  graph provider nodes.
+- `net-kingdom` — owns identity, credential, and security architecture that
+  appears in capability/interface declarations.
+- `flex-auth` — owns authorization policy and decision semantics that should be
+  represented as graph capabilities and interfaces.
+
+---
+
+## Getting Oriented
+
+- Start with: `INTENT.md`
+- Key files / directories: `workplans/`
+- Entry points: `workplans/RAIL-FAB-WP-0001-ecosystem-graph-model.md`
+
+---
+
+## Provided Capabilities
+
+```capability
+type: tooling
+title: Railiance ecosystem graph model
+description: Shared declaration schema, validation model, query tooling, and State Hub export contract for Railiance service/capability/dependency graphs.
+keywords: [railiance, graph, capabilities, dependencies, interfaces, state-hub]
+```
+
+---
+
+## Notes
+
+Repos own declarations. Railiance Fabric owns graph semantics and validation.
+State Hub owns coordination and display of ingested read models.