project plan, values, milestone 1 spec, zig 0.16 api research

AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+## Aim
+
+nxdns: a self-hosted DNS sinkhole for a household LAN, written in Zig 0.16.0.
+Portfolio-grade public repo. PLAN.md is the source of truth for scope and design;
+specs/ holds per-milestone contracts; specs/research/ holds verified stdlib facts.
+
+## Values
+
+We intentionally architect this code to be robust, maintainable, pragmatic —
+good craftsmanship and good engineering. We explicitly avoid tech debt, code
+smells, bad architecture decisions, and brittle implementations.
+
+What that means in practice:
+
+- This is a greenfield project. Breaking changes are allowed. Never keep a bad
+  interface for compatibility; fix it at the root.
+- No versioning of scope. A feature is in scope (build it completely) or out of
+  scope (do not build it). No "v2 later", no stubs left behind.
+- Fix root causes, not symptoms. Do not iterate on workarounds.
+- Scope is small on purpose: household scale, two targets, few dependencies.
+  Do not add generality nobody asked for.
+- Dependencies are liabilities: stdlib first; vendored + pinned C deps
+  (sqlite3, mbedTLS) only where the stdlib has nothing.
+- Verify stdlib claims against ../zig at tag 0.16.0 — pre-0.16 knowledge is
+  stale (std.Io migration). See specs/research/zig-0.16-api-notes.md.
+- Pure core: dns/, filter/, local/, cache/ take bytes and return bytes — no Io,
+  no sockets, no clocks hidden inside.
+- Every failure mode must be visible: no silent drops, no unbounded logs, no
+  swallowed errors. Counters + health surfaces over log spam.
+- Tests are runnable acceptance criteria, not decoration. Required CI stays
+  deterministic — no network-dependent tests in blocking jobs.
+- Comments state constraints the code cannot show. No narration, no
+  commented-out code.
+- Git: GPG-signed commits (`git commit -S`), simple lowercase messages, no
+  generated-by footers.