docs: add .adr/ and record the one-managed-front-door decision#37
Merged
Conversation
The reasoning for declining a second managed front door lived in a PR thread, which is exactly where it would be lost. The next NetBird-shaped proposal — Cloudflare Tunnel, ZeroTier, Twingate — would have re-derived it or quietly reversed it. .adr/ is for decisions that close off an option someone will reasonably propose again: the ones where you find yourself explaining why NOT rather than how. Not for what the code, a test name or CLAUDE.md already says. ADR 0001 records the front-door decision with what was actually measured — the one-line Tailscale coupling in the bridge, the credential leak into argv that PR #26 demonstrated, and that COLLIE_SKIP_SERVE=1 already made every other tunnel a one-command integration. Also the reversal condition, so it can be superseded deliberately rather than ignored. CLAUDE.md keeps the rule and drops the argument, per the split the folder's README sets out: rules there, reasoning here. Doc-only, no version bump. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
AltanS
marked this pull request as ready for review
July 27, 2026 07:02
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The reasoning for declining a second managed front door lived in a PR thread — exactly where it gets lost. The next NetBird-shaped proposal (Cloudflare Tunnel, ZeroTier, Twingate) would have re-derived it or quietly reversed it.
What's here
.adr/— decision records, Nygard format, numbered. Scoped deliberately narrow: decisions that close off an option someone will reasonably propose again, i.e. the ones where you find yourself explaining why not rather than how. Not a second home for things the code, a test name, or CLAUDE.md already say..adr/README.mdstates the split against the existing docs and the rule that a superseded ADR is marked, never edited into agreement with the present.ADR 0001 — Collie manages exactly one front door. Records what was actually measured rather than the summary:
req.headers.get("tailscale-user-login")), so "too tied to Tailscale" was a docs problem, not an architecture oneCOLLIE_SKIP_SERVE=1+netbird expose 8787was already the whole integration — nobody was blocked--with-pin/--with-passwordin argv,/proc/<pid>/cmdlinemode 444) as the concrete cost of supervising someone else's authenticated processCLAUDE.md keeps the rule, drops the argument, and gains a short section pointing at
.adr/before reopening a settled question.Doc-only; no version bump (per CLAUDE.md).
Draft because the scope of
.adr/is a judgment call worth your eye — happy to narrow or widen what qualifies.