docs: bring the usage docs in line with the quality-run behaviour changes

[zoza1982]

Stacked on #197 (the review report) — it adds docs/reviews/, which this PR links to. Merge that first and I'll retarget.

Documents behaviour from #193–#207. Should land with or after them; every claim here is false until they merge.

What

One coherent pass over the user-facing docs for the behaviour the 15 fix PRs changed.

Why

Each of those PRs carried its own CHANGELOG entry, RFC updates and rustdoc, per §5. What none of them could carry well is the README's usage prose — it is cross-cutting, and fifteen fragments of it would read worse than one pass. So there was a real gap: a user reading the README today would not learn that a tree copy skips symlinks, that q now asks during a transfer, or anything at all about SSH host-key policy.

How

README:

• Transfers — what a copy does and does not carry: symlinks and special files skipped (with the reason — a FIFO blocks until written to), a move never deleting what it did not copy, atomic replacement via a .part sibling and what to do if you find one left behind, both panes on one directory refused. Quitting during a transfer confirms.
• Capability gating — operations are refused before you commit, not after.
• SSH host keys — an entirely new section, and the biggest gap. The policy table, plus why accept-new means a host you hold no key for rather than a key you have not seen: that distinction is the vulnerability fix(ssh): honour every known_hosts entry form when deciding a host is pinned #198 closed, so it is stated rather than left implicit. Covers @revoked / @cert-authority / wildcards / hashed entries, the algorithm preference, ~/.ssh permissions, and the known gap that a rejected key still reports as a generic connection failure.
• Marks — Space/Insert, that operations act on them, and that they clear when the listing is replaced (with the reason, because otherwise it reads as a bug).
• AI assistant — the confirm gate shows the call that will actually run beneath each description, and why reviewing only the description approves a claim rather than an action.
• Status blurb notes SFTP now streams, while object stores still buffer.

LLD — §3.3 gains how the UI reads capabilities and the one-directional rule; §5 gains the Runtime/RuntimeCtx split and the reap-before-update ordering invariant, including the one event that deliberately does not reap.

IMPLEMENTATION_PLAN — records the quality run as the current phase and adds a Known gaps row, so what is still open sits on the dashboard rather than only in the report.

docs/README.md — indexes reviews/.

Testing

cargo test --workspace --all-features                                   # 0 failures
RUSTDOCFLAGS="-D warnings" cargo doc --workspace --no-deps --all-features # 0 errors

Plus a relative-link check across the four edited documents — 0 broken (which is how I caught that docs/reviews/ only exists on #197, hence the stacking).

Every factual claim was checked against the code, not written from memory: key bindings against keymap.rs (Space/Insert → ToggleMark, Ctrl-A → AiPropose), the plan overlay's hint string and bulk-approve rule against render.rs, the SSH policy names and defaults against connect/mod.rs, and that marked entries drive operations against op_targets.

Checklist

• PR title follows Conventional Commits
• Branched off main (stacked on docs(review): record the 2026-09-09 whole-workspace quality review #197)
• cargo fmt / clippy / test / doc — no code changed; test and doc run clean
• Tests added — n/a, documentation
• Docs updated — this PR is the docs
• CHANGELOG.md — intentionally skipped: the behaviour entries already landed with their own PRs; duplicating them here would double-report every change
• Review gates — n/a for a docs-only diff
• Security review — n/a. The SSH section describes the policy and names a known gap; it discloses no exploit beyond what the code and CHANGELOG already state
• No secrets, credentials, or generated artifacts committed

Deliberate omissions

• PRD.md is untouched. It is the what and why at product level and none of this changed the product's intent — CLAUDE.md says to keep the PRD high-level, so behaviour detail belongs in the README and LLD.
• No keybinding table was added. The README documents keys inline where the feature is explained, which is the existing convention; a second, separate table would drift.
• The .part temp-file note is deliberately in the user docs rather than only the CHANGELOG: it is the one change that leaves something visible on disk, and a user finding .notes.txt.cairn-1234-0.part deserves to know what it is.

Risk & rollback

Documentation only. The real risk is describing behaviour that does not merge — hence the stacking note at the top. Rollback: revert the single commit.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SM3dDrioC5KntqjB6WDqjW