docs: sync README ports, teach the skill to read the envelope, record DX-gap resolutions

[burrows99]

Documentation sync following the emit/fail-loudly work in #5, #6, #7. Docs-only — no source changes.

Changes

README.md — fix Docker Compose port drift: dashboard :14747, Postgres :65432, S3 :19000 (console :19001), and the matching S3_ENDPOINT. (Doc-side of DX-gap #5, "port story inconsistent.")

skills/trace/SKILL.md — add a "Reading the result — don't mistake an empty trace for a clean pass" section. The CLI now makes failure/completeness legible in the JSON envelope; this teaches an agent to actually read it: ok (mirrors exit code), diagnostics[] (stable codes; warn does not flip ok, so ok:true + events:[] + a warn = ran-but-saw-nothing), and meta.running (a partial mid-run envelope; a stuck "running" means the run never finished). Directly addresses the cross-cutting theme of the gaps doc.

docs/agent-dx-gaps.md — the DX-gaps analysis (minted from a real debugging session) is now a resolved record: the analysis is kept verbatim as rationale, with a status banner + table and a per-gap resolution note pointing to where each was closed. Status:

• feat(graph): LSP code-graph provider + Chrome auto-launch, slimmer CLI #1 collector 400-for-everything → ✅ 413 / 400 INGEST_INVALID / 400 INGEST_NO_SESSION / 503 STORE
• Welcome to trace-cli Discussions! #2 emit failures swallowed → ✅ rich EmitResult + Diagnostic.warn(Code.EMIT, …) (fix(collector): make trace failures self-explanatory in the JSON envelope #5/fix(collector): bound emit failure memory and word network failures accurately #6)
• Feat/non pausing logpoints #3 --concise looks like it shapes the wire → ✅ help text disclaims --emit
• docs: replace debug-replay video link with GIF #4 "0 hits" silent in JSON → ✅ BP_BOUND_UNHIT diagnostic
• fix(collector): make trace failures self-explanatory in the JSON envelope #5 port story → ◐ serve prints the --emit URL; open: no lockfile for non-default-port auto-discovery
• fix(collector): bound emit failure memory and word network failures accurately #6 silent empty / stuck-"running" → ◐ terminal abort envelope + RECORD_EMPTY/UPLOAD diagnostics (fix(trace): make empty/aborted runs fail loudly instead of silently "running" #7); open: dashboard age-out (#6b), done/upload decoupling (#6c)

🤖 Generated with Claude Code

[Copilot]

⚠️ Not ready to approve

The new DX-gaps doc includes brittle/now-inaccurate file:line references (e.g. Cli.ts:123) that should be adjusted (remove line numbers or link to a permalink) to avoid misleading readers.

Pull request overview

Docs synchronization following the recent “emit/fail-loudly” work: updates user- and agent-facing documentation to reflect the current port mappings and to teach consumers how to interpret the Trace JSON envelope (especially “empty but ok” and mid-run meta.running envelopes), plus records the DX-gap analysis with resolution pointers.

Changes:

• Update README Docker Compose port/S3 endpoint documentation to match current mappings.
• Extend the trace agent skill doc with explicit guidance on interpreting ok, diagnostics[], and meta.running.
• Add a resolved “DX gaps” record documenting what was misleading and where each gap was closed (or remains partially open).

File summaries

File	Description
README.md	Sync Compose port and S3_ENDPOINT documentation with current docker-compose mappings.
skills/trace/SKILL.md	Teach agents to evaluate envelope completeness via ok, diagnostics[], and meta.running rather than exit code alone.
docs/agent-dx-gaps.md	Add a resolved DX-gap record with status table and narrative rationale/snippets.

Copilot's findings

• Files reviewed: 3/3 changed files
• Comments generated: 1

Note

Your feedback helps us improve the quality of this feature.
Please use 👍 or 👎 to tell us whether this assessment is correct.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.