# ARACHNID — design brief

**Display name:** ARACHNID
**Tagline:** *The spider crawls. You watch.*
**Bundle:** `net.llmtech.arachnid` · URL scheme `arachnid://`
**Tier:** Paramount (per IHP-WS protocol) · standalone on-device
**Family:** Everplay-Tech · v1 line · 2026-05-16
**Sibling-of:** AiMANAC · BROILR · MailSloth · HELMPC · Satcheli · Bombadil · DeepDive · PSL · FL33T

---

## 1 · What it is

ARACHNID is the family's first **browser-control sibling**. A hardened iOS browser that exposes its eight HELM tools (`browser_navigate`, `extract_text`, `extract_links`, `screenshot`, `click_text`, `fill_field`, `get_url`, `arachnid_mode_toggle`) as a transparent operator surface — the user always knows what the AI is doing, why, and is one tap from intervening.

A dual-mode renderer (WKWebView default + Acid Bath text-mode toggle) makes paramount-tier defensiveness visible at all times: every page either reaches the user through Apple's full WebKit pipeline or through a Rust sanitizer pipe that strips tags, decodes entities, and emits mono-text. The mode is **always announced**, and the chrome shifts unambiguously on toggle.

ARACHNID has **no own customer-deployed server**. HELM relay rides on `aimanac-rs`; trust mesh is inherited via the App Group reader on `group.net.llmtech.aimanac`.

---

## 2 · The visual register · spider + HUD reconciled

Two voices, locked by XZA:

1. **Spaceship HUD** — cockpit-language readouts, instrumentation, glanceable telemetry.
2. **Spider operates browser** — creature/woven/crawling motif. Threads. Web. Eight eyes. Eight arms.

The reconciliation: **the HUD is the spider's nervous system, surfaced for the operator.** Eight eyes ↔ eight arms ↔ eight HELM tools. One geometry serves all three motifs — no triple-coding.

We do **not** draw a literal spider anywhere. Spider-ness is implied through:
- 8-eye geometry (faceted octagons; spider eye arrangement at the EYES marquee)
- Silk-thread edges in Your Web
- Crawling motion in page-open
- Chitinous-but-mineral material palette

This puts maximum distance from MechaTheme (BROILR/AiMANAC base) and from Victorian (MailSloth). ARACHNID earns its own register without inheriting either's visual moves.

---

## 3 · Palette — Spectrum (i) + (ii) hybrid

**Chosen direction:** Deep space base + amber-eye glow as default; chromatic per-tool eye hues layered on when firing.

**Rationale:** Pure (i) makes 8 amber eyes indistinguishable in a row. Pure (ii) makes idle chrome a circus. The hybrid keeps chrome cohesive (amber + silver) and reserves chroma for the *one moment* it carries information — when an eye fires, its color identifies which tool is acting.

| Token | Role | OKLCH |
|---|---|---|
| `--arn-void`        | matte near-black base, faint violet | `oklch(0.12 0.012 285)` |
| `--arn-void-2`      | panel base                          | `oklch(0.16 0.018 285)` |
| `--arn-hull`        | chrome rail                         | `oklch(0.26 0.020 270)` |
| `--arn-glass`       | translucent panel                   | `oklch(0.22 0.020 280 / 0.62)` |
| `--arn-ink`         | warm pearl, primary readout         | `oklch(0.94 0.008 95)`  |
| `--arn-silk`        | web thread                          | `oklch(0.86 0.012 80)`  |
| `--arn-amber`       | default eye + accent                | `oklch(0.78 0.165 70)`  |
| `--arn-amber-hot`   | firing eye glow                     | `oklch(0.88 0.180 78)`  |
| `--eye-1..8`        | per-tool hues (firing only)         | hue rotation 25→335, equal L/C |
| `--arn-trust-ok`    | HSTS · allowlist hit                | chartreuse (`145`)      |
| `--arn-trust-warn`  | unrated                             | amber (`72`)            |
| `--arn-trust-bad`   | blocklist hit                       | vermilion (`25`)        |
| `--arn-acid`        | Acid Bath active phosphor           | `oklch(0.86 0.180 130)` |
| `--arn-quarantine`  | quarantine envelope                 | magenta (`320`)         |

---

## 4 · Typography — Spectrum (b) Mixed

**Display:** Saira Condensed 600 · ALLCAPS · tracking 0.04em–0.18em. Used for marquee, section titles, and tier badges.
**Mono:** JetBrains Mono 400/500 · tabular nums on. Used for telemetry, URLs, audit data, readouts, and small labels (8–11 px).

Pairing rationale: Saira Condensed reads HUD-archetypal at scale; JetBrains Mono reads as instrumentation at small sizes. Avoids Inter/Roboto/system fonts.

Prefix glyph **◇** is used to lead small-cap section labels (e.g., `◇ ACID BATH MODE · GLOBAL`) — it doubles as a faceted-eye motif anchor.

---

## 5 · Motion grammar — five primitives

| Primitive | When | What |
|---|---|---|
| **CRAWL**      | Page-open       | Thread tightens between vantage and target; spider scuttles along radial; chrome materializes around content. ~900 ms. 5 phases: DWELL · ACQUIRE · CRAWL · ARRIVE · SETTLED. |
| **EYE-SCAN**   | Strip idle/standby | Eyes pulse in rotation, ~2.4 s cycle, ~150 ms phase offset. Commits + glows on fire. |
| **WEB-PULSE**  | Your Web        | Edges along recently-traveled paths pulse amber; "where the spider's been recently." |
| **LOCK-ON**    | Crawl initiation | Brackets converge around target; brief "acquiring" beat (~120 ms). Spaceship targeting language. |
| **MODE-SHIFT** | Acid Bath toggle | Whole-chrome swap: color, type density, materials flip together. Operator never wonders which mode is on. |

---

## 6 · Materials

- **Deep glass HUD panels** — translucent slate; inset 1 px top highlight; 8 px blur backdrop; subtle inner border (1 px @ `oklch(0.10 / 0.5)`)
- **Silk threads** — 0.6–1.4 px curved bezier paths; 1 px drop-shadow on recent paths
- **Faceted gem-eyes** — octagonal SVG with inner facet lines; stroked, not pictographic
- **Hairline grid bg** — 32 px grid @ very-low-opacity slate; radial vignette toward top
- **Scanlines** — subtle 2 px repeating gradient @ screen blend; 1 % opacity. Never call attention to itself.

---

## 7 · IA — opens to Your Web

### 7.1 Home — Your Web (marquee surface)

- **Nodes** = sites. Octagonal HUD chip + label + favicon-position dot.
- **Edges** = silk threads. Three line weights: routine (0.7 px / 0.32 alpha), pinned-route (1 px / 0.6), recent-spider-path (1.4 px / 0.95 + amber glow).
- **Clusters** = dashed elliptical halos labelled `◇ WORK / READ / REFS / NET`.
- **Concentric rings** = literal spider-web shape behind the cluster graph; 5 rings + 14 radial spokes at the vantage.
- **Spider vantage** = 8-point star at center. Inner ring of 8 small chromatic eye-dots (one per tool); outer 8-point star in amber.
- **Active node** = lock-on brackets + outer halo.
- **Settings widget** = floating glass panel bottom-left (Acid Bath, HELM session pause, Audit shortcut).
- **Threads-live widget** = floating glass panel bottom-right (3 of 8 in this example; each thread tagged with its leading tool hue).
- **HELM strip** = always-visible bottom (see §10).

Scale: at >50 nodes, clusters collapse to a single anchored chip; user taps to expand. (Cluster-collapse behaviour is **open** — see §13.)

### 7.2 Page in flight

- Full-screen replaces Home (sheet would obstruct the woven web; full-screen is the more honest "we crawled into" gesture).
- **Top bar:** breadcrumb-style depth indicator (`◇ WEB / hn / item · DEPTH 02`) + mode badge.
- **URL bar:** TrustPill (◇/▲/✕ + status word) + URL + reticle reload glyph.
- **Page body:** WKWebView render OR Acid Bath text-mode (see §8).
- **HUD overlay:** corner readouts on top of page — top-right shows firing tool, bottom-left shows current-action data; corner brackets in 2 corners. Always present in both modes.
- **HELM strip** at bottom.

### 7.3 Settings — single-pane with filter chips

Six chips: `WEB · EYES · HARDENING · AUDIT · IDENTITY · ABOUT`.

