docs: close contributor onboarding gaps and correct the v0.4.x release state

CONTRIBUTING.md

@@ -21,10 +21,12 @@ cd toolkit
 # Install dependencies
 pnpm install
 
-# Verify everything works
+# Verify everything works (same checks CI runs, in the same order)
 pnpm lint
-pnpm test
+pnpm format:check
+pnpm typecheck
 pnpm build
+pnpm test
 ```
 
 ## Monorepo Structure
@@ -80,12 +82,12 @@ compose these functions to provide the full analysis pipeline.
 | Parser | `src/core/parser.ts` | `parseTrace()` — JSON, JSONL, bare array |
 | Normalizer | `src/core/normalizer.ts` | Event normalization (timestamps, directions) |
 | Timeline | `src/core/timeline.ts` | `buildSessionTimeline()` — session correlation |
-| Detection | `src/core/detection.ts` | `detectFailures()` — 15 failure rules |
+| Detection | `src/core/detection.ts` | `detectFailures()` — failure detection rules |
 | Diff | `src/core/diff.ts` | `diffTraces()` — compare two traces |
 | Assertions | `src/core/assertions.ts` | `evaluateScenario()` — scenario assertions |
 | Summarizer | `src/core/summarizer.ts` | Session summary statistics |
 | Validator | `src/core/validator.ts` | OCPP 1.6 structural validation |
-| Scenarios | `src/scenarios/` | 15 predefined scenarios + registry |
+| Scenarios | `src/scenarios/` | Predefined scenarios + registry |
 | Reporter | `src/reporter/` | Markdown + HTML report generators |
 | Replay | `src/replay/` | Deterministic replay engine |
 | React | `src/react/` | Reusable UI components |
@@ -120,11 +122,17 @@ git checkout -b feat/<scope>-<description>
 
 ```bash
 pnpm lint
+pnpm format:check
 pnpm typecheck
-pnpm test
 pnpm build
