docs: add package READMEs for npm discoverability

.changeset/package-readmes.md

@@ -0,0 +1,8 @@
+---
+'@ocpp-debugkit/core': patch
+'@ocpp-debugkit/scenarios': patch
+'@ocpp-debugkit/reporter': patch
+'@ocpp-debugkit/cli': patch
+---
+
+Add package READMEs for npm discoverability.

packages/cli/README.md

@@ -0,0 +1,69 @@
+# @ocpp-debugkit/cli
+
+> Command-line interface for OCPP DebugKit — inspect traces, generate reports, run scenarios.
+
+## Installation
+
+```bash
+npm install -g @ocpp-debugkit/cli
+```
+
+## Commands
+
+### inspect
+
+Parse and analyze an OCPP trace file:
+
+```bash
+ocpp-debugkit inspect trace.json
+```
+
+Outputs event count, sessions, detected failures, and parse warnings.
+
+### report
+
+Generate a Markdown report:
+
+```bash
+# To stdout
+ocpp-debugkit report trace.json
+
+# To a file
+ocpp-debugkit report trace.json --output report.md
+
+# Specify format
+ocpp-debugkit report trace.json --format markdown
+```
+
+### scenario list
+
+List all available built-in scenarios:
+
+```bash
+ocpp-debugkit scenario list
+```
+
+### scenario run
+
+Run a scenario through the analysis engine and compare detected vs expected failures:
+
+```bash
+ocpp-debugkit scenario run failed-auth
+```
+
+**Note:** `scenario run` runs static fixtures through the local analysis engine only. It is not active endpoint testing, WebSocket simulation, or live station/CSMS testing.
+
+## Accepted Trace Formats
+
+- **JSON Object** — `{ "metadata": {...}, "events": [...] }`
+- **JSONL** — one event per line
+- **Bare array** — `[[2, "id", "Action", {}], ...]`
+
+## Limits
+
+- Maximum input size: 10 MB
+- Maximum event count: 10,000
+
+## License
+
+Apache 2.0

packages/core/README.md

@@ -0,0 +1,69 @@
+# @ocpp-debugkit/core
+
+> Core data model, parser, normalizer, timeline, and failure detection for OCPP DebugKit.
+
+## Installation
+
+```bash
+npm install @ocpp-debugkit/core
+```
+
+## Usage
+
+### Parse a trace
+
+```typescript
+import { parseTrace } from '@ocpp-debugkit/core';
+
+const result = parseTrace(traceString);
+// result.events — normalized Event[]
+// result.warnings — ParseWarning[] for malformed entries
+```
+
+Accepts JSON Object, JSONL, and bare array formats.
+
+### Build session timeline
+
+```typescript
+import { buildSessionTimeline } from '@ocpp-debugkit/core';
+
+const sessions = buildSessionTimeline(result.events);
+```
+
+### Detect failures
+
+```typescript
+import { detectFailures } from '@ocpp-debugkit/core';
+
+const failures = detectFailures(result.events, sessions);
+// Three detection rules: FAILED_AUTHORIZATION, CONNECTOR_FAULT,
+// STATION_OFFLINE_DURING_SESSION
+```
+
+### Generate summaries
+
+```typescript
+import { summarizeSessions } from '@ocpp-debugkit/core';
+
+const summaries = summarizeSessions(sessions, failures);
+```
+
+### Validate messages
+
+```typescript
+import { validateMessage } from '@ocpp-debugkit/core';
+
+const result = validateMessage(event);
+// result.valid, result.errors
+```
+
+## Key Types
+
+- `Event` — canonical normalized OCPP message
+- `Session` — logical charging session
+- `Failure` — detected failure with severity and suggested steps
+- `Scenario` — predefined trace fixture with expected failures
+
+## License
+
+Apache 2.0

packages/reporter/README.md

@@ -0,0 +1,50 @@
+# @ocpp-debugkit/reporter
+
+> Report generators for OCPP DebugKit analysis results.
+
+## Installation
+
+```bash
+npm install @ocpp-debugkit/reporter
+```
+
+## Usage
+
+### Generate a Markdown report
+
+```typescript
+import { generateMarkdownReport } from '@ocpp-debugkit/reporter';
+import type { AnalysisResult } from '@ocpp-debugkit/reporter';
+
+const report = generateMarkdownReport({
+  events,
+  sessions,
+  failures,
+  summaries,
+  warnings,
+});
+
+// report is a Markdown string with:
+// - Session overview table
+// - Timeline summary (action sequences)
+// - Failures (severity, description, suggested steps)
+// - Suggested next steps
+// - Raw event appendix
+```
+
+## Input Type
+
+```typescript
+interface AnalysisResult {
+  events: Event[];
+  sessions: Session[];
+  failures: Failure[];
+  summaries: SessionSummary[];
+  warnings: ParseWarning[];
+  metadata?: TraceMetadata;
+}
+```
+
+## License
+
+Apache 2.0

packages/scenarios/README.md

@@ -0,0 +1,44 @@
+# @ocpp-debugkit/scenarios
+
+> Predefined OCPP trace scenarios for testing the DebugKit analysis engine.
+
+## Installation
+
+```bash
+npm install @ocpp-debugkit/scenarios
+```
+
+## Usage
+
+```typescript
+import { scenarios, getScenario } from '@ocpp-debugkit/scenarios';
+
+// List all scenario names
+scenarios.forEach(s => console.log(s.name, s.expectedFailures));
+
+// Get a specific scenario
+const scenario = getScenario('failed-auth');
+
+// Run through the analysis engine
+import { parseTrace, buildSessionTimeline, detectFailures } from '@ocpp-debugkit/core';
+
+const result = parseTrace(JSON.stringify(scenario.trace));
+const sessions = buildSessionTimeline(result.events);
+const failures = detectFailures(result.events, sessions);
+```
+
+## Available Scenarios
+
+| Name | Expected Failures |
+|------|-------------------|
+| `normal-session` | none |
+| `failed-auth` | `FAILED_AUTHORIZATION` |
+| `connector-fault` | `CONNECTOR_FAULT` |
+| `station-offline` | `STATION_OFFLINE_DURING_SESSION` |
+| `unexpected-stop-reason` | none (parser/timeline-only fixture) |
+
+All scenario data is fully synthetic — no real station identifiers or personal data.
+
+## License
+
+Apache 2.0