# Maintain & diagnose

runward update keeps a mission current, runward doctor diagnoses the setup, runward status shows where it stands, runward explain reads a rule, and the global flags.

## Keep a mission current: `runward update`

`runward update` refreshes the shipped method under `runward/workflows/`, the [craft rules](https://runward.dev/docs/en/reference/rules/) under `runward/rules/`, and the [gate adapter samples](https://runward.dev/docs/en/operating/wire-the-gate/) under `runward/adapters/`, pulling each from the installed runward package. Run it after upgrading the package, so your mission gates against the current rules and follows the current workflows.

It is deliberately conservative:

- **It never touches mission state.** Your `framing.md`, architecture note, ADRs and governance files are left exactly as they are.
- **It preserves your local edits.** A file you changed is reported as `drift (locally modified)` and skipped, not overwritten. Pass `--force` to replace drifted files with the package version.
- **It reports what changed.** Each file is counted as up to date, added, or drifted.
- **Exit `2`** if there is no `runward/` mission here (run `runward init` first). Preview everything with `runward --dry-run update`.

Because `update` can change the rules your gate enforces, read the diff before you re-run `runward check --strict`.

## Diagnose the setup: `runward doctor`

`runward doctor` runs three self-checks and prints a report:

- **Environment** — Node >= 20 and git present.
- **Package integrity** — the mission templates, the workflow set, the expected rule and adapter counts, and the rule-mapping floors are all intact.
- **This directory** — whether you are in a mission root, whether `AGENTS.md` and git are present, and which tool profiles are detected.

> **Its exit codes are inverted, on purpose.** Unlike every other command (`0` clean, `1` gaps, `2` no mission / misuse), `doctor` uses `0` = all good, `1` = warnings, `2` = a critical failure, and it treats "no mission here" as a *warning*, not a hard `2`. An agent that branches on exit codes uniformly should special-case `doctor`.

## See where a mission stands: `runward status`

`runward status` is the "where am I" snapshot, and the natural first command for a team receiving a mission. It reads, and changes nothing. It prints:

- the mission title and the **current gate**;
- **phase progress** across the gated arc, gate by gate, with a `← you are here` marker;
- the **decision journal** (ratified ADRs) and recent activity;
- a warning if an expected workflow is missing.

## Read a rule before you apply it: `runward explain`

Before applying or deviating from a craft rule, read its contract:

```bash
runward explain <rule>          # impact, phases, the "why", the evidence signature, full body
runward explain <rule> --json   # the same, as a machine contract for an agent
```

To narrow the catalog to one phase, filter it:

```bash
runward rules --phase floor     # architect | topology | floor | govern
runward rules --json            # the whole set as a versioned, additive contract
```

## Advisory coverage: `check --coverage`

`runward check --coverage` reports a deliverables-filled ratio, the count of ratified decisions, and the list of unratified ADRs. It is **advisory** and never gates: use it to see how far a mission has come, not to pass or fail it.

## Operator hooks: `runward/hooks.json`

You can have your own commands run around the audit. Create `runward/hooks.json`:

```json
{
  "pre":  ["npm run lint"],
  "post": ["./scripts/notify.sh"]
}
```

`pre` commands run before the audit, `post` after. They run **only** when you pass `runward check --hooks`: runward's own gate never runs them, so cloning a repo never executes anything by surprise. Under `--json`, hook output is routed to stderr so it cannot corrupt the single JSON object on stdout.

## Global flags

These apply to any command:

- `--dry-run` — print the planned writes without touching disk (same as `RUNWARD_DRY_RUN=1`).
- `--verbose` — print full error stack traces when something goes wrong (same as `VERBOSE=1`).
- `--no-color` — disable coloured output, useful in logs and non-TTY environments.

## See also

- [CLI commands](https://runward.dev/docs/en/reference/cli/)
- [Wire the gate](https://runward.dev/docs/en/operating/wire-the-gate/)
- [Rule catalog](https://runward.dev/docs/en/reference/rules/)
- [Resume an existing system](https://runward.dev/docs/en/operating/resume-existing/)