docs: self-hosting guide for what the quick start doesn't cover

[Seanathon]

Deploying board-oss to a Proxmox LXC surfaced four failure modes the README didn't cover. Each one fails quietly, which is what made them expensive.

New: docs/self-hosting.md

Container sizing and the unprivileged LXC features Chromium needs, binding when the reverse proxy runs on a different host, CLI-agent setup, backups, upgrades, and a symptom → cause → fix table.

The two that cost the most time:

The unit binds 127.0.0.1. With the proxy on another host this reads as a proxy fault — 502 from outside, healthy inside, /healthz passing. The fix is a wider bind plus a network-layer restriction, applied through a systemd drop-in rather than an edit to the installed unit. That distinction matters: scripts/install-lxc.sh runs install -m 644 … /etc/systemd/system/board-oss.service, overwriting unconditionally, so an in-place edit is silently reverted on the next upgrade and the service goes unreachable again.

board-oss spawns a CLI agent by bare command name, with cwd set to a temp directory (src/llm/cli-provider.ts). So systemd's minimal PATH cannot find a binary the operator's shell finds. Authentication is also interactive and must run as the service user with the unit's HOME, and reproducing as root exercises a different environment than the service uses.

README

• CAPTURE_TIMEOUT_MS added to the config table, with the real number behind it: a CLI agent routinely takes 90–100s per item, so the 180s default is sized, not generous.
• The cross-host bind case, with the drop-in warning.
• The three CLI-agent failure modes, linking to the guide for verification commands.
• Portability now describes the .tar backup (boards, items, and image bytes) alongside the existing "copy DATA_DIR" advice, and notes that a container snapshot is a different backup covering the install and credentials that the collection export deliberately doesn't carry.

Voice

Written against the vault house style: American English, no stock phrases, answer-first opener, headings that carry meaning when skimmed alone. That pass replaced "happy path", "gotchas" and "backup stories", and rewrote a first line that restated its own heading.

It also corrected six British spellings — three in the new document, three in prose I wrote earlier in the same session (two code comments and one test name). Those three are the only non-.md changes here: text only, no behavior change. 574 tests still pass.

Two deliberate deviations from that style guide, which is written for vault notes: noun-phrase titles rather than claim-titles, and hard wrapping rather than one-sentence-per-line, both to match the repo's existing docs.

Not covered

Only the reader-facing docs were reviewed — README.md, the new guide, and docs/integrations.md (already clean). The BMAD planning artifacts (prd.md, research.md, product-brief.md, docs/bmad/, docs/planning/, docs/stories/) are untouched: ~100KB of generated internal output, far less payoff than the docs a stranger actually reads.

🤖 Generated with Claude Code

https://claude.ai/code/session_01C83mrW9X8zBLY1sSZRgdCa