docs: add and update README files across all packages

- Root README: updated with full package table, architecture diagram,
  and references to both browser and VS Code extensions
- devtools-core: new README documenting annotators, diagnosis, event
  store, and export modules
- devtools-ui: new README documenting Elm views, ports, and build
- vscode-extension: new README with quick start, commands, architecture
- devtools-extension: updated architecture section to reference shared
  packages (devtools-core, devtools-ui)
- devtools-bridge: updated to reference VS Code extension and CDP
  capture path
- devtools-types: added FlowState/FlowExport/OidcSemantics to exports
  table and consumers section
- e2e: new README documenting test suite and mock OIDC server

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: ryanbas21

README.md

@@ -2,7 +2,7 @@
 
 **Captures, correlates, and diagnoses** OIDC/OAuth 2.0 authentication flows in real time — works standalone with any OIDC provider or as an enhanced companion to the Ping Identity SDK.
 
-A browser DevTools panel for Chrome and Firefox that replaces the Network-panel-and-jwt.io workflow with a single view: OIDC-annotated network traffic, SDK-level event correlation, inline JWT decoding, and an automated diagnosis engine that tells you what went wrong and how to fix it.
+Available as a **browser DevTools panel** (Chrome & Firefox) and a **VS Code extension** (via Chrome DevTools Protocol). Both share the same annotation engine, diagnosis rules, and Elm UI.
 
 ![Flow view with diagnosis banner and node rail](packages/devtools-extension/screenshots/Flow-Screen.png)
 
@@ -12,14 +12,19 @@ A browser DevTools panel for Chrome and Firefox that replaces the Network-panel-
 
 | Package | Description | npm |
 | --- | --- | --- |
