Fix documentation (#30)

Author: brakit-ai

CONTRIBUTING.md

@@ -71,7 +71,7 @@ src/
     tools/             # McpTool implementations (one file per tool)
   output/              # Terminal insight listener
   runtime/             # In-process architecture (interceptor, capture, health)
-  store/               # In-memory bounded stores, persistent finding store
+  store/               # In-memory bounded stores, persistent issue store
   telemetry/           # Anonymous usage analytics
   types/               # TypeScript type definitions
   utils/               # Shared utilities (collections, format, math, endpoint)
@@ -243,6 +243,7 @@ interface SecurityRule {
 interface SecurityContext {
   requests: readonly TracedRequest[];   // all captured HTTP requests
   logs: readonly TracedLog[];           // all captured console output
+  parsedBodies: ParsedBodyCache;        // pre-parsed JSON bodies (avoids re-parsing per rule)
 }
 ```
 

README.md

@@ -41,7 +41,7 @@
 <p align="center">
   <img width="700" src="docs/images/vscode.png" alt="Claude reading Brakit findings in VS Code" />
   <br />
-  <sub>Claude reads findings via MCP and fixes your code</sub>
+  <sub>Claude reads issues via MCP and fixes your code</sub>
 </p>
 
 ## Quick Start
@@ -56,7 +56,7 @@ That's it. Brakit detects your framework, adds itself as a devDependency, and cr
 npm run dev
 ```
 
-Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
+Dashboard at `http://localhost:<port>/__brakit`. Issues in the terminal.
 
 > **Requirements:** Node.js >= 18 and a project with `package.json`.
 
@@ -74,7 +74,7 @@ Dashboard at `http://localhost:<port>/__brakit`. Insights in the terminal.
 - **Full server tracing** — fetch calls, DB queries, console logs, errors — zero code changes
 - **Response overfetch** — large JSON responses with many fields your client doesn't use
 - **Performance tracking** — health grades and p95 trends across dev sessions
-- **AI-native via MCP** — Claude Code and Cursor can query findings, inspect endpoints, and verify fixes directly
+- **AI-native via MCP** — Claude Code and Cursor can query issues, inspect endpoints, and verify fixes directly
 
 ---
 

docs/design/analysis-engine.md

@@ -240,7 +240,7 @@ required. Each store holds up to 1,000 entries and evicts the oldest when full.
 | LogStore     | Console output                                                                           |
 | ErrorStore   | Uncaught exceptions and unhandled rejections                                             |
 | MetricsStore | Per-endpoint session statistics, persisted to `.brakit/metrics.json`                     |
-| FindingStore | Stateful security findings with lifecycle tracking, persisted to `.brakit/findings.json` |
+| IssueStore   | Stateful issue tracking with lifecycle (open/fixing/resolved/stale/regressed), persisted to `.brakit/issues.json`    |
 
 Stores are registered in a typed ServiceRegistry and accessed through it —
 no module-level singletons. The EventBus delivers new entries to all
@@ -349,8 +349,8 @@ traceable.
 **Why bounded in-memory stores, not a database?** Brakit is a zero-config dev
 tool. Requiring a database (even SQLite) adds setup friction. Bounded arrays
 with oldest-eviction give predictable memory usage without configuration. The
-MetricsStore and FindingStore persist to JSON files for cross-session features
-(regression detection, finding lifecycle) — everything else is ephemeral.
+MetricsStore and IssueStore persist to JSON files for cross-session features
+(regression detection, issue lifecycle): everything else is ephemeral.
 
 **Why debounced analysis, not real-time?** A single request can generate 20+
 telemetry events (queries, fetches, logs). Recomputing insights on every event

docs/design/architecture.md

@@ -1,6 +1,6 @@
 # Dashboard
 
-Brakit serves a live dashboard at `/__brakit` that shows requests, queries, errors, performance insights, and security findings in real time. This document covers how it's built.
+Brakit serves a live dashboard at `/__brakit` that shows requests, queries, errors, performance issues, and security issues in real time. This document covers how it's built.
 
 ## Table of contents
 
@@ -39,12 +39,12 @@ Brakit serves a live dashboard at `/__brakit` that shows requests, queries, erro
 │  │  SSE handler   ──▶ EventBus ──▶ Subscribe to channels   │     │
 │  └─────────────────────────────────────────────────────────┘     │
 │                                                                  │
-│  ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌──────────────┐  │
-│  │ EventBus │  │  Stores  │  │  Analysis  │  │ MCP Server   │  │
-│  │ (channels│  │ (7 total)│  │  Engine    │  │ (separate    │  │
-│  │  + subs) │  │          │  │            │  │  process,    │  │
-│  └──────────┘  └──────────┘  └────────────┘  │  same API)   │  │
-│                                               └──────────────┘  │
+│  ┌──────────┐  ┌──────────┐  ┌────────────┐  ┌──────────────┐    │
+│  │ EventBus │  │  Stores  │  │  Analysis  │  │ MCP Server   │    │
+│  │ (channels│  │ (8 total)│  │  Engine    │  │ (separate    │    │
+│  │  + subs) │  │          │  │            │  │  process,    │    │
+│  └──────────┘  └──────────┘  └────────────┘  │  same API)   │    │
+│                                              └──────────────┘    │
 └──────────────────────────────────────────────────────────────────┘
          │ SSE stream                      │ REST API
          ▼                                 ▼
@@ -65,24 +65,26 @@ Real-time updates use Server-Sent Events. When brakit captures a new request or
 
 `src/dashboard/router.ts` creates a route table mapping URL paths to handler functions:
 
-| Path | Handler | Purpose |
-|------|---------|---------|
-| `/__brakit` | HTML page | Serves the dashboard |
-| `/__brakit/api/requests` | `createRequestsHandler` | List captured requests |
-| `/__brakit/api/flows` | `createFlowsHandler` | List request flows (user actions) |
-| `/__brakit/api/events` | `createSSEHandler` | SSE stream for real-time updates |
-| `/__brakit/api/logs` | `createLogsHandler` | List captured console logs |
-| `/__brakit/api/fetches` | `createFetchesHandler` | List outgoing fetch calls |
-| `/__brakit/api/errors` | `createErrorsHandler` | List captured errors |
-| `/__brakit/api/queries` | `createQueriesHandler` | List database queries |
-| `/__brakit/api/metrics` | `createMetricsHandler` | Per-endpoint session metrics |
-| `/__brakit/api/metrics/live` | `createLiveMetricsHandler` | Current session live metrics |
-| `/__brakit/api/activity` | `createActivityHandler` | Timeline of events for a request |
-| `/__brakit/api/insights` | `createInsightsHandler` | Performance insights |
-| `/__brakit/api/security` | `createSecurityHandler` | Security findings |
-| `/__brakit/api/findings` | `createFindingsHandler` | Stateful findings with lifecycle |
-| `/__brakit/api/ingest` | `createIngestHandler` | External SDK event ingestion |
-| `/__brakit/api/clear` | `createClearHandler` | Clear all stores |
+| Path                            | Handler                       | Purpose                                          |
+| ------------------------------- | ----------------------------- | ------------------------------------------------ |
+| `/__brakit`                     | HTML page                     | Serves the dashboard                             |
+| `/__brakit/api/requests`        | `createRequestsHandler`       | List captured requests                           |
+| `/__brakit/api/flows`           | `createFlowsHandler`          | List request flows (user actions)                |
+| `/__brakit/api/events`          | `createSSEHandler`            | SSE stream for real-time updates                 |
+| `/__brakit/api/logs`            | `createLogsHandler`           | List captured console logs                       |
+| `/__brakit/api/fetches`         | `createFetchesHandler`        | List outgoing fetch calls                        |
+| `/__brakit/api/errors`          | `createErrorsHandler`         | List captured errors                             |
+| `/__brakit/api/queries`         | `createQueriesHandler`        | List database queries                            |
+| `/__brakit/api/metrics`         | `createMetricsHandler`        | Per-endpoint session metrics                     |
+| `/__brakit/api/metrics/live`    | `createLiveMetricsHandler`    | Current session live metrics                     |
+| `/__brakit/api/activity`        | `createActivityHandler`       | Timeline of events for a request                 |
+| `/__brakit/api/insights`        | `createInsightsHandler`       | Performance and reliability issues               |
+| `/__brakit/api/security`        | `createSecurityHandler`       | Security issues                                  |
+| `/__brakit/api/findings`        | `createFindingsHandler`       | All stateful issues with lifecycle (used by MCP) |
+| `/__brakit/api/findings/report` | `createFindingsReportHandler` | Record AI fix result (POST)                      |
+| `/__brakit/api/tab`             | `createTabHandler`            | Track active dashboard tab                       |
+| `/__brakit/api/ingest`          | `createIngestHandler`         | External SDK event ingestion                     |
+| `/__brakit/api/clear`           | `createClearHandler`          | Clear all stores                                 |
 
 Every handler is a factory function that receives the `ServiceRegistry`. No global imports, no singletons.
 
@@ -113,16 +115,16 @@ Response shapes are defined in `src/types/api-contracts.ts` and shared between t
 4. Send heartbeat comments every 30 seconds to keep the connection alive
 5. On disconnect, call `subs.dispose()` to clean up all subscriptions
 
-| Bus channel | SSE event type | What it carries |
-|-------------|---------------|-----------------|
-| `request:completed` | (default) | Completed request record |
-| `telemetry:fetch` | `fetch` | Outgoing fetch call |
-| `telemetry:log` | `log` | Console log entry |
-| `telemetry:error` | `error_event` | Uncaught error |
-| `telemetry:query` | `query` | Database query |
-| `analysis:updated` | `insights` + `security` | Computed insights and findings |
+| Bus channel         | SSE event type                     | What it carries                                      |
+| ------------------- | ---------------------------------- | ---------------------------------------------------- |
+| `request:completed` | (default)                          | Completed request record                             |
+| `telemetry:fetch`   | `fetch`                            | Outgoing fetch call                                  |
+| `telemetry:log`     | `log`                              | Console log entry                                    |
+| `telemetry:error`   | `error_event`                      | Uncaught error                                       |
+| `telemetry:query`   | `query`                            | Database query                                       |
+| `analysis:updated`  | `issues` + `insights` + `security` | Computed issues, raw insights, and security findings |
 
-The `analysis:updated` channel emits two SSE events — one for insights, one for security findings — so the client can update each section independently.
+The `analysis:updated` channel emits three SSE events: `issues` (the unified StatefulIssue list with lifecycle state), `insights` (raw Insight objects from performance rules), and `security` (raw SecurityFinding objects). The client can update each section independently.
 
 ---
 
@@ -149,6 +151,7 @@ The dashboard enforces several security measures:
 **Localhost-only access.** The interceptor only serves dashboard routes to localhost connections. Non-local IPs get a 404.
 
 **Content Security Policy.** Every response includes a strict CSP header:
+
 ```
 default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; connect-src 'self'; img-src data:
 ```

docs/design/dashboard.md

@@ -52,7 +52,15 @@ interface ChannelMap {
   "telemetry:error": Omit<TracedError, "id">;
   "request:completed": TracedRequest;
   "analysis:updated": AnalysisUpdate;
-  "store:cleared": void;
+  "issues:changed": readonly StatefulIssue[];
+  "store:cleared": undefined;
+}
+
+// AnalysisUpdate carries the full computed state after each recompute cycle:
+interface AnalysisUpdate {
+  insights: readonly Insight[];
+  findings: readonly SecurityFinding[];
+  issues: readonly StatefulIssue[];
 }
 ```
 
@@ -69,6 +77,7 @@ Channels follow a `domain:event` convention:
 | `telemetry:*` | Raw telemetry from hooks and SDKs | `telemetry:fetch`, `telemetry:query` |
 | `request:*`   | HTTP request lifecycle            | `request:completed`                  |
 | `analysis:*`  | Computed insights and findings    | `analysis:updated`                   |
+| `issues:*`    | Issue lifecycle state changes     | `issues:changed`                     |
 | `store:*`     | Store-level operations            | `store:cleared`                      |
 
 Prefer this convention when adding new channels. It keeps the bus scannable and groups related events.
@@ -143,10 +152,9 @@ The analysis engine emits computed results after recompute:
 
 ```typescript
 bus.emit("analysis:updated", {
-  insights,
-  findings,
-  statefulFindings,
-  statefulInsights,
+  insights,    // Insight[] from performance rules
+  findings,    // SecurityFinding[] from security rules
+  issues,      // StatefulIssue[] with full lifecycle state
 });
 ```
 
@@ -171,8 +179,9 @@ subs.add(
 );
 subs.add(
   bus.on("analysis:updated", (u) => {
-    writeEvent("insights", JSON.stringify(u.statefulInsights));
-    writeEvent("security", JSON.stringify(u.statefulFindings));
+    writeEvent("issues", JSON.stringify(u.issues));
+    writeEvent("insights", JSON.stringify(u.insights));
+    writeEvent("security", JSON.stringify(u.findings));
   }),
 );
 
@@ -202,7 +211,7 @@ subs.add(bus.on("telemetry:log", handler2));
 subs.dispose();
 ```
 
-`bus.on()` returns a dispose function. `SubscriptionBag.add()` accepts it. This is the only way to manage subscriptions — never call `bus.off()` directly.
+`bus.on()` returns a dispose function. `SubscriptionBag.add()` accepts it. `bus.off(channel, fn)` also exists as a direct unsubscribe, but prefer `SubscriptionBag` for any code that manages multiple subscriptions — it avoids the error-prone manual pairing of every `on` with an `off`.
 
 Used by: