docs: reframe the DNS options as intents #98

Merged

mysticalsoap merged 1 commit from change/readme-dns-intents into trunk

2026-08-20 17:42:03 -04:00

mysticalsoap commented

2026-08-20 17:17:28 -04:00

Owner

Problem

The alternative-DNS bullet accreted four concerns across #94 and #97 — enforcement wording, bypass resolver behavior, the split-horizon recipe, and a firewall caveat — and the other two DNS bullets described mechanisms rather than what a user is choosing.

Fix

Each DNS option now states one intent — whose resolvers answer tunneled DNS: the provider's (the default, noted in passing), yours, or nobody's:

Always use alternative DNS servers opens with the intent, states the slot semantics (primary plus true fallback with automatic return, post-#96), and keeps the split-horizon recipe in one sentence.
Never change DNS servers says what actually happens — lookups keep going wherever the system already sends them — instead of naming resolv.conf.
Use same DNS servers for bypass says what it skips and the consequence.

Bypass DNS behavior (#97's network-first resolution) moves to the Bypass section, which owns that feature — one home per fact.

Verification

Docs-only; rendered output proofread. No behavior described that the code does not have.

**Problem** The alternative-DNS bullet accreted four concerns across #94 and #97 — enforcement wording, bypass resolver behavior, the split-horizon recipe, and a firewall caveat — and the other two DNS bullets described mechanisms rather than what a user is choosing. **Fix** Each DNS option now states one intent — whose resolvers answer tunneled DNS: the provider's (the default, noted in passing), yours, or nobody's: - *Always use alternative DNS servers* opens with the intent, states the slot semantics (primary plus true fallback with automatic return, post-#96), and keeps the split-horizon recipe in one sentence. - *Never change DNS servers* says what actually happens — lookups keep going wherever the system already sends them — instead of naming resolv.conf. - *Use same DNS servers for bypass* says what it skips and the consequence. Bypass DNS behavior (#97's network-first resolution) moves to the Bypass section, which owns that feature — one home per fact. **Verification** Docs-only; rendered output proofread. No behavior described that the code does not have.

mysticalsoap added 1 commit

2026-08-20 17:17:28 -04:00

docs: reframe the DNS options as intents

ci / test (pull_request) Successful in 30s

Details

e6ab714f2a

The alternative-DNS bullet had accreted four concerns across #94 and
#97: enforcement wording, bypass resolver behavior, the split-horizon
recipe, and a firewall caveat. Each option now states one intent --
whose resolvers answer tunneled DNS: the provider's (default), yours,
or nobody's -- with the slot semantics (primary plus true fallback,
post-#96) on the option where the user picks the slots.

Bypass DNS behavior moves to the Bypass section, which owns that
feature; the alternative-DNS bullet no longer describes it.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

mysticalsoap force-pushed change/readme-dns-intents from e6ab714f2a

ci / test (pull_request) Successful in 30s

Details

to 5e2255ab90

ci / test (pull_request) Successful in 36s

Details

ci / test (push) Has been cancelled

Details

2026-08-20 17:24:57 -04:00

Compare

mysticalsoap merged commit 5e2255ab90 into trunk

2026-08-20 17:42:03 -04:00