scaffold: project structure, wire contract, roadmap and agent briefs

Lays out Velox Download Manager (IDM-class download manager for Ubuntu
26.04) as a monorepo ready for parallel lane development. No implementation
code by design.

- docs/: architecture, roadmap M0-M7, IDM-parity GUI spec, engine design,
  Firefox extension spec, risks/spikes, packaging
- contracts/: wire-contract skeleton (JSON Schema + fixture templates) —
  the single synchronization point between lanes
- docs/agents/: one brief per lane (PROTO, CORE, DAEMON, GUI, EXT, PKG/QA)
  with owned directories, build order and definition of done
- CLAUDE.md: rules of engagement — lane ownership, layering, non-negotiables
- CMake scaffolding with dev/tsan/release/ci presets

Two environment findings shape the design: Firefox here is the Mozilla snap
(native-messaging risk, so the extension carries a loopback-WebSocket
fallback), and Wayland forbids passive clipboard monitoring (so clipboard
capture is explicit-action-first).

Co-Authored-By: Claude Opus 5 <[email protected]>

docs/agents/AGENT-PROTO.md

@@ -0,0 +1,53 @@
+# Agent brief — PROTO (contract owner)
+
+**Runs first, alone, in M0. Then stays on call as gatekeeper for the whole project.**
+
+## You own
+```
+contracts/**          tools/mockd/**          tests/conformance/**
+```
+
+## You may read everything. You may write nowhere else.
+
+## Mission
+Make it impossible for the CORE, DAEMON, GUI and EXT lanes to become incompatible without
+CI noticing the same day.
+
+## M0 deliverables (in order)
+
+1. **`contracts/schema/`** — JSON Schema (draft 2020-12) for every type, method and event
+   in `contracts/README.md`. Two templates already exist
+   (`types/TaskSummary.schema.json`, `methods/capture.offer.schema.json`) — follow their
+   shape, including the `x-privileged` / `x-transports` / `x-deadlineMs` annotations.
+2. **`contracts/openrpc.json`** — generated from the schemas; it is the doc humans read.
+3. **`contracts/codegen/gen_cpp.py`** → emits `core/generated/velox_proto.{hpp,cpp}`:
+   plain structs, `to_json`/`from_json` (nlohmann), a `Method` enum, and a
+   `dispatch(method, json) -> json` skeleton. No exceptions on the hot path; parse errors
+   return a `Result`.
+4. **`contracts/codegen/gen_ts.py`** → emits `extension/src/shared/protocol/`: discriminated
+   union types, a typed `call<M>()` signature, event payload types, and runtime validators
+   for anything crossing the WS boundary (the daemon is not allowed to trust the wire, and
+   neither is the extension).
+5. **`contracts/fixtures/`** — every method gets a success fixture; auth, timeout, and
+   not-found cases get error fixtures. Use `$uuid` / `$isoDate` placeholders for values
+   that can't be fixed.
+6. **`tools/mockd`** — Node/TS. Serves the fixtures over **both** transports (Unix socket
+   NDJSON and loopback WS), fakes plausible progress events at 4 Hz, and has flags for
+   `--slow`, `--flaky`, `--drop-connection`, `--refuse-pairing` so GUI and EXT can test
+   their unhappy paths before `veloxd` exists.
+7. **`tests/conformance/`** — one suite, two runners: replays each fixture against a live
+   `veloxd` (C++ side) and through the generated TS client. Wired into CI as a **required
+   check on every lane's PR**.
+
+## Definition of done
+- `mockd` answers all fixtures over both transports.
+- Both generated clients round-trip every fixture with no hand-written types anywhere.
+- Conformance is a required CI check.
+- `VERSION` frozen at `1.0.0` and the freeze announced to all lanes.
+
+## Standing duties after M0
+- You are the **only** committer to `contracts/`. Other lanes file requests; you implement,
+  bump `VERSION`, regenerate, update fixtures, and notify the lanes in one PR.
+- Reject "just add a field locally" every single time. That request is the M2 integration
+  disaster arriving early enough to stop.
+- Optional field or new method → minor. Rename/remove/retype → major + an ADR.