ocpp-debugkit · sepehr-safari · Jul 12, 2026 · Jul 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,54 @@
+# Changelog
+
+All notable changes to OCPP DebugKit Studio are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This
+project is pre-1.0: while Zig, the Native SDK, and the toolkit conformance
+reference are all pre-1.0, minor (0.x) releases may include breaking changes.
+
+## [Unreleased]
+
+The upcoming **0.5.0** — Studio's first packaged, signed public release,
+assembled across milestones S0–S5. Highlights:
+
+### Added
+
+- **Engine** — a pure-Zig, headless OCPP 1.6J engine: canonical event / session /
+  failure model, a trace parser (JSON object, JSONL, and bare-array formats with
+  untrusted-input limits), timestamp + direction normalization, and
+  `transactionId` session correlation.
+- **Detection** — the full 16-rule OCPP 1.6J failure taxonomy, conformant with the
+  TypeScript toolkit and locked to the `contract-v1` goldens (15/15 scenarios).
+- **Inspector** — a native window with a virtualized event timeline (smooth past
+  500k events), a message inspector (raw OCPP-J array, normalized fields, a
+  bounded payload disclosure tree), a session-correlation panel, a ranked failure
+  drawer with remediation steps, and search / filter facets. Traces open from
+  command-line paths, with a built-in sample.
+- **Analysis** — Markdown and self-contained HTML reports, anonymize-on-export
+  (redacts idTag / serials / stationId / identifier, resequences transaction ids,
+  and scrubs email / phone / IPv4 patterns), semantic trace diff, and a
+  deterministic step-through replay engine with a manual scrub transport.
+- **Live capture** — a live WebSocket MITM proxy between a charge point and its
+  CSMS (hand-rolled RFC 6455 subset): frames are relayed verbatim, decoded in
+  flight into canonical events, run through detection as they stream, and recorded
+  to the canonical trace format. Surfaced both in a live inspector timeline and
+  from the CLI; **OS notifications** fire on critical live failures.
+- **Headless CLI** — the same binary is a scriptable CLI: `inspect`, `report`
+  (markdown / html), `diff` (text / json), `anonymize`, `capture`, `ci`, and
+  `scenario`.
+- **Packaging** — macOS (`.dmg`, ad-hoc signed) and Linux (`.tar.gz`) packages via
+  `native package`, published by a tag-triggered release workflow.
+- **Conformance contract** — the Studio ⇄ toolkit contract frozen and documented
+  as `contract-v1` ([CONTRACT.md](docs/CONTRACT.md)), CI-gated on every change.
+
+### Known limitations
+
+- macOS builds are ad-hoc signed, not notarized (first launch needs
+  right-click → Open). Notarization is planned post-0.5.
+- Failure detection is capped at 50k events (several rules are O(n²)); larger
+  traces stay fully inspectable with detection skipped. The O(n) rewrite is
+  tracked upstream.
+- TLS (`wss://`) live capture, a menu-bar monitor, and interactive open
+  (dialog / drag-drop) are planned for later releases.
+
+[Unreleased]: https://github.com/ocpp-debugkit/studio/commits/main
diff --git a/CURRENT_STATE.md b/CURRENT_STATE.md
@@ -23,9 +23,11 @@ publishes both to a GitHub release (see [RELEASING.md](RELEASING.md)). The
 automation smoke now **drives** the GUI (#71) — clicking the replay transport,
 a filter facet, and the Live tab, asserting the semantics tree after each and
 screenshotting the inspector + live surfaces. The conformance contract is frozen
-as `contract-v1` (#72, [docs/CONTRACT.md](docs/CONTRACT.md), ADR-0012). Remaining:
-release-ready docs (#73) and the v0.5.0 cut (#74). The menu-bar monitor and
-notarization are post-0.5; see [ROADMAP.md](ROADMAP.md).
+as `contract-v1` (#72, [docs/CONTRACT.md](docs/CONTRACT.md), ADR-0012). The docs
+are release-ready (#73): the README is present-tense with install / usage and a
+live inspector screenshot, and a [CHANGELOG](CHANGELOG.md) stages the 0.5.0 notes.
+Remaining: the v0.5.0 cut (#74). The menu-bar monitor and notarization are
+post-0.5; see [ROADMAP.md](ROADMAP.md).
 
 ## What's done
 

diff --git a/README.md b/README.md
@@ -9,7 +9,7 @@
 
 Studio is built in [Zig](https://ziglang.org) on the [Native SDK](https://github.com/vercel-labs/native) — native-rendered, no browser, no Electron. It starts instantly, stays small, and does the things a browser tab fundamentally cannot: open raw sockets, watch the filesystem, and run for days as a background monitor.
 
-> 🚧 **Early development.** The foundation is in place (a native window, green CI on macOS + Linux, an automation-driven smoke test). The OCPP engine and inspector UI are next — see the [roadmap](ROADMAP.md).
+![The Studio inspector: a virtualized event timeline, message inspector with session correlation, and a failure drawer.](docs/assets/inspector.png)
 
 ## The ecosystem
 
@@ -22,26 +22,56 @@ Studio is one of two independent products under the OCPP DebugKit umbrella:
 
 The two share **no code**. They meet only at a *conformance contract*: the same trace format, the same normalized event model, the same failure taxonomy, and the same scenario fixtures. A trace captured in Studio opens in the toolkit's web inspector, and vice versa — two independent implementations, one format, checked in CI on every change. See **[the conformance contract](docs/CONTRACT.md)** (`contract-v1`) and [ADR-0001](docs/adr/0001-independent-implementation.md).
 
-## What it will do
+## What it does
 
-The near-term vision, in priority order (full detail in the [roadmap](ROADMAP.md)):
+- **Inspect** — open JSON / JSONL / bare-array traces in a virtualized timeline that stays smooth past **500k events**; unpack any message (raw OCPP-J array, normalized fields, a payload disclosure tree), see the session it correlates into, and search / filter by action, direction, type, or severity.
+- **Detect** — the full **OCPP 1.6J failure taxonomy** (16 rules), bit-for-bit conformant with the toolkit's reference, ranked critical → warning → info with remediation steps.
+- **Watch** — a **live WebSocket proxy** between a charge point and its CSMS: decode OCPP frames in flight, run detection as events stream, record to the canonical trace format, and get an **OS notification** the moment a critical failure appears.
+- **Prove** — Markdown / HTML reports, semantic trace diffing, anonymize-on-export, and step-through replay.
+- **Scale** — native performance with no GC; stream-parse traces far past what a browser tab can hold.
+- **Script** — the same binary is a headless CLI (`inspect` / `report` / `diff` / `anonymize` / `capture` / `ci`) for pipelines and automation.
 
-- **Inspect** — open JSON / JSONL / bare-array traces; virtualized timeline, per-message inspector, session correlation, failure list.
-- **Detect** — the full OCPP 1.6J failure taxonomy, streaming, as events arrive.
-- **Watch** — a live WebSocket proxy between charge point and CSMS, decoding OCPP frames in flight and recording them to the canonical trace format.
-- **Prove** — reports, trace diffing, anonymize-on-export, and wall-clock replay.
-- **Scale** — stream-parse traces far past what a browser tab can hold.
+## Install
 
-## Quick start
+Download the latest release for your platform from the
+[**Releases**](https://github.com/ocpp-debugkit/studio/releases) page.
 
-Studio is a source-first project during early development.
+- **macOS** — open the `.dmg` and drag *OCPP DebugKit Studio* to Applications. The
+  0.5.0 build is **ad-hoc signed** (not yet notarized), so the first launch needs
+  **right-click → Open** (or *System Settings → Privacy & Security → Open Anyway*).
+- **Linux** — extract the `.tar.gz` and run the `studio` binary. Requires GTK 4
+  (`libgtk-4`, `libwebkitgtk-6.0`).
 
-**Prerequisites**
+Studio is pre-1.0 (0.x) while Zig, the Native SDK, and the toolkit conformance
+reference are all pre-1.0 — see the [roadmap](ROADMAP.md).
 
-- [Zig](https://ziglang.org/download/) `0.16.0`
-- The Native SDK CLI: `npm install -g @native-sdk/cli`
+## Usage
 
-**Build and run**
+Open a trace in the GUI, or drive the headless CLI:
+
+```sh
+studio path/to/trace.json                      # open the inspector on a trace
+studio                                          # open with the built-in sample
+
+# Live capture: proxy a charge point ↔ CSMS session and stream it to a file
+studio capture --listen 127.0.0.1:9000 \
+               --upstream ws://csms.example:9000/ocpp --ndjson > session.jsonl
+
+# Headless analysis (stdout)
+studio inspect trace.json                       # a parsed + analyzed summary
+studio report trace.json -f html > report.html  # a full report (markdown | html)
+studio diff before.json after.json              # semantic diff of two traces
+studio anonymize trace.json > shareable.json    # strip sensitive fields
+studio ci                                        # run the conformance contract (exit 0/1)
+```
+
+Point your charge point (or the toolkit's tooling) at the `--listen` address and
+its traffic is proxied to `--upstream`, decoded, and recorded. Full CLI ⇄ toolkit
+parity is documented in [docs/cli-parity.md](docs/cli-parity.md).
+
+## Build from source
+
+**Prerequisites:** [Zig](https://ziglang.org/download/) `0.16.0` and the Native SDK CLI (`npm install -g @native-sdk/cli`).
 
 ```sh
 git clone https://github.com/ocpp-debugkit/studio.git
@@ -53,7 +83,8 @@ native build    # produce a ReleaseFast binary in zig-out/bin/
 native check    # validate src/*.native markup and app.zon
 ```
 
-The `native` CLI owns the build — there is no `build.zig` to manage.
+The `native` CLI owns the build — there is no `build.zig` to manage. To build a
+distributable package, see [RELEASING.md](RELEASING.md).
 
 ## Non-goals
 
@@ -65,7 +96,7 @@ Studio is a debugging instrument, not infrastructure. It is **not**:
 
 ## Contributing
 
-Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and point your tooling at [AGENTS.md](AGENTS.md) for a structured overview of the architecture and conventions. [CURRENT_STATE.md](CURRENT_STATE.md) tracks what is built and what is in progress.
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), and point your tooling at [AGENTS.md](AGENTS.md) for a structured overview of the architecture and conventions. [CURRENT_STATE.md](CURRENT_STATE.md) tracks what is built and what is in progress; [CHANGELOG.md](CHANGELOG.md) records what shipped in each release.
 
 ## Security
 

diff --git a/docs/assets/inspector.png b/docs/assets/inspector.png