docs: add CLAUDE.md development guideline

Project-specific daily-development guide synthesized from the seanslab Engineering Guide and this project's devlogs/lessons. Links to the workspace-root workflow rules and tasks/lessons.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAUDE.md

+# CLAUDE.md — jensen
+
+> **Workflow rules live in the workspace root:** [`../CLAUDE.md`](../CLAUDE.md)
+> (plan-first → tests → peer-review-before-push → devlog → cleanup). This file is
+> only the project-specific layer.
+>
+> ⚠️ This project has **no `devlog-*.md` or `tasks/lessons.md` yet.** The hard-won
+> lessons below were learned by its *consumers* (`sugr-audio-notes`,
+> `sugr-console-web`) — they are jensen's API contracts, so keep them honored here
+> and start a `tasks/lessons.md` when corrections arise.
+
+## What this is
+Shared **WebUSB device-communication library** for HiDock hardware. Consumed by
+`sugr-audio-notes` and `sugr-console-web` (pinned by git tag, e.g. `v3.0.5`).
+
+- **Stack:** TypeScript, React 19, Vite.
+- **Public surface:** `ConnectionManager` (multi-device), `TaskManager`
+  (init / timer / background / user tasks), `DeviceStateStore` (reactive state).
+  Type defs in `jensen.d.ts`; source in `src/` (`utils/`, `mgr.tsx`, `Logger.ts`).
+- **Remote:** `gitlab.jing.zone/skye/jensen` (GitLab — review = MR).
+- **Release impact:** consumers pin a tag — **bump the version on every behavior
+  change** and let consumers update via their `update:jensen` script. A breaking
+  change here ripples into both apps.
+
+## Build / verify
+```bash
+pnpm install
+pnpm run build      # vite build
+pnpm run dev        # local harness (index.html / mgr.tsx)
+pnpm run prettier   # format
+```
+⚠️ **No unit tests exist here.** Per the Engineering Guide, new features need tests —
+add a test setup (vitest) before non-trivial changes, or at minimum verify against a
+real device via the dev harness and record the result in a devlog. This library is a
+shared dependency: "verify on real hardware" is the minimum DoD.
+
+## API contracts that MUST hold (consumers depend on these)
+- **One USB command at a time.** The device cannot handle concurrent commands.
+  `TaskManager` must serialize: a user task may only acquire the slot when no other
+  user task **and** no in-progress scheduler/background work is running (`schedulerBusy`).
+  Background tasks that `await` long USB ops (like `getFile`) block the loop without
+  setting `userTask` — treat scheduler-busy as a mutual-exclusion signal.
+- **Multi-callback APIs settle once, then go quiet.** `getFile()` fires data/progress
+  callbacks for every chunk and keeps firing after logical completion. Either guarantee
+  callers can add a `settled` guard, or stop emitting after completion — otherwise a
+  161MB file (~20k callbacks) causes O(n²) main-thread freezes downstream.
+- **Scale timeouts to payload size.** Large transfers legitimately take tens of
+  seconds (Download user-task timeout 3s→60s). Don't time out mid-transfer.
+- **Don't drop playback-critical metadata** (e.g. recording `version`) on
+  state merges — consumers depend on it for codec selection; a wrong default
+  (e.g. version 4) corrupts playback.
+
+## Conventions
+- Versioned releases only — never let a consumer point at a moving branch.
+- After any consumer-reported bug, capture the contract in `tasks/lessons.md` here
+  (so the fix is enforced at the source) and log it in a `devlog-YYYYMMDD.md`.