docs: define the cross-platform porting strategy (ADR 0020, macOS first)

The tree is Ubuntu-first, but the Linux-specific surface is about ten files and
already sits at the bottom of the I/O and RPC stacks. Rather than fork the repo
or scatter ifdefs, platform differences go behind narrow seams with one backend
directory per OS, selected centrally in cmake/platform.cmake.

Linux stays the reference implementation and its behaviour does not change: the
owning lanes (CORE, DAEMON) move today's Linux code behind the seams on Ubuntu
first, with the suite still green, before any macOS code exists. A new PORT lane
owns only the per-OS backends, so macOS work never writes shared logic and
CLAUDE.md's lane rule stays intact.

Adds ADR 0020 (the decision and phases), docs/08-porting.md (seam list, API
mapping for macOS and Windows, dependency table, verification gates) and
docs/agents/AGENT-PORT.md (the lane brief), plus the PORT row in the ownership
table.

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

docs/agents/AGENT-PORT.md

@@ -0,0 +1,50 @@
+# Agent brief — PORT (per-OS backends)
+
+**Starts after Phase 0: CORE and DAEMON have landed the seams on Ubuntu.**
+
+## You own
+```
+core/src/**/platform/<os>/**        daemon/src/**/platform/<os>/**
+cmake/platform*.cmake               packaging/macos/**   packaging/windows/**
+```
+You may read everything. **You never write logic** — not in `core/src/io/*.cpp`, not in
+`daemon/src/rpc/*.cpp`, not in `gui/`, never in `contracts/`.
+
+## Read first
+`docs/adr/0020-cross-platform-strategy.md`, then `docs/08-porting.md` — it has the seam
+list, the API mapping and the dependency table. Then `CLAUDE.md`.
+
+## The one rule that matters
+**Linux behaviour never changes.** If your port needs a seam that doesn't exist, or a seam
+whose shape is wrong, you do not widen it yourself — you file a request with the owning
+lane (CORE for `core/`, DAEMON for `daemon/`) exactly as every other lane does. A port that
+quietly edits shared logic is how one tree becomes two.
+
+## Build order (macOS)
+1. **Configure at all.** The root `CMakeLists.txt` requires `libsecret-1` unconditionally;
+   that must be Linux-gated before anything else compiles. File it with PKG/QA — root build
+   files are theirs.
+2. `core/` — `preallocate`, `advise_dontneed`, `flush_durable`. Use `F_FULLFSYNC`, not
+   `fsync`: `.veloxpart` resume correctness depends on a real flush.
+3. `daemon/` — `Wakeup` (self-pipe), `peer_of` (`getpeereid`), `instance_lock` (socket file
+   + `flock`, with stale-socket cleanup), `runtime_dir` (`$TMPDIR`, `~/Library/Application
+   Support/Velox`).
+4. Unit tests green for both lanes.
+5. `tools/testserver` (stdlib Python) and conformance (Node) — expected to run unchanged.
+   If they don't, that's a bug worth reporting, not patching around.
+6. GUI against Qt 6 for macOS.
+7. Packaging — `.dmg`/Homebrew, `launchd`, native-messaging manifest locations. Last.
+
+## Definition of done (Phase 1–2)
+- macOS builds `libveloxcore`, `veloxd` and `velox` with `-Wall -Wextra -Werror`.
+- Core and daemon unit tests pass on macOS.
+- One real download completes on macOS against `tools/testserver` with a SHA-256 that
+  matches the server's reference — the same gate the Linux vertical slice passed.
+- `kill -9` mid-download, restart, resume completes and the checksum still matches.
+- The Ubuntu suite is **still** 57/57 from the same commit.
+
+## Do not
+- Do not add `#ifdef` outside a `platform/<os>/` file.
+- Do not change a fixture, a schema or a hostile-mode expectation to make macOS pass.
+- Do not substitute `F_NOCACHE` for `posix_fadvise(DONTNEED)` — see `docs/08` for why.
+- Do not start with packaging.