Plan: Refactor foc-devnet: agent-first, legible, footgun-free

## Why

foc-devnet is likely to be increasingly driven by AI agents so a command's stdout should be viewed as the primary interface. This also obviously benefits humans arriving cold. Today the stdout interface is poor: output is unstructured trace spam, failures are opaque (`clean` can die with a bare `PermissionDenied` on Docker's own root-owned files), and the init->build->start lifecycle isn't discoverable from `--help`. The code has also drifted into 12 startup steps spread across 83 files, which makes it slow to change. This issue tracks making the CLI clear, recoverable, and easier to move forward on.

**Guiding principle: every command's output is agent context.** Say what happened, name the paths that matter, state what phase we're in, point at the next command, and be honest about damage and edges.

## User-facing changes

**Recovery / self-service**
- `clean` self-heals the root-owned files Docker leaves behind instead of failing opaquely; lifecycle commands become retry-safe; poison is explained and cleared predictably.
- New `doctor` command: checks Docker, `host.docker.internal`, basedir ownership, ports, disk, poison, and binaries, with `--fix` for the safe repairs.

**Orientation**
- New `foc-devnet system-context` prints a compact primer (what the devnet is, components, protocol, footguns) so a cold agent gets competent before acting; `--help` points to it.

**Legible output**
- `status` gains a phase line (built / running+run_id / poisoned) with source refs and the suggested next command.
- `--output json` with a stable error `kind` and a stable exit-code contract, so agents and CI can branch deterministically.
- Each run writes a `run-summary.json` handoff so the next agent resumes from one artifact.

**Fewer lifecycle surprises**
- `--help` ordered init->build->start->..., with honest command and flag descriptions.
- `start` refuses to clobber a running cluster (opt-in override). **Breaking.**
- Portainer becomes opt-in and is torn down by `stop`.
- Artifact-preserving reinit (keep proof params, binaries, builder cache).

**Testing ergonomics**
- Scenarios can run against a local Synapse worktree without patching the harness.
- `fund-user` / larger default deposit to unblock piece-heavy tests.

**Documentation**
- Consolidate the split README / README_ADVANCED into one README, plus a self-contained `SYSTEM-CONTEXT.md` (the primer the command prints) and a checked-in `AGENTS.md`, each readable from a bare clone.

## What it looks like

Illustrative target output, not current behavior.

### `--help` (lifecycle-ordered, self-describing)

```
$ foc-devnet --help
Local Filecoin devnet for FOC integration testing.

Lifecycle: init -> build -> start -> stop/clean
Re-initializing requires `clean` first. State lives under
$FOC_DEVNET_BASEDIR (default ~/.foc-devnet).

Commands:
init Clone repos, generate keys, stage proof params, build Docker images
build Compile Lotus or Curio from the configured sources
start Bring up the cluster (5-10 min); writes devnet-info.json
status Show phase, run_id, sources, and the next command
doctor Check environment and known sharp edges; --fix repairs safe ones
system-context Print the primer: what the devnet is and how the pieces fit
stop Stop containers, keep state on disk
clean Remove run state (self-heals Docker-owned files; keeps config + images)
version Show build/version info
config Show resolved configuration
requirements Check/set up Docker prerequisites

Options:
--output Output format (default: human)
-h, --help
```

### A cold agent recovers and reaches a working devnet

```
$ foc-devnet status
Phase: poisoned (a prior command failed mid-run)
Basedir: /mnt/nvme2/foc-devnet
Recover: foc-devnet clean (clears poison, self-heals Docker-owned files)

$ foc-devnet doctor
ok Docker reachable, user in docker group
ok host.docker.internal present
FAIL Basedir has root-owned files: docker/volumes/cache/foc-builder
fix -> foc-devnet doctor --fix (or `clean`, which self-heals)
ok Ports 5700-5800 free
ok Free disk 812 GiB
warn Poison present -> `clean` clears it
ok Required binaries present in bin/

$ foc-devnet clean
Cleaned run state. Kept config.toml and cached images.
Self-healed 3 root-owned paths under docker/volumes/cache.
Cleared poison.
Next: foc-devnet start

$ foc-devnet start
[step 7/12] deploy FOC contracts ... done (128s)
...
Phase: running (run_id=20260701T1042_TizzyMoo)
devnet-info: /mnt/nvme2/foc-devnet/state/latest/devnet-info.json
run-summary: /mnt/nvme2/foc-devnet/state/latest/run-summary.json
Next: python3 scenarios/run.py or foc-devnet status
```

### The same, machine-readable (`--output json`)

Agents branch on `kind` and exit code instead of grepping prose.

```
$ foc-devnet start --output json # transient chain error, exit 5
{"command":"start","status":"error","phase":"multicall3_deploy",
"kind":"chain_actor_unavailable","error":"actor not found: validation failure",
"advice":"f4 activation delay; retry in ~5s","logs":".../run//setup.log"}

$ foc-devnet start --output json # cluster already up, exit 3
{"command":"start","status":"error","kind":"cluster_running",
"run_id":"20260701T1042_TizzyMoo",
"advice":"stop it, use a different FOC_DEVNET_BASEDIR, or pass --force"}
```

### `start` no longer silently clobbers a running cluster

```
$ foc-devnet start
Error: a cluster is already running (run_id=20260701T1042_TizzyMoo).
Stop it: foc-devnet stop
Isolate: FOC_DEVNET_BASEDIR=/mnt/nvme2/other foc-devnet start
Override: foc-devnet start --force (tears down the running cluster)
```

## Internal cleanup (not user-facing)

Collapse the step-module sprawl, delete dead code, and unify the sequential/parallel step DAG, which also fixes a live bug: the default `start` currently skips the prerequisites check that `--parallel` runs.

This is a broad plan spanning the CLI lifecycle, Docker recovery, output contracts, scenarios, and documentation. Start by running the current foc-devnet --help and lifecycle commands, then read README, README_ADVANCED, scenarios/run.py, and the proposed SYSTEM-CONTEXT.md and AGENTS.md. Done requires the listed recovery, orientation, legibility, lifecycle, testing, and documentation behaviors to be implemented and verified.

Written by the indexing model from the issue text.