XY-78: align runtime docs with canonical routers and current defaults

README.md

@@ -81,9 +81,9 @@ cargo run -p rsnap
 ### HUD settings behavior
 
 - HUD controls are in Settings → Overlay:
-  - Opacity (`0..100`, default `75`)
-  - Blur (`0..100`, default `25`)
-  - Tint (`0..100`, default `0`)
+  - Opacity (`0..100`, default `50`)
+  - Blur (`0..100`, default `50`)
+  - Tint (`0..100`, default `50`)
   - Hue (`0..360`, system-blue default)
   - Toolbar placement (`bottom` / `top`, default `bottom`)
 - Tint is applied as hue-shift intensity (0 = no tint, 100 = full tint), while Hue sets
@@ -150,7 +150,7 @@ Recording / automation permissions.
 
 For `XY-185` style downward scroll-capture work, treat the verification order as:
 
-1. deterministic tests and `cargo make check`
+1. deterministic tests and `cargo make checks`
 2. `cargo make replay-scroll-capture`
 3. `cargo make analyze-scroll-capture-trace`
 4. one fresh release live touchpad run with a newly recorded trace
@@ -174,6 +174,24 @@ command selection and baseline comparison lives at
 
 The capture-session contract lives at `docs/spec/capture-session.md`.
 
+## Workspace Layout
+
+The tracked workspace keeps one app-shell crate in `apps/rsnap/`, one overlay/runtime crate in
+`packages/rsnap-overlay/`, and shared docs/assets/scripts at the repository root.
+Generated or local-only directories such as `target/`, `.worktrees/`, and `.workspaces/` are not
+part of the tracked repository structure. For the authoritative layout and ownership map, read
+`docs/reference/workspace-layout.md`.
+
+## Documentation
+
+- Product and development overview: this `README.md`
+- Unified documentation router: `docs/index.md`
+- Normative specs: `docs/spec/index.md`
+- Procedural runbooks: `docs/runbook/index.md`
+- Current implementation references: `docs/reference/index.md`
+- Durable design rationale: `docs/decisions/index.md`
+- Documentation policy and placement rules: `docs/policy.md`
+
 ## Support Me
 
 If you find this project helpful and would like to support its development, you can buy me a coffee!

docs/reference/live-sampling.md

@@ -10,8 +10,8 @@ freeze/export.
 
 Depends on: `docs/spec/capture-session.md`
 
-Covers: The stream-only sampling model, cache usage, fallback behavior, and the current support
-constraints.
+Covers: The stream-only sampling model, cache usage, fallback behavior, and the current live
+versus freeze/export capture split.
 
 Spec boundary: `docs/spec/capture-session.md`
 
@@ -100,15 +100,14 @@ Fallback behavior:
   - Desktop layer
 - This keeps behavior stable and avoids false window outlines.
 
-## Proposed future architecture direction
+## Current capture-plane split
 
-Keep capture split by quality profile:
+The current implementation already keeps capture responsibilities split by quality profile:
 
 - `Live` plane: stream-first, low-latency RGB/Loupe and live outline updates.
 - `Freeze/export` plane: higher-cost still capture for full screenshot quality.
 
-Linux/Windows details are tracked for future work and remain out of scope for this
-live-implementation milestone.
+Linux/Windows details remain out of scope for the current macOS-first contract.
 
 ## Known status
 

docs/reference/window-hit-testing.md

@@ -11,8 +11,8 @@ default strategy.
 
 Depends on: `docs/spec/capture-session.md`
 
-Covers: The snapshot-based default strategy, the researched alternative, and the planned rule for
-current live mode.
+Covers: The snapshot-based default strategy, the documented alternative, and the current default
+rule for live mode.
 
 Spec boundary: `docs/spec/capture-session.md`
 
@@ -41,7 +41,7 @@ Implementation notes:
 - If a snapshot is missing, no outline is drawn until fresh geometry is available.
 - Excluded from the target set: menu bar, dock, and desktop-layer windows.
 
-## Strategy B (alternative, researched)
+## Strategy B (documented alternative)
 
 - Query the active window under point directly on each cursor event, for example through
   platform-specific APIs that report the topmost window at a point.
@@ -53,7 +53,7 @@ Observed trade-offs:
 - Can produce inconsistent results across platform boundaries and special windows.
 - Less aligned with a strict stream-first low-latency pipeline.
 
-## Planned rule
+## Current default rule
 
 Use Strategy A by default on macOS live mode. Evaluate Strategy B only if a later release needs
 explicit behavior changes.

docs/runbook/performance-validation.md

@@ -62,7 +62,7 @@ legacy recorded-source replay mode.
 
 For the downward scroll-capture rebuild, the expected verification sequence is:
 
-1. `cargo make check`
+1. `cargo make checks`
 2. `cargo make replay-scroll-capture`
 3. `cargo make analyze-scroll-capture-trace`
 4. any targeted deterministic `cargo test -p rsnap-overlay ...`