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]>

CLAUDE.md

@@ -0,0 +1,70 @@
+# Rules of engagement — agents working in this repo
+
+Read this before touching anything. Then read your lane brief in [docs/agents/](docs/agents/).
+
+## 1. Stay in your lane
+
+| Lane | Owns | Never writes |
+|---|---|---|
+| PROTO | `contracts/`, `tools/mockd/`, `tests/conformance/` | everything else |
+| CORE | `core/`, `tools/bench/`, `tools/fuzz/` | `daemon/`, `gui/`, `extension/`, `contracts/` |
+| DAEMON | `daemon/`, `cli/`, `nmhost/`, `packaging/nativehost/` | `core/`, `gui/`, `extension/`, `contracts/` |
+| GUI | `gui/` | everything else |
+| EXT | `extension/` | everything else |
+| PKG/QA | `packaging/`, `.github/`, `tools/testserver/`, `tests/integration/`, `tests/e2e/`, root build files | any lane's feature code |
+
+If your task seems to require editing another lane's files, that is a signal the interface
+is wrong. **File the request; don't reach across.**
+
+## 2. `contracts/` is sacred
+
+- Only PROTO commits there.
+- Generated code (`core/generated/`, `extension/src/shared/protocol/`) is committed and
+  **must never be hand-edited**. Fix the schema, regenerate.
+- Need a new field? Open a `contracts/`-only PR: schema + fixtures + regenerated code +
+  `VERSION` bump. Optional field or new method = minor; rename/remove/retype = major + ADR.
+- Working around a wrong contract locally is the single failure mode most likely to sink
+  this project. Don't.
+
+## 3. Layering
+
+```
+core        → no JSON, no SQL, no Qt, no RPC. Ever.
+daemon      → depends on core. No Qt.
+gui / ext   → zero download logic. They render state and forward user intent.
+nmhost      → a dumb pipe. Under 300 lines. No logic.
+```
+
+A grep for `curl|pwrite|sqlite` in `gui/` must come back empty. Same for download logic in
+`extension/`.
+
+## 4. Non-negotiable behaviours
+
+- **Capture fails open.** Daemon down, slow, or erroring → Firefox downloads normally.
+  Never swallow a user's download. `capture.offer` answers within 750 ms or the extension
+  gives up.
+- **Resume is validated.** `If-Range` with ETag/Last-Modified; a `200` where `206` was
+  expected means the file changed — ask the user, never silently corrupt.
+- **Never bind beyond `127.0.0.1`.** The WS transport is token-authenticated, origin-checked,
+  and rate-limited.
+- **Secrets go to the Secret Service**, never SQLite, never logs.
+- **Paths are canonicalized** and checked against allowed roots before any write.
+- **No allocation in the transfer hot path.**
+
+## 5. Definition of done, everywhere
+
+Code + tests + docs updated in the same change. A feature with no test does not exist. If
+you change observable behaviour, update the doc in `docs/` that describes it in the same PR.
+
+## 6. Style
+
+- C++23, `-Wall -Wextra -Werror`, clang-format (config at root), clang-tidy clean.
+- TypeScript strict mode, ESLint, no `any` on protocol boundaries.
+- Commit messages: `lane: imperative summary` (e.g. `core: add dynamic segment stealing`).
+- One logical change per commit. Rebase onto `main`; no merge commits.
+
+## 7. When you're unsure
+
+Ask in the PR rather than guessing at the interface. A day of clarification is cheaper than
+an M2 integration rewrite. And record real decisions as an ADR in `docs/adr/` — the next
+agent to touch this will have none of your context.