+pnpm test
 ```
 
+These are the checks CI runs, in the same order, so a green run here means a
+green run there. CI stops at the first failure, which means a formatting problem
+masks every result after it. `pnpm format:check` only reports; run `pnpm format`
+to apply the fixes.
+
 ### 5. Add a Changeset
 
 If your PR changes publishable package behavior, add a changeset:
@@ -217,17 +225,26 @@ trace with expected failure outcomes and optional assertions.
 
 2. Import and register it in `packages/toolkit/src/scenarios/index.ts`.
 
-3. Update the scenario count in:
+3. Update the scenario count in every place that states it:
    - `packages/toolkit/src/scenarios/index.test.ts`
    - `tests/external-fixture/test.mjs`
+   - `README.md`
+   - `packages/toolkit/README.md`
+
+   The first two fail the test suite when they drift. The two READMEs do not, so
+   they are easy to miss.
 
-4. Run `ocpp-debugkit ci` to verify all scenarios pass.
+4. Run `ocpp-debugkit ci` to verify all scenarios pass, then run the full local
+   check from [Verify Locally](#4-verify-locally). `ocpp-debugkit ci` does not
+   cover formatting, lint, or types.
 
 ### Guidelines
 
 - All data must be **synthetic** — no real station IDs, transaction IDs, idTags,
   or personal data.
 - Use `SYNTHETIC-TAG-NNN` for idTags, `CS-SYNTHETIC-NNN` for station IDs.
+- Each scenario takes its own station ID. Check the existing files in
+  `__scenarios__/` for the next free number rather than reusing one.
 - `expectedFailures` must align with detection rules available in the current
   version.
 - Test your scenario with `ocpp-debugkit scenario run my-scenario`.
@@ -278,6 +295,16 @@ new contributors. They should:
 If you're a new contributor, look for issues with the `good-first-issue` label
 on the [issues page](https://github.com/ocpp-debugkit/toolkit/issues).
 
+### Claiming One
+
+Comment on the issue saying you would like to work on it and it will be assigned
+to you.
+
+Please hold one open claim at a time. Once your pull request for it is merged,
+say which issue you want next and it will be assigned. This keeps issues from
+sitting claimed while another is still in review, so other newcomers can see what
+is genuinely free.
+
 ## Security Guidelines
 
 OCPP DebugKit processes untrusted input (trace files, pasted content). When

CURRENT_STATE.md

@@ -4,21 +4,21 @@
 
 ## Current Version
 
-`0.4.1`, METER_VALUE_ANOMALY fix (published 2026-07-22). A `0.4.2` patch is in
-progress (STATUS_TRANSITION_VIOLATION per-connector fix, #128).
+`0.4.2`, STATUS_TRANSITION_VIOLATION per-connector fix (published 2026-07-22).
+The v0.4.x line is complete.
 
 ## Active Milestone
 
-**v0.4.x - detection correctness patches, then v0.5.0 (OCPP 2.0.1)**
+**v0.5.0 (OCPP 2.0.1), after a complete v0.4.x**
 
 v0.4.0 shipped the Open OCPP Trace interop: the toolkit reads and writes the
 shared v1.1 interchange format (input adapter #121, exporter + `convert` CLI
-#122), checked against the specification's conformance fixtures. Two
-false-positive bugs shiv3 found from the simulator integration are being
-fixed: `METER_VALUE_ANOMALY` measurand/connector flattening (#127, shipped in
-0.4.1) and `STATUS_TRANSITION_VIOLATION` global status tracking (#128, in
-0.4.2). Next milestone is **v0.5.0 (OCPP 2.0.1)**, where the per-connector /
-EVSE model these fixes introduce is required across detection.
+#122), checked against the specification's conformance fixtures. Both
+false-positive bugs shiv3 found from the simulator integration are fixed and
+released: `METER_VALUE_ANOMALY` measurand/connector flattening (#127, in 0.4.1)
+and `STATUS_TRANSITION_VIOLATION` global status tracking (#128, in 0.4.2). Next
+milestone is **v0.5.0 (OCPP 2.0.1)**, where the per-connector / EVSE model
+these fixes introduce is required across detection.
 
 ## What's Done
 
@@ -272,15 +272,36 @@ EVSE model these fixes introduce is required across detection.
   (vendored) in CI; round-trip tests prove export-then-reparse preserves the
   consumer view and the events
 
+### v0.4.x Releases
+
+- ✅ `@ocpp-debugkit/toolkit@0.4.0` published 2026-07-17, Open OCPP Trace
+  interop (#121, #122)
+- ✅ `@ocpp-debugkit/toolkit@0.4.1` published 2026-07-22, `METER_VALUE_ANOMALY`
+  scoped to cumulative energy registers per connector (Issue #127, PR #129)
+- ✅ `@ocpp-debugkit/toolkit@0.4.2` published 2026-07-22,
+  `STATUS_TRANSITION_VIOLATION` tracked per connector (Issue #128, PR #131)
+- ✅ Git tags + GitHub releases `v0.4.0`, `v0.4.1`, `v0.4.2` created
+
+### Contributor Onboarding Fixes (Issue #134)
+
+- ✅ First external contribution to a `good-first-issue` arrived (#133,
+  firmware-update-success scenario for #104). Second external contributor after
+  #114.
+- ✅ `CONTRIBUTING.md` now documents `pnpm format:check`, which CI enforced and
+  the guide never named, with both command lists ordered to match the CI job
+- ✅ Hard-coded rule and scenario counts dropped from the architecture table
+  after drifting twice; the READMEs stay authoritative and the suite asserts them
+- ✅ "Adding a Scenario" names all four files carrying the count, and station
+  IDs are documented as unique per scenario
+- ✅ Good-first-issues carry a one-open-claim-at-a-time policy
+
 ## What's Next
 
-1. **v0.4.0 release** - both interop halves (#121, #122) are in; cut and
-   publish `v0.4.0`
-2. **v0.5.0 - OCPP 2.0.1 Support** - extend the engine beyond 1.6J: message
+1. **v0.5.0 - OCPP 2.0.1 Support** - extend the engine beyond 1.6J: message
    set, device model, scenarios, and detection
-3. **v1.0.0 - Stable FOSS Ecosystem** - API stabilization, 20+ scenarios, docs
+2. **v1.0.0 - Stable FOSS Ecosystem** - API stabilization, 20+ scenarios, docs
    overhaul, contributor onboarding
-4. **Future** - active scenario runner (live endpoint testing), playground,
+3. **Future** - active scenario runner (live endpoint testing), playground,
    YAML trace format support
 
 ## Known Blockers / Decisions Pending