docs: sync README host ports + teach the skill to read the result envelope

README.md

@@ -90,9 +90,9 @@ Any trace **auto-streams to a collector running locally** — no flag needed. Ov
 Docker Compose bundles the dashboard, Postgres, and a mock S3 for one-command local setup:
 
 ```bash
-docker compose up --build                # dashboard :4747 · Postgres :5432 · S3 :9000
+docker compose up --build                # dashboard :14747 · Postgres :65432 · S3 :19000 (console :19001)
 # then run the CLI natively from where your target is reachable; it auto-detects the collector
-export S3_ENDPOINT=http://localhost:9000
+export S3_ENDPOINT=http://localhost:19000
 trace-cli run --chrome 9222 --url http://localhost:3000 --breakpoint src/App.tsx:9
 ```
 

skills/trace/SKILL.md

@@ -34,3 +34,13 @@ trace-cli doctor            # which backing tools are installed (node, chrome, f
 ```
 
 - Start with `trace-cli manifest` (to reason over the options programmatically) or `trace-cli <command> --help` (for a quick look). Whatever you need to know about executing `trace-cli`, get it from there — not from this file.
+
+## Reading the result — don't mistake an empty trace for a clean pass
+
+The envelope **is** the result; read it, don't just check the exit code. Three fields decide whether a run did what you asked (full contract: `trace-cli schema`):
+
+- **`ok`** — `false` when a diagnostic is an error (engine aborted, a failed journey step, a malformed envelope); the exit code mirrors it.
+- **`diagnostics[]`** — each carries a stable `code` (the same vocabulary the stderr logs use, so you can join the two). **`warn`-level codes do *not* flip `ok`** — so a run can be `ok:true` and still have observed or recorded nothing: a breakpoint that *bound but never hit*, a Chrome run with no frames, or a recording/upload that failed. **Read `diagnostics` before concluding a trace succeeded.**
+- **`meta.running`** — `true` marks a *partial*, mid-run envelope (streamed to the collector while the run is in flight); it is absent on the finished trace. A dashboard session stuck on `running` means the run never finished (it aborted, or the final envelope never arrived) — not that it's still working.
+
+Rule of thumb: `ok:true` **+ `events: []` + a `warn` diagnostic** = the trace ran fine but saw nothing (wrong line, branch not taken, or the trigger never fired) — re-aim the breakpoint/trigger, don't report success.