# 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.