This file is a living FAQ — known failure modes and recovery paths. Add a new entry every time you debug something that took more than 15 minutes; future-you (and other maintainers) will thank you.
Symptom: short reproduction. What does the user see?
Cause: root cause (one or two sentences).
Fix:
<the actual commands to recover>Avoidance: how to not hit this again (config setting, doc link, etc.).
When something is wrong, run these first:
just doctor # runs all available self-checks
just version # prints the version & build hash
just log-tail # last N lines of logs-
Filed an issue with: version, OS, exact command, full error output, and the symptom in plain English.
-
Linked from the issue: the relevant ADR(s) and any related issues.
-
For security-relevant findings, see SECURITY.md — do not file public issues.
-
docs/architecture.adoc— internals. -
docs/decisions/— historical record of why things are this shape. -
https://github.com/hyperpolymath/ipv6-site-enforcer/issues?q=is%3Aissue+<your symptom>— has anyone hit this before? -
https://github.com/hyperpolymath/standards/issues— for estate-wide problems.