Establish Railiance Fabric graph model

README.md

@@ -1,3 +1,51 @@
-# repo-seed
+# Railiance Fabric
 
-A git repository template to bootstrap coulomb projects from.
+Railiance Fabric defines the repo-owned declaration model for the Railiance
+ecosystem graph.
+
+It will hold schemas, seed declarations, validation tools, graph queries, and
+State Hub export contracts for services, capabilities, interfaces,
+dependencies, and bindings across Railiance repositories.
+
+## Validate Declarations
+
+From a checkout with the Python dependencies installed:
+
+```bash
+railiance-fabric validate .
+```
+
+During early bootstrapping, the local module entry point works too:
+
+```bash
+PYTHONPATH=. python -m railiance_fabric.cli validate .
+```
+
+The validator loads `fabric/` declarations, checks schema conformance, verifies
+catalog type names, catches missing references/providers, checks active
+production dependency source links, and warns about dependency cycles.
+
+## Query The Graph
+
+```bash
+railiance-fabric providers runtime-secrets
+railiance-fabric consumers railiance-platform.openbao.kv-v2
+railiance-fabric dependency-path flex-auth.api
+railiance-fabric unresolved
+railiance-fabric blast-radius openbao-kv-v2-mount
+railiance-fabric export --format json
+railiance-fabric export --format mermaid
+```
+
+See `docs/discovery-queries.md` for command details.
+
+## Adopt In Another Repo
+
+See `docs/adoption-guide.md` for the declaration workflow and
+`docs/first-rollout.md` for the initial Railiance repo rollout.
+
+## Next: Ecosystem Registry Service
+
+See `docs/ecosystem-registry-service.md` for the standards comparison and
+service direction for registering repos and interacting with the combined
+ecosystem model.