-| [`@wolfcola/devtools-extension`](packages/devtools-extension) | Browser extension (Chrome & Firefox) — DevTools panel with Timeline, Flow, and Learn views | private |
-| [`@wolfcola/devtools-bridge`](packages/devtools-bridge) | Opt-in SDK adapter — emits `AuthEvent`s from DaVinci, Journey, and OIDC clients | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-bridge)](https://www.npmjs.com/package/@wolfcola/devtools-bridge) |
-| [`@wolfcola/devtools-types`](packages/devtools-types) | Shared `AuthEvent` Effect Schema definitions and TypeScript types | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-types)](https://www.npmjs.com/package/@wolfcola/devtools-types) |
+| [`devtools-extension`](packages/devtools-extension) | Chrome & Firefox DevTools panel — Timeline, Flow, and Learn views | private |
+| [`vscode-extension`](packages/vscode-extension) | VS Code extension — debugs via Chrome DevTools Protocol | private |
+| [`devtools-core`](packages/devtools-core) | Shared logic — annotators, diagnosis engine, event store, export | private |
+| [`devtools-ui`](packages/devtools-ui) | Shared Elm UI — compiled JS, CSS, TypeScript port interface | private |
+| [`devtools-bridge`](packages/devtools-bridge) | SDK adapter — emits events from DaVinci, Journey, and OIDC clients | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-bridge)](https://www.npmjs.com/package/@wolfcola/devtools-bridge) |
+| [`devtools-types`](packages/devtools-types) | Effect Schema definitions for AuthEvent, FlowState | [![npm](https://img.shields.io/npm/v/@wolfcola/devtools-types)](https://www.npmjs.com/package/@wolfcola/devtools-types) |
 
 ---
 
 ## Quick start
 
+### Browser extension
+
 ```bash
 pnpm install
 pnpm build              # Chrome (default)
@@ -28,14 +33,30 @@ pnpm build:firefox      # Firefox
 
 Load the extension as unpacked from `packages/devtools-extension/dist/` — see the [extension README](packages/devtools-extension) for full instructions.
 
+### VS Code extension
+
+```bash
+pnpm install
+pnpm build
+```
+
+Open the `packages/vscode-extension` folder in VS Code and press F5 to launch. Then:
+
+1. Launch Chrome with `--remote-debugging-port=9222`
+2. Run **"OIDC DevTools: Start Capture"** from the command palette
+
+See the [VS Code extension README](packages/vscode-extension) for details.
+
 ### Browser compatibility
 
 | Browser | Minimum version |
 | --- | --- |
 | Chrome | 88+ (Manifest V3) |
 | Firefox | 128+ (`world: "MAIN"` content scripts) |
 
-To wire up SDK-level events in your app:
+### SDK integration (optional)
+
+The extension captures and annotates OIDC network traffic automatically. To also see SDK-level events, add the bridge:
 
 ```bash
 pnpm add @wolfcola/devtools-bridge
@@ -53,16 +74,127 @@ The bridge is a no-op when the extension is not installed.
 
 ---
 
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────┐
+│                    Shared Packages                        │
+│  devtools-core: annotators, diagnosis, event store       │
+│  devtools-ui:   Elm UI (Timeline, Flow, Learn)           │
+│  devtools-types: Effect Schema definitions               │
+└─────────────────────┬────────────────────────────────────┘
+                      │
+          ┌───────────┴───────────┐
+          ▼                       ▼
+┌──────────────────┐    ┌──────────────────┐
+│ Browser Extension│    │ VS Code Extension│
+│ Chrome / Firefox │    │ CDP → Chrome     │
+│                  │    │                  │
+│ content scripts  │    │ CDP client       │
+│ service worker   │    │ TreeView         │
+│ Elm panel        │    │ WebView (Elm)    │
+└──────────────────┘    └──────────────────┘
+```
+
+Both consumers import the same annotators, diagnosis engine, and Elm UI from the shared packages. The only difference is how events enter the system:
+
+- **Browser extension** → `chrome.devtools.network.onRequestFinished` + content script relay
+- **VS Code extension** → CDP `Network` domain + `Runtime.bindingCalled` for SDK events
+
+---
+
+## Network-first OIDC intelligence
+
+The extension automatically detects and annotates OIDC/OAuth 2.0 traffic without any SDK integration. It works out of the box with **any OIDC provider** — Ping Identity, Auth0, Okta, Keycloak, or any spec-compliant authorization server.
+
+**Well-known discovery** — parses `/.well-known/openid-configuration` responses and matches subsequent requests against discovered endpoints.
+
+**OIDC semantic annotation:**
+
+| Phase | Extracted data |
+| --- | --- |
+| **discovery** | Issuer, all discovered endpoints |
+| **authorize** | `client_id`, `state`, `nonce`, `code_challenge`, `response_type` |
+| **par** | `request_uri`, `expires_in`, pushed parameters |
+| **token** | `grant_type`, `code_verifier`, tokens received, `token_type` |
+| **userinfo** | User profile data |
+| **revocation** | Token revocation status |
+| **introspection** | Token validity |
+| **end-session** | Logout status |
+
+**DPoP detection (RFC 9449)** — detects `DPoP` proof JWTs, `token_type: "DPoP"`, `use_dpop_nonce` errors, and `DPoP-Nonce` headers.
+
+**PAR detection (RFC 9126)** — detects Pushed Authorization Requests and correlates `request_uri` values.
+
+---
+
+## Diagnosis
+
+Every captured event is run through a rule engine that produces flow-level and per-event diagnostics with severity ratings and numbered remediation steps.
+
+| Category | Examples |
+| --- | --- |
+| **CORS** | Status-zero failures, missing `Access-Control-Allow-Origin`, wildcard + credentials |
+| **Token** | Missing `interactionToken` on non-initial nodes, expired JWTs |
+| **Flow config** | Node error/failure status, connector errors, policy-not-found |
+| **OIDC** | State mismatch, missing PKCE, redirect URI mismatch |
+| **OIDC flow** | Auth code without PKCE, missing `code_verifier`, implicit flow, nonce, code reuse |
+| **DPoP** | Missing proof, invalid proof structure, method/URI mismatch |
+| **PAR** | Missing `request_uri`, inline params alongside `request_uri` |
+
+---
+
+## Panel views
+
+### Timeline
+
+Chronological event table with type badges (NET, SDK, SES, CFG), status codes, OIDC phase tags, and inline CORS/DPoP indicators. A graph sidebar draws SDK node-change events as a vertical rail. The Inspector panel shows contextual tabs (Headers, SDK State, Collectors, OIDC, Diagnosis, etc.).
+
+### Flow
+
+Visual representation of the authentication flow as a sequence of SDK nodes. Includes a node rail, detail cards, playback controls, and a Flow Health banner for diagnosis.
+
+### Learn
+
+Canvas-based flow lifecycle visualization with layout variants for DaVinci, Journey, OIDC Code, OIDC+DPoP, and OIDC+PAR flows.
+
+---
+
 ## Development
 
 ```bash
 pnpm install
-pnpm build              # build all packages (Chrome)
-pnpm build:firefox      # build Firefox variant
+pnpm build              # build all packages
+pnpm test               # vitest (308 tests)
+pnpm typecheck          # TypeScript type checking
 pnpm lint               # eslint
-pnpm test               # vitest
 ```
 
+| Script | Description |
+| --- | --- |
+| `pnpm build` | Build all packages |
+| `pnpm test` | Run all unit tests |
+| `pnpm typecheck` | TypeScript type checking |
+| `pnpm lint` | Lint all packages |
+| `pnpm changeset` | Create a changeset for versioning |
+| `pnpm version` | Apply changesets and bump versions |
+| `pnpm release` | Build and publish to npm |
+
+### Tech stack
+
+- **TypeScript** with strict mode and Effect for typed functional effects
+- **Elm 0.19** for the DevTools panel UI
+- **esbuild** for bundling
+- **Vitest** for unit tests, **Playwright** for e2e tests
+- **pnpm workspaces** for monorepo management
+- **Changesets** for versioning and publishing
+
+---
+
+## Security and privacy
+
+The extension requests only `storage` and `clipboardWrite`/`clipboardRead` — no `cookies`, `webRequest`, `tabs`, or other sensitive APIs. Content scripts use a two-world architecture to prevent arbitrary page code from injecting messages into the background script. All SDK events are decoded through `AuthEventSchema` (Effect Schema) before reaching the EventStore — malformed payloads are dropped. Captured data is stored locally and never transmitted off-device.
+
 ---
 
 ## License

e2e/README.md

@@ -0,0 +1,44 @@
+# E2E Tests
+
+Playwright end-to-end tests for the WolfCola DevTools browser extension.
+
+## Tests
+
+| Test | What it verifies |
+|------|-----------------|
+| `extension-loads` | Service worker registers, DevTools panel mounts |
+| `network-capture` | OIDC network events are captured and annotated |
+| `panel-renders-events` | Events render in the timeline, clear button works |
+| `firefox-build` | Firefox build produces valid manifest and dist files |
+
+## Running
+
+```bash
+pnpm test
+```
+
+Chrome must be installed. The tests load the built extension into a Chrome instance with a temporary user data directory.
+
+## Setup
+
+The tests use a shared fixture (`fixtures/extension.ts`) that:
+1. Creates a temporary Chrome profile with the extension loaded
+2. Provides a `BrowserContext` with the extension ID resolved
+3. Starts a mock OIDC server (`mock-oidc-server/server.ts`) for network capture tests
+
+## Mock OIDC server
+
+A lightweight HTTP server that implements:
+- `/.well-known/openid-configuration` — discovery document
+- `/authorize` — authorization endpoint (302 redirect)
+- `/token` — token endpoint (returns access/refresh/ID tokens)
+- `/userinfo` — userinfo endpoint
+
+## Prerequisites
+
+- Chrome installed
+- Extension must be built first: `cd packages/devtools-extension && pnpm build`
+
+## License
+
+MIT

packages/devtools-bridge/README.md

@@ -1,6 +1,6 @@
 # @wolfcola/devtools-bridge
 
-Opt-in SDK adapter that connects your Ping Identity / ForgeRock application to the [WolfCola DevTools extension](../devtools-extension). Add it to your app in one line — it is a no-op when the extension is not installed, so it is safe to ship in production builds.
+Opt-in SDK adapter that connects your Ping Identity / ForgeRock application to WolfCola DevTools — either the [browser extension](../devtools-extension) or the [VS Code extension](../vscode-extension). Add it to your app in one line — it is a no-op when the extension is not installed, so it is safe to ship in production builds.
 
 ## Contents
 
@@ -178,8 +178,23 @@ Your app
             │  chrome.runtime.sendMessage({ type: 'EVENTS_UPDATED' })
             ▼
       panel (Elm)  ──  Timeline view + Flow view
+
+── OR (VS Code extension) ──
+
+Your app
+  └── emitAuthEvent()
+            │
+            │  window.postMessage({ type: '__pingDevtools', ... })
+            ▼
+      CDP-injected script  (Page.addScriptToEvaluateOnNewDocument)
+            │
+            │  Runtime.bindingCalled('__wolfcolaBridge', payload)
+            ▼
+      VS Code extension host  ──▶  TreeView + WebView (Elm)
 ```
 
+The VS Code extension captures SDK events via a CDP-injected script that listens for the same `__pingDevtools` postMessage — no browser extension needed.
+
 Each bridge function:
 
 1. Subscribes to the client store

packages/devtools-core/README.md

@@ -0,0 +1,68 @@
+# @wolfcola/devtools-core
+
+Shared logic for WolfCola DevTools. Contains annotators, diagnosis engine, event store, and export utilities. Used by both the browser extension and VS Code extension.
+
+## Modules
+
+### Annotators (`src/annotators/`)
+
+Pure functions that analyze network traffic and detect OIDC/OAuth patterns.
+
+| Module | Purpose |
+|--------|---------|
+| `network-observer` | Filters auth-related requests and builds `AuthEvent` from HAR entries |
+| `oidc-annotator` | Detects OIDC phases (authorize, token, userinfo, etc.) and extracts parameters |
+| `cors-detector` | Identifies CORS issues (missing headers, wildcard+credentials, status zero) |
+| `dpop-detector` | Detects DPoP proof JWTs and validates claims |
+| `par-detector` | Detects Pushed Authorization Requests |
+| `oidc-discovery` | Parses `.well-known/openid-configuration` and matches endpoints |
+| `oidc-flow-tracker` | Tracks multi-step OIDC flows across requests |
+| `jwt-utils` | JWT decoding, pattern matching, and expiry detection |
+
+### Diagnosis engine (`src/diagnosis/`)
+
+Rule-based diagnostic engine that analyzes captured events and produces actionable issues.
+
+**Rule categories:**
+- CORS rules — preflight failures, missing `Access-Control-Allow-Origin`, wildcard+credentials
+- Token rules — missing interaction tokens, expired sessions
+- Flow config rules — DaVinci node errors, connector errors, policy not found
+- OIDC rules — state mismatch, redirect URI mismatch, missing PKCE
+- DPoP rules — proof JWT validation, method/URI mismatches
+- PAR rules — missing `request_uri`, inline params with `request_uri`
+
+### Event store (`src/event-store/`)
+
+Effect-based event store with dependency injection via `Context.Tag` and `Layer`.
+
+- `EventStoreInMemory` — in-memory store with no-op persistence (for VS Code and testing)
+- Consumers provide their own Layer for persistent storage (e.g., `chrome.storage.local`)
+
+### Export (`src/export/`)
+
+- `redact` — strips sensitive data (tokens, passwords, credentials) from flow state
+- `markdown` — renders a flow as a Markdown table with diagnosis results
+
+## Usage
+
+```ts
+import {
+  buildNetworkEvent,
+  isAuthRelated,
+  runDiagnosis,
+  redactFlowState,
+  renderFlowMarkdown,
+  EventStoreService,
+  EventStoreInMemory,
+} from '@wolfcola/devtools-core';
+```
+
+## Testing
+
+```bash
+pnpm test    # 161 tests
+```
+
+## License
+
+MIT