wireguard-admin/docs/evidence/milestone-18.md

# Milestone 18 evidence: in-app Help

Recorded 2026-10-28T23:59:51+02:00 on `x86_64-unknown-linux-gnu` with
`rustc`/Cargo 1.97.1, rustfmt 1.9.0 and Clippy 0.1.97. Base commit:
`4960c65f6511da50bac9d35e2b4a625adbaf86c3`. The working tree is dirty;
the M18 Rust/README inputs at final validation have SHA256:

| Input | SHA256 |
| --- | --- |
| `src/tui/render.rs` | `dbf00298f1bf466f99688f790be5ae34e9a7434aa374bc61c7df31e41c8d842b` |
| `src/tui/terminal.rs` | `4658404e856c1acced9c115f1cfb4c9f87e714b2343c3996df7ee63504368b81` |
| `tests/tui_workflow.rs` | `d7bc72c20eb9b4d3ba160e599d83f83111e418a9c3056b4e430aa17a555baacd` |
| `README.md` | `7352da8e13850b1b13e11bf2f828c8368dbd1b6b95320d6838ac26b7fa0532d6` |

`PLANS.md` is also dirty, recording the prior M18 plan and this milestone's
progress. No dependency manifests or application adapters changed. Release
`target/release/wireguard-admin` SHA256 is
`d179b2934565e12e0d90ad716730418a40b215c5ca68058fd76566c267e98488`;
`file` identified an x86-64 dynamically linked GNU/Linux PIE.

## Shortcut audit and content basis

The implementer audited current `src/tui/terminal.rs::handle_key` and
`handle_navigation_key`, `src/tui/forms.rs::handle_key` and
`src/tui/events.rs` before writing Help. The guide's shortcut families map to
the existing handlers and guards:

| Keys | Handler and actual availability |
| --- | --- |
| `?`, `Up/Down`, `PageUp/PageDown`, `Enter`, `Esc` | `terminal.rs`: Help resets to top; Help scrolls by visual row/page; list arrows select and Enter opens details; Esc returns to list or cancels an active form/clears QR. |
| `q`, handled Ctrl-C | `terminal.rs`: outside forms, exit is immediate without a draft or asks about draft discard; Ctrl-C is translated to `q` and is form-specific while a form is active. |
| `n`, `r`, `d` | `terminal.rs` and `forms.rs`: create requires a loaded view; rename/delete require a supported unambiguous selected peer and confirmation. Blank paired addresses select automatic allocation. |
| `p`, `c`, `x`, `R` | `terminal.rs`, `forms.rs`, `events.rs`: preview draft; confirmed Commit saves after backup; confirmed discard drops draft; uppercase restart previews saved state and requires confirmation, backup, service completion and verification. |
| `o`, `O` | `terminal.rs`, `forms.rs`, `events.rs`: supported selected saved client only; first delivery after Commit is session-bound and retryable after file failure, while uppercase reissue requires a vault password per action; file precedes optional QR. |
| `b`, `B` | `terminal.rs` and `forms.rs`: list/select backup and preview confirmed full restore versus create manual backup. Restore changes saved state only. |
| `s`, `i`, `!` | `terminal.rs` and `forms.rs`: setup only before vault initialization; import submits one configured-directory filename and preserves its source; issue summary is available after view load. |

Actions remain guarded by the existing handlers. The Help navigation keys
themselves do not submit application work. Existing action letters can still
dispatch while Help is visible; the milestone did not change action dispatch.
The guide says how to return to the list and accurately distinguishes lowercase
and uppercase keys.

## Implementation, review and acceptance mapping

The Help screen is one ordered document with an introduction and nine sections:
quick start; list/details; state/observations; client changes; save/restart;
delivery/reissue; backups/restore; vault/import/issues; navigation/exit. It
uses styled headings, key labels, workflows and warnings, with display-cell
wrapping at the actual inner viewport width. A visible row-range title and the
fixed-height footer show navigation and overflow. Renderer and terminal share
the same wrapped-row metrics: one-row arrows, viewport-page keys, bounded
scrolling, resize clamping, `?` reset and Esc return. These changes cover
M18-A1–A5; synthetic buffers cover 34×8, 40×9, 60×16, 80×24, 100×30 and
180×50, including reachability of the last section. README Help instructions
were updated.

One GPT-6-Luna/high implementer completed M18.1–M18.3 sequentially. A separate
fresh GPT-6-Luna/high read-only reviewer compared content with the handlers and
tested Help rendering/navigation. It found M18-R1 (P2): at 34×8, the Help
footer omitted Esc return. A separate GPT-6-Luna/high repairer changed only
Help's narrow hint packing and added 34×8/40×9 assertions. The reviewer
rechecked the actual repair, ran the focused test and closed R1. No actionable
finding remained in that pass. A coordinator content audit then found M18-R2:
four missing explanations about Applied status, current observations, the
first-delivery activation warning and masked password entry. The reviewer
independently confirmed those gaps. The separate repairer amended Help and
added a 34×8 semantic/reachability regression; independent re-review checked
the claims against status/form code and SPEC.md and closed R2. No actionable
finding remains, satisfying M18-A6. A proposed change to action-key dispatch
was withdrawn after checking the explicit preserve-actions boundary.

## Final checks and limits

| Command | Result |
| --- | --- |
| `cargo fmt --all -- --check` | exit 0 |
| `cargo test --locked tui::` | 79 passed, 0 failed |
| `cargo test --locked --test tui_workflow` | 8 passed, 0 failed; includes synthetic PTY Help/resize flow |
| `cargo clippy --locked --all-targets -- -D warnings` | exit 0 |
| `cargo test --locked` | 392 passed, 0 failed, 3 explicitly ignored; 2 doctests passed |
| `cargo build --locked --release` | exit 0; binary hash above |
| `git diff --check` | exit 0 |

Tests use synthetic fixtures and an isolated PTY. That PTY run checks emitted
terminal behavior, not manual readability in a specific terminal emulator.
Alpine Testcontainers, disposable-VM systemd, live WireGuard and production
configuration were not used for this presentation milestone. The user-directed
M16 manual check has no recorded environment/transport detail and is not M18
evidence. No host service was restarted and no Git commit was made.