From 08848aaccbdc3415bcde98b6829c81597ee5d752 Mon Sep 17 00:00:00 2001 From: burrows99 Date: Fri, 19 Jun 2026 09:09:07 +0100 Subject: [PATCH] docs: sync README ports + teach the skill to read the result envelope MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keep the prose docs in step with the behavior changes from the collector/trace fixes (#5–#7). - README: the docker-compose section showed the container ports (:4747 · :5432 · :9000) instead of the host-published ports the compose file actually maps. Correct to :14747 · :65432 · :19000 (console :19001), and the S3_ENDPOINT example to :19000, so the README matches docker-compose.yml. The native-serve example keeps :5432 (your own Postgres) — that one was right. - skills/trace/SKILL.md: add a "Reading the result" section. The skill is deliberately minimal (the binary is the source of truth), but it gave zero guidance on interpreting a trace — the gap behind an agent treating an empty or perpetually-"running" trace as success. Names the three stable fields that decide whether a run did what was asked (ok · diagnostics[].code · meta.running) and the rule that ok:true + events:[] + a warn diagnostic means "ran fine, saw nothing — re-aim," not success. Field-level (no drift-prone code list). --- README.md | 4 ++-- skills/trace/SKILL.md | 10 ++++++++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f918b42..85e7ea7 100644 --- a/README.md +++ b/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 ``` diff --git a/skills/trace/SKILL.md b/skills/trace/SKILL.md index 6996074..5458551 100644 --- a/skills/trace/SKILL.md +++ b/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 --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.