Establish Railiance Fabric graph model

docs/validator.md

@@ -0,0 +1,40 @@
+# Validator
+
+The first validator entry point is:
+
+```bash
+railiance-fabric validate <repo-or-file>...
+```
+
+It accepts:
+
+- a repo root containing `fabric/`
+- a `fabric/` directory
+- one or more declaration YAML files
+
+The validator currently checks:
+
+- YAML load errors
+- declaration schema conformance
+- duplicate graph IDs
+- unknown capability and interface types
+- missing service, capability, interface, dependency, and binding references
+- missing provider capabilities for dependencies
+- binding provider/dependency capability type mismatches
+- active production dependencies without `metadata.source_links`
+- active production dependencies whose providers do not cover the environment
+- service dependency cycles from binding assertions
+
+Exit behavior:
+
+- exits `0` when there are no errors
+- exits `1` when errors are present
+- exits `1` for warnings only when `--warnings-as-errors` is used
+
+Examples:
+
+```bash
+PYTHONPATH=. python -m railiance_fabric.cli validate .
+PYTHONPATH=. python -m railiance_fabric.cli validate fabric/
+PYTHONPATH=. python -m railiance_fabric.cli validate examples/declarations/invalid/*.yaml
+```