fix: formatting normalization, DOM API XSS fixes, script robustness

.gitignore

@@ -13,3 +13,12 @@ coverage/*
 !coverage/coverage-badge.json
 .tsbuildinfo
 .eslintcache
+
+# CodeQL analysis database folders (generated, large, and machine-specific)
+codeql-db/
+codeql-db-js/
+codeql-db-*/
+codeql-db-js-*/
+
+# CodeQL results (analysis output)
+codeql-results*.sarif

CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Build (TypeScript compile + esbuild bundle)
+npm run build:dev          # compile + bundle webview (no minification, for dev/test)
+npm run build:bundle       # full production build (minified)
+
+# Test
+npm test                   # unit tests + integration suite (full run)
+npm run test:unit          # unit tests only (fast, no VS Code host needed)
+npm run test:activation    # integration tests only (launches VS Code Extension Host)
+
+# Run a single unit test file
+npm run build:dev && node --test --test-reporter=spec out/test/unit/format.test.js
+
+# Lint
+npm run lint               # ESLint on src/**/*.ts
+npm run lint:md            # markdownlint on *.md files
+
+# Packaging
+npm run package            # builds and produces a .vsix
+```
+
+`npm run build:dev` must be run before any test command since tests run against compiled output in `out/`.
+
+## Architecture
+
+This is a VS Code extension with two UI surfaces and a shared backend.
+
+### Data flow
+
+GitHub API (billing/usage endpoints) → `extension.ts` (fetch + state) → two parallel UIs:
+1. **Status bar** — icon + usage bar + percentage, updated on a configurable interval
+2. **Webview panel** (`UsagePanel`) — rich HTML panel with budget meters and trend charts
+3. **Sidebar** (`CopilotUsageSidebarProvider` in `sidebarProvider.ts`) — compact webview in the activity bar
+
+The webview (`media/webview.js`) is a self-contained vanilla JS file that receives all its data via `postMessage`. It never calls the VS Code API or GitHub directly. Dynamic HTML is always escaped via the local `escapeHtml()` helper to prevent XSS.
+
+### Key source files
+
+| File | Role |
+|------|------|
+| `src/extension.ts` | Activation, GitHub fetch, status bar, `UsagePanel` class, exported test hooks |
+| `src/sidebarProvider.ts` | `CopilotUsageSidebarProvider` — sidebar webview provider |
+| `src/lib/usageUtils.ts` | `normalizeUsageQuantity`, `computeIncludedOverageSummary`, billing math |
+| `src/lib/viewModel.ts` | `buildUsageViewModel` — derives display values from raw data |
+| `src/lib/format.ts` | Pure helpers: `computeUsageBar`, `pickIcon`, `formatRelativeTime` |
+| `src/lib/planUtils.ts` | Plan catalog (loads `media/generated/copilot-plans.json`, falls back to hardcoded defaults) |
+| `src/lib/usageHistory.ts` | `UsageHistoryManager` — snapshot persistence, trend analysis, multi-month analytics |
+| `src/lib/tokenState.ts` | State machine for PAT/secret token presence across set/clear/migrate events |
+| `src/secrets.ts` | Secret Storage read/write with legacy plaintext migration |
+| `media/webview.js` | All webview rendering — not bundled, served directly |
+
+### Included requests priority
+
+`getEffectiveIncludedRequests()` in `extension.ts` resolves the limit used for overage calculation in this order:
+1. User-configured `includedPremiumRequests` setting
+2. Selected plan's `included` field (from `planUtils.ts`)
+3. Raw billing API value
+
+### Plan data
+
+`media/generated/copilot-plans.json` is generated by `scripts/update-plan-data.mjs` and committed. `scripts/sync-plan-enums.mjs` keeps TypeScript enums in sync. Both run automatically before publish (`prepublishOnly`).
+
+### Test structure
+
+- **Unit tests** (`src/test/unit/`) — run with Node's built-in `node --test`, no VS Code host. Cover pure lib functions and webview logic via DOM stubs.
+- **Integration tests** (`src/test/suite/`) — run inside the VS Code Extension Host via `@vscode/test-electron`. Use test hooks exported from the extension's activation return value (e.g., `_test_setSpendAndUpdate`, `_test_getStatusBarText`, `_test_postedMessages`).
+- `src/test/testGlobals.ts` — typed helpers for setting up DOM/window stubs in unit tests.
+
+### Numeric formatting
+
+All billing quantities pass through `normalizeUsageQuantity(value, digits?)` (default 3 decimal places) before display or storage, preventing floating-point artifacts like `406.59000000000003`.