docs(lifeboard): user guide, bridge setup, QA guide, persistence audit

[ivanmkc]

The stack

#	PR	What it adds	Tests at this point
1	#311	A real localStorage for the test suite on Node 25	viewer 747
2	#312	@ivanmkc/termchart-canvas; injectable interact transport	canvas 473 · viewer 278
3	#313	lifeboard PWA: fact log, boards, service worker	lifeboard 36
4	#314	Shell, family profiles, tap layer	lifeboard 82
5	#315	The agent turn, four providers, Connections	lifeboard 142
6	#316	Packs, recipes, shopping-list arithmetic	lifeboard 231
7	#317	Provenance and lineage	lifeboard 257
8	#318	Calendar, Gmail, mail triage	lifeboard 301
9	#319	The bridge and long jobs	cli 314 · lifeboard 320
10	#310	Proactivity, scheduled boards, Google sign-in	cli 320 · lifeboard 343
11	#320	Persistence audit fixes: multi-tab, stale builds, no-storage boot	lifeboard 350
12	#321	User guide, bridge setup, QA guide, persistence audit	lifeboard 350
13	#322	A plan for third-party integrations (docs only)	unchanged
14	#323	A practice drill a board can define: audio + Q&A	canvas 485 · lifeboard 372
15	#325	Export and restore	lifeboard 389
16	#326	Draft a message, approve it, then send	lifeboard 399
17	#327	Hand long work to the Mac	lifeboard 406
18	#328	A Packs screen, and authoring one by describing it	lifeboard 418
19	#329	Activity — what changed, who changed it, undo	lifeboard 428
20	#330	Four defects found reviewing the stack	cli 323 · lifeboard 431

Every branch in the stack was checked out on its own and verified independently: npm install, tsc --noEmit for every package, npm test across the workspace, and the offline e2e where it exists. All twenty are green — no branch depends on a later one to build or pass. Full viewer e2e (11 suites, 106 assertions) was run on #312 as the behaviour-preservation evidence for the extraction.

---

Stack position: 12 of 12 — the top of the stack. Base: lifeboard/10-persistence.

Documentation, so someone who did not write this can run it, use it, test it, and know what it does not do.

Document	For
packages/lifeboard/README.md	Building on it: how to run it, how the fact log works and why, where each concern lives
docs/lifeboard/user-guide.md	The family. Boards, ticking, profiles, connecting an assistant, meals, mail, provenance, privacy
docs/lifeboard/bridge.md	Running turns through subscriptions you already pay for, and the bridge's security model
docs/lifeboard/qa-guide.md	Testing it: automated checks with expected counts, then a ten-section manual test plan
docs/lifeboard/persistence-audit.md	The audit behind the previous PR, including what is still open

Every guide ends by naming what is not there. Four capabilities are implemented and unit-tested but have no UI reaching them — sending email, starting a long job, sending a text message, authoring a pack by asking. The QA guide lists them under "do not file these" so nobody spends an afternoon on a bug that is a missing screen. The largest known risk — that there is no export or backup — is stated in the user guide, the README and the audit rather than left to be discovered.

The QA guide is a test plan, not a description. Ten sections with steps and expected results, weighted toward where getting it wrong is worst: section E walks the shopping-list arithmetic (re-scale must update in place, staples must never vanish, two incompatible amounts must not be summed), and section J covers the persistence edge cases the previous PR fixed — two tabs, a private window, a new build reaching a device that cached the old one.

Adds npm run serve, a dependency-free static server, because a guide that says "serve dist/ somehow" is a guide nobody follows. It binds all interfaces so an iPad on the same wifi can open it, normalises paths so a request cannot climb out of dist/ (verified against .., %2e%2e and ..%2f forms), and says on start-up that offline support needs localhost or HTTPS.

Verified: the numbers quoted in the QA guide were taken from real runs, not estimated — lifeboard 350, canvas 473, CLI 320, viewer 278, and 18 e2e assertions. The serve script was smoke-tested for routes, SPA fallback and traversal.

🤖 Generated with Claude Code