@wenathlan/argan 2.0.154 → 2.0.158

package/README.md

@@ -19,10 +19,11 @@ pnpm dev
 
 # The family contract (wave 6-a)
 
-- `family.ts` — the single table of the eight siblings beside argan with the
-  spec §12 accent of each one; the shell rail foot, the landing footer and
-  `tests/family.test.ts` all consume this one table.
-- `familyurl.ts` — the verbatim relative-url contract (`"../" + slug + "/"`)
+- `family.ts` — the family keyword file (the fold law): the single table of
+  the eight siblings beside argan with the spec §12 accent of each one — the
+  shell rail foot, the landing footer and `tests/family.test.ts` all consume
+  this one table — plus the retired `familyurl.ts` arm riding as the
+  familyurl lane: the verbatim relative-url contract (`"../" + slug + "/"`)
   that keeps every cross-app link mount-proof.
 - `restore:entry` — the entry-face guard: a no-op while `index.html` rides the
   canonical source face (the `./App.tsx` script plus the font triad link), a

package/cli.ts

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+/**
+ * @file cli.ts — the argan binary seat of the clibin wave (PR13 — CLI
+ *   binário mesmo design): the same Windows 11 chat console as the web and
+ *   desktop surfaces, rendered inside the terminal as a subapp — the only
+ *   difference is responsiveness / DPI (the 28px top rule becomes one line
+ *   and the accent falls back to the ANSI 256 palette).
+ * @module argan/cli
+ * @family wave/clibin
+ * @law same design as web / desktop, difference only responsiveness / DPI
+ * @seat 2026 · rung 2.0.157 · hierarchical JSDoc, tokens/flags, no hardcoded
+ *   data — the version is read from package.json at runtime and the engine
+ *   one-liner is quoted from the app docs.
+ * @runtime node strips the types; the shebang hands the file to the runtime
+ *   (the saddle law).
+ * @deps zero — node builtins only (readline/promises, process, fs/promises).
+ */
+
+import { createInterface } from "node:readline/promises";
+import { argv, exit, stdin, stdout } from "node:process";
+import { readFile } from "node:fs/promises";
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 1: the chrome tokens — the windows 11 palette folded to the DPI of the terminal (the accent #a3d7e6 lands on ansi 117, the focus #4cc2ff on 75, the hover red rgb(232,17,35) on 203; the 28px top rule becomes one line). */
+/* ════════════════════════════════════════════════════════════════════ */
+
+/** the chat accent of the prompt and the titlebar name. */
+const ACCENT = "\x1b[38;5;117m" as const; // #a3d7e6
+/** the focus ink of the active top rule. */
+const FOCUS = "\x1b[38;5;75m" as const; // #4cc2ff
+/** the hover red of the unknown-command rows. */
+const HOVER = "\x1b[38;5;203m" as const; // rgb(232, 17, 35)
+/** the dim ink of the description rows (the minimal text law). */
+const INK = "\x1b[2m" as const;
+/** the reset token that closes every colored run. */
+const RESET = "\x1b[0m" as const;
+/** the single glyph of the rules and the rails. */
+const BAR = "─" as const;
+
+/** the app name of this binary seat — the titlebar text. */
+const APP = "argan" as const;
+/** the engine ownership one-liner, quoted from the app docs. */
+const ENGINE =
+  "the network, DNS and edge engine of the devthink family — authoritative zones, record snapshots, dnssec validation math, a 231-protocol gateway mesh and a 3217-row media type catalog (docs/engine.md)" as const;
+
+/** the titlebar bar: the app name on the left rail, the window controls on the right — the windows 11 chrome inside the terminal. */
+function titlebar(): string {
+  return `${ACCENT}┌ ${APP} ─ cli${RESET}  ${INK}${BAR.repeat(24)} ─ ❐ ✕${RESET}`;
+}
+
+/** the top rule: the 28px divider of the web surface folded to one terminal line. */
+function toprule(): string {
+  return `${FOCUS}${BAR.repeat(3)} ${APP} ${BAR.repeat(3)}${RESET}`;
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 2: the runtime reads — no hardcoded data; the version comes from package.json at runtime. */
+/* ════════════════════════════════════════════════════════════════════ */
+
+/** reads the version of this seat from the sibling package.json — never a literal. */
+async function readversion(): Promise<string> {
+  try {
+    const manifest = JSON.parse(await readFile(new URL("./package.json", import.meta.url), "utf8")) as { version?: string };
+    return manifest.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
+
+/* ════════════════════════════════════════════════════════════════════ */
+/* Section 3: the chat console — the REPL with the ❯ prompt, the command dispatch and the same chat look as the web surface. */
+/* ════════════════════════════════════════════════════════════════════ */
+
+/** the command help of the console — minimal text law: title + description only. */
+function help(): string[] {
+  return [
+    `${INK}commands${RESET}`,
+    `  help      ${INK}this list${RESET}`,
+    `  version   ${INK}the package version, read from package.json at runtime${RESET}`,
+    `  engine    ${INK}the engine ownership one-liner of the app${RESET}`,
+    `  exit      ${INK}close the console${RESET}`,
+  ];
+}
+
+/** runs the chat console: the titlebar, the top rule, the ❯ prompt and the dispatch (help, version, engine, exit); an eof on stdin closes the console the same way exit does. */
+export async function main(): Promise<void> {
+  /* the version read happens before the interface exists, so a piped stdin never races the readline open (node buffers the pipe until the reader resumes it). */
+  const version = await readversion();
+  const rl = createInterface({ input: stdin, output: stdout });
+  let eof = false;
+  rl.on("close", () => { eof = true; });
+  console.log(titlebar());
+  console.log(toprule());
+  console.log(`${ACCENT}${APP}${RESET} ${INK}v${version}${RESET}`);
+  console.log(`${INK}the ${APP} console — same design as web / desktop, only the DPI differs. type help.${RESET}`);
+  rl.setPrompt(`${ACCENT}❯${RESET} `);
+  rl.prompt();
+  for await (const raw of rl) {
+    const line = raw.trim();
+    const command = line.length > 0 ? line.split(/\s+/)[0]!.toLowerCase() : "";
+    if (command === "exit") rl.close();
+    else if (command === "help") for (const row of help()) console.log(row);
+    else if (command === "version") console.log(`${ACCENT}${APP}${RESET} ${version}`);
+    else if (command === "engine") console.log(`${INK}${ENGINE}${RESET}`);
+    else if (command.length > 0) console.log(`${HOVER}✕${RESET} ${INK}unknown command: ${command} — type help${RESET}`);
+    if (command === "exit") break;
+    /* the prompt is cosmetic chrome: a piped stdin that already reached eof skips it, the buffered lines still answer. */
+    if (!eof) rl.prompt();
+  }
+  console.log(`${INK}${APP} console closed.${RESET}`);
+}
+
+/* the autorun guard (the saddle law): only a direct `node cli.ts` (or a bun run) boots the console here — an import stays quiet. */
+if (import.meta.url === `file://${argv[1]}`) main().catch((error) => { console.error(error); exit(1); });

package/docs/engine.md

@@ -0,0 +1,60 @@
+# argan engine
+
+The network, DNS and edge engine of the devthink family: authoritative zones, record set snapshots, DNSSEC validation math, a 231-protocol gateway mesh, a 3217-row media type catalog and a self-hosted SQLite data layer, served to a Vite + React Sol surface.
+
+## Overview
+
+Argan is the DNS and gateway library of the wenathlan family (`@wenathlan/argan`, version 2.0.155). The engine lives as library-grade TypeScript modules at the app root; the web surface lives in `sol/` and renders every row from the data layer (seed rows offline, the site API over HTTPS when configured). The published package exports `./mimetypes` for family consumers (the vault storage engine among them).
+
+## Module inventory
+
+- `argan.ts` — the domain core: types for zones (`ZoneSnapshot`), record sets (`RecordSetRow`), publication steps, feature cards, signal badges, DNS transports, config blocks, rollover steps and option choices; helpers `formatSerial` (YYYYMMDDNN serials), `nextSerial` (revision bump, rolls at 99), `findZone`, `transportsByPort`, `apexZoneFile` (verbatim zone file rebuild) and `findConfigBlock`.
+- `dnssec.ts` — the DNSSEC validation math: RRSIG presentation parsing (RFC 4034 §3.1), the RFC 4034 Appendix B key tag checksum, signature validity window with clock skew, RRset/RRSIG TTL equality, the label-count wildcard rule and the DS→DNSKEY structural match. Answers 8 IANA algorithms (5, 7, 8, 10, 13, 14, 15, 16) and 3 DS digest types (SHA-1, SHA-256, SHA-384); every failed check names one of 11 typed failure codes. Cryptographic signature verification itself is deliberately out of scope.
+- `mimetypes.ts` — the media type catalog: 3217 rows across 10 families (application 2245, text 260, audio 255, video 138, image 170, chemical 54, model 45, message 27, multipart 17, font 6). Extension collisions resolve in family order (`.ts` answers `video/mp2t`, `.tsx` answers `application/typescript`). The engine tail adds the corpus layer: `parseMimeCorpus` and `createMimeCatalog` (families, type/extension/entry counts, `mimeTypeFor`, `extensionsFor`, `contentTypeFor` with the `application/octet-stream` default).
+- `protocols.ts` — the gateway protocol mesh: 231 protocol rows in 15 family groups (web 17, api 23, messaging 25, tunnel 25, legacy 29, file 16, stream 15, overlay 14, ops 14, dns 12, directory 11, mail 10, remote 9, data 7, collab 4). Each row names its port, governing spec and security posture — 84 encrypted, 60 opportunistic, 87 cleartext; `tlsCapableProtocols()` answers the 144 wires that run or upgrade to TLS-grade crypto.
+- `zonediff.ts` — the planned change set engine: a master-file parser (RFC 1035 §5.1 — `$ORIGIN`/`$TTL` directives, `@` apex, owner inheritance, parenthesized continuations, quoted strings, RFC 2308 TTL units) and an external-dns style planner (`diffZones`, `diffZoneFiles`, `recordsFromRows`, `serialForPublication`) that groups records by owner and type, compares targets as a set, reports `create`/`delete`/`update` with reason `targets` or `ttl`, and suggests the next serial through `argan.nextSerial`.
+- `catalog.ts` — the typed accessor the Sol pages call: 14 list functions (`listZones`, `listApexRecordSets`, `listTransports`, `listConfigBlocks`, `listProtocols`, `listMimetypes` and friends) that fetch from `VITE_CATALOG_URL` over HTTPS when configured or answer from the in-memory seed, behind a memoized promise cache that retries failed fetches.
+- `db.ts` — the self-hosted SQLite runtime: opens better-sqlite3 through `openStorageLane` from `@wenathlan/vault/storagelane` (default file `./local.db`), re-exports the parameterized helpers `execute`, `queryAll`, `queryOne` — no SQL is ever assembled by string concatenation.
+- `seed.ts` — the in-memory content tables: 5 zones, the apex `devthink.pro` record set snapshot (A, AAAA, CAA, MX, NS, SOA, TXT rows), 5 publication steps, 4 library cards, 2 DNSSEC key cards, 3 DoH-first cards, 3 hero badges, 4 algorithm badges, 8 transports, 2 config blocks, 4 rollover steps, 5 resolver choices and 2 locale choices.
+- `labels.ts` — the copy law: an English manifest of 183 interface strings (`LABEL_MANIFEST`, revision 2) with the accessors `label`, `labelfill` and the browser-side `seedLabels`; the store factory comes from `@wenathlan/vault/labelstore`. Translated rows are protected from seed overwrites.
+- `cleanurl.ts` — the clean URL bar: hash routes become paths, `index.html` and duplicate slashes disappear, and campaign trackers (utm, gclid, fbclid, msclkid, dclid, igshid, yclid, twclid, `_tt`, srsltid and friends) are stripped with `replaceState` — no reload, no history pollution.
+- `theme.ts` — the light-fusion theme default: `dark`/`light` on the `data-theme` document attribute, session scope only, no cookies or storage.
+- `motionpref.ts` — the in-session reduce-motion switch: rides session storage under `argan.motion.reduced` and the `data-motion="reduced"` document flag, additive on top of `prefers-reduced-motion`.
+- `reveal.ts` — scroll reveal: an IntersectionObserver at 12% visibility adds the `in` class once per element.
+- `onboardingstate.ts` — the first-run state: the only writer of the intro/onboarding seen flags; DB is the source of truth over `GET`/`POST /api/v1/onboarding` (base `VITE_ONBOARDING_URL`, host-validated — localhost, loopback, private and reserved ranges refused), with the localStorage key `argan.onboarding.seen` as a pure cache mirror and a stable per-browser visitor id.
+- `sandboxmodality.ts` — the workload lane declaration: 4 mirrored lanes (`dnssec-validate`, `zonefile-parse-diff`, `catalog-registry-serve`, `label-store-seed`) with role, demand and boot budget; resolves the deploy's `ARGAN_SANDBOX_LANE` seat (local, join, or a pinned modality id).
+- `family.ts` — the family keyword file (the fold law): the family table — the 8 sibling slugs (cadria, debonair, forge, foundry, getry, saddle, stealthhead, vault) with the spec §12 accent and dot-ink of each, consumed by the shell rail, the landing footer and the family test — plus the retired `familyurl.ts` arm riding as the familyurl lane: the cross-app URL contract where `familyurl(slug)` answers the relative `"../" + slug + "/"` path so every family link survives any mount point.
+
+## Data layer
+
+- Storage: better-sqlite3 via the vault `storagelane` (`openStorageLane`, default file `./local.db`); the schema mirrors `schema.prisma`.
+- Tables: 7 — `zones`, `record_sets`, `dnssec_keys` (algorithm default 15, ED25519), `gateway_routes`, `content_rows`, `onboarding_state` and `labels`.
+- Bootstrap: `ensureSchema()` creates the tables idempotently; `seedIfEmpty()` inserts the 11 seed content kinds plus zones and record sets inside one transaction on first run.
+- Accessors: `zoneRow`, `recordSetRows`, `getonboardingstate`, `setonboardingstage` (seen-monotonic upsert), `saveLabel`, `readLabel`, `readAllLabels`, `seedLabelRows` (ingests the labels manifest, protects translated rows; rides the boot best-effort).
+- Serving: `catalog.ts` serves the same tables to the Sol pages over HTTPS when `VITE_CATALOG_URL` points at the site API; a page never hardcodes a row.
+
+## Sol surface
+
+- `sol/Sol.tsx` — the theme anchor and route tree: `/intro`, `/onboarding`, `/`, `/zones`, `/dnssec`, `/gateway`, `/settings`, `/404` plus the catch-all.
+- `sol/home/` — the landing: a dig-style local resolver over the served apex snapshot (query types A, AAAA, MX, NS, TXT, SOA, CAA; wildcard honored; honest ok/nodata/nxdomain verdicts), hero badges, the zones and library ledgers, publication steps, the apex CTA and the family footer; the entry gate decides between intro, onboarding and the landing.
+- `sol/zones/` — the zones console: the zone ledger with the apex featured and the newest serial pulsing, the 5-step publication rail, the apex record set ledger and the verbatim zone file one summary away.
+- `sol/dnssec/` — the DNSSEC console: the KSK/ZSK key ledger, the algorithm badges, the sign-pipeline output as a terminal and the 4-step rollover ladder.
+- `sol/gateway/` — the gateway console: the transport table (8 transports — classic 53, DoT 853, DoH 443, DoH JSON, DoQ, DoH3, DNSCrypt, ODoH), the 3-step DoH-first rail and the staging Corefile terminal.
+- `sol/settings/` — the settings console: three numbered sections (appearance, clean URLs, network) with the theme switch, the reduce-motion switch, resolver and locale selects and a live clean-URL demo.
+- `sol/intro/`, `sol/onboarding/` — the first-run flow: a 1.6s splash with the drawn mark and three Windows 11-style first-run frames; both mark their stage through `onboardingstate.ts`.
+- `sol/shell/` — the app frame: full-bleed standalone law, the page rail, the family foot with one accent dot per sibling, the theme flip and the `ArganMark` icon.
+- `sol/notfound/` — the single 404 (RCODE 3, NXDOMAIN).
+- `sol/toast/` — the toast surface: a role=status live region with success, error and info tones.
+- `sol/wingets/` — the shared widgets: `HomeEntrygate` (the first-run gate) and `ShellEmptystate` (glyph, one line of truth, one action, pending shimmer).
+
+## Family integration
+
+- `@wenathlan/vault/storagelane` — the SQLite lane `db.ts` opens (`openStorageLane`, `SqlParam`).
+- `@wenathlan/vault/labelstore` — the label store factory `labels.ts` rides; the vite and vitest configs bridge the specifier to the monorepo source.
+- `saddle/workloadlaw.ts` — the `FAMILYLANES` engine of record that `sandboxmodality.ts` mirrors (rows mirrored, not imported; the vitest battery pins the mirror against the engine source through the library bridge).
+- `family.ts` — the 8 sibling deploy units in rail order, linked out through relative URLs (the familyurl lane of the fold answers the links).
+- Runtime dependencies include `@wenathlan/cadria`, `@wenathlan/debonair`, `@wenathlan/devthink`, `@wenathlan/getry`, `@wenathlan/saddle` and `@wenathlan/vault` (all `~2.0.155` family envelopes).
+
+## Testing
+
+Seven vitest batteries at `tests/`: `design.test.ts`, `dnssec.test.ts`, `family.test.ts`, `mimetypes.test.ts` (pins the 3217 count), `protocols.test.ts` (pins 231 rows and the 144 TLS-capable wires), `sandboxmodality.test.ts` and `zonediff.test.ts`.

package/docs/features.md

@@ -0,0 +1,75 @@
+# argan features
+
+Real feature list of the argan engine and its Sol surface, extracted from the code — every entry names a module.
+
+## DNS
+
+- Zone table — `argan.ts` types the managed zones (origin, master/slave kind, YYYYMMDDNN serial, signed state); the seed carries 5 zones with `devthink.pro` as the apex.
+- Serial management — `formatSerial` builds the YYYYMMDDNN serial (UTC date plus daily revision) and `nextSerial` bumps it, rolling the revision at 99.
+- Record set snapshots — `RecordSetRow` carries the verbatim zone-file line of every apex record (A, AAAA, CAA, MX, NS, SOA, TXT in the seed); `apexZoneFile` rebuilds the zone file text from the rows.
+- Zone file parser — `zonediff.ts` `parseZoneRecords` handles `$ORIGIN`, `$TTL`, the `@` apex, owner inheritance on indented lines, parenthesized continuations, quoted strings, both `[ttl] [class]` orders and RFC 2308 TTL units (s/m/h/d/w), throwing `ZoneDiffError` with the offending line number.
+- Zone planner — `diffZones`/`diffZoneFiles`/`recordsFromRows` diff two zone versions into create/delete/update changes grouped by owner and type; round-robin order never produces a change and an unconfigured TTL never triggers an update.
+- Publication serial — `serialForPublication` keeps the serial when the diff is empty and bumps it through `nextSerial` otherwise.
+- Dig resolver — `sol/home/home.tsx` parses dig-style queries (`dig <name> [TYPE]`, verb optional) and resolves them against the served apex snapshot with the wildcard honored, answering ok, nodata or nxdomain.
+- Record type chips — the home resolver offers A, AAAA, MX, NS, TXT, SOA and CAA, intersected with the served rows.
+- Publication flow — the 5-step rail (Validate, Write zone, Persist, Republish, Serve) served from `seed.ts` through `catalog.ts` to the zones page.
+
+## DNSSEC
+
+- RRSIG parsing — `parseRrSig` reads the RFC 4034 §3.1 presentation fields, including zone-file UTC timestamps (YYYYMMDDHHmmSS), and rejects broken rows with `DnssecValidationError`.
+- Key tag checksum — `keyTag` computes the RFC 4034 Appendix B checksum over the DNSKEY rdata (`dnsKeyRdata`).
+- Validity window — `validateSignatureWindow` checks inception/expiration with a configurable clock skew on both edges.
+- TTL rules — `validateSignatureTtl` enforces the RRset/RRSIG TTL equality and the original-TTL ceiling.
+- Wildcard label rule — `validateSignatureLabels` checks the label count against the owner name with the wildcard drop rule.
+- DS match — `validateDsMatch` and `validateChainLink` check the DS→DNSKEY structural match over the IANA registries (key tag, algorithm, digest type, zone-key flag, protocol).
+- Typed verdicts — every failed check answers one of 11 `DnssecFailureCode` values, traceable from the resolver answer back to the row.
+- Algorithm registry — `DNSSECALGORITHMS` answers 8 IANA algorithms (RSASHA1 through ED448); `DNSSECDIGESTTYPES` answers 3 DS digest types.
+- Key cards — the dnssec page serves the KSK (360-day rollover, DS in the parent) and ZSK (90-day rollover, NIST SP 800-81r3) ledger from the data layer.
+- Rollover ladder — the 4-step key rotation timeline (Pre-publish T−30d, Switch T0, Retire T+TTL, Remove T+2TTL) with CDS/CDNSKEY DS swap.
+
+## Edge and gateway
+
+- Transport table — `seed.ts` carries the 8 DNS transports the gateway speaks: classic UDP+TCP 53, DoT 853, DoH 443, DoH JSON, DoQ 853/UDP, DoH3 443/UDP, DNSCrypt 443 and ODoH 443; `transportsByPort` filters by port.
+- Protocol mesh — `protocols.ts` registers 231 protocol rows in 15 family groups (web through legacy), each with scheme, port, governing spec and security posture; `findProtocol`, `protocolsByGroup`, `protocolSchemes` and `protocolGroups` serve the lookups.
+- TLS-capable count — `tlsCapableProtocols` answers the 144 wires that run encrypted or upgrade to it (84 encrypted, 60 opportunistic).
+- Security tones — `protocolTone` derives the badge tone of one protocol row from its posture and state.
+- Media type catalog — `MIMETYPES` carries 3217 media types across 10 families; `mimeTypeForExtension` resolves extensions in family order (`.ts` → `video/mp2t`), plus `findMimeType`, `extensionsForType`, `mimeFamilyOf` and `mimetypesByFamily`.
+- Corpus engine — `parseMimeCorpus` parses any registry corpus (the vault's `mime.types` lane among them) and `createMimeCatalog` builds the served catalog: families, type/extension/entry counts, `mimeTypeFor`, `extensionsFor`, `extensionOf` and `contentTypeFor` with the `application/octet-stream` default.
+- DoH-first strategy — the 3-step gateway rail (Probe on UDP/53, Switch to DoH on 443, Serve the same TTL-cached answers on every transport) served to the gateway page.
+- Staging Corefile — the gateway page renders the staging CoreDNS Corefile and the `argan sign` pipeline output as config blocks from `seed.ts`.
+- Clean URLs — `cleanurl.ts` rewrites hash routes to paths, drops `index.html` and duplicate slashes, strips campaign trackers (utm, gclid, fbclid, msclkid, dclid, igshid, yclid, twclid, `_tt`, srsltid) with `replaceState` and keeps the canonical link in sync.
+
+## Storage
+
+- SQLite runtime — `db.ts` opens better-sqlite3 through the vault `storagelane` (default file `./local.db`); every statement is prepared and parameterized.
+- Schema — 7 tables: `zones`, `record_sets`, `dnssec_keys`, `gateway_routes`, `content_rows`, `onboarding_state` and `labels`, mirroring `schema.prisma`.
+- First-run seed — `seedIfEmpty` inserts the 11 content kinds plus zones and record sets inside one transaction when the content rows are empty.
+- Typed accessors — `zoneRow`, `recordSetRows`, `getonboardingstate`, `setonboardingstage`, `saveLabel`, `readLabel` and `readAllLabels` serve parameterized reads and upserts.
+- Catalog accessor — `catalog.ts` serves the same tables to the pages over HTTPS (`VITE_CATALOG_URL`) with a memoized promise cache and the offline seed fallback; a failed fetch retries on the next call.
+- Label store — `labels.ts` seeds the 183-entry English manifest (revision 2) through the vault `labelstore`, protecting translated rows from overwrite; the db-side twin `seedLabelRows` rides the boot.
+- Onboarding state — `onboardingstate.ts` keeps the first-run flags in the DB over `GET`/`POST /api/v1/onboarding` (host-validated against localhost, loopback, private and reserved ranges), with the localStorage key `argan.onboarding.seen` as a cache mirror and a seen-monotonic merge.
+- Workload lanes — `sandboxmodality.ts` declares the 4 lanes the app owns (`dnssec-validate`, `zonefile-parse-diff`, `catalog-registry-serve`, `label-store-seed`) with role, demand and boot budget, and resolves the `ARGAN_SANDBOX_LANE` seat (local, join, pinned modality).
+
+## UI
+
+- Route tree — `sol/Sol.tsx` mounts `/intro`, `/onboarding`, `/`, `/zones`, `/dnssec`, `/gateway`, `/settings` and the `/404` catch-all behind the wouter router.
+- Entry gate — `HomeEntrygate` reads the first-run state and routes unseen visitors to the intro or the onboarding; only a finished flow sees the landing.
+- Intro splash — the 1.6s opening splash with the drawn mark, skippable by click or key, straight hand-over under reduced motion.
+- Onboarding frames — three first-run frames (what the app is, what it hosts, the enter hand-over); finish and skip both mark the stage seen.
+- Zones console — the zone ledger with the apex featured and the newest serial pulsing, the publication rail, the record set ledger and the verbatim zone file.
+- DNSSEC console — the KSK/ZSK ledger, the algorithm badges with tone dots, the sign-pipeline terminal and the rollover ladder.
+- Gateway console — the transport ledger (ports in kbd, states as dots), the DoH-first rail and the Corefile terminal.
+- Settings console — three numbered sections (appearance, clean URLs, network): theme switch, reduce-motion switch, resolver select (5 choices), locale select (2 choices) and a live tracker-stripping URL demo with toast feedback.
+- Shell frame — `Shell.tsx` renders full-bleed at the app's own URL (the standalone law) or identical under the DevThink OS embedded seat, with the page rail, the family foot of 8 sibling accent dots and the theme flip.
+- Theme — `theme.ts` applies the light-fusion default and the dark variant through the `data-theme` attribute, session scope only.
+- Reduce motion — `motionpref.ts` rides the `argan.motion.reduced` session key and the `data-motion="reduced"` document flag, additive on top of `prefers-reduced-motion`.
+- Scroll reveal — `reveal.ts` adds the `in` class at 12% visibility through one shared IntersectionObserver.
+- Toast — `Toast.tsx` answers action feedback in success, error and info tones through a role=status live region (2600 ms fade, 3000 ms remove).
+- Empty states — `ShellEmptystate` renders the glyph-in-wash, one line of truth and one real action, with the pending shimmer while tables are in flight.
+- Family rail — `family.ts` links the 8 siblings in rail order with their spec §12 accents through mount-proof relative URLs (the familyurl lane of the fold).
+- 404 — `notfound.tsx` renders the single NXDOMAIN (RCODE 3) page.
+- Error boundary — `App.tsx` wraps the router in a theme error boundary with a reload action and seeds the label store before the first paint.
+
+## Dependencies
+
+- synchronized dependency union — the eleven family apps share one dependency tree: identical `dependencies`, `devDependencies` and `peerDependencies` (same keys, same versions, nothing removed, highest semver wins on conflicts) and one `engines` catalog with node as maestro and the V 0.5.2 seat as catalog annotation (@family wave/depssync).