- **WEB** — Acid Bath mode (ALWAYS / SMART-AUTO / NEVER); trust allowlist; thread cap (1–8); default-mode toggles.
- **EYES** — capability deck. Spider-arrangement cluster at top + 8 jack rows below. Each row: eye glyph, tool number + label, status pill (GRANTED / FACE ID / REVOKED).
- **HARDENING** — IHP-WS rekey cadence; Acid Bath strictness levels; family-canonical auto-lock policy.
- **AUDIT** — Lattice-style timeline; filter chips per tool; signed-export + replay buttons.
- **IDENTITY** — bundle, scheme, backend URL; "Re-inherit from AiMANAC" (no "Reset deployment" — there's no deploy).
- **ABOUT** — version, EAOS arachnid.rs pin, Acid Bath uniffi pin.

---

## 8 · Dual-mode runtime — visible chrome shift

| | WKWebView | Acid Bath |
|---|---|---|
| **Render** | Apple WebKit, full CSS / JS / images / video | HTTP → Rust sanitizer → mono text |
| **Background** | white page or whatever site uses | `oklch(0.10 0.020 130)` — deep phosphor green-black |
| **Text** | site's own | `--arn-acid` chartreuse, JetBrains Mono, soft text-shadow bloom |
| **Trust posture** | Safari-grade (HSTS, ITP) | defensive baseline — no scripts, cookies, or external resources |
| **Mode badge** | `WKWEBVIEW · RENDER` (amber-ringed pill) | `ACID BATH · TEXT` (chartreuse-ringed pill) |
| **URL bar trust** | TrustPill: ok / warn / bad | TrustPill: ACID · QUARANTINED |
| **Quarantine envelope** | not shown | dashed magenta box wrapping any external-content callout |
| **HUD overlay** | amber-tinted | chartreuse-tinted |
| **All 8 HELM tools** | operational | operational (text-match for click_text/fill_field) |

Toggle UX: Settings → WEB → Acid Bath = ALWAYS / SMART-AUTO / NEVER. Per Q3 lock — **single global mode**. Toggle is also one-tap from the strip's expanded panel.

---

## 9 · Trust visual language

ARACHNID does **not** inherit BROILR's 4-state trust chip. It composes its own from three layers:

1. **Mode badge** — always visible. WKWebView or Acid Bath. (See §8.)
2. **URL trust pill** — ok (▲ chartreuse) / warn (◇ amber) / bad (✕ vermilion) / acid (◈ chartreuse-quarantined).
3. **Quarantine envelope** — dashed magenta wrapper around any external content the spider has consumed (links extracted, page text surfaced). Maps to family `helm-core-quarantine` per locked_specifics §16 (eight security layers).

Every HELM action is attested to the AUDIT Lattice timeline. Signed artifacts exportable.

---

## 10 · HELM indicator strip (operator-trust surface)

Per Q4 lock — **always-visible bottom strip**.

**Layout:**
- Row 1 (top): session readout — `HELM · IDLE / ACTIVE · NAV / STANDING BY · awaiting next step / PAUSED` + IHP-WS tier + session token short-hex.
- Row 2 (main): 8 eyes in a row + short labels (NAV TXT LNK EYE CLK FIL URL MOD).
- Row 3 (expanded only, on tap): Lattice glimpse — last 3–5 actions with results + pause/resume control.

**Per-eye states:**
- **Dormant** — `oklch(0.22 ring opacity)` + glyph at 28 % alpha
- **Standing-by** — scanned in rotation (2.4 s cycle, 150 ms phase offset between eyes) + 70 % glyph alpha
- **Firing** — full chroma in the tool's hue + drop-shadow bloom + label takes hue + 1.4 s fire-glow animation

**Session-dot color** mirrors session state: idle = ink-3, standby = amber, active = amber-hot (animated), paused = vermilion.

The strip is the answer to "is the spider being driven right now?" — readable in peripheral vision.

---

## 11 · Eight HELM tools — eight eyes

| # | Tool                     | Eye hue       | Glyph             | Short |
|---|---                       |---            |---                |---    |
| 1 | `browser_navigate`       | amber-orange  | chevron-double    | NAV   |
| 2 | `browser_extract_text`   | straw         | 3 horizontal bars | TXT   |
| 3 | `browser_extract_links`  | chartreuse    | nodes + edges     | LNK   |
| 4 | `browser_screenshot`     | cyan          | aperture          | EYE   |
| 5 | `browser_click_text`     | azure         | reticle           | CLK   |
| 6 | `browser_fill_field`     | violet        | stylus + underline| FIL   |
| 7 | `browser_get_url`        | magenta       | pin diamond       | URL   |
| 8 | `browser_arachnid_mode_toggle` | vermilion | half-fill toggle  | MOD   |

All glyphs live inside the 24×24 viewBox of an octagonal facet ring. None are pictographic — they are HUD markers (chevron, bars, dots, target, etc.).

---

## 12 · Family invariants — adoption checklist

- [x] CCW-0 namespace · `net.llmtech.arachnid` · `arachnid://`
- [x] App Group reader · `group.net.llmtech.aimanac` (trust mesh)
- [x] App Group writer · `group.net.llmtech.browser-state` (bookmarks, history)
- [x] AdaptiveGlass + tintedSurface · P15/P17 · all HUD glass panels
- [x] `perform401Refresh` / `bytesWith401Refresh` · P15 · HELM relay HTTP
- [x] APIError taxonomy · `locked_specifics §11`
- [x] ReauthProofMinter · P14 · biometric gate for capability-token mint
- [x] HelmMCPClient · P24 · MCP dispatch for `browser_*` tools
- [x] TrustMeshInheritedEnvironment · P25 · 4-key envelope from AiMANAC
- [x] Always-visible auto-lock policy · family rule #12 · Settings → HARDENING
- [—] NO own customer-deployed server (standalone, per Bombadil pattern)
- [—] NO first-boot claim-writer (no master key to mint)
- [—] NO lifecycle taxonomy card stack (no deploy to taxonomize)

---

## 13 · Open design questions (for XZA)

1. **Cluster collapse at scale.** Above ~50 nodes, the literal woven graph stops being legible. Proposed: clusters collapse to a single anchored chip at a zoom threshold, with a tap-to-expand to a cluster-detail view that re-uses the same vantage geometry centred on the cluster's primary node. *Confirm acceptable or propose alternative.*
2. **Spider position.** Three candidates: (a) fixed at vantage center, (b) animates to most-recent node, (c) hidden, implied only by the recent-path glow. Current default = (a) fixed; the 8-eye-cluster vantage doubles as the spider. *Confirm.*
3. **Thread cap.** Current = 8 (matches 8-arm metaphor). Beyond 8, oldest thread auto-closes (with warning toast) or user must close one manually. Current default = auto-close oldest with toast. *Confirm.*
4. **Acid Bath toggle hot-key.** Should the strip's expanded panel offer a one-tap mode-toggle, or keep it in Settings → WEB only? Current default = panel offers it. *Confirm or remove.*

---

## 14 · Out of scope (locked)

- IA itself (locked above)
- HELM chat (base AiMANAC concern)
- 8 HELM tools' detailed JSON-RPC schemas (Cipher locks during impl)
- Drill-down full-DOM tree visualizer (v1.x)
- Multi-user / team-collab features (FL33T territory)
- Server-side architecture (no server)
- Customer setup wizard (no deploy)
- Lifecycle taxonomy card stack (no master key)

---

## 15 · Tone — final

- **Defensive without paranoid** — the spider IS the defender, not a panicked observer
- **Cryptographic without opaque** — HUD readouts make trust state legible to humans
- **Paramount without intimidating** — the operator is in control; the spider serves
- **Creature + machine in service of user** — neither a cute mascot nor a cold tool; both, fused
- **Easy to see and understand** (XZA's lock) — operator-tier readability over decorative-tier mystery

---

## 16 · Build order — Wave J ARACHNID adoption chip

| # | Step |
|---|---|
| 01 | iOS frame · Theme tokens · custom spider/HUD palette + Saira/JetBrains pairing |
| 02 | App Group entitlements · `group.net.llmtech.aimanac` (reader) + `browser-state` (writer) |
| 03 | Home / Your Web · woven graph + vantage + cluster halos + settings widget |
| 04 | Page-in-flight · HUD chrome + crawl animation (~900 ms, 5-phase) |
| 05 | Mode toggle · whole-chrome swap WKWebView ⇄ Acid Bath |
| 06 | Acid Bath rendering · uniffi binding from EAOS `arachnid.rs` · text-mode display |
| 07 | 8-eye HELM indicator strip · always-visible bottom · per-eye states |
| 08 | Settings · 6 filter chips (WEB / EYES / HARDENING / AUDIT / IDENTITY / ABOUT) |
| 09 | EYES capability deck · spider-arrangement cluster + 8 jack rows + biometric gates |
| 10 | AUDIT timeline · Lattice-style log + export signed artifact + replay |
| 11 | Trust signals · mode badge + URL trust pill + quarantine envelope |
| 12 | HARDENING · IHP-WS rekey cadence + Acid Bath strictness + family auto-lock policy |

Twelve chip-sized commits. Mirrors BROILR's 12-step. Steps 03 / 07 / 09 are the marquee design moments; steps 05 / 11 carry the paramount-tier hardening posture.

— end brief —