Add Railiance Stage 1 run command

docs/README.md

@@ -76,6 +76,7 @@ From two bare Linux servers, a Git repo, and valid credentials, you can rebuild
 - [Deployment lifecycle](deployment-lifecycle.md)
 - [Railiance app.toml contract](app-toml-contract.md)
 - [Railiance overlay repo pattern](overlay-repo-pattern.md)
+- [Railiance run command](railiance-run-command.md)
 
 ## 👥 Contributing
 

docs/railiance-run-command.md

@@ -0,0 +1,52 @@
+# Railiance Run Command
+
+`bin/railiance run` executes Stage 1 local validation for a repository that
+contains `railiance/app.toml`.
+
+The command is intentionally local and conservative:
+
+- reads `railiance/app.toml` using the `railiance.app.v1` contract;
+- runs `[stages.stage1].commands` from the app directory;
+- evaluates Stage 1 check ids listed in `[stages.stage1].checks` when they can
+  be checked locally;
+- emits a machine-readable `railiance.run-result.v1` JSON result;
+- records command references, exit codes, durations, and output byte counts,
+  but not shell text or command stdout/stderr content;
+- strips credentials, query strings, and fragments from URLs before reporting HTTP
+  check results.
+
+## Usage
+
+```bash
+bin/railiance run /path/to/app-or-overlay --pretty
+bin/railiance run . --json-out .railiance/stage1-result.json
+```
+
+The process exits `0` only when all Stage 1 commands and required checks pass.
+Optional checks may be skipped without failing the run. For example, an optional
+local health endpoint can be declared before a local server command exists.
+
+## Supported Local Checks
+
+- `command`: runs the check `run` command in the app directory.
+- `http`: calls the declared URL and compares the HTTP status.
+- `helm`: runs `helm template` when Helm is installed. Required Helm checks fail
+  if Helm is unavailable; optional Helm checks are skipped.
+
+Other check types are reported as skipped or failed depending on whether the
+check is required. Stage 2 and Stage 3 checks are never executed by
+`railiance run`.
+
+## Result Shape
+
+The JSON result includes:
+
+- app identity and source revision;
+- contract path and app directory;
+- command/check status summaries using contract references instead of raw shell
+  commands;
+- expected evidence labels from Stage 1;
+- timing and exit status metadata.
+
+The result is suitable for later promotion gates and State Hub progress notes,
+without embedding secrets or verbose logs.