Restructure System Operation into a user-first Daily Operation page

[mairas]

Why

The first User Guide page front-loaded firmware internals (Solo/Co-op modes, shutdown state sequences, watchdog mechanics) that are invisible to anyone running HaLOS or halpid, while the things every owner needs — what the LEDs mean, how shutdown works — were buried at the bottom or written in firmware vocabulary. It also carried facts that contradict the firmware. Plan and fact sheet: issue #46 (phase 1, English only).

How

• Daily Operation (user-guide/operation.md, same URL, #status-led-indicators anchor preserved): task-first rewrite — automatic power management lead, powering on/off with the auto-restart behavior up front, LED table in user vocabulary, power-loss reassurance, health check, daemonless-fallback callout, blinkenlights pointer.
• Technical Reference placeholders filled in place: controller.md receives the modes, sequences, watchdog, standby, authoritative LED/state table, and config defaults; power-supply.md receives the input stage, current limiting, and super-capacitor detail.
• Fact corrections, verified against HALPI2-firmware source and a live device (fw 3.3.1 / halpid 5.1.1): watchdog default 10 s (was documented as 30 s), input voltage 10–32 V (was 11–32 in two places), standby is shipped and its CLI form is halpi shutdown --standby --time … (halpi standby does not exist), troubleshooting LED table reconciled with led_patterns.rs (three documented patterns did not exist in firmware).
• Link fixes: four Getting Started links pointed to the operation page for procedures that live in the Hardware Guide; retargeted removed-anchor references; dropped phantom "Common Use Cases" mentions.
• Nav: "System Operation" → "Daily Operation", deduplicated "Interfaces and Connectivity" titles, flattened single-page Getting Started section, empty placeholder pages removed from nav (files kept).
• FAQ seeded with the recurring daily-operation questions.

All 9 locale editions are synced in this PR: the four rewritten pages are fully re-translated, the eight diff-touched pages carry the equivalent edits, nav_translations covers the renamed titles, and every page is stamped (translation_status reports all locales current).

mkdocs build --strict passes; 10,610 anchors across 202 pages resolve; per-language glossary and typography checks pass.

Part of #46 (phase 1 — does not close it).

🤖 Generated with Claude Code

[mairas]

Code Review — PR #47

Scope: origin/main..docs/daily-operation-restructure — 11 files, +287/−227 (before review fixes).
Intent: Restructure the first User Guide page for mainstream users; move firmware internals to Technical Reference; correct facts against firmware 3.3.x; preserve URLs and the #status-led-indicators anchor.
Reviewers: correctness, testing, maintainability, project-standards (always-on) + adversarial (diff ≥ 50 lines; user-facing factual claims with physical consequences). All 5 returned results.

The two P1 product findings were independently re-verified by the orchestrator against halpid and firmware source before being reported here.

P1 — High

#	File	Issue	Reviewer(s)	Conf.	Route
1	docs/en/user-guide/operation.md:13	halpi shutdown is documented as a graceful shutdown, but halpid's POST /shutdown only writes the I2C register — nothing runs poweroff, and the controller hard-cuts the rails after 60 s. Product bug, filed as HALPI2-rust-daemon#103.	adversarial (verified)	0.88	gated — docs must stop recommending the command until the daemon is fixed
2	docs/en/technical-reference/controller.md:78	Standby is documented as powering down the CM5, but halpid's POST /standby never halts the OS and the firmware waits for a ComputeModuleOff that never comes — Linux keeps running behind standby LEDs. Product bug, filed as HALPI2-rust-daemon#104.	adversarial (verified)	0.85	gated — same
3	docs/en/technical-reference/controller.md:83, software.md:364	Documented standby datetime example (T separator, no offset) is rejected by halpid's parser.	correctness, adversarial	1.0	fixed in a55bf35

P2 — Moderate

#	File	Issue	Reviewer(s)	Conf.	Route
4	mkdocs.yml	Renamed nav titles ("Daily Operation", "Interface Reference") have no nav_translations keys — all 9 locale sidebars now show them in English; 45 stale keys remain.	all 5 reviewers	1.0	gated — add 18 keys + delete stale ones, or defer to phase 2
5	power-supply.md:9 vs hardware.md:11,30,75	Input range contradiction: 10–32 VDC (shop, index, new pages) vs 9–36 VDC (Hardware Reference, unchanged). Firmware's blackout threshold is 9.0 V. Already an open question in #46.	correctness, testing, maintainability, adversarial	0.95	human — owner decision
6	controller.md:72	watchdog_timeout documented as configurable, but halpid re-applies a hardcoded 10 s at every daemon start. Filed as HALPI2-rust-daemon#105.	correctness, adversarial (verified)	0.95	gated — docs caveat until resolved
7	controller.md:127	solo_power_off_threshold documented as active behavior; the firmware stores and reports it but never reads it. Filed as HALPI2-firmware#41.	adversarial (verified)	0.85	gated — mark stored-but-unused
8	hardware.md:248, index.md:112	Both still send readers to Advanced Configuration, which this PR removed from the nav (page is a 7-line stub, now unreachable by navigation).	maintainability, project-standards, correctness, testing	0.9	gated — retarget or drop
9	operation.md:15, faq.md:5	"Wait for the LEDs to turn off, then disconnect input power" is a 5-second race: LEDs-off and the auto-restart timer start simultaneously.	adversarial	0.8	gated — reword
10	getting-started.md:159	"Shutting Down the Device" retells the full shutdown/auto-restart story with no link to Daily Operation — will drift. ("violet"→"purple" already fixed.)	maintainability	0.8	gated — trim to summary + link
11	troubleshooting.md:56	Firmware-rollback recovery step tells the user to control a 30 s wait that auto-restart may not let them control. Pre-existing; mechanism needs verification. Filed as HALPI2-firmware#42.	adversarial	0.7	file-issue ✓ (filed)

P3 — Low

#	File	Issue	Reviewer(s)	Conf.	Route
12	technical-reference/interfaces.md:1	Nav entry says "Interface Reference"; the page H1 is still "Interfaces and Connectivity" — the ambiguity the rename was meant to remove survives in page titles and search.	project-standards, testing	0.8	gated — rename H1
13	operation.md	18 previously published anchors disappear with no alias; external deep links land at page top.	testing	0.78	advisory — accepted, noted in PR description
14	controller.md:94	PowerOff LED row said "input power present"; firmware condition is the opposite.	correctness	0.8	fixed in a55bf35
15	operation.md:7	"There is no power button" contradicted the External Buttons interface docs.	correctness, adversarial	0.75	fixed in a55bf35
16	operation.md:7	Powering On skipped the rainbow/color-cycle phase; the LED table read it as a fault.	adversarial	0.7	fixed in a55bf35
17	operation.md:44	Repeated short dips deplete the super-capacitors faster than they recharge (25 s at 0.9 A); "operation continues undisturbed" is true per-dip, not cumulatively.	adversarial	0.65	advisory
18	software.md:324	Sample halpi config output shows led_brightness 40; the new defaults table says 48. Sample is device-state, not defaults.	maintainability, testing	0.7	advisory — phase 2
19	controller.md:37 / power-supply.md:42	The 9.0 V threshold and 5 s blackout timer are stated in near-identical prose on both new pages.	maintainability	0.75	advisory — editorial
20	troubleshooting.md:140	LED semantics now live in three tables (operation, controller, troubleshooting).	maintainability	0.7	advisory

Applied fixes (commit a55bf35)

• Standby datetime examples corrected in controller.md and software.md (space-separated local form; noted Z/offset variant).
• PowerOff LED row corrected to the firmware condition.
• Power-button claim qualified with a pointer to External Buttons.
• Startup animation added to Powering On.
• Co-op power-loss detection attributed to the daemon's own monitoring.
• Getting Started "violet" → "purple".

Pre-existing (action taken)

• Finding 11 → HALPI2-firmware#42 (verification).
• daemon.md placeholder kept in nav while four others were pruned: intentional — its fill is a named phase-2 item in Restructure System Operation into a user-first Daily Operation page #46.

Coverage

• Testing independently reproduced the PR's verification claims: strict build green, check_anchors.py 9,950 links across 202 pages all resolving, and every numeric claim re-checked against firmware 3.3.1 constants — all hold.
• Residual risk (all reviewers): the 9 locale trees keep serving the old System Operation content (11–32 V, 30 s watchdog, standby-as-future) until phase 2 lands; the language switcher makes the contradiction one click away.
• Testing-gap candidates for phase 2: a nav_translations completeness check, a docs-CLI-example parse check, and a cross-page numeric consistency check — each would have caught a finding in this PR mechanically.
• Untracked files excluded from scope: book/, .claude/settings.local.json.

Verdict

Not ready. The docs work itself is sound, but items 1–2 mean the PR currently documents two commands that do not do what they say; the docs stance on those (warn vs remove) plus items 4, 8, 9, 10, 12 and the voltage decision (5) need resolution before merge. Fix order: 1–2 docs stance → 8/9/10/12 edits → 4 nav keys → 5 voltage decision. Review-fix commits will be folded into their topic commits before merge.

🤖 Generated with Claude Code

[mairas]

Review follow-up — resolution of the gated findings (decisions by @mairas):

• Findings 1 and 2 (halpi shutdown / standby broken in halpid): docs stay as-is; the daemon fixes (HALPI2-rust-daemon#103, #104) are expected to land before or with this docs release.
• Finding 4 (nav_translations): deferred to the phase-2 translation PR; locale sidebars show the two renamed titles in English until then.
• Finding 5 (input voltage): decided — 10–32 VDC is canonical everywhere; the three 9–36 entries in the Hardware Reference are aligned (38.6 V absolute max and 100 V transient figures kept).
• Finding 8: orphaned Advanced Configuration links retargeted (hardware.md → Software Guide) or dropped (index.md).
• Finding 9: shutdown race reworded — cutting power directly is now the stated method, with the ~5 s window called out; the auto_restart false option carries a physical-reach caveat.
• Finding 10: Getting Started shutdown section trimmed to a summary linking Daily Operation.
• Finding 12: technical-reference interfaces H1 renamed to "Interface Reference".
• Findings 6 and 7: kept documented as-is per the same leave-as-is decision; behavior tracked in HALPI2-rust-daemon#105 and HALPI2-firmware#41.

Review-fix commits are folded into their topic commits; the branch was force-pushed (history: 5 commits, 34f03f7..0848ca7). Strict build and the anchor sweep pass.

🤖 Generated with Claude Code

[github-actions]

Translation status

da — 20 current
de — 20 current
es — 20 current
fi — 20 current
fr — 20 current
it — 20 current
nb — 20 current
nl — 20 current
sv — 20 current

Every translation of the pages in scope is current.

[mairas]

Fact correction: the firmware constant DEFAULT_AUTO_RESTART = true is not the shipped default — the production test suite writes auto_restart = false into every unit since early 2026 (HALPI2-tests tests/200_controller/222_set_auto_restart_action.py). The issue body fact sheet and the PR #47 pages (Daily Operation, FAQ, controller reference) are updated: current units stay off after a software shutdown; enabling restart is the opt-in, and pre-2026 units shipped with it enabled.