docs: add developer READMEs to the major directories (#174)

Adds one short orientation README per major directory.
Developer-focused: what
the directory is, its key modules with real file names, how it relates
to its
neighbours, and the one or two commands you actually run there.

## What was added

| file | covers |
|---|---|
| `crates/README.md` | index of the 12 workspace members + which way
dependencies point |
| `crates/driven-core/README.md` | the I/O-free sync engine: scanner,
planner, orchestrator, state |
| `crates/driven-drive/README.md` | the `RemoteStore` seam, the Google
backend, the in-memory fake |
| `crates/driven-crypto/README.md` | content + filename encryption,
keystore, recovery phrase |
| `crates/driven-net/README.md` | the production probe backend behind
`driven-core::network` |
| `crates/driven-tls/README.md` | shared custom-CA + proxy support; the
locked trust rules |
| `crates/driven-power/README.md` | AC / battery / metered / sleep-wake,
normalized per OS |
| `crates/driven-diskstat/README.md` | disk-saturation reader + the
fail-open rule |
| `crates/driven-vss/README.md` | Windows shadow-copy reads for locked
files |
| `crates/driven-vss-helper/README.md` | the least-privilege elevated
broker |
| `crates/driven-cli/README.md` | the headless auth / sync / inspect CLI
|
| `crates/driven-chaos/README.md` | the stress harness and its `just`
entry points |
| `crates/driven-test-fixtures/README.md` | the shared fakes every seam
is tested against |
| `scripts/README.md` | the release / deploy / coverage helpers and who
invokes them |
| `site-landing/README.md` | the static landing page and the
whole-site-snapshot deploy rule |
| `src-tauri/README.md` | the Tauri shell: boot, IPC commands, tray,
updater |
| `ui/README.md` | the Vue frontend: ipc / stores / views layering and
its commands |

## Notes

- **`telemetry-worker/` was skipped** - it already has a thorough
  developer-focused README, and the brief was new files only.
- Every claim is derived from the crate's `lib.rs`/`main.rs` module doc,
its
`Cargo.toml`, the `justfile`, or `ui/package.json`. Where a README would
just
restate a module doc or a design doc, it gives the short version and
points at
  the source instead.
- No existing file is modified, including the root `README.md`.
- Side effects checked: no crate sets `readme`/`include`/`exclude`,
nothing runs
`cargo publish`, `ui/` prettier and eslint only cover `src/`, and no CI
path
  filter is affected except `deploy-landing.yml`, which triggers on
`site-landing/**`. That deploy is a harmless republish -
`assemble-landing.sh`
  copies four files by name, so the new README is never published.
- `docs:` is changelog-hidden, which is correct for this change.

Author: pmaxhogan

crates/README.md

@@ -0,0 +1,20 @@
+# `crates/` - the Rust workspace members
+
+Everything Driven does that is not the Tauri shell. The split follows the
+thick-core / thin-shell rule in `design/DESIGN.md` s4.2: `driven-core` owns the
+sync engine and stays I/O-free, and every side effect sits in its own crate
+behind a trait, so `cargo test --workspace` runs with no real Drive, clock, or GUI.
+
+- `driven-core` - scanner, planner, orchestrator, pacer, executor, SQLite state
+- `driven-drive` - the `RemoteStore` trait, the Google Drive backend, the in-memory fake
+- `driven-crypto` - content + filename encryption, keystore, BIP39 recovery phrase
+- `driven-net` / `driven-tls` - network probes; shared custom-CA + proxy support
+- `driven-power` / `driven-diskstat` - per-OS power, metered, sleep-wake, disk-busy signals
+- `driven-vss` / `driven-vss-helper` - Windows shadow-copy reads and the elevated broker
+- `driven-cli` - headless debugging CLI; `driven-chaos` - the stress harness
+- `driven-test-fixtures` - shared dev-dependency fakes (`tree!`, `FakeClock`, ...)
+
+Dependencies point one way: `driven-tls` / `driven-crypto` are leaves, `driven-core`
+sits above drive / crypto / power / diskstat / vss, and `src-tauri` on top of all of
+them. Nothing here depends on `src-tauri`. Each crate's `src/lib.rs` module doc is
+the real reference - `cargo doc --open`.

crates/driven-chaos/README.md

@@ -0,0 +1,21 @@
+# `driven-chaos`
+
+The stress / chaos harness. It boots the headless core directly (never `src-tauri`)
+and hammers it with hostile inputs and injected faults. Design and the scenario
+catalogue live in `design/STRESS_HARNESS.md` - this README is orientation only.
+
+- `handle.rs` - `DrivenHandle`, one booted headless instance under test
+- `scenario.rs` + `registry.rs` + `dispatch.rs` - the `Scenario` trait, the registry
+  the runner iterates, and the dispatch
+- `capabilities.rs` - the host capability probe; rows the host cannot satisfy
+  (admin, VSS, real Drive, wrong OS) skip cleanly rather than fail
+- `scenarios/` - the catalogue, one module per category: `filenames`, `file_size`,
+  `permissions`, `ntfs`, `concurrency`, `storage`, `drive_side`, `mutation`
+- `mutator.rs` + `runner.rs` + `reporting.rs` - the seeded fuzz mutation loop and the
+  per-scenario verdict / run report
+
+```sh
+just chaos              # full hermetic sweep
+just chaos-fake-drive   # the fault-injection subset CI gates on
+just chaos-fuzz         # seeded continuous-mutation soak
+```

crates/driven-cli/README.md

@@ -0,0 +1,21 @@
+# `driven-cli`
+
+A small headless debugging CLI: do real Drive work, and inspect the local state
+database, without launching the GUI. Not shipped to users.
+
+- `main.rs` - the clap command tree: `auth` (PKCE loopback flow, stores the refresh
+  token in the OS keychain), `dump-refresh-token` and `dump-client-creds` (for
+  debugging refresh failures and minting `DRIVEN_E2E_REFRESH_TOKEN`), and `sync`
+  (one sync cycle of a local folder to a real Drive folder)
+- `inspect.rs` - the read-only state-database commands: `status`, `history`, `verify`
+  (exits non-zero when any file is in a corrupt / error state); no network access
+
+Uses only the public `driven-drive` surface plus clap / tokio / anyhow / tracing - it
+has no HTTP or serde dependency of its own, deliberately. OAuth client credentials
+come from a gitignored `client_secret.json` at the repo root, `--client-id` /
+`--client-secret`, or the public installed-app default. See `design/SPEC.md` s4.
+
+```sh
+cargo run --bin driven-cli -- auth --account me
+cargo test -p driven-cli
+```

crates/driven-core/README.md

@@ -0,0 +1,22 @@
+# `driven-core`
+
+The I/O-free heart of Driven: the sync state machine and everything that decides
+*what* to back up and *when*. All real I/O (filesystem, network, clock, keychain,
+power) arrives through injected traits, so the whole crate is exercisable from
+`cargo test` with no Tauri shell, no real Drive, and no real wall clock.
+
+- `scanner.rs` + `exclude.rs` - walk the source tree, apply the exclusion rules
+- `planner.rs` - diff scan results against state into a plan of operations
+- `orchestrator.rs` + `pacer.rs` + `executor.rs` - run that plan, paced by the rules
+- `adaptive.rs` - upload-parallelism controller (throughput + disk-busy driven)
+- `state/sqlite.rs` + `migrations/` - the SQLite state layer and its schema
+- `types.rs` - the shared `OrchestratorState` machine, event, and error types
+
+The traits declared here (`Clock`, `StateRepo`, `NetworkProbe`, `SourceWatcher`,
+`CryptoProvider`) are implemented by the sibling crates; `src-tauri` assembles them.
+See `design/DESIGN.md` s5 and s11 for the engine design.
+
+```sh
+cargo test -p driven-core
+just sqlx-prepare   # after changing any sqlx::query! macro
+```

crates/driven-crypto/README.md

@@ -0,0 +1,21 @@
+# `driven-crypto`
+
+Driven's authenticated-encryption format: nothing leaves the machine unencrypted,
+and this crate owns every byte of that. Specified in `design/DESIGN.md` s7.
+
+- `content.rs` - chunked content encryption (XChaCha20-Poly1305 STREAM) and the
+  ciphertext MD5 that Drive verifies the upload against
+- `filename.rs` - per path-component filename encryption with base32hex encoding,
+  using the parent component's ciphertext as AEAD AAD
+- `key.rs` / `keystore.rs` - master and per-source keys, OS-keychain storage
+- `recovery.rs` - BIP39 encoding of the master key (the user's recovery phrase)
+
+The `SourceCryptoSuite` trait in `lib.rs` is the seam `driven-core`'s executor codes
+against. It deliberately references no `driven-core` type - every signature is
+`&str` / `Bytes` / `[u8; 16]` - so the dependency graph stays one-way. This crate is
+a leaf. Read the `lib.rs` module doc before touching the seam; it explains why
+content encryption yields a per-file encryptor object rather than a one-shot call.
+
+```sh
+cargo test -p driven-crypto
+```

crates/driven-diskstat/README.md

@@ -0,0 +1,22 @@
+# `driven-diskstat`
+
+Answers one question for the adaptive upload-parallelism controller: *is the local
+disk saturated right now?* If it is, adding in-flight uploads cannot raise
+throughput, so the controller must not grow the pool (`design/DESIGN.md` s11.4.7,
+s18.2).
+
+- `lib.rs` - the `DiskBusyProbe` trait, the `DiskBusy` reading, and the pure
+  classifier (`busy_fraction_from_delta`, `SATURATION_THRESHOLD` = 80 %) that is
+  unit-tested on every target
+- `linux.rs` (`/proc/diskstats`), `macos.rs` (IOKit), `windows.rs` (PDH
+  `% Disk Time`) - exactly one `RealDiskBusyProbe` compiled per target
+
+Kept a standalone crate rather than folded into `driven-core` so the PDH / IOKit FFI
+never reaches a foreign host's `cargo build --workspace`. The fail-open rule is
+load-bearing: an unreadable probe returns `Unknown`, which reads as "not saturated",
+because a broken reader must never pin uploads small. Tests use `FakeDiskBusyProbe`
+from `driven-test-fixtures`.
+
+```sh
+cargo test -p driven-diskstat
+```

crates/driven-drive/README.md

@@ -0,0 +1,21 @@
+# `driven-drive`
+
+The `RemoteStore` seam plus its implementations. Everything the sync engine knows
+about a backup destination goes through this trait, so `driven-core` never names
+Google Drive directly.
+
+- `remote_store.rs` - the trait every backend must satisfy (list, create, upload, delete)
+- `google/` - the production Google Drive backend: `oauth.rs` (PKCE loopback flow),
+  `token_store.rs` (refresh token in the OS keychain), `resumable.rs` (resumable
+  uploads), `retry.rs`, `pagination.rs`
+- `fake/` - `InMemoryRemoteStore`, the backend behind the contract tests and every
+  sync-engine test in the workspace; `fault_injection.rs` makes it fail on demand
+
+Depends only on `driven-tls` (custom CA + proxy config, re-exported here so callers
+need no direct dependency). Consumed by `driven-core`, `driven-cli`, `driven-chaos`,
+and `src-tauri`. OAuth and the Drive layout are specified in `design/SPEC.md` s4.
+
+```sh
+cargo test -p driven-drive              # fake contract suite
+just test-e2e-real                      # real Drive, env-gated; see design/E2E_REAL.md
+```

crates/driven-net/README.md

@@ -0,0 +1,23 @@
+# `driven-net`
+
+The production `Backend` behind `driven-core::network`'s `NetworkProbe` seam.
+`driven-core` ships only the transport-agnostic probe topology and the per-service
+circuit breakers and stays I/O-free; this crate supplies the real clients
+(`design/DESIGN.md` s5.8).
+
+- `reachability.rs` - the native per-OS connectivity read (`INetworkListManager` on
+  Windows, NetworkManager on Linux, `NWPathMonitor` on macOS) with a dual-stack TCP
+  fallback when the native verdict is unavailable or ambiguous
+- `classify.rs` - turning a probe response into a `ProbeOutcome` (offline, captive
+  portal, DNS failure, service down)
+- `lib.rs` - the `Backend` impl: captive-portal probe, per-service health probes with
+  per-service timeouts, and connection-pool teardown
+
+Every client is built through `driven_tls::apply_proxy` / `apply_custom_ca`, so the
+user's proxy and corporate-CA settings apply here too. Consumed by `driven-cli` and
+`src-tauri`; the tests drive the topology through `FakeNetwork` from
+`driven-test-fixtures`.
+
+```sh
+cargo test -p driven-net
+```

crates/driven-power/README.md

@@ -0,0 +1,20 @@
+# `driven-power`
+
+Battery / AC / metered-network / sleep-wake signals, normalized across OSes. The
+orchestrator's pause-and-resume rules (`design/SPEC.md` s10, `design/DESIGN.md` s5.7
+and s5.10.1) are driven entirely by what this crate reports.
+
+- `lib.rs` - the `PowerSource` trait, the `PowerState` snapshot, and the
+  `SleepWakeEvent` edge; both subscriptions are `tokio::sync::broadcast` receivers
+  because several consumers (state machine, tray, activity log) fan out from them
+- `windows.rs` / `macos.rs` / `linux.rs` - exactly one is compiled per target, each
+  exporting `RealPowerSource` (re-exported cfg-free so callers need no `cfg`)
+- `network.rs` - shared metered / reachability detection used by every backend
+
+Steady state is a 30 s poll; sleep and wake are OS notification edges, not polls.
+Tests use `FakePowerSource` from `driven-test-fixtures`. `driven-diskstat` is
+deliberately shaped the same way.
+
+```sh
+cargo test -p driven-power
+```

crates/driven-test-fixtures/README.md

@@ -0,0 +1,20 @@
+# `driven-test-fixtures`
+
+Shared test helpers, pulled in as a `[dev-dependencies]` entry by sibling crates and
+the workspace integration tests. It is what makes the injected-trait design pay off:
+every seam in the workspace has a deterministic fake here.
+
+- `tree.rs` - the `tree!` macro for declaring a temp directory tree inline
+- `clock.rs` - `FakeClock` (`driven_core::time::Clock`) with `advance()` / `now_set()`
+- `power.rs` - `FakePowerSource` with a `set()` driver for state transitions
+- `diskstat.rs` - `FakeDiskBusyProbe` for the adaptive-parallelism tests
+- `network.rs` - `FakeNetwork`, simulating offline, captive portal, lossy links, and
+  per-service outages
+- `assert.rs` - `assert_remote_eq!`, a snapshot diff over remote-store listings
+
+Never a normal dependency of anything, and `publish = false`. Add a fake here rather
+than re-rolling one per crate.
+
+```sh
+cargo test -p driven-test-fixtures
+```