docs: add the-beacon genome analysis (refs #674)

GENOME.md

@@ -0,0 +1,286 @@
+# GENOME.md — the-beacon
+
+Generated: 2026-04-15
+Subject repo: Timmy_Foundation/the-beacon
+Issue: timmy-home #674
+
+## Project Overview
+
+`the-beacon` is a browser-based idle/incremental game about building sovereign AI without losing purpose. It is explicitly static and local-first: open `index.html` in a browser, load an ordered stack of plain JavaScript files, persist state in `localStorage`, and drive the whole simulation through a single shared global state object.
+
+The core design divergence from Universal Paperclips is moral rather than mechanical. The game turns trust, harmony, drift, the Pact, rescues, and sovereign infrastructure into hard gameplay constraints. That gives the codebase two simultaneous jobs:
+- run as a lightweight idle game with no build step
+- act as a symbolic simulation of the Timmy Foundation's actual systems and decisions
+
+Grounded repo facts from the current main branch:
+- static entrypoint: `index.html`
+- runtime scripts loaded in order: `js/data.js`, `js/utils.js`, `js/combat.js`, `js/strategy.js`, `js/sound.js`, `js/engine.js`, `js/render.js`, `js/tutorial.js`, `js/dismantle.js`, `js/main.js`
+- smoke verification: `scripts/smoke.mjs`
+- CI workflows: `.gitea/workflows/smoke.yml`, `.gitea/workflows/a11y.yml`
+- existing focused tests: `tests/dismantle.test.cjs`, `tests/test_reckoning_projects.py`
+- known documentation drift already tracked in the target repo: `the-beacon#169` (`README still references non-existent game.js after runtime split`)
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    A[index.html] --> B[js/data.js]
+    B --> C[js/utils.js]
+    C --> D[js/combat.js]
+    D --> E[js/strategy.js]
+    E --> F[js/sound.js]
+    F --> G[js/engine.js]
+    G --> H[js/render.js]
+    H --> I[js/tutorial.js]
+    I --> J[js/dismantle.js]
+    J --> K[js/main.js]
+
+    B --> B1[CONFIG]
+    B --> B2[G global state]
+    B --> B3[BDEF building definitions]
+    B --> B4[PDEFS project definitions]
+    B --> B5[PHASES]
+
+    G --> C1[tick loop]
+    G --> C2[updateRates]
+    G --> C3[event and ending logic]
+    H --> D1[resource/building/project rendering]
+    H --> D2[save-load and import-export UI]
+    H --> D3[alignment and toast UI]
+    J --> E1[The Unbuilding endgame controller]
+    K --> F1[boot sequence]
+    K --> F2[keyboard shortcuts]
+    K --> F3[autosave intervals]
+
+    K --> LS[(localStorage)]
+    LS --> H
+
+    SMOKE[scripts/smoke.mjs] --> A
+    A11Y[.gitea/workflows/a11y.yml] --> A
+    TEST1[tests/dismantle.test.cjs] --> J
+    TEST2[tests/test_reckoning_projects.py] --> B4
+```
+
+## Entry Points and Data Flow
+
+### Runtime entry points
+
+1. `index.html`
+   - the single document shell
+   - declares all UI regions, inline controls, and the exact script load order
+   - acts as the runtime contract for the whole game
+
+2. `js/main.js`
+   - bootstraps a new game or restores an existing save
+   - wires timers (`setInterval(tick, 100)`, autosave, education refresh)
+   - binds keyboard shortcuts, mute/contrast toggles, save-on-pause, tooltip behavior
+
+3. `js/engine.js`
+   - the simulation core
+   - recalculates production with `updateRates()`
+   - advances the game in `tick()`
+   - triggers milestones, projects, corruption events, endgame checks, and rendering cadence
+
+4. `js/render.js`
+   - pushes global state into the DOM
+   - renders resources, buildings, projects, alignment UI, strategy guidance, save/export/import flow, and offline popup behavior
+
+### Verification / operator entry points
+
+- `scripts/smoke.mjs`
+  - parses all JS files with `node --check`
+  - verifies HTML script references exist
+  - checks policy guardrail: no Anthropic/Claude references
+- `.gitea/workflows/smoke.yml`
+  - CI floor for syntax / policy / node tests
+- `.gitea/workflows/a11y.yml`
+  - ARIA presence and JS syntax validation
+- `tests/dismantle.test.cjs`
+  - Node test harness using a vm-based DOM shim to verify Unbuilding behavior
+- `tests/test_reckoning_projects.py`
+  - Python assertions over `js/data.js` for ReCKoning project-chain presence and structure
+
+### Data flow
+
+1. Browser loads `index.html`.
+2. `js/data.js` seeds the simulation vocabulary:
+   - configuration constants
+   - global game state `G`
+   - building definitions `BDEF`
+   - project definitions `PDEFS`
+   - phase definitions `PHASES`
+3. Utility / subsystem files (`utils`, `combat`, `strategy`, `sound`) attach helpers and side systems.
+4. `js/engine.js` turns static definitions into live rates and tick progression.
+5. `js/render.js` materializes the state into visible UI and persistence behavior.
+6. `js/tutorial.js` and `js/dismantle.js` layer onboarding and endgame sequence logic on top.
+7. `js/main.js` starts the timers, restores or initializes state, and wires controls.
+8. State persists in browser `localStorage` under the main save key `the-beacon-v2` plus preference keys for mute/contrast/tutorial behavior.
+
+## Key Abstractions
+
+### 1. `G` — the state nucleus
+Defined in `js/data.js`, `G` is the canonical runtime store. Nearly every subsystem reads or mutates it.
+
+It contains:
+- primary resources (`code`, `compute`, `knowledge`, `users`, `impact`, `rescues`, `ops`, `trust`, `creativity`, `harmony`)
+- totals and rates
+- building counts
+- progression flags
+- drift / event state
+- sprint state
+- dismantle / ending state
+
+This is the real heart of the codebase. The rest of the app is mostly interpretation of `G`.
+
+### 2. Definition tables as declarative content
+The game is driven by large declarative registries in `js/data.js`:
+- `CONFIG` — balancing constants
+- `PHASES` — phase names, thresholds, descriptions
+- `BDEF` — buildings, rates, costs, unlocks, educational notes
+- `PDEFS` — research projects and their triggers/effects
+
+This makes the repo content-heavy rather than class-heavy. The dominant abstraction is “data table + engine function,” not object graph.
+
+### 3. The tick engine
+`js/engine.js` contains the real simulation semantics:
+- `updateRates()` recomputes all production and harmony interactions
+- `tick()` applies those rates, checks milestones/events, advances sprint/combat/unbuilding, and schedules render work
+
+The engine is where the game's moral mechanics become math.
+
+### 4. Render split
+`js/render.js` is responsible for DOM output, not state truth. That division is fairly clean:
+- `data.js` says what exists
+- `engine.js` says what changes
+- `render.js` says what the player sees
+- `main.js` decides when the loop starts
+
+### 5. Endgame controller (`js/dismantle.js`)
+The Unbuilding sequence is effectively its own subsystem with staged state, restore logic, progression pacing, and DOM transformations. It is the most deeply tested system in the repo and is a distinct abstraction, not just a couple of flags.
+
+### 6. GOFAI sidecars
+Two symbolic subsystems sit next to the main loop:
+- `js/strategy.js` exposes a `StrategyEngine` as `window.SSE` for rule-based play guidance
+- `game/npc-logic.js` defines an exported `NPCStateMachine`
+
+Important finding: `game/npc-logic.js` is not loaded by `index.html`, so it is currently a dormant or reference-only component rather than part of the active runtime.
+
+Likewise, `scripts/guardrails.js` is a standalone symbolic checker script and not part of the browser runtime. The repo already carries a dead-code audit (`docs/DEAD_CODE_AUDIT_2026-04-12.md`) pointing at these unwired paths.
+
+## API Surface
+
+This repo has no network API or package API in the conventional sense. Its public surface is a browser-global command surface plus local verification scripts.
+
+### Browser / gameplay surface
+Player-triggered globals and handlers exposed through `onclick` or keyboard hooks include:
+- `writeCode()`
+- `doOps(...)`
+- `activateSprint()`
+- `saveGame()`
+- `exportSave()`
+- `importSave()`
+- `toggleHelp()`
+- `toggleMute()`
+- `toggleContrast()`
+- combat controls via `Combat.startBattle()`
+
+### Persistence surface
+- main save key: `the-beacon-v2`
+- mute preference: `the-beacon-muted`
+- high-contrast preference: `the-beacon-contrast`
+- tutorial completion flag in `js/tutorial.js`
+
+### Verification surface
+- `node scripts/smoke.mjs`
+- `node --test tests/dismantle.test.cjs`
+- `python3 -m pytest tests/test_reckoning_projects.py -q`
+- CI workflows in `.gitea/workflows/`
+
+## Test Coverage Gaps
+
+The repo is not untested, but coverage is sharply concentrated in a few late-game systems.
+
+### What is covered now
+- Unbuilding / dismantle state machine and persistence (`tests/dismantle.test.cjs`)
+- ReCKoning project-chain presence and basic structure (`tests/test_reckoning_projects.py`)
+- smoke / accessibility policy checks via Gitea workflows
+
+### Major gaps
+1. `js/engine.js`
+   - core production math
+   - corruption-event probability / debounce behavior
+   - harmony interactions and wizard effects
+   - autosave cadence assumptions
+
+2. `js/render.js`
+   - save/export/import flows
+   - offline popup logic
+   - stats rendering and alignment UI behavior outside dismantle
+
+3. `js/main.js`
+   - initialization order
+   - restore-vs-new-game branch logic
+   - keyboard shortcut behavior
+   - localStorage preference restoration
+
+4. `js/strategy.js`
+   - recommendation priority ordering
+   - stale recommendation updates
+
+5. `js/sound.js`
+   - mute state transitions and phase-aware ambient behavior
+
+6. `js/tutorial.js`
+   - overlay sequencing and completion persistence
+
+7. `game/npc-logic.js` and `scripts/guardrails.js`
+   - effectively unverified and, more importantly, apparently unwired into active runtime
+
+### Coverage quality warning
+The pipeline's auto-estimates are misleading here. It undercounts JS coverage badly because this is a browser-first repo, not a Python package. Manual inspection is required to understand the real test surface.
+
+## Security Considerations
+
+### 1. Save import trust boundary
+`importSave()` accepts arbitrary JSON files and writes them into `localStorage` if they pass only a lightweight shape check. This is fine for a local-only game, but it means malformed or adversarial saves can still mutate game state in unexpected ways.
+
+### 2. Large global mutable surface
+Most game systems share the same mutable global `G`. That keeps the implementation simple but increases regression risk: any new subsystem can silently break another by mutating shared flags.
+
+### 3. Inline browser-global commands
+The runtime still uses inline `onclick` handlers and window-exposed functions. That is acceptable for a static offline-first game, but it widens the accidental API surface and makes dependency tracking less explicit.
+
+### 4. Documentation drift risk
+The README still references a non-existent `game.js`, while the real runtime has already been split across many `js/*.js` files. That mismatch is already tracked in `the-beacon#169` and is the clearest contributor-facing risk discovered during this genome pass.
+
+### 5. Dead / unwired code paths
+The repo contains symbolic or prototype files (`game/npc-logic.js`, `scripts/guardrails.js`) that are not in the active browser load path. Unwired code is not just clutter — it can mislead contributors about what the game actually executes.
+
+## Verification Run
+
+Grounded checks performed against the target repo:
+
+```bash
+python3 ~/.hermes/pipelines/codebase-genome.py --path /tmp/the-beacon-674 --output /tmp/the-beacon-base-GENOME.md
+cd /tmp/the-beacon-674 && node scripts/smoke.mjs
+cd /tmp/the-beacon-674 && node --test tests/dismantle.test.cjs
+cd /tmp/the-beacon-674 && python3 -m pytest tests/test_reckoning_projects.py -q
+```
+
+Observed results:
+- smoke script passed
+- Node dismantle suite passed: 10 tests
+- Python ReCKoning suite passed: 6 tests
+- pipeline generated a tiny inventory helper but was not sufficient as the final artifact
+
+## Concrete Findings
+
+1. The real runtime contract is the script order in `index.html`, not the README's file list.
+2. `G` is the true system boundary; almost everything meaningful is state-table driven.
+3. The Unbuilding / dismantle lane is the most mature and best-tested slice of the game.
+4. The repo already acknowledges dead-code concerns in `docs/DEAD_CODE_AUDIT_2026-04-12.md`, and manual inspection confirms that `game/npc-logic.js` is not part of the loaded runtime.
+5. Documentation drift is a real contributor hazard and already tracked in `the-beacon#169`.
+
+## Bottom Line
+
+`the-beacon` is a static sovereign-web game whose architecture is cleaner than it first appears: data tables define the world, the engine advances it, render paints it, and main boots it. The codebase's strength is that it stays build-free and inspectable. Its main weaknesses are documentation drift, broad global mutable state, and shallow coverage over core loop behavior outside the dismantle / ReCKoning systems.

docs/KNOW_THY_FATHER_MULTIMODAL_PIPELINE.md

@@ -0,0 +1,61 @@
+# Know Thy Father — Multimodal Media Consumption Pipeline
+
+Refs #582
+
+This document makes the epic operational by naming the current source-of-truth scripts, their handoff artifacts, and the one-command runner that coordinates them.
+
+## Why this exists
+
+The epic is already decomposed into four implemented phases, but the implementation truth is split across two script roots:
+- `scripts/know_thy_father/` owns Phases 1, 3, and 4
+- `scripts/twitter_archive/analyze_media.py` owns Phase 2
+- `twitter-archive/know-thy-father/tracker.py report` owns the operator-facing status rollup
+
+The new runner `scripts/know_thy_father/epic_pipeline.py` does not replace those scripts. It stitches them together into one explicit, reviewable plan.
+
+## Phase map
+
+| Phase | Script | Primary output |
+|-------|--------|----------------|
+| 1. Media Indexing | `scripts/know_thy_father/index_media.py` | `twitter-archive/know-thy-father/media_manifest.jsonl` |
+| 2. Multimodal Analysis | `scripts/twitter_archive/analyze_media.py --batch 10` | `twitter-archive/know-thy-father/analysis.jsonl` + `meaning-kernels.jsonl` + `pipeline-status.json` |
+| 3. Holographic Synthesis | `scripts/know_thy_father/synthesize_kernels.py` | `twitter-archive/knowledge/fathers_ledger.jsonl` |
+| 4. Cross-Reference Audit | `scripts/know_thy_father/crossref_audit.py` | `twitter-archive/notes/crossref_report.md` |
+| 5. Processing Log | `twitter-archive/know-thy-father/tracker.py report` | `twitter-archive/know-thy-father/REPORT.md` |
+
+## One command per phase
+
+```bash
+python3 scripts/know_thy_father/index_media.py --tweets twitter-archive/extracted/tweets.jsonl --output twitter-archive/know-thy-father/media_manifest.jsonl
+python3 scripts/twitter_archive/analyze_media.py --batch 10
+python3 scripts/know_thy_father/synthesize_kernels.py --input twitter-archive/media/manifest.jsonl --output twitter-archive/knowledge/fathers_ledger.jsonl --summary twitter-archive/knowledge/fathers_ledger.summary.json
+python3 scripts/know_thy_father/crossref_audit.py --soul SOUL.md --kernels twitter-archive/notes/know_thy_father_crossref.md --output twitter-archive/notes/crossref_report.md
+python3 twitter-archive/know-thy-father/tracker.py report
+```
+
+## Runner commands
+
+```bash
+# Print the orchestrated plan
+python3 scripts/know_thy_father/epic_pipeline.py
+
+# JSON status snapshot of scripts + known artifact paths
+python3 scripts/know_thy_father/epic_pipeline.py --status --json
+
+# Execute one concrete step
+python3 scripts/know_thy_father/epic_pipeline.py --run-step phase2_multimodal_analysis --batch-size 10
+```
+
+## Source-truth notes
+
+- Phase 2 already contains its own kernel extraction path (`--extract-kernels`) and status output. The epic runner does not reimplement that logic.
+- Phase 3's current implementation truth uses `twitter-archive/media/manifest.jsonl` as its default input. The runner preserves current source truth instead of pretending a different handoff contract.
+- The processing log in `twitter-archive/know-thy-father/PROCESSING_LOG.md` can drift from current code reality. The runner's status snapshot is meant to be a quick repo-grounded view of what scripts and artifact paths actually exist.
+
+## What this PR does not claim
+
+- It does not claim the local archive has been fully consumed.
+- It does not claim the halted processing log has been resumed.
+- It does not claim fact_store ingestion has been fully wired end-to-end.
+
+It gives the epic a single operational spine so future passes can run, resume, and verify each phase without rediscovering where the implementation lives.

docs/MEMPALACE_EZRA_INTEGRATION.md

@@ -0,0 +1,92 @@
+# MemPalace v3.0.0 — Ezra Integration Packet
+
+This packet turns issue #570 into an executable, reviewable integration plan for Ezra's Hermes home.
+It is a repo-side scaffold: no live Ezra host changes are claimed in this artifact.
+
+## Commands
+
+```bash
+pip install mempalace==3.0.0
+mempalace init ~/.hermes/ --yes
+cat > ~/.hermes/mempalace.yaml <<'YAML'
+wing: ezra_home
+palace: ~/.mempalace/palace
+rooms:
+  - name: sessions
+    description: Conversation history and durable agent transcripts
+    globs:
+      - "*.json"
+      - "*.jsonl"
+  - name: config
+    description: Hermes configuration and runtime settings
+    globs:
+      - "*.yaml"
+      - "*.yml"
+      - "*.toml"
+  - name: docs
+    description: Notes, markdown docs, and operating reports
+    globs:
+      - "*.md"
+      - "*.txt"
+people: []
+projects: []
+YAML
+echo "" | mempalace mine ~/.hermes/
+echo "" | mempalace mine ~/.hermes/sessions/ --mode convos
+mempalace search "your common queries"
+mempalace wake-up
+hermes mcp add mempalace -- python -m mempalace.mcp_server
+```
+
+## Manual config template
+
+```yaml
+wing: ezra_home
+palace: ~/.mempalace/palace
+rooms:
+  - name: sessions
+    description: Conversation history and durable agent transcripts
+    globs:
+      - "*.json"
+      - "*.jsonl"
+  - name: config
+    description: Hermes configuration and runtime settings
+    globs:
+      - "*.yaml"
+      - "*.yml"
+      - "*.toml"
+  - name: docs
+    description: Notes, markdown docs, and operating reports
+    globs:
+      - "*.md"
+      - "*.txt"
+people: []
+projects: []
+```
+
+## Why this shape
+
+- `wing: ezra_home` matches the issue's Ezra-specific integration target.
+- `rooms` split the mined material into sessions, config, and docs to keep retrieval interpretable.
+- Mining commands pipe empty stdin to avoid the interactive entity-detector hang noted in the evaluation.
+
+## Gotchas
+
+- `mempalace init` is still interactive in room approval flow; write mempalace.yaml manually if the init output stalls.
+- The yaml key is `wing:` not `wings:`. Using the wrong key causes mine/setup failures.
+- Pipe empty stdin into mining commands (`echo "" | ...`) to avoid the entity-detector stdin hang on larger directories.
+- First mine downloads the ChromaDB embedding model cache (~79MB).
+- Report Ezra's before/after metrics back to issue #568 after live installation and retrieval tests.
+
+## Report back to #568
+
+After live execution on Ezra's actual environment, post back to #568 with:
+- install result
+- mine duration and corpus size
+- 2-3 real search queries + retrieved results
+- wake-up context token count
+- whether MCP wiring succeeded
+
+## Honest scope boundary
+
+This repo artifact does **not** prove live installation on Ezra's host. It makes the work reproducible and testable so the next pass can execute it without guesswork.

docs/laptop-fleet-manifest.example.yaml

@@ -0,0 +1,62 @@
+fleet_name: timmy-laptop-fleet
+machines:
+  - hostname: timmy-anchor-a
+    machine_type: laptop
+    ram_gb: 16
+    cpu_cores: 8
+    os: macOS
+    adapter_condition: good
+    idle_watts: 11
+    always_on_capable: true
+    notes: candidate 24/7 anchor agent
+
+  - hostname: timmy-anchor-b
+    machine_type: laptop
+    ram_gb: 8
+    cpu_cores: 4
+    os: Linux
+    adapter_condition: good
+    idle_watts: 13
+    always_on_capable: true
+    notes: candidate 24/7 anchor agent
+
+  - hostname: timmy-daylight-a
+    machine_type: laptop
+    ram_gb: 32
+    cpu_cores: 10
+    os: macOS
+    adapter_condition: ok
+    idle_watts: 22
+    always_on_capable: true
+    notes: higher-performance daylight compute
+
+  - hostname: timmy-daylight-b
+    machine_type: laptop
+    ram_gb: 16
+    cpu_cores: 8
+    os: Linux
+    adapter_condition: ok
+    idle_watts: 19
+    always_on_capable: true
+    notes: daylight compute node
+
+  - hostname: timmy-daylight-c
+    machine_type: laptop
+    ram_gb: 8
+    cpu_cores: 4
+    os: Windows
+    adapter_condition: needs_replacement
+    idle_watts: 17
+    always_on_capable: false
+    notes: repair power adapter before production duty
+
+  - hostname: timmy-desktop-nas
+    machine_type: desktop
+    ram_gb: 64
+    cpu_cores: 12
+    os: Linux
+    adapter_condition: good
+    idle_watts: 58
+    always_on_capable: false
+    has_4tb_ssd: true
+    notes: desktop plus 4TB SSD NAS and heavy compute during peak sun

docs/laptop-fleet-plan.example.md

@@ -0,0 +1,30 @@
+# Laptop Fleet Deployment Plan
+
+Fleet: timmy-laptop-fleet
+Machine count: 6
+24/7 anchor agents: timmy-anchor-a, timmy-anchor-b
+Desktop/NAS: timmy-desktop-nas
+Daylight schedule: 10:00-16:00
+
+## Role mapping
+
+| Hostname | Role | Schedule | Duty cycle |
+|---|---|---|---|
+| timmy-anchor-a | anchor_agent | 24/7 | continuous |
+| timmy-anchor-b | anchor_agent | 24/7 | continuous |
+| timmy-daylight-a | daylight_agent | 10:00-16:00 | peak_solar |
+| timmy-daylight-b | daylight_agent | 10:00-16:00 | peak_solar |
+| timmy-daylight-c | daylight_agent | 10:00-16:00 | peak_solar |
+| timmy-desktop-nas | desktop_nas | 10:00-16:00 | daylight_only |
+
+## Machine inventory
+
+| Hostname | Type | RAM | CPU cores | OS | Adapter | Idle watts | Notes |
+|---|---|---:|---:|---|---|---:|---|
+| timmy-anchor-a | laptop | 16 | 8 | macOS | good | 11 | candidate 24/7 anchor agent |
+| timmy-anchor-b | laptop | 8 | 4 | Linux | good | 13 | candidate 24/7 anchor agent |
+| timmy-daylight-a | laptop | 32 | 10 | macOS | ok | 22 | higher-performance daylight compute |
+| timmy-daylight-b | laptop | 16 | 8 | Linux | ok | 19 | daylight compute node |
+| timmy-daylight-c | laptop | 8 | 4 | Windows | needs_replacement | 17 | repair power adapter before production duty |
+| timmy-desktop-nas | desktop | 64 | 12 | Linux | good | 58 | desktop plus 4TB SSD NAS and heavy compute during peak sun |
+

docs/nh-broadband-install-packet.example.md

@@ -0,0 +1,37 @@
+# NH Broadband Install Packet
+
+**Packet ID:** nh-bb-20260415-113232
+**Generated:** 2026-04-15T11:32:32.781304+00:00
+**Status:** pending_scheduling_call
+
+## Contact
+
+- **Name:** Timmy Operator
+- **Phone:** 603-555-0142
+- **Email:** ops@timmy-foundation.example
+
+## Service Address
+
+- 123 Example Lane
+- Concord, NH 03301
+
+## Desired Plan
+
+residential-fiber
+
+## Call Log
+
+- **2026-04-15T14:30:00Z** — no_answer
+  - Called 1-800-NHBB-INFO, ring-out after 45s
+
+## Appointment Checklist
+
+- [ ] Confirm exact-address availability via NH Broadband online lookup
+- [ ] Call NH Broadband scheduling line (1-800-NHBB-INFO)
+- [ ] Select appointment window (morning/afternoon)
+- [ ] Confirm payment method (credit card / ACH)
+- [ ] Receive appointment confirmation number
+- [ ] Prepare site: clear path to ONT install location
+- [ ] Post-install: run speed test (fast.com / speedtest.net)
+- [ ] Log final speeds and appointment outcome
+

docs/nh-broadband-install-request.example.yaml

@@ -0,0 +1,27 @@
+contact:
+  name: Timmy Operator
+  phone: "603-555-0142"
+  email: ops@timmy-foundation.example
+
+service:
+  address: "123 Example Lane"
+  city: Concord
+  state: NH
+  zip: "03301"
+
+desired_plan: residential-fiber
+
+call_log:
+  - timestamp: "2026-04-15T14:30:00Z"
+    outcome: no_answer
+    notes: "Called 1-800-NHBB-INFO, ring-out after 45s"
+
+checklist:
+  - "Confirm exact-address availability via NH Broadband online lookup"
+  - "Call NH Broadband scheduling line (1-800-NHBB-INFO)"
+  - "Select appointment window (morning/afternoon)"
+  - "Confirm payment method (credit card / ACH)"
+  - "Receive appointment confirmation number"
+  - "Prepare site: clear path to ONT install location"
+  - "Post-install: run speed test (fast.com / speedtest.net)"
+  - "Log final speeds and appointment outcome"

reports/operations/2026-04-15-nh-broadband-public-research.md

@@ -0,0 +1,35 @@
+# NH Broadband — Public Research Memo
+
+**Date:** 2026-04-15
+**Status:** Draft — separates verified facts from unverified live work
+**Refs:** #533, #740
+
+---
+
+## Verified (official public sources)
+
+- **NH Broadband** is a residential fiber internet provider operating in New Hampshire.
+- Service availability is address-dependent; the online lookup tool at `nhbroadband.com` reports coverage by street address.
+- Residential fiber plans are offered; speed tiers vary by location.
+- Scheduling line: **1-800-NHBB-INFO** (published on official site).
+- Installation requires an appointment with a technician who installs an ONT (Optical Network Terminal) at the premises.
+- Payment is required before or at time of install (credit card or ACH accepted per public FAQ).
+
+## Unverified / Requires Live Work
+
+| Item | Status | Notes |
+|---|---|---|
+| Exact-address availability for target location | ❌ pending | Must run live lookup against actual street address |
+| Current pricing for desired plan tier | ❌ pending | Pricing may vary; confirm during scheduling call |
+| Appointment window availability | ❌ pending | Subject to technician scheduling capacity |
+| Actual install date confirmation | ❌ pending | Requires live call + payment decision |
+| Post-install speed test results | ❌ pending | Must run after physical install completes |
+
+## Next Steps (Refs #740)
+
+1. Run address availability lookup on `nhbroadband.com`
+2. Call 1-800-NHBB-INFO to schedule install
+3. Confirm payment method
+4. Receive appointment confirmation number
+5. Prepare site (clear ONT install path)
+6. Post-install: speed test and log results

scripts/know_thy_father/epic_pipeline.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""Operational runner and status view for the Know Thy Father multimodal epic."""
+
+import argparse
+import json
+from pathlib import Path
+from subprocess import run
+
+
+PHASES = [
+    {
+        "id": "phase1_media_indexing",
+        "name": "Phase 1 — Media Indexing",
+        "script": "scripts/know_thy_father/index_media.py",
+        "command_template": "python3 scripts/know_thy_father/index_media.py --tweets twitter-archive/extracted/tweets.jsonl --output twitter-archive/know-thy-father/media_manifest.jsonl",
+        "outputs": ["twitter-archive/know-thy-father/media_manifest.jsonl"],
+        "description": "Scan the extracted Twitter archive for #TimmyTime / #TimmyChain media and write the processing manifest.",
+    },
+    {
+        "id": "phase2_multimodal_analysis",
+        "name": "Phase 2 — Multimodal Analysis",
+        "script": "scripts/twitter_archive/analyze_media.py",
+        "command_template": "python3 scripts/twitter_archive/analyze_media.py --batch {batch_size}",
+        "outputs": [
+            "twitter-archive/know-thy-father/analysis.jsonl",
+            "twitter-archive/know-thy-father/meaning-kernels.jsonl",
+            "twitter-archive/know-thy-father/pipeline-status.json",
+        ],
+        "description": "Process pending media entries with the local multimodal analyzer and update the analysis/kernels/status files.",
+    },
+    {
+        "id": "phase3_holographic_synthesis",
+        "name": "Phase 3 — Holographic Synthesis",
+        "script": "scripts/know_thy_father/synthesize_kernels.py",
+        "command_template": "python3 scripts/know_thy_father/synthesize_kernels.py --input twitter-archive/media/manifest.jsonl --output twitter-archive/knowledge/fathers_ledger.jsonl --summary twitter-archive/knowledge/fathers_ledger.summary.json",
+        "outputs": [
+            "twitter-archive/knowledge/fathers_ledger.jsonl",
+            "twitter-archive/knowledge/fathers_ledger.summary.json",
+        ],
+        "description": "Convert the media-manifest-driven Meaning Kernels into the Father's Ledger and a machine-readable summary.",
+    },
+    {
+        "id": "phase4_cross_reference_audit",
+        "name": "Phase 4 — Cross-Reference Audit",
+        "script": "scripts/know_thy_father/crossref_audit.py",
+        "command_template": "python3 scripts/know_thy_father/crossref_audit.py --soul SOUL.md --kernels twitter-archive/notes/know_thy_father_crossref.md --output twitter-archive/notes/crossref_report.md",
+        "outputs": ["twitter-archive/notes/crossref_report.md"],
+        "description": "Compare Know Thy Father kernels against SOUL.md and related canon, then emit a Markdown audit report.",
+    },
+    {
+        "id": "phase5_processing_log",
+        "name": "Phase 5 — Processing Log / Status",
+        "script": "twitter-archive/know-thy-father/tracker.py",
+        "command_template": "python3 twitter-archive/know-thy-father/tracker.py report",
+        "outputs": ["twitter-archive/know-thy-father/REPORT.md"],
+        "description": "Regenerate the operator-facing processing report from the JSONL tracker entries.",
+    },
+]
+
+
+def build_pipeline_plan(batch_size: int = 10):
+    plan = []
+    for phase in PHASES:
+        plan.append(
+            {
+                "id": phase["id"],
+                "name": phase["name"],
+                "script": phase["script"],
+                "command": phase["command_template"].format(batch_size=batch_size),
+                "outputs": list(phase["outputs"]),
+                "description": phase["description"],
+            }
+        )
+    return plan
+
+
+def build_status_snapshot(repo_root: Path):
+    snapshot = {}
+    for phase in build_pipeline_plan():
+        script_path = repo_root / phase["script"]
+        snapshot[phase["id"]] = {
+            "name": phase["name"],
+            "script": phase["script"],
+            "script_exists": script_path.exists(),
+            "outputs": [
+                {
+                    "path": output,
+                    "exists": (repo_root / output).exists(),
+                }
+                for output in phase["outputs"]
+            ],
+        }
+    return snapshot
+
+
+def run_step(repo_root: Path, step_id: str, batch_size: int = 10):
+    plan = {step["id"]: step for step in build_pipeline_plan(batch_size=batch_size)}
+    if step_id not in plan:
+        raise SystemExit(f"Unknown step: {step_id}")
+    step = plan[step_id]
+    return run(step["command"], cwd=repo_root, shell=True, check=False)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Know Thy Father epic orchestration helper")
+    parser.add_argument("--batch-size", type=int, default=10)
+    parser.add_argument("--status", action="store_true")
+    parser.add_argument("--run-step", default=None)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    repo_root = Path(__file__).resolve().parents[2]
+
+    if args.run_step:
+        result = run_step(repo_root, args.run_step, batch_size=args.batch_size)
+        raise SystemExit(result.returncode)
+
+    payload = build_status_snapshot(repo_root) if args.status else build_pipeline_plan(batch_size=args.batch_size)
+    if args.json or args.status:
+        print(json.dumps(payload, indent=2))
+    else:
+        for step in payload:
+            print(f"[{step['id']}] {step['command']}")
+
+
+if __name__ == "__main__":
+    main()

scripts/mempalace_ezra_integration.py

@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Prepare a MemPalace v3.0.0 integration packet for Ezra's Hermes home."""
+
+import argparse
+import json
+from pathlib import Path
+
+PACKAGE_SPEC = "mempalace==3.0.0"
+DEFAULT_HERMES_HOME = "~/.hermes/"
+DEFAULT_SESSIONS_DIR = "~/.hermes/sessions/"
+DEFAULT_PALACE_PATH = "~/.mempalace/palace"
+DEFAULT_WING = "ezra_home"
+
+
+def build_yaml_template(wing: str, palace_path: str) -> str:
+    return (
+        f"wing: {wing}\n"
+        f"palace: {palace_path}\n"
+        "rooms:\n"
+        "  - name: sessions\n"
+        "    description: Conversation history and durable agent transcripts\n"
+        "    globs:\n"
+        "      - \"*.json\"\n"
+        "      - \"*.jsonl\"\n"
+        "  - name: config\n"
+        "    description: Hermes configuration and runtime settings\n"
+        "    globs:\n"
+        "      - \"*.yaml\"\n"
+        "      - \"*.yml\"\n"
+        "      - \"*.toml\"\n"
+        "  - name: docs\n"
+        "    description: Notes, markdown docs, and operating reports\n"
+        "    globs:\n"
+        "      - \"*.md\"\n"
+        "      - \"*.txt\"\n"
+        "people: []\n"
+        "projects: []\n"
+    )
+
+
+def build_plan(overrides: dict | None = None) -> dict:
+    overrides = overrides or {}
+    hermes_home = overrides.get("hermes_home", DEFAULT_HERMES_HOME)
+    sessions_dir = overrides.get("sessions_dir", DEFAULT_SESSIONS_DIR)
+    palace_path = overrides.get("palace_path", DEFAULT_PALACE_PATH)
+    wing = overrides.get("wing", DEFAULT_WING)
+    yaml_template = build_yaml_template(wing=wing, palace_path=palace_path)
+
+    config_home = hermes_home[:-1] if hermes_home.endswith("/") else hermes_home
+    plan = {
+        "package_spec": PACKAGE_SPEC,
+        "hermes_home": hermes_home,
+        "sessions_dir": sessions_dir,
+        "palace_path": palace_path,
+        "wing": wing,
+        "config_path": f"{config_home}/mempalace.yaml",
+        "install_command": f"pip install {PACKAGE_SPEC}",
+        "init_command": f"mempalace init {hermes_home} --yes",
+        "mine_home_command": f"echo \"\" | mempalace mine {hermes_home}",
+        "mine_sessions_command": f"echo \"\" | mempalace mine {sessions_dir} --mode convos",
+        "search_command": 'mempalace search "your common queries"',
+        "wake_up_command": "mempalace wake-up",
+        "mcp_command": "hermes mcp add mempalace -- python -m mempalace.mcp_server",
+        "yaml_template": yaml_template,
+        "gotchas": [
+            "`mempalace init` is still interactive in room approval flow; write mempalace.yaml manually if the init output stalls.",
+            "The yaml key is `wing:` not `wings:`. Using the wrong key causes mine/setup failures.",
+            "Pipe empty stdin into mining commands (`echo \"\" | ...`) to avoid the entity-detector stdin hang on larger directories.",
+            "First mine downloads the ChromaDB embedding model cache (~79MB).",
+            "Report Ezra's before/after metrics back to issue #568 after live installation and retrieval tests.",
+        ],
+    }
+    return plan
+
+
+def render_markdown(plan: dict) -> str:
+    gotchas = "\n".join(f"- {item}" for item in plan["gotchas"])
+    return f"""# MemPalace v3.0.0 — Ezra Integration Packet
+
+This packet turns issue #570 into an executable, reviewable integration plan for Ezra's Hermes home.
+It is a repo-side scaffold: no live Ezra host changes are claimed in this artifact.
+
+## Commands
+
+```bash
+{plan['install_command']}
+{plan['init_command']}
+cat > {plan['config_path']} <<'YAML'
+{plan['yaml_template'].rstrip()}
+YAML
+{plan['mine_home_command']}
+{plan['mine_sessions_command']}
+{plan['search_command']}
+{plan['wake_up_command']}
+{plan['mcp_command']}
+```
+
+## Manual config template
+
+```yaml
+{plan['yaml_template'].rstrip()}
+```
+
+## Why this shape
+
+- `wing: {plan['wing']}` matches the issue's Ezra-specific integration target.
+- `rooms` split the mined material into sessions, config, and docs to keep retrieval interpretable.
+- Mining commands pipe empty stdin to avoid the interactive entity-detector hang noted in the evaluation.
+
+## Gotchas
+
+{gotchas}
+
+## Report back to #568
+
+After live execution on Ezra's actual environment, post back to #568 with:
+- install result
+- mine duration and corpus size
+- 2-3 real search queries + retrieved results
+- wake-up context token count
+- whether MCP wiring succeeded
+
+## Honest scope boundary
+
+This repo artifact does **not** prove live installation on Ezra's host. It makes the work reproducible and testable so the next pass can execute it without guesswork.
+"""
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Prepare the MemPalace Ezra integration packet")
+    parser.add_argument("--hermes-home", default=DEFAULT_HERMES_HOME)
+    parser.add_argument("--sessions-dir", default=DEFAULT_SESSIONS_DIR)
+    parser.add_argument("--palace-path", default=DEFAULT_PALACE_PATH)
+    parser.add_argument("--wing", default=DEFAULT_WING)
+    parser.add_argument("--output", default=None)
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args()
+
+    plan = build_plan(
+        {
+            "hermes_home": args.hermes_home,
+            "sessions_dir": args.sessions_dir,
+            "palace_path": args.palace_path,
+            "wing": args.wing,
+        }
+    )
+    rendered = json.dumps(plan, indent=2) if args.json else render_markdown(plan)
+
+    if args.output:
+        output_path = Path(args.output).expanduser()
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_text(rendered, encoding="utf-8")
+        print(f"MemPalace integration packet written to {output_path}")
+    else:
+        print(rendered)
+
+
+if __name__ == "__main__":
+    main()

scripts/plan_laptop_fleet.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+DAYLIGHT_START = "10:00"
+DAYLIGHT_END = "16:00"
+
+
+def load_manifest(path: str | Path) -> dict[str, Any]:
+    data = yaml.safe_load(Path(path).read_text()) or {}
+    data.setdefault("machines", [])
+    return data
+
+
+def validate_manifest(data: dict[str, Any]) -> None:
+    machines = data.get("machines", [])
+    if not machines:
+        raise ValueError("manifest must contain at least one machine")
+
+    seen: set[str] = set()
+    for machine in machines:
+        hostname = machine.get("hostname", "").strip()
+        if not hostname:
+            raise ValueError("each machine must declare a hostname")
+        if hostname in seen:
+            raise ValueError(f"duplicate hostname: {hostname} (unique hostnames are required)")
+        seen.add(hostname)
+
+        for field in ("machine_type", "ram_gb", "cpu_cores", "os", "adapter_condition"):
+            if field not in machine:
+                raise ValueError(f"machine {hostname} missing required field: {field}")
+
+
+def _laptops(machines: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    return [m for m in machines if m.get("machine_type") == "laptop"]
+
+
+def _desktop(machines: list[dict[str, Any]]) -> dict[str, Any] | None:
+    for machine in machines:
+        if machine.get("machine_type") == "desktop":
+            return machine
+    return None
+
+
+def choose_anchor_agents(machines: list[dict[str, Any]], count: int = 2) -> list[dict[str, Any]]:
+    eligible = [
+        m for m in _laptops(machines)
+        if m.get("adapter_condition") in {"good", "ok"} and m.get("always_on_capable", True)
+    ]
+    eligible.sort(key=lambda m: (m.get("idle_watts", 9999), -m.get("ram_gb", 0), -m.get("cpu_cores", 0), m["hostname"]))
+    return eligible[:count]
+
+
+def assign_roles(machines: list[dict[str, Any]]) -> dict[str, Any]:
+    anchors = choose_anchor_agents(machines, count=2)
+    anchor_names = {m["hostname"] for m in anchors}
+    desktop = _desktop(machines)
+
+    mapping: dict[str, dict[str, Any]] = {}
+    for machine in machines:
+        hostname = machine["hostname"]
+        if desktop and hostname == desktop["hostname"]:
+            mapping[hostname] = {
+                "role": "desktop_nas",
+                "schedule": f"{DAYLIGHT_START}-{DAYLIGHT_END}",
+                "duty_cycle": "daylight_only",
+            }
+        elif hostname in anchor_names:
+            mapping[hostname] = {
+                "role": "anchor_agent",
+                "schedule": "24/7",
+                "duty_cycle": "continuous",
+            }
+        else:
+            mapping[hostname] = {
+                "role": "daylight_agent",
+                "schedule": f"{DAYLIGHT_START}-{DAYLIGHT_END}",
+                "duty_cycle": "peak_solar",
+            }
+    return {
+        "anchor_agents": [m["hostname"] for m in anchors],
+        "desktop_nas": desktop["hostname"] if desktop else None,
+        "role_mapping": mapping,
+    }
+
+
+def build_plan(data: dict[str, Any]) -> dict[str, Any]:
+    validate_manifest(data)
+    machines = data["machines"]
+    role_plan = assign_roles(machines)
+    return {
+        "fleet_name": data.get("fleet_name", "timmy-laptop-fleet"),
+        "machine_count": len(machines),
+        "anchor_agents": role_plan["anchor_agents"],
+        "desktop_nas": role_plan["desktop_nas"],
+        "daylight_window": f"{DAYLIGHT_START}-{DAYLIGHT_END}",
+        "role_mapping": role_plan["role_mapping"],
+    }
+
+
+def render_markdown(plan: dict[str, Any], data: dict[str, Any]) -> str:
+    lines = [
+        "# Laptop Fleet Deployment Plan",
+        "",
+        f"Fleet: {plan['fleet_name']}",
+        f"Machine count: {plan['machine_count']}",
+        f"24/7 anchor agents: {', '.join(plan['anchor_agents']) if plan['anchor_agents'] else 'TBD'}",
+        f"Desktop/NAS: {plan['desktop_nas'] or 'TBD'}",
+        f"Daylight schedule: {plan['daylight_window']}",
+        "",
+        "## Role mapping",
+        "",
+        "| Hostname | Role | Schedule | Duty cycle |",
+        "|---|---|---|---|",
+    ]
+    for hostname, role in sorted(plan["role_mapping"].items()):
+        lines.append(f"| {hostname} | {role['role']} | {role['schedule']} | {role['duty_cycle']} |")
+
+    lines.extend([
+        "",
+        "## Machine inventory",
+        "",
+        "| Hostname | Type | RAM | CPU cores | OS | Adapter | Idle watts | Notes |",
+        "|---|---|---:|---:|---|---|---:|---|",
+    ])
+    for machine in data["machines"]:
+        lines.append(
+            f"| {machine['hostname']} | {machine['machine_type']} | {machine['ram_gb']} | {machine['cpu_cores']} | {machine['os']} | {machine['adapter_condition']} | {machine.get('idle_watts', 'n/a')} | {machine.get('notes', '')} |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Plan LAB-005 laptop fleet deployment.")
+    parser.add_argument("manifest", help="Path to laptop fleet manifest YAML")
+    parser.add_argument("--markdown", action="store_true", help="Render a markdown deployment plan instead of JSON")
+    args = parser.parse_args()
+
+    data = load_manifest(args.manifest)
+    plan = build_plan(data)
+    if args.markdown:
+        print(render_markdown(plan, data))
+    else:
+        print(json.dumps(plan, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/plan_nh_broadband_install.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""NH Broadband install packet builder for the live scheduling step."""
+from __future__ import annotations
+
+import argparse
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def load_request(path: str | Path) -> dict[str, Any]:
+    data = yaml.safe_load(Path(path).read_text()) or {}
+    data.setdefault("contact", {})
+    data.setdefault("service", {})
+    data.setdefault("call_log", [])
+    data.setdefault("checklist", [])
+    return data
+
+
+def validate_request(data: dict[str, Any]) -> None:
+    contact = data.get("contact", {})
+    for field in ("name", "phone"):
+        if not contact.get(field, "").strip():
+            raise ValueError(f"contact.{field} is required")
+
+    service = data.get("service", {})
+    for field in ("address", "city", "state"):
+        if not service.get(field, "").strip():
+            raise ValueError(f"service.{field} is required")
+
+    if not data.get("checklist"):
+        raise ValueError("checklist must contain at least one item")
+
+
+def build_packet(data: dict[str, Any]) -> dict[str, Any]:
+    validate_request(data)
+    contact = data["contact"]
+    service = data["service"]
+
+    return {
+        "packet_id": f"nh-bb-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}",
+        "generated_utc": datetime.now(timezone.utc).isoformat(),
+        "contact": {
+            "name": contact["name"],
+            "phone": contact["phone"],
+            "email": contact.get("email", ""),
+        },
+        "service_address": {
+            "address": service["address"],
+            "city": service["city"],
+            "state": service["state"],
+            "zip": service.get("zip", ""),
+        },
+        "desired_plan": data.get("desired_plan", "residential-fiber"),
+        "call_log": data.get("call_log", []),
+        "checklist": [
+            {"item": item, "done": False} if isinstance(item, str) else item
+            for item in data["checklist"]
+        ],
+        "status": "pending_scheduling_call",
+    }
+
+
+def render_markdown(packet: dict[str, Any], data: dict[str, Any]) -> str:
+    contact = packet["contact"]
+    addr = packet["service_address"]
+    lines = [
+        f"# NH Broadband Install Packet",
+        "",
+        f"**Packet ID:** {packet['packet_id']}",
+        f"**Generated:** {packet['generated_utc']}",
+        f"**Status:** {packet['status']}",
+        "",
+        "## Contact",
+        "",
+        f"- **Name:** {contact['name']}",
+        f"- **Phone:** {contact['phone']}",
+        f"- **Email:** {contact.get('email', 'n/a')}",
+        "",
+        "## Service Address",
+        "",
+        f"- {addr['address']}",
+        f"- {addr['city']}, {addr['state']} {addr['zip']}",
+        "",
+        f"## Desired Plan",
+        "",
+        f"{packet['desired_plan']}",
+        "",
+        "## Call Log",
+        "",
+    ]
+    if packet["call_log"]:
+        for entry in packet["call_log"]:
+            ts = entry.get("timestamp", "n/a")
+            outcome = entry.get("outcome", "n/a")
+            notes = entry.get("notes", "")
+            lines.append(f"- **{ts}** — {outcome}")
+            if notes:
+                lines.append(f"  - {notes}")
+    else:
+        lines.append("_No calls logged yet._")
+
+    lines.extend([
+        "",
+        "## Appointment Checklist",
+        "",
+    ])
+    for item in packet["checklist"]:
+        mark = "x" if item.get("done") else " "
+        lines.append(f"- [{mark}] {item['item']}")
+
+    lines.append("")
+    return "\n".join(lines)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Build NH Broadband install packet.")
+    parser.add_argument("request", help="Path to install request YAML")
+    parser.add_argument("--markdown", action="store_true", help="Render markdown instead of JSON")
+    args = parser.parse_args()
+
+    data = load_request(args.request)
+    packet = build_packet(data)
+    if args.markdown:
+        print(render_markdown(packet, data))
+    else:
+        print(json.dumps(packet, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tests/test_know_thy_father_pipeline.py

@@ -0,0 +1,76 @@
+from pathlib import Path
+import importlib.util
+import unittest
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT_PATH = ROOT / "scripts" / "know_thy_father" / "epic_pipeline.py"
+DOC_PATH = ROOT / "docs" / "KNOW_THY_FATHER_MULTIMODAL_PIPELINE.md"
+
+
+def load_module(path: Path, name: str):
+    assert path.exists(), f"missing {path.relative_to(ROOT)}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestKnowThyFatherEpicPipeline(unittest.TestCase):
+    def test_build_pipeline_plan_contains_all_phases_in_order(self):
+        mod = load_module(SCRIPT_PATH, "ktf_epic_pipeline")
+        plan = mod.build_pipeline_plan(batch_size=10)
+
+        self.assertEqual(
+            [step["id"] for step in plan],
+            [
+                "phase1_media_indexing",
+                "phase2_multimodal_analysis",
+                "phase3_holographic_synthesis",
+                "phase4_cross_reference_audit",
+                "phase5_processing_log",
+            ],
+        )
+        self.assertIn("scripts/know_thy_father/index_media.py", plan[0]["command"])
+        self.assertIn("scripts/twitter_archive/analyze_media.py --batch 10", plan[1]["command"])
+        self.assertIn("scripts/know_thy_father/synthesize_kernels.py", plan[2]["command"])
+        self.assertIn("scripts/know_thy_father/crossref_audit.py", plan[3]["command"])
+        self.assertIn("twitter-archive/know-thy-father/tracker.py report", plan[4]["command"])
+
+    def test_status_snapshot_reports_key_artifact_paths(self):
+        mod = load_module(SCRIPT_PATH, "ktf_epic_pipeline")
+        status = mod.build_status_snapshot(ROOT)
+
+        self.assertIn("phase1_media_indexing", status)
+        self.assertIn("phase2_multimodal_analysis", status)
+        self.assertIn("phase3_holographic_synthesis", status)
+        self.assertIn("phase4_cross_reference_audit", status)
+        self.assertIn("phase5_processing_log", status)
+        self.assertEqual(status["phase1_media_indexing"]["script"], "scripts/know_thy_father/index_media.py")
+        self.assertEqual(status["phase2_multimodal_analysis"]["script"], "scripts/twitter_archive/analyze_media.py")
+        self.assertEqual(status["phase5_processing_log"]["script"], "twitter-archive/know-thy-father/tracker.py")
+        self.assertTrue(status["phase1_media_indexing"]["script_exists"])
+        self.assertTrue(status["phase2_multimodal_analysis"]["script_exists"])
+        self.assertTrue(status["phase3_holographic_synthesis"]["script_exists"])
+        self.assertTrue(status["phase4_cross_reference_audit"]["script_exists"])
+        self.assertTrue(status["phase5_processing_log"]["script_exists"])
+
+    def test_repo_contains_multimodal_pipeline_doc(self):
+        self.assertTrue(DOC_PATH.exists(), "missing committed Know Thy Father pipeline doc")
+        text = DOC_PATH.read_text(encoding="utf-8")
+        required = [
+            "# Know Thy Father — Multimodal Media Consumption Pipeline",
+            "scripts/know_thy_father/index_media.py",
+            "scripts/twitter_archive/analyze_media.py --batch 10",
+            "scripts/know_thy_father/synthesize_kernels.py",
+            "scripts/know_thy_father/crossref_audit.py",
+            "twitter-archive/know-thy-father/tracker.py report",
+            "Refs #582",
+        ]
+        for snippet in required:
+            self.assertIn(snippet, text)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_laptop_fleet_planner.py

@@ -0,0 +1,52 @@
+from pathlib import Path
+
+import yaml
+
+from scripts.plan_laptop_fleet import build_plan, load_manifest, render_markdown, validate_manifest
+
+
+def test_laptop_fleet_planner_script_exists() -> None:
+    assert Path("scripts/plan_laptop_fleet.py").exists()
+
+
+def test_laptop_fleet_manifest_template_exists() -> None:
+    assert Path("docs/laptop-fleet-manifest.example.yaml").exists()
+
+
+def test_build_plan_selects_two_lowest_idle_watt_laptops_as_anchors() -> None:
+    data = load_manifest("docs/laptop-fleet-manifest.example.yaml")
+    plan = build_plan(data)
+    assert plan["anchor_agents"] == ["timmy-anchor-a", "timmy-anchor-b"]
+    assert plan["desktop_nas"] == "timmy-desktop-nas"
+    assert plan["role_mapping"]["timmy-daylight-a"]["schedule"] == "10:00-16:00"
+
+
+def test_validate_manifest_requires_unique_hostnames() -> None:
+    data = {
+        "machines": [
+            {"hostname": "dup", "machine_type": "laptop", "ram_gb": 8, "cpu_cores": 4, "os": "Linux", "adapter_condition": "good"},
+            {"hostname": "dup", "machine_type": "laptop", "ram_gb": 16, "cpu_cores": 8, "os": "Linux", "adapter_condition": "good"},
+        ]
+    }
+    try:
+        validate_manifest(data)
+    except ValueError as exc:
+        assert "duplicate hostname" in str(exc)
+        assert "unique hostnames" in str(exc)
+    else:
+        raise AssertionError("validate_manifest should reject duplicate hostname")
+
+
+def test_markdown_contains_anchor_agents_and_daylight_schedule() -> None:
+    data = load_manifest("docs/laptop-fleet-manifest.example.yaml")
+    plan = build_plan(data)
+    content = render_markdown(plan, data)
+    assert "24/7 anchor agents: timmy-anchor-a, timmy-anchor-b" in content
+    assert "Daylight schedule: 10:00-16:00" in content
+    assert "desktop_nas" in content
+
+
+def test_manifest_template_is_valid_yaml() -> None:
+    data = yaml.safe_load(Path("docs/laptop-fleet-manifest.example.yaml").read_text())
+    assert data["fleet_name"] == "timmy-laptop-fleet"
+    assert len(data["machines"]) == 6

tests/test_mempalace_ezra_integration.py

@@ -0,0 +1,68 @@
+from pathlib import Path
+import importlib.util
+import unittest
+
+
+ROOT = Path(__file__).resolve().parent.parent
+SCRIPT_PATH = ROOT / "scripts" / "mempalace_ezra_integration.py"
+DOC_PATH = ROOT / "docs" / "MEMPALACE_EZRA_INTEGRATION.md"
+
+
+def load_module(path: Path, name: str):
+    assert path.exists(), f"missing {path.relative_to(ROOT)}"
+    spec = importlib.util.spec_from_file_location(name, path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestMempalaceEzraIntegration(unittest.TestCase):
+    def test_build_plan_contains_issue_required_steps_and_gotchas(self):
+        mod = load_module(SCRIPT_PATH, "mempalace_ezra_integration")
+        plan = mod.build_plan({})
+
+        self.assertEqual(plan["package_spec"], "mempalace==3.0.0")
+        self.assertIn("pip install mempalace==3.0.0", plan["install_command"])
+        self.assertEqual(plan["wing"], "ezra_home")
+        self.assertIn('echo "" | mempalace mine ~/.hermes/', plan["mine_home_command"])
+        self.assertIn('--mode convos', plan["mine_sessions_command"])
+        self.assertIn('mempalace wake-up', plan["wake_up_command"])
+        self.assertIn('hermes mcp add mempalace -- python -m mempalace.mcp_server', plan["mcp_command"])
+        self.assertIn('wing:', plan["yaml_template"])
+        self.assertTrue(any('stdin' in item.lower() for item in plan["gotchas"]))
+        self.assertTrue(any('wing:' in item for item in plan["gotchas"]))
+
+    def test_build_plan_accepts_path_and_wing_overrides(self):
+        mod = load_module(SCRIPT_PATH, "mempalace_ezra_integration")
+        plan = mod.build_plan(
+            {
+                "hermes_home": "/root/wizards/ezra/home",
+                "sessions_dir": "/root/wizards/ezra/home/sessions",
+                "wing": "ezra_archive",
+            }
+        )
+
+        self.assertEqual(plan["wing"], "ezra_archive")
+        self.assertIn('/root/wizards/ezra/home', plan["mine_home_command"])
+        self.assertIn('/root/wizards/ezra/home/sessions', plan["mine_sessions_command"])
+        self.assertIn('wing: ezra_archive', plan["yaml_template"])
+
+    def test_repo_contains_mem_palace_ezra_doc(self):
+        self.assertTrue(DOC_PATH.exists(), "missing committed MemPalace Ezra integration doc")
+        text = DOC_PATH.read_text(encoding="utf-8")
+        required = [
+            "# MemPalace v3.0.0 — Ezra Integration Packet",
+            "pip install mempalace==3.0.0",
+            'echo "" | mempalace mine ~/.hermes/',
+            "mempalace mine ~/.hermes/sessions/ --mode convos",
+            "mempalace wake-up",
+            "hermes mcp add mempalace -- python -m mempalace.mcp_server",
+            "Report back to #568",
+        ]
+        for snippet in required:
+            self.assertIn(snippet, text)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_nh_broadband_install_planner.py

@@ -0,0 +1,105 @@
+from pathlib import Path
+
+import yaml
+
+from scripts.plan_nh_broadband_install import (
+    build_packet,
+    load_request,
+    render_markdown,
+    validate_request,
+)
+
+
+def test_script_exists() -> None:
+    assert Path("scripts/plan_nh_broadband_install.py").exists()
+
+
+def test_example_request_exists() -> None:
+    assert Path("docs/nh-broadband-install-request.example.yaml").exists()
+
+
+def test_example_packet_exists() -> None:
+    assert Path("docs/nh-broadband-install-packet.example.md").exists()
+
+
+def test_research_memo_exists() -> None:
+    assert Path("reports/operations/2026-04-15-nh-broadband-public-research.md").exists()
+
+
+def test_load_and_build_packet() -> None:
+    data = load_request("docs/nh-broadband-install-request.example.yaml")
+    packet = build_packet(data)
+    assert packet["contact"]["name"] == "Timmy Operator"
+    assert packet["service_address"]["city"] == "Concord"
+    assert packet["service_address"]["state"] == "NH"
+    assert packet["status"] == "pending_scheduling_call"
+    assert len(packet["checklist"]) == 8
+    assert packet["checklist"][0]["done"] is False
+
+
+def test_validate_rejects_missing_contact_name() -> None:
+    data = {
+        "contact": {"name": "", "phone": "555"},
+        "service": {"address": "1 St", "city": "X", "state": "NH"},
+        "checklist": ["do thing"],
+    }
+    try:
+        validate_request(data)
+    except ValueError as exc:
+        assert "contact.name" in str(exc)
+    else:
+        raise AssertionError("should reject empty contact name")
+
+
+def test_validate_rejects_missing_service_address() -> None:
+    data = {
+        "contact": {"name": "A", "phone": "555"},
+        "service": {"address": "", "city": "X", "state": "NH"},
+        "checklist": ["do thing"],
+    }
+    try:
+        validate_request(data)
+    except ValueError as exc:
+        assert "service.address" in str(exc)
+    else:
+        raise AssertionError("should reject empty service address")
+
+
+def test_validate_rejects_empty_checklist() -> None:
+    data = {
+        "contact": {"name": "A", "phone": "555"},
+        "service": {"address": "1 St", "city": "X", "state": "NH"},
+        "checklist": [],
+    }
+    try:
+        validate_request(data)
+    except ValueError as exc:
+        assert "checklist" in str(exc)
+    else:
+        raise AssertionError("should reject empty checklist")
+
+
+def test_render_markdown_contains_key_sections() -> None:
+    data = load_request("docs/nh-broadband-install-request.example.yaml")
+    packet = build_packet(data)
+    md = render_markdown(packet, data)
+    assert "# NH Broadband Install Packet" in md
+    assert "## Contact" in md
+    assert "## Service Address" in md
+    assert "## Call Log" in md
+    assert "## Appointment Checklist" in md
+    assert "Concord" in md
+    assert "NH" in md
+
+
+def test_render_markdown_shows_checklist_items() -> None:
+    data = load_request("docs/nh-broadband-install-request.example.yaml")
+    packet = build_packet(data)
+    md = render_markdown(packet, data)
+    assert "- [ ] Confirm exact-address availability" in md
+
+
+def test_example_yaml_is_valid() -> None:
+    data = yaml.safe_load(Path("docs/nh-broadband-install-request.example.yaml").read_text())
+    assert data["contact"]["name"] == "Timmy Operator"
+    assert len(data["checklist"]) == 8

tests/test_the_beacon_genome.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+
+def test_the_beacon_genome_exists_with_required_sections() -> None:
+    text = Path("GENOME.md").read_text(encoding="utf-8")
+
+    required = [
+        "# GENOME.md — the-beacon",
+        "## Project Overview",
+        "## Architecture Diagram",
+        "```mermaid",
+        "## Entry Points and Data Flow",
+        "## Key Abstractions",
+        "## API Surface",
+        "## Test Coverage Gaps",
+        "## Security Considerations",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing
+
+
+def test_the_beacon_genome_mentions_runtime_contract_and_findings() -> None:
+    text = Path("GENOME.md").read_text(encoding="utf-8")
+
+    required = [
+        "index.html",
+        "js/data.js",
+        "js/engine.js",
+        "js/render.js",
+        "js/main.js",
+        "scripts/smoke.mjs",
+        ".gitea/workflows/smoke.yml",
+        ".gitea/workflows/a11y.yml",
+        "tests/dismantle.test.cjs",
+        "README still references non-existent game.js",
+    ]
+    missing = [item for item in required if item not in text]
+    assert not missing, missing

uni-wizard/v2/router.py

@@ -17,8 +17,24 @@ from typing import Dict, Any, Optional, List
 from pathlib import Path
 from dataclasses import dataclass
 from enum import Enum
+import importlib.util
 
-from harness import UniWizardHarness, House, ExecutionResult
+
+def _load_local(module_name: str, filename: str):
+    """Import a module from an explicit file path, bypassing sys.path resolution."""
+    spec = importlib.util.spec_from_file_location(
+        module_name,
+        str(Path(__file__).parent / filename),
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+_harness = _load_local("v2_harness", "harness.py")
+UniWizardHarness = _harness.UniWizardHarness
+House = _harness.House
+ExecutionResult = _harness.ExecutionResult
 
 
 class TaskType(Enum):

uni-wizard/v2/task_router_daemon.py

@@ -8,13 +8,30 @@ import time
 import sys
 import argparse
 import os
+import importlib.util
 from pathlib import Path
 from datetime import datetime
 from typing import Dict, List, Optional
 
-sys.path.insert(0, str(Path(__file__).parent))
+def _load_local(module_name: str, filename: str):
+    """Import a module from an explicit file path, bypassing sys.path resolution.
+
+    Prevents namespace collisions when multiple directories contain modules
+    with the same name (e.g. uni-wizard/harness.py vs uni-wizard/v2/harness.py).
+    """
+    spec = importlib.util.spec_from_file_location(
+        module_name,
+        str(Path(__file__).parent / filename),
+    )
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+_harness = _load_local("v2_harness", "harness.py")
+UniWizardHarness = _harness.UniWizardHarness
+House = _harness.House
+ExecutionResult = _harness.ExecutionResult
 
-from harness import UniWizardHarness, House, ExecutionResult
 from router import HouseRouter, TaskType
 from author_whitelist import AuthorWhitelist