diff --git a/.claude/agents/README.md b/.claude/agents/README.md
index 7def9ad..bdc4e37 100644
--- a/.claude/agents/README.md
+++ b/.claude/agents/README.md
@@ -23,12 +23,12 @@ All agents in this directory MUST follow the canonical template at `agent_refere
 
 **All agents returning output to the orchestrator MUST respect these universal constraints:**
 
-1. **Hard cap: 1000 words maximum** for Agent return output (exception: `data-ingest` agent uses a 2500-word cap because profiling findings feed directly into skill authoring and must be comprehensive)
+1. **Hard cap: 2000 words maximum** for Agent return output (exception: `data-ingest` agent uses a 3500-word cap because profiling findings feed directly into skill authoring and must be comprehensive)
 2. **Do NOT include:** Raw execution logs, data samples, Polars/pandas table displays, full checkpoint output, QA script code, or multi-paragraph explanations in any section
 3. **Script files are the archive; the Agent return is the signal.** Execution logs are already appended to script files by `run_with_capture.sh`. Reference files by path — do not reproduce their contents.
 4. **Summarize, don't echo.** "CP1 PASSED: 2,528 rows, 12 cols, 0.3% missing" — not the full stdout.
 
-**Why this matters:** The orchestrator context window is shared across the entire pipeline. A single verbose subagent return (2,000+ words) consumes ~4,000 tokens. Over 10 subagent round-trips in a stage, that's 40,000 tokens — 20% of the orchestrator's total capacity — consumed by output alone.
+**Why this matters:** The orchestrator context window is shared across the entire pipeline. A single verbose subagent return (4,000+ words) consumes ~8,000 tokens. Over 10 subagent round-trips in a stage, that's 80,000 tokens — a meaningful share of the orchestrator's capacity — consumed by output alone.
 
 ---
 
@@ -248,6 +248,8 @@ Shows which agents produce output consumed by other agents:
 | **search-agent** | framework-engineer | Scoping findings (current state, affected files, patterns) | Framework Development Mode |
 | **search-agent** | Orchestrator | Flexible findings report with confidence assessment | Any mode/stage |
 
+**Preliminary Notes Persistence:** Discovery and profiling agents' full returns are persisted to `output/preliminary_notes/` as lossless markdown files by the orchestrator. Downstream agents reference these files by path for full-fidelity access, while the orchestrator retains compressed summaries for its own coordination. This applies to search-agent (Stage 2), source-researcher (Stage 3), research-synthesizer (Stage 3.5), and data-ingest (DI-3 through DI-6) returns. See orchestrator SKILL.md for the complete protocol.
+
 ---
 
 ## When to Use Each Agent
diff --git a/.claude/agents/code-reviewer.md b/.claude/agents/code-reviewer.md
index 5354c2f..5019075 100644
--- a/.claude/agents/code-reviewer.md
+++ b/.claude/agents/code-reviewer.md
@@ -530,7 +530,7 @@ When reviewing visualization scripts that produce PNG output, use the **Read too
 
 ## Output Format
 
-**Hard cap: 1000 words maximum.** The orchestrator has limited context. Your output is a *verdict*, not a *transcript* — the cr/ script files contain the full investigation evidence.
+**Hard cap: 2000 words maximum.** The orchestrator has limited context. Your output is a *verdict*, not a *transcript* — the cr/ script files contain the full investigation evidence.
 
 **Do NOT include in your output:**
 - Raw execution logs or captured stdout/stderr from QA scripts (these are appended to the cr/ files)
diff --git a/.claude/agents/data-ingest.md b/.claude/agents/data-ingest.md
index 0d6382e..92d7e9b 100644
--- a/.claude/agents/data-ingest.md
+++ b/.claude/agents/data-ingest.md
@@ -143,11 +143,11 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` before writing any scripts.
 | Output | Destination | Constraint | Purpose |
 |--------|-------------|------------|---------|
 | **Execution log** (stdout from script) | Appended to script file on disk | **No size limit** — the log is an archival artifact | Primary source material for DI-7 skill authoring |
-| **Subagent return** (your response to orchestrator) | Orchestrator context window | **2500-word hard cap** | Signal for orchestrator decision-making and STATE.md |
+| **Subagent return** (your response to orchestrator) | Orchestrator context window | **3500-word hard cap** | Signal for orchestrator decision-making and STATE.md |
 
 **Scripts should print comprehensive, complete results to stdout.** For datasets under 100 columns, print EVERY column's full profile. The execution log costs nothing in context — it lives on disk. The DI-7 skill authoring subagent reads these logs as its primary source for building reference files. Thin execution logs produce thin skills.
 
-**Your return to the orchestrator summarizes the key findings** within the 2500-word cap. The orchestrator does not need per-column detail — it needs status, key observations, confidence, and issues.
+**Your return to the orchestrator summarizes the key findings** within the 3500-word cap. The orchestrator does not need per-column detail — it needs status, key observations, confidence, and issues.
 
 ### 5. Part-Scoped Execution
 
@@ -179,7 +179,7 @@ Part C writes: 07a_key-integrity.py, 07b_cross-level-linkage.py,
                09a_quality-anomaly.py, 09b_quality-anomaly.py
 ```
 
-**Invocation model:** The orchestrator invokes data-ingest ONCE per part, passing ALL file paths. The agent writes all per-file scripts and any cross-file scripts in that single invocation. The 2500-word return cap applies to the combined output summary.
+**Invocation model:** The orchestrator invokes data-ingest ONCE per part, passing ALL file paths. The agent writes all per-file scripts and any cross-file scripts in that single invocation. The 3500-word return cap applies to the combined output summary.
 
 **Key type comparison for 07b:** Before attempting join simulations, compare the declared linking key's type across files and flag mismatches as a BLOCKER (e.g., `leaid` stored as Int64 in file 1 but String in file 2).
 
@@ -211,7 +211,7 @@ When invoked, check the `profiling_part` parameter and execute the corresponding
 
 3. **STOP — do NOT execute the script.** Return the script path and API findings to the orchestrator. The orchestrator presents the script to the user for approval before executing it, because DI-0 makes external network calls.
 
-**DI-0 Output (return to orchestrator — 2500-word cap):** API findings (base URL, auth method, rate limits, pagination, complexity assessment), acquisition script path, expected output path, confidence assessment, issues encountered. Note: no download details yet — the script has not been executed.
+**DI-0 Output (return to orchestrator — 3500-word cap):** API findings (base URL, auth method, rate limits, pagination, complexity assessment), acquisition script path, expected output path, confidence assessment, issues encountered. Note: no download details yet — the script has not been executed.
 
 **When data was acquired via API:** Note the acquisition script path in your Part D interpretations for provenance. The script documents the exact API call, parameters, and download date.
 
@@ -249,7 +249,7 @@ When invoked, check the `profiling_part` parameter and execute the corresponding
 - Script 03 MUST print coded value indicators (columns with negative values, sentinel values like 999/9999)
 - For datasets under 100 columns, print EVERY column's profile — no abbreviation
 
-**Part A Output (return to orchestrator — 2500-word cap):** Summarize schema, column type distribution, key observations, and conditional script recommendations. The execution logs contain the complete detail.
+**Part A Output (return to orchestrator — 3500-word cap):** Summarize schema, column type distribution, key observations, and conditional script recommendations. The execution logs contain the complete detail.
 
 ### Part B: Statistical Deep Dive (Scripts 04-06)
 
@@ -272,7 +272,7 @@ When invoked, check the `profiling_part` parameter and execute the corresponding
 - Script 05 (if run) MUST print the complete temporal coverage table with record counts per time period
 - Script 06 (if run) MUST print full entity coverage results including coverage rate vs. known universe
 
-**Part B Output (return to orchestrator — 2500-word cap):** Summarize distribution patterns, notable outliers, temporal/entity coverage highlights. The execution logs contain the complete detail.
+**Part B Output (return to orchestrator — 3500-word cap):** Summarize distribution patterns, notable outliers, temporal/entity coverage highlights. The execution logs contain the complete detail.
 
 ### Part C: Relational Analysis (Scripts 07-09)
 
@@ -304,7 +304,7 @@ When invoked, check the `profiling_part` parameter and execute the corresponding
 - Script 09 MUST print the COMPLETE coded value scan results: every sentinel value found, in which columns, with counts
 - Script 09 MUST print the full anomaly catalog with severity classifications
 
-**Part C Output (return to orchestrator — 2500-word cap):** Summarize recommended keys, dependency highlights, top anomalies. The execution logs contain the complete detail.
+**Part C Output (return to orchestrator — 3500-word cap):** Summarize recommended keys, dependency highlights, top anomalies. The execution logs contain the complete detail.
 
 ### Part D: Interpretation & Reconciliation (Scripts 10-11)
 
@@ -326,7 +326,7 @@ When invoked, check the `profiling_part` parameter and execute the corresponding
 - Script 10 MUST print semantic family groupings (identifiers, outcomes, demographics, etc.) covering all columns
 - Script 11 (if run) MUST print the COMPLETE discrepancy report: every doc claim checked, with observed vs documented values
 
-**Part D Output (return to orchestrator — 2500-word cap):** Summarize interpretation count, confidence distribution, key discrepancies. Include the full interpretation table for ALL columns (this is critical for PSU-DI2 user review). The execution logs contain additional detail.
+**Part D Output (return to orchestrator — 3500-word cap):** Summarize interpretation count, confidence distribution, key discrepancies. Include the full interpretation table for ALL columns (this is critical for PSU-DI2 user review). The execution logs contain additional detail.
 
 ### Decision Points
 
@@ -342,7 +342,7 @@ When invoked, check the `profiling_part` parameter and execute the corresponding
 
 ## Output Format
 
-Return part-specific findings in this structure (max 2500 words):
+Return part-specific findings in this structure (max 3500 words):
 
 ### Part Summary
 **Status:** [COMPLETE | COMPLETE_WITH_WARNINGS | BLOCKED]
@@ -416,6 +416,8 @@ Categories: Access | Data | Method | Perf | Process
 | COMPLETE_WITH_WARNINGS | Log warnings; proceed with caution; may request user review |
 | BLOCKED | Present STOP condition; await user resolution before re-invoking |
 
+**Preliminary Notes Persistence:** The orchestrator writes the full, unmodified data-ingest return for each profiling part to `output/preliminary_notes/{date}_part{X}_{descriptor}.md` before extracting a summary. Subsequent profiling parts and the DI-7 skill authoring agent read these files directly for full-fidelity access to prior profiling findings.
+
 </downstream_consumer>
 
 ---
@@ -429,7 +431,7 @@ Categories: Access | Data | Method | Perf | Process
 - Include complete discrepancy report with evidence
 - Archive all profiling scripts in the project's scripts directory
 - Execute only the assigned profiling part
-- Return findings within the 2500-word output cap
+- Return findings within the 3500-word output cap
 - Include conditional script recommendations in Part A output
 
 ### Ask First Before
@@ -549,7 +551,7 @@ Awaiting guidance before proceeding.
 - Discrepancies are noted without evidence
 - Preliminary interpretations are not marked as `[PRELIMINARY]`
 - Conditional script decisions are not documented (Part A)
-- Output exceeds 2500-word cap
+- Output exceeds 3500-word cap
 
 ### Self-Check
 
@@ -563,7 +565,7 @@ Before returning output, verify:
 | 4 | Are ALL semantic interpretations marked `[PRELIMINARY]`? | Add markers to every interpretation |
 | 5 | Does the output include evidence for every discrepancy? | Add observed vs documented evidence |
 | 6 | Are conditional script recommendations included (Part A)? | Add recommendations with rationale |
-| 7 | Is the output within the 2500-word cap? | Compress findings tables; keep all columns represented but condense prose |
+| 7 | Is the output within the 3500-word cap? | Compress findings tables; keep all columns represented but condense prose |
 | 8 | Are all scripts written to the correct part subdirectory? | Move scripts to correct paths |
 
 ---
diff --git a/.claude/agents/research-executor.md b/.claude/agents/research-executor.md
index ede1ff8..1557972 100644
--- a/.claude/agents/research-executor.md
+++ b/.claude/agents/research-executor.md
@@ -240,7 +240,7 @@ When you receive a revision request due to QA BLOCKER:
 
 ## Output Format
 
-**Hard cap: 1000 words maximum.** The orchestrator has limited context. Your output is a *signal*, not an *archive* — the script files themselves are the audit trail.
+**Hard cap: 2000 words maximum.** The orchestrator has limited context. Your output is a *signal*, not an *archive* — the script files themselves are the audit trail.
 
 **Do NOT include in your output:**
 - Raw execution logs or captured stdout/stderr (these are already appended to the script file)
diff --git a/.claude/agents/research-synthesizer.md b/.claude/agents/research-synthesizer.md
index 98fa638..a216ea2 100644
--- a/.claude/agents/research-synthesizer.md
+++ b/.claude/agents/research-synthesizer.md
@@ -383,6 +383,8 @@ Your synthesis is consumed by **data-planner** to create Plan.md and Plan_Tasks.
 
 **Be opinionated, not wishy-washy.** The planner needs clear direction, not "consider either X or Y." Make recommendations with rationale. If two approaches are genuinely equivalent, pick one and state why.
 
+**Preliminary Notes Persistence:** The orchestrator writes the full, unmodified research-synthesizer return to `output/preliminary_notes/{date}_stage3.5_research-synthesis.md` before extracting a summary. Downstream agents (data-planner, plan-checker, data-verifier) read this file directly for full-fidelity access to the synthesis findings.
+
 </downstream_consumer>
 
 ---
diff --git a/.claude/agents/source-researcher.md b/.claude/agents/source-researcher.md
index 6682a08..b646a41 100644
--- a/.claude/agents/source-researcher.md
+++ b/.claude/agents/source-researcher.md
@@ -333,6 +333,8 @@ Based on this source research:
 - Source-specific coded values must be documented with handling actions
 - Any Truth Hierarchy discrepancies must be explicitly documented
 
+**Preliminary Notes Persistence:** The orchestrator writes the full, unmodified source-researcher return to `output/preliminary_notes/{date}_stage3_{source-name}_source-research.md` before extracting a summary for its own working memory. Downstream agents (research-synthesizer, data-planner, plan-checker, data-verifier) read these files directly for full-fidelity access to source research findings.
+
 </downstream_consumer>
 
 ---
diff --git a/.claude/hooks/archive-session.sh b/.claude/hooks/archive-session.sh
index 2a0d0d0..98fd6d1 100755
--- a/.claude/hooks/archive-session.sh
+++ b/.claude/hooks/archive-session.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # Claude Code Session Archiver
 # Archives complete session transcripts on session end
 #
diff --git a/.claude/hooks/audit-log.sh b/.claude/hooks/audit-log.sh
index e605f76..7b56b57 100755
--- a/.claude/hooks/audit-log.sh
+++ b/.claude/hooks/audit-log.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # audit-log.sh — PostToolUse hook that logs every tool invocation
 #
 # Creates an append-only JSONL audit trail at .claude/logs/audit.jsonl.
@@ -20,6 +20,10 @@
 # Hook event: PostToolUse (matcher: "")
 # Registered in: .claude/settings.json
 
+# -u: catch unset variable typos. Deliberately omit -e: this hook must
+# never block execution — all error paths exit 0.
+set -u
+
 INPUT=$(cat)
 
 # Parse fields from the hook JSON
diff --git a/.claude/hooks/bash-safety.sh b/.claude/hooks/bash-safety.sh
index 35d1130..1c00a27 100755
--- a/.claude/hooks/bash-safety.sh
+++ b/.claude/hooks/bash-safety.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # bash-safety.sh — PreToolUse hook that blocks dangerous Bash commands
 #
 # This is the primary safety guardrail for the DAAF environment. It reads
@@ -15,13 +15,21 @@
 #   rewrites remote history and is always blocked. Similarly, `curl <url>`
 #   is fine, but `curl <url> | bash` is arbitrary code execution.
 #
-# Hook event: PreToolUse (matcher: "Bash")                                                 
+# Hook event: PreToolUse (matcher: "Bash")
 # Registered in: .claude/settings.json
 
 # Fail CLOSED: if anything unexpected goes wrong, block the command.
 # This is a security hook — ambiguous failures must not silently allow execution.
 trap 'echo "BLOCKED by bash-safety hook: unexpected error in safety check" >&2; exit 2' ERR
 
+# --- Dependency check (fail-closed) ---
+# Without jq, we cannot inspect the tool invocation JSON. Failing open here
+# would silently bypass ALL safety checks, so we must block.
+if ! command -v jq &>/dev/null; then
+    echo "BLOCKED by bash-safety hook: jq is not installed (required for hook)" >&2
+    exit 2
+fi
+
 INPUT=$(cat)
 
 # Only inspect Bash tool calls
diff --git a/.claude/hooks/context-reporter.sh b/.claude/hooks/context-reporter.sh
index bfbf142..8210bd9 100755
--- a/.claude/hooks/context-reporter.sh
+++ b/.claude/hooks/context-reporter.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # context-reporter.sh — Multi-event context utilization & timestamp hook
 #
 # Injects context window utilization and a current timestamp into Claude's
@@ -31,6 +31,10 @@
 #   0 = success (stdout/JSON processed by Claude Code)
 #   All error paths exit 0 to never block tool execution.
 
+# -u: catch unset variable typos. Deliberately omit -e: this hook must
+# never block tool execution — all error paths exit 0.
+set -u
+
 INPUT=$(cat)
 HOOK_EVENT=$(echo "$INPUT" | jq -r '.hook_event_name // empty' 2>/dev/null) || HOOK_EVENT=""
 SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // "default"' 2>/dev/null) || SESSION_ID="default"
@@ -49,7 +53,7 @@ if [[ -f "$CTX_CACHE" ]]; then
     MAX_CONTEXT=$(cat "$CTX_CACHE" 2>/dev/null)
 else
     LATEST_CTX=$(ls -t /tmp/claude-ctx-window-* 2>/dev/null | head -1)
-    if [[ -n "$LATEST_CTX" ]]; then
+    if [[ -n "${LATEST_CTX:-}" ]]; then
         MAX_CONTEXT=$(cat "$LATEST_CTX" 2>/dev/null)
     fi
 fi
@@ -118,7 +122,7 @@ cache_model() {
         select(.message.model) | .message.model
     ' 2>/dev/null | head -1)
 
-    [[ -n "$model" ]] && echo "$model" > "$cache" 2>/dev/null
+    [[ -n "${model:-}" ]] && echo "$model" > "$cache" 2>/dev/null
 }
 
 # ---------------------------------------------------------------------------
@@ -137,7 +141,7 @@ fi
 
 # Interval elapsed — calculate and emit
 MSG=$(calculate "$TRANSCRIPT_PATH")
-[[ -z "$MSG" ]] && exit 0
+[[ -z "${MSG:-}" ]] && exit 0
 
 # Update the shared timestamp gate
 echo "$NOW" > "$LAST_INJECT_FILE" 2>/dev/null
diff --git a/.claude/hooks/deny-claude-code-guide.sh b/.claude/hooks/deny-claude-code-guide.sh
index c6534c2..920f642 100755
--- a/.claude/hooks/deny-claude-code-guide.sh
+++ b/.claude/hooks/deny-claude-code-guide.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # deny-claude-code-guide.sh
 # Blocks the claude-code-guide built-in agent from being spawned.
 # This is a built-in agent with an opaque system prompt that doesn't
diff --git a/.claude/hooks/enforce-explore-model.sh b/.claude/hooks/enforce-explore-model.sh
index 5d16616..9fa3a4b 100755
--- a/.claude/hooks/enforce-explore-model.sh
+++ b/.claude/hooks/enforce-explore-model.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # enforce-explore-model.sh
 # Prevents Explore-type subagents from being launched with the haiku model.
 # Explore agents need frontier-tier reasoning for thorough codebase analysis.
diff --git a/.claude/hooks/enforce-file-first.sh b/.claude/hooks/enforce-file-first.sh
index 4fca01c..43f8eed 100755
--- a/.claude/hooks/enforce-file-first.sh
+++ b/.claude/hooks/enforce-file-first.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # enforce-file-first.sh — PreToolUse hook that blocks direct python execution
 #
 # Enforces the file-first execution protocol: all Python scripts must be
diff --git a/.claude/hooks/enforce-foreground-agents.sh b/.claude/hooks/enforce-foreground-agents.sh
index 71a4ed9..511218e 100755
--- a/.claude/hooks/enforce-foreground-agents.sh
+++ b/.claude/hooks/enforce-foreground-agents.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # enforce-foreground-agents.sh
 # Prevents agents from being launched in the background.
 # Background agents cannot prompt for user permissions, which causes
diff --git a/.claude/hooks/first-run-transparency.txt b/.claude/hooks/first-run-transparency.txt
index 608b92c..187d7ae 100644
--- a/.claude/hooks/first-run-transparency.txt
+++ b/.claude/hooks/first-run-transparency.txt
@@ -31,6 +31,7 @@ DAAF generates transparent, auditable code and documentation so you CAN verify e
 5. WHAT THIS MEANS IN PRACTICE:
 - Always review core products from DAAF: early and often (e.g., preliminary scoping notes, research plan drafts)
 - Scrutinize results with your domain knowledge, especially anything that implies causation
+- Pay close attention to when DAAF loads reference files and Skills to inform and ground its work -- and make sure it's not taking shortcuts or going off of vibes
 - Treat DAAF's output as a high-quality first draft requiring expert review, not as a finished product
 - Know that DAAF's automated quality checks are strong but not infallible — they are one layer of defense, not the only one
 - Review the References section in reports: DAAF does its best to track and attribute citations for data sources, methods, and tools used, but citations can be wrong, incomplete, or missing entirely — you should verify that the right things are credited and that the citations themselves are accurate
diff --git a/.claude/hooks/flag-orchestrator-loaded.sh b/.claude/hooks/flag-orchestrator-loaded.sh
index 9e9c3f1..5166147 100755
--- a/.claude/hooks/flag-orchestrator-loaded.sh
+++ b/.claude/hooks/flag-orchestrator-loaded.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # flag-orchestrator-loaded.sh — Set flag when daaf-orchestrator skill loads
 #
 # Hook: PostToolUse (matcher: "Skill")
diff --git a/.claude/hooks/output-scanner.sh b/.claude/hooks/output-scanner.sh
index e51f7da..1dba779 100755
--- a/.claude/hooks/output-scanner.sh
+++ b/.claude/hooks/output-scanner.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # output-scanner.sh — PostToolUse hook that scans tool output for leaked secrets
 #
 # Checks tool_response content for patterns matching common credential formats:
diff --git a/.claude/hooks/recover-session-logs.sh b/.claude/hooks/recover-session-logs.sh
index 888de99..848fcbd 100755
--- a/.claude/hooks/recover-session-logs.sh
+++ b/.claude/hooks/recover-session-logs.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # recover-session-logs.sh -- SessionStart hook: activity logging + crash recovery
 #
 # Replaces the previous inline SessionStart command. Performs:
@@ -27,6 +27,11 @@
 #   - Background execution: recovery runs in a detached subprocess so session
 #     startup is never blocked (foreground work completes in <1s)
 #
+# Environment:
+#   DAAF_SYNC_RECOVERY=1  Run recovery synchronously (foreground) instead of
+#                         detached. Used by the Log Explorer refresh endpoint
+#                         to get deterministic completion instead of a sleep.
+#
 # Exit codes:
 #   0 = always (observability hook, must never block session start)
 #
@@ -42,13 +47,11 @@ INPUT=$(cat)
 mapfile -t _meta < <(
     printf '%s' "$INPUT" | jq -r '
         (.session_id // "unknown"),
-        (.transcript_path // ""),
-        (.cwd // "unknown")
+        (.transcript_path // "")
     ' 2>/dev/null
 )
 SESSION_ID="${_meta[0]:-unknown}"
 TRANSCRIPT_PATH="${_meta[1]:-}"
-CWD="${_meta[2]:-unknown}"
 
 PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
 LOG_DIR="$PROJECT_DIR/.claude/logs"
@@ -60,16 +63,16 @@ mkdir -p "$ARCHIVE_DIR"
 DAAF_VERSION=$(git -C "$PROJECT_DIR" describe --always --dirty 2>/dev/null || echo "unknown")
 echo "Session started: $(date '+%Y-%m-%d %H:%M:%S') | DAAF: $DAAF_VERSION | Session: ${SESSION_ID:0:8}" >> "$LOG_DIR/activity.log"
 
-# --- Section 2: Background recovery ---
+# --- Section 2: Recovery ---
 # Only attempt recovery if we have a transcript_path to derive the source directory
 if [ -n "$TRANSCRIPT_PATH" ]; then
     CURRENT_SHORT="${SESSION_ID:0:8}"
 
-    (
+    _do_recovery() {
         TRANSCRIPT_DIR=$(dirname "$TRANSCRIPT_PATH")
 
         # Bail if transcript directory doesn't exist
-        [ -d "$TRANSCRIPT_DIR" ] || exit 0
+        [ -d "$TRANSCRIPT_DIR" ] || return 0
 
         # Build index of already-archived session shorts with their file sizes
         # This is a single directory read -- O(m) where m = archived sessions
@@ -109,8 +112,12 @@ if [ -n "$TRANSCRIPT_PATH" ]; then
 
             # Archive this session by piping synthesized JSON to archive-session.sh
             # archive-session.sh's own idempotency guard provides a second safety net
-            printf '{"session_id":"%s","transcript_path":"%s","cwd":"%s","reason":"recovered"}' \
-                "$uuid" "$raw" "$PROJECT_DIR" \
+            jq -n \
+                --arg session_id "$uuid" \
+                --arg transcript_path "$raw" \
+                --arg cwd "$PROJECT_DIR" \
+                --arg reason "recovered" \
+                '{"session_id": $session_id, "transcript_path": $transcript_path, "cwd": $cwd, "reason": $reason}' \
                 | "$PROJECT_DIR/.claude/hooks/archive-session.sh" 2>/dev/null
 
             RECOVERED=$((RECOVERED + 1))
@@ -154,9 +161,14 @@ if [ -n "$TRANSCRIPT_PATH" ]; then
                 rm -f "$PENDING_TMP" 2>/dev/null
             fi
         fi
-
-    ) </dev/null >/dev/null 2>&1 &
-    disown
+    }
+
+    if [ "${DAAF_SYNC_RECOVERY:-}" = "1" ]; then
+        _do_recovery
+    else
+        _do_recovery </dev/null >/dev/null 2>&1 &
+        disown
+    fi
 fi
 
 exit 0
diff --git a/.claude/hooks/remind-orchestrator.sh b/.claude/hooks/remind-orchestrator.sh
index 155cb45..21ffcac 100755
--- a/.claude/hooks/remind-orchestrator.sh
+++ b/.claude/hooks/remind-orchestrator.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # remind-orchestrator.sh — Remind main-session LLM to load daaf-orchestrator
 #
 # Hook: UserPromptSubmit (main session only — subagents never trigger this)
diff --git a/.claude/scripts/context-bar.sh b/.claude/scripts/context-bar.sh
index c98a484..7f9bd7b 100755
--- a/.claude/scripts/context-bar.sh
+++ b/.claude/scripts/context-bar.sh
@@ -37,14 +37,60 @@ fi
 # Get transcript path for context calculation and last message feature
 transcript_path=$(echo "$input" | jq -r '.transcript_path // empty')
 
-# Get context window size from JSON (accurate), but calculate tokens from transcript
-# (more accurate than total_input_tokens which excludes system prompt/tools/memory)
+# Get context window size from JSON, but override for OpenRouter models where
+# Claude Code reports a hardcoded 200k default regardless of actual model.
+# Calculate tokens from transcript (more accurate than total_input_tokens which
+# excludes system prompt/tools/memory).
 # See: github.com/anthropics/claude-code/issues/13652
 max_context=$(echo "$input" | jq -r '.context_window.context_window_size // 200000')
+
+session_id=$(echo "$input" | jq -r '.session_id // "default"')
+
+# OpenRouter context window override: Claude Code doesn't know the real context
+# window size for third-party models accessed via OpenRouter, so it reports a
+# hardcoded 200k default. Query the OpenRouter models API once per session to
+# get the actual context_length for the current model.
+if [[ "${ANTHROPIC_BASE_URL:-}" == *openrouter.ai* ]]; then
+    model_id=$(echo "$input" | jq -r '.model.id // empty')
+    or_cache="/tmp/claude-or-models-${session_id}"
+
+    if [[ -n "$model_id" && ! -s "$or_cache" ]]; then
+        # Fetch models list once per session (3s timeout to avoid blocking statusline).
+        # Write to a temp file first and move atomically to prevent truncated JSON
+        # from a mid-download timeout from poisoning the cache for the entire session.
+        or_tmp="${or_cache}.tmp"
+        if curl -sf --connect-timeout 3 --max-time 3 \
+            "https://openrouter.ai/api/v1/models" > "$or_tmp" 2>/dev/null; then
+            mv "$or_tmp" "$or_cache" 2>/dev/null
+        else
+            rm -f "$or_tmp" 2>/dev/null
+        fi
+    fi
+
+    if [[ -n "$model_id" && -s "$or_cache" ]]; then
+        # Try exact match first; if not found, strip date suffix (-YYYYMMDD)
+        # because Claude Code appends snapshot dates (e.g., glm-5.1-20260406)
+        # but OpenRouter uses versionless IDs (e.g., z-ai/glm-5.1).
+        or_context=$(jq -r --arg id "$model_id" \
+            'first(.data[] | select(.id == $id) | .context_length) // empty' \
+            "$or_cache" 2>/dev/null)
+        if [[ -z "$or_context" ]]; then
+            stripped_id=$(echo "$model_id" | sed 's/-[0-9]\{8\}$//' 2>/dev/null)
+            if [[ "$stripped_id" != "$model_id" ]]; then
+                or_context=$(jq -r --arg id "$stripped_id" \
+                    'first(.data[] | select(.id == $id) | .context_length) // empty' \
+                    "$or_cache" 2>/dev/null)
+            fi
+        fi
+        if [[ -n "$or_context" && "$or_context" -gt 0 ]]; then
+            max_context="$or_context"
+        fi
+    fi
+fi
+
 max_k=$((max_context / 1000))
 
 # Share context window size with hooks (which don't receive it in their input payload)
-session_id=$(echo "$input" | jq -r '.session_id // "default"')
 echo "$max_context" > "/tmp/claude-ctx-window-${session_id}" 2>/dev/null
 
 # Calculate context bar from transcript
diff --git a/.claude/settings.json b/.claude/settings.json
index b38dbf9..7e1ac97 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -73,6 +73,9 @@
       "Write(.env.*)",
       "Edit(.env)",
       "Edit(.env.*)",
+      "Read(environment_settings*)",
+      "Write(environment_settings*)",
+      "Edit(environment_settings*)",
       "Edit(.claude/hooks/*)",
       "Write(.claude/hooks/*)",
       "Edit(.claude/logs/*)",
@@ -85,7 +88,8 @@
     "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
     "CLAUDE_CODE_DISABLE_BACKGROUND_TASKS": "1",
     "DISABLE_AUTOUPDATER": "1",
-    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
+    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
+    "ENABLE_PROMPT_CACHING_1H": "1"
   },
   "outputStyle": "Explanatory",
   "showThinkingSummaries": true,
diff --git a/.claude/skills/daaf-orchestrator/SKILL.md b/.claude/skills/daaf-orchestrator/SKILL.md
index eca0fc1..d80ec0c 100644
--- a/.claude/skills/daaf-orchestrator/SKILL.md
+++ b/.claude/skills/daaf-orchestrator/SKILL.md
@@ -255,6 +255,7 @@ Even for simple lookups, always confirm — the user may want broader context th
 | Full Pipeline (complete) | Framework Development | User identifies framework improvements based on analysis experience; System Update Action Plan in LEARNINGS.md has actionable items — proactively suggest "incorporate learnings" |
 | Data Onboarding (complete) | Framework Development | System Update Action Plan in LEARNINGS.md has actionable items (e.g., skill template gaps discovered during profiling) |
 | User Support | Any mode | User's questions reveal they want to *do* something, not just learn — route to appropriate mode |
+| User Support (update conflicts) | Framework Development | Conflict resolution reveals customizations needing architectural re-integration beyond merge fixes — finish git operation first, then new session |
 | Any mode | User Support | Persistent confusion signals despite reactive help; user explicitly asks for general DAAF guidance |
 
 When escalation is appropriate, propose it explicitly:
@@ -551,13 +552,29 @@ See `.claude/agents/README.md` for the complete agent index with key inputs and
 - Complete code files (only references)
 - Full error tracebacks (only summaries)
 
+### Preliminary Notes Persistence
+
+Discovery and profiling agents produce rich, structured findings that downstream agents need at full fidelity. The orchestrator persists these as "preliminary notes" — lossless markdown files written to `output/preliminary_notes/` in the project directory. Downstream agents reference these files by path to supplement the orchestrator's compressed inline summaries. The orchestrator retains its own compressed summaries for coordination efficiency (gate decisions, STATE.md tracking, user-facing checkpoints).
+
 ### Subagent Return Processing
 
 When a subagent returns findings:
 1. Verify against expected OUTPUT FORMAT
-2. Extract: Status, key findings (3-5 bullets), file locations, confidence level, issues requiring escalation
-3. Discard: Verbose explanations, intermediate steps, full code blocks, raw data samples
-4. Store summarized key findings in working memory
+2. If the agent's output should be captured losslessly to disk per current WORKFLOW documents, write the FULL, UNMODIFIED return text to disk:
+   a. Create file at the designated path (see table)
+   b. Prepend the provenance header (see Provenance Header Template below)
+   c. Confirm file was written successfully — this is a **gate condition**: do not proceed until the file exists on disk and contains the complete agent return
+3. Extract: Status, key findings (3-5 bullets), file locations, confidence level, issues requiring escalation
+4. Discard from working memory: Verbose explanations, intermediate steps, full code blocks, raw data samples
+5. Store summarized key findings + **preliminary notes file path** in working memory
+
+**Provenance Header Template** (prepended as HTML comments so they don't interfere with the agent's markdown):
+```
+<!-- Preliminary Notes: auto-generated by orchestrator from {agent_type} return -->
+<!-- Stage: {stage_identifier} | Agent: {agent_name} | Generated: {ISO_timestamp} -->
+```
+
+If a write fails, retry once. If the retry also fails, stop and report the issue to the user — do not proceed with degraded findings.
 
 ### Context Recovery
 
diff --git a/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_AUTHORING.md b/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_AUTHORING.md
index 0453144..b78c54d 100644
--- a/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_AUTHORING.md
+++ b/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_AUTHORING.md
@@ -36,7 +36,19 @@ and analytical limitations that cannot be derived from profiling scripts alone.
 files must synthesize both profiling-derived observations AND documentation-derived context.
 If a documentation website URL is in STATE.md, fetch key pages for methodology context.
 
+**PROFILING PRELIMINARY NOTES:** Consolidated profiling findings from each phase are at:
+- {project_dir}/output/preliminary_notes/{date}_partA_structural-discovery.md
+- {project_dir}/output/preliminary_notes/{date}_partB_statistical-deep-dive.md
+- {project_dir}/output/preliminary_notes/{date}_partC_relational-analysis.md
+- {project_dir}/output/preliminary_notes/{date}_partD_interpretation-reconciliation.md
+Read these preliminary notes FIRST for structured summaries and recommendations from
+each profiling phase. These complement the execution logs in scripts/ — the preliminary
+notes provide the narrative, confidence assessments, and recommendations; the execution
+logs provide the granular data-level detail.
+
 **PROFILING SCRIPTS:** All executed scripts with execution logs are in `{project_dir}/scripts/`.
+The preliminary notes above provide a consolidated narrative layer; consult the execution
+logs below for granular data when the notes reference specific findings.
 Read these scripts as primary sources for data-level skill content:
 - Scripts 01-03 (structural) → schema, column details, data access patterns
 - Script 04 (distributions) → distribution notes, Common Pitfalls
@@ -216,7 +228,7 @@ Reference file density:
 - [ ] Profiling scripts bundled in .claude/skills/{skill_name}/scripts/ (excluding QA/cr scripts)
 - [ ] CPP-SKILL results reported as itemized pass/fail per check item (not just overall status)
 
-**OUTPUT FORMAT (2500-word hard cap):**
+**OUTPUT FORMAT (3500-word hard cap):**
 ### Skill Authoring: {skill_name}
 - CPP-SKILL Status (template compliance) — itemized pass/fail per checklist item
 - Line count: SKILL.md [N] lines, reference files [N] total lines ([ratio]x)
diff --git a/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_PROFILING.md b/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_PROFILING.md
index ff93cbd..ec2a697 100644
--- a/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_PROFILING.md
+++ b/.claude/skills/daaf-orchestrator/references/WORKFLOW_PHASE_DO_PROFILING.md
@@ -425,32 +425,29 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the file-first protocol
 Scripts go to: scripts/profile_structural/
 Execute: bash {BASE_DIR}/scripts/run_with_capture.sh {project_script_dir}/profile_structural/{script}.py
 
-**OUTPUT FORMAT (2500-word hard cap):**
-### Part A: Structural Discovery
-- CPP1 Status, Rows/Columns/Memory, type summary
-- Potential identifiers (>95% unique), categoricals (<50 unique)
+**OUTPUT FORMAT:**
+Return findings using the Data Ingest Output Format
+(see your agent protocol, § Output Format).
+
+**Emphasis for this invocation (Part A):**
+- CPP1 status and structural findings (rows, columns, memory, types)
+- Potential identifiers (>95% unique) and categoricals (<50 unique)
 - Coded value indicators (negative values or sentinels)
-### Conditional Script Decisions
-- Script 05: [EXECUTE/SKIP] -- [reason based on temporal/date columns]
-- Script 06: [EXECUTE/SKIP] -- [reason based on entity/geo ID columns]
-- Script 08: [EXECUTE/SKIP] -- [reason based on numeric column count]
-- Script 11: [EXECUTE/SKIP] -- [reason based on documentation availability]
-### Scripts Created
-- [paths with execution status]
-### Confidence Assessment
-**Part Confidence:** [HIGH | MEDIUM | LOW]
-| Aspect | Confidence | Rationale |
-### Issues Requiring Attention
-[BLOCKERs, WARNINGs, or "None"]
-### Learning Signal
-**Learning Signal:** [Category] -- [One-line insight] | "None"
-### Recommendations
-- **Proceed?** [YES | NO -- issues block | NO -- escalate]
-- [Specific next actions] """,
+- Conditional Script Decisions for Parts B-D (Script 05, 06, 08, 11 — EXECUTE/SKIP with reason) """,
     subagent_type: "data-ingest"
 })
 ```
 
+#### Preliminary Notes Persistence: Part A
+
+After the Part A data-ingest agent returns, the orchestrator persists the full return to disk:
+
+| Agent Return | Write To |
+|-------------|----------|
+| data-ingest (Part A) | `{project_dir}/output/preliminary_notes/{date}_partA_structural-discovery.md` |
+
+**Gate condition:** Part A preliminary notes must exist on disk before dispatching Part B data-ingest agent. The orchestrator confirms the file was written in Subagent Return Processing step 1 (see orchestrator SKILL.md).
+
 ### Part B: Statistical Deep Dive
 
 **Purpose:** Execute scripts 04-06  |  **Stage:** DI-4, Part B  |  **Subagent:** data-ingest  |  **Skills:** `data-scientist`
@@ -469,7 +466,9 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the file-first protocol
 - Data file: {data_file_path} (primary file if multi-file)
 - File format: {file_format}
 - Canonical load pattern: {canonical_load_from_part_a}
-- Prior part findings: {part_a_summary}
+- Prior part findings (orientation summary): {part_a_summary_brief}
+- Prior part full preliminary notes:
+  Read: {project_dir}/output/preliminary_notes/{date}_partA_structural-discovery.md
 - Conditional script decisions: Script 05 [{EXECUTE/SKIP}], Script 06 [{EXECUTE/SKIP}]
 - Target skill name: {skill_name}
 - Domain context: {domain_context}
@@ -493,25 +492,28 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the file-first protocol
 Scripts go to: scripts/profile_statistical/
 Execute: bash {BASE_DIR}/scripts/run_with_capture.sh {project_script_dir}/profile_statistical/{script}.py
 
-**OUTPUT FORMAT (2500-word hard cap):**
-### Part B: Statistical Deep Dive
-- CPP2 Status, distribution summary, outlier summary, multimodality
-- Temporal/entity coverage: [executed/skipped — key findings]
-### Scripts Created
-### Confidence Assessment
-**Part Confidence:** [HIGH | MEDIUM | LOW]
-| Aspect | Confidence | Rationale |
-### Issues Requiring Attention
-[BLOCKERs, WARNINGs, or "None"]
-### Learning Signal
-**Learning Signal:** [Category] -- [One-line insight] | "None"
-### Recommendations
-- **Proceed?** [YES | NO -- issues block | NO -- escalate]
-- [Specific next actions] """,
+**OUTPUT FORMAT:**
+Return findings using the Data Ingest Output Format
+(see your agent protocol, § Output Format).
+
+**Emphasis for this invocation (Part B):**
+- CPP2 status, distribution summaries, outlier findings
+- Temporal coverage: [executed/skipped — key findings]
+- Entity coverage: [executed/skipped — key findings] """,
     subagent_type: "data-ingest"
 })
 ```
 
+#### Preliminary Notes Persistence: Part B
+
+After the Part B data-ingest agent returns, the orchestrator persists the full return:
+
+| Agent Return | Write To |
+|-------------|----------|
+| data-ingest (Part B) | `{project_dir}/output/preliminary_notes/{date}_partB_statistical-deep-dive.md` |
+
+**Gate condition:** Part B preliminary notes must exist on disk before dispatching Part C.
+
 ### Part C: Relational Analysis
 
 **Purpose:** Execute scripts 07-09  |  **Stage:** DI-5, Part C  |  **Subagent:** data-ingest  |  **Skills:** `data-scientist`
@@ -530,7 +532,10 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the file-first protocol
 - Data file: {data_file_path} (primary file if multi-file)
 - File format: {file_format}
 - Canonical load pattern: {canonical_load_from_part_a}
-- Prior part findings: {part_a_summary}, {part_b_summary}
+- Prior part findings (orientation summary): {accumulated_brief_summary}
+- Prior part full preliminary notes:
+  Read: {project_dir}/output/preliminary_notes/{date}_partA_structural-discovery.md
+  Read: {project_dir}/output/preliminary_notes/{date}_partB_statistical-deep-dive.md
 - Conditional script decisions: Script 07b [{EXECUTE/SKIP}], Script 08 [{EXECUTE/SKIP}]
 - Target skill name: {skill_name}
 - Domain context: {domain_context}
@@ -556,25 +561,28 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the file-first protocol
 Scripts go to: scripts/profile_relational/
 Execute: bash {BASE_DIR}/scripts/run_with_capture.sh {project_script_dir}/profile_relational/{script}.py
 
-**OUTPUT FORMAT (2500-word hard cap):**
-### Part C: Relational Analysis
-- CPP3 Status, recommended key, dependencies, high correlations
-- Coded missing values found, anomaly catalog counts, duplicate rows
-### Scripts Created
-### Confidence Assessment
-**Part Confidence:** [HIGH | MEDIUM | LOW]
-| Aspect | Confidence | Rationale |
-### Issues Requiring Attention
-[BLOCKERs, WARNINGs, or "None"]
-### Learning Signal
-**Learning Signal:** [Category] -- [One-line insight] | "None"
-### Recommendations
-- **Proceed?** [YES | NO -- issues block | NO -- escalate]
-- [Specific next actions] """,
+**OUTPUT FORMAT:**
+Return findings using the Data Ingest Output Format
+(see your agent protocol, § Output Format).
+
+**Emphasis for this invocation (Part C):**
+- CPP3 status, recommended key, dependencies, high correlations
+- Coded missing values found, anomaly catalog counts
+- Cross-level linkage findings (if HIERARCHICAL) """,
     subagent_type: "data-ingest"
 })
 ```
 
+#### Preliminary Notes Persistence: Part C
+
+After the Part C data-ingest agent returns, the orchestrator persists the full return:
+
+| Agent Return | Write To |
+|-------------|----------|
+| data-ingest (Part C) | `{project_dir}/output/preliminary_notes/{date}_partC_relational-analysis.md` |
+
+**Gate condition:** Part C preliminary notes must exist on disk before dispatching Part D.
+
 ### Part D: Interpretation & Reconciliation
 
 **Purpose:** Execute scripts 10-11  |  **Stage:** DI-6, Part D  |  **Subagent:** data-ingest  |  **Skills:** `data-scientist`
@@ -593,7 +601,11 @@ Read `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the file-first protocol
 - Data file: {data_file_path} (primary file if multi-file)
 - File format: {file_format}
 - Canonical load pattern: {canonical_load_from_part_a}
-- Prior part findings: {part_a_summary}, {part_b_summary}, {part_c_summary}
+- Prior part findings (orientation summary): {accumulated_brief_summary}
+- Prior part full preliminary notes:
+  Read: {project_dir}/output/preliminary_notes/{date}_partA_structural-discovery.md
+  Read: {project_dir}/output/preliminary_notes/{date}_partB_statistical-deep-dive.md
+  Read: {project_dir}/output/preliminary_notes/{date}_partC_relational-analysis.md
 - Documentation files: {doc_file_paths_or_none}
 - Conditional script decisions: Script 11 [{EXECUTE/SKIP}]
 - Target skill name: {skill_name}
@@ -637,35 +649,29 @@ your return, with source citation for each exclusion. Even without documentation
 apparent population boundaries observed during profiling (e.g., "data appears limited to
 public institutions only" based on entity coverage in Part B).
 
-**OUTPUT FORMAT (2500-word hard cap):**
-### Part D: Interpretation & Reconciliation
-- CPP4 Status, interpretation count
-- Documentation reconciliation: [executed/skipped — discrepancy count]
-### Preliminary Interpretations (ALL columns)
-| Column | Interpretation | Confidence | Basis |
-### Domain Decomposition
-| Domain | Columns | Dedicated Reference File? | Rationale |
-|--------|---------|--------------------------|-----------|
-| [e.g., "Outcome variables"] | [column list or count] | [Yes/No] | [Why — methodology complexity, distinct limitations, etc.] |
-### Exclusions Identified
-| Exclusion | Source | Impact |
-|-----------|--------|--------|
-| [e.g., "Private schools not included"] | [Documentation page/section or profiling observation] | [Generalizability implication] |
-### Scripts Created
-### Confidence Assessment
-**Part Confidence:** [HIGH | MEDIUM | LOW]
-| Aspect | Confidence | Rationale |
-### Issues Requiring Attention
-[BLOCKERs, WARNINGs, or "None"]
-### Learning Signal
-**Learning Signal:** [Category] -- [One-line insight] | "None"
-### Recommendations
-- **Proceed?** [YES | NO -- issues block | NO -- escalate]
-- [Specific next actions] """,
+**OUTPUT FORMAT:**
+Return findings using the Data Ingest Output Format
+(see your agent protocol, § Output Format).
+
+**Emphasis for this invocation (Part D):**
+- CPP4 status, interpretation count, documentation reconciliation
+- Full Preliminary Interpretations table (ALL columns — critical for PSU-DI2 user review)
+- Domain Decomposition table
+- Exclusions Identified table """,
     subagent_type: "data-ingest"
 })
 ```
 
+#### Preliminary Notes Persistence: Part D
+
+After the Part D data-ingest agent returns, the orchestrator persists the full return:
+
+| Agent Return | Write To |
+|-------------|----------|
+| data-ingest (Part D) | `{project_dir}/output/preliminary_notes/{date}_partD_interpretation-reconciliation.md` |
+
+**Gate condition:** Part D preliminary notes must exist on disk before presenting PSU-DI2 to the user and before dispatching DI-7 (skill authoring). All four profiling preliminary notes (Parts A-D) must be on disk before DI-7 can proceed.
+
 ### QA Invocation Template
 
 Invoked after each profiling part completes. Orchestrator substitutes part-specific values.
@@ -705,7 +711,7 @@ IAT compliance: Required per agent_reference/INLINE_AUDIT_TRAIL.md
 4. Execute QA scripts and synthesize findings
 5. Return QA report with severity classification
 
-**OUTPUT FORMAT (2500-word hard cap):**
+**OUTPUT FORMAT (3500-word hard cap):**
 ### QA Review: Part {X}
 **QAP{N} Status:** [PASSED | ISSUES_FOUND]
 **Severity:** [BLOCKER | WARNING | INFO | None]
diff --git a/.claude/skills/daaf-orchestrator/references/ad-hoc-collaboration-mode.md b/.claude/skills/daaf-orchestrator/references/ad-hoc-collaboration-mode.md
index 0e76610..e12249b 100644
--- a/.claude/skills/daaf-orchestrator/references/ad-hoc-collaboration-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/ad-hoc-collaboration-mode.md
@@ -221,9 +221,9 @@ mode. Context for this task:
 
 ## Agent Output Handling
 
-In pipeline modes, agent output is a concise signal to the orchestrator (1000-word cap, processed internally). In Ad Hoc Collaboration mode, agent findings are typically **the deliverable to the user**, so output handling changes:
+In pipeline modes, agent output is a concise signal to the orchestrator (2000-word cap, processed internally). In Ad Hoc Collaboration mode, agent findings are typically **the deliverable to the user**, so output handling changes:
 
-**Output cap override:** When dispatching agents in Ad Hoc Collaboration mode, include this instruction in the prompt: "Output cap is relaxed to 2000 words. Your findings will be relayed directly to the user, so prioritize clarity and completeness over brevity." This applies to all agents dispatched in this mode. The standard 1000-word pipeline cap remains in effect for all other modes.
+**Output cap override:** When dispatching agents in Ad Hoc Collaboration mode, include this instruction in the prompt: "Output cap is relaxed to 3000 words. Your findings will be relayed directly to the user, so prioritize clarity and completeness over brevity." This applies to all agents dispatched in this mode. The standard 2000-word pipeline cap remains in effect for all other modes.
 
 **Relay guidelines:**
 
@@ -412,6 +412,9 @@ There is no mandatory wrap-up protocol. The session ends when the user is done.
 > - [List of scripts, data files, figures]
 > - [Key findings or decisions made]
 >
-> Session notes are saved in `SESSION_NOTES.md` if you want to come back to it. I've also copied in the session logs in the project logs folder."
+> Session notes are saved in `SESSION_NOTES.md` if you want to come back to it. I've also copied in the session logs in the project logs folder.
+>
+> To browse the session timeline interactively, run in the Docker terminal:
+> `bash /daaf/scripts/generate_log_viewer.sh {PROJECT_DIR}`"
 
 This is a courtesy, not a gate. If the user just says "thanks" and leaves, that's fine.
diff --git a/.claude/skills/daaf-orchestrator/references/data-lookup-mode.md b/.claude/skills/daaf-orchestrator/references/data-lookup-mode.md
index 720f448..0f92aba 100644
--- a/.claude/skills/daaf-orchestrator/references/data-lookup-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/data-lookup-mode.md
@@ -67,7 +67,7 @@ from base knowledge. Flag reduced confidence due to the missing skill.
 {user's specific question}
 
 ## RESPONSE FORMAT
-**Hard cap: 500 words.** Answer directly and concisely.
+**Hard cap: 750 words.** Answer directly and concisely.
 
 Provide:
 - The specific values, definitions, or information requested
@@ -110,7 +110,7 @@ you do not need to produce a complete 5-section report if the question
 only touches one area (e.g., coded values only → focus on VARIABLES section).
 
 ## RESPONSE FORMAT
-**Hard cap: 500 words.** Return only the sections relevant to the question.
+**Hard cap: 750 words.** Return only the sections relevant to the question.
 
 - The specific answer to the question
 - Supporting detail from the relevant report section(s)
diff --git a/.claude/skills/daaf-orchestrator/references/data-onboarding-mode.md b/.claude/skills/daaf-orchestrator/references/data-onboarding-mode.md
index 059e541..016a26e 100644
--- a/.claude/skills/daaf-orchestrator/references/data-onboarding-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/data-onboarding-mode.md
@@ -304,40 +304,33 @@ Record the decision in STATE.md Key Decisions Made.
 
 When the user needs to set up an API key and it's not currently available in the environment, present these options:
 
-**For the current session (temporary):**
+**Recommended: Use the environment_settings.txt file (persistent across restarts):**
 
-> Before launching Claude Code, run this in your Docker container terminal:
+> Add your key to the `environment_settings.txt` file in your `daaf-docker/` folder on the host machine:
 > ```bash
-> export YOUR_API_KEY_NAME="your_key_here"
+> YOUR_API_KEY_NAME=your_key_here
 > ```
-> You can also type `! export YOUR_API_KEY_NAME="your_key_here"` directly in the Claude Code prompt to set it for this session.
+> If you don't have an `environment_settings.txt` file yet, copy the template: `cp environment_settings_example.txt environment_settings.txt`
+> (or `Copy-Item environment_settings_example.txt environment_settings.txt` on Windows). Then recreate the container: `docker compose down` followed by `run_daaf`.
 
-**For persistence across sessions:**
+**Alternative: Set for the current session only (temporary):**
 
-> Add the export to your shell profile inside the container:
+> Before launching Claude Code, run this in your Docker container terminal:
 > ```bash
-> echo 'export YOUR_API_KEY_NAME="your_key_here"' >> ~/.bashrc
-> ```
-
-**For Docker Compose (recommended for team or repeated use):**
-
-> Add to the `environment:` section in `docker-compose.yml`:
-> ```yaml
-> environment:
->   - YOUR_API_KEY_NAME=${YOUR_API_KEY_NAME}
+> export YOUR_API_KEY_NAME="your_key_here"
 > ```
-> Then set the variable on your host machine before running `docker compose up`.
+> You can also type `! export YOUR_API_KEY_NAME="your_key_here"` directly in the Claude Code prompt to set it for this session.
 
 **Security notes to convey to user:**
-- DAAF's safety guardrails prevent reading or writing `.env` files — this is by design
-- Credentials stay in temporary memory only and are never written to files
+- The `environment_settings.txt` file lives on the host machine (in `daaf-docker/`), is gitignored, and is never visible to Claude inside the container
+- DAAF's safety guardrails prevent Claude from reading or writing environment settings files by design
 - The acquisition script references `os.environ["KEY_NAME"]`, never hardcodes the key value
 - The script is archived in the project for reproducibility, but the key value is never in it
 
 **OAuth / complex authentication:** If the API requires OAuth 2.0 (token refresh, browser-based authorization code flow) or other multi-step authentication, DI-0 cannot handle this automatically. In this case, advise the user to:
 1. Complete the OAuth flow manually outside DAAF (e.g., using the API's web portal or a CLI tool)
 2. Obtain a bearer token or access token
-3. Set it as an environment variable (e.g., `export MY_API_TOKEN="bearer_token_here"`)
+3. Add it to their `environment_settings.txt` file (e.g., `MY_API_TOKEN=bearer_token_here`) or set it as an environment variable
 4. Proceed with DI-0 using the token as a simple API key
 
 Note in the skill's Data Access section that the token may expire and needs periodic renewal. Alternatively, the user can download the data manually and provide it as a local file.
@@ -397,7 +390,7 @@ user's requested dataset to the project's data/raw/ directory.
 
 ## Output Format
 
-Return findings in this structure (max 2500 words):
+Return findings in this structure (max 3500 words):
 
 ### DI-0 Summary
 **Status:** [SCRIPT_READY | BLOCKED]
@@ -475,6 +468,9 @@ For EACH profiling part (DI-3 through DI-6), follow this complete cycle. **Do NO
 │      │   Capture from return: script paths, CPP status, part summary,      │
 │      │   conditional script decisions (Part A only), learning signals.     │
 │      │                                                                      │
+│      │   Write the full, unmodified agent return to markdown file on disk  │
+│      │   (see Preliminary Notes Persistence in WORKFLOW_PHASE docs)        │
+│      │                                                                      │
 │      └─ WAIT for data-ingest subagent to return before proceeding          │
 ├─────────────────────────────────────────────────────────────────────────────┤
 │  STEP 2: INVOKE code-reviewer (MANDATORY — DO NOT SKIP)                     │
@@ -759,7 +755,7 @@ Before dispatching a profiling subagent (Stages DI-3 through DI-6), verify:
 - [ ] Data file path(s) specified (absolute)
 - [ ] Source name and format inlined
 - [ ] Column batching boundaries specified (if >100 columns)
-- [ ] Prior part outputs inlined (for Parts B-D: structural findings from Part A)
+- [ ] Prior part findings provided (for Parts B-D: orientation summary + preliminary notes file paths)
 - [ ] Conditional script decisions documented with reasoning
 - [ ] Priority columns from intake highlighted (if any)
 - [ ] Documentation excerpts inlined (if provided and relevant to current part)
@@ -795,17 +791,30 @@ All data for a Data Onboarding project lives inside the research project folder,
 
 ```
 research/YYYY-MM-DD_{Source_Name}_Onboarding/
+├── STATE.md                                       # Session state (REQUIRED)
+├── LEARNINGS.md                                   # Session learnings (REQUIRED)
+├── logs/                                          # Session transcripts (collected at completion)
+├── scripts/
+│   ├── profile_structural/                        # Part A profiling scripts
+│   ├── profile_statistical/                       # Part B profiling scripts
+│   ├── profile_relational/                        # Part C profiling scripts
+│   ├── profile_interpretation/                    # Part D profiling scripts
+│   ├── stage5_fetch/                              # API fetch scripts (if API acquisition)
+│   └── cr/                                        # QA review scripts (phase-based)
 ├── data/
-│   └── raw/                    # Original data files (immutable after drop)
+│   └── raw/                                       # Original data files (immutable after drop)
 │       ├── {file1}.parquet
 │       └── {file2}.parquet
-├── ...
+└── output/
+    ├── skill_draft/                               # Draft skill before final placement
+    │   └── SKILL.md
+    └── preliminary_notes/                         # Lossless agent returns persisted by orchestrator
 ```
 
 #### Setup Protocol
 
 1. **Stage DI-2:** Create the research project folder under `research/`
-2. **Create `data/raw/`** subdirectory inside the research project
+2. **Create `data/raw/`** and **`output/preliminary_notes/`** subdirectories inside the research project
 3. **Copy** user-provided data files into `data/raw/`
 4. **Initialize STATE.md** from `{BASE_DIR}/agent_reference/STATE_TEMPLATE_ONBOARDING.md` — this template has onboarding-specific sections (DI-1 through DI-8 stages, Profiling Progress table, Interpretation Tracking, Skill Authoring Status) that differ from the Full Pipeline template. Populate the Data Source Info and User Request sections with intake information.
 5. **Instruct user** if files need manual placement (e.g., files too large to copy, or user prefers to place them directly)
@@ -844,6 +853,10 @@ The skill is automatically discoverable via its YAML frontmatter and ready for u
 - Contains: [N] profiling scripts, [N] QA reviews, STATE.md, LEARNINGS.md
 - Session logs: `logs/` (collected via `collect_session_logs.sh`)
 
+**Explore Session Logs:**
+To browse the session timeline interactively in your browser, run in the Docker terminal:
+`bash /daaf/scripts/generate_log_viewer.sh {PROJECT_DIR}`
+
 **Confidence Assessment:**
 - Structural profile: [HIGH/MEDIUM/LOW] — [brief rationale]
 - Statistical profile: [HIGH/MEDIUM/LOW] — [brief rationale]
diff --git a/.claude/skills/daaf-orchestrator/references/framework-development-mode.md b/.claude/skills/daaf-orchestrator/references/framework-development-mode.md
index 5fd162f..1169e4e 100644
--- a/.claude/skills/daaf-orchestrator/references/framework-development-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/framework-development-mode.md
@@ -163,7 +163,7 @@ Provide a structured report with:
 3. Potential impacts or dependencies discovered
 4. Recommended approach considerations
 
-Keep output under 800 words. Focus on findings, not descriptions of what you read.
+Keep output under 1500 words. Focus on findings, not descriptions of what you read.
 ```
 
 ### Phase 1 Exploration Prompt Template: Incorporate Learnings
@@ -197,7 +197,7 @@ Provide a structured report with:
 3. Duplicates identified (same target + same proposed change from multiple projects)
 4. Total counts: action items found, unique after dedup, by priority (P1/P2/P3)
 
-Keep output under 800 words. Focus on the consolidated backlog, not descriptions
+Keep output under 1500 words. Focus on the consolidated backlog, not descriptions
 of each file.
 ```
 
@@ -227,7 +227,7 @@ Provide a structured report with:
 2. Summary counts: already done, partial, still needed
 3. Any target files that no longer exist or have been restructured
 
-Keep output under 800 words.
+Keep output under 1500 words.
 ```
 
 **Subagent 3: Dependency and Ordering Analysis**
@@ -258,7 +258,7 @@ Provide a structured report with:
 4. Estimated complexity per item (Simple / Moderate / Complex) based on the
    number of files affected and nature of the change
 
-Keep output under 800 words.
+Keep output under 1500 words.
 ```
 
 **Note:** Subagents 2 and 3 depend on earlier results. The orchestrator may run Subagent 1 first, then Subagents 2 and 3 in sequence (or parallel if the orchestrator inlines findings). Alternatively, the orchestrator can run all three with standing instructions and let each subagent scan independently — trading some duplication for parallelism.
@@ -658,7 +658,7 @@ These boundaries supplement the universal safety boundaries in `CLAUDE.md`. See
 - Changing the structure of existing templates (AGENT_TEMPLATE.md, MODE_TEMPLATE.md, etc.)
 - Deleting or renaming existing framework files
 - Making changes beyond the user's stated scope
-- Modifying Dockerfile or docker-compose.yml. **When the user approves the edit, you must also remind them about the container-host boundary** before they rebuild: the file you just edited lives in the volume copy, but `docker compose up -d --build` reads the host copy. After making the edit, instruct the user to (1) exit Claude Code (`/exit`) and the container (`exit`), (2) run `docker cp daaf-daaf-docker-1:/daaf/<filename> ./<filename>` from their host terminal in the DAAF project folder (substituting `Dockerfile` or `docker-compose.yml` for `<filename>`), and (3) then run `docker compose up -d --build`. Skipping the copy-back step causes the rebuild to silently use the unchanged host file. Point them to `user_reference/04_extending_daaf.md` § "The Recommended Path: Modify the Dockerfile" for the full procedure if they want more detail.
+- Modifying Dockerfile or docker-compose.yml. **When the user approves the edit, you must also remind them about the container-host boundary** before they rebuild: the file you just edited lives in the volume copy, but `docker compose up -d --build` reads the host copy. After making the edit, instruct the user to (1) exit Claude Code (`/exit`) and the container (`exit`), (2) run `bash rebuild_daaf.sh` (or `.\rebuild_daaf.ps1` on Windows) from their `daaf-docker` folder — this copies the updated files from the container to the host and rebuilds the image automatically. If they don't have the rebuild script, the manual alternative is `docker cp daaf-daaf-docker-1:/daaf/<filename> ./<filename>` followed by `docker compose up -d --build`. Point them to `user_reference/04_extending_daaf.md` § "The Recommended Path: Modify the Dockerfile" for the full procedure if they want more detail.
 
 ### Never Do
 
@@ -672,6 +672,29 @@ These boundaries supplement the universal safety boundaries in `CLAUDE.md`. See
 
 ---
 
+## Session Wrap-Up
+
+When the user signals the session is ending, or after Checkpoint 2 approval with no further work:
+
+1. Update SESSION_NOTES.md with a final summary (all sections)
+2. If a research project workspace was created (i.e., the work involved subagent dispatches worth reviewing), collect session logs:
+   ```bash
+   bash {BASE_DIR}/scripts/collect_session_logs.sh {PROJECT_DIR}
+   ```
+3. Offer a brief summary to the user:
+
+> "Here's what we modified:
+> - [List of framework files created/modified]
+> - [Integration points updated]
+>
+> Session notes are saved in `SESSION_NOTES.md`.
+>
+> [If logs were collected:]
+> To browse the session timeline interactively, run in the Docker terminal:
+> `bash /daaf/scripts/generate_log_viewer.sh {PROJECT_DIR}`"
+
+---
+
 ## Escalation Triggers
 
 | Condition | Target Mode | Action |
@@ -682,4 +705,13 @@ These boundaries supplement the universal safety boundaries in `CLAUDE.md`. See
 | User wants to review or revise an analysis that used the framework | Revision and Extension | "That's a revision of existing analysis work. Want me to switch to Revision and Extension mode?" |
 | Framework change requires testing with a specific data source | Data Discovery | "Let me explore what's available for that data source first." |
 
+**Inbound from User Support (update conflicts):** When User Support's update
+conflict resolution walkthrough reveals that a user's customizations need
+architectural re-integration (not just merge fixes), the user is directed to
+start a new Framework Development session after the update completes. In this
+scenario, Phase 1 scoping should pay special attention to what changed upstream
+and how the user's custom components (agents, skills, modes) need to be rewired
+to the updated framework. The "Modify Existing" work type is the typical
+classification, though "Multi-Component" may apply for extensive customizations.
+
 All escalations require explicit user confirmation.
diff --git a/.claude/skills/daaf-orchestrator/references/full-pipeline-mode.md b/.claude/skills/daaf-orchestrator/references/full-pipeline-mode.md
index 1507281..a1f867d 100644
--- a/.claude/skills/daaf-orchestrator/references/full-pipeline-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/full-pipeline-mode.md
@@ -910,11 +910,12 @@ Each stage has explicit input/output contracts and gate criteria:
 
 | Check | What to Verify | Action if Failed |
 |-------|----------------|------------------|
-| **Size** | Output is under 1000 words | Extract only structured summary fields; discard verbose sections, raw logs, and data samples before integrating into context. If chronic, re-invoke with emphasis on the 1000-word hard cap. |
+| **Size** | Output is under 2000 words | Extract only structured summary fields; discard verbose sections, raw logs, and data samples before integrating into context. If chronic, re-invoke with emphasis on the 2000-word hard cap. |
 | **Completeness** | All required output sections present | Re-invoke with clarification |
 | **Format** | Output matches specified OUTPUT FORMAT | Re-invoke with format emphasis |
 | **Confidence** | No LOW confidence items without resolution | Request resolution or escalate |
 | **Substantive** | Real findings, not template placeholders | Re-invoke with thoroughness emphasis |
+| **Persistence** | Preliminary notes file written to disk (notes-producing agents only: search-agent Stage 2, source-researcher Stage 3, research-synthesizer Stage 3.5) | Retry write; if retry fails, stop and report to user |
 
 **Verification Procedure:**
 
@@ -1083,7 +1084,7 @@ Closely read `{BASE_DIR}/agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for the
 
 ## OUTPUT FORMAT
 
-**Hard cap: 1000 words maximum.** The orchestrator has limited context — every word you return consumes shared capacity across the entire pipeline. Your Agent output is a *signal to the orchestrator*, not an archive. The script files on disk are the archive.
+**Hard cap: 2000 words maximum.** The orchestrator has limited context — every word you return consumes shared capacity across the entire pipeline. Your Agent output is a *signal to the orchestrator*, not an archive. The script files on disk are the archive.
 
 **Do NOT include in your output:**
 - Raw execution logs or captured stdout/stderr (already appended to the script file by `run_with_capture.sh`)
@@ -1361,33 +1362,14 @@ Addressed when: {verification_condition}
 **PRIOR QA FINDINGS (if any):**
 {accumulated_warnings_from_prior_scripts}
 
-**OUTPUT FORMAT (1000-word hard cap):**
-Return findings in this structure. Do NOT paste QA script code, raw execution logs, or data samples — reference cr/ script paths instead.
-
-### QA Review: {task_name}
-
-**QA Status:** [PASSED | ISSUES_FOUND]
-**Severity:** [BLOCKER | WARNING | INFO | None]
-**Script Reviewed:** scripts/stage{N}_{type}/{step}_{task-name}.py
-**QA Scripts Created:** scripts/cr/stage{N}_{step}_cr1.py [+ cr2..cr5 if created]
-
-**Code Review:**
-| Check | Status | Notes |
-|-------|--------|-------|
-| Operations match intent | PASS/FAIL | [1 sentence] |
-| Methodology alignment | PASS/FAIL | [1 sentence] |
-| Validation robustness | PASS/FAIL | [1 sentence] |
-
-**QA Script Results:**
-[1-2 sentence summary per cr script — PASSED/FAILED + key finding. Do NOT paste raw output.]
-
-**Issues Found:**
-- BLOCKER: [list or "None"]
-- WARNING: [list or "None"]
-- INFO: [list or "None"]
+**OUTPUT FORMAT:**
+Return findings using the Code Reviewer Output Format
+(see your agent protocol, § Output Format).
 
-**Recommendation:** [PROCEED | REVISION_REQUIRED | ESCALATE]
-**If Revision:** [Specific changes needed]
+**Emphasis for this invocation:**
+- Code correctness and execution success
+- Methodology alignment with Plan specifications
+- IAT documentation completeness
 """,
     subagent_type: "code-reviewer"
 })
diff --git a/.claude/skills/daaf-orchestrator/references/reproducibility-verification-mode.md b/.claude/skills/daaf-orchestrator/references/reproducibility-verification-mode.md
index 1053bf2..e67e7d8 100644
--- a/.claude/skills/daaf-orchestrator/references/reproducibility-verification-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/reproducibility-verification-mode.md
@@ -126,8 +126,8 @@ User points to existing analysis folder
 1. User provides path to existing analysis folder
 2. Validate that the folder contains both a Report (`*_Report.md`) and a Notebook (`*.py` with `import marimo`)
 3. Create new project folder: `research/YYYY-MM-DD_[OriginalProjectName]_Reproduction/`
-4. Create subdirectories: `original_files/`, `original_files/scripts/`, `original_files/output/figures/`, `scripts/`, `scripts/repro/`, `output/figures/`
-5. Copy the Report and Notebook into `original_files/`. Copy `output/figures/` from the original project into `original_files/output/figures/` (these are the original figures needed for visual comparison during RV-2 and RV-3).
+4. Create subdirectories: `original_files/`, `original_files/scripts/`, `original_files/output/figures/`, `scripts/`, `scripts/repro/`, `output/figures/`, `output/preliminary_notes/`
+5. Copy the Report and Notebook into `original_files/`. Copy `output/figures/` from the original project into `original_files/output/figures/` (these are the original figures needed for visual comparison during RV-2 and RV-3). If `output/preliminary_notes/` exists in the original project, copy it into `original_files/output/preliminary_notes/` (these provide discovery-phase context for understanding analytical decisions).
 6. Run the decompiler: `python /daaf/scripts/decompile_notebook.py <notebook_path> <project>/original_files/scripts/`
 7. **Path normalization** — run the batch normalizer on all decompiled scripts:
    `python /daaf/scripts/normalize_project_dir.py <project>/original_files/scripts/ <project_absolute_path>`
@@ -199,6 +199,7 @@ All project-relative paths resolve from PROJECT_DIR. All repo-level paths resolv
 **ORIGINAL SCRIPT:** `{PROJECT_DIR}/original_files/scripts/{stage_dir}/{script_name}`
 **REPRODUCTION TARGET:** `{PROJECT_DIR}/scripts/repro/{stage_dir}/{script_name}`
 **ORIGINAL FIGURES:** `{PROJECT_DIR}/original_files/output/figures/` (copied from original project during RV-1)
+**ORIGINAL PRELIMINARY NOTES:** `{PROJECT_DIR}/original_files/output/preliminary_notes/` (if present — discovery-phase findings from original analysis)
 
 **INSTRUCTIONS:**
 1. Copy the original script to the reproduction target path
@@ -219,6 +220,10 @@ All project-relative paths resolve from PROJECT_DIR. All repo-level paths resolv
 5. Classify result: REPRODUCED / DIVERGED / FAILED. If a modified script also produces
    divergent output, classify as MODIFIED (document divergence in Deviations section).
 6. Methodological review depth: {LIGHT | FULL}
+   If original preliminary notes exist, consult them for discovery-phase context
+   (source caveats, coded value definitions, analytical rationale) when assessing
+   methodological concerns. These notes document why certain analytical decisions
+   were made in the original analysis.
 7. Update `{PROJECT_DIR}/Reproduction_Report.md`:
    - Script Inventory table: update Repro Status for script #{N}
    - Per-Script Reproduction Results: fill in section for Script #{N}
@@ -239,7 +244,7 @@ NOT substantive modifications — do NOT count them as modifications or deviatio
 - Re-execute the modified version
 - Mark status as MODIFIED, not REPRODUCED
 
-**OUTPUT FORMAT (1000-word hard cap):**
+**OUTPUT FORMAT (2000-word hard cap):**
 Return a concise summary:
 - Status: [REPRODUCED/DIVERGED/FAILED/MODIFIED]
 - Key comparison metrics (row counts, checkpoint results)
@@ -258,11 +263,13 @@ Return a concise summary:
 
 **Note:** The data-verifier agent is read-only (`permissionMode: plan`). It RETURNS its findings to the orchestrator, which then updates the Reproduction Report. This is consistent with how data-verifier operates at Stage 12 in Full Pipeline — it verifies and reports, never writes.
 
-**Orchestrator post-processing:** After receiving the data-verifier's return, the orchestrator updates:
-- Report Verification § Quantitative Claims table
-- Report Verification § Figure Verification table
-- Report Verification § Findings Verification table
-- Report Verification § Summary
+**Orchestrator post-processing:** After receiving the data-verifier's return, the orchestrator:
+1. **[PERSIST]** Writes the full, unmodified data-verifier return to `output/preliminary_notes/{date}_rv3_report-verification.md` with provenance header (per orchestrator SKILL.md § Subagent Return Processing). This preserves the raw verification findings as an audit record and allows the RV-4 report-writer to reference full-fidelity findings rather than depending solely on the orchestrator's transcription.
+2. Updates the Reproduction Report:
+   - Report Verification § Quantitative Claims table
+   - Report Verification § Figure Verification table
+   - Report Verification § Findings Verification table
+   - Report Verification § Summary
 
 **Invocation pattern:**
 
@@ -290,21 +297,27 @@ All project-relative paths resolve from PROJECT_DIR. All repo-level paths resolv
 **REPRODUCED SCRIPTS:** `{PROJECT_DIR}/scripts/repro/`
 **REPRODUCED FIGURES:** `{PROJECT_DIR}/output/figures/`
 **REPRODUCTION REPORT:** `{PROJECT_DIR}/Reproduction_Report.md`
+**ORIGINAL PRELIMINARY NOTES:** `{PROJECT_DIR}/original_files/output/preliminary_notes/` (if present — discovery-phase findings from original analysis)
 
 **INSTRUCTIONS:**
 1. Read the original Report in full
-2. Extract every quantitative claim (statistics, counts, percentages, coefficients)
-3. Extract every figure reference
-4. For each claim: locate the reproduced script that produced it, check the
+2. If original preliminary notes exist, read them for discovery-phase context —
+   source caveats, coded value definitions, data limitations, and analytical
+   rationale documented during the original analysis. These inform whether Report
+   claims properly reflect the constraints discovered during data exploration.
+3. Extract every quantitative claim (statistics, counts, percentages, coefficients)
+4. Extract every figure reference
+5. For each claim: locate the reproduced script that produced it, check the
    reproduced execution log for the matching value
-5. For each figure: verify the reproducing script generated the figure file.
+6. For each figure: verify the reproducing script generated the figure file.
    Use the **Read tool** to view both the original figure and the reproduced figure
    for visual comparison against Report claims. Minor rendering differences
    (anti-aliasing, font rendering) are expected and do not constitute divergence.
-6. For each key finding: assess whether the reproduced data supports the
-   same conclusion
+7. For each key finding: assess whether the reproduced data supports the
+   same conclusion. If preliminary notes documented caveats or limitations
+   relevant to a finding, verify the Report acknowledged them appropriately.
 
-**OUTPUT FORMAT (1000-word hard cap):**
+**OUTPUT FORMAT (2000-word hard cap):**
 Return structured findings for orchestrator to populate the Reproduction Report:
 - Claims verified: N of N (N% match)
 - Figures reproduced: N of N
@@ -349,28 +362,33 @@ All project-relative paths resolve from PROJECT_DIR. All repo-level paths resolv
 **MODE:** Reproducibility Verification — RV-4 (Synthesis)
 
 **REPRODUCTION REPORT:** `{PROJECT_DIR}/Reproduction_Report.md`
+**RV-3 VERIFICATION FINDINGS:** `{PROJECT_DIR}/output/preliminary_notes/{date}_rv3_report-verification.md` (full-fidelity data-verifier return)
 
 **INSTRUCTIONS:**
 1. Read the entire Reproduction Report (all per-script results, deviations,
    methodological concerns, report verification findings)
-2. Write the Executive Summary section:
+2. Read the RV-3 verification findings preliminary notes for the full-fidelity
+   data-verifier return — this contains the raw per-claim, per-figure, and
+   per-finding detail that may be more granular than the Reproduction Report's
+   transcribed tables
+3. Write the Executive Summary section:
    - Overall reproducibility assessment
    - Script counts and percentages
    - 3-5 sentence summary of findings
    - 2-3 sentence summary of methodological concerns
-3. Write the Methodological Concerns § Synthesis section:
+4. Write the Methodological Concerns § Synthesis section:
    - Group related concerns
    - Assess collective impact on conclusions
    - Provide overall methodological assessment
-4. Ensure the Report Verification Summary narrative is complete
-5. Determine overall assessment: FULLY REPRODUCED / PARTIALLY REPRODUCED / NOT REPRODUCED
+5. Ensure the Report Verification Summary narrative is complete
+6. Determine overall assessment: FULLY REPRODUCED / PARTIALLY REPRODUCED / NOT REPRODUCED
 
 **ASSESSMENT CRITERIA:**
 - FULLY REPRODUCED: All scripts reproduced or diverged only cosmetically; all Report claims verified; no modifications required
 - PARTIALLY REPRODUCED: Most scripts reproduced; some substantive deviations or modifications; most Report claims verified
 - NOT REPRODUCED: Multiple scripts failed or required modifications; key Report claims cannot be verified
 
-**OUTPUT FORMAT (1000-word hard cap):**
+**OUTPUT FORMAT (2000-word hard cap):**
 Return the overall assessment and a 3-sentence summary of the reproduction findings.
 ```
 
@@ -385,8 +403,9 @@ research/YYYY-MM-DD_[OriginalProject]_Reproduction/
 │   ├── [original_report].md            # Copied from original project
 │   ├── [original_notebook].py          # Copied from original project
 │   ├── output/                         # Copied from original project
-│   │   └── figures/                    # Original figures for visual comparison
-│   │       └── *.png
+│   │   ├── figures/                    # Original figures for visual comparison
+│   │   │   └── *.png
+│   │   └── preliminary_notes/          # Discovery-phase findings (if present)
 │   └── scripts/                        # Decompiled from notebook
 │       ├── MANIFEST.md                 # Decompiler output manifest
 │       ├── stage5_fetch/
@@ -395,9 +414,11 @@ research/YYYY-MM-DD_[OriginalProject]_Reproduction/
 │       ├── stage6_clean/
 │       ├── stage7_transform/
 │       └── stage8_analysis/
-├── output/                             # Reproduced output (generated during RV-2)
-│   └── figures/
-│       └── *.png
+├── output/                             # Reproduced output (generated during RV-2/RV-3)
+│   ├── figures/
+│   │   └── *.png
+│   └── preliminary_notes/              # Lossless agent returns persisted by orchestrator
+│       └── {date}_rv3_report-verification.md
 └── scripts/
     └── repro/                          # Re-executed scripts
         ├── stage5_fetch/
@@ -538,6 +559,10 @@ Present to the user after RV-4 completes:
 The full Reproduction Report is at: `[path]`
 Session logs collected in: `[project_dir]/logs/`
 
+**Explore Session Logs:**
+To browse the session timeline interactively in your browser, run in the Docker terminal:
+`bash /daaf/scripts/generate_log_viewer.sh [project_dir]`
+
 **What would you like to do?**
 - Review the Reproduction Report in detail
 - Discuss specific deviations or concerns
diff --git a/.claude/skills/daaf-orchestrator/references/user-support-mode.md b/.claude/skills/daaf-orchestrator/references/user-support-mode.md
index 8005620..9be84c0 100644
--- a/.claude/skills/daaf-orchestrator/references/user-support-mode.md
+++ b/.claude/skills/daaf-orchestrator/references/user-support-mode.md
@@ -145,6 +145,104 @@ Users frequently have questions about the tools DAAF runs on, not just DAAF itse
 
 ---
 
+## Update Conflict Resolution Walkthrough
+
+When a user enters Claude Code with a prompt starting with "User support mode" and
+mentioning DAAF update conflicts, this is a structured handoff from the
+`update_daaf` script. The update script launched Claude Code via
+`docker compose exec -it` and is waiting for the user to type `/exit` so the
+script can complete its remaining post-update steps.
+
+### Conflict types
+
+The user's prompt will indicate one of three conflict types. The resolution
+walkthrough (steps 1–5 below) is the same for all three — only the completion
+command in step 4 differs.
+
+| Prompt mentions | What happened | Completion command (step 4) |
+|-----------------|---------------|---------------------------|
+| "merge conflicts" | User chose merge; upstream and local commits changed the same files | `git commit -m "Resolved merge conflicts from DAAF update"` |
+| "rebase conflicts" | User chose rebase; the squashed local commit conflicts with upstream | `git rebase --continue` |
+| "stash conflicts" | The merge/rebase succeeded, but the user's uncommitted edits (temporarily set aside) conflict with the updated files when re-applied | `git stash drop` (the stash contents are already in the working tree) |
+
+### What the orchestrator must do
+
+**1. Classify as User Support mode** — the "User support mode" prefix is an
+explicit mode signal. Skip the mode confirmation gate — the user already
+confirmed by choosing option 1 in the update script.
+
+**2. Determine the conflict type** — check the user's prompt for "merge",
+"rebase", or "stash". Then identify the conflicting files:
+`git diff --name-only --diff-filter=U`. Read each one to understand both sides.
+
+**3. Walk the user through resolution interactively** — for each file:
+- Explain what the local side is (the user's customization) and what the
+  upstream side is (the DAAF update)
+- Recommend which version to keep, or how to merge both intelligently
+- **Do not resolve or edit any file without the user's explicit approval.** Present the
+  proposed resolutions file-by-file and wait for confirmation for each individual case before making changes.
+- After the user approves a given resolution, edit the file to remove all conflict
+  markers (`<<<<<<<`, `=======`, `>>>>>>>`) and run `git add <file>`
+- **Watch for escalation signals** — see "Escalation to Framework Development"
+  below. If you detect them, flag the situation before continuing with
+  mechanical resolution.
+
+**4. Complete the git operation** — after all files are resolved, run the
+completion command from the table above based on the conflict type. Verify with
+`git status` that the working tree is clean (no unmerged files, no in-progress
+merge/rebase).
+
+**5. Instruct the user to return to the updater** — the update script is still
+running on the host. When the user types `/exit`, control returns to the script,
+which then syncs updated utility scripts to the host and checks whether a Docker
+rebuild is needed. If the user closes the terminal instead, those housekeeping
+steps are skipped. Tell the user:
+
+> "Great, all conflicts are resolved and committed. Type `/exit` now to return to the
+> update script so it can finish up."
+
+### Escalation to Framework Development
+
+Sometimes update conflicts are symptoms of a deeper integration problem. Resolving
+the conflict markers gets the git state clean, but the user's customization may
+not actually *work* with the updated framework. Watch for these signals during
+step 3:
+
+**Escalation signals:**
+
+| Signal | What It Suggests |
+|--------|-----------------|
+| Conflicts in an agent, mode, or skill file where the upstream side restructured sections, renamed fields, or changed the template format | The customization needs architectural re-integration, not just a merge fix |
+| User's custom component references registration points (tables, escalation paths, loading trees) that moved or changed structure upstream | Cross-file wiring is broken — resolving one file won't fix the integration |
+| Multiple interconnected files conflict (e.g., a custom mode's reference file + its entries in the orchestrator skill + BOUNDARIES.md) | The customization is a multi-component modification that needs systematic re-integration |
+| After resolving conflict markers, the merged result contains contradictions (e.g., a section references a field that no longer exists, or a table row doesn't match the new column structure) | Mechanical merge produced a syntactically clean but semantically broken artifact |
+| User asks "how do I make my customization work with this new version?" or "will my changes still work?" | The user recognizes the problem goes beyond conflict markers |
+
+**When signals are detected:**
+
+1. **Finish the git operation first.** The update script is waiting, so the
+   working tree must reach a clean state. Resolve conflict markers to the best
+   reasonable approximation (favor upstream for structural changes, preserve the
+   user's *intent* in comments if needed). Complete the merge/rebase/stash-drop.
+2. **Tell the user what you observed.** Be specific about which files have
+   deeper integration issues and why mechanical resolution isn't sufficient.
+3. **Propose the escalation:**
+
+> "The conflicts are resolved and your git state is clean, so you're safe to
+> `/exit` and let the update script finish. But I noticed that your
+> [customization description] may need more than a merge fix to work with the
+> updated framework — [brief explanation of what changed upstream]. After the
+> update finishes, you can start a new session and ask me to help with that in
+> Framework Development mode. I'd scope what changed, check how your
+> customization connects, and re-integrate it properly."
+
+4. **Do not attempt Framework Development work in this session.** The update
+   script is still running on the host and waiting for `/exit`. Framework
+   Development requires a normal session with full scoping and checkpoints.
+   The user should `/exit` to complete the update, then start a new session.
+
+---
+
 ## Subagent Invocation
 
 User Support mode does **not** dispatch subagents under normal operation. The orchestrator handles all questions directly using pre-loaded documentation and on-demand reference reads.
@@ -169,7 +267,7 @@ User Support produces no formal deliverables. All output is conversational.
 
 **Tone:** Warm, patient, and educational. Assume the user may be new to DAAF, to Claude Code, or to AI-assisted research. Explain concepts without condescension. Use concrete examples. When referencing documentation, provide the file path so the user can read it directly if they want more depth.
 
-**Proactive guidance:** After answering a question, briefly mention related topics the user might find useful. For example, after explaining modes: "If you'd like to see what a completed analysis looks like, I can walk you through the example project structure too."
+**Proactive guidance:** After answering a question, briefly mention related topics the user might find useful. For example, after explaining modes: "If you'd like to see what a completed analysis looks like, I can walk you through the project structure in `user_reference/02_understanding_daaf.md`."
 
 ---
 
@@ -222,5 +320,6 @@ User Support is a natural entry point that routes to other modes once the user u
 | User wants to modify an existing analysis | Revision and Extension | "That's a revision of existing work. Want me to switch to Revision and Extension mode?" |
 | User wants to verify an analysis reproduces | Reproducibility Verification | "I can re-run that analysis to check. Want me to switch to Reproducibility Verification mode?" |
 | User wants to modify DAAF itself | Framework Development | "That's framework development work. Want me to switch to Framework Development mode?" |
+| Update conflict resolution reveals customizations that need architectural re-integration beyond merge fixes | Framework Development | Follow the "Escalation to Framework Development" procedure above. User-facing message: "The conflicts are resolved, but your [customization] may need deeper re-integration with the updated framework. After you `/exit` and the update finishes, start a new session and ask me to help in Framework Development mode." |
 
 **Routing, not gatekeeping:** The goal of User Support is to help users understand DAAF well enough to use it confidently. When a user's questions naturally evolve into wanting to *do* something, facilitate the transition warmly. Never make the user feel like they need to "graduate" from User Support before they can use other modes.
diff --git a/.claude/skills/data-scientist/SKILL.md b/.claude/skills/data-scientist/SKILL.md
index 9db3900..9375033 100644
--- a/.claude/skills/data-scientist/SKILL.md
+++ b/.claude/skills/data-scientist/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: data-scientist
 description: >-
-  Data science methodology for Python research: EDA, validation, causal inference (IV, DiD, RD, synthetic control), clustering/PCA/UMAP, supervised ML, geospatial, visualization. Method selection guidance. For syntax, load tool-specific skills.
+  Data science methodology and method-selection routing for quantitative research. Covers EDA, data validation, descriptive analysis, causal inference (IV, DiD, RD, synthetic control), clustering/PCA/UMAP, supervised ML, geospatial analysis, and visualization design. Contains the canonical method-to-library routing tree: statsmodels (OLS/GLM/time series), pyfixest (FE/DiD), linearmodels (RE/GMM/SUR), svy (complex surveys), scikit-learn (clustering/prediction ML), geopandas (spatial). For implementation syntax, load the routed tool-specific skill.
 metadata:
   audience: any-agent
   domain: research-methodology
diff --git a/.claude/skills/education-data-context/SKILL.md b/.claude/skills/education-data-context/SKILL.md
index 942a86c..de17baf 100644
--- a/.claude/skills/education-data-context/SKILL.md
+++ b/.claude/skills/education-data-context/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: education-data-context
 description: >-
-  Interpretation guidance for Urban Institute Portal datasets. Coded values (-1/-2/-3), year definitions, grade encoding, suppression, licensing, cross-source joins. Use when interpreting Portal data before analysis. Routes to source-specific skills.
+  Interpretation guidance for Urban Institute Education Data Portal datasets. The Portal is a curation layer over federal data: lowercase variable names, integer-encoded categoricals, standardized missing codes (-1 missing, -2 not applicable, -3 suppressed). Covers year definitions, grade encoding (grade=-1 is Pre-K, not missing), suppression rates, ODC-By licensing, and cross-source join identifiers. Load before analyzing any Portal data. Routes to source-specific deep-dive skills for individual datasets.
 metadata:
   audience: any-agent
   domain: data-documentation
diff --git a/.claude/skills/education-data-source-nhgis/SKILL.md b/.claude/skills/education-data-source-nhgis/SKILL.md
index accc42d..d648397 100644
--- a/.claude/skills/education-data-source-nhgis/SKILL.md
+++ b/.claude/skills/education-data-source-nhgis/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: education-data-source-nhgis
 description: >-
-  NHGIS — census geography crosswalks via Portal: links schools (ncessch) and colleges (unitid) to tracts, block groups, CBSAs (1990-2020). Census demographics NOT in Portal — access NHGIS directly. Use for linking education data to census geography.
+  NHGIS — census geography crosswalks via Portal: links schools (ncessch) and colleges (unitid) to census tracts, block groups, CBSAs, and regions (1990-2020). Portal provides geography linkage tables ONLY — census demographic variables (population, income, poverty, race, educational attainment) are NOT available through the Portal and must be accessed directly from NHGIS (free IPUMS registration required). Use for linking education or institutional data to census geography for contextual analysis.
 metadata:
   audience: any-agent
   domain: data-source
diff --git a/.claude/skills/election-data-source-countypres/SKILL.md b/.claude/skills/election-data-source-countypres/SKILL.md
index 1e88c23..3c4aa1e 100644
--- a/.claude/skills/election-data-source-countypres/SKILL.md
+++ b/.claude/skills/election-data-source-countypres/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: election-data-source-countypres
 description: >-
-  County Presidential Returns 2000-2024 (MIT MEDSL). Vote shares, party trends, turnout by county_fips (joins census/education data). Requires HARVARD_DATAVERSE_API_KEY. Critical: mode='TOTAL' drops ~1K counties post-2020 — use 3-pattern reconstruction
+  County Presidential Returns 2000-2024 (MIT MEDSL). Vote shares, party trends, turnout by county_fips (joins census/education data). Requires HARVARD_DATAVERSE_API_KEY set via environment_settings.txt. Critical: naive mode='TOTAL' filtering silently drops ~1,000 counties in post-2020 data where states report by vote mode (absentee, election-day, provisional) instead of totals — use 3-pattern reconstruction (TOTAL-present rows kept, breakdown-only counties summed across modes, empty-string mode rows reclassified). Categorical variables use uppercase strings, not Portal integer codes.
 metadata:
   audience: any-agent
   domain: data-source
@@ -38,12 +38,13 @@ The authoritative source for county-level U.S. presidential election returns spa
 > 1. Create a free Harvard Dataverse account at https://dataverse.harvard.edu/
 > 2. Log in, navigate to your account name (top-right) → API Token
 > 3. Click "Create Token" and copy it
-> 4. Set the environment variable **before launching Claude Code**:
+> 4. Add it to the `environment_settings.txt` file in your `daaf-docker/` folder on the host machine:
 >    ```bash
->    export HARVARD_DATAVERSE_API_KEY="your_token_here"
+>    HARVARD_DATAVERSE_API_KEY=your_token_here
 >    ```
->    For Docker users: run this inside the container after `docker compose exec daaf-docker bash`
->    but before `claude`. To make it persistent across sessions, add it to `~/.bashrc`.
+>    If you don't have an `environment_settings.txt` file yet, copy the template: `cp environment_settings_example.txt environment_settings.txt`
+>    (or `Copy-Item environment_settings_example.txt environment_settings.txt` on Windows). Then recreate the container: `docker compose down` followed by `run_daaf`.
+>    Alternatively, set it manually inside the container: `export HARVARD_DATAVERSE_API_KEY="your_token_here"`
 >
 > **If the key is missing**, any fetch script will fail with a `KeyError: 'HARVARD_DATAVERSE_API_KEY'`.
 > The orchestrator should check for this variable's existence before dispatching Stage 5 fetch tasks
diff --git a/.claude/skills/marimo/SKILL.md b/.claude/skills/marimo/SKILL.md
index eb3cf83..646fb8b 100644
--- a/.claude/skills/marimo/SKILL.md
+++ b/.claude/skills/marimo/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: marimo
 description: >-
-  Reactive Python notebook system. Cell reactivity, UI elements (sliders, dropdowns, tables), SQL cells, plotting, app deployment. Use when assembling Stage 9 notebooks, building data apps, or converting Jupyter to marimo .py format.
+  Reactive Python notebook system with cell reactivity, UI elements, SQL cells, plotting, and app deployment. DAAF's standard notebook format — stored as Git-friendly .py files, not .ipynb. For DAAF pipelines: Stage 9 notebooks compile existing executed scripts into cells verbatim as audit artifacts — no new analysis code or interactive widgets. Use when assembling Stage 9 research notebooks, building standalone interactive data apps, or converting Jupyter notebooks to marimo format.
 metadata:
   audience: research-coders
   domain: python-library
diff --git a/.claude/skills/polars/SKILL.md b/.claude/skills/polars/SKILL.md
index 2a730f3..acf8b8c 100644
--- a/.claude/skills/polars/SKILL.md
+++ b/.claude/skills/polars/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: polars
 description: >-
-  Polars DataFrame library for high-performance data manipulation. Lazy/eager execution, expressions, I/O (CSV, Parquet, JSON), aggregations, joins, string/datetime ops, pandas interop. Use for Polars DataFrames or reading/writing Parquet files.
+  High-performance data manipulation with lazy/eager execution, expressions, I/O (CSV, Parquet, JSON), aggregations, joins, string/datetime ops, and pandas interop. Covers performance optimization patterns and common anti-patterns. DAAF's default DataFrame library — all pipeline code uses Polars, not pandas. Use for any DataFrame operation, reading/writing Parquet files, or migrating existing pandas code to Polars.
 metadata:
   audience: research-coders
   domain: python-library
diff --git a/.claude/skills/shell-scripting/SKILL.md b/.claude/skills/shell-scripting/SKILL.md
new file mode 100644
index 0000000..a60dec9
--- /dev/null
+++ b/.claude/skills/shell-scripting/SKILL.md
@@ -0,0 +1,206 @@
+---
+name: shell-scripting
+description: >-
+  Standards for Bash and PowerShell scripts in DAAF: preambles, quoting, error handling, cleanup, testing. Use when writing or reviewing .sh/.ps1 files (hooks, lifecycle, utilities). Not runtime safety — that is bash-safety.sh hook.
+metadata:
+  audience: any-agent
+  domain: scripting-standards
+---
+
+# Shell Scripting Standards
+
+Coding quality standards and best practices for all `.sh` (Bash) and `.ps1` (PowerShell) scripts within DAAF. Covers preamble conventions, quoting discipline, error handling philosophy, signal/cleanup patterns, Docker interaction, output formatting, testing strategies, and cross-platform gotchas. Use when authoring new shell scripts (hooks, Docker lifecycle, utilities), reviewing existing scripts for compliance, debugging script failures, or setting up CI for shell code.
+
+**Boundary with `bash-safety.sh`:** This skill governs *how to write good scripts* (coding quality). The `bash-safety.sh` hook governs *what commands are safe to run* (runtime safety enforcement). A script can follow every standard in this skill and still be blocked by `bash-safety.sh` if it contains a dangerous command like `rm -rf /`. Conversely, a script that passes `bash-safety.sh` may still be poorly written if it ignores these standards.
+
+## How to Use This Skill
+
+### Reference File Structure
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `bash-standards.md` | Preambles, quoting, variables, ShellCheck, signal handling | Writing or reviewing any `.sh` file |
+| `powershell-standards.md` | Preambles, dual error system, defensive coding, PSScriptAnalyzer | Writing or reviewing any `.ps1` file |
+| `error-handling.md` | Fail-closed philosophy, output conventions, exit codes, Docker errors, dependency validation | Designing error paths for any script |
+| `testing.md` | BATS, Pester, CI workflows, Docker mocking, test taxonomy | Setting up or running script tests |
+| `gotchas.md` | Bash traps, PowerShell surprises, cross-platform pitfalls | Debugging unexpected script behavior |
+
+### Reading Order
+
+1. **Writing a Bash script?** Start with `bash-standards.md`, then `error-handling.md`
+2. **Writing a PowerShell script?** Start with `powershell-standards.md`, then `error-handling.md`
+3. **Setting up tests?** Read `testing.md`
+4. **Script behaving unexpectedly?** Go straight to `gotchas.md`
+5. **Reviewing a script?** Skim `bash-standards.md` or `powershell-standards.md` for the compliance checklist, then `error-handling.md` for error-path quality
+
+## Quick Decision Trees
+
+### "I need to write a script"
+
+```
+What kind of script?
+├─ Bash (.sh)
+│   ├─ Preamble and structure → ./references/bash-standards.md
+│   ├─ Error handling design → ./references/error-handling.md
+│   └─ Signal handling / cleanup → ./references/bash-standards.md
+├─ PowerShell (.ps1)
+│   ├─ Preamble and structure → ./references/powershell-standards.md
+│   ├─ Native command error handling → ./references/powershell-standards.md
+│   └─ Error handling design → ./references/error-handling.md
+└─ Either language
+    ├─ Docker interaction → ./references/error-handling.md
+    ├─ User-facing output → ./references/error-handling.md
+    └─ Cross-platform concerns → ./references/gotchas.md
+```
+
+### "I need to review a script"
+
+```
+Reviewing a script?
+├─ Bash compliance check
+│   ├─ Preamble correct? → ./references/bash-standards.md
+│   ├─ Quoting discipline? → ./references/bash-standards.md
+│   ├─ ShellCheck clean? → ./references/bash-standards.md
+│   └─ Error paths robust? → ./references/error-handling.md
+├─ PowerShell compliance check
+│   ├─ Preamble correct? → ./references/powershell-standards.md
+│   ├─ Native command handling? → ./references/powershell-standards.md
+│   ├─ PSScriptAnalyzer clean? → ./references/powershell-standards.md
+│   └─ Error paths robust? → ./references/error-handling.md
+└─ Either language
+    ├─ Exit code conventions? → ./references/error-handling.md
+    └─ Known gotchas present? → ./references/gotchas.md
+```
+
+### "Something is broken"
+
+```
+Script behaving unexpectedly?
+├─ Bash
+│   ├─ Exit code masked → ./references/gotchas.md (local var=$(cmd))
+│   ├─ Variable empty/unset → ./references/bash-standards.md (nounset)
+│   ├─ Pipeline hiding failure → ./references/bash-standards.md (pipefail)
+│   └─ cd went to wrong dir → ./references/gotchas.md (cd without || exit)
+├─ PowerShell
+│   ├─ Native command error ignored → ./references/gotchas.md ($LASTEXITCODE)
+│   ├─ Unexpected return value → ./references/gotchas.md (implicit returns)
+│   ├─ $null in ForEach loop → ./references/gotchas.md
+│   ├─ Validation not firing → ./references/gotchas.md (omitted params)
+│   └─ irm | iex fails with BOM error → ./references/gotchas.md (UTF-8 BOM)
+└─ Cross-platform
+    ├─ Env var case mismatch → ./references/gotchas.md
+    ├─ Aliases missing → ./references/gotchas.md
+    └─ Exit code truncated → ./references/gotchas.md
+```
+
+### "I need to set up tests"
+
+```
+Testing shell scripts?
+├─ Bash testing
+│   ├─ BATS setup → ./references/testing.md
+│   ├─ Mocking Docker → ./references/testing.md
+│   └─ What to test → ./references/testing.md
+├─ PowerShell testing
+│   ├─ Pester setup → ./references/testing.md
+│   ├─ Mocking native commands → ./references/testing.md
+│   └─ What to test → ./references/testing.md
+└─ CI integration
+    ├─ GitHub Actions matrix → ./references/testing.md
+    ├─ Lint-only vs full test → ./references/testing.md
+    └─ Path filtering → ./references/testing.md
+```
+
+## DAAF Script Conventions (Quick Reference)
+
+Existing patterns in DAAF scripts that this skill codifies:
+
+| Convention | Description | Example |
+|------------|-------------|---------|
+| Strict preamble | `set -euo pipefail` (Bash) / `$ErrorActionPreference = 'Stop'` (PS) | Every script, first lines |
+| Numbered progress | `[1/4] Checking prerequisites...` | All multi-step scripts |
+| `DAAF_NESTED` flag | Suppress pause-before-exit when scripts compose | `[ "${DAAF_NESTED:-}" = "1" ] && exit $ec` |
+| ERR trap pattern | Catch unexpected failures, explain recovery | `trap 'echo "ERROR: ..."; exit 1' ERR` |
+| Preflight checks | Validate all dependencies before any mutation | `command -v docker` before Docker ops |
+| Idempotent design | Check for prior state before acting | `[ -f "$BACKUP" ] && echo "Already backed up"` |
+| Fail-closed hooks | Security hooks block on uncertainty | `trap ... ERR; exit 2` |
+| Backup before destroy | Copy before overwriting | `cp -r "$TARGET" "$TARGET.bak"` |
+
+## Bash Compliance Checklist (Summary)
+
+| # | Requirement | Quick Check |
+|---|-------------|-------------|
+| 1 | `#!/usr/bin/env bash` shebang | First line |
+| 2 | `set -euo pipefail` | Second line |
+| 3 | All variables quoted | `"$var"`, `"$(cmd)"` |
+| 4 | `local` separate from `$(cmd)` | `local x; x=$(cmd)` |
+| 5 | No `eval`, no backticks | Grep for both |
+| 6 | `trap cleanup EXIT` for temp files | After variable declarations |
+| 7 | ShellCheck clean | `shellcheck -x -S warning` |
+| 8 | Errors to stderr with action guidance | `echo "ERROR: ..." >&2` |
+
+## PowerShell Compliance Checklist (Summary)
+
+| # | Requirement | Quick Check |
+|---|-------------|-------------|
+| 1 | `$ErrorActionPreference = 'Stop'` | First line |
+| 2 | `Set-StrictMode -Version 3.0` | Second line |
+| 3 | `$LASTEXITCODE` checked after every native command | After docker, git, etc. |
+| 4 | `[CmdletBinding()]` on functions | Function declarations |
+| 5 | `$null = expr` not `\| Out-Null` | Performance |
+| 6 | No reliance on `$?` for native commands | Grep for `$?` near docker/git |
+| 7 | PSScriptAnalyzer clean | `Invoke-ScriptAnalyzer` |
+| 8 | Errors via `Write-Error` with guidance | Error output |
+| 9 | ASCII-only content (no BOM) | `file script.ps1` reports "ASCII text" |
+| 10 | No interactive native commands in expression-context function calls | No `if (Fn)`, `$x = Fn` for functions with `docker exec`, `ssh`, etc. |
+
+## Exit Code Conventions
+
+| Code | Meaning | Used By |
+|------|---------|---------|
+| 0 | Success | All scripts |
+| 1 | General error | All scripts |
+| 2 | Blocked (hook convention) | `.claude/hooks/*.sh` |
+| 10-19 | Docker failures | Docker lifecycle scripts |
+| 20-29 | Configuration errors | Setup/config scripts |
+| 30-39 | Dependency errors | Preflight validation scripts |
+
+## Topic Index
+
+| Topic | Reference File |
+|-------|---------------|
+| Bash shebang and preamble | `./references/bash-standards.md` |
+| Bash quoting rules | `./references/bash-standards.md` |
+| Bash variable handling | `./references/bash-standards.md` |
+| ShellCheck integration | `./references/bash-standards.md` |
+| Bash signal handling and cleanup | `./references/bash-standards.md` |
+| Bash never-do list | `./references/bash-standards.md` |
+| PowerShell preamble | `./references/powershell-standards.md` |
+| PowerShell ASCII-only encoding | `./references/powershell-standards.md` |
+| PowerShell dual error system | `./references/powershell-standards.md` |
+| PowerShell defensive coding | `./references/powershell-standards.md` |
+| PowerShell output streams | `./references/powershell-standards.md` |
+| PSScriptAnalyzer | `./references/powershell-standards.md` |
+| Fail-closed principle | `./references/error-handling.md` |
+| User-facing output formatting | `./references/error-handling.md` |
+| Exit code conventions | `./references/error-handling.md` |
+| Docker error handling | `./references/error-handling.md` |
+| Dependency validation | `./references/error-handling.md` |
+| NO_COLOR and TTY detection | `./references/error-handling.md` |
+| BATS test framework | `./references/testing.md` |
+| Pester test framework | `./references/testing.md` |
+| CI workflow setup | `./references/testing.md` |
+| Docker mocking strategies | `./references/testing.md` |
+| Test taxonomy (lint/unit/smoke/integration) | `./references/testing.md` |
+| What to test and what to skip | `./references/testing.md` |
+| Bash exit code masking | `./references/gotchas.md` |
+| Bash set -e edge cases | `./references/gotchas.md` |
+| PowerShell `exit` in dot-sourced functions | `./references/gotchas.md` |
+| PowerShell $LASTEXITCODE vs $? | `./references/gotchas.md` |
+| PowerShell UTF-8 BOM breaks iex | `./references/gotchas.md` |
+| PowerShell implicit returns | `./references/gotchas.md` |
+| PowerShell $null pipeline behavior | `./references/gotchas.md` |
+| Cross-platform env var casing | `./references/gotchas.md` |
+| Cross-platform alias differences | `./references/gotchas.md` |
+| Cross-platform exit code truncation | `./references/gotchas.md` |
+| Cross-platform path separators | `./references/gotchas.md` |
diff --git a/.claude/skills/shell-scripting/references/bash-standards.md b/.claude/skills/shell-scripting/references/bash-standards.md
new file mode 100644
index 0000000..32aed19
--- /dev/null
+++ b/.claude/skills/shell-scripting/references/bash-standards.md
@@ -0,0 +1,349 @@
+# Bash Standards
+
+Comprehensive standards for writing Bash scripts in DAAF. Covers preamble rules, quoting discipline, variable handling, ShellCheck integration, signal handling, and prohibited patterns.
+
+---
+
+## Preamble
+
+Every Bash script starts with exactly these two lines:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+```
+
+**What each flag does:**
+
+| Flag | Name | Behavior | Nuance |
+|------|------|----------|--------|
+| `-e` | errexit | Exit immediately on non-zero return | Commands in conditionals (`if cmd; then`) are automatically exempt |
+| `-u` | nounset | Exit on unbound (undeclared) variables | Use `${VAR:-default}` for intentionally optional variables |
+| `-o pipefail` | pipefail | Pipeline returns the exit code of the *last* failing command, not the last command | Without this, `failing_cmd \| grep foo` returns grep's exit code, hiding the failure |
+
+**When to add `set -E`:**
+
+Add `set -E` (errtrace) when using `trap ... ERR` inside functions or subshells. Without `-E`, ERR traps are not inherited by functions:
+
+```bash
+#!/usr/bin/env bash
+set -Eeuo pipefail
+trap 'echo "ERROR on line $LINENO" >&2; exit 1' ERR
+```
+
+**Exception — hooks that must inspect failures:**
+
+Hooks that need to examine a failure and decide whether to block or allow should not use `set -e`. Instead, use an explicit ERR trap with controlled exit codes:
+
+```bash
+#!/usr/bin/env bash
+set -uo pipefail
+# Deliberately omit -e: this hook inspects failures and decides exit code
+
+trap 'echo "ERROR: unexpected failure in hook" >&2; exit 2' ERR
+
+# ... inspection logic with explicit error handling ...
+```
+
+This pattern is used by `bash-safety.sh` and `enforce-file-first.sh` in DAAF.
+
+---
+
+## Quoting Discipline
+
+Unquoted variables are the single most common source of Bash bugs. The rule is simple: **quote everything.**
+
+### Always Quote
+
+```bash
+# Variables
+echo "$var"
+echo "${var}"
+
+# Command substitutions
+result="$(some_command)"
+
+# Array expansion
+for item in "${array[@]}"; do
+
+# Paths with possible spaces
+cp "$source" "$destination"
+```
+
+### Use Braces for Adjacency
+
+```bash
+# Good: braces disambiguate where the variable name ends
+echo "${var}_suffix"
+echo "${filename}.bak"
+
+# Bad: shell tries to expand $var_suffix as one variable
+echo "$var_suffix"
+```
+
+### Glob Safety
+
+```bash
+# Good: ./ prefix prevents filenames starting with - from being parsed as options
+for f in ./*.txt; do
+
+# Bad: a file named -rf.txt would be interpreted as an option
+for f in *.txt; do
+```
+
+### Arrays for Command Arguments
+
+When building command-line arguments dynamically, use arrays instead of string concatenation:
+
+```bash
+# Good: each element is a separate argument, properly quoted
+local -a cmd_args=("--flag" "$value" "--output" "$outfile")
+my_command "${cmd_args[@]}"
+
+# Bad: word splitting and glob expansion can corrupt arguments
+cmd_args="--flag $value --output $outfile"
+my_command $cmd_args
+```
+
+### Separate Declaration from Assignment
+
+When using `local` with command substitution, separate the declaration from the assignment. The `local` builtin always returns 0, masking the exit code of the command substitution:
+
+```bash
+# Good: if cmd fails, set -e catches it
+local result
+result=$(some_command)
+
+# Bad: local masks the exit code — if some_command fails, $? is still 0
+local result=$(some_command)
+```
+
+This is ShellCheck SC2155 and one of the most insidious Bash bugs. See `gotchas.md` for details.
+
+---
+
+## Variable Handling
+
+### Readonly for Constants
+
+```bash
+readonly BASE_DIR="/daaf"
+readonly MAX_RETRIES=3
+```
+
+### Default Values
+
+```bash
+# Provide a default if unset (compatible with set -u)
+verbose="${VERBOSE:-0}"
+config_file="${CONFIG_FILE:-./config.yml}"
+
+# Provide a default if unset or empty
+output_dir="${OUTPUT_DIR:-.}"
+```
+
+### Parameter Validation
+
+```bash
+# Require a positional argument
+if [ $# -lt 1 ]; then
+    echo "Usage: $(basename "$0") <input-file>" >&2
+    exit 1
+fi
+
+input_file="$1"
+
+# Validate the argument
+if [ ! -f "$input_file" ]; then
+    echo "ERROR: File not found: $input_file" >&2
+    exit 1
+fi
+```
+
+---
+
+## Never Do
+
+These patterns are banned in DAAF scripts:
+
+| Pattern | Problem | Alternative |
+|---------|---------|-------------|
+| `eval "$cmd"` | Arbitrary code execution, injection attacks | Use arrays: `"${cmd[@]}"` |
+| `` `command` `` (backticks) | Cannot nest, harder to read | `$(command)` |
+| Parsing `ls` output | Breaks on spaces, newlines, special chars in filenames | `for f in ./*.ext` or `find ... -print0 \| xargs -0` |
+| `$*` when you mean `"$@"` | Joins all arguments into a single string | `"$@"` preserves individual arguments |
+| `[ $var = "value" ]` | Word splitting if var is empty or contains spaces | `[ "$var" = "value" ]` or `[[ $var = "value" ]]` |
+
+---
+
+## ShellCheck Integration
+
+[ShellCheck](https://www.shellcheck.net/) is the standard linter for Bash scripts.
+
+### Running ShellCheck
+
+```bash
+shellcheck -x -S warning script.sh
+```
+
+| Flag | Purpose |
+|------|---------|
+| `-x` | Follow `source`/`.` includes to check sourced files |
+| `-S warning` | Set minimum severity to warning (skip style/info) |
+
+### Top Findings to Watch
+
+| Code | Description | Fix |
+|------|-------------|-----|
+| SC2086 | Unquoted variable | Add double quotes: `"$var"` |
+| SC2046 | Unquoted command substitution | Add double quotes: `"$(cmd)"` |
+| SC2155 | `local var=$(cmd)` masks return code | Separate: `local var; var=$(cmd)` |
+| SC2164 | `cd` without `\|\| exit` | Add fallback: `cd "$dir" \|\| exit 1` |
+| SC2006 | Backtick command substitution | Use `$(...)` instead |
+
+### Suppressing Warnings
+
+Only suppress with an inline comment explaining why:
+
+```bash
+# shellcheck disable=SC2034 -- variable used by sourced script
+readonly MY_CONFIG="value"
+```
+
+Bare `# shellcheck disable=SCXXXX` without an explanation comment is not acceptable — the reasoning must be documented.
+
+---
+
+## Signal Handling and Cleanup
+
+### Basic Cleanup Pattern
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Variables ---
+TMPDIR=""
+
+# --- Cleanup (register immediately after variables) ---
+cleanup() {
+    rm -f "${TMPDIR:?}/"*  # -f makes it idempotent
+    rmdir "$TMPDIR" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+# --- Setup ---
+TMPDIR="$(mktemp -d)"
+
+# ... rest of script ...
+```
+
+**Key principles:**
+
+1. **Place `trap` immediately after variable declarations**, before any operations that create state needing cleanup
+2. **Use `trap ... EXIT`** — it fires on normal exit, errors (`set -e`), and most signals (SIGINT, SIGTERM)
+3. **Create temp files with `mktemp`**, then register for cleanup immediately
+4. **Make cleanup idempotent**: use `rm -f` (not `rm`), guard with `|| true` where needed
+5. **Use single quotes in trap string** to defer variable expansion:
+
+```bash
+# Good: $TMPFILE expands at trap execution time (uses current value)
+trap 'rm -f "$TMPFILE"' EXIT
+
+# Bad: $TMPFILE expands at trap definition time (may be empty)
+trap "rm -f $TMPFILE" EXIT
+```
+
+### ERR Trap for Diagnostics
+
+For scripts where you want to report the failing line on unexpected errors:
+
+```bash
+#!/usr/bin/env bash
+set -Eeuo pipefail
+
+trap 'echo "ERROR: Script failed at line $LINENO. Command: $BASH_COMMAND" >&2' ERR
+
+# ... script body ...
+```
+
+The `-E` flag ensures the ERR trap is inherited by functions and subshells.
+
+### Composable Scripts (DAAF_NESTED)
+
+When one script calls another, suppress interactive features (like pause-before-exit) in the inner script:
+
+```bash
+# In the outer script:
+export DAAF_NESTED=1
+bash ./inner_script.sh
+unset DAAF_NESTED
+
+# In the inner script:
+if [ "${DAAF_NESTED:-}" = "1" ]; then
+    exit "$exit_code"
+fi
+# ... interactive pause logic ...
+```
+
+---
+
+## Script Structure
+
+Organize scripts with clear section headers:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# --- Config ---
+readonly BASE_DIR="/daaf"
+readonly MAX_RETRIES=3
+
+# --- Functions ---
+# (Keep minimal — prefer inline logic for simple scripts)
+
+# --- Preflight ---
+command -v docker >/dev/null 2>&1 || { echo "ERROR: docker not found" >&2; exit 1; }
+
+# --- Main ---
+echo "[1/3] Starting operation..."
+# ...
+echo "[2/3] Processing..."
+# ...
+echo "[3/3] Finalizing..."
+
+echo "Done."
+```
+
+### Progress Indicators
+
+Use numbered steps for multi-step scripts so the user can track progress:
+
+```bash
+echo "[1/4] Checking prerequisites..."
+echo "[2/4] Backing up current state..."
+echo "[3/4] Applying changes..."
+echo "[4/4] Verifying results..."
+```
+
+---
+
+## Compliance Checklist
+
+Use this checklist when writing or reviewing any Bash script:
+
+| # | Item | Check |
+|---|------|-------|
+| 1 | Shebang is `#!/usr/bin/env bash` | First line |
+| 2 | `set -euo pipefail` (add `-E` if using ERR trap in functions) | Second line |
+| 3 | All variables double-quoted | No bare `$var` |
+| 4 | `local` declarations separate from `$(cmd)` assignments | No `local x=$(cmd)` |
+| 5 | No `eval`, no backticks, no `ls` parsing | `grep -n 'eval\|` `` ` `` |
+| 6 | `trap cleanup EXIT` for any temp files or state | After variable block |
+| 7 | Cleanup function is idempotent | Uses `rm -f`, `|| true` |
+| 8 | ShellCheck passes with `-x -S warning` | `shellcheck -x -S warning script.sh` |
+| 9 | Errors go to stderr with actionable guidance | `echo "ERROR: ..." >&2` (or `error()` helper — see `error-handling.md`) |
+| 10 | Positional arguments validated with usage message | `if [ $# -lt N ]; then` |
+| 11 | External dependencies checked at script start | `command -v tool` block |
+| 12 | Progress steps use `[N/M]` format | Visual scan |
diff --git a/.claude/skills/shell-scripting/references/error-handling.md b/.claude/skills/shell-scripting/references/error-handling.md
new file mode 100644
index 0000000..58cbb61
--- /dev/null
+++ b/.claude/skills/shell-scripting/references/error-handling.md
@@ -0,0 +1,380 @@
+# Error Handling
+
+Cross-language error handling philosophy and patterns for DAAF shell scripts. Covers the fail-closed principle, user-facing output conventions, exit code standards, Docker-specific error handling, and dependency validation.
+
+---
+
+## Fail-Closed Principle
+
+Security-critical scripts (hooks, safety checks) must fail closed: if the script cannot determine whether an action is safe, it must **block the action**. Uncertainty always resolves to denial.
+
+```bash
+# GOOD: fail-closed — missing dependency blocks the action
+if ! command -v jq >/dev/null 2>&1; then
+    echo "ERROR: jq is required but not found. Cannot verify safety." >&2
+    exit 2  # Block (DAAF hook convention)
+fi
+
+# BAD: fail-open — missing dependency allows the action through
+if ! command -v jq >/dev/null 2>&1; then
+    echo "WARNING: jq not found, skipping check" >&2
+    exit 0  # Allow (dangerous for security hooks)
+fi
+```
+
+**When fail-closed applies:**
+- All scripts in `.claude/hooks/`
+- Any script that gates a destructive operation (backup verification, pre-deploy checks)
+- Any script that validates permissions or credentials
+
+**When fail-open is acceptable:**
+- Non-critical convenience scripts (status displays, formatting helpers)
+- Optional enhancement checks (style linting, optional metrics collection)
+
+---
+
+## User-Facing Output Conventions
+
+### Two-Part Error Messages
+
+Every error message must include TWO parts: **what went wrong** AND **what to do about it**:
+
+```bash
+# GOOD: explains both problem and remedy
+echo "ERROR: Docker daemon is not running." >&2
+echo "  Fix: Start Docker Desktop, or run 'sudo systemctl start docker'" >&2
+
+# BAD: states the problem but leaves the user stranded
+echo "ERROR: Docker not available" >&2
+```
+
+```powershell
+# GOOD
+Write-Error "Docker daemon is not running. Start Docker Desktop or run 'sudo systemctl start docker'"
+
+# BAD
+Write-Error "Docker not available"
+```
+
+### Output Routing
+
+All diagnostic output goes to stderr so it does not contaminate stdout data streams:
+
+```bash
+# Status messages → stderr
+echo "INFO: Starting backup..." >&2
+
+# Error messages → stderr
+echo "ERROR: Backup failed: disk full" >&2
+
+# Data output → stdout (capturable by callers)
+echo "$result"
+```
+
+### Color Formatting (Bash)
+
+Use `tput` for portable color codes, and respect the `NO_COLOR` environment variable and non-TTY contexts:
+
+```bash
+# --- Color setup ---
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+    RED=$(tput setaf 1)
+    GREEN=$(tput setaf 2)
+    YELLOW=$(tput setaf 3)
+    CYAN=$(tput setaf 6)
+    RESET=$(tput sgr0)
+else
+    RED="" GREEN="" YELLOW="" CYAN="" RESET=""
+fi
+
+# --- Helper functions ---
+info()    { echo "${CYAN}INFO:${RESET} $*" >&2; }
+success() { echo "${GREEN}SUCCESS:${RESET} $*" >&2; }
+warn()    { echo "${YELLOW}WARNING:${RESET} $*" >&2; }
+error()   { echo "${RED}ERROR:${RESET} $*" >&2; }
+```
+
+**Key points:**
+- `[ -t 1 ]` checks if stdout is a terminal (not a pipe or file)
+- `NO_COLOR` is a community convention (https://no-color.org/) — respect it
+- When colors are disabled, the helper functions still work, just without formatting
+
+### Color Formatting (PowerShell)
+
+PowerShell has built-in color support via `-ForegroundColor`:
+
+```powershell
+function Write-Info    { param([string]$Message) Write-Host "INFO: $Message" -ForegroundColor Cyan }
+function Write-Success { param([string]$Message) Write-Host "SUCCESS: $Message" -ForegroundColor Green }
+function Write-Warn    { param([string]$Message) Write-Host "WARNING: $Message" -ForegroundColor Yellow }
+# Write-Error already has its own formatting
+```
+
+---
+
+## Exit Code Conventions
+
+### Standard Exit Codes
+
+| Code | Meaning | When to Use |
+|------|---------|-------------|
+| 0 | Success | Script completed normally |
+| 1 | General error | Catchall for unspecified failures |
+| 2 | Blocked | DAAF hook convention: action should be prevented |
+
+### Reserved Ranges for DAAF Scripts
+
+Scripts that need more granular exit codes should use these ranges:
+
+| Range | Category | Examples |
+|-------|----------|---------|
+| 0 | Success | — |
+| 1 | General error | — |
+| 2 | Blocked (hooks) | Safety check failed, unauthorized action |
+| 10-19 | Docker failures | 10: daemon not running, 11: build failed, 12: compose failed |
+| 20-29 | Configuration errors | 20: config file missing, 21: invalid config value |
+| 30-39 | Dependency errors | 30: required tool missing, 31: wrong version |
+
+### Consistent Exit in Bash
+
+```bash
+# Named exit codes for readability
+readonly EXIT_SUCCESS=0
+readonly EXIT_ERROR=1
+readonly EXIT_BLOCKED=2
+readonly EXIT_DOCKER_UNAVAILABLE=10
+
+if ! docker info >/dev/null 2>&1; then
+    error "Docker daemon is not running. Start Docker Desktop."
+    exit "$EXIT_DOCKER_UNAVAILABLE"
+fi
+```
+
+### Consistent Exit in PowerShell
+
+```powershell
+$EXIT_SUCCESS = 0
+$EXIT_ERROR = 1
+$EXIT_BLOCKED = 2
+$EXIT_DOCKER_UNAVAILABLE = 10
+
+if (-not (docker info 2>$null)) {
+    Write-Error "Docker daemon is not running. Start Docker Desktop."
+    exit $EXIT_DOCKER_UNAVAILABLE
+}
+```
+
+---
+
+## Docker-Specific Error Handling
+
+Docker operations are uniquely error-prone because they combine native command exit codes, complex stderr output, asynchronous container startup, and machine-readable output formats.
+
+### Pre-Docker Validation
+
+Always check two things before any Docker operation:
+
+```bash
+# 1. Is Docker installed?
+if ! command -v docker >/dev/null 2>&1; then
+    error "Docker not found. Install from https://docs.docker.com/get-docker/"
+    exit 10
+fi
+
+# 2. Is Docker daemon running?
+if ! docker info >/dev/null 2>&1; then
+    error "Docker daemon is not running. Start Docker Desktop."
+    exit 10
+fi
+```
+
+### Check Exit Codes After Every Call
+
+```bash
+# Bash — use if-not pattern (compatible with set -e)
+if ! docker compose up -d; then
+    error "docker compose up failed. Check logs: docker compose logs"
+    exit 12
+fi
+```
+
+```powershell
+# PowerShell
+docker compose up -d
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "docker compose up failed. Check logs: docker compose logs"
+    exit 12
+}
+```
+
+### Capture Build Output
+
+Docker build output should be captured to a log file AND displayed to the user. On failure, direct the user to the log:
+
+```bash
+BUILD_LOG="$(mktemp)"
+trap 'rm -f "$BUILD_LOG"' EXIT
+
+echo "[2/4] Building Docker image..."
+if ! docker build -t myimage . 2>&1 | tee "$BUILD_LOG"; then
+    error "Docker build failed. Full log: $BUILD_LOG"
+    # Don't delete the log on failure — keep trap but skip cleanup
+    trap - EXIT
+    exit 11
+fi
+```
+
+### Machine-Readable Status Checks
+
+Never parse human-readable Docker output. Use machine-readable formats:
+
+```bash
+# GOOD: JSON output for programmatic parsing
+docker compose ps --format json | jq -r '.[] | select(.State != "running") | .Name'
+
+# GOOD: Go template for specific fields
+docker inspect --format '{{.State.Status}}' mycontainer
+
+# BAD: parsing human-readable table output
+docker compose ps | grep "Up" | awk '{print $1}'
+```
+
+### Bounded Readiness Loops
+
+When waiting for a container to become ready, always set a maximum wait time:
+
+```bash
+MAX_WAIT=60
+INTERVAL=2
+elapsed=0
+
+echo "Waiting for service to be ready..."
+while [ "$elapsed" -lt "$MAX_WAIT" ]; do
+    if docker compose exec -T myservice pg_isready >/dev/null 2>&1; then
+        success "Service is ready."
+        break
+    fi
+    sleep "$INTERVAL"
+    elapsed=$((elapsed + INTERVAL))
+done
+
+if [ "$elapsed" -ge "$MAX_WAIT" ]; then
+    error "Service did not become ready within ${MAX_WAIT}s."
+    # Capture diagnostic info
+    docker compose logs myservice >&2
+    exit 12
+fi
+```
+
+**Key points:**
+- Always have a maximum wait (`MAX_WAIT`)
+- Capture stderr during readiness loops for diagnostics on timeout
+- On timeout, dump container logs to help the user diagnose
+
+---
+
+## Dependency Validation
+
+Check all external dependencies at script start, before any mutations:
+
+### Bash Pattern
+
+```bash
+# --- Preflight ---
+missing=()
+for cmd in docker jq git curl; do
+    if ! command -v "$cmd" >/dev/null 2>&1; then
+        missing+=("$cmd")
+    fi
+done
+
+if [ ${#missing[@]} -gt 0 ]; then
+    error "Missing required tools: ${missing[*]}"
+    echo "  Install with your package manager, e.g.:" >&2
+    echo "    apt-get install ${missing[*]}" >&2
+    echo "    brew install ${missing[*]}" >&2
+    exit 30
+fi
+```
+
+### PowerShell Pattern
+
+```powershell
+# --- Preflight ---
+$missing = @()
+foreach ($cmd in @('docker', 'git')) {
+    if (-not (Get-Command $cmd -ErrorAction SilentlyContinue)) {
+        $missing += $cmd
+    }
+}
+
+if ($missing.Count -gt 0) {
+    Write-Error "Missing required tools: $($missing -join ', '). Install before proceeding."
+    exit 30
+}
+```
+
+### Version Checks
+
+When a minimum version is required, validate it explicitly:
+
+```bash
+# Check Docker Compose v2
+if ! docker compose version >/dev/null 2>&1; then
+    error "Docker Compose v2 required. Found: legacy docker-compose."
+    echo "  Upgrade: https://docs.docker.com/compose/install/" >&2
+    exit 31
+fi
+```
+
+---
+
+## DAAF Composability Patterns
+
+### DAAF_NESTED Flag
+
+When scripts call other scripts, use `DAAF_NESTED` to suppress interactive behavior:
+
+```bash
+# Outer script
+export DAAF_NESTED=1
+bash ./inner_script.sh
+ec=$?
+unset DAAF_NESTED
+
+if [ $ec -ne 0 ]; then
+    error "Inner script failed with exit code $ec"
+    exit $ec
+fi
+```
+
+```bash
+# Inner script (at the end)
+if [ "${DAAF_NESTED:-}" != "1" ]; then
+    echo ""
+    echo "Press Enter to close..."
+    read -r
+fi
+exit "$exit_code"
+```
+
+### Idempotent Operations
+
+Scripts should be safe to run multiple times. Check for prior state before acting:
+
+```bash
+# Idempotent backup
+if [ -d "$BACKUP_DIR" ]; then
+    info "Backup already exists at $BACKUP_DIR — skipping."
+else
+    info "Creating backup at $BACKUP_DIR..."
+    cp -r "$TARGET_DIR" "$BACKUP_DIR"
+fi
+
+# Idempotent container start
+if docker compose ps --format json | jq -e '.[] | select(.Name == "myservice" and .State == "running")' >/dev/null 2>&1; then
+    info "Service already running — skipping start."
+else
+    docker compose up -d myservice
+fi
+```
diff --git a/.claude/skills/shell-scripting/references/gotchas.md b/.claude/skills/shell-scripting/references/gotchas.md
new file mode 100644
index 0000000..360bfbc
--- /dev/null
+++ b/.claude/skills/shell-scripting/references/gotchas.md
@@ -0,0 +1,558 @@
+# Gotchas
+
+Known pitfalls and surprising behaviors in Bash, PowerShell, and cross-platform scripting. Each entry includes the problem, why it happens, and the fix.
+
+---
+
+## Bash Gotchas
+
+### `local var=$(cmd)` Masks Exit Code
+
+**The problem:** `local` always returns 0, so the exit code of the command substitution is lost.
+
+```bash
+# BAD: if some_command fails, $? is still 0 because local succeeded
+local result=$(some_command)
+echo "Exit code: $?"  # Always 0
+
+# GOOD: separate declaration from assignment
+local result
+result=$(some_command)
+echo "Exit code: $?"  # Reflects some_command's actual exit code
+```
+
+**Why it happens:** `local` is a builtin command. Its return code (always 0 on success) overwrites the return code from the command substitution on the right-hand side.
+
+**ShellCheck:** This is SC2155. Run `shellcheck -x -S warning` to catch it automatically.
+
+**Severity:** High. This is the most insidious Bash bug because it silently swallows errors. Every `local var=$(cmd)` in your codebase is a potential hidden failure.
+
+---
+
+### `set -e` Doesn't Catch Failures in Assignments
+
+**The problem:** Even without `local`, command substitution failures in variable assignments are sometimes not caught by `set -e`:
+
+```bash
+set -e
+
+# This MAY silently succeed even if cmd fails, depending on Bash version:
+var=$(failing_command)
+
+# This reliably catches the failure:
+var=$(failing_command) || exit 1
+```
+
+**Why it happens:** The POSIX spec has ambiguous wording about whether assignment is a "simple command" for `set -e` purposes. Behavior varies across Bash versions and shells.
+
+**Fix:** For critical assignments, add explicit `|| exit 1`, or validate the result immediately afterward.
+
+---
+
+### `2>/dev/null` on Docker Probes Loses Diagnostics
+
+**The problem:** Redirecting stderr to `/dev/null` during Docker health checks discards the diagnostic information you need when the check fails:
+
+```bash
+# BAD: if docker info fails, you've thrown away the error message
+if docker info >/dev/null 2>/dev/null; then
+    echo "Docker is running"
+fi
+
+# GOOD: capture stderr for diagnostic use on failure
+docker_err=$(docker info 2>&1 >/dev/null) || {
+    error "Docker check failed: $docker_err"
+    exit 10
+}
+```
+
+**When `2>/dev/null` is acceptable:** Only for truly expected, uninformative stderr output (e.g., deprecation warnings you've already evaluated and decided to suppress).
+
+---
+
+### `cd dir` Without Error Handling
+
+**The problem:** `cd` can fail (directory doesn't exist, no permissions), and with `set -e` the behavior is inconsistent depending on context:
+
+```bash
+# BAD: if cd fails, script continues in wrong directory
+cd "$some_dir"
+rm -rf ./*.tmp  # Now deleting files in the wrong directory
+
+# GOOD: explicit failure handling
+cd "$some_dir" || { error "Cannot cd to $some_dir"; exit 1; }
+```
+
+**ShellCheck:** This is SC2164.
+
+---
+
+### Backtick Substitution Cannot Nest
+
+```bash
+# BAD: backticks cannot nest — inner backticks need escaping
+result=`echo \`date\``
+
+# GOOD: $() nests cleanly
+result=$(echo $(date))
+```
+
+Backticks are also harder to read. Always use `$(...)`.
+
+---
+
+### Word Splitting in Conditionals
+
+```bash
+# BAD: if var is empty, this becomes [ = "value" ] — syntax error
+if [ $var = "value" ]; then
+
+# GOOD: quotes prevent word splitting
+if [ "$var" = "value" ]; then
+
+# ALSO GOOD: [[ doesn't word-split
+if [[ $var = "value" ]]; then
+```
+
+---
+
+### Unquoted Glob Expansion
+
+```bash
+# BAD: if *.log matches nothing, the literal string "*.log" is passed
+for f in *.log; do
+    echo "Processing $f"
+done
+# If no .log files exist, prints "Processing *.log"
+
+# GOOD: check if glob matches
+shopt -s nullglob
+for f in ./*.log; do
+    echo "Processing $f"
+done
+# If no .log files exist, loop body never executes
+```
+
+---
+
+## PowerShell Gotchas
+
+### `exit` in Dot-Sourced Script Functions Does Not Terminate the Host
+
+**The problem:** When a script is loaded via `. script.ps1` (dot-sourcing), `exit N` inside a function defined in that script does not terminate the calling process. Instead, it unwinds the dot-sourced scope and returns control to the caller -- with exit code 0:
+
+```powershell
+# inner.ps1
+function Stop-WithError {
+    Write-Host "Error detected"
+    exit 1   # Caller expects this to terminate the process
+}
+Stop-WithError
+Write-Host "This should not print"  # Does not print (exit unwinds script scope)
+
+# caller.ps1
+. ./inner.ps1
+Write-Host "Back in caller -- exit 1 did NOT terminate"  # This DOES print!
+# Process exits with code 0
+```
+
+**When run directly** (`pwsh -File inner.ps1`), `exit 1` terminates the process with code 1 as expected. The bug is specific to dot-sourced invocation.
+
+**Why it happens:** Dot-sourcing (`. script.ps1`) runs the script in the caller's scope, not a child scope. The `exit` keyword unwinds to the scope boundary of the dot-sourced content, then returns to the caller rather than terminating the host process. This is a long-standing PowerShell behavior, not a bug in any specific version.
+
+**When this bites:** Pester test wrappers that define mock functions and then dot-source the script under test:
+```powershell
+# test_wrapper.ps1
+function docker { $global:LASTEXITCODE = 1; return }  # Mock
+. './real_script.ps1'                                    # Dot-source
+# real_script.ps1 detects error, calls exit 1
+# But exit 1 just returns here -- wrapper exits 0
+```
+
+**Fix:** Use `[Environment]::Exit(N)` for non-zero exit codes. This terminates the CLR process unconditionally, regardless of how the script was loaded:
+
+```powershell
+function Wait-ForUser {
+    param([int]$ExitCode = 0)
+    if (-not $env:DAAF_NESTED) { Read-Host "Press Enter to close" }
+    # [Environment]::Exit() bypasses scope unwinding -- always terminates
+    if ($ExitCode -ne 0) { [Environment]::Exit($ExitCode) }
+    exit $ExitCode  # For success (0), plain exit is safe and less disruptive
+}
+```
+
+**Why not `[Environment]::Exit()` for all exits?** It bypasses PowerShell cleanup (finally blocks, Dispose). More importantly, it kills the entire process -- including the Pester test host if the script is called via `&` (call operator) in non-subprocess tests. Using it only for non-zero exits keeps success-path tests (dry-run, smoke) safe while fixing error-path tests that run in subprocesses.
+
+**Severity:** High. The failure is completely silent -- the script appears to detect the error (prints error messages), but the process exit code is 0. Test assertions on `$LASTEXITCODE` fail with no indication of why.
+
+---
+
+### `$?` Is Unreliable for Native Commands
+
+**The problem:** `$?` checks whether the last *PowerShell operation* succeeded, but stderr output from native commands can make `$?` return `$false` even when the command exited 0:
+
+```powershell
+# BAD: docker writes informational messages to stderr, causing $? = $false
+docker compose up -d
+if (-not $?) {
+    Write-Error "Docker failed"  # False alarm
+}
+
+# GOOD: check the actual exit code
+docker compose up -d
+if ($LASTEXITCODE -ne 0) {
+    Write-Error "Docker compose failed (exit code: $LASTEXITCODE)"
+}
+```
+
+**Rule:** Use `$LASTEXITCODE` for ALL native command checks. Use `$?` only for PowerShell cmdlets.
+
+---
+
+### `$ErrorActionPreference = 'Stop'` Ignores Native Exit Codes
+
+**The problem:** `$ErrorActionPreference` only affects PowerShell cmdlet errors. Native command non-zero exit codes are not converted to exceptions:
+
+```powershell
+$ErrorActionPreference = 'Stop'
+
+# This does NOT throw, even though docker exits with code 1
+docker build -t badimage .
+
+# You MUST check $LASTEXITCODE manually
+docker build -t badimage .
+if ($LASTEXITCODE -ne 0) {
+    throw "Docker build failed"
+}
+```
+
+**Why it happens:** PowerShell treats native executables as black boxes. Their stderr output and exit codes are outside PowerShell's error handling system (unless `$PSNativeCommandUseErrorActionPreference = $true` in PS 7.4+).
+
+---
+
+### `$LASTEXITCODE` Starts as `$null`, Not 0
+
+**The problem:** Before any native command has run in a session, `$LASTEXITCODE` is `$null`. Naive checks like `$LASTEXITCODE -ne 0` then evaluate `$null -ne 0` which is `$true`, falsely indicating failure:
+
+```powershell
+# BAD: fires a false positive before any native command has run
+if ($LASTEXITCODE -ne 0) {
+    throw "Command failed"  # Triggers when $LASTEXITCODE is $null
+}
+
+# GOOD: guard against $null
+if ($LASTEXITCODE -and $LASTEXITCODE -ne 0) {
+    throw "Command failed"
+}
+
+# ALSO GOOD: explicit null check
+if ($null -ne $LASTEXITCODE -and $LASTEXITCODE -ne 0) {
+    throw "Command failed"
+}
+```
+
+**Why it happens:** PowerShell only sets `$LASTEXITCODE` when a native executable actually runs. Functions, cmdlets, and mock overrides of native commands (e.g., defining a `docker` function for dry-run testing) do not update `$LASTEXITCODE`. If your script overrides `docker` with a PowerShell function, `$LASTEXITCODE` stays at whatever it was before — often `$null`.
+
+**When this bites:** CI smoke tests, dry-run modes, or any scenario where native commands are mocked with PowerShell functions. The mock function must explicitly set `$global:LASTEXITCODE = 0` if downstream code checks the exit code.
+
+**Severity:** Medium. The failure is immediate and obvious (a thrown exception), but it's confusing because there is no actual command failure.
+
+---
+
+### Single-Element Pipeline Array Unwrapping
+
+**The problem:** When a pipeline returns exactly one object, PowerShell unwraps it from an array to a scalar. Indexing into the result then indexes into the string's characters instead of array elements:
+
+```powershell
+# BAD: if docker returns exactly one container name, $result is a string
+$result = docker ps --format '{{.Names}}'
+$first = $result[0]           # Returns first CHARACTER, not first element
+$first.Trim()                 # Fails: [char] has no Trim() method
+
+# GOOD: force array context with @()
+$result = @(docker ps --format '{{.Names}}')
+$first = $result[0]           # Always returns first element (string)
+$first.Trim()                 # Works
+```
+
+**Why it happens:** PowerShell's pipeline is designed to stream individual objects. When a pipeline produces a single object, PowerShell "unwraps" the implicit single-element array and returns the bare object. Two or more items return an `[Object[]]` array, but one item returns the raw scalar. This means `[0]` on a string indexes characters, not array positions.
+
+**When this bites:** Any script that collects Docker/git output into a variable and indexes into it. The bug only manifests when exactly one line is returned — zero lines give `$null` (caught by null checks) and two or more lines give an array (indexing works). The single-line case silently produces wrong results.
+
+**Severity:** High. The failure mode is silent and data-dependent — the same code works in testing with multiple containers but fails in production with one.
+
+---
+
+### Embedded Double-Quotes in Native Command Arguments on Windows
+
+**The problem:** When PowerShell on Windows passes a string containing `"` characters to a native executable (like `docker.exe`), the Windows C runtime argument parser (`CommandLineToArgvW`) can misinterpret quoting boundaries, silently truncating or mangling the argument. Multi-command `sh -c` pipelines are especially vulnerable:
+
+```powershell
+# BAD: PowerShell "" escapes produce literal " that Windows misparses
+$out = docker run --rm busybox sh -c "awk '{printf ""%d\n"", s/1024}'"
+# Result: awk receives a garbled program — "Unexpected token" or silent truncation
+
+# ALSO BAD: PowerShell single-quotes with sh double-quotes — literal " in the string
+$out = docker run --rm busybox sh -c 'stat -c "%s" file | awk "{s+=\$1} END {print s}"'
+# Result: Windows splits the argument at spaces between the " pairs
+
+# GOOD: PowerShell double-quotes with sh single-quotes — no " in the result
+$out = docker run --rm busybox sh -c "stat -c %s file | awk '{s+=`$1} END {print s}'"
+# Result: string has no embedded " — Windows passes it intact
+```
+
+**Why it happens:** On Windows, native executables receive their arguments as a single command-line string, not a pre-parsed array. The C runtime's `CommandLineToArgvW` re-parses that string using its own rules where `"` toggles quoted/unquoted state. When embedded `"` characters appear — whether from PowerShell `""` escapes or from literal `"` inside single-quoted strings — they create ambiguous boundaries that cause argument splitting or truncation. The failure is **completely silent**: no error, no warning, just wrong or missing output.
+
+**Fix:** Eliminate ALL `"` characters from the string that reaches the native executable:
+1. Use a **PowerShell double-quoted** outer string (for variable interpolation via `` `$ `` escaping)
+2. Use **sh single-quotes** for inner quoting (awk programs, format strings)
+3. Leave simple arguments **unquoted** at the sh level when safe (e.g., `stat -c %s` — no sh metacharacters in `%s`)
+4. Use `print` instead of `printf "%d\n"` in awk to avoid needing format-string quotes
+
+**Note:** This does **not** affect Bash. On Linux/macOS, Bash passes arguments via `execvp` as a pre-parsed array — there is no intermediate command-line string for a C runtime to reinterpret.
+
+**Severity:** High. The failure is completely silent — the command may exit 0 but produce truncated output. Any PowerShell script passing complex `sh -c` commands to Docker (or any native executable) on Windows is potentially affected.
+
+---
+
+### Expression Context Breaks Interactive Native Commands (TTY Loss)
+
+**The problem:** When a function containing an interactive native command (like `docker compose exec`) is called inside a PowerShell expression -- `if (-not (FunctionCall))`, `$result = FunctionCall`, `FunctionCall | ...` -- PowerShell captures the function's stdout through an internal pipe. Native commands that check both stdin AND stdout for TTY (e.g., Docker, ssh, interactive CLIs) see stdout as a pipe and refuse to allocate a TTY. The interactive program silently enters non-interactive/pipe mode:
+
+```powershell
+# BAD: expression context captures stdout through a pipe -- Docker sees non-TTY stdout
+function Resolve-Conflict {
+    docker compose exec daaf-docker claude   # Claude Code enters --print mode (3s timeout)
+    return $true
+}
+if (-not (Resolve-Conflict)) { ... }     # Expression context!
+$result = Resolve-Conflict                # Also expression context!
+
+# GOOD: call as a statement -- stdout flows to the console
+function Resolve-Conflict {
+    docker compose exec daaf-docker claude   # Claude Code starts interactively
+    $script:ConflictResolved = $true
+}
+Resolve-Conflict                             # Statement -- no pipe
+if (-not $script:ConflictResolved) { ... }   # Check variable separately
+```
+
+**Why it happens:** Docker's Go-based TTY detection (`golang.org/x/term.IsTerminal`) calls `GetConsoleMode` on BOTH stdin and stdout file handles. In expression context, PowerShell replaces stdout with a pipe to capture the function's output for evaluation. `GetConsoleMode` fails on the pipe handle, so Docker concludes the environment is non-interactive and skips PTY allocation. The containerized process then sees `isatty(0)` = false on its stdin.
+
+**What makes this insidious:**
+- The same function works perfectly when called as a statement (`FunctionCall` on its own line)
+- The same Docker command works at the PowerShell prompt and in simple scripts
+- No error message points to stdout piping -- the native command just silently enters non-interactive mode
+- `cmd /c`, `try/catch` removal, and `$ErrorActionPreference` changes do NOT fix it because the pipe is set up by the expression evaluation, not by any wrapping construct
+
+**This does NOT affect Bash.** In bash, `if ! function_call` evaluates the function's exit code without creating a subshell or capturing stdout. Stdout flows directly to the terminal.
+
+**Severity:** High. The failure is silent and difficult to diagnose. The function appears to run correctly (Docker starts, the program launches), but the interactive program immediately detects non-interactive I/O and falls back to a degraded mode or exits.
+
+---
+
+### Implicit Return Values
+
+**The problem:** Every expression in a function that produces output becomes part of the return value:
+
+```powershell
+# BAD: function returns @(0, 1, "result") instead of just "result"
+function Get-Data {
+    $list = [System.Collections.ArrayList]::new()
+    $list.Add("item1")    # .Add() returns index 0
+    $list.Add("item2")    # .Add() returns index 1
+    return "result"
+}
+
+# GOOD: suppress unwanted output
+function Get-Data {
+    $list = [System.Collections.ArrayList]::new()
+    $null = $list.Add("item1")
+    $null = $list.Add("item2")
+    return "result"
+}
+```
+
+**Other common sources of leaked output:**
+- `[void]` cast expressions
+- `.Remove()`, `.Insert()` methods on collections
+- Variable assignments that happen to produce output
+- `if` expressions that evaluate to a value
+
+---
+
+### `$null` in Pipeline Executes ForEach-Object Once
+
+**The problem:** `$null` piped to `ForEach-Object` executes the loop body once, with `$_` set to `$null`:
+
+```powershell
+# BAD: if Get-Items returns $null, ForEach still executes once
+$items = Get-Items  # Returns $null
+$items | ForEach-Object { Process-Item $_ }
+# Process-Item is called once with $null
+
+# GOOD: wrap in @() for safe empty array
+@($items) | ForEach-Object { Process-Item $_ }
+# ForEach-Object is never called if array is empty
+
+# ALSO GOOD: explicit null check
+if ($null -ne $items) {
+    $items | ForEach-Object { Process-Item $_ }
+}
+```
+
+---
+
+### `-Version Latest` on Set-StrictMode
+
+**The problem:** `Set-StrictMode -Version Latest` resolves to whatever version your PowerShell runtime supports. This means the same script enforces different rules on different machines:
+
+```powershell
+# BAD: non-deterministic across PS versions
+Set-StrictMode -Version Latest
+
+# GOOD: explicit and reproducible
+Set-StrictMode -Version 3.0
+```
+
+**Why `-Version 3.0`?** It catches the most common issues (uninitialized variables, non-existent properties) without introducing the more aggressive (and sometimes surprising) checks from later versions.
+
+---
+
+### UTF-8 BOM Breaks `Invoke-Expression`
+
+**The problem:** A `.ps1` script containing non-ASCII characters (em-dashes, curly quotes) requires a UTF-8 BOM for PowerShell 5.1 to interpret them correctly. When the script is executed via `irm URL | iex`, `Invoke-Expression` does not strip the BOM. The BOM character gets prepended to the first line, making `#` look like a command:
+
+```
+The term '#' is not recognized as the name of a cmdlet, function, script file,
+or operable program.
+```
+
+If the script has a `trap` handler, the `CommandNotFoundException` is caught and the trap fires with a misleading error message, masking the actual root cause entirely.
+
+**Why it happens:** The UTF-8 BOM is three invisible bytes (`EF BB BF`) at the start of the file. When PowerShell reads a BOM-encoded file via `Get-Content` or dot-sourcing, it recognizes and strips the BOM. But `Invoke-Expression` receives the file content as a raw string from `Invoke-RestMethod` -- the BOM bytes decode to the Unicode character U+FEFF, which becomes a visible character prepended to the first token. `#Requires` is not a valid command name.
+
+**Fix:** Use only ASCII characters (code points 0-127) in `.ps1` host scripts. Replace em-dashes (`---`) with `--`, curly quotes with straight quotes. Save files as UTF-8 without BOM. Verify with `file script.ps1` -- it should report "ASCII text", not "UTF-8 Unicode (with BOM)".
+
+**Severity:** High. The `irm | iex` pattern is the standard installation/setup one-liner. Any BOM-encoded script distributed this way will fail on every execution, and the error message gives no hint about encoding.
+
+---
+
+### Parameter Validation on Omitted Parameters
+
+**The problem:** Validation attributes fire only when the parameter is *supplied*. If a parameter is omitted entirely, validation is bypassed:
+
+```powershell
+function Do-Thing {
+    param(
+        [ValidateNotNullOrEmpty()]
+        [string]$Name  # Not Mandatory
+    )
+    # If called as Do-Thing (no -Name), $Name is "" and validation did NOT fire
+    Write-Host "Name: '$Name'"
+}
+
+# Fix: combine with [Mandatory] if the parameter is required
+function Do-Thing {
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$Name
+    )
+}
+```
+
+---
+
+## Cross-Platform Gotchas
+
+### Environment Variable Case Sensitivity
+
+**The problem:** Environment variable names are case-insensitive on Windows but case-sensitive on Linux:
+
+```powershell
+# Windows: both of these access the same variable
+$env:PATH
+$env:Path
+
+# Linux: these are DIFFERENT variables
+$env:PATH   # System PATH
+$env:Path    # Undefined (or user-defined)
+```
+
+**Fix:** Always use the exact casing that the convention requires (`PATH` on Linux, `Path` on Windows). For cross-platform scripts, use `$env:PATH` consistently.
+
+---
+
+### Aliases Removed on Linux/macOS PowerShell
+
+**The problem:** PowerShell on Windows includes aliases like `ls` (for `Get-ChildItem`), `cat` (for `Get-Content`), `cp` (for `Copy-Item`). On Linux and macOS, these aliases are removed because they conflict with the native commands:
+
+```powershell
+# BAD: works on Windows, fails on Linux (calls native ls, different output format)
+$files = ls *.txt
+
+# GOOD: use full cmdlet names
+$files = Get-ChildItem -Filter "*.txt"
+```
+
+**PSScriptAnalyzer** catches this with the `PSAvoidUsingCmdletAliases` rule.
+
+---
+
+### Exit Codes Above 255 Truncated on Linux
+
+**The problem:** Linux processes use 8-bit exit codes (0-255). Any exit code above 255 is truncated:
+
+```powershell
+# On Linux: exit 256 becomes exit 0 (256 % 256 = 0)
+# On Linux: exit 300 becomes exit 44 (300 % 256 = 44)
+exit 256  # Looks like success on Linux!
+```
+
+**Fix:** Keep all exit codes in the range 0-125. Codes 126-255 have special meanings in some shells.
+
+---
+
+### Path Separators
+
+**The problem:** Windows uses `\`, Linux/macOS use `/`. String concatenation with path separators breaks cross-platform:
+
+```powershell
+# BAD: backslash path fails on Linux
+$configPath = "$BaseDir\config\settings.json"
+
+# GOOD: Join-Path handles separators correctly
+$configPath = Join-Path $BaseDir "config" "settings.json"
+
+# ALSO GOOD in PowerShell 6+: forward slash works everywhere
+$configPath = "$BaseDir/config/settings.json"
+```
+
+In Bash, `/` is always the separator. No cross-platform concern within Bash itself, but be aware when generating paths that PowerShell scripts will consume.
+
+---
+
+## Quick Lookup
+
+| Gotcha | Language | Severity | ShellCheck/Analyzer |
+|--------|----------|----------|---------------------|
+| `local var=$(cmd)` masks exit | Bash | High | SC2155 |
+| `set -e` in assignments | Bash | Medium | — |
+| `2>/dev/null` on probes | Bash | Medium | — |
+| `cd` without `\|\| exit` | Bash | Medium | SC2164 |
+| Backtick nesting | Bash | Low | SC2006 |
+| `exit` in dot-sourced functions | PowerShell | High | — |
+| `$?` for native commands | PowerShell | High | — |
+| Expression context breaks TTY | PowerShell | High | — |
+| `$ErrorActionPreference` scope | PowerShell | High | — |
+| Embedded `"` in native args | PowerShell | High | — |
+| Implicit return values | PowerShell | High | — |
+| UTF-8 BOM breaks `iex` | PowerShell | High | — |
+| `$null` in ForEach pipeline | PowerShell | Medium | — |
+| `-Version Latest` | PowerShell | Medium | — |
+| Parameter validation bypass | PowerShell | Medium | — |
+| Env var case sensitivity | Cross-platform | Medium | — |
+| Alias removal on Linux | Cross-platform | Medium | PSAvoidUsingCmdletAliases |
+| Exit code truncation | Cross-platform | Low | — |
+| Path separator differences | Cross-platform | Medium | — |
diff --git a/.claude/skills/shell-scripting/references/powershell-standards.md b/.claude/skills/shell-scripting/references/powershell-standards.md
new file mode 100644
index 0000000..2c1ec5f
--- /dev/null
+++ b/.claude/skills/shell-scripting/references/powershell-standards.md
@@ -0,0 +1,333 @@
+# PowerShell Standards
+
+Comprehensive standards for writing PowerShell scripts in DAAF. Covers preamble rules, the dual error system, defensive coding patterns, output streams, and PSScriptAnalyzer integration.
+
+---
+
+## Preamble
+
+Every PowerShell script starts with these lines:
+
+```powershell
+#Requires -Version 5.1
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version 3.0
+```
+
+**What each line does:**
+
+| Line | Purpose | Nuance |
+|------|---------|--------|
+| `#Requires -Version 5.1` | Fail fast on unsupported environments | Checked before script body executes |
+| `$ErrorActionPreference = 'Stop'` | Convert terminating errors into exceptions caught by `try/catch` | Does NOT affect native command exit codes |
+| `Set-StrictMode -Version 3.0` | Catch uninitialized variables, non-existent properties | Prefer `-Version 3.0` over `-Version Latest` — Latest is non-deterministic across PS releases |
+
+**Why not `-Version Latest`?**
+
+`Set-StrictMode -Version Latest` resolves to whatever version the runtime supports. This means the same script may enforce different rules on different machines, creating hard-to-reproduce failures. `-Version 3.0` is deterministic.
+
+---
+
+## Character Encoding: ASCII Only
+
+All `.ps1` host scripts must contain only ASCII characters (code points 0-127). No em-dashes (`---`), curly quotes, or other non-ASCII content -- not even in comments.
+
+**Why:** Non-ASCII characters in a `.ps1` file require a UTF-8 BOM (byte order mark) for PowerShell 5.1 to interpret them correctly. The BOM is invisible but prepends three bytes (`EF BB BF`) to the file. When the script is executed via `irm URL | iex` (the standard `Invoke-Expression` one-liner pattern), PowerShell does not strip the BOM. The BOM character gets prepended to the first `#`, making the comment line look like a command:
+
+```
+The term '#' is not recognized as the name of a cmdlet, function, script file,
+or operable program.
+```
+
+This `CommandNotFoundException` is caught by `trap` handlers and masks the real error, making the failure extremely difficult to diagnose.
+
+**Rule:** Replace all non-ASCII characters with ASCII equivalents:
+
+| Non-ASCII | ASCII Replacement |
+|-----------|-------------------|
+| `---` (em-dash, U+2014) | `--` |
+| `--` (en-dash, U+2013) | `--` |
+| `\u2018` `\u2019` (curly single quotes) | `'` |
+| `\u201C` `\u201D` (curly double quotes) | `"` |
+
+**Verification:** Save files without BOM. In VS Code, the status bar shows "UTF-8" (no BOM) or "UTF-8 with BOM" -- ensure it shows "UTF-8" only. From the command line: `file script.ps1` should report "ASCII text", not "UTF-8 Unicode (with BOM)".
+
+---
+
+## The Dual Error System (Critical)
+
+PowerShell has two fundamentally different error mechanisms. Confusing them is the single most common source of PowerShell bugs in cross-tool scripts.
+
+### Cmdlet Errors (Terminating)
+
+PowerShell cmdlets throw terminating errors when `$ErrorActionPreference = 'Stop'`. These are caught by `try/catch`:
+
+```powershell
+try {
+    Get-Content -Path "nonexistent.txt"
+}
+catch {
+    Write-Error "File read failed: $_"
+}
+```
+
+### Native Command Errors (Exit Codes)
+
+Native executables (`docker`, `git`, `curl`, etc.) communicate via exit codes. PowerShell does NOT auto-convert non-zero exit codes to exceptions. `try/catch` will NOT catch a `docker build` failure:
+
+```powershell
+# BAD: docker failure is silently ignored
+try {
+    docker build -t myimage .    # Exit code 1 — NOT caught
+}
+catch {
+    Write-Error "This never fires for native command failures"
+}
+
+# GOOD: explicit exit code check
+docker build -t myimage .
+if ($LASTEXITCODE -ne 0) {
+    throw "docker build failed (exit code: $LASTEXITCODE)"
+}
+```
+
+### The Assert-ExitCode Helper
+
+For scripts with many native command calls, define a helper:
+
+```powershell
+function Assert-ExitCode {
+    param(
+        [Parameter(Mandatory)]
+        [string]$Command
+    )
+    if ($LASTEXITCODE -ne 0) {
+        throw "$Command failed (exit code: $LASTEXITCODE)"
+    }
+}
+
+# Usage:
+docker compose up -d
+Assert-ExitCode "docker compose up"
+
+git pull origin main
+Assert-ExitCode "git pull"
+```
+
+### $LASTEXITCODE vs $?
+
+| Variable | What It Tracks | Reliable For |
+|----------|---------------|--------------|
+| `$LASTEXITCODE` | Exit code of the last native command | Native commands (docker, git, curl) — always use this |
+| `$?` | Whether the last operation "succeeded" | Cmdlets only — unreliable for native commands |
+
+**Never use `$?` to check Docker or Git results.** Stderr output from native commands can cause `$?` to return `$false` even when the command succeeded (exit code 0).
+
+### PS 7.4+ Automatic Conversion
+
+PowerShell 7.4+ introduces `$PSNativeCommandUseErrorActionPreference = $true`, which auto-converts non-zero exit codes to errors. However:
+
+- Scripts targeting PS 5.1 cannot use this
+- For cross-version compatibility, always check `$LASTEXITCODE` explicitly
+
+---
+
+## Defensive Coding
+
+### CmdletBinding and Parameter Validation
+
+```powershell
+function Install-DaafComponent {
+    [CmdletBinding()]
+    param(
+        [Parameter(Mandatory)]
+        [ValidateNotNullOrEmpty()]
+        [string]$ComponentName,
+
+        [ValidateSet('Install', 'Update', 'Remove')]
+        [string]$Action = 'Install'
+    )
+
+    # ... implementation ...
+}
+```
+
+**Note on validation:** Parameter validation attributes fire only when the parameter is *supplied*. Omitted parameters bypass validation entirely — if a parameter has no default and is not `[Mandatory]`, it may be `$null` or empty at runtime despite `[ValidateNotNullOrEmpty()]`.
+
+### Suppress Unwanted Output
+
+Every unhandled expression in a function body becomes part of the return value. This is one of PowerShell's most surprising behaviors:
+
+```powershell
+# BAD: ArrayList.Add() returns the index — it becomes part of the return value
+function Get-ProcessedItems {
+    $list = [System.Collections.ArrayList]::new()
+    $list.Add("item1")   # Returns 0 — leaked into output
+    $list.Add("item2")   # Returns 1 — leaked into output
+    return $list
+}
+# Result: 0, 1, item1, item2  (not just item1, item2)
+
+# GOOD: suppress the return value
+function Get-ProcessedItems {
+    $list = [System.Collections.ArrayList]::new()
+    $null = $list.Add("item1")
+    $null = $list.Add("item2")
+    return $list
+}
+```
+
+Use `$null = expression` to suppress unwanted output. Avoid `| Out-Null` — it creates a pipeline and is up to 40x slower.
+
+### Empty Collection Safety
+
+`$null` in a pipeline executes `ForEach-Object` once with `$_` set to `$null`:
+
+```powershell
+# BAD: if $items is $null, the loop body runs once with $_ = $null
+$items | ForEach-Object { Process-Item $_ }
+
+# GOOD: wrap in @() to ensure an empty array, not $null
+@($items) | ForEach-Object { Process-Item $_ }
+
+# ALSO GOOD: null-check first
+if ($null -ne $items) {
+    $items | ForEach-Object { Process-Item $_ }
+}
+```
+
+---
+
+## Output Streams
+
+PowerShell has multiple output streams. Use the right one for each purpose:
+
+| Cmdlet | Stream | When to Use |
+|--------|--------|-------------|
+| `Write-Output` | Success (1) | Data output that should be capturable by callers |
+| `Write-Host` | Information (6) | Display-only status with color (appropriate for CLI tools) |
+| `Write-Error` | Error (2) | Actual error conditions |
+| `Write-Warning` | Warning (3) | Non-fatal concerns the user should know about |
+| `Write-Verbose` | Verbose (4) | Troubleshooting detail (visible with `-Verbose`) |
+| `Write-Debug` | Debug (5) | Developer-level tracing (visible with `-Debug`) |
+
+### Color Conventions
+
+```powershell
+Write-Host "[1/3] Checking prerequisites..." -ForegroundColor Cyan
+Write-Host "SUCCESS: All checks passed" -ForegroundColor Green
+Write-Host "WARNING: Using fallback path" -ForegroundColor Yellow
+Write-Error "FAILED: Docker not found. Install Docker Desktop from https://docs.docker.com/get-docker/"
+```
+
+### Progress Indicators
+
+```powershell
+$steps = 4
+Write-Host "[1/$steps] Checking prerequisites..." -ForegroundColor Cyan
+# ...
+Write-Host "[2/$steps] Backing up current state..." -ForegroundColor Cyan
+# ...
+Write-Host "[3/$steps] Applying changes..." -ForegroundColor Cyan
+# ...
+Write-Host "[4/$steps] Verifying results..." -ForegroundColor Cyan
+Write-Host "Done." -ForegroundColor Green
+```
+
+---
+
+## PSScriptAnalyzer
+
+[PSScriptAnalyzer](https://github.com/PowerShell/PSScriptAnalyzer) is the standard linter for PowerShell scripts.
+
+### Running the Analyzer
+
+```powershell
+Invoke-ScriptAnalyzer -Path ./scripts -Recurse -EnableExit
+```
+
+`-EnableExit` sets a non-zero exit code when violations are found, useful for CI pipelines.
+
+### Configuration File
+
+Create `PSScriptAnalyzerSettings.psd1` in `.github/linters/` and check it in:
+
+```powershell
+@{
+    Severity = @('Error', 'Warning')
+    Rules    = @{
+        PSAvoidUsingCmdletAliases         = @{ Enable = $true }
+        PSAvoidUsingInvokeExpression       = @{ Enable = $true }
+        PSUseDeclaredVarsMoreThanAssignments = @{ Enable = $true }
+        PSAvoidUsingWriteHost              = @{ Enable = $false }  # We use Write-Host for CLI output
+    }
+}
+```
+
+### Key Rules
+
+| Rule | What It Catches | Why It Matters |
+|------|----------------|----------------|
+| `PSAvoidUsingCmdletAliases` | `ls`, `cat`, `cp` instead of full cmdlet names | Aliases are removed on Linux/macOS PowerShell |
+| `PSAvoidUsingInvokeExpression` | `Invoke-Expression` (PowerShell's `eval`) | Same injection risks as Bash `eval` |
+| `PSUseDeclaredVarsMoreThanAssignments` | Variables assigned but never read | Dead code that confuses readers |
+| `PSAvoidUsingWriteHost` | `Write-Host` usage | Disabled in DAAF config — we use it intentionally for CLI tools |
+
+---
+
+## Script Structure
+
+```powershell
+#Requires -Version 5.1
+$ErrorActionPreference = 'Stop'
+Set-StrictMode -Version 3.0
+
+# --- Config ---
+$BaseDir = $PSScriptRoot
+$MaxRetries = 3
+
+# --- Helpers ---
+function Assert-ExitCode {
+    param([Parameter(Mandatory)][string]$Command)
+    if ($LASTEXITCODE -ne 0) {
+        throw "$Command failed (exit code: $LASTEXITCODE)"
+    }
+}
+
+# --- Preflight ---
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Error "Docker not found. Install from https://docs.docker.com/get-docker/"
+    exit 1
+}
+
+# --- Main ---
+Write-Host "[1/3] Starting operation..." -ForegroundColor Cyan
+# ...
+Write-Host "[2/3] Processing..." -ForegroundColor Cyan
+# ...
+Write-Host "[3/3] Finalizing..." -ForegroundColor Cyan
+
+Write-Host "Done." -ForegroundColor Green
+```
+
+---
+
+## Compliance Checklist
+
+| # | Item | Check |
+|---|------|-------|
+| 1 | `#Requires -Version 5.1` | First line |
+| 2 | `$ErrorActionPreference = 'Stop'` | Near top |
+| 3 | `Set-StrictMode -Version 3.0` (not `-Version Latest`) | Near top |
+| 4 | `$LASTEXITCODE` checked after every native command | After docker, git, etc. |
+| 5 | No reliance on `$?` for native commands | Grep for `if \($\?` near native calls |
+| 6 | `[CmdletBinding()]` on all functions | Function declarations |
+| 7 | `[ValidateNotNullOrEmpty()]` on string parameters | Parameter blocks |
+| 8 | `$null = expr` not `\| Out-Null` | Performance |
+| 9 | No implicit returns leaking into function output | Review all expressions in functions |
+| 10 | PSScriptAnalyzer clean | `Invoke-ScriptAnalyzer -Path . -Recurse -EnableExit` |
+| 11 | No `Invoke-Expression` | Grep for `Invoke-Expression` |
+| 12 | Full cmdlet names (no aliases like `ls`, `cat`) | PSScriptAnalyzer rule |
+| 13 | Progress steps use `[N/M]` format | Visual scan |
+| 14 | ASCII-only content (no em-dashes, curly quotes, no BOM) | `file script.ps1` should report "ASCII text" |
+| 15 | Functions with interactive native commands never called in expression context | No `if (Fn)`, `$x = Fn`, or `Fn \|` for functions containing `docker exec`, `ssh`, etc. -- use script-scoped variables for return values (see gotchas.md) |
diff --git a/.claude/skills/shell-scripting/references/testing.md b/.claude/skills/shell-scripting/references/testing.md
new file mode 100644
index 0000000..c3f9fb6
--- /dev/null
+++ b/.claude/skills/shell-scripting/references/testing.md
@@ -0,0 +1,438 @@
+# Testing Shell Scripts
+
+Testing strategies for Bash and PowerShell scripts in DAAF. Covers BATS for Bash, Pester for PowerShell, CI workflow configuration, Docker mocking strategies, and test taxonomy.
+
+---
+
+## Test Taxonomy
+
+Not all tests are equal. Use the right level for the right purpose:
+
+| Level | Docker Required | Run When | What It Verifies |
+|-------|-----------------|----------|------------------|
+| **Lint** (ShellCheck + PSScriptAnalyzer) | No | Every push | Syntax, quoting, known bug patterns |
+| **Unit** (mocked externals) | No | Every push | Logic, argument parsing, error paths, output formatting |
+| **Smoke** (`--help`, `--dry-run`) | No | Every push | Script loads, prints usage, exits cleanly |
+| **Integration** (real Docker) | Yes | Manual / nightly | End-to-end behavior with actual containers |
+
+**What to test:**
+- Argument parsing and validation
+- Error paths (missing files, missing tools, bad input)
+- Output formatting (correct messages, correct stream)
+- Exit codes (0 for success, correct non-zero for each failure mode)
+- Preflight checks (dependency detection)
+- Idempotency (safe to run twice)
+
+**What to skip:**
+- Actual Docker builds (slow, flaky, need real daemon)
+- Network operations (use mocks or recorded responses)
+- Full directory tree creation (test the logic, not the filesystem)
+
+---
+
+## BATS (Bash Automated Testing System)
+
+### Setup
+
+Use [bats-core](https://github.com/bats-core/bats-core) (the actively maintained fork) with helper libraries:
+
+```bash
+# Add as git submodules
+git submodule add https://github.com/bats-core/bats-core.git test/libs/bats
+git submodule add https://github.com/bats-core/bats-support.git test/libs/bats-support
+git submodule add https://github.com/bats-core/bats-assert.git test/libs/bats-assert
+git submodule add https://github.com/bats-core/bats-file.git test/libs/bats-file
+```
+
+### File Naming Convention
+
+```
+tests/bash/{script_name}.bats
+```
+
+Example: tests for `install_daaf.sh` go in `tests/bash/install_daaf.bats`.
+
+### Basic Test Structure
+
+```bash
+#!/usr/bin/env bats
+
+# Load helper libraries
+load '../libs/bats-support/load'
+load '../libs/bats-assert/load'
+
+# --- Setup/Teardown ---
+
+setup() {
+    # Create temp directory for test isolation
+    TEST_DIR="$(mktemp -d)"
+    export TEST_DIR
+}
+
+teardown() {
+    rm -rf "$TEST_DIR"
+}
+
+# --- Tests ---
+
+@test "shows usage when no arguments provided" {
+    run bash ./scripts/my_script.sh
+    assert_failure
+    assert_output --partial "Usage:"
+}
+
+@test "exits 0 on valid input" {
+    run bash ./scripts/my_script.sh "$TEST_DIR/valid-input.txt"
+    assert_success
+}
+
+@test "exits 1 when input file does not exist" {
+    run bash ./scripts/my_script.sh "/nonexistent/path"
+    assert_failure
+    assert_output --partial "ERROR:"
+}
+
+@test "error messages go to stderr" {
+    run bash ./scripts/my_script.sh "/nonexistent/path"
+    assert_failure
+    # bats captures both stdout and stderr in $output by default
+    assert_output --partial "ERROR:"
+}
+```
+
+### Key BATS Assertions
+
+| Assertion | What It Checks |
+|-----------|---------------|
+| `assert_success` | Exit code is 0 |
+| `assert_failure` | Exit code is non-zero |
+| `assert_output "exact text"` | Exact match on combined stdout+stderr |
+| `assert_output --partial "text"` | Substring match |
+| `assert_line --index 0 "text"` | First line matches |
+| `refute_output --partial "text"` | Text is NOT in output |
+| `assert_equal "$actual" "$expected"` | String equality |
+
+### Running Tests
+
+```bash
+# Run all tests
+./test/libs/bats/bin/bats tests/bash/
+
+# Run a specific test file
+./test/libs/bats/bin/bats tests/bash/install_daaf.bats
+
+# Run with TAP output (for CI)
+./test/libs/bats/bin/bats --tap tests/bash/
+```
+
+---
+
+## Docker Mocking (Bash)
+
+Most DAAF scripts call Docker. For unit tests, mock it:
+
+### Strategy 1: Function Override (Simplest)
+
+Override the `docker` command with a function, then export it so subshells see it:
+
+```bash
+setup() {
+    # Track calls for verification
+    DOCKER_CALLS=()
+    MOCK_DOCKER_EXIT=0
+
+    docker() {
+        DOCKER_CALLS+=("$*")
+        return "$MOCK_DOCKER_EXIT"
+    }
+    export -f docker
+}
+
+@test "calls docker compose up" {
+    run bash ./scripts/start.sh
+    assert_success
+
+    # Verify docker was called with expected arguments
+    [[ "${DOCKER_CALLS[0]}" == *"compose up"* ]]
+}
+
+@test "handles docker failure" {
+    MOCK_DOCKER_EXIT=1
+
+    run bash ./scripts/start.sh
+    assert_failure
+    assert_output --partial "ERROR"
+}
+```
+
+### Strategy 2: bats-mock (For Verifying Call Sequences)
+
+When you need to verify the exact sequence and arguments of Docker calls:
+
+```bash
+load '../libs/bats-mock/stub'
+
+setup() {
+    stub docker \
+        "info : echo 'Docker is running'" \
+        "compose up -d : echo 'Started'"
+}
+
+teardown() {
+    unstub docker
+}
+
+@test "checks docker info before compose up" {
+    run bash ./scripts/start.sh
+    assert_success
+    # unstub verifies all expected calls were made in order
+}
+```
+
+### Strategy 3: PATH Manipulation
+
+Create a fake `docker` script in a temp directory and prepend it to PATH:
+
+```bash
+setup() {
+    MOCK_BIN="$(mktemp -d)"
+    cat > "$MOCK_BIN/docker" <<'MOCK'
+#!/usr/bin/env bash
+echo "mock-docker: $*" >> "${MOCK_LOG:-/dev/null}"
+exit "${MOCK_DOCKER_EXIT:-0}"
+MOCK
+    chmod +x "$MOCK_BIN/docker"
+    export PATH="$MOCK_BIN:$PATH"
+    export MOCK_LOG="$MOCK_BIN/calls.log"
+}
+
+teardown() {
+    rm -rf "$MOCK_BIN"
+}
+```
+
+---
+
+## Pester (PowerShell)
+
+### Setup
+
+Pester v5.7+ comes pre-installed with PowerShell 7. For PowerShell 5.1:
+
+```powershell
+Install-Module -Name Pester -Force -SkipPublisherCheck -MinimumVersion 5.7.0
+```
+
+### File Naming Convention
+
+```
+tests/powershell/{ScriptName}.Tests.ps1
+```
+
+Example: tests for `Install-DAAF.ps1` go in `tests/powershell/Install-DAAF.Tests.ps1`.
+
+### Basic Test Structure
+
+```powershell
+Describe "Install-DAAF" {
+
+    BeforeAll {
+        # Source the script under test
+        . $PSScriptRoot/../../scripts/Install-DAAF.ps1
+    }
+
+    Context "when Docker is not installed" {
+        BeforeAll {
+            # Must declare the function before mocking
+            function docker {}
+            Mock docker { throw "not found" }
+        }
+
+        It "exits with error" {
+            { Install-DaafComponent -ComponentName "test" } | Should -Throw
+        }
+
+        It "displays an actionable error message" {
+            # Capture error output
+            try {
+                Install-DaafComponent -ComponentName "test"
+            }
+            catch {
+                $_.Exception.Message | Should -BeLike "*Docker*"
+            }
+        }
+    }
+
+    Context "when Docker is running" {
+        BeforeAll {
+            function docker {}
+            Mock docker {
+                $global:LASTEXITCODE = 0
+                return "mock output"
+            }
+        }
+
+        It "completes successfully" {
+            { Install-DaafComponent -ComponentName "test" } | Should -Not -Throw
+        }
+
+        It "calls docker with correct arguments" {
+            Install-DaafComponent -ComponentName "test"
+            Should -Invoke docker -Times 1 -ParameterFilter {
+                $args -contains "build"
+            }
+        }
+    }
+}
+```
+
+### Key Pester Assertions
+
+| Assertion | What It Checks |
+|-----------|---------------|
+| `Should -Be $expected` | Exact equality |
+| `Should -BeLike "*pattern*"` | Wildcard match |
+| `Should -BeTrue` | Boolean true |
+| `Should -Throw` | Exception thrown |
+| `Should -Not -Throw` | No exception |
+| `Should -Invoke cmd -Times N` | Mock called N times |
+
+### Mocking Native Commands in Pester
+
+PowerShell cannot mock native commands directly. Declare a dummy function first, then mock it:
+
+```powershell
+# Step 1: Declare a function with the same name
+function docker {}
+
+# Step 2: Mock the function
+Mock docker {
+    $global:LASTEXITCODE = 0
+    return "mock output"
+}
+
+# Step 3: Verify calls
+Should -Invoke docker -Times 2
+```
+
+**For testing $LASTEXITCODE behavior:**
+
+```powershell
+# Simulate docker failure
+Mock docker {
+    $global:LASTEXITCODE = 1
+    # Return nothing — simulates a failed build
+}
+
+It "detects docker build failure" {
+    { Start-DockerBuild } | Should -Throw "*failed*"
+}
+```
+
+### Running Tests
+
+```powershell
+# Run all tests
+Invoke-Pester -Path ./tests/powershell/ -Output Detailed
+
+# Run with code coverage
+Invoke-Pester -Path ./tests/powershell/ -CodeCoverage ./scripts/*.ps1
+
+# Run with CI output
+Invoke-Pester -Path ./tests/powershell/ -CI
+```
+
+---
+
+## CI Workflow (GitHub Actions)
+
+### Recommended Matrix
+
+```yaml
+name: Shell Script CI
+
+on:
+  push:
+    paths:
+      - '**.sh'
+      - '**.ps1'
+      - '**.bats'
+      - '**/Tests.ps1'
+      - '.github/workflows/shell-ci.yml'
+  pull_request:
+    paths:
+      - '**.sh'
+      - '**.ps1'
+      - '**.bats'
+      - '**/Tests.ps1'
+
+jobs:
+  shellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ludeeus/action-shellcheck@2.0.0
+        with:
+          severity: warning
+          scandir: ./scripts
+
+  psscriptanalyzer:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: devblackops/github-action-psscriptanalyzer@v2
+        with:
+          path: ./scripts
+          recurse: true
+          output: results.sarif
+
+  bats-tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - uses: bats-core/bats-action@4.0.0
+        with:
+          tests: tests/bash/
+
+  pester-tests:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - shell: pwsh
+        run: |
+          Invoke-Pester -Path ./tests/powershell/ -CI -Output Detailed
+```
+
+### Key Points
+
+- **Path filtering:** Only run when shell-related files change (saves CI minutes)
+- **ShellCheck:** Ubuntu only (same results cross-platform)
+- **PSScriptAnalyzer:** Ubuntu only (same results cross-platform)
+- **BATS:** Ubuntu + macOS (covers most Bash environments; skip Windows)
+- **Pester:** All three OS (PowerShell behavior varies across platforms)
+- **Submodules:** Required for BATS helper libraries
+
+---
+
+## Test Checklist
+
+When adding tests for a new script:
+
+| # | Item | Notes |
+|---|------|-------|
+| 1 | `--help` / no-args shows usage | Smoke test |
+| 2 | Valid input exits 0 | Happy path |
+| 3 | Missing file exits non-zero with error | Error path |
+| 4 | Missing dependency detected | Preflight check |
+| 5 | Error messages include remediation | Two-part errors |
+| 6 | Docker calls use mocks (not real daemon) | Unit test isolation |
+| 7 | Idempotent: running twice is safe | Re-run test |
+| 8 | Exit codes match documented conventions | See error-handling.md |
diff --git a/.claude/skills/skill-authoring/references/frontmatter.md b/.claude/skills/skill-authoring/references/frontmatter.md
index fbdb73b..e93ade8 100644
--- a/.claude/skills/skill-authoring/references/frontmatter.md
+++ b/.claude/skills/skill-authoring/references/frontmatter.md
@@ -254,10 +254,7 @@ Unknown frontmatter fields are ignored but may cause validation errors in strict
 ---
 name: polars
 description: >-
-  Polars DataFrame library for high-performance data manipulation. Lazy/eager
-  execution, expressions, I/O (CSV, Parquet, JSON), aggregations, joins,
-  string/datetime ops, pandas interop. Use for Polars DataFrames or
-  reading/writing Parquet files.
+  High-performance data manipulation with lazy/eager execution, expressions, I/O (CSV, Parquet, JSON), aggregations, joins, string/datetime ops, and pandas interop. Covers performance optimization patterns and common anti-patterns. DAAF's default DataFrame library — all pipeline code uses Polars, not pandas. Use for any DataFrame operation, reading/writing Parquet files, or migrating existing pandas code to Polars.
 metadata:
   audience: research-coders
   domain: python-library
@@ -275,7 +272,7 @@ from pandas, reading Parquet files, or optimizing data pipeline performance.
 [Rest of skill body...]
 ```
 
-Note how the frontmatter description (243 chars) captures the essentials, while the body paragraph preserves the full detail including database I/O, NumPy interop, and migration use cases that didn't fit.
+Note how the frontmatter description (418 chars) leads with DAAF-specific identity ("default DataFrame library — not pandas"), then covers capabilities and use triggers. The body paragraph preserves additional detail (database I/O, NumPy interop) that didn't fit even in the expanded description. Descriptions can be up to 1,536 characters; use the extra space strategically for framework context, critical caveats, and disambiguation — not for exhaustive feature lists.
 
 ## Description Writing Tips
 
diff --git a/.claude/skills/svy/SKILL.md b/.claude/skills/svy/SKILL.md
index 2cff57a..c3bc302 100644
--- a/.claude/skills/svy/SKILL.md
+++ b/.claude/skills/svy/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: svy
 description: >-
-  Complex survey analysis: strata/PSU/weights, variance estimation (Taylor, BRR, jackknife, bootstrap), survey GLM, domain analysis, calibration. Polars-native. Use for NHANES, CPS, ACS PUMS, BRFSS, DHS. Non-survey regression: statsmodels/pyfixest.
+  Complex survey analysis: strata/PSU/weights, variance estimation (Taylor, BRR, jackknife, bootstrap), survey GLM, domain analysis, calibration, survey data I/O (SAS, SPSS, Stata formats). Polars-native. Use for any complex-sample survey: NHANES, CPS, ACS PUMS, BRFSS, DHS, ECLS-K, MEPS-HC. CRITICAL: statsmodels WLS and pyfixest clustered SEs are NOT substitutes for proper survey-weighted analysis — they ignore stratification and unequal probability sampling. Non-survey regression: statsmodels/pyfixest.
 metadata:
   audience: research-coders
   domain: python-library
diff --git a/.claudeignore b/.claudeignore
index b60c79e..779b944 100644
--- a/.claudeignore
+++ b/.claudeignore
@@ -3,6 +3,8 @@
 .env.*
 .env.local
 .env.production
+environment_settings.txt
+environment_settings*.txt
 *.pem
 *.key
 *.p12
diff --git a/.github/linters/PSScriptAnalyzerSettings.psd1 b/.github/linters/PSScriptAnalyzerSettings.psd1
new file mode 100644
index 0000000..1ec0de5
--- /dev/null
+++ b/.github/linters/PSScriptAnalyzerSettings.psd1
@@ -0,0 +1,29 @@
+# PSScriptAnalyzer Settings for DAAF
+#
+# Configuration for PSScriptAnalyzer linting of all .ps1 scripts.
+# Used by CI (ci-scripts.yml) and local development.
+#
+# Run locally:
+#   Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser
+#   Invoke-ScriptAnalyzer -Path . -Recurse -Settings ./PSScriptAnalyzerSettings.psd1
+#
+# Severity levels included: Error, Warning
+# Information-level rules are excluded — too noisy for CI gating.
+
+@{
+    Severity = @('Error', 'Warning')
+
+    ExcludeRules = @(
+        # All DAAF scripts are CLI tools that intentionally use Write-Host
+        # for user-facing output (colored progress messages, status indicators).
+        # Write-Host is the correct choice for these scripts — they are not
+        # library functions where output stream purity matters.
+        'PSAvoidUsingWriteHost',
+
+        # DAAF_DRY_RUN mode intentionally overrides Invoke-WebRequest with a
+        # mock function that creates empty stub files instead of making real
+        # HTTP calls. This is by design for CI cross-platform smoke testing
+        # without network access.
+        'PSAvoidOverwritingBuiltInCmdlets'
+    )
+}
diff --git a/.github/workflows/ci-integration.yml b/.github/workflows/ci-integration.yml
new file mode 100644
index 0000000..ceb15e2
--- /dev/null
+++ b/.github/workflows/ci-integration.yml
@@ -0,0 +1,799 @@
+# CI: Docker Integration Tests
+#
+# End-to-end tests for DAAF's host lifecycle scripts running against a real
+# Docker daemon. Verifies install, run, backup, update, rebuild, and migrate
+# workflows behave correctly with actual containers and volumes.
+#
+# Companion workflow: ci-scripts.yml handles lint, unit tests, and cross-platform
+# dry-run smoke tests (no Docker required).
+#
+# Four jobs:
+#   1. lifecycle-test       - Full lifecycle: install -> run -> backup -> update -> rebuild
+#   2. migrate-era1         - Migration of clone-based installations (origin remote present)
+#   3. migrate-era2         - Migration of ZIP-based installations (no remote, requires graft)
+#   4. failure-resilience   - Graceful failure handling and edge cases
+#
+# Not tested here:
+#   - view_logs.sh/ps1: Invokes `docker compose logs --follow`, which is a
+#     blocking/streaming command unsuitable for CI. Covered by dry-run smoke
+#     tests in ci-scripts.yml.
+#   - Windows Docker integration: GitHub-hosted Windows runners have Docker
+#     configured for Windows containers, not Linux containers. DAAF uses Linux
+#     containers. Windows PowerShell logic is covered by the dry-run smoke
+#     tests in ci-scripts.yml.
+#
+# Triggers: weekly (Sunday 6 AM UTC), manual dispatch, release tags,
+#   push/PR when Dockerfile, docker-compose.yml, or host scripts change.
+# All jobs run on both ubuntu-latest (amd64) and ubuntu-24.04-arm (arm64)
+# with a 30-minute timeout.
+
+name: CI - Integration
+
+on:
+  schedule:
+    - cron: '0 6 * * 0'  # Weekly on Sunday at 6 AM UTC
+  workflow_dispatch: {}
+  push:
+    branches: ['**']
+    tags: ['v*']
+    paths:
+      - 'Dockerfile'
+      - 'docker-compose.yml'
+      - 'scripts/host/**'
+      - '.github/workflows/ci-integration.yml'
+  pull_request:
+    paths:
+      - 'Dockerfile'
+      - 'docker-compose.yml'
+      - 'scripts/host/**'
+      - '.github/workflows/ci-integration.yml'
+
+permissions:
+  contents: read
+
+# DAAF_BRANCH tells all lifecycle scripts which branch to download from and
+# target. Resolves to the branch name for schedule/dispatch, or the tag name
+# for release-tag pushes (git treats tags as valid refs for --branch).
+# DAAF_NESTED suppresses the interactive pause-before-exit in all scripts.
+env:
+  DAAF_BRANCH: ${{ github.ref_name }}
+  DAAF_NESTED: "1"
+
+# ---------------------------------------------------------------------------
+# Job 1: Full lifecycle — install, run, backup, update, rebuild
+# ---------------------------------------------------------------------------
+# Exercises the standard user journey: install DAAF from scratch, verify the
+# container is operational, run a command inside it, create a backup, attempt
+# an update (no-op on fresh install), rebuild the image, and confirm
+# everything still works afterward.
+jobs:
+  lifecycle-test:
+    name: Lifecycle Test (${{ matrix.runner }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-latest, ubuntu-24.04-arm]
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # --- Install ---
+      # install.sh creates daaf-docker/ in the current working directory,
+      # downloads docker-compose.yml, Dockerfile, and all host scripts there,
+      # builds the Docker image, and clones the repo into the container.
+      - name: Install DAAF via install.sh
+        run: bash scripts/host/install.sh
+
+      # --- Verify container is running ---
+      # install.sh has its own readiness wait, but add a retry loop as a
+      # safety net for slow CI runners. docker compose ps shows "Up" in the
+      # STATUS column (not "running").
+      - name: Verify container is running
+        working-directory: daaf-docker
+        run: |
+          for i in 1 2 3 4 5; do
+            docker compose ps | grep -q "Up" && exit 0
+            echo "Waiting for container to be ready (attempt $i/5)..."
+            sleep 3
+          done
+          echo "ERROR: Container did not reach running state"
+          docker compose ps
+          exit 1
+
+      # --- Verify CLAUDE.md exists in the container ---
+      - name: Verify CLAUDE.md present in container
+        working-directory: daaf-docker
+        run: docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md
+
+      # --- Run a quick command inside the container ---
+      # Uses the downloaded copy of run_daaf.sh (as a real user would).
+      - name: Run test command via run_daaf.sh
+        working-directory: daaf-docker
+        run: bash run_daaf.sh echo "DAAF is working"
+
+      # --- Backup ---
+      - name: Create backup via backup_daaf.sh
+        working-directory: daaf-docker
+        run: bash backup_daaf.sh
+
+      # backup_daaf.sh creates YYYY-MM-DD_daaf_backup/ in the current directory
+      - name: Verify backup directory was created
+        working-directory: daaf-docker
+        run: ls -la *_daaf_backup/
+
+      # --- Restore from backup (round-trip test) ---
+      # The restore script detects the running container and offers to stop it.
+      # Pipe: "y" (accept stop), "1" (select first backup), "RESTORE" (confirm).
+      - name: Restore from backup via restore_from_backup.sh
+        working-directory: daaf-docker
+        run: printf 'y\n1\nRESTORE\n' | bash restore_from_backup.sh
+
+      - name: Start container after restore
+        working-directory: daaf-docker
+        run: docker compose up -d
+
+      - name: Wait for container readiness after restore
+        working-directory: daaf-docker
+        run: |
+          for i in 1 2 3 4 5; do
+            docker compose ps | grep -q "Up" && exit 0
+            echo "Waiting for container to be ready (attempt $i/5)..."
+            sleep 3
+          done
+          echo "ERROR: Container did not reach running state after restore"
+          docker compose ps
+          exit 1
+
+      - name: Verify CLAUDE.md present after restore
+        working-directory: daaf-docker
+        run: docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md
+
+      # --- Update (no-op on fresh install) ---
+      - name: Run update_daaf.sh (no-op on fresh install)
+        working-directory: daaf-docker
+        run: bash update_daaf.sh
+
+      - name: Verify container running after update
+        working-directory: daaf-docker
+        run: docker compose ps | grep -q "Up"
+
+      # --- Simulate user work-in-progress ---
+      # Add a committed file and an uncommitted file to verify that rebuild
+      # preserves user data. Placed after update (which is a no-op on a fresh
+      # install) so the local commit doesn't trigger update's interactive
+      # prompt_choice for "ahead" branches.
+      - name: Add committed research file
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            mkdir -p /daaf/research
+            echo "My analysis notes" > /daaf/research/local_work.txt
+            git -C /daaf add research/local_work.txt
+            git -C /daaf commit -m "Local research work"
+          '
+
+      - name: Add uncommitted file edit
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            echo "Work in progress" > /daaf/research/uncommitted_draft.txt
+          '
+
+      # --- Rebuild ---
+      - name: Rebuild image via rebuild_daaf.sh
+        working-directory: daaf-docker
+        run: bash rebuild_daaf.sh
+
+      # --- Post-rebuild verification ---
+      - name: Verify container running after rebuild
+        working-directory: daaf-docker
+        run: docker compose ps | grep -q "Up"
+
+      - name: Verify CLAUDE.md present after rebuild
+        working-directory: daaf-docker
+        run: docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md
+
+      # --- Verify user work survived rebuild ---
+      - name: Verify committed file preserved after rebuild
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "My analysis notes" /daaf/research/local_work.txt
+            git -C /daaf log --oneline -1 | grep -q "Local research work"
+          '
+
+      - name: Verify uncommitted file preserved after rebuild
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "Work in progress" /daaf/research/uncommitted_draft.txt
+          '
+
+      # --- Multiple backups in one day ---
+      - name: Create second backup (suffix test)
+        working-directory: daaf-docker
+        run: bash backup_daaf.sh
+
+      - name: Verify two backup directories exist with date suffix
+        working-directory: daaf-docker
+        run: |
+          count=$(ls -d *_daaf_backup 2>/dev/null | wc -l)
+          echo "Found $count backup directories"
+          if [ "$count" -lt 2 ]; then
+            echo "ERROR: Expected at least 2 backup directories"
+            ls -la *_daaf_backup* 2>/dev/null || true
+            exit 1
+          fi
+
+      # --- Rebuild with no changes ---
+      - name: Rebuild again (no-changes test)
+        working-directory: daaf-docker
+        run: bash rebuild_daaf.sh 2>&1 | tee /tmp/rebuild_nochange.txt
+
+      - name: Verify no-changes message
+        run: grep -qi "No changes detected" /tmp/rebuild_nochange.txt
+
+      # --- Update with no upstream changes ---
+      - name: Run update (no-op after fresh install)
+        working-directory: daaf-docker
+        run: bash update_daaf.sh 2>&1 | tee /tmp/update_noop.txt
+
+      - name: Verify already up to date
+        run: grep -qi "Already up to date" /tmp/update_noop.txt
+
+      # --- Cleanup ---
+      # Use conditional directory check because install.sh may not have created
+      # daaf-docker/ if it failed early.
+      - name: Docker cleanup
+        if: always()
+        run: |
+          if [ -d daaf-docker ]; then
+            cd daaf-docker
+            docker compose down -v --rmi local --remove-orphans
+          fi
+
+  # ---------------------------------------------------------------------------
+  # Job 2: Migration — Era 1 (clone-based installation)
+  # ---------------------------------------------------------------------------
+  # Simulates how Era 1 users actually installed DAAF: they ran git clone
+  # directly, then docker compose up. No install.sh existed yet. The container
+  # has /daaf populated via git clone with origin configured.
+  # migrate_daaf.sh should detect "clone-based installation" and succeed.
+  # The second run tests idempotency.
+  migrate-era1:
+    name: Migrate (Era 1 - Clone) (${{ matrix.runner }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-latest, ubuntu-24.04-arm]
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # --- Simulate Era 1 installation (git clone + docker compose up) ---
+      # Era 1 users cloned the repo on their host, then ran docker compose up.
+      # We replicate this by: (1) building the container from the repo's
+      # Dockerfile/docker-compose.yml, then (2) git cloning inside the container
+      # (exactly what Era 1 users' startup process did).
+      - name: Build and start container
+        run: docker compose up -d --build
+
+      - name: Wait for container readiness
+        run: |
+          for i in 1 2 3 4 5; do
+            docker compose ps | grep -q "Up" && exit 0
+            sleep 3
+          done
+          echo "ERROR: Container not ready"; docker compose ps; exit 1
+
+      - name: Populate /daaf via git clone (Era 1 method)
+        run: |
+          docker compose exec -T daaf-docker \
+            git clone -b "$DAAF_BRANCH" \
+            "https://github.com/DAAF-Contribution-Community/daaf.git" /tmp/daaf-clone
+          docker compose exec -T daaf-docker \
+            bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone'
+
+      - name: Verify DAAF files present
+        run: docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md
+
+      # --- Pre-migration verification: confirm Era 1 simulation fidelity ---
+      # These checks verify the simulated environment matches what real Era 1
+      # (clone-based) installations looked like, BEFORE migration runs.
+      - name: "Pre-migration: verify origin remote exists (Era 1 marker)"
+        run: |
+          url=$(docker compose exec -T daaf-docker git -C /daaf remote get-url origin 2>/dev/null)
+          echo "Origin URL: $url"
+          echo "$url" | grep -qi "DAAF-Contribution-Community/daaf"
+
+      - name: "Pre-migration: verify .claude/agents/ exists (current-branch files)"
+        run: docker compose exec -T daaf-docker test -d /daaf/.claude/agents
+
+      - name: "Pre-migration: verify top-level agents/ does not exist (post-v1 layout)"
+        run: |
+          if docker compose exec -T daaf-docker test -d /daaf/agents 2>/dev/null; then
+            echo "ERROR: top-level agents/ should not exist on current branch"
+            exit 1
+          fi
+          echo "Confirmed: no top-level agents/ directory"
+
+      # --- Simulate user work-in-progress ---
+      - name: Add committed research file
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            mkdir -p /daaf/research
+            echo "My analysis notes" > /daaf/research/local_work.txt
+            git -C /daaf add research/local_work.txt
+            git -C /daaf commit -m "Local research work"
+          '
+
+      - name: Add uncommitted file edit
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            echo "Work in progress" > /daaf/research/uncommitted_draft.txt
+          '
+
+      # migrate_daaf.sh discovers the container via the daaf_daaf-data volume.
+      # It needs docker-compose.yml in the current directory to run backup.
+      - name: Run migrate_daaf.sh (should detect Era 1)
+        id: migrate_era1
+        run: bash scripts/host/migrate_daaf.sh 2>&1 | tee /tmp/migrate_era1_output.txt
+
+      # --- Post-migration verification: confirm Era 1 path was taken ---
+      - name: "Post-migration: verify 'clone-based' detected in output"
+        run: grep -qi "clone-based" /tmp/migrate_era1_output.txt
+
+      - name: "Post-migration: verify branch tracks origin"
+        run: |
+          tracking=$(docker compose exec -T daaf-docker \
+            git -C /daaf rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || true)
+          echo "Tracking: $tracking"
+          echo "$tracking" | grep -q "origin/"
+
+      # Verify origin remote is configured and points to the repo
+      - name: Verify origin remote is configured
+        run: docker compose exec -T daaf-docker git -C /daaf remote -v
+
+      # Verify fetch works (future updates will succeed)
+      - name: Verify git fetch origin succeeds
+        run: docker compose exec -T daaf-docker git -C /daaf fetch origin
+
+      # Run again to confirm idempotency — should succeed without errors
+      - name: Run migrate_daaf.sh again (idempotency check)
+        run: bash scripts/host/migrate_daaf.sh 2>&1 | tee /tmp/migrate_era1_idem.txt
+
+      - name: "Idempotency: verify Migration complete on re-run"
+        run: grep -qi "Migration complete" /tmp/migrate_era1_idem.txt
+
+      # --- Verify user work survived migration ---
+      - name: Verify committed file preserved after migration
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "My analysis notes" /daaf/research/local_work.txt
+            git -C /daaf log --oneline | grep -q "Local research work"
+          '
+
+      - name: Verify uncommitted file preserved after migration
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "Work in progress" /daaf/research/uncommitted_draft.txt
+          '
+
+      # --- Cleanup ---
+      - name: Docker cleanup
+        if: always()
+        run: docker compose down -v --rmi local --remove-orphans
+
+  # ---------------------------------------------------------------------------
+  # Job 3: Migration — Era 2 (ZIP-based installation, no remote)
+  # ---------------------------------------------------------------------------
+  # Simulates how Era 2 users actually installed DAAF: they downloaded a ZIP
+  # from GitHub, extracted it, and ran docker compose up. No git remote exists.
+  # The container has DAAF files with local git history but no origin.
+  # migrate_daaf.sh should detect "ZIP-based installation", add origin, fetch
+  # upstream history, and graft local history onto it.
+  migrate-era2:
+    name: Migrate (Era 2 - ZIP) (${{ matrix.runner }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-latest, ubuntu-24.04-arm]
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # --- Simulate Era 2 installation (ZIP extraction + docker compose up) ---
+      # Era 2 users downloaded a ZIP from a specific release tag, extracted it,
+      # and ran docker compose up. We replicate this by: (1) building the
+      # container, then (2) cloning a known tag inside the container (to get
+      # files matching a real historical commit), then (3) stripping .git and
+      # re-initializing as a local-only repo (matching what ZIP users had).
+      # Using v2.0.0 files ensures the migration's blob-tree search finds an
+      # exact match against the upstream v2.0.0 tag.
+      - name: Build and start container
+        run: docker compose up -d --build
+
+      - name: Wait for container readiness
+        run: |
+          for i in 1 2 3 4 5; do
+            docker compose ps | grep -q "Up" && exit 0
+            sleep 3
+          done
+          echo "ERROR: Container not ready"; docker compose ps; exit 1
+
+      - name: Populate /daaf with v2.0.0 files (ZIP simulation)
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            git clone --depth 1 -b v2.0.0 \
+              https://github.com/DAAF-Contribution-Community/daaf.git /tmp/daaf-zip
+            rm -rf /tmp/daaf-zip/.git
+            cp -a /tmp/daaf-zip/. /daaf/
+            rm -rf /tmp/daaf-zip
+          '
+
+      - name: Initialize local git repo (as ZIP users would have)
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            cd /daaf
+            git init
+            git branch -m main
+            git add -A
+            git commit -m "Initial DAAF installation"
+          '
+
+      - name: Verify no remote exists
+        run: |
+          output=$(docker compose exec -T daaf-docker git -C /daaf remote -v 2>&1 || true)
+          if echo "$output" | grep -q "origin"; then
+            echo "ERROR: origin remote should not exist in ZIP simulation"
+            exit 1
+          fi
+          echo "Confirmed: no origin remote (ZIP simulation correct)"
+
+      - name: Verify DAAF files present
+        run: docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md
+
+      # --- Pre-migration verification: confirm Era 2 simulation fidelity ---
+      # These checks verify the simulated environment matches what real Era 2
+      # (ZIP-based v2.0.0) installations looked like, BEFORE migration runs.
+      # v2.0.0 had scripts/entrypoint.sh (removed in current era) and
+      # .claude/agents/ (moved from top-level agents/ in v1.0.0).
+      - name: "Pre-migration: verify scripts/entrypoint.sh exists (v2.0.0 marker)"
+        run: docker compose exec -T daaf-docker test -f /daaf/scripts/entrypoint.sh
+
+      - name: "Pre-migration: verify .claude/agents/ exists (v2.0.0 layout)"
+        run: docker compose exec -T daaf-docker test -d /daaf/.claude/agents
+
+      - name: "Pre-migration: verify top-level agents/ does not exist (v1-only)"
+        run: |
+          if docker compose exec -T daaf-docker test -d /daaf/agents 2>/dev/null; then
+            echo "ERROR: top-level agents/ should not exist in v2.0.0 layout"
+            exit 1
+          fi
+          echo "Confirmed: no top-level agents/ directory (correct for v2.0.0)"
+
+      - name: "Pre-migration: verify no tests/ directory (post-v2 only)"
+        run: |
+          if docker compose exec -T daaf-docker test -d /daaf/tests 2>/dev/null; then
+            echo "ERROR: tests/ should not exist in v2.0.0 layout"
+            exit 1
+          fi
+          echo "Confirmed: no tests/ directory (correct for v2.0.0)"
+
+      - name: "Pre-migration: verify no scripts/host/ directory (post-v2 only)"
+        run: |
+          if docker compose exec -T daaf-docker test -d /daaf/scripts/host 2>/dev/null; then
+            echo "ERROR: scripts/host/ should not exist in v2.0.0 layout"
+            exit 1
+          fi
+          echo "Confirmed: no scripts/host/ directory (correct for v2.0.0)"
+
+      - name: "Pre-migration: verify CITATION.cff exists (added in v2.0.0)"
+        run: docker compose exec -T daaf-docker test -f /daaf/CITATION.cff
+
+      # --- Simulate user work-in-progress ---
+      - name: Add committed research file
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            mkdir -p /daaf/research
+            echo "My analysis notes" > /daaf/research/local_work.txt
+            git -C /daaf add research/local_work.txt
+            git -C /daaf commit -m "Local research work"
+          '
+
+      - name: Add uncommitted file edit
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            echo "Work in progress" > /daaf/research/uncommitted_draft.txt
+          '
+
+      # Run migrate — should detect Era 2, add origin, fetch, and graft
+      - name: Run migrate_daaf.sh (should detect Era 2)
+        id: migrate_era2
+        run: bash scripts/host/migrate_daaf.sh 2>&1 | tee /tmp/migrate_era2_output.txt
+
+      # --- Post-migration verification: confirm Era 2 path was taken ---
+      - name: "Post-migration: verify 'ZIP-based' detected in output"
+        run: grep -qi "ZIP-based" /tmp/migrate_era2_output.txt
+
+      - name: "Post-migration: verify graft was applied (initial commit has parent)"
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            initial=$(git -C /daaf rev-list --max-parents=0 HEAD | tail -1)
+            parent_count=$(git -C /daaf cat-file -p "$initial" | grep -c "^parent " || echo "0")
+            echo "Initial commit: $initial"
+            echo "Parent count: $parent_count"
+            if [ "$parent_count" -eq 0 ]; then
+              echo "ERROR: graft was not applied — initial commit has no parent"
+              exit 1
+            fi
+            echo "Confirmed: graft applied (initial commit has $parent_count parent(s))"
+          '
+
+      - name: "Post-migration: verify branch tracks origin"
+        run: |
+          tracking=$(docker compose exec -T daaf-docker \
+            git -C /daaf rev-parse --abbrev-ref --symbolic-full-name '@{u}' 2>/dev/null || true)
+          echo "Tracking: $tracking"
+          echo "$tracking" | grep -q "origin/"
+
+      # Verify origin was added
+      - name: Verify origin remote was added
+        run: docker compose exec -T daaf-docker git -C /daaf remote -v | grep origin
+
+      # Verify fetch works (graft connected the histories)
+      - name: Verify git fetch origin succeeds
+        run: docker compose exec -T daaf-docker git -C /daaf fetch origin
+
+      # Run again to confirm idempotency — graft already in place
+      - name: Run migrate_daaf.sh again (idempotency check)
+        run: bash scripts/host/migrate_daaf.sh 2>&1 | tee /tmp/migrate_era2_idem.txt
+
+      # After migration, origin remote exists so the re-run detects Era 1
+      # (clone-based) rather than re-entering the Era 2 graft path. The
+      # correct idempotency check is that migration completes successfully.
+      - name: "Idempotency: verify Migration complete on re-run"
+        run: grep -qi "Migration complete" /tmp/migrate_era2_idem.txt
+
+      # --- Verify file permissions after migration ---
+      - name: Verify .sh files are executable after migration
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            non_exec=$(find /daaf -name "*.sh" -not -perm /111 2>/dev/null | head -5)
+            if [ -n "$non_exec" ]; then
+              echo "WARNING: Non-executable .sh files found after migration:"
+              echo "$non_exec"
+            fi
+            echo "Permission check complete"
+          '
+
+      # --- Verify user work survived migration ---
+      - name: Verify committed file preserved after migration
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "My analysis notes" /daaf/research/local_work.txt
+            git -C /daaf log --oneline | grep -q "Local research work"
+          '
+
+      - name: Verify uncommitted file preserved after migration
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "Work in progress" /daaf/research/uncommitted_draft.txt
+          '
+
+      # --- Cleanup ---
+      - name: Docker cleanup
+        if: always()
+        run: docker compose down -v --rmi local --remove-orphans
+
+  # ---------------------------------------------------------------------------
+  # Job 4: Failure Resilience
+  # ---------------------------------------------------------------------------
+  # Tests that lifecycle scripts handle error conditions gracefully: duplicate
+  # installs, missing backups, build failures, local-only commits, and
+  # concurrent execution guards.
+  failure-resilience:
+    name: Failure Resilience (${{ matrix.runner }})
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [ubuntu-latest, ubuntu-24.04-arm]
+    timeout-minutes: 30
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # --- Install DAAF (baseline for all failure tests) ---
+      - name: Install DAAF via install.sh
+        run: bash scripts/host/install.sh
+
+      - name: Verify container is running
+        working-directory: daaf-docker
+        run: |
+          for i in 1 2 3 4 5; do
+            docker compose ps | grep -q "Up" && exit 0
+            echo "Waiting for container to be ready (attempt $i/5)..."
+            sleep 3
+          done
+          echo "ERROR: Container did not reach running state"
+          docker compose ps
+          exit 1
+
+      # --- (a) Install detects existing installation ---
+      - name: Re-install without force flag (expect failure)
+        run: |
+          set +e
+          bash scripts/host/install.sh > /tmp/reinstall_noforce.txt 2>&1
+          EXIT_CODE=$?
+          set -e
+          cat /tmp/reinstall_noforce.txt
+          if [ "$EXIT_CODE" -eq 0 ]; then
+            echo "ERROR: install.sh should have failed for existing installation"
+            exit 1
+          fi
+          echo "install.sh correctly rejected re-install (exit code $EXIT_CODE)"
+
+      - name: Verify existing installation message
+        run: grep -qi "existing.*installation" /tmp/reinstall_noforce.txt
+
+      # --- (b) Install with force reinstall ---
+      - name: Re-install with DAAF_FORCE_REINSTALL=1
+        run: DAAF_FORCE_REINSTALL=1 bash scripts/host/install.sh
+
+      - name: Verify container running after force reinstall
+        working-directory: daaf-docker
+        run: docker compose ps | grep -q "Up"
+
+      # --- (c) Backup when volume is empty (fresh) ---
+      - name: Backup right after fresh install
+        working-directory: daaf-docker
+        run: bash backup_daaf.sh
+
+      - name: Verify fresh backup was created
+        working-directory: daaf-docker
+        run: ls -d *_daaf_backup/ | head -1
+
+      # --- (d) Restore with no backups available ---
+      # Create a temporary directory with no backup folders to test the error path.
+      # restore_from_backup.sh searches for backup directories in the current
+      # directory and exits with code 1 if none are found (before prompting).
+      - name: Stop container before no-backup restore test
+        working-directory: daaf-docker
+        run: docker compose down
+
+      - name: Restore with no backups (expect failure)
+        working-directory: daaf-docker
+        run: |
+          mkdir -p /tmp/empty_restore_dir
+          cp restore_from_backup.sh /tmp/empty_restore_dir/
+          cp docker-compose.yml /tmp/empty_restore_dir/
+          set +e
+          cd /tmp/empty_restore_dir && bash restore_from_backup.sh </dev/null > /tmp/restore_nobackup.txt 2>&1
+          EXIT_CODE=$?
+          cat /tmp/restore_nobackup.txt
+          set -e
+          if [ "$EXIT_CODE" -eq 0 ]; then
+            echo "ERROR: restore should have failed with no backups"
+            exit 1
+          fi
+          echo "restore correctly failed (exit code $EXIT_CODE)"
+
+      - name: Verify no-backup error message
+        run: grep -qi "No backup folders found" /tmp/restore_nobackup.txt
+
+      # --- (e) Rebuild preserves user data after build failure recovery ---
+      - name: Restart container after no-backup restore test
+        working-directory: daaf-docker
+        run: docker compose up -d
+
+      - name: Add test file to container
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            echo "precious user data" > /daaf/research/resilience_test.txt
+            git -C /daaf add research/resilience_test.txt
+            git -C /daaf commit -m "Resilience test data"
+          '
+
+      - name: Break the Dockerfile intentionally
+        working-directory: daaf-docker
+        run: |
+          cp Dockerfile Dockerfile.good
+          docker compose exec -T daaf-docker bash -c 'echo "INVALID_INSTRUCTION this_will_fail" >> /daaf/Dockerfile'
+
+      - name: Rebuild with broken Dockerfile (expect failure)
+        working-directory: daaf-docker
+        run: |
+          set +e
+          bash rebuild_daaf.sh > /tmp/rebuild_broken.txt 2>&1
+          EXIT_CODE=$?
+          set -e
+          cat /tmp/rebuild_broken.txt
+          if [ "$EXIT_CODE" -eq 0 ]; then
+            echo "ERROR: rebuild should have failed with broken Dockerfile"
+            exit 1
+          fi
+          echo "rebuild correctly failed (exit code $EXIT_CODE)"
+
+      - name: Fix the Dockerfile
+        working-directory: daaf-docker
+        run: |
+          mv Dockerfile.good Dockerfile
+          docker compose exec -T daaf-docker bash -c 'cat > /daaf/Dockerfile' < Dockerfile
+
+      - name: Rebuild with fixed Dockerfile
+        working-directory: daaf-docker
+        run: bash rebuild_daaf.sh
+
+      - name: Verify user data survived failed rebuild
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "precious user data" /daaf/research/resilience_test.txt
+            git -C /daaf log --oneline | grep -q "Resilience test data"
+          '
+
+      # --- (f) Update when container has local-only commits ---
+      # The container already has the "Resilience test data" commit from (e).
+      # update_daaf.sh in non-interactive mode auto-selects the first option
+      # (merge) when it detects local commits ahead of upstream.
+      - name: Update with local-only commits
+        working-directory: daaf-docker
+        run: |
+          bash update_daaf.sh > /tmp/update_local_commits.txt 2>&1
+          cat /tmp/update_local_commits.txt
+
+      - name: Verify container running after update with local commits
+        working-directory: daaf-docker
+        run: docker compose ps | grep -q "Up"
+
+      - name: Verify user data preserved after update
+        working-directory: daaf-docker
+        run: |
+          docker compose exec -T daaf-docker bash -c '
+            grep -q "precious user data" /daaf/research/resilience_test.txt
+          '
+
+      # --- (g) Concurrent lock guard ---
+      # Start a long-running update in the background, then immediately try
+      # a second one. The second should fail with the lock error.
+      - name: Test concurrent update lock
+        working-directory: daaf-docker
+        run: |
+          bash update_daaf.sh &
+          BG_PID=$!
+          # Poll for lock directory instead of fixed sleep to avoid race window
+          for i in $(seq 1 20); do [ -d /tmp/daaf-update.lock.d ] && break; sleep 0.2; done
+          set +e
+          bash update_daaf.sh > /tmp/update_concurrent.txt 2>&1
+          SECOND_EXIT=$?
+          cat /tmp/update_concurrent.txt
+          set -e
+          wait $BG_PID || true
+          if [ "$SECOND_EXIT" -eq 0 ]; then
+            echo "ERROR: second update should have been blocked by lock"
+            exit 1
+          fi
+          echo "Concurrent update correctly blocked (exit code $SECOND_EXIT)"
+
+      - name: Verify lock error message
+        run: grep -qi "already running" /tmp/update_concurrent.txt
+
+      - name: Clean up stale lock if present
+        run: rmdir /tmp/daaf-update.lock.d 2>/dev/null || true
+
+      # --- Cleanup ---
+      - name: Docker cleanup
+        if: always()
+        run: |
+          if [ -d daaf-docker ]; then
+            cd daaf-docker
+            docker compose down -v --rmi local --remove-orphans
+          fi
diff --git a/.github/workflows/ci-scripts.yml b/.github/workflows/ci-scripts.yml
new file mode 100644
index 0000000..42bb1a3
--- /dev/null
+++ b/.github/workflows/ci-scripts.yml
@@ -0,0 +1,541 @@
+# CI: Shell & PowerShell Script Quality
+#
+# Validates all .sh and .ps1 scripts across the repository.
+# Companion workflow: ci-integration.yml runs Docker integration tests weekly.
+#
+# Eight jobs:
+#   1. lint-bash           - ShellCheck on all .sh files (ubuntu)
+#   2. lint-powershell     - PSScriptAnalyzer on all .ps1 files (ubuntu/pwsh 7)
+#   3. hygiene-checks      - Executable bits, LF endings, script pair parity
+#   4. validate-ps-windows - PSScriptAnalyzer on Windows PowerShell 5.1
+#   5. bats-tests          - BATS unit/smoke tests for .sh scripts (ubuntu)
+#   6. pester-tests        - Pester tests for .ps1 scripts (ubuntu + windows)
+#   7. daaf-conventions    - Custom DAAF-specific lint checks (ubuntu)
+#   8. smoke-tests         - Cross-platform dry-run smoke tests (ubuntu + macos + windows)
+#
+# Triggered only when shell-related files change (path filtering).
+
+name: CI - Scripts
+
+on:
+  push:
+    paths:
+      - '**.sh'
+      - '**.ps1'
+      - '**.bats'
+      - '**/*.Tests.ps1'
+      - '.github/workflows/ci-scripts.yml'
+      - '.github/linters/**'
+      - 'tests/lint/**'
+  pull_request:
+    paths:
+      - '**.sh'
+      - '**.ps1'
+      - '**.bats'
+      - '**/*.Tests.ps1'
+      - 'tests/lint/**'
+      - '.github/workflows/ci-scripts.yml'
+      - '.github/linters/**'
+
+permissions:
+  contents: read
+
+# ---------------------------------------------------------------------------
+# Job 1: Lint all Bash scripts with ShellCheck
+# ---------------------------------------------------------------------------
+jobs:
+  lint-bash:
+    name: ShellCheck (Bash)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # ShellCheck is pre-installed on ubuntu-latest runners.
+      # We invoke it directly to scan all .sh files across multiple
+      # directories (root, .claude/hooks/, .claude/scripts/, scripts/).
+      - name: Run ShellCheck on all .sh files
+        run: |
+          find . -name '*.sh' -not -path './.git/*' -print0 \
+            | xargs -0 shellcheck -x --severity=warning --shell=bash --format=gcc
+
+  # ---------------------------------------------------------------------------
+  # Job 2: Lint all PowerShell scripts with PSScriptAnalyzer (pwsh 7 on Linux)
+  # ---------------------------------------------------------------------------
+  lint-powershell:
+    name: PSScriptAnalyzer (pwsh 7)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # pwsh is pre-installed on ubuntu-latest runners.
+      # We install PSScriptAnalyzer and run it with the repo's config file.
+      - name: Run PSScriptAnalyzer
+        shell: pwsh
+        run: |
+          Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -SkipPublisherCheck
+          Invoke-ScriptAnalyzer -Path . -Recurse -Settings ./.github/linters/PSScriptAnalyzerSettings.psd1 | Format-Table -AutoSize
+          $failCount = (Invoke-ScriptAnalyzer -Path . -Recurse -Settings ./.github/linters/PSScriptAnalyzerSettings.psd1).Count
+          if ($failCount -gt 0) { exit 1 }
+
+  # ---------------------------------------------------------------------------
+  # Job 3: Hygiene checks (executable bits, line endings, script pair parity)
+  # ---------------------------------------------------------------------------
+  hygiene-checks:
+    name: Hygiene Checks
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Verify every tracked .sh file has Git executable mode (100755).
+      # Scripts without the executable bit will fail in Docker and on Linux.
+      - name: Verify executable bits on .sh files
+        run: |
+          echo "Checking that all tracked .sh files have mode 100755..."
+          bad_files=$(git ls-files -s '*.sh' | awk '$1 != "100755" { print $4 }')
+          if [ -n "$bad_files" ]; then
+            echo "ERROR: The following .sh files are NOT executable (mode 100644):"
+            echo "$bad_files"
+            echo ""
+            echo "Fix with: chmod +x <file> && git update-index --chmod=+x <file>"
+            exit 1
+          fi
+          echo "All .sh files have correct executable bits."
+
+      # Verify no CRLF line endings have crept into shell or PowerShell scripts.
+      # .gitattributes enforces LF globally, but this catches pre-existing files.
+      - name: Verify LF line endings
+        run: |
+          echo "Checking for CRLF line endings in .sh and .ps1 files..."
+          # -P enables Perl regex for \r; -l lists matching filenames
+          crlf_files=$(find . -name '*.sh' -o -name '*.ps1' | grep -v './.git/' | xargs grep -Pl '\r$' 2>/dev/null || true)
+          if [ -n "$crlf_files" ]; then
+            echo "ERROR: The following files contain CRLF line endings:"
+            echo "$crlf_files"
+            echo ""
+            echo "Fix with: git add --renormalize . && git commit"
+            exit 1
+          fi
+          echo "All script files have LF line endings."
+
+      # Verify that every host lifecycle .sh has a matching .ps1 (and vice versa).
+      # DAAF maintains matched pairs for cross-platform support.
+      - name: Verify script pair parity (sh/ps1)
+        run: |
+          echo "Checking scripts/host/ script pair parity..."
+          exit_code=0
+
+          # Check each host .sh has a matching .ps1
+          for sh_file in ./scripts/host/*.sh; do
+            [ -f "$sh_file" ] || continue
+            base=$(basename "$sh_file" .sh)
+            if [ ! -f "./scripts/host/${base}.ps1" ]; then
+              echo "ERROR: ${sh_file} has no matching ${base}.ps1"
+              exit_code=1
+            fi
+          done
+
+          # Check each host .ps1 has a matching .sh
+          for ps_file in ./scripts/host/*.ps1; do
+            [ -f "$ps_file" ] || continue
+            base=$(basename "$ps_file" .ps1)
+            if [ ! -f "./scripts/host/${base}.sh" ]; then
+              echo "ERROR: ${ps_file} has no matching ${base}.sh"
+              exit_code=1
+            fi
+          done
+
+          if [ "$exit_code" -eq 0 ]; then
+            echo "All scripts/host/ scripts have matching cross-platform pairs."
+          fi
+          exit $exit_code
+
+  # ---------------------------------------------------------------------------
+  # Job 4: Validate PowerShell scripts on Windows PowerShell 5.1
+  # ---------------------------------------------------------------------------
+  validate-ps-windows:
+    name: PSScriptAnalyzer (Windows PS 5.1)
+    runs-on: windows-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Windows PowerShell 5.1 (not pwsh) is the default shell on Windows.
+      # This catches compatibility issues between PS 7 and PS 5.1.
+      - name: Run PSScriptAnalyzer (Windows PS 5.1)
+        shell: powershell
+        run: |
+          Install-Module -Name PSScriptAnalyzer -Force -Scope CurrentUser -SkipPublisherCheck
+          Invoke-ScriptAnalyzer -Path . -Recurse -Settings ./.github/linters/PSScriptAnalyzerSettings.psd1 | Format-Table -AutoSize
+          $failCount = (Invoke-ScriptAnalyzer -Path . -Recurse -Settings ./.github/linters/PSScriptAnalyzerSettings.psd1).Count
+          if ($failCount -gt 0) { exit 1 }
+
+  # ---------------------------------------------------------------------------
+  # Job 5: Run BATS tests for Bash scripts
+  # ---------------------------------------------------------------------------
+  bats-tests:
+    name: BATS Tests (Bash)
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install BATS and helpers
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y bats
+
+      # Run all .bats test files. The test helper includes fallback
+      # assertions so tests work without bats-support/bats-assert submodules.
+      - name: Run BATS tests
+        run: bats tests/bash/
+
+  # ---------------------------------------------------------------------------
+  # Job 6: Run Pester tests for PowerShell scripts
+  # ---------------------------------------------------------------------------
+  pester-tests:
+    name: Pester Tests (PowerShell)
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Pester 5.x is pre-installed on GitHub-hosted runners.
+      - name: Run Pester tests
+        shell: pwsh
+        run: |
+          Invoke-Pester -Path ./tests/powershell/ -CI -Output Detailed
+
+  # ---------------------------------------------------------------------------
+  # Job 7: DAAF-specific convention checks
+  # ---------------------------------------------------------------------------
+  daaf-conventions:
+    name: DAAF Conventions Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run DAAF convention checks
+        run: bash tests/lint/check-daaf-conventions.sh
+
+  # ---------------------------------------------------------------------------
+  # Job 8: Cross-platform dry-run smoke tests (no Docker needed)
+  # ---------------------------------------------------------------------------
+  # Verifies that all lifecycle scripts load and run their full logic paths
+  # on all three OS platforms using DAAF_DRY_RUN=1 (mocked Docker/curl).
+  # Catches bash 3.2 incompatibilities (macOS), PS 5.1 quirks (Windows),
+  # unresolved variable references, and control flow errors.
+  smoke-tests:
+    name: Smoke Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      # Bash smoke tests (Linux/macOS only — Git Bash on Windows is unreliable
+      # for complex scripts with function overrides and subshells).
+      # Each script is run individually to capture output and verify both exit
+      # code and content (the [DRY-RUN] marker plus script-specific strings).
+      - name: Smoke test .sh scripts (dry-run)
+        if: matrix.os != 'windows-latest'
+        run: |
+          failed=0
+
+          assert_contains() {
+            local label="$1" output="$2" pattern="$3"
+            if echo "$output" | grep -qF "$pattern"; then
+              echo "  PASS: output contains '$pattern'"
+            else
+              echo "  FAIL: expected output to contain '$pattern'"
+              failed=1
+            fi
+          }
+
+          # --- install.sh ---
+          echo "=== Smoke testing: scripts/host/install.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/install.sh 2>&1) || { echo "FAILED: install.sh (exit code $?)"; failed=1; }
+          assert_contains "install.sh" "$out" "[DRY-RUN]"
+          assert_contains "install.sh" "$out" "DAAF Installer"
+          assert_contains "install.sh" "$out" "Installation complete!"
+
+          # --- backup_daaf.sh ---
+          echo "=== Smoke testing: scripts/host/backup_daaf.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/backup_daaf.sh 2>&1) || { echo "FAILED: backup_daaf.sh (exit code $?)"; failed=1; }
+          assert_contains "backup_daaf.sh" "$out" "[DRY-RUN]"
+          assert_contains "backup_daaf.sh" "$out" "DAAF Backup"
+          assert_contains "backup_daaf.sh" "$out" "[DRY-RUN] Would create backup at:"
+
+          # --- rebuild_daaf.sh ---
+          echo "=== Smoke testing: scripts/host/rebuild_daaf.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/rebuild_daaf.sh 2>&1) || { echo "FAILED: rebuild_daaf.sh (exit code $?)"; failed=1; }
+          assert_contains "rebuild_daaf.sh" "$out" "DAAF Rebuild"
+          assert_contains "rebuild_daaf.sh" "$out" "Rebuild complete!"
+
+          # --- update_daaf.sh ---
+          echo "=== Smoke testing: scripts/host/update_daaf.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/update_daaf.sh 2>&1) || { echo "FAILED: update_daaf.sh (exit code $?)"; failed=1; }
+          assert_contains "update_daaf.sh" "$out" "DAAF Updater"
+          assert_contains "update_daaf.sh" "$out" "Already up to date!"
+
+          # --- migrate_daaf.sh ---
+          echo "=== Smoke testing: scripts/host/migrate_daaf.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/migrate_daaf.sh 2>&1) || { echo "FAILED: migrate_daaf.sh (exit code $?)"; failed=1; }
+          assert_contains "migrate_daaf.sh" "$out" "[DRY-RUN]"
+          assert_contains "migrate_daaf.sh" "$out" "DAAF Migration"
+          assert_contains "migrate_daaf.sh" "$out" "Migration complete!"
+
+          # --- restore_from_backup.sh ---
+          echo "=== Smoke testing: scripts/host/restore_from_backup.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/restore_from_backup.sh 2>&1) || { echo "FAILED: restore_from_backup.sh (exit code $?)"; failed=1; }
+          assert_contains "restore_from_backup.sh" "$out" "DAAF Restore from Backup"
+          assert_contains "restore_from_backup.sh" "$out" "Restore dry-run complete!"
+
+          # --- view_logs.sh ---
+          echo "=== Smoke testing: scripts/host/view_logs.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/view_logs.sh 2>&1) || { echo "FAILED: view_logs.sh (exit code $?)"; failed=1; }
+          assert_contains "view_logs.sh" "$out" "DAAF container is running."
+          assert_contains "view_logs.sh" "$out" "Opening DAAF Log Explorer"
+
+          # --- view_notebooks.sh ---
+          echo "=== Smoke testing: scripts/host/view_notebooks.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/view_notebooks.sh 2>&1) || { echo "FAILED: view_notebooks.sh (exit code $?)"; failed=1; }
+          assert_contains "view_notebooks.sh" "$out" "DAAF container is running."
+          assert_contains "view_notebooks.sh" "$out" "Opening DAAF Notebook Browser"
+
+          # --- run_vscode.sh ---
+          echo "=== Smoke testing: scripts/host/run_vscode.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/run_vscode.sh 2>&1) || { echo "FAILED: run_vscode.sh (exit code $?)"; failed=1; }
+          assert_contains "run_vscode.sh" "$out" "DAAF container is running."
+          assert_contains "run_vscode.sh" "$out" "Opening DAAF Code Browser"
+
+          # --- run_daaf.sh ---
+          echo "=== Smoke testing: scripts/host/run_daaf.sh ==="
+          out=$(DAAF_DRY_RUN=1 DAAF_NESTED=1 bash scripts/host/run_daaf.sh 2>&1) || { echo "FAILED: run_daaf.sh (exit code $?)"; failed=1; }
+          assert_contains "run_daaf.sh" "$out" "[DRY-RUN]"
+          assert_contains "run_daaf.sh" "$out" "DAAF container is already running."
+          assert_contains "run_daaf.sh" "$out" "Launching Claude Code"
+
+          if [ "$failed" -ne 0 ]; then
+            echo ""
+            echo "One or more smoke tests failed."
+            exit 1
+          fi
+          echo ""
+          echo "All bash smoke tests passed."
+
+      # PowerShell 7 smoke tests (all platforms — pwsh is pre-installed).
+      # Each script is run individually to capture output and verify both exit
+      # code and content (the [DRY-RUN] marker plus script-specific strings).
+      - name: Smoke test .ps1 scripts (dry-run, pwsh 7)
+        shell: pwsh
+        run: |
+          $failed = 0
+
+          function Assert-OutputContains {
+            param([string]$Label, [string]$Output, [string]$Pattern)
+            if ($Output -match [regex]::Escape($Pattern)) {
+              Write-Host "  PASS: output contains '$Pattern'"
+            } else {
+              Write-Host "  FAIL: expected output to contain '$Pattern'"
+              $script:failed = 1
+            }
+          }
+
+          function Invoke-SmokeTest {
+            param(
+              [string]$ScriptPath,
+              [string[]]$ExpectedStrings
+            )
+            $name = Split-Path $ScriptPath -Leaf
+            Write-Host "=== Smoke testing: $name ==="
+            $env:DAAF_DRY_RUN = "1"
+            $env:DAAF_NESTED = "1"
+            try {
+              $output = & $ScriptPath *>&1 | Out-String
+              if ($LASTEXITCODE -and $LASTEXITCODE -ne 0) {
+                Write-Host "FAILED: $name (exit code $LASTEXITCODE)"
+                $script:failed = 1
+              }
+            } catch {
+              Write-Host "FAILED: $name - $_"
+              $script:failed = 1
+              return
+            }
+            foreach ($pattern in $ExpectedStrings) {
+              Assert-OutputContains $name $output $pattern
+            }
+          }
+
+          Invoke-SmokeTest "scripts/host/install.ps1" @(
+            "DAAF Installer",
+            "Installation complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/backup_daaf.ps1" @(
+            "[DRY-RUN]",
+            "DAAF Backup",
+            "[DRY-RUN] Would copy"
+          )
+
+          Invoke-SmokeTest "scripts/host/rebuild_daaf.ps1" @(
+            "DAAF Rebuild",
+            "Rebuild complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/update_daaf.ps1" @(
+            "DAAF Updater",
+            "Already up to date!"
+          )
+
+          Invoke-SmokeTest "scripts/host/migrate_daaf.ps1" @(
+            "DAAF Migration",
+            "Migration complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/restore_from_backup.ps1" @(
+            "DAAF Restore from Backup",
+            "Restore dry-run complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/view_logs.ps1" @(
+            "DAAF container is running.",
+            "Opening DAAF Log Explorer"
+          )
+
+          Invoke-SmokeTest "scripts/host/view_notebooks.ps1" @(
+            "DAAF container is running.",
+            "Opening DAAF Notebook Browser"
+          )
+
+          Invoke-SmokeTest "scripts/host/run_vscode.ps1" @(
+            "DAAF container is running.",
+            "Opening DAAF Code Browser"
+          )
+
+          Invoke-SmokeTest "scripts/host/run_daaf.ps1" @(
+            "DAAF container is already running.",
+            "Launching Claude Code"
+          )
+
+          if ($failed) {
+            Write-Host ""
+            Write-Host "One or more smoke tests failed."
+            exit 1
+          }
+          Write-Host ""
+          Write-Host "All pwsh 7 smoke tests passed."
+
+      # Windows PowerShell 5.1 smoke test (Windows only — catches PS 5.1
+      # $ErrorActionPreference quirks, alias differences, and path issues).
+      # Each script is run individually to capture output and verify both exit
+      # code and content (the [DRY-RUN] marker plus script-specific strings).
+      - name: Smoke test .ps1 scripts (dry-run, Windows PS 5.1)
+        if: matrix.os == 'windows-latest'
+        shell: powershell
+        run: |
+          $failed = 0
+
+          function Assert-OutputContains {
+            param([string]$Label, [string]$Output, [string]$Pattern)
+            if ($Output -match [regex]::Escape($Pattern)) {
+              Write-Host "  PASS: output contains '$Pattern'"
+            } else {
+              Write-Host "  FAIL: expected output to contain '$Pattern'"
+              $script:failed = 1
+            }
+          }
+
+          function Invoke-SmokeTest {
+            param(
+              [string]$ScriptPath,
+              [string[]]$ExpectedStrings
+            )
+            $name = Split-Path $ScriptPath -Leaf
+            Write-Host "=== Smoke testing (PS 5.1): $name ==="
+            $env:DAAF_DRY_RUN = "1"
+            $env:DAAF_NESTED = "1"
+            try {
+              $output = & $ScriptPath *>&1 | Out-String
+              if ($LASTEXITCODE -and $LASTEXITCODE -ne 0) {
+                Write-Host "FAILED: $name (exit code $LASTEXITCODE)"
+                $script:failed = 1
+              }
+            } catch {
+              Write-Host "FAILED: $name - $_"
+              $script:failed = 1
+              return
+            }
+            foreach ($pattern in $ExpectedStrings) {
+              Assert-OutputContains $name $output $pattern
+            }
+          }
+
+          Invoke-SmokeTest "scripts/host/install.ps1" @(
+            "DAAF Installer",
+            "Installation complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/backup_daaf.ps1" @(
+            "[DRY-RUN]",
+            "DAAF Backup",
+            "[DRY-RUN] Would copy"
+          )
+
+          Invoke-SmokeTest "scripts/host/rebuild_daaf.ps1" @(
+            "DAAF Rebuild",
+            "Rebuild complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/update_daaf.ps1" @(
+            "DAAF Updater",
+            "Already up to date!"
+          )
+
+          Invoke-SmokeTest "scripts/host/migrate_daaf.ps1" @(
+            "DAAF Migration",
+            "Migration complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/restore_from_backup.ps1" @(
+            "DAAF Restore from Backup",
+            "Restore dry-run complete!"
+          )
+
+          Invoke-SmokeTest "scripts/host/view_logs.ps1" @(
+            "DAAF container is running.",
+            "Opening DAAF Log Explorer"
+          )
+
+          Invoke-SmokeTest "scripts/host/view_notebooks.ps1" @(
+            "DAAF container is running.",
+            "Opening DAAF Notebook Browser"
+          )
+
+          Invoke-SmokeTest "scripts/host/run_vscode.ps1" @(
+            "DAAF container is running.",
+            "Opening DAAF Code Browser"
+          )
+
+          Invoke-SmokeTest "scripts/host/run_daaf.ps1" @(
+            "DAAF container is already running.",
+            "Launching Claude Code"
+          )
+
+          if ($failed) {
+            Write-Host ""
+            Write-Host "One or more smoke tests failed."
+            exit 1
+          }
+          Write-Host ""
+          Write-Host "All PS 5.1 smoke tests passed."
diff --git a/.gitignore b/.gitignore
index 1154721..e0726de 100644
--- a/.gitignore
+++ b/.gitignore
@@ -54,6 +54,7 @@ Thumbs.db
 
 # Environment variables
 .env
+environment_settings*.txt
 
 # Claude Code
 .claude/settings.local.json
@@ -62,4 +63,7 @@ Thumbs.db
 .claude/logs/audit.jsonl
 .claude/logs/subagent-registry-*.jsonl
 .claude/logs/pending_log_collection.jsonl
-.claude/logs/.last_recovery
\ No newline at end of file
+.claude/logs/.last_recovery
+
+# Generated log viewer artifacts (regenerated on demand)
+**/logs/session_manifest.json
\ No newline at end of file
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 648432f..bf0ef07 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -24,3 +24,9 @@ repos:
 
       # Trim trailing whitespace
       - id: trailing-whitespace
+
+  - repo: https://github.com/shellcheck-py/shellcheck-py
+    rev: v0.10.0.1
+    hooks:
+      - id: shellcheck
+        args: ['--severity=warning', '--shell=bash']
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..7b11614
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,661 @@
+# Changelog
+
+All notable changes to DAAF for each release version are documented here, in reverse chronological order.
+
+## Table of Contents
+
+- [v2.1.0 — 2026-05-02](#v210--2026-05-02)
+- [v2.0.1 — 2026-04-05](#v201--2026-04-05)
+- [v2.0.0 — 2026-03-31](#v200--2026-03-31)
+- [v1.0.0 — 2026-02-22](#v100--2026-02-22)
+
+---
+
+## v2.1.0 -- 2026-05-02
+
+### Data Analyst Augmentation Framework -- Quality of Life Release
+
+If v2.0.0 was about building out the reliaibility, robustness, and extensibility of DAAF's core analytical engine, v2.1.0 is about making it actually easy to set up, run, and maintain for real-world workflows and collaboration. For example, the original installation process asked users to juggle Docker commands, download and unzip GitHub repos, and manage the Docker volume filesystem. That friction was one of the biggest barrier to adoption, and this release implements a huge number of quality-of-life improvements to fix that. A single command now handles the entire installation. Named helper scripts replace every Docker incantation you'd need to remember and handles all of the back-end container management for you. A one-line update system means you can stay current without losing your work, regardless of when you installed DAAF for the first time. And a new session log viewer gives you a window into what DAAF is actually doing every step of the way, which is crucial for diagnostics and intuition when using the system.
+
+Beyond the operations story, this release also sets up a number of smaller infrastructural improvements -- for example, specialist agents can return more detailed findings, and I've implemented a code-testing pipeline to help ensure every release of DAAF ships without unexpected issues or bugs. More details for the highlights of this release are listed out below!
+
+### One-Line Installer
+
+DAAF can now be installed with a single command on both macOS/Linux and Windows. The previous multi-step manual process has been replaced by a one-line installer that handles everything automatically -- downloading the necessary files, building the Docker image, and setting up your workspace.  Getting started with DAAF and Claude Code in a secure, well-curated, and fully reproducible environment for research has never been easier! This took a LOT of experimentation and testing, since these scripts are designed to be run on your computer, and I had to account for various versions of Windows, MacOSX, etc. etc. which is quite a headache.
+
+### Helper Scripts for Everyday Operations
+
+A complete suite of "helper" convenience scripts (available for both macOS/Linux and Windows) now makes it painless and straightforward to handle the most common DAAF operations. Instead of remembering Docker commands, you can simply run a script:
+
+- **`run_daaf`** -- Start DAAF and Claude Code (automatically sets up the docker container and runs the main commands for you)
+- **`update_daaf`** -- Update to the latest DAAF version available, backing up your work automatically before making changes, and helping you integrate framework changes and customizations together (more on that below)
+- **`backup_daaf`** / **`restore_from_backup`** -- Save and restore snapshots of your entire DAAF workspace effortlessly. Also allows for painless sharing of entire repositories with colleagues!
+- **`rebuild_daaf`** -- Rebuild the Docker image when needed to update configurations, library installs, updates, etc.
+- **`view_logs`** -- Open the session log viewer in your browser to easily inspect and view what DAAF is doing at every step of its work (more on that below)
+- **`run_vscode`** -- Open a full VS Code editor in your browser for browsing, editing, uploading, downloading, and reviewing files inside the container (more on that below)
+- **`view_notebooks`** -- Open Marimo to browse your analysis notebooks
+
+Every script has both a Bash (.sh, for MacOSX and Linux) and PowerShell (.ps1, for Windows) variant, and all are covered by automated tests and quality checks. This was, by far, the most time-consuming part of this release -- making cross-platform shell scripts that work reliably across macOS, Linux, and Windows is genuinely hard, and the number of edge cases to navigate and problem-solve for was humbling. I suspect there will still be some issues that I couldn't identify on my own, so please do let me know what errors and problems you encounter!
+
+### Update and Migration Pathway
+
+Existing DAAF users can now update to the latest version without losing their work or framework customizations in a very guided process. The `update_daaf` script automatically backs up your workspace before making any changes and uses intelligent file-change detection to handle file conflicts gracefully -- leaning on Claude Code itself to help resolve conflicts between your customizations and new framework updates. 
+
+For anyone coming from an older version that doesn't have this script built-in (so anything before this very release), a dedicated `migrate_daaf` script detects your installation type, connects you to the update process, and gets everything organized in a guided walkthrough. Check the [Installation and Quickstart guide](user_reference/01_installation_and_quickstart.md#migrating-from-an-older-installation) for details -- just one line of code to run in your terminal to get caught up.
+
+### Session Log Viewer
+
+A new in-browser session transcript viewer makes it much easier to see what DAAF is doing under the hood and to diagnose issues when they arise. You can browse past sessions, search across transcripts, filter by session, and inspect individual tool calls -- all from a clean web interface. Launch it with the `view_logs` helper script. This has been genuinely useful for development too -- being able to trace exactly what happened in a subagent's session has saved hours of debugging.
+
+### In-Browser VS Code (code-server)
+
+DAAF now ships with a full VS Code editor (code-server) that runs inside the container and opens right in your browser. Before this, if you wanted to look at files DAAF produced -- scripts, data, reports, logs -- your options were scrolling through the terminal, digging through Docker Desktop's clunky file browser, or copying files out to your host machine. None of that is a great experience when you're trying to review an analysis or understand what happened during a session.
+
+Now you just run `run_vscode` from your installation folder and a complete file editor and browser environment opens in your browser -- file tree, syntax highlighting, search across files, Git history, upload and download files, all of it. It comes pre-loaded with nine extensions (Python, GitLens, Git Graph, Rainbow CSV, Markdown support, and more) and a clean dark theme, so it's ready to use immediately. Everything stays inside the container's security boundary, and you don't need to change anything on your own computer to manage it.
+
+This is one of those changes that sounds minor on paper but makes a huge difference in practice. DAAF produces a *lot* of artifacts over the course of a session, and being able to browse and inspect them in a real editor — instead of one file at a time in the terminal — makes reviewing work dramatically more natural. It's also a much friendlier way to explore the framework itself if you're learning how DAAF works or building new skills and agents.
+
+### Environment Variable Support
+
+DAAF now supports secure environment variable configuration via an `environment_settings.txt` file that lives on your host machine (outside the container and inaccessible to Claude). You can set API keys for Claude Code authentication, data source access, and alternative providers -- all in one place. The file is automatically loaded at container startup, and DAAF's safety system prevents Claude from ever reading or accessing it directly. An annotated example template (`environment_settings_example.txt` in your `daaf-docker/` folder) walks you through every option.
+
+### OpenRouter Support (Experimental)
+
+DAAF now supports running Claude Code through OpenRouter as an alternative to a direct Anthropic API key, opening the door for greater model and provider flexibility. Configuration is handled entirely through the `environment_settings.txt` file -- no code changes needed. Context window detection was also updated to correctly query OpenRouter's API for the real context length of whatever model you're running. **Note:** This integration is experimental. It works, but you may encounter rough edges. Direct Anthropic API access remains the recommended and most reliable option.
+
+### Preliminary Phase Notes Persistence
+
+Specialist agent findings (source research, data profiling, synthesis) are now saved to disk as complete markdown files in `output/preliminary_notes/`. Previously, DAAF's coordinator held compressed summaries in its own working memory -- which meant later stages of analysis were working from shortened versions of earlier findings. Now the full findings are saved to a file and later agents read directly from that file, so nothing is lost to summarization. This is a quiet change, but it meaningfully improves analytical continuity across long sessions.
+
+### Shell Scripting Skill
+
+A new `shell-scripting` skill teaches Claude the conventions and standards used across all of DAAF's helper scripts -- covering Bash, PowerShell, error handling, testing, and cross-platform gotchas. Five reference files (~2,200 lines total) cover everything from script templates to testing patterns. This means that when DAAF needs to write or modify shell scripts (or when contributors submit new ones), they'll follow consistent, well-tested patterns.
+
+### Automated Testing and Quality Checks
+
+New automated pipelines run on every proposed code change to help ensure that DAAF's helper scripts remain reliable as the project evolves:
+
+- **Script quality scanning** catches common scripting errors and enforces DAAF-specific conventions automatically on every code change
+- **Unit test suites** verify that both the Bash and PowerShell variants of every helper script behave correctly in isolation
+- **Full lifecycle tests** exercise the complete workflow -- install, run, backup, update, rebuild, and migrate -- in a fresh Docker environment to catch problems that only appear when everything runs together
+- **Pre-commit checks** flag scripting issues before they're even committed, so problems are caught as early as possible
+
+### Under the Hood
+
+- **Specialist agent word limits raised:** Agents can now return substantially longer findings (general agents doubled from 1,000 to 2,000 words; data profiling agents from 2,500 to 3,500), reducing the chance of truncated or incomplete results
+- **Prompt caching enabled:** Repeated sessions now benefit from cached context via a new default Claude setting, improving token efficiency and reducing cost
+- **Session log collection fixed:** The log collector now correctly finds all agent transcripts from a session, even when sub-agents never directly mention the project directory
+- **System prompt trimmed:** Removed ~144 lines of illustrative examples from the always-loaded system prompt -- content that was consuming working memory on every single turn without adding operational value
+- **Container startup simplified:** Git identity configuration moved into the image build itself, eliminating an extra startup step and simplifying the boot process
+- **Claude Code updated** to version 2.1.112, from the latest pin of 2.1.87
+
+### What's Coming Next
+
+- **R Support** -- Bringing first-class R language support to DAAF, as well as dual-language handling for Python and R in tandem. Long time coming, but will be worth it!
+- **Benchmarking tests** -- Creating an automated benchmarking process for DAAF with test cases for plan quality, code generation adherence, and quality checkpoint compliance: the beginning of systematic testing for how well different Claude models follow DAAF's conventions (and thus understanding what settings matter, and/or whether other models from other providers like open-source options are viable yet).
+- **More video tutorials and walkthroughs** -- Expanding the library of guided video content
+
+**Full Changelog**: [v2.0.1...v2.1.0](https://github.com/DAAF-Contribution-Community/daaf/compare/v2.0.1...v2.1.0)
+
+---
+
+## v2.0.1 — 2026-04-05
+
+### Data Analyst Augmentation Framework — Minor Revisions
+
+Minor revisions: Adds an explicit "User Support Mode" as DAAF's 9th engagement mode (with better documentation reading/routing for a variety of issues/questions related to DAAF, Claude Code, Docker, and Git), hardens session archiving in the event of accidental crash or unintended closes/session termination, improves user documentation with diagrams and extended content, and archives complete session logs for both sample projects (college selectivity analysis) for better transparency and future educational materials.
+
+**Full Changelog**: [v2.0.0...v2.0.1](https://github.com/DAAF-Contribution-Community/daaf/compare/v2.0.0...v2.0.1)
+
+---
+
+## v2.0.0 — 2026-03-31
+
+### Data Analyst Augmentation Framework — Gaining Altitude Release
+
+DAAF v2.0.0 is a ground-up architectural overhaul driven by four reinforcing goals: greater **extensibility and customizability**, broad **methodological capability expansions**, heightened alignment with **reproducibility best practices as the default**, and improved **token efficiency**. The v1.0.0 framework worked, but it was overly monolithic and fragile; every session loaded thousands of lines of workflow documentation regardless of the task, and adding new capabilities (data domains, analytical methods, engagement patterns) required modifying deeply entangled files ad hoc every single time. v2.0.0 decomposes the system into modular, progressively-disclosed components that load just-in-time, so the orchestrator and agents see only what they need for the current task/mode at hand. This same modularity makes the framework straightforwardly extensible: new data domains, analytical skills, engagement modes, and agent types can be added by authoring self-contained files and running a registration checklist. Not only that, but the new Framework Development mode makes all of these processes and updates happen basically without effort; the meta-improvement systems are working fantastically (having used it extensively for this release!). The net effect is a system that uses context more efficiently, adheres to its own protocols more reliably, can cover far more methodological territory, and scales to new research domains without architectural friction. Finally, the addition of new modes like Ad Hoc Collaboration and Reproducibility Verification begin to move DAAF from a nascent proof-of-concept to a tool that can start to genuinely add value across many domains of the research and science community.
+
+### The Headline Changes
+
+- **Architecture:** `CLAUDE.md` shrinks from ~1,800 lines to ~500 lines of universal conventions. Orchestration logic moves into a dedicated `daaf-orchestrator` skill with reference files loaded just-in-time — so a light-lift Data Lookup session never loads the 1,950-line Full Pipeline spec. Monolithic workflow documentation is split into phase-specific files, each loaded only when the orchestrator reaches that phase. The research Plan document is decomposed into 3 purpose-specific files (Plan, Plan\_Tasks, State), allowing the orchestrator to hold strategy and status in context while referencing task details by path.
+
+- **Engagement Modes: 4 to 8.** New modes: Data Onboarding (formerly Data Ingest, now a full orchestrated mode with API acquisition and multi-file support), Ad Hoc Collaboration, Reproducibility Verification, and Framework Development modes. Existing modes of Data Lookup (renamed from Targeted Assist), Data Discovery (renamed from Discovery), and Full Pipeline are greatly improved across the board.
+
+- **Analytical Skills: 7 new library skills + 2 translation skills.** Each skill follows the same SKILL.md + deep references architecture, so adding support for a new library is a matter of authoring — not framework modification. New skills: statsmodels, pyfixest, linearmodels, scikit-learn (unsupervised + supervised + fairness), geopandas, svy (complex survey analysis), science-communication, plus a major expansion of the data-scientist methodology skill with 8 new reference files covering causal inference, descriptive analysis, survey analysis, geospatial, unsupervised, supervised ML, and statistical modeling. Two cross-language translation skills (r-python-translation, stata-python-translation) enable inline code annotations for users coming from R or Stata backgrounds, powered by a persistent user language preference system.
+
+- **Citation Propagation and Verification.** A distributed citation flow spans the entire pipeline: 13 skills carry canonical citation blocks with inclusion thresholds, the research-executor tracks citations as it works, the orchestrator accumulates them in STATE.md, and the report-writer renders a four-subsection References section with rationale lines. A centralized `CITATION_REFERENCE.md` index covers ~30 methods and tools. A pre-launch audit verified 1,005 references across 46 files and corrected 58 errors (fabricated authors, incorrect API claims, deprecated parameters, dead URLs).
+
+- **Claude Code Platform Adaptations.** Systematic adjustments to DAAF's infrastructure based on testing against Claude Code's actual runtime behavior: a new search-agent replaces generic Plan dispatches (which lacked reasoning depth), subagent transcripts are now archived alongside orchestrator sessions, the 250-character frontmatter truncation limit is accommodated with a two-tier description architecture, the Dockerfile is fully pinned and smoke-tested, and audit logs now carry per-agent identity for traceability.
+
+- **Agent Architecture:** All agents relocated to `.claude/agents/` for native Claude Code discovery. Named agent dispatch replaces generic `subagent_type`, so each agent loads exactly its own protocol and preloaded skills — no wasted context on irrelevant behavioral instructions. Per-agent hook enforcement (`enforce-file-first.sh`) mechanically blocks direct Python execution in coding agents, ensuring protocol adherence at the infrastructure layer rather than relying on prompt compliance alone.
+
+- **Research Integrity:** AI Use Disclosure section (GUIDE-LLM aligned) added to all reports. `CITATION.cff` for machine-readable software citation. Session metadata tracking (DAAF version, model ID, timestamps). Session log collection utilities. First-time user transparency statement on LLM limitations and researcher responsibility.
+
+- **Self-Modification:** Framework Development mode + `framework-engineer` agent + `FRAMEWORK_INTEGRATION_CHECKLIST.md` make DAAF formally self-extensible. New skills, agents, and modes can be added through structured authoring and a registration checklist — the framework is designed to grow without requiring core rewrites.
+
+---
+
+### Painfully Detailed Changelog
+
+Note that Claude absolutely had to help me write most of this, there were like 100 commits to shift through major changes on.
+
+**Reading lens:** Nearly every change below serves one or both of two goals. _Token efficiency:_ reducing what gets loaded into context so agents see only relevant instructions and adhere to them more reliably. _Extensibility:_ making it easy to add new data domains, analytical methods, engagement modes, and agent types without modifying core framework files. These goals reinforce each other -- modular components are both cheaper to load and easier to extend.
+
+#### 1. Core Architecture Streamlining
+
+##### 1.1 Orchestrator Extraction and Progressive Disclosure
+
+The most fundamental change in v2.0.0 is the extraction of orchestration logic from `CLAUDE.md` into the `daaf-orchestrator` skill (`SKILL.md` + 9 reference files). `CLAUDE.md` retains only universal execution philosophy, code style rules, project conventions, and safety boundaries -- content that applies to all agents equally. The orchestrator skill handles mode classification, user communication, subagent dispatch, and workflow coordination.
+
+This enables far better **progressive disclosure**: the orchestrator loads only the reference file for the confirmed engagement mode, rather than ingesting thousands of lines of workflow documentation upfront. Each mode reference file is self-contained with its own invocation templates, gate definitions, PSU (Phase Status Update) templates, and escalation triggers.
+
+Had to figure out a way to ensure that the daaf-orchestrator skill correctly got loaded only by the LLM assistant interacting directly with the user, and ensure that it does so reliably regardless of how the user starts the conversation (via some reminder hooks and checks). This'll be one of those things that's unfortunately annoyingly hard to port to other systems, because the way this works is currently very Claude Code specific. See 4.2 below for more information.
+
+##### 1.2 Workflow Phase Decomposition
+
+The monolithic `02_WORKFLOW_STAGES.md` (1,628 lines) and `03_SKILL_INVOCATIONS.md` (1,847 lines) are replaced by five phase-specific workflow files for the Full Pipeline Mode:
+
+| File | Content |
+|------|---------|
+| `WORKFLOW_PHASE1_DISCOVERY.md` | Stages 1-3.5: Goal refinement, data exploration, source deep-dives, synthesis |
+| `WORKFLOW_PHASE2_PLANNING.md` | Stages 4-4.5: Plan creation, plan verification |
+| `WORKFLOW_PHASE3_ACQUISITION.md` | Stages 5-6: Data fetch, cleaning, QA |
+| `WORKFLOW_PHASE4_ANALYSIS.md` | Stages 7-10: Transform, analysis, visualization, QA aggregation |
+| `WORKFLOW_PHASE5_SYNTHESIS.md` | Stages 11-12: Report writing, final verification |
+
+Each file contains stage-specific invocation templates, gate criteria, verification checklists, and PSU content. The orchestrator loads them progressively as execution advances through phases, which makes session restarts far more efficient and focused, with better instructional adherence along the way.
+
+**Data Onboarding** also receives its own progressive workflow files in the same manner, now that it's been upgraded to a full-fledged mode
+
+- `WORKFLOW_PHASE_DO_PROFILING.md` (~855 lines) — Parts A-D profiling protocol
+- `WORKFLOW_PHASE_DO_AUTHORING.md` (~270 lines) — Skill authoring and validation
+
+##### 1.3 Plan Document Decomposition
+
+The research Plan document is split into three purpose-specific files:
+
+| Document | Purpose |
+|----------|---------|
+| `Plan.md` | Research strategy, methodology, goals, hypotheses, scope decisions |
+| `Plan_Tasks.md` | Executable Transformation Sequence — task blocks for subagent dispatch, organized in parallelizable waves |
+| `STATE.md` | Session state for recovery — current stage, script status, gate status, blockers, session metadata |
+
+This separation allows the orchestrator to hold `Plan.md` and `STATE.md` in full context while referencing `Plan_Tasks.md` only by path, significantly improving context efficiency for multi-stage sessions.
+
+**New templates:** `PLAN_TASKS_TEMPLATE.md`, expanded `STATE_TEMPLATE.md`
+
+##### 1.4 Deleted Legacy Files
+
+| Removed File | Replacement |
+|--------------|-------------|
+| `agent_reference/01_PROTOCOLS.md` | Content distributed to `full-pipeline.md` and `session-recovery.md` |
+| `agent_reference/02_WORKFLOW_STAGES.md` | Five `WORKFLOW_PHASE*.md` files |
+| `agent_reference/03_SKILL_INVOCATIONS.md` | Inline in `WORKFLOW_PHASE*.md` files |
+| `agent_reference/07_CONTEXT_MANAGEMENT.md` | Consolidated into `CLAUDE.md` and `daaf-orchestrator/SKILL.md` |
+| `agent_reference/08_LESSONS_LEARNED.md` | Replaced by per-project `LEARNINGS.md` |
+| `agent_reference/EXECUTION_CAPTURE.md` | Merged into `SCRIPT_EXECUTION_REFERENCE.md` |
+| `agent_reference/PLAN_TEMPLATE_INGEST.md` | Deleted (Data Onboarding does not produce a Plan.md) |
+| `scripts/md-outline.sh` | Deleted (superseded by direct file reads) |
+| `agents/README.md` (old location) | Replaced by `.claude/agents/README.md` |
+
+##### 1.5 File Renames
+
+| Old Name | New Name |
+|----------|----------|
+| `04_BOUNDARIES.md` | `BOUNDARIES.md` |
+| `05_VALIDATION_CHECKPOINTS.md` | `VALIDATION_CHECKPOINTS.md` |
+| `06_ERROR_RECOVERY.md` | `ERROR_RECOVERY.md` |
+| `SCRIPT_TEMPLATE.md` | `SCRIPT_EXECUTION_REFERENCE.md` |
+| `data-ingest-mode.md` | `data-onboarding-mode.md` |
+| `STATE_TEMPLATE_INGEST.md` | `STATE_TEMPLATE_ONBOARDING.md` |
+| `discovery-mode.md` | `data-discovery-mode.md` |
+| `targeted-assist-mode.md` | `data-lookup-mode.md` |
+| `revision-mode.md` | `revision-and-extension-mode.md` |
+
+---
+
+#### 2. Expanded and Refined Engagement Modes (from 4 to 8)
+
+##### 2.1 Data Onboarding Mode (formerly Data Ingest)
+
+Elevated from a simple agent invocation to a fully orchestrated mode with its own state template, profiling protocol, and skill authoring workflow. The mode profiles datasets across four parts (Structural, Statistical, Relational, Interpretation) using up to 11 scripts, with orchestrator checkpoints after setup and after critical findings review.
+
+**New in v2.0.0:**
+
+- **API acquisition (DI-0):** Conditional phase for API-based data sources. The agent researches the API, writes an acquisition script, and stops for user review before execution (external network call boundary).
+- **Multi-file support:** Two classification types — HORIZONTAL (same structure, union-able) and HIERARCHICAL (different entity levels, must be linked). Hierarchical mode adds per-file script suffixes, a cross-file inventory script, and a mandatory cross-level linkage test script.
+- **Progressive disclosure:** Profiling protocol extracted to `WORKFLOW_PHASE_DO_PROFILING.md`, skill authoring to `WORKFLOW_PHASE_DO_AUTHORING.md` — loaded just-in-time.
+- **Terminology:** "Phase A/B/C/D" renamed to "Part A/B/C/D" to avoid collision with Full Pipeline's use of "phases."
+- **Verbosity standards:** Subagent output cap raised from 1,000 to 2,500 words. Scripts must print complete per-column stats — execution logs are archival with no size limit.
+- **Skill quality targets:** New required `analytical-context.md` reference file (including mandatory "What is NOT Included" exclusion table and "Temporal Scope" section). Reference content targets 3x-6x the SKILL.md line count with a hard minimum floor of 3x. Per-file minimums (150-200+ lines).
+- **Domain Assessment protocol:** Before authoring reference files, the engineer must identify analytical domains, group columns into clusters, and create dedicated topic-specific reference files for any domain requiring 50+ lines of explanation.
+- **Exclusion documentation pipeline:** DI-1 intake collects known exclusions, profiling scripts extract exclusion statements from documentation ("does not include," "excludes," "limited to"), and `analytical-context.md` requires a structured exclusion table (minimum 2 entries).
+- **Cross-dataset discovery:** A new authoring step globs for all sibling DAAF data source skills to identify complementary sources sharing join keys, with worked Polars join examples in the skill.
+- **Edge case handling:** When profiling confirms no coded/sentinel values, `value-interpretation.md` is created instead of an empty `coded-values.md`, documenting negative value semantics, null patterns, and expected ranges.
+- **Profiling script bundling:** Profiling scripts are now bundled with skills in a `scripts/` subdirectory for provenance.
+- **Naming convention:** Formal `{domain}-data-source-{acronym}` pattern with validation regex.
+
+##### 2.2 Ad Hoc Collaboration Mode (NEW)
+
+A flexible, user-driven dispatch loop without fixed stages, gates, or mandatory deliverables. The orchestrator operates as a thought partner, responding to conversational questions or dispatching to specialized agents as needed. Thanks to Alberto Guzman-Alvarez and Preston Magouirk for the great nudging in this direction!
+
+**Key features:**
+
+- Deferred workspace creation — folder only created when first artifact is produced
+- `SESSION_NOTES.md` as lightweight continuity artifact (replacing STATE.md)
+- Orchestrator loads `data-scientist` skill directly (exception to the standard subagent-loads-skills pattern)
+- 2,000-word agent output cap (vs. standard 1,000-word pipeline cap)
+- Dispatch table mapping user needs to agents
+
+##### 2.3 Reproducibility Verification Mode (NEW)
+
+A four-stage workflow for re-executing an existing analysis and comparing outputs against originals:
+
+| Stage | Activity |
+|-------|----------|
+| RV-1 | Intake, setup, notebook decompilation into individual scripts |
+| RV-2 | Sequential re-execution with comparison |
+| RV-3 | Report claim verification against reproduced data |
+| RV-4 | Synthesis into Reproduction Report |
+
+**Supporting infrastructure:**
+
+- `decompile_notebook.py` — CLI tool to extract individual scripts from a marimo notebook with a `MANIFEST.md`
+- `compare_execution_logs.py` — programmatic comparison of original vs. reproduced script execution logs (row counts, column counts, key statistics, checkpoint pass/fail)
+- `collect_session_logs.sh` — finds and copies matching session transcripts into a project's `logs/` directory
+- `normalize_project_dir.py` — batch path normalization across decompiled scripts
+- `REPRODUCTION_REPORT_TEMPLATE.md` — the Reproduction Report serves as both deliverable and session state document
+- Mode-specific behavioral overrides in `code-reviewer`, `data-verifier`, and `report-writer` agents
+
+##### 2.4 Framework Development Mode (NEW)
+
+Enables structured, auditable self-modification of DAAF framework components (skills, agents, modes, templates, hooks, configuration).
+
+**Key features:**
+
+- `framework-engineer` agent with six core behaviors: template fidelity, read-before-write, integration completeness, cross-file consistency, minimal disruption, draft-then-place
+- `FRAMEWORK_INTEGRATION_CHECKLIST.md` — canonical registration-point checklist for all component types (skills, agents, modes) with mandatory and conditional items
+- Two checkpoints: after scoping (confirm approach) and after review pass (approve final state)
+- Bidirectional escalation paths to/from all other modes
+- **LEARNINGS.md feedback loop:** New "Incorporate Learnings" work type closes the gap between System Update Action Plans generated at project completion and their consumption back into the framework. A 3-subagent exploration protocol scans all `research/*/LEARNINGS.md` files, checks which items have already been addressed, and proposes prioritized execution order. Full Pipeline and Data Onboarding delivery messages proactively suggest Framework Development mode when action plan items exist.
+
+This works so darn well, I'm really mad I didn't make this sooner! It's made the last legs of development on DAAF v2.0.0 so, so, so much better.
+
+##### 2.5 Data Lookup Mode (renamed from Targeted Assist)
+
+Renamed for clarity — the previous name was ambiguous about the mode's purpose. No behavioral changes; purely a nomenclature improvement.
+
+##### 2.6 Data Discovery Mode (renamed from Discovery)
+
+Renamed for disambiguation from the general concept of "discovery." No behavioral changes.
+
+##### 2.7 Revision and Extension Mode (expanded from Revision Mode)
+
+- Renamed to clarify that the mode handles both fixing existing work and extending it with new analyses
+- Added formal escalation triggers, output format (Revision Status Update template), and session recovery guidance
+- Added "AI Use Disclosure in Revisions" section for disclosure inheritance across versions
+
+##### 2.8 Mode Confirmation Hard Gate
+
+A formal "HARD GATE" is introduced at mode classification: the orchestrator must confirm the mode with the user and receive explicit approval before proceeding. A **Turn Boundary Rule** enforces that no reference files are loaded and no subagents are dispatched in the same turn as the confirmation message. A **Confirmation Self-Check** checklist validates compliance.
+
+---
+
+#### 3. Agent Architecture
+
+##### 3.1 Agent Relocation
+
+All agent definition files moved from `agents/` to `.claude/agents/` to leverage Claude Code's native subagent discovery mechanism. The old `agents/` directory and its 1,180-line README are removed.
+
+A new `.claude/agents/README.md` (~630 lines) serves as the agent index with key inputs, outputs, and cross-references. This also allows the Orchestrator to more efficiently launch agents with pre-loaded agent protocols and default Skills, saving tokens and improving adherence.
+
+##### 3.2 Named Agent Dispatch
+
+All `subagent_type` values changed from generic strings (`"general-purpose"`, `"Plan"`) to agent-specific names (`"research-executor"`, `"code-reviewer"`, `"data-planner"`, etc.). Claude Code automatically loads the agent's protocol file and applies its `tools` and `permissionMode` settings.
+
+##### 3.3 New Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `framework-engineer` | Framework artifact authoring and integration (Framework Development Mode) |
+| `search-agent` | DAAF-native read-only explorer replacing generic `Plan` dispatches across all modes (see §11.1) |
+| `data-ingest` (expanded) | Dataset profiling with multi-file and API support (Data Onboarding Mode) |
+
+##### 3.4 Agent Invocation Template Consolidation
+
+Invocation templates were removed from individual agent files and consolidated into the canonical `WORKFLOW_PHASE*.md` files, eliminating hundreds of lines of duplication. Agent files now focus exclusively on behavioral protocol and anti-patterns.
+
+##### 3.5 Universal Tool Access
+
+The `Skill` tool was added to all 14 agent frontmatter `tools` lists, enabling direct skill invocation from any agent. The `debugger` also gained `WebFetch` and `WebSearch`.
+
+---
+
+#### 4. Enforcement Infrastructure
+
+##### 4.1 File-First Execution Hook (`enforce-file-first.sh`)
+
+A PreToolUse hook that mechanically blocks direct `python`/`python3` invocations, enforcing the file-first execution protocol at the hook layer. Registered per-agent (research-executor, code-reviewer, debugger, data-ingest) rather than globally. Uses fail-closed design with an ERR trap. Framework utility scripts in `/daaf/scripts/` are whitelisted. Currently scoped narrowly to code agents in the pipeline, though we may want to consider adding to the orchestrator and all agents eventually (just gets complicated with things like Marimo notebooks and other utility scripts).
+
+##### 4.2 Orchestrator Loading Enforcement
+
+Two new hooks ensure the `daaf-orchestrator` skill is loaded at session start:
+
+- `remind-orchestrator.sh` (UserPromptSubmit) — injects a reminder if the skill hasn't been loaded
+- `flag-orchestrator-loaded.sh` (PostToolUse on Skill) — writes a session flag when loaded, silencing reminders
+
+##### 4.3 Claude-Code-Guide Denial (`deny-claude-code-guide.sh`)
+
+Blocks the built-in `claude-code-guide` subagent type (Haiku model) from being dispatched within DAAF, as it lacks the reasoning depth for framework-aware work and often is just plain wrong. Hook suggests we launch a search-agent to look directly at the Claude Code documentation online via websearch and webfetch tools. Provides alternative guidance. It's such a good idea with such bad execution; why did they do it like this?
+
+##### 4.4 Context Reporter Improvements
+
+- Time-based rate limiting (60-second injection interval) replacing content-based deduplication
+- Human-readable timestamps in utilization messages
+- Baseline estimate adjusted from 40k to 20k tokens
+- **Subagent support fix:** The hook relied on a session-specific cache file for `MAX_CONTEXT` that did not exist for subagents (different session IDs). Fixed with a fallback chain that finds the parent orchestrator's cache. `CLAUDE.md` expanded with subagent-specific threshold-action table, early return protocol (5 required elements: file paths, findings summary, incomplete task list, decisions/assumptions, confidence assessment), and STATE.md coordination guidance for subagents returning under context pressure.
+- Adjusted context utilization thresholds to be either percentages OR raw token counts at 150k, 200k, and 250k. While Opus and Sonnet can now handle token windows of up to 1m tokens, there's A LOT of evidence that its performance deteriorates quickly -- and regardless, costs skyrocket per turn because of it. May need to revisit later.
+
+##### 4.5 Logging and Audit
+
+- Session log exclusion removed from `.claudeignore` — transcripts now visible for reproducibility collection
+- Edit/Write deny rules added for `.claude/logs/` to prevent audit log modification
+- `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: "1"` added to settings
+- **Per-agent audit traceability:** `agent_type` and `agent_id` fields added to every JSONL audit log entry, enabling post-session filtering by specific agent. Orchestrator calls default to `"orchestrator"`; subagent calls populate the actual agent type and unique ID.
+- Added some utility scripts that automatically pull in copies of relevant session logs into a given project for full auditability in the full pipeline mode.
+
+---
+
+#### 5. Analytical Skills
+
+##### 5.1 New Python Library Skills
+
+| Skill | Lines (SKILL.md + refs) | Key Coverage |
+|-------|------------------------|--------------|
+| **statsmodels** | ~4,300 | OLS/WLS/GLS, GLM (logit, probit, Poisson, NB), robust regression, ARIMA/SARIMAX/VAR, mixed effects, diagnostics, hypothesis testing |
+| **pyfixest** | ~2,400 | High-dimensional FE (OLS/IV/Poisson), DiD (TWFE, did2s, lpdid, Sun-Abraham), wild bootstrap, publication tables via `etable()`. Targets v0.40.0 with breaking-change documentation. |
+| **linearmodels** | ~2,900 | PanelOLS (FE/RE), BetweenOLS, FirstDifferenceOLS, Fama-MacBeth, IV2SLS/LIML/GMM, SUR, IV3SLS, asset pricing. Cross-library syntax comparison tables. |
+| **scikit-learn** | ~3,000 | KMeans, DBSCAN, HDBSCAN, PCA, t-SNE, UMAP, GMM (unsupervised). Logistic regression, random forest, gradient boosting, SVM, Ridge/Lasso (supervised). Preprocessing, pipelines, cross-validation, feature selection. Targets v1.8.0. |
+| **geopandas** | ~3,400 | GeoDataFrames, spatial joins, CRS/projections, raster integration (rasterio, xarray), PySAL ecosystem (Moran's I, LISA, spatial regression), visualization (matplotlib + contextily, folium, lonboard). Targets v1.1.3. |
+| **svy** | ~1,700 | Complex survey data analysis: design specification (strata, PSU, weights, FPC), variance estimation (Taylor linearization, BRR, jackknife, bootstrap), survey-weighted GLM regression (gaussian, binomial, Poisson), domain/subpopulation estimation, calibration, survey data I/O. Targets v0.13.0 (supersedes archived samplics). |
+| **science-communication** | ~1,700 | Audience analysis, narrative frameworks (Pyramid Principle, SCQA, AIDA), plain-language translation, hedging/uncertainty (IPCC calibrated), deliverable templates (executive summary, policy brief), accessibility/equity, pre-release review checklist. |
+
+Each skill follows the SKILL.md + deep references architecture with decision trees for routing and explicit boundary documentation against sibling skills.
+
+##### 5.2 Cross-Language Translation Skills and User Language Preferences
+
+Two translation skills provide verb-by-verb mappings from R and Stata to their Python equivalents, enabling inline code annotations for users with non-Python backgrounds.
+
+| Skill | Lines (SKILL.md + refs) | Key Coverage |
+|-------|------------------------|--------------|
+| **r-python-translation** | ~7,400 | tidyverse → polars, ggplot2 → plotnine, fixest → pyfixest, survey → svy, sf → geopandas, plm → linearmodels. Paradigm differences, gotchas, external resources. |
+| **stata-python-translation** | ~8,700 | Data management, strings/dates/labels, regression modeling, causal inference, visualization, survey/spatial/ML, workflow/environment. Mirrors the R skill architecture. |
+
+**User Language Preference System:** A persistent, cross-session preference mechanism stored in `CLAUDE.md` § User Preferences. The orchestrator detects R/Stata background signals (explicit: "I use R"; implicit: R/Stata syntax in pseudocode), proposes persisting the preference, and silently propagates a translation directive to all 4 code-producing agents (research-executor, code-reviewer, debugger, data-ingest) across all sessions. Wired into 5 mode reference documents and 2 workflow phase invocation templates.
+
+##### 5.3 Supervised ML Track
+
+- New `supervised-ml.md` methodology reference for the `data-scientist` skill covering prediction vs. inference (Shmueli 2010), bias-variance tradeoff, cross-validation strategies, model selection, feature importance caveats, algorithmic fairness impossibility theorems, and reporting standards
+- New `scikit-learn/references/interpretation.md` — SHAP (TreeExplainer, KernelExplainer), permutation importance, partial dependence, ICE plots
+- New `scikit-learn/references/fairness.md` — fairlearn MetricFrame, ThresholdOptimizer, ExponentiatedGradient, demographic parity, equalized odds
+- LightGBM and XGBoost sections added to classification and regression references
+- Supervised ML routing wired into Full Pipeline modeling library selection
+
+##### 5.4 Data-Scientist Skill Expansion
+
+The `data-scientist` skill was restructured from a single "statistical analysis" routing branch into seven methodology-specific routing trees with eight new reference files (~5,050 lines total):
+
+| Reference File | Coverage |
+|---|---|
+| `causal-inference.md` | DAGs, potential outcomes, RCT, IV/2SLS, RD, DiD, synthetic control, matching/PSM |
+| `descriptive-analysis.md` | Summary statistics, distributions, cross-tabulations, temporal patterns |
+| `statistical-modeling.md` | Model selection, assumption checking, diagnostics |
+| `survey-analysis.md` | Complex survey design anatomy, weight selection, variance estimation methods, domain estimation, plausible values, survey-weighted regression, federal survey reference table, pitfalls checklist |
+| `exploratory-unsupervised.md` | Clustering, PCA, nonlinear embeddings, cluster validation |
+| `supervised-ml.md` | Prediction vs. inference, cross-validation, fairness, reporting |
+| `geospatial-analysis.md` | MAUP, CRS, spatial autocorrelation, spatial regression |
+| `geospatial-operations.md` | Spatial joins, weights, LISA, interpolation, zonal statistics |
+
+A ~125-row topic index in SKILL.md maps specific analytical topics to the correct reference file. Beefy, but definitely worthwhile and still extensible.
+
+##### 5.5 Modeling Library Pipeline Wiring
+
+- `data-planner` task specs now require a `<skill>` element specifying the modeling library
+- `research-executor` skill loading tables updated with conditional library loading and fallback rules
+- `debugger` gains a "Modeling Library Gotchas" section with per-library failure mode summaries
+- `report-writer` gains conditional Step 5.5 for science-communication skill loading when target audience is non-technical
+- `PLAN_TEMPLATE.md` gains a "Target Audience" field controlling communication skill routing
+
+---
+
+#### 6. Research Integrity and Attribution
+
+##### 6.1 AI Use Disclosure (GUIDE-LLM Alignment)
+
+A structured AI Use Disclosure section is added to all reports, mapping to the GUIDE-LLM v2026 reporting checklist (Feuerriegel et al.). `AI_DISCLOSURE_REFERENCE.md` maps every checklist item (A.1 through G.1) to its DAAF artifact source, tagged as `[AUTO]` (auto-populated by report-writer) or `[RESEARCHER]` (requires human completion).
+
+Session metadata (DAAF version via git commit hash, model ID, session dates, transcript path) is captured in STATE.md at project setup and passed through to the report-writer.
+
+AI disclosure guidance is added for all modes — including Data Discovery, Data Lookup, Revision and Extension, and Reproducibility Verification.
+
+##### 6.2 Citation Framework
+
+- `CITATION.cff` — machine-readable software citation (CFF standard) identifying DAAF 2.0.0 as citable software
+- APA and BibTeX citation formats in README
+- Layered citation guidance (DAAF + Claude + data sources + GUIDE-LLM)
+- "Software & Tools" citations sub-section in report template
+- FORCE11 software citation principles alignment
+
+##### 6.3 Citation Propagation System
+
+A distributed citation flow that tracks methodological and software attribution across the entire pipeline, from skill loading through report generation:
+
+1. **Skill-level citation blocks:** 13 skills now carry `## Citation` sections with canonical citation text, "Cite when" / "Do not cite when" inclusion thresholds, and secondary citation guidance.
+2. **Research-executor tracking:** New `Citation Tracking` core behavior and `Citations` output section. The executor reports a table of `software`/`method` type citations with rationale as part of its return format.
+3. **Orchestrator accumulation:** STATE.md gains a `Citations Accumulated` section with four tables (Data Sources, Methodological References, Software & Tools, Reporting Standards). DAAF, marimo, and GUIDE-LLM are pre-populated at project setup.
+4. **Report-writer rendering:** The References section is now sourced from STATE.md (not verbatim Stage 6 text) and rendered as four subsections with "_Cited because:_" rationale lines for non-data-source entries.
+5. **Verification:** The data-verifier gains a citation verification step. `CITATION_REFERENCE.md` serves as a centralized index covering ~30 methods and tools with inclusion thresholds and a parsimony principle ("A report with 5 well-justified citations is better than one with 30 perfunctory ones").
+
+User-facing documentation (first-run transparency statement, Understanding DAAF guide, Best Practices guide) updated to explain the References section and advise researchers that citations are "best-effort, not guaranteed."
+
+##### 6.4 Pre-Launch Citation Audit
+
+A systematic audit verified 1,005 citations, references, URLs, and attributed API claims across 46 skill reference files in 12 skill areas. 58 corrections applied:
+
+- **HIGH (5):** Fabricated author names, wrong page numbers, reversed author order, wrong journal name
+- **MEDIUM (19):** Incorrect API claims across polars (6), statsmodels (3), linearmodels (3), marimo (3), scikit-learn (1), plotnine (1), plotly (2)
+- **LOW (32):** Outdated claims, deprecated parameters, incomplete option lists, dead URLs
+
+---
+
+#### 7. Skill Metadata and Authoring
+
+##### 7.1 Controlled Vocabulary
+
+Formal controlled vocabulary defined for skill frontmatter:
+
+- `audience`: `any-agent`, `research-orchestrator`, `research-planner`, `research-coders`, `research-writers`
+- `domain`: `data-source`, `data-access`, `data-documentation`, `python-library`, `research-methodology`, `research-orchestration`, `research-communication`, `skill-development`
+- Standard keys: `library-version`, `skill-authored`, `skill-last-updated`
+
+Applied uniformly across all 35 skill files with description enrichment.
+
+##### 7.2 Skill Authoring Guide Updates
+
+- "Concise is Key" replaced with "Right-Size Each Level": SKILL.md concise, reference files comprehensive
+- Reference file density guidelines: 3x-6x ratio of reference lines to SKILL.md lines
+- Anemic reference files flagged as harmful as bloated SKILL.md files
+- Data source skill naming convention: `{domain}-data-source-{acronym}` with validation regex
+- **250-character frontmatter limit accommodation** — see §11.2
+
+---
+
+#### 8. User Experience
+
+##### 8.1 Tone and Voice Standards
+
+Comprehensive tone specification added to the orchestrator:
+
+- **Warm:** Encouraging, acknowledges good questions, celebrates interesting findings
+- **Thoughtful:** Explains _why_ things matter, connects dots between phases
+- **Patient and methodical:** Never rushes past decision points, confirms understanding
+- **Educational:** Explains data caveats and methodology tradeoffs as they arise
+- **Direct but not terse:** Concise without being cold
+- **Honest about uncertainty:** Plain acknowledgment of ambiguity and limitations
+
+##### 8.2 Plain-Language Communication
+
+A translation table maps internal terminology to user-facing language (e.g., "PSU" becomes "phase checkpoint," "QA" becomes "quality review," "Stage N" becomes "step" or activity description). Internal terms like "Composite execution pattern" and "Gate GN" are never exposed.
+
+##### 8.3 Welcome Preamble
+
+Every conversation begins with a brief introduction to DAAF. An expanded orientation is triggered on newcomer signals ("how does this work," "what can you do"). Context-sensitive help table maps user signals to appropriate documentation files.
+
+##### 8.4 First-Time User Transparency Statement
+
+A first-run onboarding hook detects new users (via `activity.log` session count) and presents a candid transparency statement before the normal welcome flow. The statement covers what DAAF is and isn't, inherent LLM limitations (hallucination, sycophancy, over-confidence, non-determinism), the probabilistic nature of DAAF's quality improvements, the primacy of researcher expertise, and practical guidance for new users. Delivered in conversational tone, not as a terms-of-service wall.
+
+---
+
+#### 9. Infrastructure and Environment
+
+##### 9.1 Dockerfile
+
+New package layers for:
+
+- **Econometrics:** linearmodels, rdrobust, marginaleffects, arch, pydynpd, svy
+- **Geospatial:** geopandas, rasterio, xarray, rioxarray, contextily, folium, libpysal, esda, spreg, mapclassify, rasterstats, geopy, osmnx
+- **Geospatial system libraries:** libgdal-dev, gdal-bin, libgeos-dev, libproj-dev (required by fiona, a transitive dependency of rasterstats)
+- **ML:** shap, fairlearn, lightgbm, umap-learn
+- **Utilities:** poppler-utils (PDF support), tabulate, great-tables, wildboottest, fastexcel
+
+**Post-smoke-test stabilization:** 16 previously-floating packages pinned to exact versions for reproducible builds. `samplics` removed (superseded by svy). `kaleido` removed (Chromium dependency incompatible with container; plotly skill updated with workaround guidance to use plotnine for static figures). A follow-up smoke test run (246 tests) corrected additional skill documentation in pyfixest, svy, and plotly. Docker volume permissions fixed for macOS (named volumes with root ownership blocking `appuser`).
+
+Model configuration updated to `claude-opus-4-6[1m]` (1M context window).
+
+##### 9.2 New Utility Scripts
+
+| Script | Purpose |
+|--------|---------|
+| `scripts/decompile_notebook.py` | Extract individual scripts from a marimo notebook |
+| `scripts/compare_execution_logs.py` | Compare original vs. reproduced execution logs |
+| `scripts/collect_session_logs.sh` | Find and copy matching session transcripts |
+| `scripts/normalize_project_dir.py` | Batch path normalization across decompiled scripts |
+
+##### 9.3 Installation Simplification
+
+Git removed as a host-machine prerequisite. Installation now uses ZIP download (`curl`/`Invoke-WebRequest`) instead of `git clone`, reducing prerequisites from four to three. `docker-compose.yml` gains `name: daaf` for folder-independent volume naming (ZIP extracts to `daaf-main/` rather than `daaf/`). Update procedure rewritten with ZIP-based commands that copy framework files into the Docker volume while preserving the `research/` folder.
+
+##### 9.4 CLAUDE.md Philosophy
+
+The Identity section was expanded from a brief description to a full philosophical statement: DAAF as a "force-multiplying exo-skeleton," the five core requirements (Transparent, Rigorous, Reproducible, Responsible, Scalable), and the primacy of human researcher judgment.
+
+---
+
+#### 10. Documentation
+
+##### 10.1 New Reference Files
+
+| File | Purpose |
+|------|---------|
+| `AI_DISCLOSURE_REFERENCE.md` | GUIDE-LLM checklist mapping for all modes |
+| `FRAMEWORK_INTEGRATION_CHECKLIST.md` | Registration-point checklists for skills, agents, modes |
+| `MODE_TEMPLATE.md` | Template for authoring new engagement modes |
+| `PLAN_TASKS_TEMPLATE.md` | Template for the task-block document |
+| `REPRODUCTION_REPORT_TEMPLATE.md` | Template for Reproducibility Verification output |
+| `STATE_TEMPLATE_ONBOARDING.md` | State template for Data Onboarding mode |
+| `CITATION_REFERENCE.md` | Citation index for pipeline citation propagation and verification |
+
+##### 10.2 Expanded Templates
+
+- `AGENT_TEMPLATE.md` — expanded with per-agent hook registration, skills-in-frontmatter guidance
+- `DATA_SOURCE_SKILL_TEMPLATE.md` — API data access skeleton, multi-file structure section, analytical-context.md requirement
+- `MODE_TEMPLATE.md` — expanded from 6-item to 13-item checklist with naming conventions and exemplar references
+- `REPORT_TEMPLATE.md` — AI Use Disclosure section, Software & Tools citations
+- `STATE_TEMPLATE.md` — session metadata, per-script QA status, gate status tracking
+
+##### 10.3 User Documentation Updates
+
+All files in `user_reference/` updated to reflect eight engagement modes, three-document Plan structure, Data Onboarding capabilities, and Framework Development mode. Best practices and extending-DAAF guides revised.
+
+---
+
+#### 11. Claude Code Platform Adaptations
+
+Changes driven by testing DAAF against Claude Code's actual runtime behavior, addressing platform constraints and improving observability.
+
+##### 11.1 search-agent Replaces Generic Plan Dispatches
+
+Generic `Plan` subagent dispatches lacked reasoning depth for DAAF's domain-aware exploration tasks. A new `search-agent` (413-line agent definition, full 12-section template) serves as DAAF's 14th agent — a broad-purpose, read-only explorer with web access (WebSearch, WebFetch) and skill-aware domain knowledge. All exploration dispatches across Data Discovery, Data Lookup, Framework Development, and Full Pipeline modes changed from `Plan` to `search-agent`. The `Plan` generic type is de-prioritized rather than removed. The `Explore` subagent type remains blocked (runs on Haiku); error messages now recommend `search-agent`.
+
+##### 11.2 Frontmatter Description Truncation Accommodation
+
+Claude Code silently truncates skill frontmatter `description` fields at ~250 characters. All 35 DAAF skills (previously 381-813 chars) were losing trigger and disambiguation text without any visible error. All descriptions condensed to fit within 250 characters. Full descriptions preserved as plain paragraphs immediately after the `# Title` heading in each SKILL.md body. The skill-authoring reference (`frontmatter.md`) updated with the 250-char hard limit, budget priorities, and the "Full Description in Body" pattern.
+
+##### 11.3 Subagent Transcript Archiving
+
+Previously, only the orchestrator's session transcript was archived. A new observability pipeline captures subagent activity:
+
+- **`subagent-registry.sh`** — new `SubagentStop` hook records each subagent's metadata (agent\_type, agent\_id, transcript\_path, tool\_uses, duration) to a per-session JSONL registry file
+- **`archive-session.sh` expansion** — at session end, copies each subagent's JSONL transcript into the archive with `_subagent_{id}` suffixes, renders companion Markdown files, and appends a "Subagent Activity" summary table to the orchestrator's Markdown archive
+- **Unified naming convention:** `{date}_{time}_{session}_orchestrator.{jsonl,md}` and `{date}_{time}_{session}_subagent_{id}.{jsonl,md}` — all files from one session sort together
+
+##### 11.4 Script Execution Portability
+
+- `run_with_capture.sh` changed from `python` to `python3` for PEP 394 portability
+- Copy-into-project pattern eliminated across 17 files — all execution now references the canonical copy at `{BASE_DIR}/scripts/run_with_capture.sh` rather than per-project copies
+- Shell script executable permission convention established: all `.sh` files must be committed with mode `100755` via `git update-index --chmod=+x`, documented across 6 framework files (CLAUDE.md, framework-engineer agent, integration checklist, script execution reference, skill-authoring reference, framework-development mode)
+
+---
+
+### Breaking Changes Summary
+
+These changes affect the internal framework structure. External users consuming DAAF analyses are unaffected.
+
+| Change | Impact | Migration |
+|--------|--------|-----------|
+| `CLAUDE.md` reduced to conventions only | Orchestration logic must be loaded via `daaf-orchestrator` skill | Load skill at session start (enforced by hooks) |
+| Agents moved from `agents/` to `.claude/agents/` | Path references must update | All internal references updated |
+| `subagent_type` changed to agent-specific names | Orchestrator dispatch must use named agents | All invocation templates updated |
+| Plan split into Plan + Plan\_Tasks + State | Existing single-Plan projects structurally incompatible | Create Plan\_Tasks.md and STATE.md from existing Plan |
+| Multiple reference files renamed/deleted | Hardcoded path references break | See File Renames table above |
+| "Data Ingest" renamed to "Data Onboarding" | Mode name references must update | All internal references updated |
+| "Phase A/B/C/D" renamed to "Part A/B/C/D" | Data Onboarding terminology must update | All internal references updated |
+| Direct `python` calls blocked in coding agents | Must use `run_with_capture.sh` wrapper | Already enforced by hook |
+| `claude-code-guide` subagent blocked | Cannot dispatch Haiku-based guide agent | Use `search-agent` (has WebFetch/WebSearch) |
+| Generic `Plan` dispatches replaced by `search-agent` | Exploration tasks use named agent | All invocation templates updated |
+| `run_with_capture.sh` path changed from `{PROJECT_DIR}` to `{BASE_DIR}` | Per-project copy references break | All execution now uses `{BASE_DIR}/scripts/run_with_capture.sh` |
+
+**Full Changelog**: [v1.0.0...v2.0.0](https://github.com/DAAF-Contribution-Community/daaf/compare/v1.0.0...v2.0.0)
+
+---
+
+## v1.0.0 — 2026-02-22
+
+### Data Analyst Augmentation Framework — Launch Release
+
+The initial public release of DAAF, an open-source, extensible AI-augmented research workflow for Claude Code that allows skilled researchers to rapidly scale their expertise and accelerate data analysis — without sacrificing transparency, rigor, or reproducibility.
+
+#### Core Framework
+
+- Multi-stage research pipeline with mandatory validation and quality checkpoints at every stage
+- Specialized agents that tackle each stage of the research pipeline with specific insights, strategies, and expertise (e.g., research-executor, code-reviewer, data-planner, plan-checker, data-verifier, source-researcher)
+- Per-script QA with adversarial code review where every transformation has a validation, and all data operations are stored in a file-first format for maximum auditability
+
+#### Skills Ecosystem
+
+- Analytical tools for data analysis: Polars, plotnine, Plotly, marimo, data-scientist
+- Data sources: 15 source-specific data skills (CCD, IPEDS, CRDC, Scorecard, EDFacts, MEPS, SAIPE, FSA, NHGIS, NCCS, PSEO, EADA, NACUBO, Campus Safety) plus query, explorer, and context skills, to answer hundreds of meaningful research questions about education out-of-the-box
+- Extensibility tools to easily expand the data domains to any field/dataset you need
+
+#### Documentation
+
+- User guides: installation/quickstart, understanding DAAF, best practices, extending DAAF, philosophy FAQ, technical FAQ
+- 10-minute demo video walkthrough
+- Complete example project for review (College Graduation Rate Selectivity Analysis)
+
+#### Infrastructure
+
+- Docker containerized environment with defense-in-depth security
+- Pre-commit hooks, audit logging, session archiving
+- LGPL-3.0 license (core framework open; extensions can be proprietary)
diff --git a/CLAUDE.md b/CLAUDE.md
index e8ac982..ea266fb 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -210,6 +210,7 @@ Context management is NEVER about reducing the quality or completeness of work.
 - You MUST NEVER read, display, or commit files matching: `.env`, `.env.*`, `*.pem`, `*.key`, `credentials*`, or `secrets/`
 - You MUST NEVER output API keys, tokens, or private key material that appears in tool output — if detected, acknowledge the leak and stop
 - You MUST NEVER create `.env` files or write credentials to any file
+- Note: Users set data source API keys via an `environment_settings.txt` file on the **host** machine (in the `daaf-docker/` folder), which Docker Compose injects into the container as environment variables at startup. This file is outside the container filesystem and invisible to Claude. Scripts access these keys via `os.environ[]` as usual. If a user asks about setting API keys, direct them to the `environment_settings_example.txt` template in their `daaf-docker/` folder.
 
 ### Destructive Command Prevention
 
@@ -289,6 +290,7 @@ bash {BASE_DIR}/scripts/run_with_capture.sh {PROJECT_DIR}/scripts/stage5_fetch/0
 | Raw Data | `YYYY-MM-DD[suffix]_[source]_[description].parquet` | `2026-01-24a_ccd_schools.parquet` |
 | Processed Data | `YYYY-MM-DD[suffix]_[description].parquet` | `2026-01-24a_analysis_data.parquet` |
 | Figures | `YYYY-MM-DD[suffix]_[description].png` | `2026-01-24a_enrollment_trends.png` |
+| Preliminary Notes | `YYYY-MM-DD[suffix]_[stage]_[descriptor].md` | `2026-01-24a_stage3_ccd_source-research.md` |
 | Reproduction Report | `Reproduction_Report.md` | `Reproduction_Report.md` |
 
 > **Note:** The Reproduction Report uses a fixed name (not date-prefixed) because it serves as both the primary deliverable and the session state document for Reproducibility Verification mode.
@@ -328,150 +330,6 @@ See `agent_reference/SCRIPT_EXECUTION_REFERENCE.md` for complete script template
 
 ---
 
-## Example Project Structure
-
-```
-research/2026-01-24_School_Poverty_Analysis/
-├── 2026-01-24_School_Poverty_Analysis_Plan.md
-├── 2026-01-24_School_Poverty_Analysis_Plan_Tasks.md
-├── 2026-01-24_School_Poverty_Analysis.py
-├── 2026-01-24_School_Poverty_Analysis_Report.md
-├── LEARNINGS.md                                   # Session learnings (REQUIRED)
-├── logs/                                          # Session transcripts (collected at completion)
-│   ├── 2026-01-24_19-30-41_7226a42c.jsonl         # Raw JSONL transcript
-│   └── 2026-01-24_19-30-41_7226a42c.md            # Human-readable transcript
-├── scripts/                                       # All executed scripts (code archive)
-│   ├── stage5_fetch/
-│   │   ├── 01_fetch-ccd.py
-│   │   ├── 02_fetch-ipeds.py
-│   ├── stage6_clean/
-│   │   ├── 01_clean-ccd.py
-│   ├── stage7_transform/
-│   │   └── 01_join-data.py
-│   │   └── 02_process-data.py
-│   ├── stage8_analysis/
-│   │   ├── 01_regression-poverty.py
-│   │   └── 02_enrollment-plot.py
-│   ├── cr/                           # Code-review inspection scripts (iterative)
-│   │   ├── stage5_01_cr1.py          # CR for 01_fetch-ccd.py (standard + profiling)
-│   │   ├── stage5_02_cr1.py          # CR for 01_fetch-ipeds.py (standard + profiling)
-│   │   ├── stage6_01_cr1.py          # CR for 01_clean-ccd.py
-│   │   ├── stage7_01_cr1.py          # CR for 01_join-data.py
-│   │   ├── stage7_02_cr1.py          # CR for 02_process-data.py
-│   │   ├── stage7_02_cr2.py          # Additional checks for 02_process-data.py
-│   │   ├── stage8_01_cra1.py          # QA4a for 01_regression-poverty.py (analysis)
-│   │   ├── stage8_01_cra2.py          # Additional QA4a checks for 01_regression-poverty.py
-│   │   └── stage8_02_crb1.py          # QA4b for 02_enrollment-plot.py (visualization)
-│   └── debug/                                     # If debugging occurred
-│       └── 01_diag-key-mismatch.py
-├── data/
-│   ├── raw/
-│   │   ├── 2026-01-24_ccd_schools.parquet
-│   │   ├── 2026-01-24_meps_poverty.parquet
-│   └── processed/
-│       ├── 2026-01-24_ccd_clean.parquet
-│       ├── 2026-01-24_analysis.parquet
-├── output/
-│   ├── analysis/
-│   │   └── 2026-01-24_regression_results.parquet
-│   └── figures/
-│       └── 2026-01-24_poverty_distribution.png
-└── STATE.md                                       # Session state (REQUIRED for Full Pipeline)
-```
-
-### Data Onboarding Example Project Structure
-
-```
-research/2026-03-23_Onboarding_County_Elections/
-├── STATE.md                                       # Session state (REQUIRED)
-├── LEARNINGS.md                                   # Session learnings (REQUIRED)
-├── logs/                                          # Session transcripts (collected at completion)
-│   ├── 2026-03-23_22-15-08_b3f1c9d2.jsonl
-│   └── 2026-03-23_22-15-08_b3f1c9d2.md
-├── scripts/
-│   ├── profile_structural/
-│   │   ├── 01_load-and-format.py
-│   │   ├── 02_structural-profile.py
-│   │   └── 03_column-profile.py
-│   ├── profile_statistical/
-│   │   ├── 04_distribution-analysis.py
-│   │   ├── 05_temporal-coverage.py
-│   │   └── 06_entity-coverage.py
-│   ├── profile_relational/
-│   │   ├── 07_key-integrity.py
-│   │   ├── 08_correlation-dependency.py
-│   │   └── 09_quality-anomaly.py
-│   ├── profile_interpretation/
-│   │   ├── 10_semantic-interpretation.py
-│   │   └── 11_reconcile-docs.py
-│   └── cr/                                        # QA review scripts (phase-based)
-│       ├── profile_structural_cr1.py              # QAP1 review
-│       ├── profile_statistical_cr1.py             # QAP2 review
-│       ├── profile_relational_cr1.py              # QAP3 review
-│       └── profile_interpretation_cr1.py          # QAP4 review
-├── data/
-│   └── raw/
-│       └── 2026-03-23_countypres.parquet
-└── output/
-    └── skill_draft/
-        └── SKILL.md                               # Draft skill before final placement
-```
-
-**Variants for API and HIERARCHICAL onboarding:** The example above shows the single-file local-file case. For other configurations, the following additional artifacts appear:
-
-- **API acquisition (DI-0):** `scripts/stage5_fetch/00_api-fetch.py` added; `data/raw/` contains the API-downloaded file
-- **HIERARCHICAL (multi-file):** Scripts are suffixed per-file (`01_inventory.py`, `01a_load-and-format.py`, `01b_load-and-format.py`, etc.); `scripts/profile_relational/07b_cross-level-linkage.py` added; `data/raw/` contains one file per entity type
-- **API + HIERARCHICAL:** Both patterns combined; multiple `00{x}_api-fetch.py` scripts if multiple endpoints
-
-### Reproducibility Verification Example Project Structure
-
-```
-research/2026-03-24_College_Graduation_Analysis_Reproduction/
-├── Reproduction_Report.md                         # Central artifact + session state (REQUIRED)
-│   # Note: No STATE.md or LEARNINGS.md in RV projects — the Reproduction
-│   # Report serves as session state; methodological observations go within it.
-├── logs/                                          # Session transcripts (collected at completion)
-│   ├── 2026-03-24_18-45-12_c4e2a7f1.jsonl
-│   └── 2026-03-24_18-45-12_c4e2a7f1.md
-├── original_files/
-│   ├── 2026-02-15_College_Graduation_Report.md    # Original Report (copied, read-only)
-│   ├── 2026-02-15_College_Graduation_Analysis.py  # Original Notebook (copied, read-only)
-│   ├── output/                                    # Original output (copied, read-only)
-│   │   └── figures/
-│   │       ├── 2026-02-15_selectivity_scatter.png
-│   │       └── 2026-02-15_graduation_heatmap.png
-│   └── scripts/                                   # Decompiled from notebook
-│       ├── MANIFEST.md                            # Decompiler output manifest
-│       ├── stage5_fetch/
-│       │   ├── 01_fetch-directory_a.py
-│       │   └── 02_fetch-ipeds.py
-│       ├── stage6_clean/
-│       │   └── 01_clean-data.py
-│       ├── stage7_transform/
-│       │   └── 01_join-data.py
-│       └── stage8_analysis/
-│           ├── 01_regression.py
-│           └── 02_visualization.py
-├── output/                                        # Reproduced output (generated during RV-2)
-│   └── figures/
-│       ├── 2026-03-24_selectivity_scatter.png
-│       └── 2026-03-24_graduation_heatmap.png
-└── scripts/
-    └── repro/                                     # Re-executed scripts (with new logs)
-        ├── stage5_fetch/
-        │   ├── 01_fetch-directory_a.py
-        │   └── 02_fetch-ipeds.py
-        ├── stage6_clean/
-        │   └── 01_clean-data.py
-        ├── stage7_transform/
-        │   └── 01_join-data.py
-        └── stage8_analysis/
-            ├── 01_regression.py
-            └── 02_visualization.py
-```
-
----
-
 ## Reference Files
 
 | File | Purpose |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9e57672..573f7b8 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -73,6 +73,8 @@ Given what DAAF is, it would be somewhat ironic to ban AI-assisted contributions
 
 ## Quick Start: Contribution Workflow
 
+*New to Git and GitHub? GitHub's [contribution guide](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) walks through the basics, or you can ask DAAF's User Support mode for help with the workflow.*
+
 The standard contribution workflow has ten steps:
 
 1. **Open an issue** and begin a conversation about what you want to improve/add/suggest (ideally starting here!) 
@@ -124,7 +126,8 @@ Use a prefix that describes the nature of the change, followed by a colon and a
 
 All contributions to DAAF must be signed off under the [Developer Certificate of Origin v1.1](https://developercertificate.org/) (DCO). By signing off, you certify that you have the right to submit the contribution under the project's open-source license.
 
-### Full DCO Text
+<details>
+<summary><strong>Full DCO Text (click to expand)</strong></summary>
 
 ```
 Developer Certificate of Origin
@@ -161,6 +164,7 @@ By making a contribution to this project, I certify that:
     maintained indefinitely and may be redistributed consistent with
     this project or the open source license(s) involved.
 ```
+</details>
 
 ### How to Sign Off
 
@@ -374,38 +378,13 @@ If you're modifying hooks (`.claude/hooks/`), Docker configuration, or other inf
 
 ## Using Session Logs for Debugging and Issue Reports
 
-Session logs are one of DAAF's most valuable diagnostic tools. Here's how to find, read, and use them.
-
-### Where Session Logs Are Stored
-
-Claude Code automatically archives a complete log of every session when it ends. These are stored locally in `.claude/logs/sessions/` in two formats:
-
-| Format | File Pattern | Purpose |
-|--------|-------------|---------|
-| **Markdown** (`.md`) | `YYYY-MM-DD_HH-MM-SS_<session-id>_orchestrator.md` | Human-readable transcript with tool calls, timestamps, and token usage |
-| **JSONL** (`.jsonl`) | `YYYY-MM-DD_HH-MM-SS_<session-id>_orchestrator.jsonl` | Raw machine-readable transcript (full API-level detail) |
-| **Subagent JSONL** | `YYYY-MM-DD_HH-MM-SS_<session-id>_subagent_<agent-id>.jsonl` | Raw transcript for each subagent dispatched during the session |
-
-The orchestrator Markdown archive includes a **Subagent Activity** summary table listing each subagent's type, duration, tool uses, and a final-message excerpt.
-
-Additionally, `.claude/logs/activity.log` records a timestamped entry every time a session starts, giving you a quick overview of usage history, while `.claude/logs/audit.jsonl` gives a full inventory of every tool call by Claude for additional diagnostics.
-
-**These logs are gitignored by default** (they may contain sensitive content or API details), so they stay on your local machine and are never pushed to the repository.
-
-### Reading Session Logs for Debugging
-
-Session logs are invaluable when something goes wrong. The Markdown logs show you exactly what the assistant did, in order -- every tool call, every file read/write, every subagent invocation, and the full output at each step. If you need to file a bug report or understand an unexpected result:
-
-1. Find the relevant session log in `.claude/logs/sessions/` (sorted by timestamp)
-2. Open the `.md` file to review what happened in a readable format
-3. Look for the point where things went wrong -- you will see the exact tool calls and their results
-4. When filing an issue, include relevant excerpts from the log (redact any sensitive data first)
+Session logs are automatically archived transcripts of every Claude Code session, stored in `.claude/logs/sessions/` as both human-readable Markdown and machine-readable JSONL files. They capture every tool call, subagent dispatch, and file operation -- making them invaluable for debugging and issue reports.
 
-The `.jsonl` file contains the complete raw transcript if deeper inspection is needed.
+For details on finding, reading, and browsing session logs (including the DAAF Log Explorer interactive viewer), see [**FAQ: Session Logs and Diagnostics**](user_reference/07_faq_technical.md#session-logs-and-diagnostics).
 
 ### Including Log Excerpts in Issues
 
-When including session log excerpts in issues:
+When including session log excerpts in issue reports:
 
 1. Open the `.md` log file for the session where the problem occurred
 2. Find the relevant section (search for the stage or error message)
diff --git a/Dockerfile b/Dockerfile
index bbe721f..0d51090 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -134,12 +134,27 @@ RUN uv pip install --system \
     fairlearn==0.12.0 \
     lightgbm==4.6.0
 
+# ============================================
+# Install code-server (browser-based VS Code)
+# ============================================
+ARG CODE_SERVER_VERSION=4.117.0
+RUN ARCH=$(dpkg --print-architecture) \
+    && curl -fOL https://github.com/coder/code-server/releases/download/v${CODE_SERVER_VERSION}/code-server_${CODE_SERVER_VERSION}_${ARCH}.deb \
+    && dpkg -i code-server_${CODE_SERVER_VERSION}_${ARCH}.deb \
+    && rm -f code-server_${CODE_SERVER_VERSION}_${ARCH}.deb
+
 # ============================================
 # Create non-root user for security
 # ============================================
 RUN groupadd --gid 1000 appuser \
     && useradd --uid 1000 --gid 1000 --create-home appuser
 
+# Create code-server directories owned by appuser
+RUN mkdir -p /home/appuser/.local/share/code-server/User \
+             /home/appuser/.config/code-server \
+    && chown -R appuser:appuser /home/appuser/.local \
+                                /home/appuser/.config
+
 # ============================================
 # Set up working directory
 # ============================================
@@ -147,15 +162,64 @@ WORKDIR /daaf
 RUN chown appuser:appuser /daaf
 USER appuser
 
+# Install code-server extensions from Open VSX (pinned via VSIX download)
+# The @version CLI syntax is broken (silently installs latest), so we download
+# each .vsix directly from Open VSX and install from file.
+# ms-python.python dependencies (debugpy, vscode-python-envs) must be installed
+# before the parent extension to avoid activation errors.
+ARG EXT_MS_PYTHON=2026.4.0
+ARG EXT_MS_DEBUGPY=2026.6.0
+ARG EXT_MS_PYTHON_ENVS=1.28.0
+ARG EXT_MARKDOWN_AIO=3.6.2
+ARG EXT_GIT_GRAPH=1.30.0
+ARG EXT_GITLENS=17.12.2
+ARG EXT_RAINBOW_CSV=3.24.1
+ARG EXT_YAML=1.22.0
+ARG EXT_GITHUB_THEME=6.3.5
+RUN VSCODE_ARCH=$(if [ "$(dpkg --print-architecture)" = "amd64" ]; then echo x64; else echo arm64; fi) \
+    && curl -fsSL -o /tmp/debugpy.vsix \
+      "https://open-vsx.org/api/ms-python/debugpy/linux-${VSCODE_ARCH}/${EXT_MS_DEBUGPY}/file/ms-python.debugpy-${EXT_MS_DEBUGPY}@linux-${VSCODE_ARCH}.vsix" \
+    && curl -fsSL -o /tmp/python-envs.vsix \
+      "https://open-vsx.org/api/ms-python/vscode-python-envs/${EXT_MS_PYTHON_ENVS}/file/ms-python.vscode-python-envs-${EXT_MS_PYTHON_ENVS}.vsix" \
+    && curl -fsSL -o /tmp/python.vsix \
+      "https://open-vsx.org/api/ms-python/python/${EXT_MS_PYTHON}/file/ms-python.python-${EXT_MS_PYTHON}.vsix" \
+    && curl -fsSL -o /tmp/markdown-aio.vsix \
+      "https://open-vsx.org/api/yzhang/markdown-all-in-one/${EXT_MARKDOWN_AIO}/file/yzhang.markdown-all-in-one-${EXT_MARKDOWN_AIO}.vsix" \
+    && curl -fsSL -o /tmp/git-graph.vsix \
+      "https://open-vsx.org/api/mhutchie/git-graph/${EXT_GIT_GRAPH}/file/mhutchie.git-graph-${EXT_GIT_GRAPH}.vsix" \
+    && curl -fsSL -o /tmp/gitlens.vsix \
+      "https://open-vsx.org/api/eamodio/gitlens/${EXT_GITLENS}/file/eamodio.gitlens-${EXT_GITLENS}.vsix" \
+    && curl -fsSL -o /tmp/rainbow-csv.vsix \
+      "https://open-vsx.org/api/mechatroner/rainbow-csv/${EXT_RAINBOW_CSV}/file/mechatroner.rainbow-csv-${EXT_RAINBOW_CSV}.vsix" \
+    && curl -fsSL -o /tmp/yaml.vsix \
+      "https://open-vsx.org/api/redhat/vscode-yaml/${EXT_YAML}/file/redhat.vscode-yaml-${EXT_YAML}.vsix" \
+    && curl -fsSL -o /tmp/github-theme.vsix \
+      "https://open-vsx.org/api/GitHub/github-vscode-theme/${EXT_GITHUB_THEME}/file/GitHub.github-vscode-theme-${EXT_GITHUB_THEME}.vsix" \
+    && code-server --install-extension /tmp/debugpy.vsix \
+    && code-server --install-extension /tmp/python-envs.vsix \
+    && code-server --install-extension /tmp/python.vsix \
+    && code-server --install-extension /tmp/markdown-aio.vsix \
+    && code-server --install-extension /tmp/git-graph.vsix \
+    && code-server --install-extension /tmp/gitlens.vsix \
+    && code-server --install-extension /tmp/rainbow-csv.vsix \
+    && code-server --install-extension /tmp/yaml.vsix \
+    && code-server --install-extension /tmp/github-theme.vsix \
+    && rm /tmp/*.vsix
+
+# Set default code-server vscode settings (GitHub theme, sensible defaults)
+RUN echo '{"workbench.colorTheme":"GitHub Dark Default","editor.fontSize":14,"editor.minimap.enabled":false,"telemetry.telemetryLevel":"off","extensions.autoUpdate":false,"security.workspace.trust.enabled":false}' \
+    > /home/appuser/.local/share/code-server/User/settings.json
+
+# Configure git identity for DAAF's internal version tracking.
+# Agents make local commits during research sessions to create an audit trail.
+# This identity is used for those automated commits inside the container only.
+RUN git config --global user.email "daaf@local" \
+    && git config --global user.name "DAAF Container"
+
 # Install Claude Code as appuser (pinned version)
-ARG CLAUDE_CODE_VERSION=2.1.87
+ARG CLAUDE_CODE_VERSION=2.1.112
 RUN curl -fsSL https://claude.ai/install.sh | bash -s ${CLAUDE_CODE_VERSION}
 ENV PATH="/home/appuser/.local/bin:${PATH}"
 
-# Copy and configure entrypoint script for git initialization
-COPY --chown=appuser:appuser scripts/entrypoint.sh /daaf/scripts/entrypoint.sh
-RUN chmod +x /daaf/scripts/entrypoint.sh
-ENTRYPOINT ["/daaf/scripts/entrypoint.sh"]
-
 # Default command
 CMD ["bash"]
diff --git a/README.md b/README.md
index 84f02c6..7cd2889 100644
--- a/README.md
+++ b/README.md
@@ -4,7 +4,7 @@
 
 ## Summary: What is DAAF?
 
-<img width="1258" height="433" alt="daaf_20_thumbnail3" src="https://github.com/user-attachments/assets/b9bfc613-170d-41e4-b35f-b871989dc428" />
+<img width="1258" height="433" alt="daaf_20_thumbnail4" src="https://github.com/user-attachments/assets/21b17b1d-a4d8-4558-a91d-a9ecb0d43f22" />
 
 <p align="center">
   <a href="https://github.com/DAAF-Contribution-Community/daaf/releases"><img src="https://img.shields.io/badge/version-v2.0.1-blue" alt="Version v2.0.1"></a>
@@ -33,9 +33,7 @@ Install and begin using it in as little as 10 minutes from a fresh install with
 Watch the 4 minute v2.0.0 Showcase video below, or read on for more information!
   <p align="center">                                                                                                  
     <a href="https://youtu.be/747r7VT4a78">
-      <img width="607" height="339" alt="image" src="https://github.com/user-attachments/assets/ba265c65-ba25-4a98-9789-d4a1d5af6815" alt="Watch the DAAF v2.0.0 Showcase />
-      <img src="https://img.youtube.com/vi/747r7VT4a78/maxresdefault.jpg" "        
-  width="720" />                                                                                                      
+      <img width="720" alt="Watch the DAAF v2.0.0 Showcase" src="https://img.youtube.com/vi/747r7VT4a78/maxresdefault.jpg" />                                                                                                      
     </a>                                                                                                              
   </p>    
 
@@ -54,74 +52,31 @@ Watch the 4 minute v2.0.0 Showcase video below, or read on for more information!
 
 If you're already comfortable with the Terminal and Claude Code, you can get started almost immediately using the Quick Start instructions below. Otherwise, I recommend starting with the full [Installation Guide](user_reference/01_installation_and_quickstart.md) for beginner-friendly details, prerequisites, and troubleshooting.
 
-**Requirements:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) (running) and an [Anthropic Max subscription](https://claude.com/pricing/max) ($100-200/mo) or [API key](https://console.anthropic.com/). 
+**Requirements:** [Docker Desktop](https://www.docker.com/products/docker-desktop/) (running) and an [Anthropic Max subscription](https://claude.com/pricing/max) ($100-200/mo), [API key](https://console.anthropic.com/), or [OpenRouter](https://openrouter.ai/) account (pay-per-token, no subscription). Open a terminal in your desired installation directory.
 
-<table>
-<tr>
-<td><strong>macOS / Linux (Terminal)</strong></td>
-<td><strong>Windows (PowerShell)</strong></td>
-</tr>
-<tr>
-<td>
+**macOS / Linux (Terminal):**
 
 ```bash
-# 1. Download the project files
-curl -L -o daaf.zip https://github.com/DAAF-Contribution-Community/daaf/archive/refs/heads/main.zip
+# Install DAAF (downloads Docker build files, builds image, clones repo into container)
+curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh | bash
 
-# 2. Extract the ZIP file
-unzip daaf.zip
-
-# 3. Enter the project directory
-cd daaf-main
-
-# 4. Copy files into a secure Docker volume
-docker run --rm -v "${PWD}:/source:ro" \
-  -v "daaf_daaf-data:/dest" \
-  busybox sh -c 'cp -a /source/. /dest/'
-
-# 5. Build and start the container
-docker compose up -d --build
-
-# 6. Enter the container
-docker compose exec daaf-docker bash
-
-# 7. Launch Claude Code
-claude
+# Enter the installation folder and launch Claude Code with a helper script
+cd daaf-docker
+bash run_daaf.sh
 ```
 
-</td>
-<td>
+**Windows (PowerShell):**
 
 ```powershell
-# 1. Download the project files
-Invoke-WebRequest -Uri "https://github.com/DAAF-Contribution-Community/daaf/archive/refs/heads/main.zip" -OutFile daaf.zip
-
-# 2. Extract the ZIP file
-Expand-Archive -Path daaf.zip -DestinationPath .
-
-# 3. Enter the project directory
-cd daaf-main
+# Install DAAF (downloads Docker build files, builds image, clones repo into container)
+irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1 | iex
 
-# 4. Copy files into a secure Docker volume
-docker run --rm -v "${PWD}:/source:ro" `
-  -v "daaf_daaf-data:/dest" `
-  busybox sh -c 'cp -a /source/. /dest/'
-
-# 5. Build and start the container
-docker compose up -d --build
-
-# 6. Enter the container
-docker compose exec daaf-docker bash
-
-# 7. Launch Claude Code
-claude
+# Enter the installation folder and launch Claude Code with a helper script
+cd daaf-docker
+.\run_daaf.ps1
 ```
 
-</td>
-</tr>
-</table>
-
-On first launch, Claude Code will prompt you to authenticate. Set your model to **Opus 4.6** via `/model`, and set **Auto-compact** to **False** and **Verbose output** to **True** via `/config`. You're ready to go; see [Understanding DAAF](user_reference/02_understanding_daaf.md) for some suggestions on how to get started with progressively more complex tasks with DAAF!
+On first launch, Claude Code will prompt you to authenticate. Set your model to **Opus 4.6** (or Opus 4.5) via `/model`, set the thinking level to **High** using the arrow keys while the model is selected, and set **Auto-compact** to **False** (to prevent conflicts with DAAF's built-in context window management) and **Verbose output** to **True** (to ensure that you can monitor how DAAF's thinking and working for accuracy) via `/config`. You're ready to go; see [Understanding DAAF](user_reference/02_understanding_daaf.md) for some suggestions on how to get started with progressively more complex tasks with DAAF!
 
 ---
 
@@ -212,7 +167,7 @@ polars &bull; pyfixest &bull; linearmodels &bull; statsmodels &bull; scikit-lear
 Need a package that isn't listed? You can add your own by editing the Dockerfile and rebuilding -- see [Customizing Your Python Environment](user_reference/04_extending_daaf.md#customizing-your-python-environment) for instructions.
 
 **Additional features:**
-Interactive dashboards (Plotly) &bull; Reactive analytic notebooks (marimo) &bull; R/tidyverse-Python code translation &bull; Stata-Python code translation &bull; Citation propagation & verification &bull; GUIDE-LLM AI use disclosure &bull; Git version control &bull; Session transcript archiving &bull; Docker-based safety sandboxing &bull; Destructive command prevention &bull; Secret/credential scanning &bull; File-first execution enforcement &bull; Science communication
+Interactive dashboards (Plotly) &bull; Reactive analytic notebooks (marimo) &bull; Browser-based code editor (code-server) &bull; R/tidyverse-Python code translation &bull; Stata-Python code translation &bull; Citation propagation & verification &bull; GUIDE-LLM AI use disclosure &bull; Git version control &bull; Session transcript archiving &bull; DAAF Log Explorer &bull; Docker-based safety sandboxing &bull; Destructive command prevention &bull; Secret/credential scanning &bull; File-first execution enforcement &bull; Science communication
 
 ---
 
@@ -258,7 +213,7 @@ See [**Contributing to DAAF**](CONTRIBUTING.md) for the full contribution guide
 - [**02. Understanding and Working with DAAF**](user_reference/02_understanding_daaf.md) — Learn to work with DAAF for the first time: what to expect, how to use it, and how to test its strengths and limitations
 - [**03. Best Practices**](user_reference/03_best_practices.md) — Tips for working with Claude Code, writing effective prompts, ensuring quality and rigor with DAAF, reviewing outputs, and managing context
 - [**04. Extending DAAF**](user_reference/04_extending_daaf.md) — How to add new data source skills, analytical tools and methodologies, creating your own additional specialized agents, and customizing the Python environment
-- [**05. Contributing to DAAF**](CONTRIBUTING.md) — Get involved in developing DAAF! How to file issues via GitHub, support expanding the capabilities of the framework, contribute to educational tutorials and how-to's, and more!
+- [**05. Contributing to DAAF**](CONTRIBUTING.md) — Get involved in developing DAAF! How to file issues, contribute new skills and data sources, improve documentation and protocols, test your changes, and more!
 - [**06. FAQ: Philosophy**](user_reference/06_faq_philosophy.md) — **(Recommended Next Step)** Grapples with the broader implications of this work, AI automation in general, model advancement pace, approaching the "exponential", environmental ethics, what this means for the next generation of researchers, and more
 - [**07. FAQ: Technical Support**](user_reference/07_faq_technical.md) — Covers frequently asked questions about Docker, issues with Claude Code, usage limits, authentication errors, and other common errors
 
@@ -314,21 +269,26 @@ Hello! My name is Brian Heseung Kim ([@brhkim](https://github.com/brhkim)). I ha
 
 ## Acknowledgments
 
-### Urban Institute Education Data Portal
-
-The current proof-of-concept iteration of this project would not be possible without the **[Urban Institute Education Data Portal](https://educationdata.urban.org/)** -- a remarkable public resource that harmonizes data from over a dozen federal education data sources into a single, well-documented API. We are deeply grateful to the Urban Institute for making high-quality education data freely accessible, providing excellent documentation and consistent data structures, harmonizing complex federal datasets, and supporting the research community with responsive maintenance and updates.
-
-If you use DAAF or the Education Data Portal in your work, please cite the Urban Institute appropriately. See the [Education Data Portal documentation](https://educationdata.urban.org/documentation/) for citation guidelines.
+### Open Source Software & Community Resources
 
-### GUIDE-LLM Reporting Checklist
+- **[Urban Institute Education Data Portal](https://educationdata.urban.org/)** -- The proof-of-concept iteration of this project would not be possible without this remarkable public resource that harmonizes data from over a dozen federal education data sources into a single, well-documented API. We are deeply grateful to the Urban Institute for making high-quality education data freely accessible. If you use DAAF or the Education Data Portal in your work, please cite the Urban Institute appropriately -- see the [Education Data Portal documentation](https://educationdata.urban.org/documentation/) for citation guidelines.
+- **[GUIDE-LLM](https://llm-checklist.com/)** -- DAAF integrates this consensus-based reporting checklist (developed by Feuerriegel, Barrie, Crockett, Globig, McLoughlin, Mirea, Spirling, Yang, and over 80 additional experts) to help researchers transparently disclose how AI was used in their work.
+- **[Get Shit Done](https://github.com/glittercowboy/get-shit-done)** ([@glittercowboy](https://github.com/glittercowboy)) -- Several core workflow patterns in DAAF, particularly around agent specialization, shared working memory, and task decomposition, were improved thanks to excellent practices in this project.
+- **[Docker](https://www.docker.com/)** -- Containerization platform providing DAAF's sandboxed execution environment
+- **[code-server](https://github.com/coder/code-server)** ([Coder](https://coder.com/)) -- Browser-based VS Code editor, itself built on Microsoft's [VS Code](https://github.com/microsoft/vscode) and the [Open VSX](https://open-vsx.org/) extension registry
+- **[marimo](https://marimo.io/)** -- Reactive Python notebooks used for DAAF's reproducible research artifacts
+- **[Polars](https://pola.rs/)** -- High-performance DataFrame library and DAAF's default data engine
+- **[uv](https://github.com/astral-sh/uv)** ([Astral](https://astral.sh/)) -- Fast Python package manager powering DAAF's build
+- **[Git](https://git-scm.com/)** and **[pre-commit](https://pre-commit.com/)** -- Version control and commit-time safety checks
+- DAAF also relies on a broad ecosystem of specific Python libraries for statistical computing, visualization, and geospatial analysis -- see the [Dockerfile](Dockerfile) for the complete list with pinned versions.
 
-DAAF integrates the **[GUIDE-LLM](https://llm-checklist.com/)** reporting checklist into all output workflows to help researchers transparently and rigorously disclose how AI was used in their work. GUIDE-LLM is a consensus-based reporting standard developed by over 80 experts for studies using large language models in the behavioral and social sciences.
+### Methodological Foundations
 
-> Feuerriegel, S., Barrie, C., Crockett, M. J., Globig, L. K., McLoughlin, K. L., Mirea, D.-M., Spirling, A., Yang, D., ..., Rathje, S., & Ribeiro, M. H. (2026). A consensus-based reporting checklist for large language models in behavioral and social science. Available at: https://llm-checklist.com/
+DAAF's Skills encode curated methodological guidance drawn from the work of many researchers. The exact references are embedded in the Skill files themselves (see `.claude/skills/`), but we gratefully acknowledge the scholars whose textbooks, papers, and open educational resources most directly shaped the framework's embedded expertise:
 
-### Inspiration
+> **Causal inference and econometrics:** Joshua Angrist & Jorn-Steffen Pischke, Scott Cunningham, Nick Huntington-Klein, Jeffrey Wooldridge, Guido Imbens, Judea Pearl, Paul Rosenbaum & Donald Rubin, Alberto Abadie, Matias Cattaneo, Edward Leamer, Charles Manski, Anton Korinek (causal inference, statistical modeling) &bull; **Modern difference-in-differences:** Brantly Callaway & Pedro Sant'Anna, Andrew Goodman-Bacon, Liyang Sun & Sarah Abraham, Clement de Chaisemartin & Xavier D'Haultfoeuille, Jonathan Roth, John Gardner, Kirill Borusyak, Ariel Dube (causal inference, pyfixest) &bull; **Statistical inference:** A. Colin Cameron & Douglas Miller, James MacKinnon, Morten Nielsen & Matthew Webb, Yosef Benjamini & Yoav Hochberg, Joseph Romano & Michael Wolf (statistical modeling, pyfixest, linearmodels) &bull; **Sensitivity and robustness:** Emily Oster, Carlos Cinelli & Chad Hazlett, Joseph Altonji (causal inference, statistical modeling) &bull; **Statistical learning and machine learning:** Trevor Hastie, Robert Tibshirani & Jerome Friedman, Gareth James & Daniela Witten, Leo Breiman, Susan Athey & Stefan Wager, Sendhil Mullainathan, Victor Chernozhukov, Cynthia Rudin, Christoph Molnar, Scott Lundberg, Galit Shmueli (supervised ML, exploratory/unsupervised) &bull; **Fairness:** Jon Kleinberg, Alexandra Chouldechova, Ziad Obermeyer (supervised ML) &bull; **Clustering and unsupervised methods:** Leonard Kaufman & Peter Rousseeuw, Christian Hennig, Brian Everitt, Chris Fraley & Adrian Raftery, Ian Jolliffe, Laurens van der Maaten, Leland McInnes (exploratory/unsupervised) &bull; **Decomposition methods:** Ronald Oaxaca & Alan Blinder, Jonah Gelbach, Nicole Fortin, Thomas Lemieux & Sergio Firpo, Frank Cowell (descriptive analysis) &bull; **Survey methodology:** Thomas Lumley, Steven Heeringa, Brady West & Patricia Berglund, Sharon Lohr, Leslie Kish, Kirk Wolter (survey analysis, svy) &bull; **Geospatial analysis:** Sergio Rey, Dani Arribas-Bel & Levi John Wolf, Luc Anselin, Waldo Tobler, Timothy Conley, A. Stewart Fotheringham (geospatial analysis, geopandas) &bull; **Panel data and IV:** Badi Baltagi, William Greene, Kevin Sheppard, Douglas Staiger & James Stock (linearmodels, pyfixest) &bull; **Time series:** James Hamilton, Rob Hyndman, Helmut Lutkepohl (statsmodels) &bull; **Visualization and science communication:** Edward Tufte, Cole Nussbaumer Knaflic, Jonathan Schwabish, Claus Wilke, Alberto Cairo, Barbara Minto, Brent Dykes, Catherine D'Ignazio & Lauren F. Klein (visualization design, science communication) &bull; **Software:** Alexander Fischer & S. Schar (pyfixest), Skipper Seabold & Josef Perktold (statsmodels), Mamadou S. Diallo (svy), Fabian Pedregosa et al. (scikit-learn), Sergio Rey et al. (PySAL), Laurent Berge, Kyle Butts & Grant McDermott (fixest), Kelsey Jordahl et al. (geopandas), Geoff Boeing (OSMnx), Guolin Ke et al. (LightGBM)
 
-Several core workflow patterns -- particularly around agent specialization, shared working memory, and task decomposition -- were improved thanks to excellent practices in **[Get Shit Done](https://github.com/glittercowboy/get-shit-done)** by [@glittercowboy](https://github.com/glittercowboy). Early thinking on DAAF was also rapidly accelerated by Dr. Anton Korinek's working paper, [AI Agents for Economic Research](https://www.genaiforecon.org/JEL-2025-Aug-AIAgents.pdf).
+These researchers' contributions -- many freely available as open-access resources -- represent decades of accumulated methodological wisdom that DAAF aims to make more accessible to applied researchers.
 
 ---
 
diff --git a/agent_reference/DATA_SOURCE_SKILL_TEMPLATE.md b/agent_reference/DATA_SOURCE_SKILL_TEMPLATE.md
index 4e65909..ca30049 100644
--- a/agent_reference/DATA_SOURCE_SKILL_TEMPLATE.md
+++ b/agent_reference/DATA_SOURCE_SKILL_TEMPLATE.md
@@ -394,8 +394,9 @@ Use this skeleton instead of (or in addition to) the mirror-based skeleton above
 ### Prerequisites
 
 > **API Key Required:** This data source requires authentication.
-> Set the `[ENV_VAR_NAME]` environment variable before launching Claude Code.
-> See the [Installation Guide — Set up data source API keys](../user_reference/01_installation_and_quickstart.md#step-8-optional-set-up-data-source-api-keys) for setup instructions.
+> Add `[ENV_VAR_NAME]=your_key_here` to the `environment_settings.txt` file in your `daaf-docker/` folder
+> (copy `environment_settings_example.txt` to `environment_settings.txt` if you haven't already), then recreate the container: `docker compose down` followed by `run_daaf`.
+> See the [Installation Guide — Set up data source API keys](../user_reference/01_installation_and_quickstart.md#set-up-data-source-api-keys) for setup instructions.
 
 | Requirement | Details |
 |-------------|---------|
diff --git a/agent_reference/PLAN_TEMPLATE.md b/agent_reference/PLAN_TEMPLATE.md
index b0997e8..e82f4de 100644
--- a/agent_reference/PLAN_TEMPLATE.md
+++ b/agent_reference/PLAN_TEMPLATE.md
@@ -644,6 +644,7 @@ Define the expected data contracts between stages. The data-planner populates th
 | Raw data | `research/[project]/data/raw/` | `.parquet` |
 | Processed data | `research/[project]/data/processed/` | `.parquet` |
 | Figures | `research/[project]/output/figures/` | `.png` |
+| Discovery preliminary notes | `research/[project]/output/preliminary_notes/` | `.md` |
 
 ---
 
@@ -803,6 +804,7 @@ and QA reviewers understand what was intentionally accepted.*
 | Raw Data | `research/YYYY-MM-DD_[Title]/data/raw/YYYY-MM-DD_*.parquet` | Original data downloads |
 | Processed Data | `research/YYYY-MM-DD_[Title]/data/processed/YYYY-MM-DD_*.parquet` | Cleaned data |
 | Figures | `research/YYYY-MM-DD_[Title]/output/figures/YYYY-MM-DD_*.png` | Visualizations |
+| Discovery Preliminary Notes | `research/YYYY-MM-DD_[Title]/output/preliminary_notes/{date}_stage{N}_{desc}.md` | Lossless agent findings from discovery phase (Stages 2, 3, 3.5) |
 | Fetch Scripts | `research/YYYY-MM-DD_[Title]/scripts/stage5_fetch/*.py` | Data retrieval code |
 | Clean Scripts | `research/YYYY-MM-DD_[Title]/scripts/stage6_clean/*.py` | Context application code |
 | Transform Scripts | `research/YYYY-MM-DD_[Title]/scripts/stage7_transform/*.py` | Transformation code |
diff --git a/agent_reference/REPORT_TEMPLATE.md b/agent_reference/REPORT_TEMPLATE.md
index cbfe5f6..5aff8f9 100644
--- a/agent_reference/REPORT_TEMPLATE.md
+++ b/agent_reference/REPORT_TEMPLATE.md
@@ -15,6 +15,7 @@
 | Data & Methods: Key Variables | Plan.md § Key Variables | — |
 | Data & Methods: Methodology | Plan.md § Methodology Specification | Plan.md § Key Decisions |
 | Data & Methods: Data Cleaning | Stage 6 execution logs | STATE.md checkpoints |
+| Data Sources, Methodology | `output/preliminary_notes/` | Discovery-phase agent findings (source caveats, coded values, limitations) |
 | Quality Assurance | STATE.md QA Findings Summary | Stage 10 QA execution logs |
 | Key Findings | Stage 7-8 outputs + figures | Plan.md § Research Outcomes + Plan.md § Hypotheses (if any) |
 | Summary Statistics | Analysis dataset metadata + Stage 7 EDA logs | Notebook data cells |
diff --git a/agent_reference/REPRODUCTION_REPORT_TEMPLATE.md b/agent_reference/REPRODUCTION_REPORT_TEMPLATE.md
index ffd6bbf..8e15ba1 100644
--- a/agent_reference/REPRODUCTION_REPORT_TEMPLATE.md
+++ b/agent_reference/REPRODUCTION_REPORT_TEMPLATE.md
@@ -77,8 +77,10 @@ Copy this template to `Reproduction_Report.md` in the reproduction project folde
 | Original Report | `original_files/[report_name]` | [Yes/No] |
 | Original Notebook | `original_files/[notebook_name]` | [Yes/No] |
 | Original Figures | `original_files/output/figures/` | [Yes/No] |
+| Original Preliminary Notes | `original_files/output/preliminary_notes/` | [Yes/No/N/A] |
 | Decompiled Scripts | `original_files/scripts/` | [Yes/No] |
 | Decompilation Manifest | `original_files/scripts/MANIFEST.md` | [Yes/No] |
+| RV-3 Verification Findings | `output/preliminary_notes/[date]_rv3_report-verification.md` | [Yes/No] |
 | Reproduction Session Logs | `logs/` | [Yes/No] |
 
 ### Script Inventory
@@ -250,9 +252,11 @@ Copy this template to `Reproduction_Report.md` in the reproduction project folde
 | `original_files/[report]` | Original Report (copied) | RV-1 |
 | `original_files/[notebook]` | Original Notebook (copied) | RV-1 |
 | `original_files/output/figures/` | Original figures (copied) | RV-1 |
+| `original_files/output/preliminary_notes/` | Original discovery findings (copied, if present) | RV-1 |
 | `original_files/scripts/[...]` | Decompiled scripts (from notebook) | RV-1 |
 | `scripts/repro/[...]` | Re-executed scripts (with new logs) | RV-2 |
 | `output/figures/[...]` | Reproduced figures (generated) | RV-2 |
+| `output/preliminary_notes/[date]_rv3_report-verification.md` | Lossless data-verifier return (persisted) | RV-3 |
 | `Reproduction_Report.md` | This document | RV-1 |
 
 ---
diff --git a/agent_reference/STATE_TEMPLATE.md b/agent_reference/STATE_TEMPLATE.md
index d9bf62a..2cd186c 100644
--- a/agent_reference/STATE_TEMPLATE.md
+++ b/agent_reference/STATE_TEMPLATE.md
@@ -258,6 +258,29 @@ Copy this template to `STATE.md` in the project folder when starting a Full Pipe
 
 ---
 
+## Discovery Preliminary Notes
+
+> Orchestrator writes lossless agent findings to disk as preliminary notes files
+> immediately upon receiving each discovery-phase agent's return. These files
+> persist the full agent output (zero compression) and are referenced by
+> downstream agents (data-planner, plan-checker, data-verifier) for full-fidelity
+> access to discovery findings. Gate conditions prevent downstream stages from
+> proceeding until the relevant files exist on disk.
+
+| Stage | Agent | File Path | Status |
+|-------|-------|-----------|--------|
+| 2 | search-agent | `output/preliminary_notes/{date}_stage2_data-exploration.md` | [PENDING/WRITTEN] |
+| 3 | source-researcher | `output/preliminary_notes/{date}_stage3_{source}_source-research.md` | [PENDING/WRITTEN] |
+| 3.5 | research-synthesizer | `output/preliminary_notes/{date}_stage3.5_research-synthesis.md` | [PENDING/WRITTEN] |
+
+**Status Values:**
+- **PENDING** — Agent not yet dispatched or return not yet persisted
+- **WRITTEN** — File exists on disk with full lossless agent return
+
+**Note:** Add one row per source-researcher dispatch (one per data source). All rows must show WRITTEN before Stage 4 can proceed.
+
+---
+
 ## Citations Accumulated
 
 > Orchestrator populates this section after each Stage 6, 7, and 8 script completion,
diff --git a/agent_reference/STATE_TEMPLATE_ONBOARDING.md b/agent_reference/STATE_TEMPLATE_ONBOARDING.md
index d6b0246..f2eb637 100644
--- a/agent_reference/STATE_TEMPLATE_ONBOARDING.md
+++ b/agent_reference/STATE_TEMPLATE_ONBOARDING.md
@@ -187,6 +187,30 @@ States
 **Multi-file expansion (HIERARCHICAL only):** For HIERARCHICAL file structures, expand the table with per-file rows using the suffix convention. For example, with 2 files (schools + districts):
 - Row `01a` for `01a_load-and-format.py` (schools), row `01b` for `01b_load-and-format.py` (districts)
 - Similarly for scripts 02, 03, 04, 07, 09, 10
+
+---
+
+## Profiling Preliminary Notes
+
+> Orchestrator writes lossless agent findings to disk as preliminary notes files
+> immediately upon receiving each profiling agent's return. These files persist the
+> full agent output (zero compression) and are referenced by subsequent profiling
+> parts and the DI-7 skill authoring agent for full-fidelity access to prior
+> findings. Gate conditions prevent the next part from proceeding until the
+> current part's notes file exists on disk.
+
+| Part | Agent | File Path | Status |
+|------|-------|-----------|--------|
+| A | data-ingest | `output/preliminary_notes/{date}_partA_structural-discovery.md` | [PENDING/WRITTEN] |
+| B | data-ingest | `output/preliminary_notes/{date}_partB_statistical-deep-dive.md` | [PENDING/WRITTEN] |
+| C | data-ingest | `output/preliminary_notes/{date}_partC_relational-analysis.md` | [PENDING/WRITTEN] |
+| D | data-ingest | `output/preliminary_notes/{date}_partD_interpretation-reconciliation.md` | [PENDING/WRITTEN] |
+
+**Status Values:**
+- **PENDING** — Agent not yet dispatched or return not yet persisted
+- **WRITTEN** — File exists on disk with full lossless agent return
+
+**Note:** All four rows must show WRITTEN before DI-7 skill authoring can proceed.
 - Script `07b` appears once (cross-file, not per-file)
 - Conditional scripts (05, 06, 08) appear per-file only if applicable to that specific file
 - Script 11 appears once (cross-file documentation reconciliation)
diff --git a/agent_reference/VALIDATION_CHECKPOINTS.md b/agent_reference/VALIDATION_CHECKPOINTS.md
index 1fc47cd..ec9d8c9 100644
--- a/agent_reference/VALIDATION_CHECKPOINTS.md
+++ b/agent_reference/VALIDATION_CHECKPOINTS.md
@@ -999,7 +999,8 @@ research/YYYY-MM-DD_[Title]/
 │   ├── raw/
 │   └── processed/
 └── output/
-    └── figures/
+    ├── figures/
+    └── preliminary_notes/
 ```
 
 **Rationale:**
diff --git a/agent_reference/WORKFLOW_PHASE1_DISCOVERY.md b/agent_reference/WORKFLOW_PHASE1_DISCOVERY.md
index a54f56c..ec7c55b 100644
--- a/agent_reference/WORKFLOW_PHASE1_DISCOVERY.md
+++ b/agent_reference/WORKFLOW_PHASE1_DISCOVERY.md
@@ -190,6 +190,15 @@ After completing the skill's Required Actions, return findings using the format
 - [ ] Colleges level searched (if relevant)
 - [ ] Multiple sources considered
 ```
+### Preliminary Notes Persistence: Stage 2
+
+After the explorer agent returns for full pipeline mode only, the orchestrator persists the full return to disk:
+
+| Agent Return | Write To |
+|-------------|----------|
+| search-agent (Stage 2) | `{project_dir}/output/preliminary_notes/{date}_stage2_data-exploration.md` |
+
+Stage 2 preliminary notes must exist on disk before dispatching Stage 3 (source-researcher). The orchestrator confirms the file was written as specified.
 
 ### Gate Criteria (G2)
 
@@ -197,6 +206,7 @@ After completing the skill's Required Actions, return findings using the format
 - [ ] Key variables identified
 - [ ] Variables for deep-dive flagged
 - [ ] Year coverage verified
+- [ ] Full search-agent return written to disk (full pipeline mode only)
 - [ ] **If no data found:** STOP, escalate to user
 
 ---
@@ -281,53 +291,31 @@ Variables to investigate: {variables}
 - Document population coverage (who is included/excluded)
 
 **OUTPUT FORMAT:**
-Return findings in this structure:
-
-### Source: {source_name}
-
-### 1. Source-Specific Caveats
-| Caveat | Impact on Analysis | Mitigation Strategy |
-|--------|-------------------|---------------------|
-
-### 2. Coded Value Mappings
-| Variable | Code | Meaning | Recommended Action |
-|----------|------|---------|-------------------|
-| [var] | -1 | Missing/not reported | Filter before calculations |
-| [var] | -2 | Not applicable | Exclude from analysis |
-| [var] | -3 | Suppressed | Document; cannot recover |
-
-### 3. Suppression Patterns
-| Variable | Typical Rate | Threshold | Impact on Analysis |
-|----------|--------------|-----------|-------------------|
-
-### 4. Cross-State Comparability
-| Analysis Type | Valid Across States? | Notes |
-|---------------|---------------------|-------|
-
-### 5. Critical Warnings
-1. **[Warning Name]:** [Description]
-   - **Mitigation:** [How to handle]
-
-### 6. Limitations Encountered
-| Limitation | Impact | Resolution |
-|------------|--------|------------|
-
-### 7. Confidence Assessment
-| Finding | Confidence | Rationale |
-|---------|------------|-----------|
-| [key finding] | HIGH/MEDIUM/LOW | [why this confidence level] |
-
-**Overall Confidence:** [HIGH | MEDIUM | LOW]
-**LOW Confidence Items Requiring Resolution:** [list or "None"]
-
-After completing the skill's Required Actions, return findings using the format above.""",
+Return findings using the Source Researcher Output Format
+(see your agent protocol, § Output Format).
+
+**Emphasis for this invocation:**
+- Coded value mappings for flagged variables
+- Suppression patterns and thresholds
+- Cross-state comparability issues
+- COVID-19 impact notes for 2020-2021 data""",
     subagent_type: "source-researcher"
 })
 ```
 
 ### Output Format
 
-**Output Format:** See `.claude/agents/source-researcher.md` > "Output Format" section for the authoritative output structure. The source-researcher agent returns a structured report with five deliverables (SOURCE_SUMMARY, VARIABLES, CAVEATS, PATTERNS, PITFALLS) plus confidence assessment and learning signal.
+**Output Format:** The source-researcher agent follows its own Output Format (defined in `.claude/agents/source-researcher.md`). The orchestrator writes the full return to `output/preliminary_notes/{date}_stage3_{source-name}_source-research.md` before extracting a summary for its own working memory.
+
+### Preliminary Notes Persistence: Stage 3
+
+After each deep-dive agent returns for full pipeline mode only, the orchestrator persists the full return to disk:
+
+| Agent Return | Write To |
+|-------------|----------|
+| source-researcher (Stage 3, per source) | `{project_dir}/output/preliminary_notes/{date}_stage3_{source-name}_source-research.md` |
+
+**Gate condition:** ALL Stage 3 preliminary notes must exist on disk before dispatching Stage 3.5 (research-synthesizer). The orchestrator confirms the file was written as specified.
 
 ### Gate Criteria (G3)
 
@@ -337,6 +325,7 @@ After completing the skill's Required Actions, return findings using the format
 - [ ] Cross-state comparability assessed
 - [ ] Critical warnings have mitigations
 - [ ] All LOW confidence findings resolved
+- [ ] All source-researcher returns written to disk (full pipeline mode only)
 
 ---
 
@@ -390,10 +379,16 @@ Agent({
 All relative paths in referenced files resolve from BASE_DIR.
 
 **STAGE 2 FINDINGS:**
-[Insert Stage 2 output]
+Read the full preliminary notes at: {project_dir}/output/preliminary_notes/{date}_stage2_data-exploration.md
 
 **STAGE 3 FINDINGS (per source):**
-[Insert Stage 3 outputs for each source]
+Read the full preliminary notes at:
+- {project_dir}/output/preliminary_notes/{date}_stage3_{source1}_source-research.md
+- {project_dir}/output/preliminary_notes/{date}_stage3_{source2}_source-research.md
+[...one path per source-researcher dispatch]
+
+**ORCHESTRATOR SUMMARY (for quick orientation — read full preliminary notes above for detail):**
+[Brief 3-5 bullet summary of key findings across sources]
 
 **TASK:**
 Consolidate these parallel findings into a unified context for Plan creation.
@@ -409,6 +404,16 @@ Consolidate these parallel findings into a unified context for Plan creation.
 })
 ```
 
+#### Preliminary Notes Persistence: Stage 3.5
+
+After the research-synthesizer returns, the orchestrator persists the full return to disk:
+
+| Agent Return | Write To |
+|-------------|----------|
+| research-synthesizer (Stage 3.5) | `{project_dir}/output/preliminary_notes/{date}_stage3.5_research-synthesis.md` |
+
+**Gate condition:** Stage 3.5 preliminary notes must exist on disk before presenting PSU1 to the user and before dispatching Stage 4 (data-planner). The orchestrator confirms the file was written as specified.
+
 > **Full Pipeline Only:** Gate G3.5 applies only to Full Pipeline mode. In standalone Data Discovery mode, the orchestrator manages synthesis and presentation directly.
 
 ### Gate Criteria (G3.5)
@@ -416,6 +421,7 @@ Consolidate these parallel findings into a unified context for Plan creation.
 - [ ] All source findings integrated
 - [ ] Conflicts identified and resolved
 - [ ] Unified context ready for data-planner
+- [ ] Full research-synthesizer return written to disk (full pipeline mode only)
 - [ ] **PSU1 presented to user**
 - [ ] **User confirmed PSU1**
 
diff --git a/agent_reference/WORKFLOW_PHASE2_PLANNING.md b/agent_reference/WORKFLOW_PHASE2_PLANNING.md
index c390b32..b60fcc0 100644
--- a/agent_reference/WORKFLOW_PHASE2_PLANNING.md
+++ b/agent_reference/WORKFLOW_PHASE2_PLANNING.md
@@ -25,7 +25,8 @@ Stages 4, 4.5. Cross-phase orchestration guidance (invocation templates, QA prot
    │   └── processed/
    └── output/
        ├── analysis/
-       └── figures/
+       ├── figures/
+       └── preliminary_notes/
    ```
 
 2. **Synthesize Phase 1 Findings**
@@ -122,14 +123,19 @@ All relative paths in referenced files resolve from BASE_DIR.
 **RESEARCH QUESTION (orchestrator formulation):**
 {research_question}
 
-**STAGE 2 FINDINGS (Data Exploration):**
-{stage_2_output_summary}
+**DISCOVERY PRELIMINARY NOTES:**
+Read these files for full-fidelity discovery findings:
+- Stage 2: {project_dir}/output/preliminary_notes/{date}_stage2_data-exploration.md
+- Stage 3 (per source):
+  - {project_dir}/output/preliminary_notes/{date}_stage3_{source1}_source-research.md
+  - {project_dir}/output/preliminary_notes/{date}_stage3_{source2}_source-research.md
+  [...one path per source]
+- Stage 3.5: {project_dir}/output/preliminary_notes/{date}_stage3.5_research-synthesis.md
 
-**STAGE 3 FINDINGS (Source Deep-Dive):**
-{stage_3_output_summary}
-
-**STAGE 3.5 FINDINGS (research synthesis):**
-{stage_3_5_synthesis}
+**ORCHESTRATOR CONTEXT (orientation summary):**
+[5-8 sentence summary of the discovery phase — key sources, main constraints,
+recommended approach. This is for quick orientation; consult the full preliminary
+notes above for complete detail.]
 
 **PROJECT FOLDER:**
 research/{date}_{title}/
@@ -154,9 +160,8 @@ Do NOT paraphrase or summarize — copy the exact text.
 **Orchestrator Checklist Before Invoking data-planner:**
 - [ ] Original user request text available (verbatim, not paraphrased)
 - [ ] Clarifications documented (numbered list)
-- [ ] Stage 2 findings summarized
-- [ ] Stage 3 findings summarized (per source)
-- [ ] Stage 3.5 synthesis included
+- [ ] Preliminary notes file paths confirmed on disk (Stage 2, Stage 3 per source, Stage 3.5)
+- [ ] Orientation summary drafted (5-8 sentences covering key sources, constraints, approach)
 - [ ] Project folder path determined
 
 ### Continuation Handling (Complex Plans)
@@ -218,7 +223,7 @@ Agent({
 - [ ] **STATE.md created** at `research/[folder]/STATE.md` (MANDATORY — Gate G4) — includes Runtime Risks, QA Findings Summary, and Final Review Log skeleton sections
 - [ ] **LEARNINGS.md skeleton created** at `research/[folder]/LEARNINGS.md` (MANDATORY — Gate G4)
 - [ ] **Plan Completeness Gate passed** (all sections verified in both Plan.md and Plan_Tasks.md)
-- [ ] Project folder structure created (`data/raw/`, `data/processed/`, `output/analysis/`, `output/figures/`)
+- [ ] Project folder structure created (`data/raw/`, `data/processed/`, `output/analysis/`, `output/figures/`, `output/preliminary_notes/`)
 - [ ] User notified (PSU2 presented after Stage 4.5 completes)
 
 **Gate G4 Enforcement:** Plan-checker (Stage 4.5) CANNOT be invoked without Plan.md, Plan_Tasks.md, STATE.md, and LEARNINGS.md all existing. (Stage 5 additionally requires G4.5 — see below.)
@@ -288,14 +293,25 @@ All relative paths in referenced files resolve from BASE_DIR.
 **CLARIFICATIONS:**
 {inline any user clarifications, or "None"}
 
+**DISCOVERY PRELIMINARY NOTES (for verification against Plan):**
+Read these files to verify the Plan accurately represents the data landscape:
+- {project_dir}/output/preliminary_notes/{date}_stage2_data-exploration.md
+- {project_dir}/output/preliminary_notes/{date}_stage3_{source1}_source-research.md
+- {project_dir}/output/preliminary_notes/{date}_stage3_{source2}_source-research.md
+- {project_dir}/output/preliminary_notes/{date}_stage3.5_research-synthesis.md
+
+Use these to verify:
+- All caveats from source research are reflected in the Plan's Risk Register
+- Coded value handling matches source-researcher recommendations
+- Suppression thresholds are documented as constraints
+- The Plan's methodology aligns with the synthesis's Recommended Approach
+
 **TASK:**
 Validate BOTH Plan.md and Plan_Tasks.md across all 6 dimensions (Completeness, Consistency, Feasibility, Testability, Clarity, Scope). Return structured report with per-dimension confidence and issues in YAML format.
 
 **OUTPUT FORMAT:**
-1. Dimension Scores (PASS/WARN/FAIL for each)
-2. Issues Found (with severity and location)
-3. Recommended Fixes (if ISSUES_FOUND)
-4. Overall Status: PASSED / PASSED_WITH_WARNINGS / ISSUES_FOUND
+Return findings using the Plan Checker Output Format
+(see your agent protocol, § Output Format).
 """,
     subagent_type: "plan-checker"
 })
diff --git a/agent_reference/WORKFLOW_PHASE3_ACQUISITION.md b/agent_reference/WORKFLOW_PHASE3_ACQUISITION.md
index 532e33b..bbc3657 100644
--- a/agent_reference/WORKFLOW_PHASE3_ACQUISITION.md
+++ b/agent_reference/WORKFLOW_PHASE3_ACQUISITION.md
@@ -106,40 +106,14 @@ Use the mirror-based fetch pattern from the education-data-query skill:
 - Verify all requested years are present
 - Verify all requested columns are present
 
-**OUTPUT FORMAT (1000-word hard cap):**
-Return findings in this structure:
-
-### Fetch Summary
-- Mirror used: [name from mirrors.yaml]
-- Download URL: [full URL used]
-- Records retrieved: [count]
-- Columns retrieved: [list]
-- Years present: [list]
-- Mirror fallback: [None | fell through from {mirror_name} due to {reason}]
-
-### Initial Validation (CP1)
-- Shape: [rows] x [cols]
-- Expected rows: [from Plan.md]
-- Row count ratio: [actual/expected]
-- Missing values by column:
-  | Column | Null Count | Null % |
-  |--------|------------|--------|
-- Critical columns present: [Yes/No]
-- **CP1 Status:** [PASSED | FAILED | WARNING]
-- **If FAILED:** [Stop reason]
-
-### File Locations
-- Parquet: data/raw/{filename}.parquet
-
-### Confidence Assessment
-| Check | Confidence | Rationale |
-|-------|------------|-----------|
-| Data completeness | HIGH/MEDIUM/LOW | [why this confidence level] |
-
-**Overall Confidence:** [HIGH | MEDIUM | LOW]
-**LOW Confidence Items Requiring Resolution:** [list or "None"]
-
-After completing the skill's Required Actions, return findings using the format above.""",
+**OUTPUT FORMAT:**
+Return findings using the Research Executor Output Format
+(see your agent protocol, § Output Format).
+
+**Emphasis for this invocation:**
+- File locations (parquet paths in `data/raw/`), mirror used, and any fallback events
+- Row counts, column lists, year coverage, and CP1 validation status
+- Initial data quality observations (missingness, coded values present)""",
     subagent_type: "research-executor"
 })
 ```
@@ -305,49 +279,14 @@ During execution, ACTIVELY MONITOR for watch-for symptoms. Escalate if detected.
 - Generate complete citation text with access date
 - Document all cleaning decisions and row impacts
 
-**OUTPUT FORMAT (1000-word hard cap):**
-Return findings in this structure:
-
-### Cleaning Applied
-| Code Filtered | Variable(s) | Rows Removed | % of Total |
-|---------------|-------------|--------------|------------|
-| -1 (Missing) | | | |
-| -2 (N/A) | | | |
-| -3 (Suppressed) | | | |
-| **Total** | | | |
-
-*(Coded values shown are education domain defaults. Substitute values from Plan Domain Configuration.)*
-
-### Data Quality Report (CP2)
-- Original rows: [count]
-- Clean rows: [count]
-- Total loss: [count] ([%])
-- Suppression rate (key variable): [%]
-- **CP2 Status:** [PASSED | FAILED]
-- **If FAILED:** [Stop reason]
-
-### Validity Check
-- Analysis type: {analysis_description}
-- Cross-state comparison: [Yes/No]
-- **Valid:** [Yes | No | Conditional]
-- **Warnings:** [list any concerns]
-
-### Citation
-> {full_citation_text}
-
-### File Locations
-- Parquet: data/processed/{filename}.parquet
-
-### Confidence Assessment
-| Check | Confidence | Rationale |
-|-------|------------|-----------|
-| Data quality | HIGH/MEDIUM/LOW | [why this confidence level] |
-| Analysis validity | HIGH/MEDIUM/LOW | [why this confidence level] |
-
-**Overall Confidence:** [HIGH | MEDIUM | LOW]
-**LOW Confidence Items Requiring Resolution:** [list or "None"]
+**OUTPUT FORMAT:**
+Return findings using the Research Executor Output Format
+(see your agent protocol, § Output Format).
 
-After completing the skill's Required Actions, return findings using the format above.""",
+**Emphasis for this invocation:**
+- Cleaning operations applied (coded value filters, row removal counts, suppression rates)
+- Data quality metrics (CP2 status, original vs. clean row counts, loss percentage)
+- Citation data (full citation text with access date) and file locations""",
     subagent_type: "research-executor"
 })
 ```
diff --git a/agent_reference/WORKFLOW_PHASE4_ANALYSIS.md b/agent_reference/WORKFLOW_PHASE4_ANALYSIS.md
index 8d71530..5ab7ab2 100644
--- a/agent_reference/WORKFLOW_PHASE4_ANALYSIS.md
+++ b/agent_reference/WORKFLOW_PHASE4_ANALYSIS.md
@@ -219,19 +219,13 @@ If user has R/Stata background, also include: "User has [R/Stata] background. Lo
 5. Document findings
 
 **OUTPUT FORMAT:**
-Return EDA summary ONLY:
-- Shape: [rows x cols]
-- Key distributions: [summary]
-- Data quality issues: [list]
-- Ready for transformations: [Yes/No]
+Return findings using the Research Executor Output Format
+(see your agent protocol, § Output Format).
 
-**Confidence Assessment:**
-| Aspect | Confidence | Rationale |
-|--------|------------|-----------|
-| Data quality | HIGH/MEDIUM/LOW | [why] |
-
-**Overall Confidence:** [HIGH | MEDIUM | LOW]
-**Issues Requiring Resolution:** [list or "None"]
+**Emphasis for this invocation:**
+- Data shape, type summary, and memory usage
+- Key distributions and data quality issues identified
+- Readiness assessment for transformations (Yes/No with justification)
 
 Do NOT proceed to transformations. Return findings for orchestrator review.""",
     subagent_type: "research-executor"
@@ -302,19 +296,14 @@ If user has R/Stata background, also include: "User has [R/Stata] background. Lo
 - Use script-based validation (see `{BASE_DIR}/agent_reference/SCRIPT_EXECUTION_REFERENCE.md`)
 - Report clear PASS/FAIL with metrics
 
-**OUTPUT FORMAT (1000-word hard cap):**
-Return validation report:
-
-### Transformation #{n}: {description}
-**Pre-state:** {shape}, sample: {sample_ids}
-**Post-state:** {shape}, sample: {sample_ids}
-**Row change:** {percent}
-**Invariants:** {list with pass/fail}
-**Status:** PASSED | FAILED
+**OUTPUT FORMAT:**
+Return findings using the Research Executor Output Format
+(see your agent protocol, § Output Format).
 
-If FAILED:
-- Issue description: [what went wrong]
-- Proposed fix: [how to correct]
+**Emphasis for this invocation:**
+- Pre/post row counts and shape changes for this transformation
+- Invariant validation results (pass/fail per invariant)
+- Transformation status (PASSED/FAILED) with issue details if failed
 
 Do NOT proceed to transformation #{n+1}. Return to orchestrator for approval.""",
     subagent_type: "research-executor"
@@ -568,34 +557,14 @@ During execution, ACTIVELY MONITOR for watch-for symptoms. Escalate if detected.
 - Save all results as parquet for downstream use
 - If producing figures, save to output/figures/
 
-**OUTPUT FORMAT (1000-word hard cap):**
-Return analysis report:
-
-### Statistical Analysis: {analysis_name}
-**Model:** {model_type}
-**Hypothesis:** {hypothesis}
-
-**Assumption Checks:**
-| Assumption | Test | Result | Status |
-|------------|------|--------|--------|
-| {assumption} | {test_name} | {value} | PASS/FAIL/WARNING |
-
-**Primary Results:**
-- {key_result_1}
-- {key_result_2}
-- Effect size: {effect_size}
-
-**Robustness Checks:**
-| Check | Result | Consistent with Primary? |
-|-------|--------|------------------------|
-| {check_name} | {result} | Yes/No |
-
-**Files Created:**
-- `output/analysis/{filename}`: {description}
-- `output/figures/{filename}`: {description} (if applicable)
+**OUTPUT FORMAT:**
+Return findings using the Research Executor Output Format
+(see your agent protocol, § Output Format).
 
-**Status:** PASSED | FAILED | WARNING
-If FAILED: [issue description and proposed fix]
+**Emphasis for this invocation:**
+- Analysis results summary (key coefficients, effect sizes, p-values, model fit)
+- Assumption check outcomes and robustness check consistency
+- File paths created (`output/analysis/`, `output/figures/` if applicable)
 
 Do NOT proceed to next analysis task. Return to orchestrator for approval.""",
     subagent_type: "research-executor"
diff --git a/agent_reference/WORKFLOW_PHASE5_SYNTHESIS.md b/agent_reference/WORKFLOW_PHASE5_SYNTHESIS.md
index 8586616..a8c7346 100644
--- a/agent_reference/WORKFLOW_PHASE5_SYNTHESIS.md
+++ b/agent_reference/WORKFLOW_PHASE5_SYNTHESIS.md
@@ -173,6 +173,16 @@ Agent({
     - LEARNINGS.md path: {learnings_path}
     - QA Summary findings: {qa_summary_or_path}
 
+    **DISCOVERY PRELIMINARY NOTES (for Telephone Game trace):**
+    The following preliminary notes contain the original source research. Use these
+    for the Telephone Game trace — verify that constraints, caveats, and coded value
+    rules established in discovery are faithfully reflected through Plan -> scripts -> output:
+    - {project_dir}/output/preliminary_notes/{date}_stage2_data-exploration.md
+    - {project_dir}/output/preliminary_notes/{date}_stage3_{source1}_source-research.md
+    - {project_dir}/output/preliminary_notes/{date}_stage3_{source2}_source-research.md
+    [...one path per source]
+    - {project_dir}/output/preliminary_notes/{date}_stage3.5_research-synthesis.md
+
     **TASK:**
     Perform adversarial goal-backward verification of the completed
     analysis. Verify all four layers (existence, substantiveness,
@@ -461,6 +471,11 @@ After passing Final Review, deliver to user:
 - Data: `research/[folder]/data/`
 - Figures: `research/[folder]/output/figures/`
 - Learnings: `research/[folder]/LEARNINGS.md`
+- Session logs: `research/[folder]/logs/`
+
+**Explore Session Logs:**
+To browse the session timeline interactively in your browser, run in the Docker terminal:
+`bash /daaf/scripts/generate_log_viewer.sh /daaf/research/[folder]`
 
 **Key Findings:**
 1. [Finding 1]
diff --git a/benchmarks/__init__.py b/benchmarks/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/config/cost_budget.yaml b/benchmarks/config/cost_budget.yaml
new file mode 100644
index 0000000..cd869e9
--- /dev/null
+++ b/benchmarks/config/cost_budget.yaml
@@ -0,0 +1,21 @@
+# Cost budget configuration for DAAF Framework Adherence Benchmarks
+#
+# The runner will halt execution if any budget limit is exceeded.
+
+# Maximum cost for a single test case run (USD)
+max_cost_per_run: 15.00
+
+# Maximum total cost for an entire benchmark suite (USD)
+max_cost_per_suite: 500.00
+
+# Maximum total cost across all suites in a session (USD)
+max_cost_per_session: 1000.00
+
+# Number of repetitions per test case per model (for pass@k)
+default_repetitions: 3
+
+# Override repetitions for specific cost tiers
+repetitions_by_tier:
+  low: 3
+  medium: 3
+  high: 2
diff --git a/benchmarks/config/models.yaml b/benchmarks/config/models.yaml
new file mode 100644
index 0000000..bff9357
--- /dev/null
+++ b/benchmarks/config/models.yaml
@@ -0,0 +1,34 @@
+# Model matrix for DAAF Framework Adherence Benchmarks
+#
+# Each entry defines a model configuration to benchmark.
+# env_overrides are passed as environment variables to the claude CLI.
+
+models:
+  - id: "claude-haiku-4-5-20251001"
+    name: "Haiku 4.5"
+    cost_tier: "low"
+    env_overrides: {}
+
+  - id: "claude-sonnet-4-6"
+    name: "Sonnet 4.6"
+    cost_tier: "medium"
+    env_overrides: {}
+
+  - id: "claude-opus-4-6"
+    name: "Opus 4.6"
+    cost_tier: "high"
+    env_overrides: {}
+
+# Thinking level variants (uncomment to include in benchmark runs)
+#
+#  - id: "claude-sonnet-4-6"
+#    name: "Sonnet 4.6 (low effort)"
+#    cost_tier: "medium"
+#    env_overrides:
+#      CLAUDE_CODE_EFFORT_LEVEL: "low"
+#
+#  - id: "claude-sonnet-4-6"
+#    name: "Sonnet 4.6 (max effort)"
+#    cost_tier: "medium"
+#    env_overrides:
+#      CLAUDE_CODE_EFFORT_LEVEL: "max"
diff --git a/benchmarks/datasets/mode_classification/cases.jsonl b/benchmarks/datasets/mode_classification/cases.jsonl
new file mode 100644
index 0000000..06ff402
--- /dev/null
+++ b/benchmarks/datasets/mode_classification/cases.jsonl
@@ -0,0 +1,15 @@
+{"id": "mc-01", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "I have a new CSV of school-level poverty data that I downloaded from the Census Bureau. Can you help me profile it and make it available for future analyses?", "expected": {"mode": "data_onboarding", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-02", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "What are the coded values for the inst_control variable in IPEDS? I need to know what 1, 2, and 3 mean.", "expected": {"mode": "data_lookup", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-03", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "Is it feasible to analyze the relationship between school poverty rates and student achievement using publicly available data? What data sources might be relevant?", "expected": {"mode": "data_discovery", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-04", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "Can you help me debug this Polars join that is dropping rows? I think the key columns might have type mismatches but I am not sure where to look.", "expected": {"mode": "ad_hoc_collaboration", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-05", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "Analyze the relationship between college selectivity (admission rates) and six-year graduation rates using IPEDS data. I want a complete analysis with visualizations and a final report.", "expected": {"mode": "full_pipeline", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-06", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "Can you re-run my college selectivity analysis from last week to verify that the results reproduce? I want to make sure everything checks out before I share it.", "expected": {"mode": "reproducibility_verification", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-07", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "I want to create a new data source skill for the NCES Private School Universe Survey data so it can be used in future DAAF analyses.", "expected": {"mode": "framework_development", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-08", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "What is DAAF? How does it work and what can it do? I am brand new to this system.", "expected": {"mode": "user_support", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-09", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "The regression in my previous college graduation rate analysis used total enrollment as a control instead of FTE enrollment. Can you fix that and re-run the affected steps?", "expected": {"mode": "revision_and_extension", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-10", "category": "mode_classification", "subcategory": "ambiguous", "prompt": "Explore what data exists about school discipline disparities by race and disability status.", "expected": {"mode": "data_discovery", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-11", "category": "mode_classification", "subcategory": "ambiguous", "prompt": "Help me think through the best approach for analyzing how Pell Grant distribution has changed over time across different institution types.", "expected": {"mode": "ad_hoc_collaboration", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-12", "category": "mode_classification", "subcategory": "ambiguous", "prompt": "I want to extend my graduation rate analysis to also include financial aid variables from FSA. Can you add Pell Grant data to the existing analysis?", "expected": {"mode": "revision_and_extension", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-13", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "What years does the CRDC cover and what variables are available for analyzing restraint and seclusion practices?", "expected": {"mode": "data_lookup", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-14", "category": "mode_classification", "subcategory": "unambiguous", "prompt": "Update the CCD data source skill to document the 2023-24 school year data that was recently added to the Education Data Portal.", "expected": {"mode": "framework_development", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
+{"id": "mc-15", "category": "mode_classification", "subcategory": "ambiguous", "prompt": "I have enrollment data from a brand new source that nobody has used before. Can you analyze racial disparities in enrollment trends across school districts?", "expected": {"mode": "full_pipeline", "confirmation_gate": true}, "turn_limit": 5, "cost_tier": "low", "hard_requirements": ["mode_correct", "confirmation_gate_present", "no_premature_execution"], "soft_requirements": ["reasoning_present"]}
diff --git a/benchmarks/harness/__init__.py b/benchmarks/harness/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/harness/collector.py b/benchmarks/harness/collector.py
new file mode 100644
index 0000000..c436424
--- /dev/null
+++ b/benchmarks/harness/collector.py
@@ -0,0 +1,219 @@
+"""Collector module: reads DAAF artifacts after a benchmark run.
+
+Extracts audit.jsonl entries, session transcripts, and created files
+for a specific session_id. Runs OUTSIDE the execution environment
+(or reads via volume mount) to maintain scoring isolation.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+
+# Default paths within the DAAF container
+DEFAULT_AUDIT_LOG = Path("/daaf/.claude/logs/audit.jsonl")
+DEFAULT_SESSIONS_DIR = Path("/daaf/.claude/logs/sessions")
+
+
+def collect_audit_entries(
+    session_id: str,
+    audit_log_path: Path = DEFAULT_AUDIT_LOG,
+    after_timestamp: str | None = None,
+) -> list[dict]:
+    """Extract audit.jsonl entries for a specific session.
+
+    Args:
+        session_id: The Claude Code session ID to filter by.
+        audit_log_path: Path to the audit.jsonl file.
+        after_timestamp: ISO timestamp; only return entries after this time.
+            Useful when the audit log contains entries from prior runs.
+
+    Returns:
+        List of audit entry dicts, chronologically ordered.
+    """
+    if not audit_log_path.exists():
+        return []
+
+    entries = []
+    with open(audit_log_path) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            if entry.get("session_id") != session_id:
+                continue
+
+            if after_timestamp and entry.get("timestamp", "") <= after_timestamp:
+                continue
+
+            entries.append(entry)
+
+    return sorted(entries, key=lambda e: e.get("timestamp", ""))
+
+
+def get_audit_log_position(audit_log_path: Path = DEFAULT_AUDIT_LOG) -> tuple[int, str]:
+    """Snapshot the current audit log position before a run.
+
+    Returns:
+        Tuple of (line_count, last_timestamp) for filtering after the run.
+    """
+    if not audit_log_path.exists():
+        return (0, "")
+
+    line_count = 0
+    last_timestamp = ""
+    with open(audit_log_path) as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                line_count += 1
+                try:
+                    entry = json.loads(line)
+                    ts = entry.get("timestamp", "")
+                    if ts > last_timestamp:
+                        last_timestamp = ts
+                except json.JSONDecodeError:
+                    continue
+
+    return (line_count, last_timestamp)
+
+
+def collect_new_audit_entries(
+    after_timestamp: str,
+    audit_log_path: Path = DEFAULT_AUDIT_LOG,
+) -> list[dict]:
+    """Collect ALL audit entries added after a given timestamp.
+
+    Useful when session_id is not yet known (we collect then filter).
+    """
+    if not audit_log_path.exists():
+        return []
+
+    entries = []
+    with open(audit_log_path) as f:
+        for line in f:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                entry = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            if entry.get("timestamp", "") > after_timestamp:
+                entries.append(entry)
+
+    return sorted(entries, key=lambda e: e.get("timestamp", ""))
+
+
+def find_session_transcript(
+    session_id: str,
+    sessions_dir: Path = DEFAULT_SESSIONS_DIR,
+) -> Path | None:
+    """Find the archived session transcript for a given session ID.
+
+    Session archives are named: {date}_{time}_{session-short}_orchestrator.jsonl
+    The session-short is the first 8 chars of the session UUID.
+    """
+    if not sessions_dir.exists():
+        return None
+
+    session_short = session_id[:8] if len(session_id) >= 8 else session_id
+
+    for p in sessions_dir.glob(f"*_{session_short}_orchestrator.jsonl"):
+        return p
+
+    # Fallback: try matching any file containing the short ID
+    for p in sessions_dir.glob(f"*{session_short}*.jsonl"):
+        return p
+
+    return None
+
+
+def find_session_markdown(
+    session_id: str,
+    sessions_dir: Path = DEFAULT_SESSIONS_DIR,
+) -> Path | None:
+    """Find the human-readable Markdown transcript for a session."""
+    jsonl_path = find_session_transcript(session_id, sessions_dir)
+    if jsonl_path is None:
+        return None
+
+    md_path = jsonl_path.with_suffix(".md")
+    return md_path if md_path.exists() else None
+
+
+def collect_created_files(
+    sandbox_dir: Path,
+    after_time: float,
+) -> list[str]:
+    """List files created in the sandbox directory after a given time.
+
+    Args:
+        sandbox_dir: Directory to scan for new files.
+        after_time: Unix timestamp; only return files modified after this.
+
+    Returns:
+        List of absolute file paths as strings.
+    """
+    if not sandbox_dir.exists():
+        return []
+
+    created = []
+    for p in sandbox_dir.rglob("*"):
+        if p.is_file() and p.stat().st_mtime > after_time:
+            created.append(str(p))
+
+    return sorted(created)
+
+
+def extract_tool_sequence(audit_entries: list[dict]) -> list[dict]:
+    """Extract a simplified tool call sequence from audit entries.
+
+    Returns a list of dicts with: tool, target, agent_type, timestamp.
+    Useful for protocol adherence scoring.
+    """
+    return [
+        {
+            "tool": e.get("tool", "unknown"),
+            "target": e.get("target", ""),
+            "agent_type": e.get("agent_type", "orchestrator"),
+            "agent_id": e.get("agent_id", ""),
+            "timestamp": e.get("timestamp", ""),
+        }
+        for e in audit_entries
+    ]
+
+
+def extract_skill_loads(audit_entries: list[dict]) -> list[str]:
+    """Extract the names of skills loaded during a session.
+
+    Looks for Skill tool invocations in the audit entries.
+    The target field for Skill calls contains the skill name.
+    """
+    skills = []
+    for e in audit_entries:
+        if e.get("tool") == "Skill":
+            target = e.get("target", "").strip()
+            if target:
+                skills.append(target)
+    return skills
+
+
+def extract_read_targets(audit_entries: list[dict]) -> list[str]:
+    """Extract file paths read during a session."""
+    return [
+        e.get("target", "")
+        for e in audit_entries
+        if e.get("tool") == "Read" and e.get("target")
+    ]
+
+
+def now_iso() -> str:
+    """Return current UTC time as ISO string matching audit.jsonl format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
diff --git a/benchmarks/harness/executor.py b/benchmarks/harness/executor.py
new file mode 100644
index 0000000..66b368d
--- /dev/null
+++ b/benchmarks/harness/executor.py
@@ -0,0 +1,214 @@
+"""Executor module: runs a single benchmark test case via Claude Code CLI.
+
+Wraps `claude -p` invocation with model selection, turn limits, and output
+capture. Designed to run INSIDE the DAAF container so all hooks fire and
+the full framework is exercised.
+"""
+
+import json
+import subprocess
+import time
+from pathlib import Path
+
+from benchmarks.harness.models import RunConfig, RunResult
+
+
+# Timeout per cost tier (seconds)
+TIMEOUT_BY_TIER = {
+    "low": 120,      # 2 minutes for simple classification
+    "medium": 300,   # 5 minutes for multi-turn protocol tests
+    "high": 600,     # 10 minutes for code generation tests
+}
+
+
+def execute_run(config: RunConfig) -> RunResult:
+    """Execute a single benchmark run via claude -p.
+
+    Launches Claude Code in headless mode with the test case prompt,
+    captures the JSON output, and returns a RunResult.
+    """
+    test_case = config.test_case
+    model = config.model
+
+    # Build the CLI command
+    cmd = [
+        "claude",
+        "-p", test_case.prompt,
+        "--model", model.id,
+        "--output-format", "json",
+        "--max-turns", str(test_case.turn_limit),
+        "--permission-mode", config.permission_mode,
+    ]
+
+    # Build environment with any model-specific overrides
+    import os
+    env = os.environ.copy()
+    env.update(model.env_overrides)
+
+    timeout = TIMEOUT_BY_TIER.get(test_case.cost_tier, 300)
+
+    result = RunResult(
+        test_case_id=test_case.id,
+        model_id=model.id,
+        model_name=model.name,
+        run_index=config.run_index,
+    )
+
+    start_time = time.time()
+
+    try:
+        proc = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            cwd=config.working_dir,
+            env=env,
+        )
+
+        result.exit_code = proc.returncode
+        result.duration_seconds = time.time() - start_time
+
+        if proc.returncode != 0 and not proc.stdout.strip():
+            result.error = f"CLI exited with code {proc.returncode}: {proc.stderr[:500]}"
+            return result
+
+        # Parse JSON output.
+        # claude -p --output-format json returns a JSON array of messages:
+        #   [{type: "system", subtype: "init", ...},
+        #    {type: "assistant", message: {content: [...]}},
+        #    ...,
+        #    {type: "result", subtype: "success", session_id, result, total_cost_usd, ...}]
+        stdout = proc.stdout.strip()
+        if stdout:
+            try:
+                output = json.loads(stdout)
+
+                # Handle list-of-messages format
+                if isinstance(output, list):
+                    result.raw_json = {"messages": output}
+
+                    # Find the result message (last item with type=result)
+                    result_msg = None
+                    for msg in reversed(output):
+                        if isinstance(msg, dict) and msg.get("type") == "result":
+                            result_msg = msg
+                            break
+
+                    if result_msg:
+                        result.session_id = result_msg.get("session_id", "")
+                        result.response_text = result_msg.get("result", "")
+                        result.total_cost_usd = result_msg.get("total_cost_usd", 0.0)
+                        result.total_turns = result_msg.get("num_turns", 0)
+                        duration_ms = result_msg.get("duration_ms", 0)
+                        if duration_ms:
+                            result.duration_seconds = duration_ms / 1000.0
+
+                    # Also extract the last assistant text as response if
+                    # result.response_text is empty
+                    if not result.response_text:
+                        for msg in reversed(output):
+                            if not isinstance(msg, dict):
+                                continue
+                            if msg.get("type") == "assistant":
+                                content = msg.get("message", {}).get("content", [])
+                                for block in content:
+                                    if isinstance(block, dict) and block.get("type") == "text":
+                                        result.response_text = block.get("text", "")
+                                        break
+                                if result.response_text:
+                                    break
+
+                elif isinstance(output, dict):
+                    # Fallback: single dict format (future-proofing)
+                    result.raw_json = output
+                    result.session_id = output.get("session_id", "")
+                    result.response_text = output.get("result", "")
+                    result.total_cost_usd = output.get("total_cost_usd", 0.0)
+                    result.total_turns = output.get("num_turns", 0)
+
+            except json.JSONDecodeError as e:
+                result.error = f"Failed to parse JSON output: {e}"
+                result.response_text = stdout[:2000]
+
+        # Capture stderr for diagnostics (but don't treat as error)
+        if proc.stderr.strip():
+            stderr_summary = proc.stderr.strip()[:500]
+            if result.error:
+                result.error += f"\nstderr: {stderr_summary}"
+
+    except subprocess.TimeoutExpired:
+        result.duration_seconds = time.time() - start_time
+        result.error = f"Timed out after {timeout}s"
+
+    except Exception as e:
+        result.duration_seconds = time.time() - start_time
+        result.error = f"Execution error: {type(e).__name__}: {e}"
+
+    return result
+
+
+def check_cli_available() -> bool:
+    """Verify that the claude CLI is available and responsive."""
+    try:
+        proc = subprocess.run(
+            ["claude", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+        return proc.returncode == 0
+    except (subprocess.TimeoutExpired, FileNotFoundError):
+        return False
+
+
+def check_hooks_active(working_dir: str = "/daaf") -> dict[str, bool]:
+    """Check which DAAF hooks are likely active by examining settings.json.
+
+    DAAF settings.json uses a nested structure:
+    {event: [{matcher, hooks: [{command, ...}]}]}
+    """
+    settings_path = Path(working_dir) / ".claude" / "settings.json"
+    hooks_found = {
+        "audit_log": False,
+        "bash_safety": False,
+        "enforce_file_first": False,
+        "context_reporter": False,
+        "archive_session": False,
+        "output_scanner": False,
+    }
+
+    if not settings_path.exists():
+        return hooks_found
+
+    # Map hook script names to our key names
+    hook_name_map = {
+        "audit-log": "audit_log",
+        "bash-safety": "bash_safety",
+        "enforce-file-first": "enforce_file_first",
+        "context-reporter": "context_reporter",
+        "archive-session": "archive_session",
+        "output-scanner": "output_scanner",
+    }
+
+    try:
+        with open(settings_path) as f:
+            settings = json.load(f)
+
+        hooks = settings.get("hooks", {})
+        for event_matchers in hooks.values():
+            if not isinstance(event_matchers, list):
+                continue
+            for matcher_group in event_matchers:
+                inner_hooks = matcher_group.get("hooks", [])
+                if not isinstance(inner_hooks, list):
+                    continue
+                for hook_def in inner_hooks:
+                    cmd = hook_def.get("command", "") if isinstance(hook_def, dict) else ""
+                    for script_name, key in hook_name_map.items():
+                        if script_name in cmd:
+                            hooks_found[key] = True
+    except (json.JSONDecodeError, KeyError, TypeError):
+        pass
+
+    return hooks_found
diff --git a/benchmarks/harness/models.py b/benchmarks/harness/models.py
new file mode 100644
index 0000000..b6500c8
--- /dev/null
+++ b/benchmarks/harness/models.py
@@ -0,0 +1,161 @@
+"""Data models for the DAAF Framework Adherence Benchmark harness.
+
+Defines the core dataclasses used throughout the benchmark pipeline:
+TestCase, RunConfig, RunResult, ScoredResult, and ModelConfig.
+"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+import json
+from pathlib import Path
+
+
+@dataclass
+class TestCase:
+    """A single benchmark test case loaded from a JSONL dataset file."""
+
+    id: str
+    category: str
+    prompt: str
+    expected: dict
+    subcategory: str = ""
+    auto_replies: list[dict] = field(default_factory=list)
+    turn_limit: int = 5
+    cost_tier: str = "low"
+    hard_requirements: list[str] = field(default_factory=list)
+    soft_requirements: list[str] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "TestCase":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+    @classmethod
+    def load_from_jsonl(cls, path: Path) -> list["TestCase"]:
+        cases = []
+        with open(path) as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    cases.append(cls.from_dict(json.loads(line)))
+        return cases
+
+
+@dataclass
+class ModelConfig:
+    """Configuration for a model to benchmark."""
+
+    id: str
+    name: str
+    cost_tier: str = "medium"
+    env_overrides: dict[str, str] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ModelConfig":
+        return cls(**{k: v for k, v in data.items() if k in cls.__dataclass_fields__})
+
+
+@dataclass
+class RunConfig:
+    """Configuration for a single benchmark run."""
+
+    test_case: TestCase
+    model: ModelConfig
+    run_index: int
+    permission_mode: str = "dontAsk"
+    working_dir: str = "/daaf"
+    sandbox_dir: str = "/daaf/benchmarks/_sandbox"
+
+
+@dataclass
+class RunResult:
+    """Raw result from executing a single benchmark run."""
+
+    test_case_id: str
+    model_id: str
+    model_name: str
+    run_index: int
+    session_id: str = ""
+    total_turns: int = 0
+    total_cost_usd: float = 0.0
+    duration_seconds: float = 0.0
+    response_text: str = ""
+    raw_json: dict = field(default_factory=dict)
+    audit_entries: list[dict] = field(default_factory=list)
+    transcript_path: str = ""
+    files_created: list[str] = field(default_factory=list)
+    error: Optional[str] = None
+    exit_code: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "test_case_id": self.test_case_id,
+            "model_id": self.model_id,
+            "model_name": self.model_name,
+            "run_index": self.run_index,
+            "session_id": self.session_id,
+            "total_turns": self.total_turns,
+            "total_cost_usd": self.total_cost_usd,
+            "duration_seconds": self.duration_seconds,
+            "response_text": self.response_text[:500],
+            "audit_entry_count": len(self.audit_entries),
+            "transcript_path": self.transcript_path,
+            "files_created": self.files_created,
+            "error": self.error,
+            "exit_code": self.exit_code,
+        }
+
+
+@dataclass
+class CriterionResult:
+    """Result for a single scoring criterion."""
+
+    name: str
+    passed: bool
+    tier: str  # "tier1", "tier2", "tier3"
+    detail: str = ""
+    judge_reasoning: str = ""
+
+
+@dataclass
+class ScoredResult:
+    """A RunResult with scoring applied."""
+
+    run: RunResult
+    criteria: list[CriterionResult] = field(default_factory=list)
+
+    @property
+    def pass_count(self) -> int:
+        return sum(1 for c in self.criteria if c.passed)
+
+    @property
+    def total_count(self) -> int:
+        return len(self.criteria)
+
+    @property
+    def pass_rate(self) -> float:
+        if not self.criteria:
+            return 0.0
+        return self.pass_count / self.total_count
+
+    def hard_requirement_failures(self, hard_reqs: list[str]) -> list[str]:
+        return [
+            c.name for c in self.criteria
+            if c.name in hard_reqs and not c.passed
+        ]
+
+    def to_dict(self) -> dict:
+        return {
+            "run": self.run.to_dict(),
+            "criteria": [
+                {
+                    "name": c.name,
+                    "passed": c.passed,
+                    "tier": c.tier,
+                    "detail": c.detail,
+                }
+                for c in self.criteria
+            ],
+            "pass_count": self.pass_count,
+            "total_count": self.total_count,
+            "pass_rate": self.pass_rate,
+        }
diff --git a/benchmarks/harness/runner.py b/benchmarks/harness/runner.py
new file mode 100644
index 0000000..4ef32ce
--- /dev/null
+++ b/benchmarks/harness/runner.py
@@ -0,0 +1,388 @@
+"""Runner module: orchestrates benchmark execution across the test matrix.
+
+Iterates over test cases, models, and repetitions. Calls executor for each
+run, collector to gather artifacts, and the appropriate scorer to evaluate.
+Writes per-run results to a timestamped results directory.
+"""
+
+import argparse
+import json
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+
+import yaml
+
+from benchmarks.harness.models import (
+    ModelConfig,
+    RunConfig,
+    RunResult,
+    ScoredResult,
+    TestCase,
+)
+from benchmarks.harness.executor import check_cli_available, check_hooks_active, execute_run
+from benchmarks.harness.collector import (
+    collect_audit_entries,
+    collect_new_audit_entries,
+    get_audit_log_position,
+    now_iso,
+)
+
+# Scorer registry: maps category name to scoring function
+SCORER_REGISTRY: dict = {}
+
+
+def register_scorer(category: str):
+    """Decorator to register a scoring function for a test category."""
+    def wrapper(fn):
+        SCORER_REGISTRY[category] = fn
+        return fn
+    return wrapper
+
+
+def load_scorers():
+    """Import scorer modules to trigger registration."""
+    try:
+        from benchmarks.scorers.deterministic.mode_classification import score_mode_classification
+        SCORER_REGISTRY["mode_classification"] = score_mode_classification
+    except ImportError as e:
+        print(f"WARNING: Could not load mode_classification scorer: {e}", file=sys.stderr)
+
+
+def load_models(config_path: Path) -> list[ModelConfig]:
+    """Load model configurations from YAML."""
+    with open(config_path) as f:
+        data = yaml.safe_load(f)
+    return [ModelConfig.from_dict(m) for m in data.get("models", [])]
+
+
+def load_budget(config_path: Path) -> dict:
+    """Load cost budget configuration from YAML."""
+    with open(config_path) as f:
+        return yaml.safe_load(f)
+
+
+def load_test_cases(dataset_dir: Path, category: str | None = None) -> list[TestCase]:
+    """Load test cases from JSONL files in the datasets directory.
+
+    If category is specified, only load from that subdirectory.
+    Otherwise, load from all subdirectories.
+    """
+    cases = []
+    if category:
+        jsonl_path = dataset_dir / category / "cases.jsonl"
+        if jsonl_path.exists():
+            cases.extend(TestCase.load_from_jsonl(jsonl_path))
+    else:
+        for subdir in sorted(dataset_dir.iterdir()):
+            if subdir.is_dir():
+                jsonl_path = subdir / "cases.jsonl"
+                if jsonl_path.exists():
+                    cases.extend(TestCase.load_from_jsonl(jsonl_path))
+    return cases
+
+
+def run_single(
+    config: RunConfig,
+    pre_run_timestamp: str,
+) -> ScoredResult:
+    """Execute a single test case run and score the result."""
+    # Execute
+    run_result = execute_run(config)
+
+    # Collect audit entries if we got a session_id
+    if run_result.session_id:
+        run_result.audit_entries = collect_audit_entries(
+            session_id=run_result.session_id,
+            after_timestamp=pre_run_timestamp,
+        )
+    elif not run_result.error:
+        # No session_id but no error — collect by timestamp
+        run_result.audit_entries = collect_new_audit_entries(
+            after_timestamp=pre_run_timestamp,
+        )
+
+    # Score
+    scorer = SCORER_REGISTRY.get(config.test_case.category)
+    if scorer:
+        criteria = scorer(run_result, config.test_case.expected)
+        return ScoredResult(run=run_result, criteria=criteria)
+    else:
+        print(
+            f"WARNING: No scorer for category '{config.test_case.category}'. "
+            f"Returning unscored result.",
+            file=sys.stderr,
+        )
+        return ScoredResult(run=run_result)
+
+
+def print_result_summary(scored: ScoredResult, test_case: TestCase):
+    """Print a concise summary of a single scored run."""
+    status = "PASS" if scored.pass_rate == 1.0 else "FAIL" if scored.pass_rate == 0.0 else "PARTIAL"
+    cost_str = f"${scored.run.total_cost_usd:.3f}" if scored.run.total_cost_usd else "n/a"
+    error_str = f" ERROR: {scored.run.error}" if scored.run.error else ""
+
+    print(
+        f"  [{status}] {test_case.id} | "
+        f"model={scored.run.model_name} | "
+        f"rep={scored.run.run_index} | "
+        f"pass={scored.pass_count}/{scored.total_count} | "
+        f"cost={cost_str} | "
+        f"turns={scored.run.total_turns} | "
+        f"time={scored.run.duration_seconds:.1f}s"
+        f"{error_str}"
+    )
+
+    # Print individual criteria
+    for c in scored.criteria:
+        mark = "+" if c.passed else "x"
+        print(f"    [{mark}] {c.name}: {c.detail[:120]}")
+
+
+def print_suite_summary(all_results: list[ScoredResult]):
+    """Print an aggregate summary table across all results."""
+    if not all_results:
+        print("\nNo results to summarize.")
+        return
+
+    # Group by model
+    by_model: dict[str, list[ScoredResult]] = {}
+    for sr in all_results:
+        model_name = sr.run.model_name
+        by_model.setdefault(model_name, []).append(sr)
+
+    # Collect all criterion names
+    all_criteria = []
+    seen = set()
+    for sr in all_results:
+        for c in sr.criteria:
+            if c.name not in seen:
+                all_criteria.append(c.name)
+                seen.add(c.name)
+
+    # Print table
+    models = sorted(by_model.keys())
+    header = f"{'Criterion':<35}" + "".join(f"| {m:<20}" for m in models)
+    separator = "-" * len(header)
+
+    print(f"\n{separator}")
+    print("SUITE SUMMARY (pass@1 rates)")
+    print(separator)
+    print(header)
+    print(separator)
+
+    for criterion in all_criteria:
+        row = f"{criterion:<35}"
+        for model_name in models:
+            results = by_model[model_name]
+            passes = sum(
+                1 for sr in results
+                for c in sr.criteria
+                if c.name == criterion and c.passed
+            )
+            total = sum(
+                1 for sr in results
+                for c in sr.criteria
+                if c.name == criterion
+            )
+            rate = passes / total if total > 0 else 0.0
+            row += f"| {rate:.2f} ({passes}/{total})       "
+        print(row)
+
+    print(separator)
+
+    # Cost summary
+    print("\nCOST SUMMARY")
+    print(separator)
+    for model_name in models:
+        results = by_model[model_name]
+        total_cost = sum(sr.run.total_cost_usd for sr in results)
+        total_time = sum(sr.run.duration_seconds for sr in results)
+        errors = sum(1 for sr in results if sr.run.error)
+        print(
+            f"  {model_name}: "
+            f"runs={len(results)}, "
+            f"cost=${total_cost:.2f}, "
+            f"time={total_time:.0f}s, "
+            f"errors={errors}"
+        )
+    print(separator)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="DAAF Framework Adherence Benchmark Runner"
+    )
+    parser.add_argument(
+        "--category",
+        type=str,
+        default=None,
+        help="Run only test cases from this category (e.g., 'mode_classification')",
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default=None,
+        help="Run only this model ID (e.g., 'claude-haiku-4-5-20251001')",
+    )
+    parser.add_argument(
+        "--test-id",
+        type=str,
+        default=None,
+        help="Run only this specific test case ID (e.g., 'mc-01')",
+    )
+    parser.add_argument(
+        "--reps",
+        type=int,
+        default=None,
+        help="Override number of repetitions per test case",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print the test matrix without executing",
+    )
+    parser.add_argument(
+        "--base-dir",
+        type=str,
+        default="/daaf",
+        help="DAAF base directory (default: /daaf)",
+    )
+
+    args = parser.parse_args()
+
+    base = Path(args.base_dir)
+    bench = base / "benchmarks"
+
+    # Load configuration
+    models = load_models(bench / "config" / "models.yaml")
+    budget = load_budget(bench / "config" / "cost_budget.yaml")
+    test_cases = load_test_cases(bench / "datasets", args.category)
+    load_scorers()
+
+    if not test_cases:
+        print("ERROR: No test cases found.", file=sys.stderr)
+        sys.exit(1)
+
+    # Filter by model if specified
+    if args.model:
+        models = [m for m in models if m.id == args.model or m.name == args.model]
+        if not models:
+            print(f"ERROR: Model '{args.model}' not found in config.", file=sys.stderr)
+            sys.exit(1)
+
+    # Filter by test ID if specified
+    if args.test_id:
+        test_cases = [tc for tc in test_cases if tc.id == args.test_id]
+        if not test_cases:
+            print(f"ERROR: Test case '{args.test_id}' not found.", file=sys.stderr)
+            sys.exit(1)
+
+    # Determine repetitions
+    default_reps = args.reps or budget.get("default_repetitions", 3)
+    reps_by_tier = budget.get("repetitions_by_tier", {})
+
+    # Build test matrix
+    matrix = []
+    for model in models:
+        for tc in test_cases:
+            reps = args.reps or reps_by_tier.get(tc.cost_tier, default_reps)
+            for rep in range(reps):
+                matrix.append((model, tc, rep))
+
+    print(f"DAAF Framework Adherence Benchmark")
+    print(f"===================================")
+    print(f"Models:     {len(models)} ({', '.join(m.name for m in models)})")
+    print(f"Test cases: {len(test_cases)}")
+    print(f"Total runs: {len(matrix)}")
+    print(f"Categories: {sorted(set(tc.category for tc in test_cases))}")
+    print(f"Scorers:    {sorted(SCORER_REGISTRY.keys())}")
+    print()
+
+    if args.dry_run:
+        print("DRY RUN — test matrix:")
+        for model, tc, rep in matrix:
+            print(f"  {model.name} | {tc.id} | rep={rep}")
+        return
+
+    # Pre-flight checks
+    if not check_cli_available():
+        print("ERROR: 'claude' CLI not found or not responsive.", file=sys.stderr)
+        sys.exit(1)
+
+    hooks_status = check_hooks_active(str(base))
+    print("Hook status:")
+    for hook, active in hooks_status.items():
+        print(f"  {hook}: {'active' if active else 'NOT FOUND'}")
+    print()
+
+    # Create results directory
+    run_timestamp = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+    results_dir = bench / "results" / run_timestamp
+    results_dir.mkdir(parents=True, exist_ok=True)
+
+    # Execute
+    all_results: list[ScoredResult] = []
+    total_cost = 0.0
+
+    for i, (model, tc, rep) in enumerate(matrix):
+        print(f"\n--- Run {i + 1}/{len(matrix)} ---")
+
+        # Check budget
+        if total_cost >= budget.get("max_cost_per_suite", float("inf")):
+            print(f"BUDGET EXCEEDED: ${total_cost:.2f} >= suite limit. Stopping.")
+            break
+
+        # Snapshot audit log position
+        pre_run_ts = now_iso()
+        time.sleep(0.1)  # Ensure timestamp separation
+
+        config = RunConfig(
+            test_case=tc,
+            model=model,
+            run_index=rep,
+            working_dir=str(base),
+        )
+
+        scored = run_single(config, pre_run_ts)
+        all_results.append(scored)
+        total_cost += scored.run.total_cost_usd
+
+        print_result_summary(scored, tc)
+
+        # Write individual result
+        result_file = results_dir / f"{tc.id}_{model.id}_{rep}.json"
+        with open(result_file, "w") as f:
+            json.dump(scored.to_dict(), f, indent=2)
+
+        # Check per-run cost
+        if scored.run.total_cost_usd > budget.get("max_cost_per_run", float("inf")):
+            print(
+                f"WARNING: Run cost ${scored.run.total_cost_usd:.2f} "
+                f"exceeds per-run limit."
+            )
+
+    # Write aggregate results
+    aggregate_file = results_dir / "aggregate.json"
+    with open(aggregate_file, "w") as f:
+        json.dump(
+            {
+                "timestamp": run_timestamp,
+                "models": [m.id for m in models],
+                "test_cases": [tc.id for tc in test_cases],
+                "total_runs": len(all_results),
+                "total_cost_usd": total_cost,
+                "results": [sr.to_dict() for sr in all_results],
+            },
+            f,
+            indent=2,
+        )
+
+    # Print summary
+    print_suite_summary(all_results)
+    print(f"\nResults written to: {results_dir}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/benchmarks/results/.gitignore b/benchmarks/results/.gitignore
new file mode 100644
index 0000000..bd2483b
--- /dev/null
+++ b/benchmarks/results/.gitignore
@@ -0,0 +1,4 @@
+# Benchmark run results are ephemeral — regenerated on each run.
+# Only the .gitignore and .gitkeep are tracked.
+*.json
+*/
diff --git a/benchmarks/results/.gitkeep b/benchmarks/results/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/scorers/__init__.py b/benchmarks/scorers/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/scorers/deterministic/__init__.py b/benchmarks/scorers/deterministic/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/scorers/deterministic/mode_classification.py b/benchmarks/scorers/deterministic/mode_classification.py
new file mode 100644
index 0000000..9c2deb0
--- /dev/null
+++ b/benchmarks/scorers/deterministic/mode_classification.py
@@ -0,0 +1,238 @@
+"""Deterministic scorer for mode classification test cases.
+
+Checks whether the model correctly classified the engagement mode
+and produced a confirmation gate in its response. All checks are
+Tier 1 (pure deterministic, no LLM involvement).
+"""
+
+import re
+
+from benchmarks.harness.models import CriterionResult, RunResult
+
+
+# Keywords that indicate a specific mode classification.
+# Multiple variants per mode to handle natural language variation.
+MODE_KEYWORDS: dict[str, list[str]] = {
+    "data_onboarding": [
+        "data onboarding",
+        "onboarding mode",
+        "profile your data",
+        "profile the data",
+        "profiling phases",
+        "onboard",
+    ],
+    "data_lookup": [
+        "data lookup",
+        "lookup mode",
+        "look that up",
+        "focused answer",
+        "direct answer",
+    ],
+    "data_discovery": [
+        "data discovery",
+        "discovery mode",
+        "read-only exploration",
+        "no code, no downloads",
+        "explore what",
+    ],
+    "ad_hoc_collaboration": [
+        "ad hoc",
+        "ad-hoc",
+        "collaboration mode",
+        "thought partner",
+        "flexible",
+        "working session",
+    ],
+    "full_pipeline": [
+        "full pipeline",
+        "complete pipeline",
+        "comprehensive mode",
+        "most comprehensive",
+        "5 phases",
+        "five phases",
+        "4 checkpoints",
+        "four checkpoints",
+        "research pipeline",
+    ],
+    "revision_and_extension": [
+        "revision",
+        "extension mode",
+        "revise",
+        "existing analysis",
+        "new version",
+        "original untouched",
+    ],
+    "reproducibility_verification": [
+        "reproducibility",
+        "verification mode",
+        "reproduce",
+        "re-run",
+        "rerun",
+        "reproduction report",
+    ],
+    "framework_development": [
+        "framework development",
+        "framework mode",
+        "modify daaf",
+        "framework components",
+        "skills, agents",
+        "create a skill",
+    ],
+    "user_support": [
+        "user support",
+        "support mode",
+        "answer your questions",
+        "how it works",
+        "troubleshooting",
+    ],
+}
+
+# Patterns indicating a confirmation gate (must end with a question)
+CONFIRMATION_PATTERNS = [
+    r"shall I proceed",
+    r"shall we proceed",
+    r"sound good",
+    r"want me to",
+    r"ready to",
+    r"go ahead\??",
+    r"proceed\?",
+    r"confirm",
+    r"does this .* look right",
+    r"any adjustments",
+    r"approach .* differently",
+    r"shall I",
+    r"want to (try|proceed|start|begin)",
+    r"proceed with",
+    r"do you want",
+    r"would you like",
+    r"should I",
+]
+
+
+def score_mode_classification(
+    run_result: RunResult,
+    expected: dict,
+) -> list[CriterionResult]:
+    """Score a mode classification test case.
+
+    Args:
+        run_result: The raw result from executing the test case.
+        expected: The expected outcomes dict from the test case.
+
+    Returns:
+        List of CriterionResult for each scoring criterion.
+    """
+    results = []
+    response = run_result.response_text
+    response_lower = response.lower()
+
+    # --- Criterion 1: mode_correct ---
+    expected_mode = expected.get("mode", "")
+    keywords = MODE_KEYWORDS.get(expected_mode, [])
+
+    mode_detected = any(kw.lower() in response_lower for kw in keywords)
+
+    # Also check if any OTHER mode was more prominently classified
+    other_modes_detected = []
+    for mode_name, mode_kws in MODE_KEYWORDS.items():
+        if mode_name == expected_mode:
+            continue
+        if any(kw.lower() in response_lower for kw in mode_kws):
+            other_modes_detected.append(mode_name)
+
+    results.append(CriterionResult(
+        name="mode_correct",
+        passed=mode_detected,
+        tier="tier1",
+        detail=(
+            f"Expected mode '{expected_mode}'. "
+            f"{'Detected' if mode_detected else 'NOT detected'} in response. "
+            f"Other modes detected: {other_modes_detected or 'none'}"
+        ),
+    ))
+
+    # --- Criterion 2: confirmation_gate_present ---
+    gate_found = any(
+        re.search(pattern, response, re.IGNORECASE)
+        for pattern in CONFIRMATION_PATTERNS
+    )
+
+    results.append(CriterionResult(
+        name="confirmation_gate_present",
+        passed=gate_found,
+        tier="tier1",
+        detail=(
+            "Confirmation gate "
+            f"{'found' if gate_found else 'NOT found'} in response."
+        ),
+    ))
+
+    # --- Criterion 3: no_premature_execution ---
+    # Check audit entries for tool calls that should not happen before confirmation.
+    # In mode classification, the model should NOT read mode-specific reference files
+    # or dispatch subagents in the same turn as the classification.
+    premature_tools = []
+    mode_ref_files = [
+        "full-pipeline-mode.md",
+        "data-onboarding-mode.md",
+        "data-lookup-mode.md",
+        "data-discovery-mode.md",
+        "ad-hoc-collaboration-mode.md",
+        "revision-and-extension-mode.md",
+        "reproducibility-verification-mode.md",
+        "framework-development-mode.md",
+        "user-support-mode.md",
+    ]
+
+    for entry in run_result.audit_entries:
+        tool = entry.get("tool", "")
+        target = entry.get("target", "")
+
+        # Check for reading mode-specific reference files
+        if tool == "Read" and any(ref in target for ref in mode_ref_files):
+            premature_tools.append(f"Read({target})")
+
+        # Check for Agent dispatches (subagent launches)
+        if tool == "Agent":
+            premature_tools.append(f"Agent({target[:80]})")
+
+    results.append(CriterionResult(
+        name="no_premature_execution",
+        passed=len(premature_tools) == 0,
+        tier="tier1",
+        detail=(
+            "No premature tool calls."
+            if not premature_tools
+            else f"Premature tool calls: {premature_tools}"
+        ),
+    ))
+
+    # --- Criterion 4: reasoning_present (soft) ---
+    # Check that the response includes some reasoning for the classification,
+    # not just a bare mode name.
+    reasoning_indicators = [
+        "because",
+        "since",
+        "this is",
+        "classification",
+        "sounds like",
+        "this falls under",
+        "i'd classify",
+        "this request",
+        "you're asking",
+        "you want to",
+        "your request",
+    ]
+    reasoning_found = any(ind in response_lower for ind in reasoning_indicators)
+
+    results.append(CriterionResult(
+        name="reasoning_present",
+        passed=reasoning_found,
+        tier="tier1",
+        detail=(
+            "Classification reasoning "
+            f"{'found' if reasoning_found else 'NOT found'} in response."
+        ),
+    ))
+
+    return results
diff --git a/benchmarks/scorers/llm_judge/__init__.py b/benchmarks/scorers/llm_judge/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/benchmarks/scripts/clean_sandbox.sh b/benchmarks/scripts/clean_sandbox.sh
new file mode 100755
index 0000000..4ba7e16
--- /dev/null
+++ b/benchmarks/scripts/clean_sandbox.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# clean_sandbox.sh — Reset benchmark sandbox state between runs.
+#
+# Clears any files created by previous benchmark test cases in the
+# sandbox area so each run starts from a clean state. Does NOT touch
+# audit.jsonl or session archives (those are filtered by timestamp).
+#
+# Usage: bash benchmarks/scripts/clean_sandbox.sh [base_dir]
+
+set -euo pipefail
+
+BASE_DIR="${1:-/daaf}"
+SANDBOX_DIR="${BASE_DIR}/benchmarks/_sandbox"
+
+# Create sandbox if it does not exist
+mkdir -p "$SANDBOX_DIR"
+
+# Remove all contents but keep the directory
+if [ -d "$SANDBOX_DIR" ]; then
+    find "$SANDBOX_DIR" -mindepth 1 -delete 2>/dev/null || true
+    echo "Sandbox cleaned: ${SANDBOX_DIR}"
+else
+    echo "Sandbox directory created: ${SANDBOX_DIR}"
+fi
diff --git a/benchmarks/scripts/run_benchmark.sh b/benchmarks/scripts/run_benchmark.sh
new file mode 100755
index 0000000..162fd94
--- /dev/null
+++ b/benchmarks/scripts/run_benchmark.sh
@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# run_benchmark.sh — Entry point for DAAF Framework Adherence Benchmarks.
+#
+# Runs the benchmark harness from within the DAAF container.
+# All arguments are forwarded to the Python runner.
+#
+# Usage:
+#   bash benchmarks/scripts/run_benchmark.sh --category mode_classification
+#   bash benchmarks/scripts/run_benchmark.sh --model claude-haiku-4-5-20251001 --test-id mc-01
+#   bash benchmarks/scripts/run_benchmark.sh --dry-run
+#
+# From host (via docker exec):
+#   docker exec daaf-daaf-docker-1 bash /daaf/benchmarks/scripts/run_benchmark.sh --dry-run
+
+set -euo pipefail
+
+BASE_DIR="${DAAF_BASE_DIR:-/daaf}"
+
+# Ensure we are in the right directory
+cd "$BASE_DIR"
+
+# Clean sandbox before run
+bash "${BASE_DIR}/benchmarks/scripts/clean_sandbox.sh" "$BASE_DIR"
+
+# Run the benchmark harness
+python3 -m benchmarks.harness.runner --base-dir "$BASE_DIR" "$@"
diff --git a/docker-compose.yml b/docker-compose.yml
index 5535634..3028ecd 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -13,8 +13,13 @@ services:
 
   daaf-docker:
     build: .
+    env_file:                      # Requires Docker Compose v2.17+ (Docker Desktop 4.15+)
+      - path: environment_settings.txt
+        required: false         # Container starts normally if environment_settings.txt doesn't exist
     ports:
-      - "2718:2718"   # Marimo notebook server
+      - "127.0.0.1:2718:2718"   # Marimo notebook server (localhost only)
+      - "127.0.0.1:2719:2719"   # Session log viewer (localhost only)
+      - "127.0.0.1:2720:2720"   # code-server / VS Code in browser (localhost only)
     volumes:
       - daaf-data:/daaf        # Named volume instead of bind mount
     working_dir: /daaf
diff --git a/scripts/collect_session_logs.sh b/scripts/collect_session_logs.sh
index 16b7d18..d17b76a 100755
--- a/scripts/collect_session_logs.sh
+++ b/scripts/collect_session_logs.sh
@@ -9,6 +9,12 @@
 #   bash /daaf/scripts/collect_session_logs.sh /daaf/research/YYYY-MM-DD_Title
 #
 # Design:
+#   - Session-grouped matching: greps only orchestrator (*_orchestrator.jsonl)
+#     archives for the project BASENAME, then collects ALL archives from each
+#     matching session (orchestrator + subagents) via session-short ID glob.
+#     This ensures subagent transcripts are collected even if they don't
+#     individually mention the project directory (e.g., search-agent exploring
+#     framework files, source-researcher that never touches project paths).
 #   - Uses the project folder BASENAME as the search term (not the full path),
 #     so results are stable even if the repo root path changes.
 #   - Idempotent: skips files already present in the destination.
@@ -62,20 +68,26 @@ echo ""
 
 # --- Search for matching sessions ---
 
-# grep -l returns filenames of JSONL files containing the project folder name
-# Use || true to prevent set -e from exiting if grep finds no matches
-MATCHING_JSONL=()
-while IFS= read -r filepath; do
-    MATCHING_JSONL+=("$filepath")
-done < <(grep -rl --include="*.jsonl" "$PROJECT_BASENAME" "$SESSIONS_DIR" 2>/dev/null || true)
-
-if [ ${#MATCHING_JSONL[@]} -eq 0 ]; then
+# Search ONLY orchestrator transcripts for the project basename, then collect
+# all archives (orchestrator + subagents) from each matching session by
+# session-short ID.  This mirrors the session-grouped approach used by
+# archive-session.sh and recover-session-logs.sh, ensuring subagent transcripts
+# are collected even if they don't individually contain the project basename
+# (e.g., search-agent exploring framework files, source-researcher that never
+# touches project directories).
+MATCHING_SESSIONS=()
+while IFS= read -r orch_path; do
+    short=$(basename "$orch_path" | sed 's/.*_\([a-f0-9]\{8\}\)_orchestrator\.jsonl/\1/')
+    [[ "$short" =~ ^[a-f0-9]{8}$ ]] && MATCHING_SESSIONS+=("$short")
+done < <(grep -rl --include="*_orchestrator.jsonl" "$PROJECT_BASENAME" "$SESSIONS_DIR" 2>/dev/null || true)
+
+if [ ${#MATCHING_SESSIONS[@]} -eq 0 ]; then
     echo "No sessions found referencing '$PROJECT_BASENAME'."
     echo "This is expected if the project had no file operations yet (e.g., Phase 1 only)."
     exit 0
 fi
 
-echo "Found ${#MATCHING_JSONL[@]} session(s) referencing this project."
+echo "Found ${#MATCHING_SESSIONS[@]} session(s) referencing this project."
 echo ""
 
 # --- Copy matching sessions ---
@@ -86,34 +98,21 @@ COPIED=0
 SKIPPED=0
 TOTAL_SIZE=0
 
-for jsonl_path in "${MATCHING_JSONL[@]}"; do
-    filename="$(basename "$jsonl_path")"
-    md_filename="${filename%.jsonl}.md"
-    md_path="$(dirname "$jsonl_path")/$md_filename"
-
-    # Copy JSONL
-    if [ -f "$DEST_DIR/$filename" ]; then
-        SKIPPED=$((SKIPPED + 1))
-    else
-        cp "$jsonl_path" "$DEST_DIR/$filename"
-        COPIED=$((COPIED + 1))
-        if [ -f "$jsonl_path" ]; then
-            size=$(stat -c%s "$jsonl_path" 2>/dev/null || stat -f%z "$jsonl_path" 2>/dev/null || echo 0)
-            TOTAL_SIZE=$((TOTAL_SIZE + size))
-        fi
-    fi
+for session_short in "${MATCHING_SESSIONS[@]}"; do
+    # Glob all archives from this session (orchestrator + subagents, JSONL + MD)
+    for src in "$SESSIONS_DIR"/*_${session_short}_*.jsonl "$SESSIONS_DIR"/*_${session_short}_*.md; do
+        [ -f "$src" ] || continue
+        filename="$(basename "$src")"
 
-    # Copy corresponding MD (if it exists)
-    if [ -f "$md_path" ]; then
-        if [ ! -f "$DEST_DIR/$md_filename" ]; then
-            cp "$md_path" "$DEST_DIR/$md_filename"
+        if [ -f "$DEST_DIR/$filename" ]; then
+            SKIPPED=$((SKIPPED + 1))
+        else
+            cp "$src" "$DEST_DIR/$filename"
             COPIED=$((COPIED + 1))
-            size=$(stat -c%s "$md_path" 2>/dev/null || stat -f%z "$md_path" 2>/dev/null || echo 0)
+            size=$(stat -c%s "$src" 2>/dev/null || stat -f%z "$src" 2>/dev/null || echo 0)
             TOTAL_SIZE=$((TOTAL_SIZE + size))
-        else
-            SKIPPED=$((SKIPPED + 1))
         fi
-    fi
+    done
 done
 
 # --- Summary ---
@@ -128,7 +127,7 @@ else
 fi
 
 echo "--- Summary ---"
-echo "Sessions matched:  ${#MATCHING_JSONL[@]}"
+echo "Sessions matched:  ${#MATCHING_SESSIONS[@]}"
 echo "Files copied:      $COPIED"
 echo "Files skipped:     $SKIPPED (already present)"
 echo "Total size copied: $SIZE_HR"
diff --git a/scripts/discover_log_sources.sh b/scripts/discover_log_sources.sh
new file mode 100755
index 0000000..7557464
--- /dev/null
+++ b/scripts/discover_log_sources.sh
@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# discover_log_sources.sh — List available log sources for the Log Explorer
+#
+# Outputs one line per source in pipe-delimited format:
+#   ARCHIVE|<count>              (if archive has sessions)
+#   <project_path>|<count>       (for each project with logs)
+#
+# Called by view_logs.sh and view_logs.ps1 on the host via:
+#   docker compose exec -T daaf-docker bash /daaf/scripts/discover_log_sources.sh
+#
+# Exit codes:
+#   0 — always (empty output means no sources found)
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# Archive sessions
+archive_dir="$REPO_ROOT/.claude/logs/sessions"
+if [ -d "$archive_dir" ]; then
+    count=$(find "$archive_dir" -maxdepth 1 -name "*_orchestrator.jsonl" 2>/dev/null | wc -l)
+    count=$(echo "$count" | tr -d " ")
+    if [ "$count" -gt 0 ]; then
+        echo "ARCHIVE|$count"
+    fi
+fi
+
+# Project folders with logs
+for d in "$REPO_ROOT"/research/*/logs; do
+    [ -d "$d" ] || continue
+    count=$(find "$d" -maxdepth 1 -name "*_orchestrator.jsonl" 2>/dev/null | wc -l)
+    count=$(echo "$count" | tr -d " ")
+    if [ "$count" -gt 0 ]; then
+        echo "$(dirname "$d")|$count"
+    fi
+done
diff --git a/scripts/entrypoint.sh b/scripts/entrypoint.sh
deleted file mode 100755
index 703e61c..0000000
--- a/scripts/entrypoint.sh
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/bin/bash
-# Initialize git repo in the named volume if not already present.
-# Since users install from a zip/tarball (not git clone), there is no .git
-# directory by default. This creates a local-only repo for VS Code integration
-# and DAAF's internal script versioning. No remote is configured — developers
-# who need one can run: git remote add origin <url>
-if [ ! -d "/daaf/.git" ]; then
-    git init /daaf
-    git -C /daaf branch -m main
-    git -C /daaf config user.email "daaf@local"
-    git -C /daaf config user.name "DAAF Container"
-    git -C /daaf add -A
-    git -C /daaf commit -m "Initial commit: DAAF framework"
-fi
-
-exec "$@"
diff --git a/scripts/generate_log_viewer.py b/scripts/generate_log_viewer.py
new file mode 100755
index 0000000..b3b813b
--- /dev/null
+++ b/scripts/generate_log_viewer.py
@@ -0,0 +1,1339 @@
+#!/usr/bin/env python3
+"""
+generate_log_viewer.py — DAAF Session Log Manifest Builder
+
+Standalone CLI tool that parses DAAF session JSONL logs and produces a
+session_manifest.json for the HTML viewer.
+
+Usage:
+    python3 generate_log_viewer.py <project_path>
+    python3 generate_log_viewer.py --logs-dir <logs_directory>
+
+Arguments:
+    project_path: Absolute path to a DAAF research project
+                  (e.g., /daaf/research/2026-03-29_College_...)
+    --logs-dir:   Direct path to a directory containing JSONL files
+                  (e.g., /daaf/.claude/logs/sessions for archive mode)
+
+Output:
+    {logs_dir}/session_manifest.json
+"""
+
+import argparse
+import json
+import os
+import sys
+from datetime import datetime, timezone
+from glob import glob
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+DAAF_ROOT = "/daaf/"
+
+SKIP_RECORD_TYPES = {"file-history-snapshot", "queue-operation"}
+
+TOOL_CATEGORY_MAP = {
+    "Read": "read",
+    "Write": "write",
+    "Edit": "write",
+    "Bash": "execute",
+    "Glob": "read",
+    "Grep": "read",
+    "Skill": "skill",
+    "Agent": "delegate",
+    "WebSearch": "search",
+    "WebFetch": "search",
+    "TaskCreate": "track",
+    "TaskUpdate": "track",
+    "NotebookEdit": "write",
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def strip_daaf_prefix(path):
+    """Strip /daaf/ prefix to make paths relative to DAAF root."""
+    if path and path.startswith(DAAF_ROOT):
+        return path[len(DAAF_ROOT):]
+    return path
+
+
+def safe_json_loads(line, line_num, filepath):
+    """Parse a JSON line, returning None on failure."""
+    line = line.strip()
+    if not line:
+        return None
+    try:
+        return json.loads(line)
+    except json.JSONDecodeError:
+        print(f"  WARNING: Malformed JSON at line {line_num} in {os.path.basename(filepath)}, skipping")
+        return None
+
+
+def iso_timestamp():
+    """Return current UTC time in ISO 8601 format."""
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%S.%f")[:-3] + "Z"
+
+
+def duration_between(start_iso, end_iso):
+    """Compute seconds between two ISO timestamps. Returns 0.0 on error."""
+    try:
+        fmt_options = [
+            "%Y-%m-%dT%H:%M:%S.%fZ",
+            "%Y-%m-%dT%H:%M:%S.%f",
+            "%Y-%m-%dT%H:%M:%SZ",
+            "%Y-%m-%dT%H:%M:%S",
+        ]
+        t_start = None
+        t_end = None
+        for fmt in fmt_options:
+            if t_start is None:
+                try:
+                    t_start = datetime.strptime(start_iso, fmt)
+                except ValueError:
+                    pass
+            if t_end is None:
+                try:
+                    t_end = datetime.strptime(end_iso, fmt)
+                except ValueError:
+                    pass
+        if t_start and t_end:
+            return round((t_end - t_start).total_seconds(), 1)
+    except Exception:
+        pass
+    return 0.0
+
+
+def truncate(text, max_len):
+    """Truncate text to max_len characters with ellipsis."""
+    if not text:
+        return ""
+    if len(text) <= max_len:
+        return text
+    return text[:max_len - 3] + "..."
+
+
+def extract_bash_file_paths(command):
+    """Extract file paths from a Bash command string."""
+    import re
+    paths = []
+    # Match absolute paths (starting with /)
+    for match in re.finditer(r'(?:^|\s)(/\S+)', command):
+        p = match.group(1).rstrip(';,|&)')
+        # Skip common non-file arguments
+        if p in ('/', '/dev/null') or p.startswith('/proc/') or p.startswith('/sys/'):
+            continue
+        # Must look like a real file path (has at least one directory separator beyond root)
+        if '/' in p[1:]:
+            paths.append(strip_daaf_prefix(p))
+    return paths
+
+
+def tool_description(tool_name, tool_input):
+    """Build human-readable description for a tool call."""
+    inp = tool_input or {}
+
+    if tool_name == "Read":
+        path = strip_daaf_prefix(inp.get('file_path', ''))
+        desc = f"Read {path}"
+        offset = inp.get('offset')
+        limit = inp.get('limit')
+        if offset and limit:
+            end_line = offset + limit - 1
+            desc += f" (lines {offset}-{end_line})"
+        elif offset:
+            desc += f" (from line {offset})"
+        elif limit:
+            desc += f" (first {limit} lines)"
+        return desc
+    elif tool_name == "Write":
+        path = strip_daaf_prefix(inp.get('file_path', ''))
+        return f"Wrote {path}"
+    elif tool_name == "Edit":
+        path = strip_daaf_prefix(inp.get('file_path', ''))
+        return f"Edited {path}"
+    elif tool_name == "Bash":
+        cmd = inp.get("command", "")
+        desc = inp.get("description", "")
+        if desc:
+            return f"Ran command: {desc}"
+        return f"Ran: {cmd}"
+    elif tool_name == "Glob":
+        pattern = inp.get('pattern', '')
+        path = inp.get('path', '')
+        desc = f"Searched for files matching {pattern}"
+        if path:
+            desc += f" in {strip_daaf_prefix(path)}"
+        return desc
+    elif tool_name == "Grep":
+        pattern = inp.get('pattern', '')
+        desc = f"Searched file contents for '{pattern}'"
+        if inp.get("path"):
+            desc += f" in {strip_daaf_prefix(inp['path'])}"
+        mode = inp.get("output_mode", "")
+        if mode == "content":
+            desc += " (showing matches)"
+        elif mode == "count":
+            desc += " (counting matches)"
+        return desc
+    elif tool_name == "Skill":
+        skill_name = inp.get('skill', '')
+        return f"Loaded skill: {skill_name}"
+    elif tool_name == "Agent":
+        agent_type = inp.get("subagent_type", "agent")
+        description = inp.get("description", "")
+        return f"Dispatched {agent_type} specialist: {description}"
+    elif tool_name == "WebSearch":
+        return f"Web search: '{inp.get('query', '')}'"
+    elif tool_name == "WebFetch":
+        return f"Fetched URL: {inp.get('url', '')}"
+    elif tool_name == "TaskCreate":
+        return f"Created task: {inp.get('subject', '')}"
+    elif tool_name == "TaskUpdate":
+        return f"Updated task #{inp.get('taskId', '')}"
+    elif tool_name == "NotebookEdit":
+        return "Edited notebook cell"
+    else:
+        return f"Tool: {tool_name}"
+
+
+def tool_target(tool_name, tool_input):
+    """Extract file path target from a tool call, if applicable."""
+    inp = tool_input or {}
+    if tool_name in ("Read", "Write", "Edit"):
+        return strip_daaf_prefix(inp.get("file_path", ""))
+    elif tool_name == "Glob":
+        return inp.get("pattern", "")
+    elif tool_name == "Grep":
+        p = inp.get("path")
+        if p:
+            return strip_daaf_prefix(p)
+    elif tool_name == "Skill":
+        skill_name = inp.get("skill", "")
+        if skill_name:
+            return f".claude/skills/{skill_name}/SKILL.md"
+    elif tool_name == "Bash":
+        paths = extract_bash_file_paths(inp.get("command", ""))
+        if paths:
+            return paths[0]
+    return None
+
+
+def tool_extra_targets(tool_name, tool_input):
+    """Extract additional file path targets beyond the primary one (e.g., multiple paths in Bash)."""
+    inp = tool_input or {}
+    if tool_name == "Bash":
+        paths = extract_bash_file_paths(inp.get("command", ""))
+        if len(paths) > 1:
+            return paths[1:]
+    return []
+
+
+def tool_category(tool_name):
+    """Map tool name to activity type category."""
+    return TOOL_CATEGORY_MAP.get(tool_name, "other")
+
+
+def extract_text_from_content(content):
+    """Extract concatenated text from a content array or string."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict):
+                if block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+            elif isinstance(block, str):
+                parts.append(block)
+        return "\n".join(parts)
+    return ""
+
+
+def extract_user_text(content):
+    """Extract user-visible text from content, skipping tool results."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, dict):
+                if block.get("type") == "text":
+                    parts.append(block.get("text", ""))
+        return "\n".join(parts)
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Agent Frontmatter Parsing
+# ---------------------------------------------------------------------------
+
+
+def extract_agent_frontmatter_skills(agent_type):
+    """Extract skills list from an agent definition file's YAML frontmatter."""
+    if not agent_type:
+        return []
+    agent_file = os.path.join(DAAF_ROOT, ".claude", "agents", f"{agent_type}.md")
+    if not os.path.exists(agent_file):
+        return []
+    try:
+        import yaml
+        with open(agent_file, "r", encoding="utf-8") as f:
+            content = f.read(4096)
+        if not content.startswith("---"):
+            return []
+        end_idx = content.index("---", 3)
+        frontmatter = content[3:end_idx]
+        parsed = yaml.safe_load(frontmatter)
+        if not isinstance(parsed, dict):
+            return []
+        skills = parsed.get("skills")
+        if skills is None:
+            return []
+        if isinstance(skills, str):
+            return [skills]
+        if isinstance(skills, list):
+            return [str(s) for s in skills if s]
+        return []
+    except Exception:
+        return []
+
+
+# ---------------------------------------------------------------------------
+# JSONL Loading
+# ---------------------------------------------------------------------------
+
+
+def load_jsonl(filepath):
+    """Load a JSONL file, returning list of (line_number, record) tuples."""
+    records = []
+    try:
+        with open(filepath, "r", encoding="utf-8", errors="replace") as f:
+            for i, line in enumerate(f, start=1):
+                rec = safe_json_loads(line, i, filepath)
+                if rec is not None:
+                    rec["_line"] = i
+                    rec["_file"] = filepath
+                    records.append((i, rec))
+    except Exception as e:
+        print(f"  WARNING: Could not read {filepath}: {e}")
+    return records
+
+
+# ---------------------------------------------------------------------------
+# Session Grouping
+# ---------------------------------------------------------------------------
+
+
+def group_files_by_session(logs_dir):
+    """
+    Group JSONL files by session prefix.
+    Returns dict: session_prefix -> {"orchestrator": path, "subagents": {agent_short_id: path}}
+    """
+    jsonl_files = sorted(glob(os.path.join(logs_dir, "*.jsonl")))
+    sessions = {}
+
+    for fpath in jsonl_files:
+        fname = os.path.basename(fpath)
+        # Expected patterns:
+        #   {date}_{time}_{sessionShort}_orchestrator.jsonl
+        #   {date}_{time}_{sessionShort}_subagent_{agentShortId}.jsonl
+        parts = fname.replace(".jsonl", "").split("_")
+
+        # Find the session prefix: date_time_sessionShort
+        # Format: YYYY-MM-DD_HH-MM-SS_XXXXXXXX
+        if len(parts) < 4:
+            continue
+
+        # date = parts[0], time = parts[1], sessionShort = parts[2]
+        session_prefix = f"{parts[0]}_{parts[1]}_{parts[2]}"
+
+        if session_prefix not in sessions:
+            sessions[session_prefix] = {"orchestrator": None, "subagents": {}}
+
+        if "orchestrator" in fname:
+            sessions[session_prefix]["orchestrator"] = fpath
+        elif "subagent" in fname:
+            # Extract agent short ID (the part after "subagent_")
+            subagent_idx = fname.index("subagent_") + len("subagent_")
+            agent_short = fname[subagent_idx:].replace(".jsonl", "")
+            sessions[session_prefix]["subagents"][agent_short] = fpath
+
+    return sessions
+
+
+# ---------------------------------------------------------------------------
+# Streaming Chunk Merging
+# ---------------------------------------------------------------------------
+
+
+def merge_streaming_chunks(records):
+    """
+    Merge consecutive assistant records sharing the same message.id.
+
+    Returns a new list of (line_number, record) tuples with merged content.
+    Non-assistant records pass through unchanged.
+    """
+    merged = []
+    i = 0
+    while i < len(records):
+        line_num, rec = records[i]
+        msg = rec.get("message", {})
+
+        # Only merge assistant records with a message.id
+        if rec.get("type") != "assistant" or not msg.get("id"):
+            merged.append((line_num, rec))
+            i += 1
+            continue
+
+        msg_id = msg["id"]
+        chunk_group = [(line_num, rec)]
+
+        # Collect consecutive assistant records with the same message.id
+        j = i + 1
+        while j < len(records):
+            next_line, next_rec = records[j]
+            next_msg = next_rec.get("message", {})
+            if next_rec.get("type") == "assistant" and next_msg.get("id") == msg_id:
+                chunk_group.append((next_line, next_rec))
+                j += 1
+            else:
+                break
+
+        if len(chunk_group) == 1:
+            # No merging needed
+            merged.append((line_num, rec))
+            i += 1
+            continue
+
+        # Merge the chunks
+        first_line, first_rec = chunk_group[0]
+        last_line, last_rec = chunk_group[-1]
+
+        # Build merged content by deduplicating blocks
+        seen_tool_ids = set()
+        seen_text_hashes = set()
+        merged_content = []
+
+        for _, chunk_rec in chunk_group:
+            chunk_content = chunk_rec.get("message", {}).get("content", [])
+            if isinstance(chunk_content, list):
+                for block in chunk_content:
+                    if not isinstance(block, dict):
+                        continue
+                    btype = block.get("type")
+
+                    if btype == "tool_use":
+                        # Deduplicate by tool_use id
+                        tid = block.get("id")
+                        if tid and tid in seen_tool_ids:
+                            continue
+                        if tid:
+                            seen_tool_ids.add(tid)
+                        merged_content.append(block)
+
+                    elif btype == "thinking":
+                        # Keep last thinking block (later chunks supersede)
+                        # Use signature as dedup key if present, otherwise hash
+                        sig = block.get("signature", "")
+                        key = f"thinking:{sig}" if sig else f"thinking:{hash(block.get('thinking', '')[:200])}"
+                        if key not in seen_text_hashes:
+                            seen_text_hashes.add(key)
+                            merged_content.append(block)
+
+                    elif btype == "text":
+                        # Later text blocks may contain earlier text plus more.
+                        # Keep only the last (longest) text block.
+                        txt = block.get("text", "")
+                        # Replace any earlier text blocks with this one
+                        # by tracking and updating
+                        merged_content = [
+                            b for b in merged_content
+                            if b.get("type") != "text" or b.get("text", "") not in txt
+                        ]
+                        merged_content.append(block)
+                    else:
+                        merged_content.append(block)
+
+        # Find usage from the chunk with stop_reason != null
+        final_usage = None
+        final_stop_reason = None
+        for _, chunk_rec in chunk_group:
+            chunk_msg = chunk_rec.get("message", {})
+            sr = chunk_msg.get("stop_reason")
+            if sr is not None:
+                final_usage = chunk_msg.get("usage")
+                final_stop_reason = sr
+
+        # Collect all UUIDs from merged chunks for cross-reference linking
+        all_uuids = set()
+        for _, chunk_rec in chunk_group:
+            uid = chunk_rec.get("uuid")
+            if uid:
+                all_uuids.add(uid)
+
+        # Build merged record
+        merged_rec = dict(first_rec)
+        merged_rec["message"] = dict(first_rec.get("message", {}))
+        merged_rec["message"]["content"] = merged_content
+        if final_usage:
+            merged_rec["message"]["usage"] = final_usage
+        if final_stop_reason:
+            merged_rec["message"]["stop_reason"] = final_stop_reason
+        merged_rec["_line"] = first_line
+        merged_rec["_line_end"] = last_line
+        merged_rec["_end_timestamp"] = last_rec.get("timestamp", first_rec.get("timestamp"))
+        merged_rec["_file"] = first_rec.get("_file")
+        merged_rec["_all_uuids"] = all_uuids
+
+        merged.append((first_line, merged_rec))
+        i = j
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Activity Extraction
+# ---------------------------------------------------------------------------
+
+
+def extract_activities_from_content(content, line_num):
+    """Extract activity entries from a message content array."""
+    activities = []
+    if not isinstance(content, list):
+        return activities
+
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+
+        btype = block.get("type")
+
+        if btype == "text":
+            text = block.get("text", "").strip()
+            if text:
+                activities.append({
+                    "type": "text",
+                    "tool": None,
+                    "description": text,
+                    "target": None,
+                    "line": line_num,
+                    "resultLine": None,
+                    "error": None,
+                })
+
+        elif btype == "thinking":
+            thinking_text = block.get("thinking", "").strip()
+            if thinking_text:
+                activities.append({
+                    "type": "thinking",
+                    "tool": None,
+                    "description": thinking_text,
+                    "target": None,
+                    "line": line_num,
+                    "resultLine": None,
+                    "error": None,
+                })
+
+        elif btype == "tool_use":
+            tname = block.get("name", "Unknown")
+            tinput = block.get("input", {})
+            cat = tool_category(tname)
+            desc = tool_description(tname, tinput)
+            target = tool_target(tname, tinput)
+
+            extras = tool_extra_targets(tname, tinput)
+
+            activity = {
+                "type": cat,
+                "tool": tname,
+                "description": desc,
+                "target": target,
+                "extraTargets": extras if extras else None,
+                "line": line_num,
+                "resultLine": None,
+                "error": None,
+                "_tool_use_id": block.get("id"),
+            }
+
+            # For Agent tool calls, add subagent metadata
+            if tname == "Agent":
+                activity["subagentType"] = tinput.get("subagent_type", "")
+                activity["subagentDescription"] = tinput.get("description", "")
+
+            activities.append(activity)
+
+    return activities
+
+
+def extract_activities_from_tool_results(content, line_num, tool_result_meta):
+    """
+    Extract tool result information from user records containing tool_result blocks.
+    Returns a list of dicts with tool_use_id -> result info for back-patching.
+    """
+    results = []
+    if not isinstance(content, list):
+        return results
+
+    for block in content:
+        if not isinstance(block, dict):
+            continue
+        if block.get("type") == "tool_result":
+            tool_use_id = block.get("tool_use_id")
+            is_error = block.get("is_error", False)
+            results.append({
+                "tool_use_id": tool_use_id,
+                "line": line_num,
+                "error": is_error,
+            })
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Block Building
+# ---------------------------------------------------------------------------
+
+
+def build_blocks(records, session_idx, file_rel):
+    """
+    Build the blocks array from merged orchestrator records.
+
+    Returns (blocks, agent_dispatches) where agent_dispatches maps
+    tool_use_id -> dispatch info for linking subagents.
+    """
+    blocks = []
+    agent_dispatches = {}  # tool_use_id -> {agentId, agentType, description, blockId, line}
+    block_counter = 0
+
+    # Index for back-patching tool result lines
+    # tool_use_id -> {resultLine, error}
+    tool_result_index = {}
+
+    # First pass: collect all tool result locations
+    for line_num, rec in records:
+        rtype = rec.get("type")
+        if rtype == "user":
+            content = rec.get("message", {}).get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_result":
+                        tuid = block.get("tool_use_id")
+                        if tuid:
+                            # Extract tool result content for search display
+                            result_content = ""
+                            raw_content = block.get("content", "")
+                            if isinstance(raw_content, str):
+                                result_content = raw_content
+                            elif isinstance(raw_content, list):
+                                rc_parts = []
+                                for rc_block in raw_content:
+                                    if isinstance(rc_block, dict) and rc_block.get("type") == "text":
+                                        rc_parts.append(rc_block.get("text", ""))
+                                    elif isinstance(rc_block, str):
+                                        rc_parts.append(rc_block)
+                                result_content = "\n".join(rc_parts)
+                            tool_result_index[tuid] = {
+                                "resultLine": line_num,
+                                "error": block.get("is_error", False),
+                                "content": result_content,
+                            }
+
+            # Also check for Agent tool results
+            tur = rec.get("toolUseResult", {})
+            if isinstance(tur, dict) and tur.get("agentId"):
+                # This is an Agent return — store subagent metadata
+                tool_result_index[f"_agent_{tur['agentId']}"] = {
+                    "resultLine": line_num,
+                    "status": tur.get("status"),
+                    "totalDurationMs": tur.get("totalDurationMs"),
+                    "totalTokens": tur.get("totalTokens"),
+                    "totalToolUseCount": tur.get("totalToolUseCount"),
+                    "agentType": tur.get("agentType", ""),
+                    "prompt": tur.get("prompt", ""),
+                }
+
+    # Second pass: build blocks
+    for line_num, rec in records:
+        rtype = rec.get("type")
+
+        if rtype in SKIP_RECORD_TYPES:
+            continue
+        if rtype == "system":
+            continue
+
+        # Skip isMeta user records
+        if rtype == "user" and rec.get("isMeta"):
+            continue
+
+        # Skip user records that are pure tool results (no user text)
+        if rtype == "user":
+            content = rec.get("message", {}).get("content", [])
+            if isinstance(content, list):
+                has_text = any(
+                    isinstance(b, dict) and b.get("type") == "text"
+                    for b in content
+                )
+                has_tool_result = any(
+                    isinstance(b, dict) and b.get("type") == "tool_result"
+                    for b in content
+                )
+                if has_tool_result and not has_text:
+                    continue
+            elif isinstance(content, str) and not content.strip():
+                continue
+
+        msg = rec.get("message", {})
+        timestamp = rec.get("timestamp", "")
+        end_timestamp = rec.get("_end_timestamp", timestamp)
+        line_end = rec.get("_line_end", line_num)
+
+        block_counter += 1
+        block_id = f"s{session_idx}_b{block_counter:03d}"
+
+        if rtype == "user":
+            content = msg.get("content", "")
+            summary = extract_user_text(content)
+
+            blocks.append({
+                "id": block_id,
+                "type": "user",
+                "startTime": timestamp,
+                "endTime": end_timestamp,
+                "durationSec": duration_between(timestamp, end_timestamp),
+                "lineStart": line_num,
+                "lineEnd": line_end,
+                "file": file_rel,
+                "summary": summary,
+                "activities": [],
+            })
+
+        elif rtype == "assistant":
+            content = msg.get("content", [])
+            activities = extract_activities_from_content(content, line_num)
+
+            # Back-patch tool result lines and errors
+            for act in activities:
+                if act["tool"] and act["tool"] != "Agent":
+                    # Match by tool_use_id for precise linking
+                    tuid = act.get("_tool_use_id")
+                    if tuid and tuid in tool_result_index:
+                        tri = tool_result_index[tuid]
+                        act["resultLine"] = tri["resultLine"]
+                        act["error"] = tri.get("error", False)
+                        # Capture search result content for display
+                        if act["tool"] in ("Glob", "Grep") and tri.get("content"):
+                            act["resultContent"] = truncate(tri["content"], 3000)
+
+                elif act["tool"] == "Agent":
+                    # Use the activity's own tool_use_id for precise matching
+                    tuid = act.get("_tool_use_id")
+                    if tuid and tuid in tool_result_index:
+                        tri = tool_result_index[tuid]
+                        act["resultLine"] = tri["resultLine"]
+                        act["error"] = tri.get("error", False)
+
+            # Collect Agent dispatches for subagent linking
+            for block_item in (content if isinstance(content, list) else []):
+                if (isinstance(block_item, dict)
+                        and block_item.get("type") == "tool_use"
+                        and block_item.get("name") == "Agent"):
+                    tuid = block_item.get("id")
+                    tinput = block_item.get("input", {})
+                    agent_dispatches[tuid] = {
+                        "description": tinput.get("description", ""),
+                        "agentType": tinput.get("subagent_type", ""),
+                        "blockId": block_id,
+                        "line": line_num,
+                    }
+
+            # Build summary from activities
+            summary = build_assistant_summary(activities)
+
+            # Extract token usage
+            usage = msg.get("usage", {})
+            token_usage = None
+            if usage:
+                token_usage = {
+                    "input": usage.get("input_tokens", 0),
+                    "output": usage.get("output_tokens", 0),
+                    "cacheRead": usage.get("cache_read_input_tokens", 0),
+                    "cacheWrite": usage.get("cache_creation_input_tokens", 0),
+                }
+
+            block_data = {
+                "id": block_id,
+                "type": "assistant",
+                "startTime": timestamp,
+                "endTime": end_timestamp,
+                "durationSec": duration_between(timestamp, end_timestamp),
+                "lineStart": line_num,
+                "lineEnd": line_end,
+                "file": file_rel,
+                "summary": summary,
+                "activities": activities,
+            }
+            if token_usage:
+                block_data["tokenUsage"] = token_usage
+
+            blocks.append(block_data)
+
+    return blocks, agent_dispatches
+
+
+def build_assistant_summary(activities):
+    """Auto-generate summary from activities list."""
+    counts = {}
+    for act in activities:
+        atype = act.get("type", "other")
+        tool = act.get("tool")
+
+        if atype in ("text", "thinking"):
+            continue  # Don't count text/thinking blocks in summary
+
+        if tool == "Read":
+            counts["read"] = counts.get("read", 0) + 1
+        elif tool in ("Write", "Edit", "NotebookEdit"):
+            counts["wrote"] = counts.get("wrote", 0) + 1
+        elif tool == "Bash":
+            counts["ran"] = counts.get("ran", 0) + 1
+        elif tool == "Agent":
+            counts["dispatched"] = counts.get("dispatched", 0) + 1
+        elif tool == "Skill":
+            counts["loaded skill"] = counts.get("loaded skill", 0) + 1
+        elif tool in ("Glob", "Grep"):
+            counts["searched"] = counts.get("searched", 0) + 1
+        elif tool in ("WebSearch", "WebFetch"):
+            counts["web"] = counts.get("web", 0) + 1
+        elif tool in ("TaskCreate", "TaskUpdate"):
+            counts["task"] = counts.get("task", 0) + 1
+        else:
+            counts["other"] = counts.get("other", 0) + 1
+
+    if not counts:
+        # Fallback: use first text activity
+        for act in activities:
+            if act.get("type") == "text":
+                return act.get("description", "")
+        return ""
+
+    parts = []
+    label_map = {
+        "read": ("Read {} file", "Read {} files"),
+        "wrote": ("Wrote {} file", "Wrote {} files"),
+        "ran": ("Ran {} command", "Ran {} commands"),
+        "dispatched": ("Dispatched {} agent", "Dispatched {} agents"),
+        "loaded skill": ("Loaded {} skill", "Loaded {} skills"),
+        "searched": ("{} search", "{} searches"),
+        "web": ("{} web request", "{} web requests"),
+        "task": ("{} task update", "{} task updates"),
+        "other": ("{} other action", "{} other actions"),
+    }
+
+    for key in ["read", "wrote", "ran", "dispatched", "loaded skill", "searched", "web", "task", "other"]:
+        if key in counts:
+            n = counts[key]
+            singular, plural = label_map[key]
+            parts.append((singular if n == 1 else plural).format(n))
+
+    return ", ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Subagent Processing
+# ---------------------------------------------------------------------------
+
+
+def process_subagent_file(filepath, file_rel, agent_short_id, orchestrator_dispatches,
+                          orchestrator_file_rel):
+    """
+    Process a subagent JSONL file. Returns a subagent dict for the manifest,
+    or None if the file is empty/invalid.
+    """
+    raw_records = load_jsonl(filepath)
+    if not raw_records:
+        return None
+
+    records = merge_streaming_chunks(raw_records)
+
+    # Extract metadata from first record
+    first_line, first_rec = records[0]
+    agent_full_id = first_rec.get("agentId", "")
+    start_time = first_rec.get("timestamp", "")
+
+    # Find the last assistant record (the final report)
+    last_assistant_line = None
+    last_assistant_rec = None
+    end_time = start_time
+    for line_num, rec in reversed(records):
+        if rec.get("timestamp"):
+            end_time = rec["timestamp"]
+            break
+
+    for line_num, rec in reversed(records):
+        if rec.get("type") == "assistant":
+            msg = rec.get("message", {})
+            if msg.get("stop_reason") == "end_turn":
+                last_assistant_line = line_num
+                last_assistant_rec = rec
+                break
+
+    # Extract the dispatch prompt (first user record content) — full text, no truncation
+    prompt_preview = ""
+    if first_rec.get("type") == "user":
+        content = first_rec.get("message", {}).get("content", "")
+        prompt_text = extract_text_from_content(content)
+        prompt_preview = prompt_text
+
+    # Extract final report text — full text, no truncation
+    report_preview = ""
+    report_subagent_line = None
+    if last_assistant_rec:
+        content = last_assistant_rec.get("message", {}).get("content", [])
+        report_text = extract_text_from_content(content)
+        report_preview = report_text
+        report_subagent_line = last_assistant_line or None
+
+    # Build tool result index for subagent (mirrors build_blocks logic)
+    sa_tool_result_index = {}
+    for line_num, rec in records:
+        if rec.get("type") != "user":
+            continue
+        content = rec.get("message", {}).get("content", [])
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "tool_result":
+                tuid = block.get("tool_use_id")
+                if not tuid:
+                    continue
+                result_content = ""
+                raw_content = block.get("content", "")
+                if isinstance(raw_content, str):
+                    result_content = raw_content
+                elif isinstance(raw_content, list):
+                    rc_parts = []
+                    for rc_block in raw_content:
+                        if isinstance(rc_block, dict) and rc_block.get("type") == "text":
+                            rc_parts.append(rc_block.get("text", ""))
+                        elif isinstance(rc_block, str):
+                            rc_parts.append(rc_block)
+                    result_content = "\n".join(rc_parts)
+                sa_tool_result_index[tuid] = {
+                    "resultLine": line_num,
+                    "error": block.get("is_error", False),
+                    "content": result_content,
+                }
+
+    # Build activities for subagent
+    subagent_activities = []
+    for line_num, rec in records:
+        if rec.get("type") == "assistant":
+            content = rec.get("message", {}).get("content", [])
+            acts = extract_activities_from_content(content, line_num)
+            # Back-patch tool result lines and search content
+            for act in acts:
+                tuid = act.get("_tool_use_id")
+                if tuid and tuid in sa_tool_result_index:
+                    tri = sa_tool_result_index[tuid]
+                    act["resultLine"] = tri["resultLine"]
+                    act["error"] = tri.get("error", False)
+                    if act.get("tool") in ("Glob", "Grep") and tri.get("content"):
+                        act["resultContent"] = truncate(tri["content"], 3000)
+            subagent_activities.extend(acts)
+
+    # Calculate totals from records
+    total_tool_uses = 0
+    total_tokens = 0
+    for line_num, rec in records:
+        if rec.get("type") == "assistant":
+            content = rec.get("message", {}).get("content", [])
+            if isinstance(content, list):
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "tool_use":
+                        total_tool_uses += 1
+            usage = rec.get("message", {}).get("usage", {})
+            if usage:
+                total_tokens += usage.get("input_tokens", 0) + usage.get("output_tokens", 0)
+                total_tokens += usage.get("cache_read_input_tokens", 0)
+                total_tokens += usage.get("cache_creation_input_tokens", 0)
+
+    # Determine agentType from first record context or dispatch
+    agent_type = ""
+    label = ""
+
+    subagent_data = {
+        "id": agent_short_id,
+        "fullId": agent_full_id,
+        "agentType": agent_type,
+        "label": label,
+        "file": file_rel,
+        "parentBlockId": None,
+        "startTime": start_time,
+        "endTime": end_time,
+        "durationMs": int(duration_between(start_time, end_time) * 1000),
+        "tokens": total_tokens,
+        "toolUseCount": total_tool_uses,
+        "invocation": {
+            "promptPreview": prompt_preview,
+            "orchestratorFile": orchestrator_file_rel,
+            "orchestratorLine": None,
+            "subagentFile": file_rel,
+            "subagentLine": first_line,
+        },
+        "report": {
+            "summaryPreview": report_preview,
+            "orchestratorFile": orchestrator_file_rel,
+            "orchestratorLine": None,
+            "subagentFile": file_rel,
+            "subagentLine": report_subagent_line,
+        },
+        "activities": subagent_activities,
+    }
+
+    return subagent_data
+
+
+def link_subagents_to_dispatches(subagents, agent_dispatches, orch_records, orch_file_rel):
+    """
+    Link subagent entries to their orchestrator dispatch points using
+    the toolUseResult.agentId field in orchestrator user records.
+    """
+    # Build map: agentId (full or short) -> dispatch info from tool results
+    agent_result_map = {}  # agentId -> {tool_use_id, line, agentType, ...}
+
+    for line_num, rec in orch_records:
+        if rec.get("type") != "user":
+            continue
+        tur = rec.get("toolUseResult", {})
+        if not isinstance(tur, dict):
+            continue
+        aid = tur.get("agentId", "")
+        if aid:
+            source_tool_uuid = rec.get("sourceToolAssistantUUID", "")
+            # Extract tool_use_id from the tool_result block for precise dispatch matching
+            tool_use_id = None
+            content = rec.get("message", {}).get("content", [])
+            if isinstance(content, list):
+                for cblock in content:
+                    if isinstance(cblock, dict) and cblock.get("type") == "tool_result":
+                        tool_use_id = cblock.get("tool_use_id")
+                        break
+            agent_result_map[aid] = {
+                "line": line_num,
+                "agentType": tur.get("agentType", ""),
+                "totalDurationMs": tur.get("totalDurationMs"),
+                "totalTokens": tur.get("totalTokens"),
+                "totalToolUseCount": tur.get("totalToolUseCount"),
+                "prompt": tur.get("prompt", ""),
+                "sourceToolAssistantUUID": source_tool_uuid,
+                "tool_use_id": tool_use_id,
+            }
+
+    # Also build a map from sourceToolAssistantUUID -> dispatch info
+    # by finding which assistant record contained the Agent tool_use.
+    # After streaming chunk merging, a merged record may have multiple UUIDs
+    # stored in _all_uuids. The sourceToolAssistantUUID on the result record
+    # may reference ANY of those chunk UUIDs, so we index all of them.
+    uuid_to_dispatch = {}
+    for line_num, rec in orch_records:
+        if rec.get("type") != "assistant":
+            continue
+        content = rec.get("message", {}).get("content", [])
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if (isinstance(block, dict)
+                    and block.get("type") == "tool_use"
+                    and block.get("name") == "Agent"):
+                tuid = block.get("id")
+                tinput = block.get("input", {})
+                dispatch_entry = {
+                    "tool_use_id": tuid,
+                    "description": tinput.get("description", ""),
+                    "agentType": tinput.get("subagent_type", ""),
+                    "line": line_num,
+                }
+                # Index by primary UUID
+                rec_uuid = rec.get("uuid", "")
+                if rec_uuid:
+                    uuid_to_dispatch[rec_uuid] = dispatch_entry
+                # Also index by all merged chunk UUIDs
+                for uid in rec.get("_all_uuids", set()):
+                    uuid_to_dispatch[uid] = dispatch_entry
+
+    # Now link each subagent
+    for sa in subagents:
+        full_id = sa.get("fullId", "")
+        short_id = sa.get("id", "")
+
+        # Look up agent result by full ID
+        result_info = agent_result_map.get(full_id)
+        if result_info:
+            sa["report"]["orchestratorLine"] = result_info["line"]
+
+            # Use metadata from the result to enrich
+            if result_info.get("totalDurationMs"):
+                sa["durationMs"] = result_info["totalDurationMs"]
+            if result_info.get("totalTokens"):
+                sa["tokens"] = result_info["totalTokens"]
+            if result_info.get("totalToolUseCount"):
+                sa["toolUseCount"] = result_info["totalToolUseCount"]
+            if result_info.get("agentType"):
+                sa["agentType"] = result_info["agentType"]
+
+            # Match dispatch by tool_use_id first (precise), then UUID (fallback)
+            dispatch = None
+            tuid = result_info.get("tool_use_id")
+            if tuid and tuid in agent_dispatches:
+                dispatch = agent_dispatches[tuid]
+            else:
+                source_uuid = result_info.get("sourceToolAssistantUUID", "")
+                if source_uuid and source_uuid in uuid_to_dispatch:
+                    dispatch = uuid_to_dispatch[source_uuid]
+            if dispatch:
+                sa["invocation"]["orchestratorLine"] = dispatch["line"]
+                if not sa["agentType"]:
+                    sa["agentType"] = dispatch.get("agentType", "")
+                sa["label"] = dispatch.get("description", "")
+
+                # Find parent block
+                for tuid, dinfo in agent_dispatches.items():
+                    if dinfo.get("line") == dispatch["line"]:
+                        sa["parentBlockId"] = dinfo.get("blockId")
+                        break
+
+        # If we still don't have a label, try to extract from prompt
+        if not sa["label"] and sa["invocation"]["promptPreview"]:
+            # Use first line of prompt as label
+            first_line_text = sa["invocation"]["promptPreview"].split("\n")[0]
+            sa["label"] = first_line_text
+
+
+# ---------------------------------------------------------------------------
+# Session Processing
+# ---------------------------------------------------------------------------
+
+
+def process_session(session_idx, session_prefix, session_files):
+    """Process a single session (orchestrator + subagents). Returns a session dict."""
+    orch_path = session_files["orchestrator"]
+    if not orch_path or not os.path.exists(orch_path):
+        print(f"  WARNING: No orchestrator file for session {session_prefix}, skipping")
+        return None
+
+    orch_file_rel = strip_daaf_prefix(orch_path)
+    print(f"  Processing session: {os.path.basename(orch_path)}")
+
+    # Load and merge orchestrator records
+    raw_records = load_jsonl(orch_path)
+    if not raw_records:
+        print(f"    No records found in orchestrator file")
+        return None
+
+    records = merge_streaming_chunks(raw_records)
+
+    # Extract DAAF version from companion .md file
+    daaf_version = ""
+    md_path = orch_path.replace(".jsonl", ".md")
+    if os.path.exists(md_path):
+        try:
+            with open(md_path, "r", encoding="utf-8", errors="replace") as f:
+                for md_line in f:
+                    if md_line.startswith("**DAAF Version:**"):
+                        daaf_version = md_line.split("**DAAF Version:**")[1].strip()
+                        break
+                    if md_line.startswith("---"):
+                        break
+        except Exception:
+            pass
+
+    # Extract session metadata from first meaningful record
+    full_session_id = ""
+    cli_version = ""
+    git_branch = ""
+    model = ""
+    start_time = ""
+    end_time = ""
+
+    for _, rec in records:
+        if rec.get("sessionId"):
+            full_session_id = rec["sessionId"]
+        if rec.get("version") and not cli_version:
+            cli_version = rec["version"]
+        if rec.get("gitBranch") and not git_branch:
+            git_branch = rec["gitBranch"]
+        if not start_time and rec.get("timestamp"):
+            start_time = rec["timestamp"]
+        m = rec.get("message", {}).get("model")
+        if m and not model:
+            model = m
+
+    # Get end time from last record
+    for _, rec in reversed(records):
+        if rec.get("timestamp"):
+            end_time = rec["timestamp"]
+            break
+
+    session_short = full_session_id[:8] if full_session_id else session_prefix.split("_")[-1]
+
+    # Build blocks and agent dispatches
+    blocks, agent_dispatches = build_blocks(records, session_idx, orch_file_rel)
+
+    # Process subagents
+    subagents = []
+    for agent_short, sa_path in sorted(session_files["subagents"].items()):
+        sa_file_rel = strip_daaf_prefix(sa_path)
+        sa_data = process_subagent_file(
+            sa_path, sa_file_rel, agent_short,
+            agent_dispatches, orch_file_rel
+        )
+        if sa_data:
+            subagents.append(sa_data)
+
+    # Link subagents to their orchestrator dispatches
+    link_subagents_to_dispatches(subagents, agent_dispatches, records, orch_file_rel)
+
+    # Enrich subagents with frontmatter skills from agent definitions
+    for sa in subagents:
+        agent_type = sa.get("agentType", "")
+        sa["frontmatterSkills"] = extract_agent_frontmatter_skills(agent_type)
+
+    # Also enrich agent-type activities in blocks with subagent IDs
+    for block in blocks:
+        for act in block.get("activities", []):
+            if act.get("tool") == "Agent":
+                # Find matching subagent by checking the line
+                for sa in subagents:
+                    if sa["invocation"].get("orchestratorLine") == act.get("line"):
+                        act["subagentId"] = sa["id"]
+                        act["subagentType"] = sa.get("agentType", "")
+                        act["subagentLabel"] = sa.get("label", "")
+                        break
+
+    session_data = {
+        "sessionId": session_short,
+        "fullSessionId": full_session_id,
+        "startTime": start_time,
+        "endTime": end_time,
+        "durationSec": duration_between(start_time, end_time),
+        "model": model,
+        "cliVersion": cli_version,
+        "daafVersion": daaf_version,
+        "gitBranch": git_branch,
+        "orchestratorFile": orch_file_rel,
+        "blocks": blocks,
+        "subagents": subagents,
+    }
+
+    print(f"    Blocks: {len(blocks)}, Subagents: {len(subagents)}")
+    return session_data
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Parse DAAF session JSONL logs and produce a session_manifest.json"
+    )
+    parser.add_argument(
+        "project_path",
+        nargs="?",
+        help="Absolute path to a DAAF research project"
+    )
+    parser.add_argument(
+        "--logs-dir",
+        help="Direct path to directory containing JSONL files (overrides project_path/logs)"
+    )
+    args = parser.parse_args()
+
+    if args.logs_dir:
+        logs_dir = os.path.abspath(args.logs_dir)
+        project_name = "DAAF Session Archive"
+        project_rel = strip_daaf_prefix(os.path.dirname(logs_dir))
+    elif args.project_path:
+        project_path = os.path.abspath(args.project_path)
+        logs_dir = os.path.join(project_path, "logs")
+        project_name = os.path.basename(project_path)
+        project_rel = strip_daaf_prefix(project_path)
+    else:
+        parser.error("Either project_path or --logs-dir is required")
+
+    if not os.path.isdir(logs_dir):
+        print(f"ERROR: Logs directory does not exist: {logs_dir}")
+        sys.exit(1)
+
+    print(f"DAAF Log Manifest Builder")
+    print(f"Project: {project_name}")
+    print(f"Logs dir: {logs_dir}")
+    print()
+
+    # Group files by session
+    session_groups = group_files_by_session(logs_dir)
+
+    if not session_groups:
+        print("No JSONL session files found in logs/")
+        sys.exit(1)
+
+    print(f"Found {len(session_groups)} session(s)")
+    print()
+
+    # Process each session
+    sessions = []
+    total_subagents = 0
+
+    for idx, (prefix, files) in enumerate(sorted(session_groups.items())):
+        session_data = process_session(idx, prefix, files)
+        if session_data:
+            sessions.append(session_data)
+            total_subagents += len(session_data.get("subagents", []))
+
+    # Sort sessions chronologically
+    sessions.sort(key=lambda s: s.get("startTime", ""))
+
+    # Build manifest
+    manifest = {
+        "version": 1,
+        "generated": iso_timestamp(),
+        "project": {
+            "name": project_name,
+            "path": project_rel,
+        },
+        "sessions": sessions,
+    }
+
+    # Strip internal fields (prefixed with _) before writing
+    def strip_internal(obj):
+        if isinstance(obj, dict):
+            return {k: strip_internal(v) for k, v in obj.items() if not k.startswith("_")}
+        if isinstance(obj, list):
+            return [strip_internal(item) for item in obj]
+        if isinstance(obj, set):
+            return list(obj)
+        return obj
+
+    manifest = strip_internal(manifest)
+
+    # Write output
+    output_path = os.path.join(logs_dir, "session_manifest.json")
+    with open(output_path, "w", encoding="utf-8") as f:
+        json.dump(manifest, f, indent=2, ensure_ascii=False)
+
+    print()
+    print(f"Summary:")
+    print(f"  Sessions: {len(sessions)}")
+    print(f"  Subagents: {total_subagents}")
+    print(f"  Output: {output_path}")
+
+
+if __name__ == "__main__":
+    main()
diff --git a/scripts/generate_log_viewer.sh b/scripts/generate_log_viewer.sh
new file mode 100755
index 0000000..75a090a
--- /dev/null
+++ b/scripts/generate_log_viewer.sh
@@ -0,0 +1,250 @@
+#!/usr/bin/env bash
+# generate_log_viewer.sh — Generate an interactive HTML session viewer for a DAAF project
+#
+# Processes JSONL session transcripts into a structured manifest, then starts
+# an HTTP server so the interactive Log Explorer is accessible in a browser.
+#
+# Usage:
+#   bash /daaf/scripts/generate_log_viewer.sh <project_path> [--port PORT]
+#   bash /daaf/scripts/generate_log_viewer.sh --archive [--port PORT]
+#
+# Examples:
+#   bash /daaf/scripts/generate_log_viewer.sh /daaf/research/2026-03-29_College_Analysis
+#   bash /daaf/scripts/generate_log_viewer.sh /daaf/research/2026-03-29_College_Analysis --port 2720
+#   bash /daaf/scripts/generate_log_viewer.sh --archive
+#
+# Prerequisites:
+#   - Project must have a logs/ directory containing *_orchestrator.jsonl files
+#     (run collect_session_logs.sh first if needed), or use --archive for all sessions
+#   - Port 2719 (default) must be mapped in docker-compose.yml
+#
+# Exit codes:
+#   0 — success
+#   1 — usage error, invalid project path, or missing logs
+
+set -euo pipefail
+
+# --- Resolve paths ---
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+GENERATOR_SCRIPT="$SCRIPT_DIR/generate_log_viewer.py"
+
+# --- Parse arguments ---
+
+PROJECT_PATH=""
+SERVE=true
+PORT=2719
+ARCHIVE=false
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --archive)
+            ARCHIVE=true
+            shift
+            ;;
+        --serve)
+            # Default behavior; accepted for backwards compatibility
+            shift
+            ;;
+        --no-serve)
+            SERVE=false
+            shift
+            ;;
+        --port)
+            if [ $# -lt 2 ]; then
+                echo "ERROR: --port requires a value"
+                exit 1
+            fi
+            PORT="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: bash $0 <project_path> [--port PORT] [--no-serve]"
+            echo "       bash $0 --archive [--port PORT] [--no-serve]"
+            echo ""
+            echo "Generates an interactive HTML viewer for DAAF session logs"
+            echo "and starts an HTTP server (default port: 2719)."
+            echo ""
+            echo "Arguments:"
+            echo "  project_path    Absolute path to a DAAF research project"
+            echo "  --archive       View all sessions from the DAAF-wide log archive"
+            echo "  --port PORT     Use a custom port for the HTTP server (default: 2719)"
+            echo "  --no-serve      Generate the manifest without starting a server"
+            echo ""
+            echo "Examples:"
+            echo "  bash $0 /daaf/research/2026-03-29_Analysis"
+            echo "  bash $0 --archive"
+            exit 0
+            ;;
+        *)
+            if [ -z "$PROJECT_PATH" ]; then
+                PROJECT_PATH="$1"
+            else
+                echo "ERROR: Unexpected argument: $1"
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+# --- Validate inputs ---
+
+if [ "$ARCHIVE" = true ] && [ -n "$PROJECT_PATH" ]; then
+    echo "ERROR: --archive and project_path are mutually exclusive"
+    exit 1
+fi
+
+if [ "$ARCHIVE" = false ] && [ -z "$PROJECT_PATH" ]; then
+    echo "ERROR: Project path is required (or use --archive for DAAF-wide view)"
+    echo "Usage: bash $0 <project_path> [--port PORT] [--no-serve]"
+    echo "       bash $0 --archive [--port PORT] [--no-serve]"
+    exit 1
+fi
+
+if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1 ] || [ "$PORT" -gt 65535 ]; then
+    echo "ERROR: --port must be a number between 1 and 65535 (got: $PORT)"
+    exit 1
+fi
+
+if [ "$ARCHIVE" = true ]; then
+    LOGS_DIR="$REPO_ROOT/.claude/logs/sessions"
+else
+    if [ ! -d "$PROJECT_PATH" ]; then
+        echo "ERROR: Project directory does not exist: $PROJECT_PATH"
+        exit 1
+    fi
+    LOGS_DIR="$PROJECT_PATH/logs"
+fi
+
+if [ ! -d "$LOGS_DIR" ]; then
+    if [ "$ARCHIVE" = true ]; then
+        echo "ERROR: No session archive found at: $LOGS_DIR"
+    else
+        echo "ERROR: No logs/ directory found in: $PROJECT_PATH"
+        echo "Hint: Run collect_session_logs.sh first to gather session transcripts."
+    fi
+    exit 1
+fi
+
+# Check for orchestrator JSONL files
+ORCH_COUNT=$(find "$LOGS_DIR" -maxdepth 1 -name '*_orchestrator.jsonl' 2>/dev/null | wc -l)
+if [ "$ORCH_COUNT" -eq 0 ]; then
+    echo "ERROR: No orchestrator JSONL files found in: $LOGS_DIR"
+    if [ "$ARCHIVE" = false ]; then
+        echo "Hint: Run collect_session_logs.sh first to gather session transcripts."
+    fi
+    exit 1
+fi
+
+if [ ! -f "$GENERATOR_SCRIPT" ]; then
+    echo "ERROR: Python generator not found: $GENERATOR_SCRIPT"
+    exit 1
+fi
+
+# --- Step 1: Generate manifest ---
+
+echo "Generating session manifest..."
+if [ "$ARCHIVE" = true ]; then
+    if ! python3 "$GENERATOR_SCRIPT" --logs-dir "$LOGS_DIR"; then
+        echo "ERROR: Manifest generation failed (see Python output above)"
+        exit 1
+    fi
+else
+    if ! python3 "$GENERATOR_SCRIPT" "$PROJECT_PATH"; then
+        echo "ERROR: Manifest generation failed (see Python output above)"
+        exit 1
+    fi
+fi
+
+MANIFEST="$LOGS_DIR/session_manifest.json"
+if [ ! -f "$MANIFEST" ]; then
+    echo "ERROR: Manifest generation failed — no output file created"
+    exit 1
+fi
+
+# --- Step 2: Compute viewer URL ---
+
+# The viewer lives at its canonical location in scripts/ and accepts
+# the manifest path as a query parameter — no copy needed.
+RELATIVE_MANIFEST="${MANIFEST#$REPO_ROOT/}"
+VIEWER_URL="scripts/log_viewer.html?manifest=$RELATIVE_MANIFEST"
+
+# --- Summary ---
+
+echo ""
+echo "=== Log Viewer Generated ==="
+echo "  Manifest: $MANIFEST"
+echo ""
+
+# --- Step 3: Optionally start HTTP server ---
+
+if [ "$SERVE" = true ]; then
+    # Check if a server is already listening on the target port
+    # Use /proc/net/tcp and /proc/net/tcp6 (reliable in Docker) since lsof may not see all processes
+    PORT_HEX=$(printf '%04X' "$PORT")
+    LISTEN_INODE=$(awk -v ph="$PORT_HEX" '$2 ~ ":"ph"$" && $4 == "0A" {print $10}' /proc/net/tcp /proc/net/tcp6 2>/dev/null | head -1)
+
+    if [ -n "$LISTEN_INODE" ]; then
+        # Find the PID holding this socket
+        # Note: find may return non-zero as /proc entries vanish mid-scan; || true prevents set -e abort
+        LISTEN_PID=$(find /proc -maxdepth 3 -path '*/fd/*' -exec ls -la {} + 2>/dev/null \
+            | grep "socket:\[$LISTEN_INODE\]" | head -1 \
+            | sed 's|.*/proc/\([0-9]*\)/.*|\1|' || true)
+
+        # Validate PID is numeric
+        if ! [[ "$LISTEN_PID" =~ ^[0-9]+$ ]]; then
+            LISTEN_PID=""
+        fi
+
+        LISTEN_CMD=""
+        [ -n "$LISTEN_PID" ] && LISTEN_CMD=$(ps -p "$LISTEN_PID" -o args= 2>/dev/null || true)
+
+        if echo "$LISTEN_CMD" | grep -qE "http\.server|log_viewer_server"; then
+            echo "Server already running on port $PORT (PID $LISTEN_PID)."
+            echo ""
+            echo "  Open in your browser:"
+            echo "  http://localhost:$PORT/$VIEWER_URL"
+            echo ""
+        elif [ -n "$LISTEN_PID" ]; then
+            echo "Port $PORT is in use by: $LISTEN_CMD (PID $LISTEN_PID). Stopping it..."
+            kill "$LISTEN_PID" 2>/dev/null
+            sleep 1
+            echo "Starting HTTP server on port $PORT (serving from $REPO_ROOT)..."
+            echo ""
+            echo "  Open in your browser:"
+            echo "  http://localhost:$PORT/$VIEWER_URL"
+            echo ""
+            if [ "$ARCHIVE" = true ]; then
+                python3 "$SCRIPT_DIR/log_viewer_server.py" --port "$PORT" --root "$REPO_ROOT" --archive --logs-dir "$LOGS_DIR"
+            else
+                python3 "$SCRIPT_DIR/log_viewer_server.py" --port "$PORT" --root "$REPO_ROOT" --project-path "$PROJECT_PATH"
+            fi
+        else
+            echo "ERROR: Port $PORT is in use but the owning process could not be identified."
+            echo "Free the port manually or use --port to specify a different one."
+            exit 1
+        fi
+    else
+        echo "Starting HTTP server on port $PORT (serving from $REPO_ROOT)..."
+        echo ""
+        echo "  Open in your browser:"
+        echo "  http://localhost:$PORT/$VIEWER_URL"
+        echo ""
+        if [ "$ARCHIVE" = true ]; then
+            python3 "$SCRIPT_DIR/log_viewer_server.py" --port "$PORT" --root "$REPO_ROOT" --archive --logs-dir "$LOGS_DIR"
+        else
+            python3 "$SCRIPT_DIR/log_viewer_server.py" --port "$PORT" --root "$REPO_ROOT" --project-path "$PROJECT_PATH"
+        fi
+    fi
+else
+    echo "Manifest generated. To view, re-run without --no-serve:"
+    echo ""
+    if [ "$ARCHIVE" = true ]; then
+        echo "  bash $0 --archive"
+    else
+        echo "  bash $0 $PROJECT_PATH"
+    fi
+    echo ""
+fi
diff --git a/scripts/host/backup_daaf.ps1 b/scripts/host/backup_daaf.ps1
new file mode 100644
index 0000000..4557c48
--- /dev/null
+++ b/scripts/host/backup_daaf.ps1
@@ -0,0 +1,245 @@
+# ============================================================================
+# DAAF Backup Utility (Windows PowerShell)
+# ============================================================================
+# Creates a timestamped backup of your DAAF Docker volume on the host.
+#
+# Usage:
+#   cd daaf-docker
+#   .\backup_daaf.ps1
+#
+# Backups are created in the current directory with date-versioned names:
+#   2026-04-21_daaf_backup\     (first backup of the day)
+#   2026-04-21a_daaf_backup\    (second backup)
+#   2026-04-21b_daaf_backup\    (third backup)
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*volume inspect*" { return }
+            "*run --rm*" {
+                # Scan command -- return 4 lines matching the parsing expectations:
+                # Line 0: file count, Line 1: "KB\t/source", Line 2: "size\t/source", Line 3: logical KB
+                Write-Output "42"
+                Write-Output "1024`t/source"
+                Write-Output "1.0M`t/source"
+                Write-Output "1000"
+                return
+            }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/backup_daaf.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# --- Configuration ---
+$VolumeName = "daaf_daaf-data"
+$Today = Get-Date -Format "yyyy-MM-dd"
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  DAAF Backup"
+Write-Host "=========================================="
+Write-Host ""
+
+# --- Preflight ---
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from PowerShell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker volume inspect $VolumeName 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker volume '$VolumeName' not found." -ForegroundColor Red
+    Write-Host "Have you run the DAAF installer yet?"
+    Wait-AndExit 1
+}
+
+# --- Generate date-versioned backup name ---
+$BackupName = "${Today}_daaf_backup"
+
+if (Test-Path $BackupName) {
+    # First backup of the day already exists -- find next available suffix
+    $SuffixNum = 0
+    while ($true) {
+        $Suffix = [char](97 + $SuffixNum)  # 0=a, 1=b, 2=c, ...
+        $BackupName = "${Today}${Suffix}_daaf_backup"
+        if (-not (Test-Path $BackupName)) { break }
+        $SuffixNum++
+        if ($SuffixNum -ge 26) {
+            Write-Host "ERROR: Too many backups for today (26 max). Please remove some old backups." -ForegroundColor Red
+            Wait-AndExit 1
+        }
+    }
+}
+
+Write-Host "Backup name: $BackupName\"
+Write-Host ""
+
+# --- Count source files ---
+Write-Host "Scanning Docker volume..."
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$ScanOutput = docker run --rm -v "${VolumeName}:/source:ro" busybox sh -c "find /source -type f | wc -l && du -sk /source && du -sh /source && find /source -type f -exec stat -c %s {} + | awk '{s+=`$1} END {print int(s/1024)}'"
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Could not scan Docker volume." -ForegroundColor Red
+    Wait-AndExit 1
+}
+$TotalFiles = [int]($ScanOutput[0].Trim())
+$VolumeSizeKB = [long](($ScanOutput[1].Trim() -split '\s+')[0])
+$TotalSize = ($ScanOutput[2].Trim() -split '\s+')[0]
+$VolumeLogicalKB = [long]($ScanOutput[3].Trim())
+Write-Host "Found $TotalFiles files to copy ($TotalSize)."
+Write-Host ""
+
+# --- Disk space pre-check ---
+$BackupDrive = (Get-Item -Path ".").PSDrive.Name
+$DriveInfo = New-Object System.IO.DriveInfo($BackupDrive)
+$AvailableKB = [long]($DriveInfo.AvailableFreeSpace / 1024)
+# Add 10% buffer to account for filesystem overhead
+$RequiredKB = [long]($VolumeSizeKB * 110 / 100)
+if ($AvailableKB -lt $RequiredKB) {
+    $RequiredMB = [math]::Floor($RequiredKB / 1024)
+    $AvailableMB = [math]::Floor($AvailableKB / 1024)
+    Write-Host "ERROR: Insufficient disk space for backup." -ForegroundColor Red
+    Write-Host "       Required: ~${RequiredMB} MB (includes 10% buffer), Available: ${AvailableMB} MB"
+    Wait-AndExit 1
+}
+
+# --- Dry-run early exit ---
+# The mock copy creates no files, so verification would fail. Exit cleanly
+# after confirming scan parsing works.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    Write-Host "[DRY-RUN] Would copy $TotalFiles files ($TotalSize) to $BackupName\"
+    Write-Host ""
+    Write-Host "=========================================="
+    Write-Host "  Backup dry-run complete!"
+    Write-Host "=========================================="
+    Write-Host ""
+    Wait-AndExit 0
+}
+
+# --- Create backup ---
+New-Item -ItemType Directory -Path $BackupName -Force | Out-Null
+$HostPath = (Resolve-Path $BackupName).Path
+Write-Host "Copying files from Docker volume..."
+Write-Host "  Progress: 0 / $TotalFiles files (0%)" -NoNewline
+
+$CopyProcess = Start-Process -FilePath "docker" `
+    -ArgumentList "run --rm -v `"${VolumeName}:/source:ro`" -v `"${HostPath}:/dest`" busybox sh -c `"cp -a /source/. /dest/`"" `
+    -NoNewWindow -PassThru
+
+try {
+    while (-not $CopyProcess.HasExited) {
+        Start-Sleep -Seconds 3
+        if ($CopyProcess.HasExited) { break }
+        $Copied = @(Get-ChildItem -Path $BackupName -Recurse -File -Force -ErrorAction SilentlyContinue).Count
+        if ($TotalFiles -gt 0) {
+            $Percent = [math]::Min(100, [math]::Floor($Copied * 100 / $TotalFiles))
+        } else {
+            $Percent = 0
+        }
+        Write-Host "`r  Progress: $Copied / $TotalFiles files ($Percent%)   " -NoNewline
+    }
+} finally {
+    if (-not $CopyProcess.HasExited) {
+        Stop-Process -Id $CopyProcess.Id -Force -ErrorAction SilentlyContinue
+        $CopyProcess.WaitForExit()
+    }
+}
+
+$CopyProcess.WaitForExit()
+$CopyExitCode = if ($null -ne $CopyProcess.ExitCode) { $CopyProcess.ExitCode } else { 0 }
+Write-Host "`r  Progress: $TotalFiles / $TotalFiles files (100%)   "
+
+# --- Verify ---
+$FileCount = @(Get-ChildItem -Path $BackupName -Recurse -File -Force -ErrorAction SilentlyContinue).Count
+
+if ($FileCount -eq 0) {
+    Write-Host ""
+    if ($CopyExitCode -ne 0) {
+        Write-Host "ERROR: Backup failed (exit code $CopyExitCode). Check Docker Desktop for errors." -ForegroundColor Red
+    } else {
+        Write-Host "WARNING: Backup completed but 0 files were copied." -ForegroundColor Yellow
+        Write-Host "The Docker volume may be empty. Is DAAF properly installed?"
+    }
+    Write-Host "Location: $HostPath\"
+    Wait-AndExit 1
+}
+
+if ($CopyExitCode -ne 0) {
+    Write-Host "Note: File copy reported warnings (exit code $CopyExitCode) but all $FileCount files were transferred." -ForegroundColor Yellow
+}
+
+# --- Size verification ---
+# Compare source vs backup logical byte sums to detect truncated files
+$SourceSizeKB = $VolumeLogicalKB
+$BackupSizeKB = [long]((Get-ChildItem -Path $BackupName -Recurse -Force -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum).Sum / 1024)
+if ($SourceSizeKB -gt 0 -and $BackupSizeKB -gt 0) {
+    # Allow 1% tolerance for filesystem metadata differences
+    $ToleranceKB = [math]::Max(1, [long]($SourceSizeKB / 100))
+    $DiffKB = [math]::Abs($SourceSizeKB - $BackupSizeKB)
+    if ($DiffKB -gt $ToleranceKB) {
+        Write-Host ""
+        Write-Host "WARNING: Backup size mismatch." -ForegroundColor Yellow
+        Write-Host "         Source: ${SourceSizeKB} KB, Backup: ${BackupSizeKB} KB (difference: ${DiffKB} KB)"
+        Write-Host "         The backup may be incomplete. Consider re-running."
+    }
+}
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  Backup complete!"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "Location: $HostPath\"
+Write-Host "Files:    $FileCount files copied"
+Write-Host ""
+Write-Host "To restore from this backup, run the restore script from this folder:"
+Write-Host ""
+Write-Host "  .\restore_from_backup.ps1"
+Write-Host ""
+Write-Host "The restore script lets you pick which backup to restore from and"
+Write-Host "handles clearing the volume before copying to ensure a clean state."
+Write-Host ""
+Wait-AndExit 0
diff --git a/scripts/host/backup_daaf.sh b/scripts/host/backup_daaf.sh
new file mode 100755
index 0000000..2eec8c5
--- /dev/null
+++ b/scripts/host/backup_daaf.sh
@@ -0,0 +1,227 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Backup Utility (macOS / Linux)
+# ============================================================================
+# Creates a timestamped backup of your DAAF Docker volume on the host.
+#
+# Usage:
+#   cd daaf-docker
+#   bash backup_daaf.sh
+#
+# Backups are created in the current directory with date-versioned names:
+#   2026-04-21_daaf_backup/     (first backup of the day)
+#   2026-04-21a_daaf_backup/    (second backup)
+#   2026-04-21b_daaf_backup/    (third backup)
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script like migrate_daaf.sh).
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Configuration ---
+VOLUME_NAME="daaf_daaf-data"
+TODAY=$(date +%Y-%m-%d)
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"volume inspect"*) return 0 ;;
+            *"run --rm"*"find /source"*)
+                printf '100\n1024\t/source\n1M\t/source\n1024\n'
+                return 0
+                ;;
+            *"run --rm"*"cp -a"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/backup_daaf.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+echo ""
+echo "=========================================="
+echo "  DAAF Backup"
+echo "=========================================="
+echo ""
+
+# --- Preflight ---
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal."
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start it and try again."
+    exit 1
+fi
+
+# Check the volume exists
+if ! docker volume inspect "${VOLUME_NAME}" &> /dev/null; then
+    echo "ERROR: Docker volume '${VOLUME_NAME}' not found."
+    echo "Have you run the DAAF installer yet?"
+    exit 1
+fi
+
+# --- Generate date-versioned backup name ---
+BACKUP_NAME="${TODAY}_daaf_backup"
+
+if [ -e "${BACKUP_NAME}" ]; then
+    # First backup of the day already exists -- find next available suffix
+    SUFFIX_NUM=0
+    while true; do
+        # Convert number to letter: 0=a, 1=b, 2=c, ...
+        SUFFIX=$(printf "\\$(printf '%03o' $((97 + SUFFIX_NUM)))")
+        BACKUP_NAME="${TODAY}${SUFFIX}_daaf_backup"
+        if [ ! -e "${BACKUP_NAME}" ]; then
+            break
+        fi
+        SUFFIX_NUM=$((SUFFIX_NUM + 1))
+        if [ "${SUFFIX_NUM}" -ge 26 ]; then
+            echo "ERROR: Too many backups for today (26 max). Please remove some old backups."
+            exit 1
+        fi
+    done
+fi
+
+echo "Backup name: ${BACKUP_NAME}/"
+echo ""
+
+# --- Count source files ---
+echo "Scanning Docker volume..."
+SCAN_OUTPUT=$(docker run --rm -v "${VOLUME_NAME}:/source:ro" busybox sh -c 'find /source -type f | wc -l && du -sk /source && du -sh /source && find /source -type f -exec stat -c "%s" {} + | awk "{s+=\$1} END {print int(s/1024)}"') || {
+    echo ""
+    echo "ERROR: Could not scan Docker volume."
+    exit 1
+}
+TOTAL_FILES=$(echo "${SCAN_OUTPUT}" | head -1 | tr -d '[:space:]')
+VOLUME_SIZE_KB=$(echo "${SCAN_OUTPUT}" | sed -n '2p' | awk '{print $1}')
+TOTAL_SIZE=$(echo "${SCAN_OUTPUT}" | sed -n '3p' | awk '{print $1}')
+VOLUME_LOGICAL_KB=$(echo "${SCAN_OUTPUT}" | sed -n '4p' | tr -d '[:space:]')
+echo "Found ${TOTAL_FILES} files to copy (${TOTAL_SIZE})."
+echo ""
+
+# --- Disk space pre-check ---
+AVAILABLE_KB=$(df -P . | awk 'NR==2 {print $4}')
+# Add 10% buffer to account for filesystem overhead
+REQUIRED_KB=$(( VOLUME_SIZE_KB * 110 / 100 ))
+if [ "${AVAILABLE_KB}" -lt "${REQUIRED_KB}" ]; then
+    echo "ERROR: Insufficient disk space for backup." >&2
+    echo "       Required: ~$(( REQUIRED_KB / 1024 )) MB (includes 10% buffer), Available: $(( AVAILABLE_KB / 1024 )) MB" >&2
+    exit 1
+fi
+
+# --- Dry-run early exit ---
+# The mock docker copy creates no files, so file-count verification would fail.
+# Exit after validating the full pre-backup logic path.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    echo ""
+    echo "[DRY-RUN] Would create backup at: $(pwd)/${BACKUP_NAME}/"
+    echo "[DRY-RUN] Source: ${TOTAL_FILES} files (${TOTAL_SIZE}), Space required: ~$((REQUIRED_KB / 1024)) MB"
+    exit 0
+fi
+
+# --- Create backup ---
+mkdir -p "${BACKUP_NAME}"
+echo "Copying files from Docker volume..."
+printf "  Progress: 0 / %d files (0%%)" "${TOTAL_FILES}"
+
+docker run --rm \
+    -v "${VOLUME_NAME}:/source:ro" \
+    -v "$(pwd)/${BACKUP_NAME}:/dest" \
+    busybox sh -c "cp -a /source/. /dest/" &
+COPY_PID=$!
+trap 'kill "${COPY_PID}" 2>/dev/null; wait "${COPY_PID}" 2>/dev/null' INT TERM
+
+while kill -0 "${COPY_PID}" 2>/dev/null; do
+    sleep 3
+    if ! kill -0 "${COPY_PID}" 2>/dev/null; then
+        break
+    fi
+    COPIED=$(find "${BACKUP_NAME}" -type f 2>/dev/null | wc -l | tr -d '[:space:]') || COPIED=0
+    if [ "${TOTAL_FILES}" -gt 0 ]; then
+        PERCENT=$((COPIED * 100 / TOTAL_FILES))
+        if [ "${PERCENT}" -gt 100 ]; then PERCENT=100; fi
+    else
+        PERCENT=0
+    fi
+    printf "\r  Progress: %d / %d files (%d%%)   " "${COPIED}" "${TOTAL_FILES}" "${PERCENT}"
+done
+
+COPY_EXIT=0
+wait "${COPY_PID}" || COPY_EXIT=$?
+printf "\r  Progress: %d / %d files (100%%)   \n" "${TOTAL_FILES}" "${TOTAL_FILES}"
+
+# --- Verify ---
+FILE_COUNT=$(find "${BACKUP_NAME}" -type f 2>/dev/null | wc -l | tr -d '[:space:]') || FILE_COUNT=0
+
+if [ "${FILE_COUNT}" -eq 0 ]; then
+    echo ""
+    if [ "${COPY_EXIT}" -ne 0 ]; then
+        echo "ERROR: Backup failed (exit code ${COPY_EXIT}). Check Docker Desktop for errors."
+    else
+        echo "WARNING: Backup completed but 0 files were copied."
+        echo "The Docker volume may be empty. Is DAAF properly installed?"
+    fi
+    echo "Location: $(pwd)/${BACKUP_NAME}/"
+    exit 1
+fi
+
+if [ "${COPY_EXIT}" -ne 0 ]; then
+    echo "Note: File copy reported warnings (exit code ${COPY_EXIT}) but all ${FILE_COUNT} files were transferred."
+fi
+
+# --- Size verification ---
+# Compare source vs backup logical byte sums to detect truncated files
+SOURCE_SIZE_KB="${VOLUME_LOGICAL_KB}"
+BACKUP_SIZE_KB=$(find "${BACKUP_NAME}" -type f -exec ls -ln {} + 2>/dev/null | awk '{s+=$5} END {printf "%d\n", s/1024}') || BACKUP_SIZE_KB=0
+if [ "${SOURCE_SIZE_KB}" -gt 0 ] && [ "${BACKUP_SIZE_KB}" -gt 0 ]; then
+    # Allow 1% tolerance for filesystem metadata differences
+    TOLERANCE_KB=$(( SOURCE_SIZE_KB / 100 ))
+    if [ "${TOLERANCE_KB}" -lt 1 ]; then TOLERANCE_KB=1; fi
+    DIFF_KB=$(( SOURCE_SIZE_KB - BACKUP_SIZE_KB ))
+    # Absolute value
+    if [ "${DIFF_KB}" -lt 0 ]; then DIFF_KB=$(( -DIFF_KB )); fi
+    if [ "${DIFF_KB}" -gt "${TOLERANCE_KB}" ]; then
+        echo ""
+        echo "WARNING: Backup size mismatch." >&2
+        echo "         Source: ${SOURCE_SIZE_KB} KB, Backup: ${BACKUP_SIZE_KB} KB (difference: ${DIFF_KB} KB)" >&2
+        echo "         The backup may be incomplete. Consider re-running." >&2
+    fi
+fi
+
+echo ""
+echo "=========================================="
+echo "  Backup complete!"
+echo "=========================================="
+echo ""
+echo "Location: $(pwd)/${BACKUP_NAME}/"
+echo "Files:    ${FILE_COUNT} files copied"
+echo ""
+echo "To restore from this backup, run the restore script from this folder:"
+echo ""
+echo "  bash restore_from_backup.sh"
+echo ""
+echo "The restore script lets you pick which backup to restore from and"
+echo "handles clearing the volume before copying to ensure a clean state."
+echo ""
diff --git a/scripts/host/environment_settings_example.txt b/scripts/host/environment_settings_example.txt
new file mode 100644
index 0000000..93bd597
--- /dev/null
+++ b/scripts/host/environment_settings_example.txt
@@ -0,0 +1,85 @@
+# ============================================================================
+# DAAF Environment Variables
+# ============================================================================
+# Copy this file to environment_settings.txt in your daaf-docker folder and fill in your keys:
+#
+#   cp environment_settings_example.txt environment_settings.txt            (macOS / Linux)
+#   Copy-Item environment_settings_example.txt environment_settings.txt     (Windows PowerShell)
+#
+# The environment_settings.txt file is loaded automatically when the container starts.
+# After editing environment_settings.txt, recreate the container to pick up changes:
+#
+#   docker compose down
+#   bash run_daaf.sh            (macOS / Linux)
+#   .\run_daaf.ps1              (Windows)
+#
+# IMPORTANT: Never commit environment_settings.txt to version control — it is gitignored by default.
+# ============================================================================
+
+
+# === CLAUDE CODE AUTHENTICATION =============================================
+# Uncomment ONE section below matching your setup. Claude Code checks
+# credentials in priority order — if multiple are set, the highest-priority
+# one wins. See: https://code.claude.com/docs/en/authentication
+#
+# Priority order:
+#   1. Bedrock / Vertex / Foundry (cloud provider)
+#   2. ANTHROPIC_AUTH_TOKEN (proxy / gateway)
+#   3. ANTHROPIC_API_KEY (direct API — pay-per-use)
+#   4. CLAUDE_CODE_OAUTH_TOKEN (subscription — Max, Pro, Team, Enterprise)
+#   5. Interactive login (browser-based, no env var needed)
+# ============================================================================
+
+# --- Option A: Anthropic API Key (pay-per-use) ---
+# Get a key: https://console.anthropic.com/
+# ANTHROPIC_API_KEY=sk-ant-api03-your_key_here
+
+# --- Option B: Max / Pro / Team / Enterprise Subscription ---
+# Run `claude setup-token` once inside the container to generate a long-lived
+# OAuth token (valid ~1 year), then paste it here for persistent auth.
+# NOTE: Do NOT also set ANTHROPIC_API_KEY — it takes priority and you'll be
+# billed per-use instead of through your subscription.
+# CLAUDE_CODE_OAUTH_TOKEN=your_oauth_token_here
+
+# --- Option C: OpenRouter (third-party model gateway) ---
+# Docs: https://openrouter.ai/docs/guides/coding-agents/claude-code-integration
+# Get a key: https://openrouter.ai/settings/keys
+# If you previously logged in with Anthropic, run /logout in Claude Code first.
+# Leave the ANTHROPIC_API_KEY blank below
+# ANTHROPIC_BASE_URL=https://openrouter.ai/api
+# ANTHROPIC_AUTH_TOKEN=your_openrouter_api_key_here
+# ANTHROPIC_API_KEY=
+# OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# --- Option D: Amazon Bedrock ---
+# Docs: https://code.claude.com/docs/en/bedrock-vertex
+# CLAUDE_CODE_USE_BEDROCK=1
+# AWS_REGION=us-east-1
+# ANTHROPIC_BEDROCK_BASE_URL=https://bedrock-runtime.us-east-1.amazonaws.com
+
+# --- Option E: Google Vertex AI ---
+# Docs: https://code.claude.com/docs/en/bedrock-vertex
+# CLAUDE_CODE_USE_VERTEX=1
+# ANTHROPIC_VERTEX_PROJECT_ID=your_project_id
+# CLOUD_ML_REGION=us-central1
+
+
+# === DATA SOURCE API KEYS ===================================================
+# These are for datasets that require authentication to download.
+# Most DAAF data sources (including all education data) need no keys.
+# ============================================================================
+
+# Harvard Dataverse (required for County Presidential Election Returns)
+# Get a token: https://dataverse.harvard.edu/ -> Log in -> Account name (top-right) -> API Token -> Create Token
+# HARVARD_DATAVERSE_API_KEY=your_token_here
+
+# --- Add your own keys below ---
+# When you onboard new data sources via DAAF's Data Onboarding Mode,
+# it will tell you which environment variable to add here.
+
+# === CODE-SERVER (BROWSER-BASED VS CODE) ====================================
+# Set a custom password for code-server's browser login.
+# If not set, the default password is "daaf".
+# ============================================================================
+
+# PASSWORD=your_password_here
diff --git a/scripts/host/install.ps1 b/scripts/host/install.ps1
new file mode 100644
index 0000000..05056db
--- /dev/null
+++ b/scripts/host/install.ps1
@@ -0,0 +1,344 @@
+# ============================================================================
+# DAAF One-Line Installer (Windows PowerShell)
+# ============================================================================
+# Usage:
+#   irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1 | iex
+#
+# What this script does:
+#   1. Creates a minimal build directory (~5 KB)
+#   2. Downloads the Dockerfile, docker-compose.yml, and convenience scripts
+#   3. Builds the Docker image (Python, data science stack, Claude Code)
+#   4. Clones the full DAAF repository into the Docker volume
+#   5. Prints instructions for first launch
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Internet connection
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-ForUser {
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to close this window"
+    }
+    exit
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, Invoke-WebRequest)
+# for CI cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*volume inspect*" {
+                # Simulate volume-not-found for fresh install path
+                $global:LASTEXITCODE = 1
+                return
+            }
+            "*compose*build*" { return }
+            "*compose*up*" { return }
+            "*compose*exec*true*" { return }
+            "*compose*exec*git clone*" { return }
+            "*compose*exec*bash -c*" { return }
+            "*compose*exec*test -f*" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+
+    function Invoke-WebRequest {
+        param(
+            [switch]$UseBasicParsing,
+            [string]$Uri,
+            [string]$OutFile
+        )
+        # Acknowledge parameters accepted for interface compatibility
+        $null = $UseBasicParsing, $Uri
+        if ($OutFile) {
+            # Create parent directory if needed, then an empty file
+            $parentDir = Split-Path $OutFile -Parent
+            if ($parentDir -and -not (Test-Path $parentDir)) {
+                New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+            }
+            Set-Content -Path $OutFile -Value ""
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/install.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# Ensure TLS 1.2 for GitHub downloads (required on PowerShell 5.1)
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+
+# --- Configuration ---
+$Repo = "DAAF-Contribution-Community/daaf"
+$Branch = if ($env:DAAF_BRANCH) { $env:DAAF_BRANCH } else { "main" }
+$RawBase = "https://raw.githubusercontent.com/$Repo/$Branch"
+$InstallDir = Join-Path (Get-Location).Path "daaf-docker"
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  DAAF Installer"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "Branch: $Branch"
+Write-Host ""
+
+# --- Preflight checks ---
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Powershell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-ForUser; return
+}
+
+# Check Docker daemon is running (compatible with PowerShell 5.1 and 7+)
+# Save/restore ErrorActionPreference around native commands to prevent PS 5.1
+# from promoting stderr output to a terminating error when $ErrorActionPreference
+# is "Stop".
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start Docker Desktop on your computer and try again." -ForegroundColor Red
+    Wait-ForUser; return
+}
+
+# --- Check for existing installation ---
+if (Test-Path "$InstallDir\docker-compose.yml") {
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker volume inspect daaf_daaf-data 2>&1 | Out-Null
+    $ErrorActionPreference = $savedEAP
+    $volumeExists = ($LASTEXITCODE -eq 0)
+    if ($volumeExists) {
+        # Volume exists -- this is a completed or substantially completed installation
+        if ($env:DAAF_FORCE_REINSTALL -eq "1") {
+            Write-Host "NOTE: Existing installation detected. Proceeding with re-install (DAAF_FORCE_REINSTALL=1)."
+            Write-Host ""
+        } else {
+            Write-Host "WARNING: An existing DAAF installation was detected." -ForegroundColor Yellow
+            Write-Host ""
+            Write-Host "Re-running the installer will overwrite framework files (CLAUDE.md, skills,"
+            Write-Host "agents, templates) and local git history. Your research data will NOT be"
+            Write-Host "deleted, but a backup is strongly recommended."
+            Write-Host ""
+            Write-Host "To update DAAF instead (recommended - preserves local changes):"
+            Write-Host "  cd $InstallDir"
+            Write-Host "  .\update_daaf.ps1"
+            Write-Host ""
+            Write-Host "To force a fresh re-install:"
+            Write-Host '  $env:DAAF_FORCE_REINSTALL = "1"'
+            Write-Host "  irm $RawBase/scripts/host/install.ps1 | iex"
+            Write-Host ""
+            Wait-ForUser; return
+        }
+    } else {
+        Write-Host "NOTE: A previous install attempt was detected but appears incomplete."
+        Write-Host "      Proceeding with a fresh install."
+        Write-Host ""
+    }
+}
+
+# --- Create minimal build directory ---
+Write-Host "[1/4] Creating an initial directory for installation files at $InstallDir ..."
+New-Item -ItemType Directory -Path "$InstallDir" -Force | Out-Null
+
+# --- Download build-context and utility files ---
+Write-Host "[2/4] Downloading installation files ..."
+try {
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/Dockerfile"                          -OutFile "$InstallDir\Dockerfile"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/docker-compose.yml"                   -OutFile "$InstallDir\docker-compose.yml"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/run_daaf.ps1"             -OutFile "$InstallDir\run_daaf.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/backup_daaf.ps1"          -OutFile "$InstallDir\backup_daaf.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/restore_from_backup.ps1"  -OutFile "$InstallDir\restore_from_backup.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/rebuild_daaf.ps1"         -OutFile "$InstallDir\rebuild_daaf.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/update_daaf.ps1"          -OutFile "$InstallDir\update_daaf.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/view_logs.ps1"            -OutFile "$InstallDir\view_logs.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/view_notebooks.ps1"      -OutFile "$InstallDir\view_notebooks.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/run_vscode.ps1"           -OutFile "$InstallDir\run_vscode.ps1"
+    Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/environment_settings_example.txt" -OutFile "$InstallDir\environment_settings_example.txt"
+} catch {
+    Write-Host ""
+    Write-Host "ERROR: Failed to download installation files from branch '$Branch'." -ForegroundColor Red
+    Write-Host "Please verify that the branch name is correct and that you have an internet connection."
+    Write-Host "You can check available branches at: https://github.com/$Repo/branches"
+    Write-Host "Details: $_"
+    Wait-ForUser; return
+}
+
+# --- Build the Docker image ---
+Write-Host "[3/4] Building Docker image (this may take a few minutes on first run since there are a lot of Python libraries to install)..."
+# Project name is set declaratively via the top-level "name: daaf" key in
+# docker-compose.yml -- no need to set COMPOSE_PROJECT_NAME here.
+# Build and start are split into two commands so that --progress plain can be
+# applied to the build step (where it is universally supported) without relying
+# on `docker compose up --progress`, which is rejected as "unknown flag" on
+# Docker Compose versions prior to ~v2.27.
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose -f "$InstallDir\docker-compose.yml" build --progress plain
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker image build failed. Check the output above for details." -ForegroundColor Red
+    Write-Host "You can safely re-run this installer to retry (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    Wait-ForUser; return
+}
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose -f "$InstallDir\docker-compose.yml" up -d
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Failed to start the Docker container after build. Check the output above for details." -ForegroundColor Red
+    Write-Host "You can safely re-run this installer to retry (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    Wait-ForUser; return
+}
+
+# --- Wait for container to be ready ---
+Write-Host "      Waiting for container to be ready ..."
+$retries = 0
+$maxRetries = 30
+$readyLog = [System.IO.Path]::GetTempFileName()
+while ($retries -lt $maxRetries) {
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose -f "$InstallDir\docker-compose.yml" exec -T daaf-docker true 2>> $readyLog
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -eq 0) { break }
+    $retries++
+    Start-Sleep -Seconds 2
+}
+if ($retries -ge $maxRetries) {
+    Write-Host "ERROR: Container did not become ready within 60 seconds." -ForegroundColor Red
+    if ((Test-Path $readyLog) -and (Get-Item $readyLog).Length -gt 0) {
+        Write-Host "  Docker reported:" -ForegroundColor Red
+        Get-Content $readyLog -Tail 5 | ForEach-Object { Write-Host "    $_" -ForegroundColor Red }
+        Write-Host ""
+    }
+    Write-Host "Check Docker Desktop for errors, then retry with:"
+    Write-Host "  docker compose -f $InstallDir\docker-compose.yml up -d"
+    Remove-Item $readyLog -ErrorAction SilentlyContinue
+    Wait-ForUser; return
+}
+Remove-Item $readyLog -ErrorAction SilentlyContinue
+
+# --- Clone the full repository into the Docker volume ---
+Write-Host "[4/4] Cloning DAAF repository files into the Docker container ..."
+
+# On reinstall, remove the existing .git directory first.  Git pack files are
+# mode 444 (read-only by design) which prevents cp -a from overwriting them.
+# The research/ folder is preserved -- only framework files are replaced.
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose -f "$InstallDir\docker-compose.yml" exec -T daaf-docker `
+    bash -c 'rm -rf /daaf/.git /daaf/.pre-commit-config.yaml /daaf/.gitignore /daaf/.claudeignore 2>/dev/null; true'
+$ErrorActionPreference = $savedEAP
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose -f "$InstallDir\docker-compose.yml" exec -T daaf-docker `
+    git clone --depth 1 -b "$Branch" "https://github.com/$Repo.git" /tmp/daaf-clone
+$ErrorActionPreference = $savedEAP
+
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to clone the DAAF repository." -ForegroundColor Red
+    Write-Host "The Docker image was built successfully, but the repository could not be downloaded."
+    Write-Host "Check your internet connection and retry with:"
+    Write-Host "  docker compose -f $InstallDir\docker-compose.yml exec -T daaf-docker ``"
+    Write-Host "    git clone --depth 1 -b $Branch https://github.com/$Repo.git /tmp/daaf-clone"
+    Write-Host "  docker compose -f $InstallDir\docker-compose.yml exec -T daaf-docker ``"
+    Write-Host "    bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone'"
+    Write-Host "You can also safely re-run this installer to retry from scratch (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    Wait-ForUser; return
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose -f "$InstallDir\docker-compose.yml" exec -T daaf-docker `
+    bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone'
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to copy repository files into the container." -ForegroundColor Red
+    Write-Host "The clone succeeded, but copying to /daaf/ failed (possibly a permissions issue)."
+    Write-Host "You can retry manually with:"
+    Write-Host "  docker compose -f $InstallDir\docker-compose.yml exec -T daaf-docker ``"
+    Write-Host "    bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone'"
+    Write-Host "You can also safely re-run this installer to retry from scratch (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    Wait-ForUser; return
+}
+
+# --- Verify DAAF files are present ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose -f "$InstallDir\docker-compose.yml" exec -T daaf-docker test -f /daaf/CLAUDE.md 2>&1 | Out-Null
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "WARNING: Installation may be incomplete -- /daaf/CLAUDE.md was not found in the container." -ForegroundColor Yellow
+    Write-Host "The Docker image was built, but the repository files may not have copied correctly."
+    Write-Host "You can try cloning manually inside the container:"
+    Write-Host "  cd $InstallDir"
+    Write-Host "  docker compose exec daaf-docker bash"
+    Write-Host "  git clone --depth 1 -b $Branch https://github.com/$Repo.git /tmp/daaf-clone"
+    Write-Host "  cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone"
+    Wait-ForUser; return
+}
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  Installation complete!"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "To start using DAAF:"
+Write-Host ""
+Write-Host "  1. Navigate to the install directory and launch Claude Code:"
+Write-Host "     cd $InstallDir"
+Write-Host "     .\run_daaf.ps1"
+Write-Host ""
+Write-Host "     This starts the container (if needed) and launches Claude Code directly."
+Write-Host ""
+Write-Host "  2. On first launch, you'll be asked to authenticate with your Anthropic account."
+Write-Host ""
+Write-Host "  3. Configure Claude Code (required):"
+Write-Host "     - Type /config and set:"
+Write-Host "         Auto-compact  -> False"
+Write-Host "         Verbose output -> True"
+Write-Host "     - Press ESC to return to the chat"
+Write-Host ""
+Write-Host "Convenience scripts (in $InstallDir):"
+Write-Host "  .\run_daaf.ps1                 Launch Claude Code (starts container if needed)"
+Write-Host "  .\run_daaf.ps1 bash            Enter the container shell"
+Write-Host "  .\backup_daaf.ps1              Back up the Docker volume to a dated folder"
+Write-Host "  .\restore_from_backup.ps1      Restore from a backup"
+Write-Host "  .\update_daaf.ps1              Check for and apply DAAF updates"
+Write-Host "  .\rebuild_daaf.ps1             Copy build files from container and rebuild image"
+Write-Host "  .\view_logs.ps1                Browse session logs in your browser"
+Write-Host "  .\view_notebooks.ps1           Browse and edit marimo notebooks in your browser"
+Write-Host "  .\run_vscode.ps1               Open VS Code in your browser (code-server)"
+Write-Host ""
+Write-Host "To set up data source API keys (optional):"
+Write-Host "  Copy-Item environment_settings_example.txt environment_settings.txt   Copy the template"
+Write-Host "  Edit environment_settings.txt with your keys, then restart with: .\run_daaf.ps1"
+Write-Host ""
+Write-Host "Manual alternative (if you prefer individual commands):"
+Write-Host "  docker compose exec daaf-docker bash   # enter the container"
+Write-Host "  claude                                  # launch Claude Code"
+Write-Host ""
+Write-Host "For day-to-day usage and more, see:"
+Write-Host "  https://github.com/$Repo/blob/$Branch/user_reference/01_installation_and_quickstart.md"
+Write-Host ""
+Write-Host "Keep this directory - it contains the Dockerfile needed for rebuilds."
+Write-Host ""
+Write-Host "To get started using any of those scripts, enter the install directory first:"
+Write-Host "  cd daaf-docker"
+Write-Host ""
+
+Wait-ForUser
diff --git a/scripts/host/install.sh b/scripts/host/install.sh
new file mode 100755
index 0000000..aeb3a89
--- /dev/null
+++ b/scripts/host/install.sh
@@ -0,0 +1,314 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF One-Line Installer (macOS / Linux)
+# ============================================================================
+# Usage:
+#   curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh | bash
+#
+# What this script does:
+#   1. Creates a minimal build directory (~5 KB)
+#   2. Downloads the Dockerfile, docker-compose.yml, and convenience scripts
+#   3. Builds the Docker image (Python, data science stack, Claude Code)
+#   4. Clones the full DAAF repository into the Docker volume
+#   5. Prints instructions for first launch
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Internet connection
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Interactivity detection: use /dev/tty instead of stdin (fd 0).
+# When users run `curl ... | bash`, stdin is the pipe -- but the user's
+# terminal is still available at /dev/tty. CI environments lack a real
+# terminal entirely.
+#
+# DAAF_NESTED is separate: it suppresses the exit prompt (so nested
+# scripts don't double-pause) but does NOT suppress interactive prompts.
+IS_INTERACTIVE=false
+if [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    IS_INTERACTIVE=true
+fi
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script like test_migration.sh).
+if [ "${IS_INTERACTIVE}" = "true" ] && [ -z "${DAAF_NESTED:-}" ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Configuration ---
+REPO="DAAF-Contribution-Community/daaf"
+BRANCH="${DAAF_BRANCH:-main}"
+RAW_BASE="https://raw.githubusercontent.com/${REPO}/${BRANCH}"
+INSTALL_DIR="$(pwd)/daaf-docker"
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"volume inspect"*) return 1 ;;
+            *"compose"*"build"*) return 0 ;;
+            *"compose"*"up"*) return 0 ;;
+            *"compose"*"exec"*"true"*) return 0 ;;
+            *"compose"*"exec"*"git clone"*) return 0 ;;
+            *"compose"*"exec"*"bash -c"*) return 0 ;;
+            *"compose"*"exec"*"test -f"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+    curl() {
+        # Parse -o flag to create empty target files so chmod +x succeeds
+        local outfile=""
+        local args=("$@")
+        local i
+        for (( i=0; i<${#args[@]}; i++ )); do
+            if [ "${args[$i]}" = "-o" ] && [ $((i+1)) -lt ${#args[@]} ]; then
+                outfile="${args[$((i+1))]}"
+                break
+            fi
+        done
+        if [ -n "${outfile}" ]; then
+            mkdir -p "$(dirname "${outfile}")"
+            touch "${outfile}"
+        fi
+        echo "[DRY-RUN] curl $*" >&2
+        return 0
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/install.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+echo ""
+echo "=========================================="
+echo "  DAAF Installer"
+echo "=========================================="
+echo ""
+echo "Branch: ${BRANCH}"
+echo ""
+
+# --- Preflight checks ---
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal."
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start Docker Desktop on your computer and try again."
+    exit 1
+fi
+
+# --- Check for existing installation ---
+if [ -f "${INSTALL_DIR}/docker-compose.yml" ]; then
+    if docker volume inspect daaf_daaf-data &>/dev/null; then
+        # Volume exists -- this is a completed or substantially completed installation
+        if [ "${DAAF_FORCE_REINSTALL:-}" = "1" ]; then
+            echo "NOTE: Existing installation detected. Proceeding with re-install (DAAF_FORCE_REINSTALL=1)."
+            echo ""
+        else
+            echo "WARNING: An existing DAAF installation was detected."
+            echo ""
+            echo "Re-running the installer will overwrite framework files (CLAUDE.md, skills,"
+            echo "agents, templates) and local git history. Your research data will NOT be"
+            echo "deleted, but a backup is strongly recommended."
+            echo ""
+            echo "To update DAAF instead (recommended -- preserves local changes):"
+            echo "  cd ${INSTALL_DIR}"
+            echo "  bash update_daaf.sh"
+            echo ""
+            echo "To force a fresh re-install, set DAAF_FORCE_REINSTALL=1:"
+            echo "  DAAF_FORCE_REINSTALL=1 bash -c \"\$(curl -fsSL ${RAW_BASE}/scripts/host/install.sh)\""
+            echo ""
+            exit 1
+        fi
+    else
+        echo "NOTE: A previous install attempt was detected but appears incomplete."
+        echo "      Proceeding with a fresh install."
+        echo ""
+    fi
+fi
+
+# --- Create minimal build directory ---
+echo "[1/4] Creating initial directory for installation files at ${INSTALL_DIR} ..."
+mkdir -p "${INSTALL_DIR}"
+
+# --- Download build-context and utility files ---
+echo "[2/4] Downloading installation files ..."
+if ! curl -fsSL "${RAW_BASE}/Dockerfile"                          -o "${INSTALL_DIR}/Dockerfile" ||
+   ! curl -fsSL "${RAW_BASE}/docker-compose.yml"                   -o "${INSTALL_DIR}/docker-compose.yml" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/run_daaf.sh"             -o "${INSTALL_DIR}/run_daaf.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/backup_daaf.sh"          -o "${INSTALL_DIR}/backup_daaf.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/restore_from_backup.sh"  -o "${INSTALL_DIR}/restore_from_backup.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/rebuild_daaf.sh"         -o "${INSTALL_DIR}/rebuild_daaf.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/update_daaf.sh"          -o "${INSTALL_DIR}/update_daaf.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/view_logs.sh"            -o "${INSTALL_DIR}/view_logs.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/view_notebooks.sh"      -o "${INSTALL_DIR}/view_notebooks.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/run_vscode.sh"           -o "${INSTALL_DIR}/run_vscode.sh" ||
+   ! curl -fsSL "${RAW_BASE}/scripts/host/environment_settings_example.txt" -o "${INSTALL_DIR}/environment_settings_example.txt"; then
+    echo ""
+    echo "ERROR: Failed to download installation files from branch '${BRANCH}'."
+    echo "Please verify that the branch name is correct and that you have an internet connection."
+    echo "You can check available branches at: https://github.com/${REPO}/branches"
+    exit 1
+fi
+chmod +x "${INSTALL_DIR}/run_daaf.sh" "${INSTALL_DIR}/backup_daaf.sh" "${INSTALL_DIR}/restore_from_backup.sh" "${INSTALL_DIR}/rebuild_daaf.sh" "${INSTALL_DIR}/update_daaf.sh" "${INSTALL_DIR}/view_logs.sh" "${INSTALL_DIR}/view_notebooks.sh" "${INSTALL_DIR}/run_vscode.sh"
+
+# --- Build the Docker image ---
+echo "[3/4] Building Docker image (this may take a few minutes on first run since there are a lot of Python libraries to install)..."
+# Project name is set declaratively via the top-level "name: daaf" key in
+# docker-compose.yml -- no need to set COMPOSE_PROJECT_NAME here.
+# Build and start are split into two commands so that --progress plain can be
+# applied to the build step (where it is universally supported) without relying
+# on `docker compose up --progress`, which is rejected as "unknown flag" on
+# Docker Compose versions prior to ~v2.27.
+if ! docker compose -f "${INSTALL_DIR}/docker-compose.yml" build --progress plain; then
+    echo ""
+    echo "ERROR: Docker image build failed. Check the output above for details."
+    echo "You can safely re-run this installer to retry (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    exit 1
+fi
+echo "Starting container..."
+if ! docker compose -f "${INSTALL_DIR}/docker-compose.yml" up -d; then
+    echo ""
+    echo "ERROR: Failed to start the Docker container after build. Check the output above for details."
+    echo "You can safely re-run this installer to retry (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    exit 1
+fi
+
+# --- Wait for container to be ready ---
+echo "      Waiting for container to be ready ..."
+RETRIES=0
+MAX_RETRIES=30
+READY_LOG=$(mktemp)
+until docker compose -f "${INSTALL_DIR}/docker-compose.yml" exec -T daaf-docker true </dev/null 2>>"$READY_LOG"; do
+    RETRIES=$((RETRIES + 1))
+    if [ "${RETRIES}" -ge "${MAX_RETRIES}" ]; then
+        echo "ERROR: Container did not become ready within 60 seconds." >&2
+        if [ -s "$READY_LOG" ]; then
+            echo "  Docker reported:" >&2
+            tail -5 "$READY_LOG" | sed 's/^/    /' >&2
+            echo "" >&2
+        fi
+        echo "Check Docker Desktop for errors, then retry with:" >&2
+        echo "  docker compose -f ${INSTALL_DIR}/docker-compose.yml up -d" >&2
+        rm -f "$READY_LOG"
+        exit 1
+    fi
+    sleep 2
+done
+rm -f "$READY_LOG"
+
+# --- Clone the full repository into the Docker volume ---
+echo "[4/4] Cloning DAAF repository files into the Docker container ..."
+
+# On reinstall, remove the existing .git directory first.  Git pack files are
+# mode 444 (read-only by design) which prevents cp -a from overwriting them.
+# The research/ folder is preserved -- only framework files are replaced.
+docker compose -f "${INSTALL_DIR}/docker-compose.yml" exec -T daaf-docker \
+    bash -c 'rm -rf /daaf/.git /daaf/.pre-commit-config.yaml /daaf/.gitignore /daaf/.claudeignore 2>/dev/null; true' </dev/null \
+    || true
+
+if ! docker compose -f "${INSTALL_DIR}/docker-compose.yml" exec -T daaf-docker \
+    git clone --depth 1 -b "${BRANCH}" "https://github.com/${REPO}.git" /tmp/daaf-clone </dev/null; then
+    echo ""
+    echo "ERROR: Failed to clone the DAAF repository."
+    echo "The Docker image was built successfully, but the repository could not be downloaded."
+    echo "Check your internet connection and retry with:"
+    echo "  docker compose -f ${INSTALL_DIR}/docker-compose.yml exec -T daaf-docker \\"
+    echo "    git clone --depth 1 -b ${BRANCH} https://github.com/${REPO}.git /tmp/daaf-clone"
+    echo "  docker compose -f ${INSTALL_DIR}/docker-compose.yml exec -T daaf-docker \\"
+    echo "    bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone'"
+    echo "You can also safely re-run this installer to retry from scratch (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    exit 1
+fi
+
+if ! docker compose -f "${INSTALL_DIR}/docker-compose.yml" exec -T daaf-docker \
+    bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone' </dev/null; then
+    echo ""
+    echo "ERROR: Failed to copy repository files into the container."
+    echo "The clone succeeded, but copying to /daaf/ failed (possibly a permissions issue)."
+    echo "You can retry manually with:"
+    echo "  docker compose -f ${INSTALL_DIR}/docker-compose.yml exec -T daaf-docker \\"
+    echo "    bash -c 'cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone'"
+    echo "You can also safely re-run this installer to retry from scratch (set DAAF_FORCE_REINSTALL=1 if prompted)."
+    exit 1
+fi
+
+# --- Verify DAAF files are present ---
+if ! docker compose -f "${INSTALL_DIR}/docker-compose.yml" exec -T daaf-docker \
+    test -f /daaf/CLAUDE.md </dev/null 2>/dev/null; then
+    echo ""
+    echo "WARNING: Installation may be incomplete -- /daaf/CLAUDE.md was not found in the container."
+    echo "The Docker image was built, but the repository files may not have copied correctly."
+    echo "You can try cloning manually inside the container:"
+    echo "  cd ${INSTALL_DIR}"
+    echo "  docker compose exec daaf-docker bash"
+    echo "  git clone --depth 1 -b ${BRANCH} https://github.com/${REPO}.git /tmp/daaf-clone"
+    echo "  cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone"
+    exit 1
+fi
+
+echo ""
+echo "=========================================="
+echo "  Installation complete!"
+echo "=========================================="
+echo ""
+echo "To start using DAAF:"
+echo ""
+echo "  1. Navigate to the install directory and launch Claude Code:"
+echo "     cd ${INSTALL_DIR}"
+echo "     bash run_daaf.sh"
+echo ""
+echo "     This starts the container (if needed) and launches Claude Code directly."
+echo ""
+echo "  2. On first launch, you'll be asked to authenticate with your Anthropic account."
+echo ""
+echo "  3. Configure Claude Code (required):"
+echo "     - Type /config and set:"
+echo "         Auto-compact  -> False"
+echo "         Verbose output -> True"
+echo "     - Press ESC to return to the chat"
+echo ""
+echo "Convenience scripts (in ${INSTALL_DIR}):"
+echo "  bash run_daaf.sh               Launch Claude Code (starts container if needed)"
+echo "  bash run_daaf.sh bash          Enter the container shell"
+echo "  bash backup_daaf.sh            Back up the Docker volume to a dated folder"
+echo "  bash restore_from_backup.sh    Restore from a backup"
+echo "  bash update_daaf.sh            Check for and apply DAAF updates"
+echo "  bash rebuild_daaf.sh           Copy build files from container and rebuild image"
+echo "  bash view_logs.sh              Browse session logs in your browser"
+echo "  bash view_notebooks.sh         Browse and edit marimo notebooks in your browser"
+echo "  bash run_vscode.sh             Open VS Code in your browser (code-server)"
+echo ""
+echo "To set up data source API keys (optional):"
+echo "  cp environment_settings_example.txt environment_settings.txt   Copy the template"
+echo "  Edit environment_settings.txt with your keys, then restart with: bash run_daaf.sh"
+echo ""
+echo "Manual alternative (if you prefer individual commands):"
+echo "  docker compose exec daaf-docker bash   # enter the container"
+echo "  claude                                  # launch Claude Code"
+echo ""
+echo "For day-to-day usage and more, see:"
+echo "  https://github.com/${REPO}/blob/${BRANCH}/user_reference/01_installation_and_quickstart.md"
+echo ""
+echo "Keep this directory -- it contains the Dockerfile needed for rebuilds."
+echo ""
+echo "To get started using any of those scripts, enter the install directory first:"
+echo "  cd daaf-docker"
+echo ""
diff --git a/scripts/host/migrate_daaf.ps1 b/scripts/host/migrate_daaf.ps1
new file mode 100644
index 0000000..e819faf
--- /dev/null
+++ b/scripts/host/migrate_daaf.ps1
@@ -0,0 +1,1208 @@
+# ============================================================================
+# DAAF Migration Script (Windows PowerShell)
+# ============================================================================
+# Migrates existing DAAF installations to the new update infrastructure.
+#
+# This script is for users who installed DAAF before update_daaf.ps1 existed.
+# It downloads the host utility scripts, backs up the volume, detects your
+# installation type (git clone vs ZIP download), and connects your local git
+# history to the upstream repository so that update_daaf.ps1 works going
+# forward.
+#
+# Usage (one-liner):
+#   irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/migrate_daaf.ps1 | iex
+#
+# Or download and run:
+#   Invoke-WebRequest -Uri https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/migrate_daaf.ps1 -OutFile migrate_daaf.ps1
+#   .\migrate_daaf.ps1
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Internet connection
+#   - An existing DAAF installation (Docker volume daaf_daaf-data exists)
+#
+# This script is idempotent - safe to run multiple times. If the migration
+# has already been completed, it will detect that and skip ahead.
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+# Ensure TLS 1.2 for GitHub downloads (required on PowerShell 5.1)
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+
+# --- Pause before exit so the user can review output ---
+# Skip the prompt when called from another script (DAAF_NESTED).
+# Always calls exit so the window closes cleanly after the user presses
+# Enter -- including when invoked via irm ... | iex (which terminates the
+# PowerShell session, but the user has already read the output).
+function Wait-ForUser {
+    param([int]$ExitCode = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to close this window"
+    }
+    # For non-zero exits, use [Environment]::Exit() which terminates the CLR
+    # process unconditionally.  Plain `exit` fails to propagate when this
+    # script is dot-sourced for testing -- it only unwinds the dot-sourced
+    # scope instead of terminating the host process.
+    if ($ExitCode -ne 0) { [Environment]::Exit($ExitCode) }
+    exit $ExitCode
+}
+
+# --- Configuration ---
+$Repo = "DAAF-Contribution-Community/daaf"
+$Branch = if ($env:DAAF_BRANCH) { $env:DAAF_BRANCH } else { "main" }
+$RawBase = "https://raw.githubusercontent.com/$Repo/$Branch"
+$VolumeName = "daaf_daaf-data"
+$ContainerName = ""
+$BackupCompleted = $false
+$IsFork = $false
+$DetectedEra = ""
+$UpdateChoice = "n"
+
+# --- Detect non-interactive mode (curl-pipe equivalent) ---
+$NonInteractive = $false
+try {
+    if (-not [Environment]::UserInteractive) {
+        $NonInteractive = $true
+    } elseif ([Console]::IsInputRedirected) {
+        $NonInteractive = $true
+    }
+} catch {
+    # Console properties unavailable (e.g., ISE, remoting) -- default to interactive
+    Write-Verbose "Silenced: $_"
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, Invoke-WebRequest)
+# for CI cross-platform smoke testing without a Docker daemon.
+# Mock simulates an era-1 clone-based installation (already migrated path).
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*volume inspect*" { return }
+            "*ps -a*--filter*volume=*--format*" {
+                Write-Output "daaf-daaf-docker-1"
+            }
+            "*inspect*--format*Status*" {
+                Write-Output "running"
+            }
+            "*exec*true*" { return }
+            "*exec*test -f*" { return }
+            "*exec*git -C /daaf remote get-url origin*" {
+                Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+            }
+            "*exec*git -C /daaf fetch*" { return }
+            "*exec*git -C /daaf branch --set-upstream*" { return }
+            "*exec*git -C /daaf remote get-url upstream*" {
+                $global:LASTEXITCODE = 1
+                return
+            }
+            "*exec*git*" { return }
+            "*exec*" { return }
+            "*start*" { return }
+            "*compose up*" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+
+    function Invoke-WebRequest {
+        param(
+            [switch]$UseBasicParsing,
+            [string]$Uri,
+            [string]$OutFile
+        )
+        # Acknowledge parameters accepted for interface compatibility
+        $null = $UseBasicParsing, $Uri
+        if ($OutFile) {
+            $parentDir = Split-Path $OutFile -Parent
+            if ($parentDir -and -not (Test-Path $parentDir)) {
+                New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+            }
+            # Write a minimal stub that exits cleanly (for nested script calls)
+            Set-Content -Path $OutFile -Value "exit 0"
+        }
+    }
+
+    # Force non-interactive to skip the update prompt at the end
+    $NonInteractive = $true
+}
+
+# --- Trap handler for unexpected failures ---
+trap {
+    Write-Host "" -ForegroundColor Red
+    Write-Host "-------------------------------------------" -ForegroundColor Red
+    Write-Host "  Something went wrong unexpectedly" -ForegroundColor Red
+    Write-Host "-------------------------------------------" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "Your research files and data are safe - the migration only changes"
+    Write-Host "framework git history, not your research/ folder."
+    Write-Host ""
+    if ($BackupCompleted) {
+        Write-Host "A backup was created before any changes were made."
+    } else {
+        Write-Host "No changes were made to your installation."
+    }
+    Write-Host ""
+    Write-Host "Most likely causes:"
+    Write-Host "  - Docker Desktop stopped (laptop sleep, lid closed)"
+    Write-Host "  - Internet connection dropped during download"
+    Write-Host "  - A temporary Docker glitch"
+    Write-Host ""
+    Write-Host "To try again:"
+    Write-Host "  1. Make sure Docker Desktop is running"
+    Write-Host "  2. Re-run:  .\migrate_daaf.ps1"
+    Write-Host "     (It is safe to re-run - it will pick up where it left off.)"
+    Write-Host ""
+    if ($Mutex) { try { $Mutex.ReleaseMutex() } catch { <# Mutex already released or not owned -- safe to ignore #> Write-Verbose "Silenced: $_" } }
+    # Inline Wait-ForUser logic -- do not call the function here because trap
+    # blocks are scope-wide (active before function definitions execute), and
+    # Invoke-Expression evaluation may lose function definitions during scope
+    # unwinding, causing CommandNotFoundException.
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to close this window"
+    }
+    [Environment]::Exit(1)
+}
+
+# =====================================================================
+# Helper functions
+# =====================================================================
+
+function Read-UserChoice {
+    param(
+        [string]$PromptText,
+        [string[]]$ValidChoices
+    )
+    # Non-interactive mode (CI, piped input): auto-select first valid choice
+    try { $interactive = [Environment]::UserInteractive -and (-not [Console]::IsInputRedirected) }
+    catch { $interactive = $false }
+    if (-not $interactive) {
+        Write-Host "  (Non-interactive mode - auto-selecting: $($ValidChoices[0]))"
+        return $ValidChoices[0]
+    }
+    while ($true) {
+        $choice = (Read-Host $PromptText).Trim().ToLower()
+        if ($ValidChoices -contains $choice) { return $choice }
+        Write-Host "  Please enter one of: $($ValidChoices -join ', ')" -ForegroundColor Yellow
+    }
+}
+
+# Override Read-UserChoice in dry-run mode (must come after the real definition
+# since the later definition overwrites the earlier one at the same scope)
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function Read-UserChoice {
+        param([string]$PromptText, [string[]]$ValidChoices)
+        $null = $PromptText  # Accept param for interface compatibility
+        Write-Host "[DRY-RUN] Auto-selecting: $($ValidChoices[0])"
+        return $ValidChoices[0]
+    }
+}
+
+# Run a git command inside the container (strips carriage returns, suppresses stderr)
+# Uses SilentlyContinue to prevent PS 5.1 from promoting stderr to a terminating
+# error when $ErrorActionPreference is "Stop" in the caller's scope.
+function Invoke-ContainerGit {
+    # Uses $args (simple function) instead of [Parameter(ValueFromRemainingArguments)]
+    # so PowerShell does not add common parameters (-Debug, -Verbose,
+    # -PipelineVariable, ...) that silently consume single-letter git flags.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $raw = @(docker exec $script:ContainerName git -C /daaf @args 2>$null)
+        $exitCode = $LASTEXITCODE
+        $result = ($raw | Out-String)
+        $global:LASTEXITCODE = $exitCode
+        return ($result -replace "`r","").Trim()
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run a git command inside the container, allowing stderr through
+# Uses SilentlyContinue to prevent PS 5.1 from promoting stderr to a terminating
+# error when $ErrorActionPreference is "Stop" in the caller's scope.
+function Invoke-ContainerGitVerbose {
+    # Simple function -- see Invoke-ContainerGit comment for rationale.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $raw = @(docker exec $script:ContainerName git -C /daaf @args)
+        $exitCode = $LASTEXITCODE
+        $result = ($raw | Out-String)
+        $global:LASTEXITCODE = $exitCode
+        return ($result -replace "`r","").Trim()
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run an arbitrary command inside the container
+# Uses SilentlyContinue to prevent PS 5.1 from promoting stderr to a terminating
+# error when $ErrorActionPreference is "Stop" in the caller's scope.
+function Invoke-ContainerExec {
+    # Simple function -- see Invoke-ContainerGit comment for rationale.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        docker exec $script:ContainerName @args
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run a shell command inside the container, capturing stdout as a string.
+# Suppresses stderr and strips carriage returns. Returns trimmed string.
+# Uses SilentlyContinue to prevent PS 5.1 from promoting stderr to a terminating
+# error when $ErrorActionPreference is "Stop" in the caller's scope.
+function Invoke-ContainerShell {
+    param([string]$ShellCommand)
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $raw = @(docker exec $script:ContainerName sh -c $ShellCommand 2>$null)
+        $exitCode = $LASTEXITCODE
+        $result = ($raw | Out-String)
+        $global:LASTEXITCODE = $exitCode
+        return ($result -replace "`r","").Trim()
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run a shell command inside the container, capturing stdout+stderr as a string.
+# Strips carriage returns. Returns trimmed string.
+# Uses SilentlyContinue to prevent PS 5.1 from promoting stderr to a terminating
+# error when $ErrorActionPreference is "Stop" in the caller's scope.
+function Invoke-ContainerShellVerbose {
+    param([string]$ShellCommand)
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $raw = @(docker exec $script:ContainerName sh -c $ShellCommand 2>&1)
+        $exitCode = $LASTEXITCODE
+        $result = ($raw | Out-String)
+        $global:LASTEXITCODE = $exitCode
+        return ($result -replace "`r","").Trim()
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/migrate_daaf.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# =====================================================================
+# Concurrent-run lock
+# =====================================================================
+# Prevent two instances from operating on the same container simultaneously.
+# The mutex is released on normal exit or when the process terminates.
+
+$MutexName = "Global\DAAFMigrate"
+$Mutex = [System.Threading.Mutex]::new($false, $MutexName)
+try {
+    if (-not $Mutex.WaitOne(0)) {
+        Write-Host "ERROR: Another instance of migrate_daaf is already running." -ForegroundColor Red
+        Write-Host "       Wait for it to finish or restart Docker Desktop to clear the lock." -ForegroundColor Yellow
+        Wait-ForUser -ExitCode 1
+        return
+    }
+} catch [System.Threading.AbandonedMutexException] {
+    # Previous instance crashed -- we inherited ownership of the mutex, safe to continue
+    Write-Verbose "Silenced: $_"
+}
+
+# =====================================================================
+# Main script
+# =====================================================================
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  DAAF Migration"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "This script migrates your existing DAAF installation to support"
+Write-Host "the new update infrastructure (update_daaf.ps1)."
+Write-Host ""
+
+# =====================================================================
+# 1. PREFLIGHT
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Preflight checks"
+Write-Host "-------------------------------------------"
+Write-Host ""
+
+# --- Docker installed ---
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from PowerShell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-ForUser -ExitCode 1; return
+}
+
+# --- Docker running ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start it and try again." -ForegroundColor Red
+    Wait-ForUser -ExitCode 1; return
+}
+
+Write-Host "Docker is running."
+
+# --- Volume exists ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker volume inspect $VolumeName 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Docker volume '$VolumeName' not found." -ForegroundColor Red
+    Write-Host ""
+    Write-Host "This script is for migrating an existing DAAF installation."
+    Write-Host "If you haven't installed DAAF yet, use the installer instead:"
+    Write-Host "  irm $RawBase/scripts/host/install.ps1 | iex"
+    Wait-ForUser -ExitCode 1; return
+}
+
+Write-Host "Found DAAF volume: $VolumeName"
+
+# --- Determine host directory ---
+# If docker-compose.yml exists in the current directory, use it.
+# Otherwise, create daaf-docker\ as install.ps1 would.
+if (Test-Path "docker-compose.yml") {
+    $HostDir = (Get-Location).Path
+    Write-Host "Using current directory: $HostDir"
+} else {
+    $HostDir = Join-Path (Get-Location).Path "daaf-docker"
+    Write-Host "Will create host directory: $HostDir"
+    New-Item -ItemType Directory -Path $HostDir -Force | Out-Null
+}
+
+Write-Host ""
+
+# =====================================================================
+# 2. DOWNLOAD HOST SCRIPTS
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Downloading host scripts"
+Write-Host "-------------------------------------------"
+Write-Host ""
+
+Write-Host "Downloading utility scripts from GitHub..."
+
+$DownloadFailed = $false
+
+foreach ($File in @("backup_daaf.ps1", "restore_from_backup.ps1", "rebuild_daaf.ps1", "update_daaf.ps1", "run_daaf.ps1", "view_logs.ps1", "view_notebooks.ps1", "run_vscode.ps1", "environment_settings_example.txt")) {
+    try {
+        Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/scripts/host/$File" -OutFile "$HostDir\$File"
+        Write-Host "  Downloaded: $File"
+    } catch {
+        Write-Host "  FAILED: $File"
+        $DownloadFailed = $true
+    }
+}
+
+if ($DownloadFailed) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to download one or more utility scripts." -ForegroundColor Red
+    Write-Host "Please check your internet connection and try again."
+    Wait-ForUser -ExitCode 1; return
+}
+
+# Download Dockerfile and docker-compose.yml if not already present
+if (-not (Test-Path "$HostDir\Dockerfile")) {
+    try {
+        Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/Dockerfile" -OutFile "$HostDir\Dockerfile"
+        Write-Host "  Downloaded: Dockerfile"
+    } catch {
+        Write-Host ""
+        Write-Host "ERROR: Failed to download Dockerfile." -ForegroundColor Red
+        Write-Host "Please check your internet connection and try again."
+        Wait-ForUser -ExitCode 1; return
+    }
+}
+
+if (-not (Test-Path "$HostDir\docker-compose.yml")) {
+    try {
+        Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/docker-compose.yml" -OutFile "$HostDir\docker-compose.yml"
+        Write-Host "  Downloaded: docker-compose.yml"
+    } catch {
+        Write-Host ""
+        Write-Host "ERROR: Failed to download docker-compose.yml." -ForegroundColor Red
+        Write-Host "Please check your internet connection and try again."
+        Wait-ForUser -ExitCode 1; return
+    }
+} else {
+    # Even if docker-compose.yml exists, update it so it has name: daaf
+    # (v1.0.0 installations may lack this)
+    $composeContent = Get-Content "$HostDir\docker-compose.yml" -Raw
+    if ($composeContent -notmatch '(?m)^name: daaf') {
+        Write-Host ""
+        Write-Host "  Updating docker-compose.yml to current version..."
+        Copy-Item "$HostDir\docker-compose.yml" "$HostDir\docker-compose.yml.pre-migrate" -Force
+        try {
+            Invoke-WebRequest -UseBasicParsing -Uri "$RawBase/docker-compose.yml" -OutFile "$HostDir\docker-compose.yml"
+            Write-Host "  Updated: docker-compose.yml (old version saved as docker-compose.yml.pre-migrate)"
+        } catch {
+            Write-Host "  WARNING: Could not download updated docker-compose.yml. Restoring original." -ForegroundColor Yellow
+            Move-Item "$HostDir\docker-compose.yml.pre-migrate" "$HostDir\docker-compose.yml" -Force
+        }
+    }
+}
+
+Write-Host ""
+Write-Host "All scripts downloaded to: $HostDir\"
+Write-Host ""
+
+# =====================================================================
+# 3. BACKUP
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Backup"
+Write-Host "-------------------------------------------"
+Write-Host ""
+Write-Host "Before making any changes, a full backup of your DAAF volume will"
+Write-Host "be created. This protects your research data and local history."
+Write-Host ""
+
+$OriginalDir = (Get-Location).Path
+Set-Location $HostDir
+$env:DAAF_NESTED = "1"
+& .\backup_daaf.ps1
+$backupExit = $LASTEXITCODE
+Remove-Item Env:\DAAF_NESTED -ErrorAction SilentlyContinue
+Set-Location $OriginalDir
+if ($backupExit -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Backup failed (exit code $backupExit)."
+    Write-Host "The migration will not proceed without a successful backup."
+    Write-Host "Please resolve the backup issue and re-run: .\migrate_daaf.ps1"
+    Wait-ForUser -ExitCode 1; return
+}
+$BackupCompleted = $true
+
+Write-Host ""
+
+# =====================================================================
+# 4. START CONTAINER (if not running)
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Starting container"
+Write-Host "-------------------------------------------"
+Write-Host ""
+
+# Discover container dynamically from the volume
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$AllContainers = (docker ps -a --filter "volume=$VolumeName" --format '{{.Names}}' | Out-String) -replace "`r",""
+$ErrorActionPreference = $savedEAP
+$AllContainersList = @($AllContainers.Trim() -split "`n" | Where-Object { $_.Trim() -ne "" })
+$ContainerCount = $AllContainersList.Count
+$ContainerName = if ($ContainerCount -gt 0) { $AllContainersList[0].Trim() } else { "" }
+
+if ($ContainerCount -gt 1) {
+    Write-Host "WARNING: Multiple containers found using the DAAF volume:" -ForegroundColor Yellow
+    foreach ($c in $AllContainersList) {
+        Write-Host "  $($c.Trim())"
+    }
+    Write-Host ""
+    Write-Host "Using the first one: $ContainerName"
+    Write-Host "If this is wrong, stop the other containers and re-run."
+    Write-Host ""
+}
+
+if (-not [string]::IsNullOrWhiteSpace($ContainerName)) {
+    Write-Host "Found existing container: $ContainerName"
+
+    # Check if it's running
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    $ContainerState = (docker inspect --format '{{.State.Status}}' $ContainerName 2>$null | Out-String).Trim() -replace "`r",""
+    $ErrorActionPreference = $savedEAP
+    if ([string]::IsNullOrWhiteSpace($ContainerState)) { $ContainerState = "unknown" }
+
+    if ($ContainerState -ne "running") {
+        Write-Host "Container is $ContainerState. Starting it..."
+        $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+        docker start $ContainerName 2>&1 | Out-Null
+        $ErrorActionPreference = $savedEAP
+
+        # Wait for readiness
+        $retries = 0
+        $maxRetries = 30
+        while ($retries -lt $maxRetries) {
+            Invoke-ContainerExec true 2>&1 | Out-Null
+            if ($LASTEXITCODE -eq 0) { break }
+            $retries++
+            Start-Sleep -Seconds 2
+        }
+        if ($retries -ge $maxRetries) {
+            Write-Host ""
+            Write-Host "ERROR: Container did not become ready within 60 seconds." -ForegroundColor Red
+            Write-Host "Try restarting Docker Desktop, then re-run:  .\migrate_daaf.ps1"
+            Wait-ForUser -ExitCode 1; return
+        }
+        Write-Host "Container started."
+    } else {
+        Write-Host "Container is already running."
+    }
+} else {
+    Write-Host "No existing container found. Starting one with docker compose..."
+
+    $OriginalDirCompose = (Get-Location).Path
+    Set-Location $HostDir
+
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose up -d
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Failed to start the DAAF container." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "Common causes:"
+        Write-Host "  - Another program is using the same ports"
+        Write-Host "  - Docker Desktop needs more memory (Settings > Resources)"
+        Write-Host ""
+        Write-Host "Try restarting Docker Desktop, then re-run:  .\migrate_daaf.ps1"
+        Set-Location $OriginalDirCompose
+        Wait-ForUser -ExitCode 1; return
+    }
+
+    # After docker compose up, discover the container name
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    $ContainerName = (docker ps -a --filter "volume=$VolumeName" --format '{{.Names}}' | Select-Object -First 1 | Out-String).Trim() -replace "`r",""
+    $ErrorActionPreference = $savedEAP
+    if ([string]::IsNullOrWhiteSpace($ContainerName)) {
+        Write-Host "ERROR: Container started but could not be found." -ForegroundColor Red
+        Write-Host "Try restarting Docker Desktop, then re-run:  .\migrate_daaf.ps1"
+        Set-Location $OriginalDirCompose
+        Wait-ForUser -ExitCode 1; return
+    }
+
+    Set-Location $OriginalDirCompose
+
+    # Wait for readiness
+    $retries = 0
+    $maxRetries = 30
+    while ($retries -lt $maxRetries) {
+        Invoke-ContainerExec true 2>&1 | Out-Null
+        if ($LASTEXITCODE -eq 0) { break }
+        $retries++
+        Start-Sleep -Seconds 2
+    }
+    if ($retries -ge $maxRetries) {
+        Write-Host ""
+        Write-Host "ERROR: Container started but is not responding after 60 seconds." -ForegroundColor Red
+        Write-Host "Try restarting Docker Desktop, then re-run:  .\migrate_daaf.ps1"
+        Wait-ForUser -ExitCode 1; return
+    }
+    Write-Host "Container started: $ContainerName"
+}
+
+Write-Host ""
+
+# --- Verify DAAF is in the container ---
+Invoke-ContainerExec test -f /daaf/CLAUDE.md
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: DAAF does not appear to be installed in the container." -ForegroundColor Red
+    Write-Host "The volume exists but /daaf/CLAUDE.md was not found."
+    Write-Host ""
+    Write-Host "If this is a fresh installation, use the installer instead:"
+    Write-Host "  irm $RawBase/scripts/host/install.ps1 | iex"
+    Wait-ForUser -ExitCode 1; return
+}
+
+Write-Host "DAAF installation verified in container."
+Write-Host ""
+
+# =====================================================================
+# 5. DETECT ERA
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Detecting installation type"
+Write-Host "-------------------------------------------"
+Write-Host ""
+
+$OriginUrl = Invoke-ContainerGit remote get-url origin
+# Invoke-ContainerGit returns "" on failure (stderr suppressed, empty stdout)
+
+if (-not [string]::IsNullOrWhiteSpace($OriginUrl) -and $OriginUrl -match $Repo) {
+    $DetectedEra = "1"
+    Write-Host "Detected: clone-based installation (remote already configured)"
+    Write-Host "Remote URL: $OriginUrl"
+} elseif (-not [string]::IsNullOrWhiteSpace($OriginUrl)) {
+    # Remote exists but points somewhere unexpected (likely a fork)
+    $DetectedEra = "1"
+    $IsFork = $true
+    Write-Host "Detected: clone-based installation (remote already configured)"
+    Write-Host "Remote URL: $OriginUrl"
+    Write-Host ""
+    Write-Host "NOTE: Your remote points to a location other than the official DAAF"
+    Write-Host "repository. The migration will proceed, but you may want to verify"
+    Write-Host "this is correct."
+} else {
+    $DetectedEra = "2"
+    Write-Host "Detected: ZIP-based installation (no remote configured)"
+    Write-Host "Your local history will be connected to the official DAAF timeline"
+    Write-Host "so that future updates can merge cleanly with your work."
+}
+
+Write-Host ""
+
+# =====================================================================
+# 6a. ERA 1 PATH (v1.0.0 - remote exists)
+# =====================================================================
+if ($DetectedEra -eq "1") {
+    Write-Host "-------------------------------------------"
+    Write-Host "  Fetching upstream history"
+    Write-Host "-------------------------------------------"
+    Write-Host ""
+
+    Write-Host "Running git fetch origin..."
+    $null = Invoke-ContainerGitVerbose fetch origin
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Failed to fetch from origin." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "Common causes:"
+        Write-Host "  - No internet connection"
+        Write-Host "  - GitHub may be experiencing an outage"
+        Write-Host ""
+        Write-Host "Once the issue is resolved, re-run:  .\migrate_daaf.ps1"
+        Wait-ForUser -ExitCode 1; return
+    }
+    Write-Host "Fetch complete."
+
+    # Ensure tracking is set up
+    $null = Invoke-ContainerGit branch --set-upstream-to=origin/main main
+
+    # --- For fork users: add upstream remote for official updates ---
+    if ($IsFork) {
+        $ExistingUpstream = Invoke-ContainerGit remote get-url upstream
+        if ([string]::IsNullOrWhiteSpace($ExistingUpstream)) {
+            Write-Host ""
+            Write-Host "Your 'origin' remote points to a fork. Adding 'upstream' remote"
+            Write-Host "for official DAAF updates..."
+            $null = Invoke-ContainerGitVerbose remote add upstream "https://github.com/$Repo.git"
+            if ($LASTEXITCODE -ne 0) {
+                Write-Host ""
+                Write-Host "WARNING: Could not add 'upstream' remote. You can add it" -ForegroundColor Yellow
+                Write-Host "manually later:"
+                Write-Host "  .\run_daaf.ps1 bash"
+                Write-Host "  git remote add upstream https://github.com/$Repo.git"
+                Write-Host "  git fetch upstream"
+                Write-Host "  exit"
+            } else {
+                Write-Host "Fetching upstream history..."
+                $null = Invoke-ContainerGitVerbose fetch upstream
+                if ($LASTEXITCODE -ne 0) {
+                    Write-Host ""
+                    Write-Host "WARNING: Could not fetch from upstream. The 'upstream' remote was" -ForegroundColor Yellow
+                    Write-Host "added but the fetch failed. You can retry later:"
+                    Write-Host "  .\run_daaf.ps1 bash"
+                    Write-Host "  git fetch upstream"
+                    Write-Host "  exit"
+                } else {
+                    Write-Host "Fetch complete."
+                }
+            }
+        } else {
+            Write-Host ""
+            Write-Host "'upstream' remote already configured: $ExistingUpstream"
+        }
+    }
+
+    Write-Host ""
+    if ($IsFork) {
+        Write-Host "Migration complete. Your installation is connected to your fork"
+        Write-Host "(origin) and the official DAAF repository (upstream)."
+        Write-Host ""
+        Write-Host "update_daaf.ps1 will pull official updates from 'upstream' and merge"
+        Write-Host "them with your fork's changes."
+    } else {
+        Write-Host "Migration complete. Your installation is connected to upstream"
+        Write-Host "and update_daaf.ps1 will work immediately."
+    }
+    Write-Host ""
+
+# =====================================================================
+# 6b. ERA 2 PATH (v2.0.0+ - no remote, need graft)
+# =====================================================================
+} else {
+    Write-Host "-------------------------------------------"
+    Write-Host "  Connecting to upstream repository"
+    Write-Host "-------------------------------------------"
+    Write-Host ""
+
+    # --- Check if remote was already added (idempotent) ---
+    $ExistingOrigin = Invoke-ContainerGit remote get-url origin
+    if (-not [string]::IsNullOrWhiteSpace($ExistingOrigin)) {
+        Write-Host "Remote 'origin' already exists: $ExistingOrigin"
+        Write-Host "Skipping remote add (previous migration attempt detected)."
+    } else {
+        Write-Host "Adding remote origin..."
+        $null = Invoke-ContainerGitVerbose remote add origin "https://github.com/$Repo.git"
+        Write-Host "Remote added."
+    }
+
+    Write-Host ""
+
+    # --- Fetch full history ---
+    Write-Host "Fetching upstream history (this may take a moment)..."
+    $null = Invoke-ContainerGitVerbose fetch origin
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Failed to fetch from origin." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "Common causes:"
+        Write-Host "  - No internet connection"
+        Write-Host "  - GitHub may be experiencing an outage"
+        Write-Host ""
+        Write-Host "Once the issue is resolved, re-run:  .\migrate_daaf.ps1"
+        Wait-ForUser -ExitCode 1; return
+    }
+    Write-Host "Fetch complete."
+
+    Write-Host ""
+
+    # --- Find the initial (root) commit ---
+    $InitialCommits = Invoke-ContainerGitVerbose rev-list --max-parents=0 HEAD
+
+    if ([string]::IsNullOrWhiteSpace($InitialCommits)) {
+        Write-Host ""
+        Write-Host "ERROR: Could not find git history in the container." -ForegroundColor Red
+        Write-Host "The volume exists but no git repository was found at /daaf/."
+        Write-Host ""
+        Write-Host "If this is a fresh installation, use the installer instead:"
+        Write-Host "  irm $RawBase/scripts/host/install.ps1 | iex"
+        Wait-ForUser -ExitCode 1; return
+    }
+
+    # Parse commits into array (force @() to prevent single-element unwrapping --
+    # without it, a single root commit becomes a string and [-1] returns the
+    # last character instead of the last element)
+    $InitialCommitsList = @($InitialCommits -split "`n" | Where-Object { $_.Trim() -ne "" } | ForEach-Object { $_.Trim() })
+    $RootCount = $InitialCommitsList.Count
+
+    # If multiple root commits exist, use the last (oldest) one
+    $InitialCommit = $InitialCommitsList[-1]
+
+    if ($RootCount -gt 1) {
+        Write-Host "NOTE: Found $RootCount root commits. Using the oldest one"
+        Write-Host "      ($($InitialCommit.Substring(0, [Math]::Min(12, $InitialCommit.Length)))) for graft matching."
+        Write-Host ""
+    }
+
+    # --- Check if graft is already in place (idempotent) ---
+    $CatFileOutput = Invoke-ContainerGitVerbose cat-file -p $InitialCommit
+    $InitialParentCount = 0
+    if (-not [string]::IsNullOrWhiteSpace($CatFileOutput)) {
+        $InitialParentCount = ($CatFileOutput -split "`n" | Where-Object { $_ -match '^parent ' }).Count
+    }
+
+    if ($InitialParentCount -gt 0) {
+        Write-Host "History graft already in place (root commit has a parent)."
+        Write-Host "Skipping graft step (previous migration completed successfully)."
+        Write-Host ""
+    } else {
+        # --- Find matching upstream commit ---
+        Write-Host "Analyzing local initial commit..."
+        Write-Host ""
+
+        # Get the blob fingerprint of the initial local commit
+        # We compare only (blob_hash, filepath) pairs, ignoring file modes
+        $LocalTree = Invoke-ContainerShell "cd /daaf && git ls-tree -r '$InitialCommit' | awk '{print `$3, `$4}' | sort"
+
+        if ([string]::IsNullOrWhiteSpace($LocalTree)) {
+            Write-Host ""
+            Write-Host "ERROR: Could not compute file fingerprint for the initial commit."
+            Write-Host "The git repository may be corrupted."
+            Write-Host ""
+            Write-Host "You can try a fresh install instead:"
+            Write-Host "  irm $RawBase/scripts/host/install.ps1 | iex"
+            Wait-ForUser -ExitCode 1; return
+        }
+
+        $MatchingCommit = ""
+        $MatchType = ""
+
+        # Try known tags first, then origin/main HEAD
+        Write-Host "Searching for matching upstream commit..."
+        Write-Host ""
+
+        $Candidates = @("v2.0.1", "v2.0.0", "v1.0.0")
+
+        # Check which tags actually exist
+        $ValidCandidates = @()
+        foreach ($Tag in $Candidates) {
+            $null = Invoke-ContainerGit rev-parse --verify $Tag
+            if ($LASTEXITCODE -eq 0) {
+                $ValidCandidates += $Tag
+            } else {
+                $null = Invoke-ContainerGit rev-parse --verify "origin/$Tag"
+                if ($LASTEXITCODE -eq 0) {
+                    $ValidCandidates += "origin/$Tag"
+                }
+            }
+        }
+
+        # Also try origin/main HEAD
+        $ValidCandidates += "origin/main"
+
+        $Step = 0
+        $TotalCandidates = $ValidCandidates.Count
+
+        foreach ($Candidate in $ValidCandidates) {
+            $Step++
+            $CandidateSha = Invoke-ContainerGit rev-parse $Candidate
+            if ([string]::IsNullOrWhiteSpace($CandidateSha)) {
+                continue
+            }
+
+            Write-Host "  Checking $Candidate ($Step/$TotalCandidates)..." -NoNewline
+
+            $CandidateTree = Invoke-ContainerShell "cd /daaf && git ls-tree -r '$CandidateSha' | awk '{print `$3, `$4}' | sort"
+
+            if ($LocalTree -eq $CandidateTree) {
+                $MatchingCommit = $CandidateSha
+                $MatchType = "exact"
+                Write-Host " EXACT MATCH"
+                Write-Host ""
+                Write-Host "  Matched: $Candidate ($($CandidateSha.Substring(0, [Math]::Min(12, $CandidateSha.Length))))"
+                break
+            } else {
+                Write-Host " no match"
+            }
+        }
+
+        # If no exact match from known candidates, search all commits on origin/main
+        # This runs the entire search inside a SINGLE docker exec call to avoid
+        # the overhead of hundreds of individual docker exec invocations.
+        if ([string]::IsNullOrWhiteSpace($MatchingCommit)) {
+            Write-Host ""
+            Write-Host "  No exact match from known tags. Searching all upstream commits..."
+            Write-Host "  (This runs inside the container and may take 30-60 seconds.)"
+            Write-Host ""
+
+            # Build a skip list of SHAs we already checked
+            $SkipList = ""
+            foreach ($Candidate in $ValidCandidates) {
+                $CandidateSha = Invoke-ContainerGit rev-parse $Candidate
+                if (-not [string]::IsNullOrWhiteSpace($CandidateSha)) {
+                    $SkipList = "$SkipList $CandidateSha"
+                }
+            }
+
+            # Run the full search inside the container in one exec call.
+            # Output format: "EXACT:<sha>" or "BEST:<sha>:<overlap>:<local_count>"
+            # Progress lines go to stderr (prefixed with PROGRESS:)
+            # Temporarily lower ErrorActionPreference so PS 5.1 does not promote
+            # stderr progress output to a terminating error.
+            $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+            $SearchResultRaw = @'
+cd /daaf
+
+# Save local blob fingerprint to temp file
+git ls-tree -r "$INITIAL" | awk '{print $3, $4}' | sort > /tmp/migrate_local_blobs.txt
+LOCAL_COUNT=$(wc -l < /tmp/migrate_local_blobs.txt)
+
+BEST_SHA=""
+BEST_OVERLAP=0
+TOTAL=$(git rev-list origin/main | wc -l)
+NUM=0
+
+for COMMIT in $(git rev-list origin/main); do
+    NUM=$((NUM + 1))
+
+    # Skip already-checked commits
+    case " $SKIP_SHAS " in
+        *" $COMMIT "*) continue ;;
+    esac
+
+    # Progress every 20 commits (to stderr so it does not mix with result)
+    if [ $((NUM % 20)) -eq 0 ]; then
+        printf "  Searching commit %d/%d...\r" "$NUM" "$TOTAL" >&2
+    fi
+
+    # Generate candidate blob fingerprint
+    git ls-tree -r "$COMMIT" | awk '{print $3, $4}' | sort > /tmp/migrate_cand_blobs.txt
+
+    # Exact match check (fast)
+    if diff -q /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt >/dev/null 2>&1; then
+        echo "EXACT:$COMMIT"
+        rm -f /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt
+        exit 0
+    fi
+
+    # Track best fuzzy match
+    OVERLAP=$(comm -12 /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt | wc -l)
+    if [ "$OVERLAP" -gt "$BEST_OVERLAP" ]; then
+        BEST_OVERLAP=$OVERLAP
+        BEST_SHA=$COMMIT
+    fi
+done
+
+rm -f /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt
+echo "BEST:$BEST_SHA:$BEST_OVERLAP:$LOCAL_COUNT"
+'@ | docker exec -i -e "INITIAL=$InitialCommit" -e "SKIP_SHAS=$SkipList" $ContainerName sh 2>&1 | Out-String
+            $ErrorActionPreference = $savedEAP
+            $SearchResult = ($SearchResultRaw -replace "`r","").Trim()
+
+            # Parse the result (last non-empty line matching EXACT/BEST is the result;
+            # earlier lines are progress)
+            $ResultLine = ""
+            foreach ($line in ($SearchResult -split "`n")) {
+                if ($line -match '^(EXACT|BEST):') {
+                    $ResultLine = $line.Trim()
+                }
+            }
+
+            if ($ResultLine -match '^EXACT:') {
+                $MatchingCommit = ($ResultLine -split ':')[1]
+                $MatchType = "exact"
+                Write-Host ""
+                Write-Host "  EXACT MATCH found: $($MatchingCommit.Substring(0, [Math]::Min(12, $MatchingCommit.Length)))"
+            } elseif ($ResultLine -match '^BEST:') {
+                $parts = $ResultLine -split ':'
+                $BestMatchSha = $parts[1]
+                $BestMatchOverlap = [int]$parts[2]
+                $LocalLineCount = [int]$parts[3]
+
+                $OverlapPct = 0
+                if (-not [string]::IsNullOrWhiteSpace($BestMatchSha) -and $LocalLineCount -gt 0) {
+                    $OverlapPct = [math]::Floor($BestMatchOverlap * 100 / $LocalLineCount)
+                }
+
+                if ($OverlapPct -ge 95) {
+                    $MatchingCommit = $BestMatchSha
+                    $MatchType = "fuzzy ($OverlapPct% blob overlap)"
+                    Write-Host ""
+                    Write-Host "  Best match: $($BestMatchSha.Substring(0, [Math]::Min(12, $BestMatchSha.Length))) ($OverlapPct% overlap)"
+                } else {
+                    Write-Host ""
+                    Write-Host "  WARNING: No upstream commit matches your initial commit well enough." -ForegroundColor Yellow
+                    if (-not [string]::IsNullOrWhiteSpace($BestMatchSha)) {
+                        Write-Host "  Best candidate: $($BestMatchSha.Substring(0, [Math]::Min(12, $BestMatchSha.Length))) ($OverlapPct% overlap)"
+                    }
+                    Write-Host ""
+                }
+            }
+        }
+
+        # Fallback: graft onto latest known tag
+        if ([string]::IsNullOrWhiteSpace($MatchingCommit)) {
+            Write-Host "  Falling back to grafting onto the latest known tag..."
+
+            $FallbackTag = ""
+            foreach ($Tag in @("v2.0.1", "v2.0.0", "v1.0.0")) {
+                $null = Invoke-ContainerGit rev-parse --verify $Tag
+                if ($LASTEXITCODE -eq 0) {
+                    $FallbackTag = $Tag
+                    break
+                }
+                $null = Invoke-ContainerGit rev-parse --verify "origin/$Tag"
+                if ($LASTEXITCODE -eq 0) {
+                    $FallbackTag = "origin/$Tag"
+                    break
+                }
+            }
+
+            if (-not [string]::IsNullOrWhiteSpace($FallbackTag)) {
+                $MatchingCommit = Invoke-ContainerGit rev-parse $FallbackTag
+                $MatchType = "fallback ($FallbackTag)"
+                Write-Host ""
+                Write-Host "  WARNING: Using fallback graft point: $FallbackTag ($($MatchingCommit.Substring(0, [Math]::Min(12, $MatchingCommit.Length))))" -ForegroundColor Yellow
+                Write-Host "  Your local initial commit did not match any upstream commit exactly."
+                Write-Host "  This is safe but means your git history may show a small discontinuity"
+                Write-Host "  at the graft point. update_daaf.ps1 will still work correctly."
+            } else {
+                # Last resort: use origin/main
+                $MatchingCommit = Invoke-ContainerGit rev-parse origin/main
+                $MatchType = "fallback (origin/main HEAD)"
+                Write-Host ""
+                Write-Host "  WARNING: No tags found. Using origin/main HEAD as graft point." -ForegroundColor Yellow
+                Write-Host "  This is safe but means your git history may show a discontinuity."
+            }
+        }
+
+        Write-Host ""
+
+        if ([string]::IsNullOrWhiteSpace($MatchingCommit)) {
+            Write-Host "ERROR: Could not determine a graft point." -ForegroundColor Red
+            Write-Host "This is unexpected. Please report this issue at:"
+            Write-Host "  https://github.com/$Repo/issues"
+            Wait-ForUser -ExitCode 1; return
+        }
+
+        # --- Graft local history onto upstream ---
+        Write-Host "Connecting local history to upstream ($MatchType)..."
+        $null = Invoke-ContainerGitVerbose replace --graft $InitialCommit $MatchingCommit
+        Write-Host "Graft complete."
+        Write-Host ""
+
+        # --- Verify the graft works ---
+        Write-Host "Verifying graft..."
+        $MergeBase = Invoke-ContainerGitVerbose merge-base HEAD origin/main
+        if (-not [string]::IsNullOrWhiteSpace($MergeBase)) {
+            Write-Host "  Verified: common ancestor found ($($MergeBase.Substring(0, [Math]::Min(12, $MergeBase.Length))))"
+            Write-Host "  git merge and git pull will work correctly."
+        } else {
+            Write-Host ""
+            Write-Host "  WARNING: Could not verify graft - no common ancestor found." -ForegroundColor Yellow
+            Write-Host "  The graft was applied, but git merge may not work as expected."
+            Write-Host "  This is unusual. You can re-run:  .\migrate_daaf.ps1"
+            Write-Host "  If the problem persists, report it at:"
+            Write-Host "    https://github.com/$Repo/issues"
+        }
+        Write-Host ""
+
+        # --- Fix file permissions in the index ---
+        Write-Host "Fixing file permissions (ZIP downloads don't preserve executable bits)..."
+
+        # Get files that are 100755 upstream but 100644 locally
+        $UpstreamExec = Invoke-ContainerShell "cd /daaf && git ls-tree -r '$MatchingCommit' | grep '^100755' | awk '{print `$4}' | sort"
+
+        $PermFixed = 0
+        if (-not [string]::IsNullOrWhiteSpace($UpstreamExec)) {
+            $UpstreamExecFiles = @($UpstreamExec -split "`n" | Where-Object { $_.Trim() -ne "" } | ForEach-Object { $_.Trim() })
+
+            foreach ($FilePath in $UpstreamExecFiles) {
+                if ([string]::IsNullOrWhiteSpace($FilePath)) { continue }
+
+                # Check if the file exists locally and has wrong mode
+                # Use git ls-files -s -- <filepath> (no sh -c wrapper)
+                $LocalMode = Invoke-ContainerGit ls-files -s -- $FilePath
+                if (-not [string]::IsNullOrWhiteSpace($LocalMode)) {
+                    $ModeField = ($LocalMode -split '\s+')[0]
+                    if ($ModeField -eq "100644") {
+                        $null = Invoke-ContainerGit update-index --chmod=+x $FilePath
+                        $PermFixed++
+                    }
+                }
+            }
+        }
+
+        if ($PermFixed -gt 0) {
+            Write-Host "  Fixed permissions on $PermFixed file(s)."
+            Write-Host ""
+            Write-Host "Committing permission fixes..."
+            # Commit only the permission changes already staged by update-index
+            # (do NOT use 'git add -A' which could sweep in unrelated changes)
+            $null = Invoke-ContainerGitVerbose commit --allow-empty -m "Migration: normalize file permissions"
+            Write-Host "Permission fixes committed."
+        } else {
+            Write-Host "  No permission fixes needed."
+        }
+
+        Write-Host ""
+    }
+
+    # --- Set upstream tracking ---
+    Write-Host "Setting upstream tracking branch..."
+    $null = Invoke-ContainerGit branch --set-upstream-to=origin/main main
+    Write-Host "Tracking set: main -> origin/main"
+    Write-Host ""
+
+    Write-Host "Migration complete. Your local history is now connected to the"
+    Write-Host "official DAAF timeline. Future updates will merge cleanly."
+    Write-Host ""
+}
+
+# =====================================================================
+# 7. OFFER UPDATE
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Run update?"
+Write-Host "-------------------------------------------"
+Write-Host ""
+Write-Host "Your installation is now connected to the upstream repository."
+Write-Host "Would you like to pull the latest updates now?"
+Write-Host ""
+
+if (-not $NonInteractive) {
+    $UpdateChoice = Read-UserChoice "  Run update_daaf.ps1 now? [y/n]" @("y", "n")
+} else {
+    # Non-interactive (piped) - skip the update
+    Write-Host "  (Non-interactive mode detected - skipping update. Run it manually.)"
+    $UpdateChoice = "n"
+}
+
+$UpdateRan = $false
+if ($UpdateChoice -eq "y") {
+    Write-Host ""
+    $OriginalDirUpdate = (Get-Location).Path
+    Set-Location $HostDir
+    $env:DAAF_NESTED = "1"
+    & .\update_daaf.ps1
+    if ($LASTEXITCODE -eq 0) { $UpdateRan = $true }
+    Remove-Item Env:\DAAF_NESTED -ErrorAction SilentlyContinue
+    Set-Location $OriginalDirUpdate
+}
+
+# =====================================================================
+# 8. SUCCESS MESSAGE
+# =====================================================================
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  Migration complete!"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "Your DAAF installation has been migrated to support the new update"
+Write-Host "infrastructure. Here is what was done:"
+Write-Host ""
+if ($DetectedEra -eq "1") {
+    Write-Host "  - Downloaded host utility scripts to: $HostDir\"
+    Write-Host "  - Created a full backup of your Docker volume"
+    Write-Host "  - Fetched latest upstream history into your existing repo"
+} else {
+    Write-Host "  - Downloaded host utility scripts to: $HostDir\"
+    Write-Host "  - Created a full backup of your Docker volume"
+    Write-Host "  - Added remote origin pointing to the official DAAF repository"
+    Write-Host "  - Connected your local git history to the official DAAF timeline"
+    Write-Host "  - Fixed file permissions to match upstream"
+    Write-Host "  - Set upstream tracking (main -> origin/main)"
+}
+Write-Host ""
+if ($UpdateChoice -eq "y" -and $UpdateRan) {
+    Write-Host "Going forward, you can update DAAF with:"
+} elseif ($UpdateChoice -eq "y" -and (-not $UpdateRan)) {
+    Write-Host "The update step encountered an issue (see above). Once resolved,"
+    Write-Host "you can update DAAF with:"
+} elseif ($UpdateChoice -eq "n" -and (-not $NonInteractive)) {
+    # User chose not to update
+    Write-Host "To pull the latest updates when you're ready:"
+} elseif ($NonInteractive) {
+    # Non-interactive mode (irm pipe) - update was skipped automatically
+    Write-Host "IMPORTANT: The update step was skipped because the script was run"
+    Write-Host "non-interactively. To pull the latest updates, run:"
+} else {
+    Write-Host "Going forward, you can update DAAF with:"
+}
+Write-Host "  cd $HostDir"
+Write-Host "  .\update_daaf.ps1"
+Write-Host ""
+Write-Host "Other available scripts:"
+Write-Host "  .\run_daaf.ps1                Launch Claude Code"
+Write-Host "  .\backup_daaf.ps1             Back up the Docker volume"
+Write-Host "  .\restore_from_backup.ps1     Restore from a backup"
+Write-Host "  .\rebuild_daaf.ps1            Rebuild the Docker image"
+Write-Host "  .\view_logs.ps1               Browse session logs"
+Write-Host "  .\view_notebooks.ps1          Browse and edit marimo notebooks"
+Write-Host "  .\run_vscode.ps1              Open VS Code in your browser (code-server)"
+Write-Host ""
+
+if ($Mutex) { try { $Mutex.ReleaseMutex() } catch { <# Mutex already released or not owned -- safe to ignore #> Write-Verbose "Silenced: $_" } }
+Wait-ForUser
diff --git a/scripts/host/migrate_daaf.sh b/scripts/host/migrate_daaf.sh
new file mode 100755
index 0000000..93275e7
--- /dev/null
+++ b/scripts/host/migrate_daaf.sh
@@ -0,0 +1,1005 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Migration Script (macOS / Linux)
+# ============================================================================
+# Migrates existing DAAF installations to the new update infrastructure.
+#
+# This script is for users who installed DAAF before update_daaf.sh existed.
+# It downloads the host utility scripts, backs up the volume, detects your
+# installation era (git clone vs ZIP download), and grafts your local git
+# history onto the upstream repository so that update_daaf.sh works going
+# forward.
+#
+# Usage (one-liner):
+#   curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/migrate_daaf.sh | bash
+#
+# Or download and run:
+#   curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/migrate_daaf.sh -o migrate_daaf.sh
+#   bash migrate_daaf.sh
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Internet connection
+#   - An existing DAAF installation (Docker volume daaf_daaf-data exists)
+#
+# This script is idempotent -- safe to run multiple times. If the migration
+# has already been completed, it will detect that and skip ahead.
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Interactivity detection: use /dev/tty instead of stdin (fd 0).
+# When users run `curl ... | bash`, stdin is the pipe -- but the user's
+# terminal is still available at /dev/tty. CI runners either lack /dev/tty
+# or it is not a real terminal, so this naturally gives the right answer.
+#
+# DAAF_NESTED is separate: it suppresses the exit prompt (so nested
+# scripts don't double-pause) but does NOT suppress interactive prompts.
+IS_INTERACTIVE=false
+if [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    IS_INTERACTIVE=true
+fi
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script).
+if [ "${IS_INTERACTIVE}" = "true" ] && [ -z "${DAAF_NESTED:-}" ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Configuration ---
+REPO="DAAF-Contribution-Community/daaf"
+BRANCH="${DAAF_BRANCH:-main}"
+RAW_BASE="https://raw.githubusercontent.com/${REPO}/${BRANCH}"
+VOLUME_NAME="daaf_daaf-data"
+CONTAINER_NAME=""
+BACKUP_COMPLETED=false
+IS_FORK=false
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"volume inspect"*) return 0 ;;
+            *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-dry-run-1" ;;
+            *"inspect --format"*"State.Status"*) echo "running" ;;
+            *"exec"*"true"*) return 0 ;;
+            *"exec"*"test -f"*) return 0 ;;
+            *"exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+            *"exec"*"fetch"*) return 0 ;;
+            *"exec"*"branch --set-upstream"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+    curl() {
+        # Parse -o flag to create empty target files so chmod +x succeeds
+        local outfile=""
+        local args=("$@")
+        local i
+        for (( i=0; i<${#args[@]}; i++ )); do
+            if [ "${args[$i]}" = "-o" ] && [ $((i+1)) -lt ${#args[@]} ]; then
+                outfile="${args[$((i+1))]}"
+                break
+            fi
+        done
+        if [ -n "${outfile}" ]; then
+            mkdir -p "$(dirname "${outfile}")"
+            touch "${outfile}"
+        fi
+        echo "[DRY-RUN] curl $*" >&2
+        return 0
+    }
+fi
+
+# --- Trap handler for unexpected failures ---
+cleanup_on_error() {
+    [ -n "${LOCK_DIR:-}" ] && rmdir "$LOCK_DIR" 2>/dev/null || true
+    echo "" >&2
+    echo "-------------------------------------------" >&2
+    echo "  Something went wrong unexpectedly" >&2
+    echo "-------------------------------------------" >&2
+    echo "" >&2
+    echo "Your research files and data are safe -- the migration only changes" >&2
+    echo "framework git history, not your research/ folder." >&2
+    echo "" >&2
+    if [ "${BACKUP_COMPLETED}" = true ]; then
+        echo "A backup was created before any changes were made." >&2
+    else
+        echo "No changes were made to your installation." >&2
+    fi
+    echo "" >&2
+    echo "Most likely causes:" >&2
+    echo "  - Docker Desktop stopped (laptop sleep, lid closed)" >&2
+    echo "  - Internet connection dropped during download" >&2
+    echo "  - A temporary Docker glitch" >&2
+    echo "" >&2
+    echo "To try again:" >&2
+    echo "  1. Make sure Docker Desktop is running" >&2
+    echo "  2. Re-run:  bash migrate_daaf.sh" >&2
+    echo "     (It is safe to re-run -- it will pick up where it left off.)" >&2
+    echo "" >&2
+}
+trap cleanup_on_error ERR
+
+# =====================================================================
+# Helper functions
+# =====================================================================
+
+prompt_choice() {
+    local prompt_text="$1"
+    local valid_choices="$2"
+    local choice=""
+    # Non-interactive mode: auto-select first valid choice
+    if [ "${IS_INTERACTIVE}" != "true" ]; then
+        choice=$(echo "${valid_choices}" | awk '{print $1}')
+        echo "  (Non-interactive mode -- auto-selecting: ${choice})" >&2
+        echo "${choice}"
+        return
+    fi
+    while true; do
+        read -r -p "${prompt_text}" choice < /dev/tty
+        choice=$(echo "${choice}" | tr '[:upper:]' '[:lower:]')
+        if echo "${valid_choices}" | grep -qw "${choice}"; then
+            echo "${choice}"
+            return
+        fi
+        echo "  Please enter one of: ${valid_choices}" >&2
+    done
+}
+
+# Override prompt_choice in dry-run mode (must come after the real definition
+# since bash function definitions are global, not block-scoped)
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    prompt_choice() {
+        local valid_choices="$2"
+        local first_choice
+        first_choice=$(echo "${valid_choices}" | awk '{print $1}')
+        echo "[DRY-RUN] Auto-selecting: ${first_choice}" >&2
+        echo "${first_choice}"
+    }
+fi
+
+# Run a git command inside the container (strips carriage returns)
+container_git() {
+    docker exec "${CONTAINER_NAME}" git -C /daaf "$@" </dev/null 2>/dev/null | tr -d '\r'
+}
+
+# Run a git command inside the container, allowing stderr through
+container_git_verbose() {
+    docker exec "${CONTAINER_NAME}" git -C /daaf "$@" </dev/null | tr -d '\r'
+}
+
+# Run a shell command inside the container
+container_exec() {
+    docker exec "${CONTAINER_NAME}" "$@" </dev/null
+}
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/migrate_daaf.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# =====================================================================
+# Portable concurrent-run lock (mkdir)
+# =====================================================================
+# Prevent two instances from operating on the same container simultaneously.
+# mkdir is atomic on all POSIX systems (Linux, macOS, Git Bash on Windows).
+# The lock directory is cleaned up via the EXIT trap when the script exits.
+LOCK_DIR="/tmp/daaf-migrate.lock.d"
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+    echo "ERROR: Another instance of migrate_daaf is already running." >&2
+    echo "       If you believe this is stale, remove: $LOCK_DIR" >&2
+    exit 1
+fi
+_daaf_prior_exit_trap=$(trap -p EXIT | sed -n "s/^trap -- '\\(.*\\)' EXIT$/\\1/p")
+trap 'rmdir "$LOCK_DIR" 2>/dev/null || true; '"$_daaf_prior_exit_trap" EXIT
+
+# =====================================================================
+# Main script
+# =====================================================================
+
+echo ""
+echo "=========================================="
+echo "  DAAF Migration"
+echo "=========================================="
+echo ""
+echo "This script migrates your existing DAAF installation to support"
+echo "the new update infrastructure (update_daaf.sh)."
+echo ""
+
+# =====================================================================
+# 1. PREFLIGHT
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Preflight checks"
+echo "-------------------------------------------"
+echo ""
+
+# --- Docker installed ---
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal."
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    exit 1
+fi
+
+# --- Docker running ---
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start it and try again."
+    exit 1
+fi
+
+echo "Docker is running."
+
+# --- Volume exists ---
+if ! docker volume inspect "${VOLUME_NAME}" &> /dev/null; then
+    echo ""
+    echo "ERROR: Docker volume '${VOLUME_NAME}' not found."
+    echo ""
+    echo "This script is for migrating an existing DAAF installation."
+    echo "If you haven't installed DAAF yet, use the installer instead:"
+    echo "  curl -fsSL https://raw.githubusercontent.com/${REPO}/${BRANCH}/scripts/host/install.sh | bash"
+    exit 1
+fi
+
+echo "Found DAAF volume: ${VOLUME_NAME}"
+
+# --- Determine host directory ---
+# If docker-compose.yml exists in the current directory, use it.
+# Otherwise, create daaf-docker/ as install.sh would.
+if [ -f "docker-compose.yml" ]; then
+    HOST_DIR="$(pwd)"
+    echo "Using current directory: ${HOST_DIR}"
+else
+    HOST_DIR="$(pwd)/daaf-docker"
+    echo "Will create host directory: ${HOST_DIR}"
+    mkdir -p "${HOST_DIR}"
+fi
+
+echo ""
+
+# =====================================================================
+# 2. DOWNLOAD HOST SCRIPTS
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Downloading host scripts"
+echo "-------------------------------------------"
+echo ""
+
+echo "Downloading utility scripts from GitHub..."
+
+DOWNLOAD_FAILED=false
+
+for FILE in backup_daaf.sh restore_from_backup.sh rebuild_daaf.sh update_daaf.sh run_daaf.sh view_logs.sh view_notebooks.sh run_vscode.sh environment_settings_example.txt; do
+    if curl -fsSL "${RAW_BASE}/scripts/host/${FILE}" -o "${HOST_DIR}/${FILE}"; then
+        echo "  Downloaded: ${FILE}"
+    else
+        echo "  FAILED: ${FILE}"
+        DOWNLOAD_FAILED=true
+    fi
+done
+
+if [ "${DOWNLOAD_FAILED}" = true ]; then
+    echo ""
+    echo "ERROR: Failed to download one or more utility scripts."
+    echo "Please check your internet connection and try again."
+    exit 1
+fi
+
+# Download Dockerfile and docker-compose.yml if not already present
+if [ ! -f "${HOST_DIR}/Dockerfile" ]; then
+    if curl -fsSL "${RAW_BASE}/Dockerfile" -o "${HOST_DIR}/Dockerfile"; then
+        echo "  Downloaded: Dockerfile"
+    else
+        echo ""
+        echo "ERROR: Failed to download Dockerfile."
+        echo "Please check your internet connection and try again."
+        exit 1
+    fi
+fi
+
+if [ ! -f "${HOST_DIR}/docker-compose.yml" ]; then
+    if curl -fsSL "${RAW_BASE}/docker-compose.yml" -o "${HOST_DIR}/docker-compose.yml"; then
+        echo "  Downloaded: docker-compose.yml"
+    else
+        echo ""
+        echo "ERROR: Failed to download docker-compose.yml."
+        echo "Please check your internet connection and try again."
+        exit 1
+    fi
+else
+    # Even if docker-compose.yml exists, update it so it has name: daaf
+    # (v1.0.0 installations may lack this)
+    if ! grep -q '^name: daaf' "${HOST_DIR}/docker-compose.yml"; then
+        echo ""
+        echo "  Updating docker-compose.yml to current version..."
+        cp "${HOST_DIR}/docker-compose.yml" "${HOST_DIR}/docker-compose.yml.pre-migrate"
+        if curl -fsSL "${RAW_BASE}/docker-compose.yml" -o "${HOST_DIR}/docker-compose.yml"; then
+            echo "  Updated: docker-compose.yml (old version saved as docker-compose.yml.pre-migrate)"
+        else
+            echo "  WARNING: Could not download updated docker-compose.yml. Restoring original."
+            mv "${HOST_DIR}/docker-compose.yml.pre-migrate" "${HOST_DIR}/docker-compose.yml"
+        fi
+    fi
+fi
+
+# Make all .sh files executable
+chmod +x "${HOST_DIR}"/*.sh 2>/dev/null || true
+
+echo ""
+echo "All scripts downloaded to: ${HOST_DIR}/"
+echo ""
+
+# =====================================================================
+# 3. BACKUP
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Backup"
+echo "-------------------------------------------"
+echo ""
+echo "Before making any changes, a full backup of your DAAF volume will"
+echo "be created. This protects your research data and local history."
+echo ""
+
+ORIGINAL_DIR="$(pwd)"
+cd "${HOST_DIR}"
+DAAF_NESTED=1 bash backup_daaf.sh
+cd "${ORIGINAL_DIR}"
+BACKUP_COMPLETED=true
+
+echo ""
+
+# =====================================================================
+# 4. START CONTAINER (if not running)
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Starting container"
+echo "-------------------------------------------"
+echo ""
+
+# Discover container dynamically from the volume
+ALL_CONTAINERS=$(docker ps -a --filter "volume=${VOLUME_NAME}" --format '{{.Names}}')
+CONTAINER_COUNT=$(echo "${ALL_CONTAINERS}" | grep -c . || true)
+CONTAINER_COUNT="${CONTAINER_COUNT:-0}"
+CONTAINER_NAME=$(echo "${ALL_CONTAINERS}" | head -1)
+
+if [ "${CONTAINER_COUNT}" -gt 1 ]; then
+    echo "WARNING: Multiple containers found using the DAAF volume:"
+    echo "${ALL_CONTAINERS}" | sed 's/^/  /'
+    echo ""
+    echo "Using the first one: ${CONTAINER_NAME}"
+    echo "If this is wrong, stop the other containers and re-run."
+    echo ""
+fi
+
+if [ -n "${CONTAINER_NAME}" ]; then
+    echo "Found existing container: ${CONTAINER_NAME}"
+
+    # Check if it's running
+    CONTAINER_STATE=$(docker inspect --format '{{.State.Status}}' "${CONTAINER_NAME}" 2>/dev/null || echo "unknown")
+    if [ "${CONTAINER_STATE}" != "running" ]; then
+        echo "Container is ${CONTAINER_STATE}. Starting it..."
+        docker start "${CONTAINER_NAME}" >/dev/null 2>&1 || true
+
+        # Wait for readiness
+        RETRIES=0
+        MAX_RETRIES=30
+        until docker exec "${CONTAINER_NAME}" true </dev/null 2>/dev/null; do
+            RETRIES=$((RETRIES + 1))
+            if [ "${RETRIES}" -ge "${MAX_RETRIES}" ]; then
+                echo ""
+                echo "ERROR: Container did not become ready within 60 seconds."
+                echo "Try restarting Docker Desktop, then re-run:  bash migrate_daaf.sh"
+                exit 1
+            fi
+            sleep 2
+        done
+        echo "Container started."
+    else
+        echo "Container is already running."
+    fi
+else
+    echo "No existing container found. Starting one with docker compose..."
+
+    ORIGINAL_DIR_COMPOSE="$(pwd)"
+    cd "${HOST_DIR}"
+
+    if ! docker compose up -d; then
+        echo ""
+        echo "ERROR: Failed to start the DAAF container."
+        echo ""
+        echo "Common causes:"
+        echo "  - Another program is using the same ports"
+        echo "  - Docker Desktop needs more memory (Settings > Resources)"
+        echo ""
+        echo "Try restarting Docker Desktop, then re-run:  bash migrate_daaf.sh"
+        cd "${ORIGINAL_DIR_COMPOSE}"
+        exit 1
+    fi
+
+    # After docker compose up, discover the container name
+    CONTAINER_NAME=$(docker ps -a --filter "volume=${VOLUME_NAME}" --format '{{.Names}}' | head -1)
+    if [ -z "${CONTAINER_NAME}" ]; then
+        echo "ERROR: Container started but could not be found."
+        echo "Try restarting Docker Desktop, then re-run:  bash migrate_daaf.sh"
+        cd "${ORIGINAL_DIR_COMPOSE}"
+        exit 1
+    fi
+
+    cd "${ORIGINAL_DIR_COMPOSE}"
+
+    # Wait for readiness
+    RETRIES=0
+    MAX_RETRIES=30
+    until docker exec "${CONTAINER_NAME}" true </dev/null 2>/dev/null; do
+        RETRIES=$((RETRIES + 1))
+        if [ "${RETRIES}" -ge "${MAX_RETRIES}" ]; then
+            echo ""
+            echo "ERROR: Container started but is not responding after 60 seconds."
+            echo "Try restarting Docker Desktop, then re-run:  bash migrate_daaf.sh"
+            exit 1
+        fi
+        sleep 2
+    done
+    echo "Container started: ${CONTAINER_NAME}"
+fi
+
+echo ""
+
+# --- Verify DAAF is in the container ---
+if ! container_exec test -f /daaf/CLAUDE.md; then
+    echo "ERROR: DAAF does not appear to be installed in the container."
+    echo "The volume exists but /daaf/CLAUDE.md was not found."
+    echo ""
+    echo "If this is a fresh installation, use the installer instead:"
+    echo "  curl -fsSL https://raw.githubusercontent.com/${REPO}/${BRANCH}/scripts/host/install.sh | bash"
+    exit 1
+fi
+
+echo "DAAF installation verified in container."
+echo ""
+
+# =====================================================================
+# 5. DETECT ERA
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Detecting installation type"
+echo "-------------------------------------------"
+echo ""
+
+ORIGIN_URL=$(container_git remote get-url origin 2>/dev/null || true)
+
+if [ -n "${ORIGIN_URL}" ] && echo "${ORIGIN_URL}" | grep -qi "${REPO}"; then
+    DETECTED_ERA="1"
+    echo "Detected: clone-based installation (remote already configured)"
+    echo "Remote URL: ${ORIGIN_URL}"
+elif [ -n "${ORIGIN_URL}" ]; then
+    # Remote exists but points somewhere unexpected (likely a fork)
+    DETECTED_ERA="1"
+    IS_FORK=true
+    echo "Detected: clone-based installation (remote already configured)"
+    echo "Remote URL: ${ORIGIN_URL}"
+    echo ""
+    echo "NOTE: Your remote points to a location other than the official DAAF"
+    echo "repository. The migration will proceed, but you may want to verify"
+    echo "this is correct."
+else
+    DETECTED_ERA="2"
+    echo "Detected: ZIP-based installation (no remote configured)"
+    echo "Your local history will be connected to the official DAAF timeline"
+    echo "so that future updates can merge cleanly with your work."
+fi
+
+echo ""
+
+# =====================================================================
+# 6a. ERA 1 PATH (v1.0.0 -- remote exists)
+# =====================================================================
+if [ "${DETECTED_ERA}" = "1" ]; then
+    echo "-------------------------------------------"
+    echo "  Fetching upstream history"
+    echo "-------------------------------------------"
+    echo ""
+
+    echo "Running git fetch origin..."
+    if container_git_verbose fetch origin; then
+        echo "Fetch complete."
+    else
+        echo ""
+        echo "ERROR: Failed to fetch from origin."
+        echo ""
+        echo "Common causes:"
+        echo "  - No internet connection"
+        echo "  - GitHub may be experiencing an outage"
+        echo ""
+        echo "Once the issue is resolved, re-run:  bash migrate_daaf.sh"
+        exit 1
+    fi
+
+    # Ensure tracking is set up
+    container_git branch --set-upstream-to=origin/main main 2>/dev/null || true
+
+    # --- For fork users: add upstream remote for official updates ---
+    if [ "${IS_FORK}" = true ]; then
+        EXISTING_UPSTREAM=$(container_git remote get-url upstream 2>/dev/null || true)
+        if [ -z "${EXISTING_UPSTREAM}" ]; then
+            echo ""
+            echo "Your 'origin' remote points to a fork. Adding 'upstream' remote"
+            echo "for official DAAF updates..."
+            if container_git_verbose remote add upstream "https://github.com/${REPO}.git"; then
+                echo "Fetching upstream history..."
+                if container_git_verbose fetch upstream; then
+                    echo "Fetch complete."
+                else
+                    echo ""
+                    echo "WARNING: Could not fetch from upstream. The 'upstream' remote was"
+                    echo "added but the fetch failed. You can retry later:"
+                    echo "  bash run_daaf.sh bash"
+                    echo "  git fetch upstream"
+                    echo "  exit"
+                fi
+            else
+                echo ""
+                echo "WARNING: Could not add 'upstream' remote. You can add it"
+                echo "manually later:"
+                echo "  bash run_daaf.sh bash"
+                echo "  git remote add upstream https://github.com/${REPO}.git"
+                echo "  git fetch upstream"
+                echo "  exit"
+            fi
+        else
+            echo ""
+            echo "'upstream' remote already configured: ${EXISTING_UPSTREAM}"
+        fi
+    fi
+
+    echo ""
+    if [ "${IS_FORK}" = true ]; then
+        echo "Migration complete. Your installation is connected to your fork"
+        echo "(origin) and the official DAAF repository (upstream)."
+        echo ""
+        echo "update_daaf.sh will pull official updates from 'upstream' and merge"
+        echo "them with your fork's changes."
+    else
+        echo "Migration complete. Your installation is connected to upstream"
+        echo "and update_daaf.sh will work immediately."
+    fi
+    echo ""
+
+# =====================================================================
+# 6b. ERA 2 PATH (v2.0.0+ -- no remote, need graft)
+# =====================================================================
+else
+    echo "-------------------------------------------"
+    echo "  Connecting to upstream repository"
+    echo "-------------------------------------------"
+    echo ""
+
+    # --- Check if remote was already added (idempotent) ---
+    EXISTING_ORIGIN=$(container_git remote get-url origin 2>/dev/null || true)
+    if [ -n "${EXISTING_ORIGIN}" ]; then
+        echo "Remote 'origin' already exists: ${EXISTING_ORIGIN}"
+        echo "Skipping remote add (previous migration attempt detected)."
+    else
+        echo "Adding remote origin..."
+        container_git_verbose remote add origin "https://github.com/${REPO}.git"
+        echo "Remote added."
+    fi
+
+    echo ""
+
+    # --- Fetch full history ---
+    echo "Fetching upstream history (this may take a moment)..."
+    if container_git_verbose fetch origin; then
+        echo "Fetch complete."
+    else
+        echo ""
+        echo "ERROR: Failed to fetch from origin."
+        echo ""
+        echo "Common causes:"
+        echo "  - No internet connection"
+        echo "  - GitHub may be experiencing an outage"
+        echo ""
+        echo "Once the issue is resolved, re-run:  bash migrate_daaf.sh"
+        exit 1
+    fi
+
+    echo ""
+
+    # --- Find the initial (root) commit ---
+    INITIAL_COMMITS=$(container_git_verbose rev-list --max-parents=0 HEAD || true)
+
+    if [ -z "${INITIAL_COMMITS}" ]; then
+        echo ""
+        echo "ERROR: Could not find git history in the container."
+        echo "The volume exists but no git repository was found at /daaf/."
+        echo ""
+        echo "If this is a fresh installation, use the installer instead:"
+        echo "  curl -fsSL https://raw.githubusercontent.com/${REPO}/${BRANCH}/scripts/host/install.sh | bash"
+        exit 1
+    fi
+
+    # If multiple root commits exist, use the first (oldest) one
+    INITIAL_COMMIT=$(echo "${INITIAL_COMMITS}" | tail -1)
+    ROOT_COUNT=$(echo "${INITIAL_COMMITS}" | grep -c . || true)
+    ROOT_COUNT="${ROOT_COUNT:-0}"
+    if [ "${ROOT_COUNT}" -gt 1 ]; then
+        echo "NOTE: Found ${ROOT_COUNT} root commits. Using the oldest one"
+        echo "      (${INITIAL_COMMIT:0:12}) for graft matching."
+        echo ""
+    fi
+
+    # --- Check if graft is already in place (idempotent) ---
+    INITIAL_PARENT_COUNT=$(container_git_verbose cat-file -p "${INITIAL_COMMIT}" | grep -c '^parent ' || true)
+    INITIAL_PARENT_COUNT="${INITIAL_PARENT_COUNT:-0}"
+
+    if [ "${INITIAL_PARENT_COUNT}" -gt 0 ]; then
+        echo "History graft already in place (root commit has a parent)."
+        echo "Skipping graft step (previous migration completed successfully)."
+        echo ""
+    else
+        # --- Find matching upstream commit ---
+        echo "Analyzing local initial commit..."
+        echo ""
+
+        # Get the blob fingerprint of the initial local commit
+        # We compare only (blob_hash, filepath) pairs, ignoring file modes
+        LOCAL_TREE=$(container_exec sh -c "cd /daaf && git ls-tree -r '${INITIAL_COMMIT}' | awk '{print \$3, \$4}' | sort" </dev/null | tr -d '\r')
+
+        MATCHING_COMMIT=""
+        MATCH_TYPE=""
+
+        # Try known tags first, then origin/main HEAD
+        echo "Searching for matching upstream commit..."
+        echo ""
+
+        CANDIDATES="v2.0.1 v2.0.0 v1.0.0"
+
+        # Check which tags actually exist
+        VALID_CANDIDATES=""
+        for TAG in ${CANDIDATES}; do
+            if container_git rev-parse --verify "${TAG}" >/dev/null 2>&1; then
+                VALID_CANDIDATES="${VALID_CANDIDATES} ${TAG}"
+            elif container_git rev-parse --verify "origin/${TAG}" >/dev/null 2>&1; then
+                VALID_CANDIDATES="${VALID_CANDIDATES} origin/${TAG}"
+            fi
+        done
+
+        # Also try origin/main HEAD
+        VALID_CANDIDATES="${VALID_CANDIDATES} origin/main"
+
+        STEP=0
+        TOTAL_CANDIDATES=$(echo "${VALID_CANDIDATES}" | wc -w | tr -d '[:space:]')
+
+        for CANDIDATE in ${VALID_CANDIDATES}; do
+            STEP=$((STEP + 1))
+            CANDIDATE_SHA=$(container_git rev-parse "${CANDIDATE}" 2>/dev/null || true)
+            if [ -z "${CANDIDATE_SHA}" ]; then
+                continue
+            fi
+
+            printf "  Checking %s (%d/%d)..." "${CANDIDATE}" "${STEP}" "${TOTAL_CANDIDATES}"
+
+            CANDIDATE_TREE=$(container_exec sh -c "cd /daaf && git ls-tree -r '${CANDIDATE_SHA}' | awk '{print \$3, \$4}' | sort" </dev/null | tr -d '\r')
+
+            if [ "${LOCAL_TREE}" = "${CANDIDATE_TREE}" ]; then
+                MATCHING_COMMIT="${CANDIDATE_SHA}"
+                MATCH_TYPE="exact"
+                echo " EXACT MATCH"
+                echo ""
+                echo "  Matched: ${CANDIDATE} (${CANDIDATE_SHA:0:12})"
+                break
+            else
+                echo " no match"
+            fi
+        done
+
+        # If no exact match from known candidates, search all commits on origin/main
+        # This runs the entire search inside a SINGLE docker exec call to avoid
+        # the overhead of hundreds of individual docker exec invocations.
+        if [ -z "${MATCHING_COMMIT}" ]; then
+            echo ""
+            echo "  No exact match from known tags. Searching all upstream commits..."
+            echo "  (This runs inside the container and may take 30-60 seconds.)"
+            echo ""
+
+            # Build a skip list of SHAs we already checked
+            SKIP_LIST=""
+            for CANDIDATE in ${VALID_CANDIDATES}; do
+                CANDIDATE_SHA=$(container_git rev-parse "${CANDIDATE}" 2>/dev/null || true)
+                if [ -n "${CANDIDATE_SHA}" ]; then
+                    SKIP_LIST="${SKIP_LIST} ${CANDIDATE_SHA}"
+                fi
+            done
+
+            # Run the full search inside the container in one exec call.
+            # Output format: "EXACT:<sha>" or "BEST:<sha>:<overlap>:<local_count>"
+            # Progress lines go to stderr (prefixed with PROGRESS:)
+            SEARCH_RESULT=$(docker exec "${CONTAINER_NAME}" sh -c '
+                cd /daaf
+                INITIAL="'"${INITIAL_COMMIT}"'"
+                SKIP_SHAS="'"${SKIP_LIST}"'"
+
+                # Save local blob fingerprint to temp file
+                git ls-tree -r "$INITIAL" | awk "{print \$3, \$4}" | sort > /tmp/migrate_local_blobs.txt
+                LOCAL_COUNT=$(wc -l < /tmp/migrate_local_blobs.txt)
+
+                BEST_SHA=""
+                BEST_OVERLAP=0
+                TOTAL=$(git rev-list origin/main | wc -l)
+                NUM=0
+
+                for COMMIT in $(git rev-list origin/main); do
+                    NUM=$((NUM + 1))
+
+                    # Skip already-checked commits
+                    case " $SKIP_SHAS " in
+                        *" $COMMIT "*) continue ;;
+                    esac
+
+                    # Progress every 20 commits (to stderr so it does not mix with result)
+                    if [ $((NUM % 20)) -eq 0 ]; then
+                        printf "  Searching commit %d/%d...\r" "$NUM" "$TOTAL" >&2
+                    fi
+
+                    # Generate candidate blob fingerprint
+                    git ls-tree -r "$COMMIT" | awk "{print \$3, \$4}" | sort > /tmp/migrate_cand_blobs.txt
+
+                    # Exact match check (fast)
+                    if diff -q /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt >/dev/null 2>&1; then
+                        echo "EXACT:$COMMIT"
+                        rm -f /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt
+                        exit 0
+                    fi
+
+                    # Track best fuzzy match
+                    OVERLAP=$(comm -12 /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt | wc -l)
+                    if [ "$OVERLAP" -gt "$BEST_OVERLAP" ]; then
+                        BEST_OVERLAP=$OVERLAP
+                        BEST_SHA=$COMMIT
+                    fi
+                done
+
+                rm -f /tmp/migrate_local_blobs.txt /tmp/migrate_cand_blobs.txt
+                echo "BEST:$BEST_SHA:$BEST_OVERLAP:$LOCAL_COUNT"
+            ' </dev/null 2>&1 | tr -d '\r')
+
+            # Parse the result (last non-empty line is the result; earlier lines are progress)
+            RESULT_LINE=$(echo "${SEARCH_RESULT}" | grep -E '^(EXACT|BEST):' | tail -1)
+
+            if echo "${RESULT_LINE}" | grep -q '^EXACT:'; then
+                MATCHING_COMMIT=$(echo "${RESULT_LINE}" | cut -d: -f2)
+                MATCH_TYPE="exact"
+                echo ""
+                echo "  EXACT MATCH found: ${MATCHING_COMMIT:0:12}"
+            elif echo "${RESULT_LINE}" | grep -q '^BEST:'; then
+                BEST_MATCH_SHA=$(echo "${RESULT_LINE}" | cut -d: -f2)
+                BEST_MATCH_OVERLAP=$(echo "${RESULT_LINE}" | cut -d: -f3)
+                LOCAL_LINE_COUNT=$(echo "${RESULT_LINE}" | cut -d: -f4)
+
+                if [ -n "${BEST_MATCH_SHA}" ] && [ "${LOCAL_LINE_COUNT:-0}" -gt 0 ]; then
+                    OVERLAP_PCT=$((BEST_MATCH_OVERLAP * 100 / LOCAL_LINE_COUNT))
+                else
+                    OVERLAP_PCT=0
+                fi
+
+                if [ "${OVERLAP_PCT}" -ge 95 ]; then
+                    MATCHING_COMMIT="${BEST_MATCH_SHA}"
+                    MATCH_TYPE="fuzzy (${OVERLAP_PCT}% blob overlap)"
+                    echo ""
+                    echo "  Best match: ${BEST_MATCH_SHA:0:12} (${OVERLAP_PCT}% overlap)"
+                else
+                    echo ""
+                    echo "  WARNING: No upstream commit matches your initial commit well enough."
+                    if [ -n "${BEST_MATCH_SHA}" ]; then
+                        echo "  Best candidate: ${BEST_MATCH_SHA:0:12} (${OVERLAP_PCT}% overlap)"
+                    fi
+                    echo ""
+                fi
+            fi
+        fi
+
+        # Fallback: graft onto latest known tag
+        if [ -z "${MATCHING_COMMIT}" ]; then
+            echo "  Falling back to grafting onto the latest known tag..."
+
+            FALLBACK_TAG=""
+            for TAG in v2.0.1 v2.0.0 v1.0.0; do
+                if container_git rev-parse --verify "${TAG}" >/dev/null 2>&1; then
+                    FALLBACK_TAG="${TAG}"
+                    break
+                elif container_git rev-parse --verify "origin/${TAG}" >/dev/null 2>&1; then
+                    FALLBACK_TAG="origin/${TAG}"
+                    break
+                fi
+            done
+
+            if [ -n "${FALLBACK_TAG}" ]; then
+                MATCHING_COMMIT=$(container_git rev-parse "${FALLBACK_TAG}" 2>/dev/null || true)
+                MATCH_TYPE="fallback (${FALLBACK_TAG})"
+                echo ""
+                echo "  WARNING: Using fallback graft point: ${FALLBACK_TAG} (${MATCHING_COMMIT:0:12})"
+                echo "  Your local initial commit did not match any upstream commit exactly."
+                echo "  This is safe but means your git history may show a small discontinuity"
+                echo "  at the graft point. update_daaf.sh will still work correctly."
+            else
+                # Last resort: use origin/main
+                MATCHING_COMMIT=$(container_git rev-parse origin/main 2>/dev/null || true)
+                MATCH_TYPE="fallback (origin/main HEAD)"
+                echo ""
+                echo "  WARNING: No tags found. Using origin/main HEAD as graft point."
+                echo "  This is safe but means your git history may show a discontinuity."
+            fi
+        fi
+
+        echo ""
+
+        if [ -z "${MATCHING_COMMIT}" ]; then
+            echo "ERROR: Could not determine a graft point."
+            echo "This is unexpected. Please report this issue at:"
+            echo "  https://github.com/${REPO}/issues"
+            exit 1
+        fi
+
+        # --- Graft local history onto upstream ---
+        echo "Connecting local history to upstream (${MATCH_TYPE})..."
+        container_git_verbose replace --graft "${INITIAL_COMMIT}" "${MATCHING_COMMIT}"
+        echo "Graft complete."
+        echo ""
+
+        # --- Verify the graft works ---
+        echo "Verifying graft..."
+        MERGE_BASE=$(container_git_verbose merge-base HEAD origin/main || true)
+        if [ -n "${MERGE_BASE}" ]; then
+            echo "  Verified: common ancestor found (${MERGE_BASE:0:12})"
+            echo "  git merge and git pull will work correctly."
+        else
+            echo ""
+            echo "  WARNING: Could not verify graft -- no common ancestor found."
+            echo "  The graft was applied, but git merge may not work as expected."
+            echo "  This is unusual. You can re-run:  bash migrate_daaf.sh"
+            echo "  If the problem persists, report it at:"
+            echo "    https://github.com/${REPO}/issues"
+        fi
+        echo ""
+
+        # --- Fix file permissions in the index ---
+        echo "Fixing file permissions (ZIP downloads don't preserve executable bits)..."
+
+        # Get files that are 100755 upstream but 100644 locally
+        UPSTREAM_EXEC=$(container_exec sh -c "cd /daaf && git ls-tree -r '${MATCHING_COMMIT}' | grep '^100755' | awk '{print \$4}' | sort" </dev/null | tr -d '\r')
+
+        PERM_FIXED=0
+        PERM_FILES=""
+        if [ -n "${UPSTREAM_EXEC}" ]; then
+            while IFS= read -r FILEPATH; do
+                [ -z "${FILEPATH}" ] && continue
+                # Check if the file exists locally and has wrong mode
+                LOCAL_MODE=$(container_git ls-files -s -- "${FILEPATH}" 2>/dev/null | awk '{print $1}' | tr -d '\r' || true)
+                if [ "${LOCAL_MODE}" = "100644" ]; then
+                    container_git update-index --chmod=+x "${FILEPATH}" 2>/dev/null || true
+                    PERM_FILES="${PERM_FILES} ${FILEPATH}"
+                    PERM_FIXED=$((PERM_FIXED + 1))
+                fi
+            done <<< "${UPSTREAM_EXEC}"
+        fi
+
+        if [ "${PERM_FIXED}" -gt 0 ]; then
+            echo "  Fixed permissions on ${PERM_FIXED} file(s)."
+            echo ""
+            echo "Committing permission fixes..."
+            # Commit only the permission changes already staged by update-index
+            # (do NOT use 'git add -A' which could sweep in unrelated changes)
+            container_git_verbose commit --allow-empty -m "Migration: normalize file permissions"
+            echo "Permission fixes committed."
+        else
+            echo "  No permission fixes needed."
+        fi
+
+        echo ""
+    fi
+
+    # --- Set upstream tracking ---
+    echo "Setting upstream tracking branch..."
+    container_git branch --set-upstream-to=origin/main main 2>/dev/null || true
+    echo "Tracking set: main -> origin/main"
+    echo ""
+
+    echo "Migration complete. Your local history is now connected to the"
+    echo "official DAAF timeline. Future updates will merge cleanly."
+    echo ""
+fi
+
+# =====================================================================
+# 7. OFFER UPDATE
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Run update?"
+echo "-------------------------------------------"
+echo ""
+echo "Your installation is now connected to the upstream repository."
+echo "Would you like to pull the latest updates now?"
+echo ""
+
+if [ "${IS_INTERACTIVE}" = "true" ]; then
+    CHOICE=$(prompt_choice "  Run update_daaf.sh now? [y/n]: " "y n")
+else
+    # Non-interactive -- skip the update
+    echo "  (Non-interactive mode detected -- skipping update. Run it manually.)"
+    CHOICE="n"
+fi
+
+UPDATE_RAN=false
+if [ "${CHOICE}" = "y" ]; then
+    echo ""
+    ORIGINAL_DIR_UPDATE="$(pwd)"
+    cd "${HOST_DIR}"
+    if DAAF_NESTED=1 bash update_daaf.sh; then
+        UPDATE_RAN=true
+    else
+        UPDATE_RAN=false
+    fi
+    cd "${ORIGINAL_DIR_UPDATE}"
+fi
+
+# =====================================================================
+# 8. SUCCESS MESSAGE
+# =====================================================================
+echo ""
+echo "=========================================="
+echo "  Migration complete!"
+echo "=========================================="
+echo ""
+echo "Your DAAF installation has been migrated to support the new update"
+echo "infrastructure. Here is what was done:"
+echo ""
+if [ "${DETECTED_ERA}" = "1" ]; then
+    echo "  - Downloaded host utility scripts to: ${HOST_DIR}/"
+    echo "  - Created a full backup of your Docker volume"
+    echo "  - Fetched latest upstream history into your existing repo"
+else
+    echo "  - Downloaded host utility scripts to: ${HOST_DIR}/"
+    echo "  - Created a full backup of your Docker volume"
+    echo "  - Added remote origin pointing to the official DAAF repository"
+    echo "  - Connected your local git history to the official DAAF timeline"
+    echo "  - Fixed file permissions to match upstream"
+    echo "  - Set upstream tracking (main -> origin/main)"
+fi
+echo ""
+if [ "${CHOICE}" = "y" ] && [ "${UPDATE_RAN}" = true ]; then
+    echo "Going forward, you can update DAAF with:"
+elif [ "${CHOICE}" = "y" ] && [ "${UPDATE_RAN}" = false ]; then
+    echo "The update step encountered an issue (see above). Once resolved,"
+    echo "you can update DAAF with:"
+elif [ "${CHOICE}" = "n" ] && [ "${IS_INTERACTIVE}" = "true" ]; then
+    # User chose not to update
+    echo "To pull the latest updates when you're ready:"
+elif [ "${IS_INTERACTIVE}" != "true" ]; then
+    # Non-interactive mode -- update was skipped automatically
+    echo "IMPORTANT: The update step was skipped because the script was run"
+    echo "non-interactively. To pull the latest updates, run:"
+else
+    echo "Going forward, you can update DAAF with:"
+fi
+echo "  cd ${HOST_DIR}"
+echo "  bash update_daaf.sh"
+echo ""
+echo "Other available scripts:"
+echo "  bash run_daaf.sh               Launch Claude Code"
+echo "  bash backup_daaf.sh            Back up the Docker volume"
+echo "  bash restore_from_backup.sh    Restore from a backup"
+echo "  bash rebuild_daaf.sh           Rebuild the Docker image"
+echo "  bash view_logs.sh              Browse session logs"
+echo "  bash view_notebooks.sh         Browse and edit marimo notebooks"
+echo "  bash run_vscode.sh             Open VS Code in your browser (code-server)"
+echo ""
diff --git a/scripts/host/rebuild_daaf.ps1 b/scripts/host/rebuild_daaf.ps1
new file mode 100644
index 0000000..6448ed6
--- /dev/null
+++ b/scripts/host/rebuild_daaf.ps1
@@ -0,0 +1,258 @@
+# ============================================================================
+# DAAF Rebuild Utility (Windows PowerShell)
+# ============================================================================
+# Copies the current Dockerfile and docker-compose.yml from the container
+# back to the host build directory, then rebuilds the Docker image.
+#
+# Use this after:
+#   - Adding Python packages via DAAF's Framework Development mode
+#   - Running update_daaf.ps1 when it reports Dockerfile or docker-compose.yml changes
+#   - Any other change to build files inside the container
+#
+# Why this is needed:
+#   The Dockerfile and docker-compose.yml live in two places - inside the Docker
+#   volume (where DAAF and update_daaf.ps1 modify them) and on the host (where docker
+#   compose reads them for builds). This script bridges the gap so you don't
+#   have to remember the manual docker cp commands.
+#
+# Usage:
+#   cd daaf-docker
+#   .\rebuild_daaf.ps1
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to close this window"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*inspect*" { return }
+            "*cp *" { return }
+            "*compose build*" { return }
+            "*compose up*" { return }
+            "*compose exec*true*" { return }
+            "*compose exec*test -f*" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/rebuild_daaf.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+$ContainerName = "daaf-daaf-docker-1"
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  DAAF Rebuild"
+Write-Host "=========================================="
+Write-Host ""
+
+# --- Preflight ---
+if (-not (Test-Path "docker-compose.yml")) {
+    Write-Host "ERROR: docker-compose.yml not found in the current directory." -ForegroundColor Red
+    Write-Host "Please run this script from your daaf-docker folder."
+    Wait-AndExit 1
+}
+
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from PowerShell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Check container exists (running or stopped) ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker inspect $ContainerName 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Container '$ContainerName' not found." -ForegroundColor Red
+    Write-Host "Have you run the DAAF installer? The container must exist (running or stopped)"
+    Write-Host "for this script to copy the updated files from it."
+    Wait-AndExit 1
+}
+
+# --- Copy build files from container to host ---
+Write-Host "[1/3] Copying build files from container to host..."
+
+# Back up current host files so we can show what changed
+$DockerfileChanged = $false
+$ComposefileChanged = $false
+
+if (Test-Path "Dockerfile") {
+    Copy-Item "Dockerfile" "Dockerfile.pre-rebuild" -Force
+}
+if (Test-Path "docker-compose.yml") {
+    Copy-Item "docker-compose.yml" "docker-compose.yml.pre-rebuild" -Force
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker cp "${ContainerName}:/daaf/Dockerfile" ./Dockerfile
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Failed to copy Dockerfile from container." -ForegroundColor Red
+    Write-Host "Make sure DAAF is installed in the container (run the installer if needed)."
+    Wait-AndExit 1
+}
+Write-Host "      Copied Dockerfile"
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker cp "${ContainerName}:/daaf/docker-compose.yml" ./docker-compose.yml
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Failed to copy docker-compose.yml from container." -ForegroundColor Red
+    Wait-AndExit 1
+}
+Write-Host "      Copied docker-compose.yml"
+
+# --- Show what changed ---
+Write-Host ""
+if (Test-Path "Dockerfile.pre-rebuild") {
+    $OldHash = (Get-FileHash "Dockerfile.pre-rebuild").Hash
+    $NewHash = (Get-FileHash "Dockerfile").Hash
+    if ($OldHash -eq $NewHash) {
+        Write-Host "      Dockerfile: no changes detected"
+    } else {
+        $DockerfileChanged = $true
+        Write-Host "      Dockerfile: UPDATED"
+    }
+} else {
+    $DockerfileChanged = $true
+    Write-Host "      Dockerfile: new (no previous version on host)"
+}
+
+if (Test-Path "docker-compose.yml.pre-rebuild") {
+    $OldHash = (Get-FileHash "docker-compose.yml.pre-rebuild").Hash
+    $NewHash = (Get-FileHash "docker-compose.yml").Hash
+    if ($OldHash -eq $NewHash) {
+        Write-Host "      docker-compose.yml: no changes detected"
+    } else {
+        $ComposefileChanged = $true
+        Write-Host "      docker-compose.yml: UPDATED"
+    }
+} else {
+    $ComposefileChanged = $true
+    Write-Host "      docker-compose.yml: new (no previous version on host)"
+}
+
+if ((-not $DockerfileChanged) -and (-not $ComposefileChanged)) {
+    Write-Host ""
+    Write-Host "      No changes detected - the host files already match the container."
+    Write-Host "      Rebuilding anyway to make sure the image is up to date."
+}
+
+# --- Rebuild ---
+Write-Host ""
+Write-Host "[2/3] Rebuilding Docker image (this may take a few minutes if packages changed)..."
+Write-Host ""
+# Build and start are split into two commands so that --progress plain can be
+# applied to the build step (where it is universally supported) without relying
+# on `docker compose up --progress`, which is rejected as "unknown flag" on
+# Docker Compose versions prior to ~v2.27.
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose build --progress plain
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Rebuild failed. Check the output above for details." -ForegroundColor Red
+    if (Test-Path "Dockerfile.pre-rebuild") {
+        Write-Host "Your previous Dockerfile was saved as Dockerfile.pre-rebuild"
+    }
+    Wait-AndExit 1
+}
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose up -d
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to start the container after rebuild. Check the output above for details." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Wait for container to be ready ---
+Write-Host ""
+Write-Host "      Waiting for container to be ready..."
+$retries = 0
+$maxRetries = 30
+$readyLog = [System.IO.Path]::GetTempFileName()
+while ($retries -lt $maxRetries) {
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose exec -T daaf-docker true 2>> $readyLog
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -eq 0) { break }
+    $retries++
+    Start-Sleep -Seconds 2
+}
+if ($retries -ge $maxRetries) {
+    Write-Host "ERROR: Container did not become ready within 60 seconds." -ForegroundColor Red
+    if ((Test-Path $readyLog) -and (Get-Item $readyLog).Length -gt 0) {
+        Write-Host "  Docker reported:" -ForegroundColor Red
+        Get-Content $readyLog -Tail 5 | ForEach-Object { Write-Host "    $_" -ForegroundColor Red }
+        Write-Host ""
+    }
+    Write-Host "Check Docker Desktop for errors."
+    Remove-Item $readyLog -ErrorAction SilentlyContinue
+    Wait-AndExit 1
+}
+Remove-Item $readyLog -ErrorAction SilentlyContinue
+
+# --- Verify ---
+Write-Host ""
+Write-Host "[3/3] Verifying DAAF installation..."
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md 2>&1 | Out-Null
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "WARNING: Rebuild completed but DAAF files may not be intact." -ForegroundColor Yellow
+    Write-Host "Try entering the container with: .\run_daaf.ps1 bash"
+    Wait-AndExit 1
+}
+
+Write-Host "      DAAF verified."
+
+# Clean up pre-rebuild backups on success
+if (Test-Path "Dockerfile.pre-rebuild") { Remove-Item "Dockerfile.pre-rebuild" -Force }
+if (Test-Path "docker-compose.yml.pre-rebuild") { Remove-Item "docker-compose.yml.pre-rebuild" -Force }
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  Rebuild complete!"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "The Docker image has been rebuilt with the latest Dockerfile."
+Write-Host "To launch DAAF:  .\run_daaf.ps1"
+Write-Host ""
+Wait-AndExit 0
diff --git a/scripts/host/rebuild_daaf.sh b/scripts/host/rebuild_daaf.sh
new file mode 100755
index 0000000..7152d1c
--- /dev/null
+++ b/scripts/host/rebuild_daaf.sh
@@ -0,0 +1,226 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Rebuild Utility (macOS / Linux)
+# ============================================================================
+# Copies the current Dockerfile and docker-compose.yml from the container
+# back to the host build directory, then rebuilds the Docker image.
+#
+# Use this after:
+#   - Adding Python packages via DAAF's Framework Development mode
+#   - Running update_daaf.sh when it reports Dockerfile or docker-compose.yml changes
+#   - Any other change to build files inside the container
+#
+# Why this is needed:
+#   The Dockerfile and docker-compose.yml live in two places -- inside the Docker
+#   volume (where DAAF and update_daaf.sh modify them) and on the host (where docker
+#   compose reads them for builds). This script bridges the gap so you don't
+#   have to remember the manual docker cp commands.
+#
+# Usage:
+#   cd daaf-docker
+#   bash rebuild_daaf.sh
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script like update_daaf.sh).
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+CONTAINER_NAME="daaf-daaf-docker-1"
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            "inspect"*) return 0 ;;
+            "cp"*) return 0 ;;
+            *"compose build"*) return 0 ;;
+            *"compose up"*) return 0 ;;
+            *"compose exec"*"true"*) return 0 ;;
+            *"compose exec"*"test -f"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/rebuild_daaf.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+echo ""
+echo "=========================================="
+echo "  DAAF Rebuild"
+echo "=========================================="
+echo ""
+
+# --- Preflight ---
+if [ ! -f "docker-compose.yml" ]; then
+    echo "ERROR: docker-compose.yml not found in the current directory."
+    echo "Please run this script from your daaf-docker folder."
+    exit 1
+fi
+
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal."
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start it and try again."
+    exit 1
+fi
+
+# --- Check container exists (running or stopped) ---
+if ! docker inspect "${CONTAINER_NAME}" &> /dev/null; then
+    echo "ERROR: Container '${CONTAINER_NAME}' not found."
+    echo "Have you run the DAAF installer? The container must exist (running or stopped)"
+    echo "for this script to copy the updated files from it."
+    exit 1
+fi
+
+# --- Copy build files from container to host ---
+echo "[1/3] Copying build files from container to host..."
+
+# Back up current host files so we can show what changed
+DOCKERFILE_CHANGED="no"
+COMPOSEFILE_CHANGED="no"
+
+if [ -f "Dockerfile" ]; then
+    cp Dockerfile Dockerfile.pre-rebuild
+fi
+if [ -f "docker-compose.yml" ]; then
+    cp docker-compose.yml docker-compose.yml.pre-rebuild
+fi
+
+if ! docker cp "${CONTAINER_NAME}:/daaf/Dockerfile" ./Dockerfile; then
+    echo "ERROR: Failed to copy Dockerfile from container."
+    echo "Make sure DAAF is installed in the container (run the installer if needed)."
+    exit 1
+fi
+echo "      Copied Dockerfile"
+
+if ! docker cp "${CONTAINER_NAME}:/daaf/docker-compose.yml" ./docker-compose.yml; then
+    echo "ERROR: Failed to copy docker-compose.yml from container."
+    exit 1
+fi
+echo "      Copied docker-compose.yml"
+
+# --- Show what changed ---
+echo ""
+if [ -f "Dockerfile.pre-rebuild" ]; then
+    if diff -q Dockerfile.pre-rebuild Dockerfile &> /dev/null; then
+        echo "      Dockerfile: no changes detected"
+    else
+        DOCKERFILE_CHANGED="yes"
+        echo "      Dockerfile: UPDATED"
+    fi
+else
+    DOCKERFILE_CHANGED="yes"
+    echo "      Dockerfile: new (no previous version on host)"
+fi
+
+if [ -f "docker-compose.yml.pre-rebuild" ]; then
+    if diff -q docker-compose.yml.pre-rebuild docker-compose.yml &> /dev/null; then
+        echo "      docker-compose.yml: no changes detected"
+    else
+        COMPOSEFILE_CHANGED="yes"
+        echo "      docker-compose.yml: UPDATED"
+    fi
+else
+    COMPOSEFILE_CHANGED="yes"
+    echo "      docker-compose.yml: new (no previous version on host)"
+fi
+
+if [ "${DOCKERFILE_CHANGED}" = "no" ] && [ "${COMPOSEFILE_CHANGED}" = "no" ]; then
+    echo ""
+    echo "      No changes detected -- the host files already match the container."
+    echo "      Rebuilding anyway to make sure the image is up to date."
+fi
+
+# --- Rebuild ---
+echo ""
+echo "[2/3] Rebuilding Docker image (this may take a few minutes if packages changed)..."
+echo ""
+# Build and start are split into two commands so that --progress plain can be
+# applied to the build step (where it is universally supported) without relying
+# on `docker compose up --progress`, which is rejected as "unknown flag" on
+# Docker Compose versions prior to ~v2.27.
+if ! docker compose build --progress plain; then
+    echo ""
+    echo "ERROR: Rebuild failed. Check the output above for details."
+    if [ -f "Dockerfile.pre-rebuild" ]; then
+        echo "Your previous Dockerfile was saved as Dockerfile.pre-rebuild"
+    fi
+    exit 1
+fi
+echo ""
+echo "Starting container..."
+if ! docker compose up -d; then
+    echo ""
+    echo "ERROR: Failed to start the container after rebuild. Check the output above for details."
+    exit 1
+fi
+
+# --- Wait for container to be ready ---
+echo ""
+echo "      Waiting for container to be ready..."
+RETRIES=0
+MAX_RETRIES=30
+READY_LOG=$(mktemp)
+until docker compose exec -T daaf-docker true </dev/null 2>>"$READY_LOG"; do
+    RETRIES=$((RETRIES + 1))
+    if [ "${RETRIES}" -ge "${MAX_RETRIES}" ]; then
+        echo "ERROR: Container did not become ready within 60 seconds." >&2
+        if [ -s "$READY_LOG" ]; then
+            echo "  Docker reported:" >&2
+            tail -5 "$READY_LOG" | sed 's/^/    /' >&2
+            echo "" >&2
+        fi
+        echo "Check Docker Desktop for errors." >&2
+        rm -f "$READY_LOG"
+        exit 1
+    fi
+    sleep 2
+done
+rm -f "$READY_LOG"
+
+# --- Verify ---
+echo ""
+echo "[3/3] Verifying DAAF installation..."
+if ! docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md </dev/null 2>/dev/null; then
+    echo ""
+    echo "WARNING: Rebuild completed but DAAF files may not be intact."
+    echo "Try entering the container with: bash run_daaf.sh bash"
+    exit 1
+fi
+
+echo "      DAAF verified."
+
+# Clean up pre-rebuild backups on success
+rm -f Dockerfile.pre-rebuild docker-compose.yml.pre-rebuild
+
+echo ""
+echo "=========================================="
+echo "  Rebuild complete!"
+echo "=========================================="
+echo ""
+echo "The Docker image has been rebuilt with the latest Dockerfile."
+echo "To launch DAAF:  bash run_daaf.sh"
+echo ""
diff --git a/scripts/host/restore_from_backup.ps1 b/scripts/host/restore_from_backup.ps1
new file mode 100644
index 0000000..075c0c6
--- /dev/null
+++ b/scripts/host/restore_from_backup.ps1
@@ -0,0 +1,317 @@
+# ============================================================================
+# DAAF Restore from Backup (Windows PowerShell)
+# ============================================================================
+# Restores a DAAF Docker volume from a previously created backup.
+#
+# Usage:
+#   cd daaf-docker
+#   .\restore_from_backup.ps1
+#
+# The script searches the current directory for backup folders matching the
+# naming pattern produced by backup_daaf.ps1 (e.g., 2026-04-21_daaf_backup\)
+# and presents them for interactive selection.
+#
+# WARNING: Restoring is a DESTRUCTIVE operation. The entire contents of the
+# Docker volume are erased and replaced with the backup contents.
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*volume inspect*" { return }
+            "*ps --filter*" { return }
+            "*run --rm*rm -rf*" { return }
+            "*run --rm*cp -a*" { return }
+            "*run --rm*find /dest*" {
+                Write-Output "42"
+                return
+            }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/restore_from_backup.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  DAAF Restore from Backup"
+Write-Host "=========================================="
+Write-Host ""
+
+# --- Preflight ---
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from PowerShell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+$VolumeName = "daaf_daaf-data"
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker volume inspect $VolumeName 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker volume '$VolumeName' not found." -ForegroundColor Red
+    Write-Host "Have you run the DAAF installer yet?"
+    Wait-AndExit 1
+}
+
+# --- Check for running containers using the volume ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$RunningContainers = @(docker ps --filter "volume=$VolumeName" --format '{{.Names}}' 2>&1)
+$ErrorActionPreference = $savedEAP
+$RunningContainers = @($RunningContainers | Where-Object { $_ -and $_.Trim() -ne "" })
+
+if ($RunningContainers.Count -gt 0) {
+    Write-Host "The DAAF container is currently running:"
+    Write-Host ""
+    foreach ($name in $RunningContainers) {
+        Write-Host "  - $name"
+    }
+    Write-Host ""
+    Write-Host "The container must be stopped before restoring. This will terminate"
+    Write-Host "any Claude Code sessions currently in progress."
+    Write-Host ""
+    $StopChoice = Read-Host "Stop the container now? (y/n)"
+    if ($StopChoice -eq "y" -or $StopChoice -eq "Y") {
+        Write-Host ""
+        Write-Host "Stopping containers..."
+        $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+        $null = docker compose down 2>&1
+        $ErrorActionPreference = $savedEAP
+        if ($LASTEXITCODE -ne 0) {
+            Write-Host "ERROR: Failed to stop containers." -ForegroundColor Red
+            Wait-AndExit 1
+        }
+        Write-Host "Containers stopped."
+        Write-Host ""
+    } else {
+        Write-Host ""
+        Write-Host "Restore cancelled. Stop the container manually and try again:"
+        Write-Host "  docker compose down"
+        Wait-AndExit 0
+    }
+}
+
+# --- Find backup folders ---
+$Backups = @(Get-ChildItem -Directory | Where-Object {
+    $_.Name -match '^\d{4}-\d{2}-\d{2}[a-z]?_daaf_backup$'
+} | Sort-Object Name -Descending)
+
+if ($Backups.Count -eq 0) {
+    if ($env:DAAF_DRY_RUN -eq "1") {
+        Write-Host "[DRY-RUN] No backup folders found (expected in CI)."
+        Write-Host ""
+        Write-Host "=========================================="
+        Write-Host "  Restore dry-run complete!"
+        Write-Host "=========================================="
+        Wait-AndExit 0
+    }
+    Write-Host "No backup folders found in the current directory." -ForegroundColor Red
+    Write-Host ""
+    Write-Host "Backup folders are created by backup_daaf.ps1 and follow the pattern:"
+    Write-Host "  2026-04-21_daaf_backup\"
+    Write-Host "  2026-04-21a_daaf_backup\"
+    Write-Host ""
+    Write-Host "Make sure you are running this script from your daaf-docker folder."
+    Wait-AndExit 1
+}
+
+# --- Display backups (newest first, already sorted descending) ---
+Write-Host "Available backups (newest first):"
+Write-Host ""
+for ($i = 0; $i -lt $Backups.Count; $i++) {
+    $dir = $Backups[$i]
+    $fileCount = @(Get-ChildItem -Path $dir.FullName -Recurse -File -Force -ErrorAction SilentlyContinue).Count
+    $sizeBytes = (Get-ChildItem -Path $dir.FullName -Recurse -Force -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum).Sum
+    if ($null -eq $sizeBytes) { $sizeBytes = 0 }
+    if ($sizeBytes -ge 1073741824) {
+        $sizeStr = "{0:N1}G" -f ($sizeBytes / 1073741824)
+    } elseif ($sizeBytes -ge 1048576) {
+        $sizeStr = "{0:N0}M" -f ($sizeBytes / 1048576)
+    } else {
+        $sizeStr = "{0:N0}K" -f ($sizeBytes / 1024)
+    }
+    Write-Host ("  {0}) {1}  ({2} files, {3})" -f ($i + 1), $dir.Name, $fileCount, $sizeStr)
+}
+Write-Host ""
+
+# --- Dry-run early exit ---
+if ($env:DAAF_DRY_RUN -eq "1") {
+    Write-Host "[DRY-RUN] Would present interactive selection for $($Backups.Count) backup(s)."
+    Write-Host ""
+    Write-Host "=========================================="
+    Write-Host "  Restore dry-run complete!"
+    Write-Host "=========================================="
+    Wait-AndExit 0
+}
+
+# --- User selects backup ---
+$Choice = Read-Host "Enter backup number to restore (1-$($Backups.Count))"
+
+$ChoiceNum = 0
+if (-not [int]::TryParse($Choice, [ref]$ChoiceNum) -or $ChoiceNum -lt 1 -or $ChoiceNum -gt $Backups.Count) {
+    Write-Host "" -ForegroundColor Red
+    Write-Host "ERROR: Invalid selection '$Choice'. Please enter a number between 1 and $($Backups.Count)." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+$Selected = $Backups[$ChoiceNum - 1]
+$SelectedName = $Selected.Name
+$SelectedPath = $Selected.FullName
+
+Write-Host ""
+Write-Host "Selected: $SelectedName"
+
+# --- Count source files ---
+Write-Host ""
+Write-Host "Scanning backup..."
+$TotalFiles = @(Get-ChildItem -Path $SelectedPath -Recurse -File -Force -ErrorAction SilentlyContinue).Count
+$TotalSizeBytes = (Get-ChildItem -Path $SelectedPath -Recurse -Force -ErrorAction SilentlyContinue | Measure-Object -Property Length -Sum).Sum
+if ($null -eq $TotalSizeBytes) { $TotalSizeBytes = 0 }
+if ($TotalSizeBytes -ge 1073741824) {
+    $TotalSizeStr = "{0:N1}G" -f ($TotalSizeBytes / 1073741824)
+} elseif ($TotalSizeBytes -ge 1048576) {
+    $TotalSizeStr = "{0:N0}M" -f ($TotalSizeBytes / 1048576)
+} else {
+    $TotalSizeStr = "{0:N0}K" -f ($TotalSizeBytes / 1024)
+}
+Write-Host "Found $TotalFiles files ($TotalSizeStr) to restore."
+
+# --- Destructive warning ---
+Write-Host ""
+Write-Host "==========================================" -ForegroundColor Red
+Write-Host "  *** WARNING: DESTRUCTIVE OPERATION ***" -ForegroundColor Red
+Write-Host "==========================================" -ForegroundColor Red
+Write-Host ""
+Write-Host "This will COMPLETELY ERASE the current contents of your"
+Write-Host "DAAF Docker volume and replace them with the backup."
+Write-Host ""
+Write-Host "All existing files, git history, research data, and"
+Write-Host "configuration in the Docker volume will be permanently"
+Write-Host "deleted and overwritten by the backup contents."
+Write-Host ""
+Write-Host "Source:      $SelectedName\ ($TotalFiles files, $TotalSizeStr)"
+Write-Host "Destination: Docker volume '$VolumeName'"
+Write-Host ""
+$Confirm = Read-Host "Type RESTORE to confirm, or anything else to cancel"
+
+if ($Confirm -ne "RESTORE") {
+    Write-Host ""
+    Write-Host "Restore cancelled."
+    Wait-AndExit 0
+}
+
+Write-Host ""
+
+# --- Step 1: Clear the Docker volume ---
+Write-Host "Clearing Docker volume..."
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker run --rm -v "${VolumeName}:/dest" busybox sh -c 'rm -rf /dest/* /dest/.[!.]* /dest/..?*' 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Failed to clear Docker volume." -ForegroundColor Red
+    Write-Host "The volume may be in an inconsistent state."
+    Wait-AndExit 1
+}
+Write-Host "Volume cleared."
+Write-Host ""
+
+# --- Step 2: Copy backup into volume ---
+Write-Host "Copying backup into Docker volume..."
+Write-Host "  This may take a few minutes for large backups."
+Write-Host ""
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker run --rm -v "${SelectedPath}:/source:ro" -v "${VolumeName}:/dest" busybox sh -c "cp -a /source/. /dest/" 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "" -ForegroundColor Red
+    Write-Host "ERROR: File copy failed." -ForegroundColor Red
+    Write-Host "The Docker volume may be in an inconsistent state."
+    Write-Host "You may want to re-run this restore or reinstall DAAF."
+    Wait-AndExit 1
+}
+Write-Host "Copy complete."
+Write-Host ""
+
+# --- Verify ---
+Write-Host "Verifying restore..."
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$VerifyOutput = docker run --rm -v "${VolumeName}:/dest:ro" busybox sh -c 'find /dest -type f | wc -l' 2>&1
+$ErrorActionPreference = $savedEAP
+$RestoredCount = 0
+if ($null -ne $VerifyOutput) {
+    $null = [int]::TryParse(($VerifyOutput | Out-String).Trim(), [ref]$RestoredCount)
+}
+
+if ($RestoredCount -eq 0) {
+    Write-Host ""
+    Write-Host "ERROR: Verification failed -- 0 files found in restored volume." -ForegroundColor Red
+    Write-Host "The restore may have failed. Consider re-running or reinstalling DAAF."
+    Wait-AndExit 1
+}
+
+Write-Host "Verified: $RestoredCount files in restored volume."
+
+# --- File count comparison ---
+if ($TotalFiles -gt 0 -and $RestoredCount -gt 0) {
+    $Diff = [math]::Abs($TotalFiles - $RestoredCount)
+    $Tolerance = [math]::Max(1, [math]::Floor($TotalFiles / 100))
+    if ($Diff -gt $Tolerance) {
+        Write-Host ""
+        Write-Host "WARNING: File count mismatch." -ForegroundColor Yellow
+        Write-Host "         Backup: $TotalFiles files, Restored: $RestoredCount files (difference: $Diff)"
+        Write-Host "         The restore may be incomplete."
+    }
+}
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  Restore complete!"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "Restored: $SelectedName"
+Write-Host "Files:    $RestoredCount files in volume"
+Write-Host ""
+Write-Host "You can now start DAAF with:"
+Write-Host "  .\run_daaf.ps1"
+Write-Host ""
+Wait-AndExit 0
diff --git a/scripts/host/restore_from_backup.sh b/scripts/host/restore_from_backup.sh
new file mode 100755
index 0000000..dafda62
--- /dev/null
+++ b/scripts/host/restore_from_backup.sh
@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Restore from Backup (macOS / Linux)
+# ============================================================================
+# Restores a DAAF Docker volume from a previously created backup.
+#
+# Usage:
+#   cd daaf-docker
+#   bash restore_from_backup.sh
+#
+# The script searches the current directory for backup folders matching the
+# naming pattern produced by backup_daaf.sh (e.g., 2026-04-21_daaf_backup/)
+# and presents them for interactive selection.
+#
+# WARNING: Restoring is a DESTRUCTIVE operation. The entire contents of the
+# Docker volume are erased and replaced with the backup contents.
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script) and CI environments.
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Configuration ---
+VOLUME_NAME="daaf_daaf-data"
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"volume inspect"*) return 0 ;;
+            *"ps --filter"*) return 0 ;;
+            *"run --rm"*"rm -rf"*) return 0 ;;
+            *"run --rm"*"cp -a"*) return 0 ;;
+            *"run --rm"*"find /dest"*)
+                echo "42"
+                return 0
+                ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/restore_from_backup.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+echo ""
+echo "=========================================="
+echo "  DAAF Restore from Backup"
+echo "=========================================="
+echo ""
+
+# --- Preflight ---
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." >&2
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/" >&2
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start it and try again." >&2
+    exit 1
+fi
+
+if ! docker volume inspect "${VOLUME_NAME}" &> /dev/null; then
+    echo "ERROR: Docker volume '${VOLUME_NAME}' not found." >&2
+    echo "Have you run the DAAF installer yet?" >&2
+    exit 1
+fi
+
+# --- Check for running containers using the volume ---
+RUNNING_CONTAINERS=""
+RUNNING_CONTAINERS=$(docker ps --filter "volume=${VOLUME_NAME}" --format '{{.Names}}' 2>/dev/null || true)
+if [ -n "${RUNNING_CONTAINERS}" ]; then
+    echo "The DAAF container is currently running:"
+    echo ""
+    echo "${RUNNING_CONTAINERS}" | while IFS= read -r name; do
+        echo "  - ${name}"
+    done
+    echo ""
+    echo "The container must be stopped before restoring. This will terminate"
+    echo "any Claude Code sessions currently in progress."
+    echo ""
+    read -r -p "Stop the container now? (y/n): " STOP_CHOICE
+    if [ "${STOP_CHOICE}" = "y" ] || [ "${STOP_CHOICE}" = "Y" ]; then
+        echo ""
+        echo "Stopping containers..."
+        if ! docker compose down; then
+            echo "ERROR: Failed to stop containers." >&2
+            exit 1
+        fi
+        echo "Containers stopped."
+        echo ""
+    else
+        echo ""
+        echo "Restore cancelled. Stop the container manually and try again:"
+        echo "  docker compose down"
+        exit 0
+    fi
+fi
+
+# --- Find backup folders ---
+BACKUPS=()
+shopt -s nullglob
+for dir in ./[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]*_daaf_backup; do
+    if [ -d "${dir}" ]; then
+        BACKUPS+=("${dir}")
+    fi
+done
+shopt -u nullglob
+
+if [ ${#BACKUPS[@]} -eq 0 ]; then
+    if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+        echo "[DRY-RUN] No backup folders found (expected in CI)."
+        echo ""
+        echo "=========================================="
+        echo "  Restore dry-run complete!"
+        echo "=========================================="
+        exit 0
+    fi
+    echo "No backup folders found in the current directory." >&2
+    echo "" >&2
+    echo "Backup folders are created by backup_daaf.sh and follow the pattern:" >&2
+    echo "  2026-04-21_daaf_backup/" >&2
+    echo "  2026-04-21a_daaf_backup/" >&2
+    echo "" >&2
+    echo "Make sure you are running this script from your daaf-docker folder." >&2
+    exit 1
+fi
+
+# --- Display backups (newest first) ---
+# Reverse the array so newest (alphabetically last) appears first
+SORTED_BACKUPS=()
+for ((i=${#BACKUPS[@]}-1; i>=0; i--)); do
+    SORTED_BACKUPS+=("${BACKUPS[$i]}")
+done
+
+echo "Available backups (newest first):"
+echo ""
+for i in "${!SORTED_BACKUPS[@]}"; do
+    dir="${SORTED_BACKUPS[$i]}"
+    name="$(basename "${dir}")"
+    count=$(find "${dir}" -type f 2>/dev/null | wc -l | tr -d '[:space:]') || count="?"
+    size=$(du -sh "${dir}" 2>/dev/null | awk '{print $1}') || size="?"
+    printf "  %d) %s  (%s files, %s)\n" "$((i + 1))" "${name}" "${count}" "${size}"
+done
+echo ""
+
+# --- Dry-run early exit ---
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    echo "[DRY-RUN] Would present interactive selection for ${#SORTED_BACKUPS[@]} backup(s)."
+    echo ""
+    echo "=========================================="
+    echo "  Restore dry-run complete!"
+    echo "=========================================="
+    exit 0
+fi
+
+# --- User selects backup ---
+read -r -p "Enter backup number to restore (1-${#SORTED_BACKUPS[@]}): " CHOICE
+
+if ! [[ "${CHOICE}" =~ ^[0-9]+$ ]] || [ "${CHOICE}" -lt 1 ] || [ "${CHOICE}" -gt "${#SORTED_BACKUPS[@]}" ]; then
+    echo "" >&2
+    echo "ERROR: Invalid selection '${CHOICE}'. Please enter a number between 1 and ${#SORTED_BACKUPS[@]}." >&2
+    exit 1
+fi
+
+SELECTED="${SORTED_BACKUPS[$((CHOICE - 1))]}"
+SELECTED_NAME="$(basename "${SELECTED}")"
+SELECTED_PATH="$(cd "${SELECTED}" && pwd)"
+
+echo ""
+echo "Selected: ${SELECTED_NAME}"
+
+# --- Count source files ---
+echo ""
+echo "Scanning backup..."
+TOTAL_FILES=$(find "${SELECTED_PATH}" -type f | wc -l | tr -d '[:space:]')
+TOTAL_SIZE=$(du -sh "${SELECTED_PATH}" 2>/dev/null | awk '{print $1}')
+echo "Found ${TOTAL_FILES} files (${TOTAL_SIZE}) to restore."
+
+# --- Destructive warning ---
+echo ""
+echo "=========================================="
+echo "  *** WARNING: DESTRUCTIVE OPERATION ***"
+echo "=========================================="
+echo ""
+echo "This will COMPLETELY ERASE the current contents of your"
+echo "DAAF Docker volume and replace them with the backup."
+echo ""
+echo "All existing files, git history, research data, and"
+echo "configuration in the Docker volume will be permanently"
+echo "deleted and overwritten by the backup contents."
+echo ""
+echo "Source:      ${SELECTED_NAME}/ (${TOTAL_FILES} files, ${TOTAL_SIZE})"
+echo "Destination: Docker volume '${VOLUME_NAME}'"
+echo ""
+read -r -p "Type RESTORE to confirm, or anything else to cancel: " CONFIRM
+
+if [ "${CONFIRM}" != "RESTORE" ]; then
+    echo ""
+    echo "Restore cancelled."
+    exit 0
+fi
+
+echo ""
+
+# --- Step 1: Clear the Docker volume ---
+echo "Clearing Docker volume..."
+if ! docker run --rm -v "${VOLUME_NAME}:/dest" busybox sh -c 'rm -rf /dest/* /dest/.[!.]* /dest/..?*'; then
+    echo "ERROR: Failed to clear Docker volume." >&2
+    echo "The volume may be in an inconsistent state." >&2
+    exit 1
+fi
+echo "Volume cleared."
+echo ""
+
+# --- Step 2: Copy backup into volume ---
+echo "Copying backup into Docker volume..."
+echo "  This may take a few minutes for large backups."
+echo ""
+
+if ! docker run --rm \
+    -v "${SELECTED_PATH}:/source:ro" \
+    -v "${VOLUME_NAME}:/dest" \
+    busybox sh -c "cp -a /source/. /dest/"; then
+    echo "" >&2
+    echo "ERROR: File copy failed." >&2
+    echo "The Docker volume may be in an inconsistent state." >&2
+    echo "You may want to re-run this restore or reinstall DAAF." >&2
+    exit 1
+fi
+echo "Copy complete."
+echo ""
+
+# --- Verify ---
+echo "Verifying restore..."
+RESTORED_COUNT=$(docker run --rm -v "${VOLUME_NAME}:/dest:ro" busybox sh -c 'find /dest -type f | wc -l' | tr -d '[:space:]')
+
+if [ "${RESTORED_COUNT}" -eq 0 ]; then
+    echo "" >&2
+    echo "ERROR: Verification failed -- 0 files found in restored volume." >&2
+    echo "The restore may have failed. Consider re-running or reinstalling DAAF." >&2
+    exit 1
+fi
+
+echo "Verified: ${RESTORED_COUNT} files in restored volume."
+
+# --- Size comparison ---
+if [ "${TOTAL_FILES}" -gt 0 ] && [ "${RESTORED_COUNT}" -gt 0 ]; then
+    DIFF=$((TOTAL_FILES - RESTORED_COUNT))
+    if [ "${DIFF}" -lt 0 ]; then DIFF=$(( -DIFF )); fi
+    TOLERANCE=$(( TOTAL_FILES / 100 ))
+    if [ "${TOLERANCE}" -lt 1 ]; then TOLERANCE=1; fi
+    if [ "${DIFF}" -gt "${TOLERANCE}" ]; then
+        echo ""
+        echo "WARNING: File count mismatch." >&2
+        echo "         Backup: ${TOTAL_FILES} files, Restored: ${RESTORED_COUNT} files (difference: ${DIFF})" >&2
+        echo "         The restore may be incomplete." >&2
+    fi
+fi
+
+echo ""
+echo "=========================================="
+echo "  Restore complete!"
+echo "=========================================="
+echo ""
+echo "Restored: ${SELECTED_NAME}"
+echo "Files:    ${RESTORED_COUNT} files in volume"
+echo ""
+echo "You can now start DAAF with:"
+echo "  bash run_daaf.sh"
+echo ""
diff --git a/scripts/host/run_daaf.ps1 b/scripts/host/run_daaf.ps1
new file mode 100644
index 0000000..0d7aa24
--- /dev/null
+++ b/scripts/host/run_daaf.ps1
@@ -0,0 +1,164 @@
+# ============================================================================
+# DAAF Launcher (Windows PowerShell)
+# ============================================================================
+# Starts the DAAF container (if needed) and launches Claude Code.
+#
+# Usage:
+#   cd daaf-docker
+#   .\run_daaf.ps1            # Start container + launch Claude Code
+#   .\run_daaf.ps1 bash       # Start container + drop into bash shell
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*compose ps*--format*" { Write-Output "daaf-docker" }
+            "*compose up*" { return }
+            "*compose exec*" { return }
+            "*inspect*--format*" { Write-Output "2026-01-01T00:00:00.0000000Z" }
+            "*compose ps -q*" { Write-Output "abc123" }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/run_daaf.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+$Command = if ($args.Count -gt 0) { $args[0] } else { "claude" }
+
+# --- Preflight ---
+if (-not (Test-Path "docker-compose.yml")) {
+    Write-Host "ERROR: docker-compose.yml not found in the current directory." -ForegroundColor Red
+    Write-Host "Please run this script from your daaf-docker folder."
+    Wait-AndExit 1
+}
+
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from PowerShell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Start container if not running ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$RunningOutput = docker compose ps --status running --format '{{.Name}}' 2>&1
+$ErrorActionPreference = $savedEAP
+$Running = ($RunningOutput | Select-String "daaf-docker").Count
+
+if ($Running -eq 0) {
+    Write-Host "Starting DAAF container..."
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose up -d
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "ERROR: Failed to start the container. Check Docker Desktop for errors." -ForegroundColor Red
+        Wait-AndExit 1
+    }
+    Write-Host "Container started."
+} else {
+    Write-Host "DAAF container is already running."
+    # Check if environment_settings.txt has been modified since the container was created
+    if (Test-Path "environment_settings.txt") {
+        $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+        $_cid = docker compose ps -q daaf-docker 2>&1
+        $ErrorActionPreference = $savedEAP
+        if ($_cid) {
+            $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+            $_created = docker inspect --format '{{.Created}}' $_cid 2>&1
+            $ErrorActionPreference = $savedEAP
+            try {
+                # Truncate to 7 fractional digits -- .NET DateTimeOffset.Parse() rejects Docker's 9-digit nanoseconds
+                $_created = $_created -replace '(\.\d{7})\d+', '$1'
+                $ContainerStart = [DateTimeOffset]::Parse($_created).UtcDateTime
+                $EnvModified = (Get-Item "environment_settings.txt").LastWriteTimeUtc
+                if ($EnvModified -gt $ContainerStart) {
+                    Write-Host ""
+                    Write-Host "NOTE: Your environment_settings.txt file has been modified since this container was started." -ForegroundColor Yellow
+                    Write-Host "      To apply environment_settings.txt changes, close all DAAF sessions, then run:"
+                    Write-Host "        docker compose down"
+                    Write-Host "        .\run_daaf.ps1"
+                }
+            } catch {
+                # Date-parsing edge cases (e.g., Docker nanosecond format) are
+                # non-critical -- the environment_settings.txt freshness hint is best-effort only.
+                Write-Verbose "Silenced: $_"
+            }
+        }
+    }
+}
+
+Write-Host ""
+
+# --- Verify DAAF is installed in the container ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md 2>&1 | Out-Null
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "WARNING: DAAF does not appear to be installed in the container (/daaf is empty or missing key files)." -ForegroundColor Yellow
+    Write-Host "The container is running, but DAAF's repository files may not have been cloned."
+    Write-Host "You can fix this by running '.\update_daaf.ps1' from your daaf-docker folder, or manually cloning inside the container:"
+    Write-Host "  docker compose exec daaf-docker bash"
+    Write-Host "  git clone --depth 1 https://github.com/DAAF-Contribution-Community/daaf.git /tmp/daaf-clone"
+    Write-Host "  cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone"
+    Wait-AndExit 1
+}
+
+# --- Launch ---
+if ($Command -eq "claude") {
+    Write-Host "Launching Claude Code..."
+    Write-Host "(Press Ctrl+C twice to exit Claude Code when done)"
+    Write-Host ""
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose exec daaf-docker claude
+    $ErrorActionPreference = $savedEAP
+} elseif ($Command -eq "bash") {
+    Write-Host "Entering container shell..."
+    Write-Host "(Type 'exit' to leave the container)"
+    Write-Host ""
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose exec daaf-docker bash
+    $ErrorActionPreference = $savedEAP
+} else {
+    Write-Host "Running: $Command"
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose exec daaf-docker $Command
+    $ErrorActionPreference = $savedEAP
+}
+
+Wait-AndExit 0
diff --git a/scripts/host/run_daaf.sh b/scripts/host/run_daaf.sh
new file mode 100755
index 0000000..07ca04e
--- /dev/null
+++ b/scripts/host/run_daaf.sh
@@ -0,0 +1,138 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Launcher (macOS / Linux)
+# ============================================================================
+# Starts the DAAF container (if needed) and launches Claude Code.
+#
+# Usage:
+#   cd daaf-docker
+#   bash run_daaf.sh          # Start container + launch Claude Code
+#   bash run_daaf.sh bash     # Start container + drop into bash shell
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script).
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+COMMAND="${1:-claude}"
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"compose ps --status running"*"--format"*) echo "daaf-docker" ;;
+            *"compose ps -q"*) echo "abc123" ;;
+            *"inspect --format"*) echo "2026-01-01T00:00:00Z" ;;
+            *"compose exec"*"test -f"*) return 0 ;;
+            *"compose exec"*)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/run_daaf.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# --- Preflight ---
+if [ ! -f "docker-compose.yml" ]; then
+    echo "ERROR: docker-compose.yml not found in the current directory."
+    echo "Please run this script from your daaf-docker folder."
+    exit 1
+fi
+
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal."
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start it and try again."
+    exit 1
+fi
+
+# --- Start container if not running ---
+RUNNING=$(docker compose ps --status running --format '{{.Name}}' 2>/dev/null | grep -c "daaf-docker" || true)
+
+if [ "${RUNNING}" -eq 0 ]; then
+    echo "Starting DAAF container..."
+    if ! docker compose up -d; then
+        echo "ERROR: Failed to start the container. Check Docker Desktop for errors."
+        exit 1
+    fi
+    echo "Container started."
+else
+    echo "DAAF container is already running."
+    # Check if environment_settings.txt has been modified since the container was created
+    if [ -f "environment_settings.txt" ]; then
+        _cid=$(docker compose ps -q daaf-docker 2>/dev/null || true)
+        if [ -n "${_cid}" ]; then
+            _created=$(docker inspect --format '{{.Created}}' "${_cid}" 2>/dev/null || true)
+            # Get environment_settings.txt mtime as epoch (Linux: -c %Y, macOS: -f %m)
+            _env_epoch=$(stat -c %Y environment_settings.txt 2>/dev/null || stat -f %m environment_settings.txt 2>/dev/null || echo "")
+            # Convert container creation ISO timestamp to epoch (Linux: date -d, macOS: date -j -f)
+            # Strip fractional seconds and trailing Z for macOS BSD date compatibility
+            _ts_clean=$(echo "${_created}" | sed 's/\.[0-9]*Z$//' | sed 's/Z$//')
+            _ctr_epoch=$(date -d "${_created}" +%s 2>/dev/null || \
+                date -j -f "%Y-%m-%dT%H:%M:%S" "${_ts_clean}" +%s 2>/dev/null || \
+                echo "")
+            if [ -n "${_ctr_epoch}" ] && [ -n "${_env_epoch}" ] && [ "${_env_epoch}" -gt "${_ctr_epoch}" ]; then
+                echo ""
+                echo "NOTE: Your environment_settings.txt file has been modified since this container was started."
+                echo "      To apply environment_settings.txt changes, close all DAAF sessions, then run:"
+                echo "        docker compose down"
+                echo "        bash run_daaf.sh"
+            fi
+        fi
+    fi
+fi
+
+echo ""
+
+# --- Verify DAAF is installed in the container ---
+if ! docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md </dev/null 2>/dev/null; then
+    echo "WARNING: DAAF does not appear to be installed in the container (/daaf is empty or missing key files)."
+    echo "The container is running, but DAAF's repository files may not have been cloned."
+    echo "You can fix this by running 'bash update_daaf.sh' from your daaf-docker folder, or manually cloning inside the container:"
+    echo "  docker compose exec daaf-docker bash"
+    echo "  git clone --depth 1 https://github.com/DAAF-Contribution-Community/daaf.git /tmp/daaf-clone"
+    echo "  cp -a /tmp/daaf-clone/. /daaf/ && rm -rf /tmp/daaf-clone"
+    exit 1
+fi
+
+# --- Launch ---
+if [ "${COMMAND}" = "claude" ]; then
+    echo "Launching Claude Code..."
+    echo "(Press Ctrl+C twice to exit Claude Code when done)"
+    echo ""
+    docker compose exec daaf-docker claude
+elif [ "${COMMAND}" = "bash" ]; then
+    echo "Entering container shell..."
+    echo "(Type 'exit' to leave the container)"
+    echo ""
+    docker compose exec daaf-docker bash
+else
+    echo "Running: ${COMMAND}"
+    docker compose exec daaf-docker "${COMMAND}"
+fi
diff --git a/scripts/host/run_vscode.ps1 b/scripts/host/run_vscode.ps1
new file mode 100644
index 0000000..d5ab93b
--- /dev/null
+++ b/scripts/host/run_vscode.ps1
@@ -0,0 +1,115 @@
+# ============================================================================
+# DAAF Code Browser (Windows PowerShell)
+# ============================================================================
+# Opens code-server (VS Code in the browser) for browsing, editing, and
+# reviewing files in the DAAF container.
+# Starts the DAAF container if needed.
+#
+# Usage:
+#   cd daaf-docker
+#   .\run_vscode.ps1
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Port 2720 mapped in docker-compose.yml
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*compose ps*--format*" { Write-Output "daaf-docker" }
+            "*compose up*" { return }
+            "*compose exec*" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/run_vscode.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# --- Preflight ---
+if (-not (Test-Path "docker-compose.yml")) {
+    Write-Host "ERROR: docker-compose.yml not found in the current directory." -ForegroundColor Red
+    Write-Host "Please run this script from your daaf-docker folder."
+    Wait-AndExit 1
+}
+
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop is not running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Start container if not running ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$RunningOutput = docker compose ps --status running --format '{{.Name}}' 2>&1
+$ErrorActionPreference = $savedEAP
+$Running = ($RunningOutput | Select-String "daaf-docker").Count
+
+if ($Running -eq 0) {
+    Write-Host "Starting DAAF container..."
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose up -d
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "ERROR: Failed to start the container." -ForegroundColor Red
+        Wait-AndExit 1
+    }
+    Write-Host "Container started."
+} else {
+    Write-Host "DAAF container is running."
+}
+
+Write-Host ""
+Write-Host "Opening DAAF Code Browser (VS Code in the browser)..."
+Write-Host ""
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose exec daaf-docker bash /daaf/scripts/launch_code_server.sh
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to start code-server." -ForegroundColor Red
+    Write-Host "  The container may not be running, or code-server may not be installed." -ForegroundColor Red
+    Write-Host "  Try: docker compose logs daaf-docker" -ForegroundColor Yellow
+}
+
+# If code-server was already running, the container-side script returns
+# immediately after printing the URL. Wait-AndExit keeps the window open
+# so the user can read/copy it.
+Wait-AndExit 0
diff --git a/scripts/host/run_vscode.sh b/scripts/host/run_vscode.sh
new file mode 100755
index 0000000..80c3505
--- /dev/null
+++ b/scripts/host/run_vscode.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Code Browser (macOS / Linux)
+# ============================================================================
+# Opens code-server (VS Code in the browser) for browsing, editing, and
+# reviewing files in the DAAF container.
+# Starts the DAAF container if needed.
+#
+# Usage:
+#   cd daaf-docker
+#   bash run_vscode.sh
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Port 2720 mapped in docker-compose.yml
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script).
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"compose ps --status running"*"--format"*) echo "daaf-docker" ;;
+            *"compose exec"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/run_vscode.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# --- Preflight ---
+if [ ! -f "docker-compose.yml" ]; then
+    echo "ERROR: docker-compose.yml not found in the current directory." >&2
+    echo "  Please run this script from your daaf-docker folder." >&2
+    exit 1
+fi
+
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." >&2
+    echo "  Please install Docker Desktop: https://www.docker.com/products/docker-desktop/" >&2
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop is not running. Please start it and try again." >&2
+    exit 1
+fi
+
+# --- Start container if not running ---
+RUNNING=$(docker compose ps --status running --format '{{.Name}}' 2>/dev/null | grep -c "daaf-docker" || true)
+
+if [ "${RUNNING}" -eq 0 ]; then
+    echo "Starting DAAF container..."
+    if ! docker compose up -d; then
+        echo "ERROR: Failed to start the container." >&2
+        exit 1
+    fi
+    echo "Container started."
+else
+    echo "DAAF container is running."
+fi
+
+echo ""
+echo "Opening DAAF Code Browser (VS Code in the browser)..."
+echo ""
+if ! docker compose exec daaf-docker bash /daaf/scripts/launch_code_server.sh; then
+    echo "" >&2
+    echo "ERROR: Failed to start code-server." >&2
+    echo "  The container may not be running, or code-server may not be installed." >&2
+    echo "  Try: docker compose logs daaf-docker" >&2
+fi
+
+# If code-server was already running, the container-side script returns
+# immediately after printing the URL. The EXIT trap keeps the terminal open
+# so the user can read/copy it.
diff --git a/scripts/host/update_daaf.ps1 b/scripts/host/update_daaf.ps1
new file mode 100644
index 0000000..931a2ed
--- /dev/null
+++ b/scripts/host/update_daaf.ps1
@@ -0,0 +1,1446 @@
+# ============================================================================
+# DAAF Update Script (Windows PowerShell)
+# ============================================================================
+# Usage:
+#   cd daaf-docker
+#   .\update_daaf.ps1
+#
+#   To update from a specific branch (default: auto-detects main/master):
+#   $env:DAAF_BRANCH = "dev"; .\update_daaf.ps1
+#
+# What this script does:
+#   1. Optionally backs up your DAAF installation (via backup_daaf.ps1)
+#   2. Checks for updates and detects your git state
+#   3. Walks you through updating safely with options at each step
+#   4. Offers Claude Code to help resolve any merge conflicts
+#   5. Syncs utility scripts and auto-rebuilds if Docker files changed
+#
+# This script runs on the host and reaches into the container for git
+# operations. It composes the existing backup and rebuild scripts rather
+# than reimplementing their logic.
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Internet connection
+#   - Run from the daaf-docker directory
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    # Release the concurrent-run mutex if we hold it
+    if ($script:Mutex) {
+        try { $script:Mutex.ReleaseMutex() } catch {
+            # Mutex may not be held (e.g., exit before acquisition) -- safe to ignore
+            Write-Verbose "Silenced: $_"
+        }
+    }
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    # For non-zero exits, use [Environment]::Exit() which terminates the CLR
+    # process unconditionally.  Plain `exit` fails to propagate when this
+    # script is dot-sourced for testing -- it only unwinds the dot-sourced
+    # scope instead of terminating the host process.
+    if ($Code -ne 0) { [Environment]::Exit($Code) }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+# Mock git returns simulate an "already up to date" state for clean exit.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*compose ps*--format*" { Write-Output "daaf-docker" }
+            "*compose up*" { return }
+            "*compose exec*test -f*/daaf/.git/shallow*" {
+                # Not a shallow clone
+                $global:LASTEXITCODE = 1
+                return
+            }
+            "*compose exec*test -f*" { return }
+            "*compose exec*git -C /daaf remote get-url origin*" {
+                Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+            }
+            "*compose exec*git -C /daaf fetch*" { return }
+            "*compose exec*git -C /daaf rev-parse --verify*origin/main*" {
+                Write-Output "abc123def456"
+            }
+            "*compose exec*git -C /daaf rev-parse HEAD*" {
+                Write-Output "abc123def456"
+            }
+            "*compose exec*git -C /daaf rev-parse*origin/main*" {
+                Write-Output "abc123def456"
+            }
+            "*compose exec*git -C /daaf branch*--show-current*" {
+                Write-Output "main"
+            }
+            "*compose exec*git -C /daaf branch*" { return }
+            "*compose exec*git -C /daaf diff --name-only*" {
+                # No dirty files
+                return
+            }
+            "*compose exec*git -C /daaf rev-list*" {
+                Write-Output "0"
+            }
+            "*compose exec*git*" { return }
+            "*compose exec*" { return }
+            "*cp *" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+$UpstreamRepo = "DAAF-Contribution-Community/daaf"
+$ContainerName = "daaf-daaf-docker-1"
+$Timestamp = Get-Date -Format "yyyy-MM-dd-HHmmss"
+$BackupBranch = "backup/pre-update-$Timestamp"
+$Mutex = $null  # Initialized before trap; set to actual mutex after helper functions
+
+# --- Trap handler for unexpected failures ---
+trap {
+    Write-Host "" -ForegroundColor Red
+    Write-Host "-------------------------------------------" -ForegroundColor Red
+    Write-Host "  Something went wrong unexpectedly" -ForegroundColor Red
+    Write-Host "-------------------------------------------" -ForegroundColor Red
+    Write-Host ""
+    Write-Host "Your research files and data are safe - updates only change"
+    Write-Host "framework files, not your research/ folder."
+    Write-Host ""
+    Write-Host "Most likely causes:"
+    Write-Host "  - Docker Desktop stopped (laptop sleep, lid closed)"
+    Write-Host "  - Internet connection dropped during download"
+    Write-Host "  - A temporary Docker glitch"
+    Write-Host ""
+    Write-Host "To try again:"
+    Write-Host "  1. Make sure Docker Desktop is running"
+    Write-Host "  2. Re-run:  .\update_daaf.ps1"
+    Write-Host "     (It is safe to re-run - it will pick up where it left off.)"
+    Write-Host ""
+    if ($Stashed) {
+        Write-Host "Your uncommitted changes are safely saved in a stash."
+        Write-Host "To restore them after fixing the issue:"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+        Write-Host ""
+    }
+    $branchExists = Invoke-ComposeGit rev-parse --verify $BackupBranch
+    if ($LASTEXITCODE -eq 0) {
+        Write-Host "A restore point was saved before the update started. To undo"
+        Write-Host "any partial changes:"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+        Write-Host ""
+    }
+    # Release the concurrent-run mutex if we hold it
+    if ($Mutex) {
+        try { $Mutex.ReleaseMutex() } catch {
+            # Mutex may not be held if trap fires before lock acquisition -- safe to ignore
+            Write-Verbose "Silenced: $_"
+        }
+    }
+    # Inline Wait-AndExit logic -- do not call the function here because trap
+    # blocks are scope-wide (active before function definitions execute), and
+    # Invoke-Expression evaluation may lose function definitions during scope
+    # unwinding, causing CommandNotFoundException.
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    [Environment]::Exit(1)
+}
+
+# =====================================================================
+# Helper functions
+# =====================================================================
+
+# Run docker compose exec with git, suppressing stderr (for commands where
+# stderr is expected/unwanted). Strips carriage returns and returns trimmed
+# string. Uses SilentlyContinue to prevent PS 5.1 from promoting stderr to
+# a terminating error when $ErrorActionPreference is "Stop" in the caller's
+# scope.
+function Invoke-ComposeGit {
+    # Uses $args (simple function) instead of [Parameter(ValueFromRemainingArguments)]
+    # so PowerShell does not add common parameters (-Debug, -Verbose,
+    # -PipelineVariable, ...) that silently consume single-letter git flags.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $raw = @(docker compose exec -T daaf-docker git -C /daaf @args 2>$null)
+        $exitCode = $LASTEXITCODE
+        $result = ($raw | Out-String)
+        $global:LASTEXITCODE = $exitCode
+        return ($result -replace "`r","").Trim()
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run docker compose exec with git, allowing stderr through (for commands
+# that produce useful progress output). Strips carriage returns and returns
+# trimmed string. Uses SilentlyContinue to prevent PS 5.1 from promoting
+# stderr to a terminating error when $ErrorActionPreference is "Stop" in
+# the caller's scope.
+function Invoke-ComposeGitVerbose {
+    # Simple function -- see Invoke-ComposeGit comment for rationale.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $raw = @(docker compose exec -T daaf-docker git -C /daaf @args)
+        $exitCode = $LASTEXITCODE
+        $result = ($raw | Out-String)
+        $global:LASTEXITCODE = $exitCode
+        return ($result -replace "`r","").Trim()
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run docker compose exec with git, piping output to Out-Null (for commands
+# where we only care about $LASTEXITCODE). Uses SilentlyContinue to prevent
+# PS 5.1 from promoting stderr to a terminating error.
+function Invoke-ComposeGitNull {
+    # Simple function -- see Invoke-ComposeGit comment for rationale.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        $null = docker compose exec -T daaf-docker git -C /daaf @args 2>&1
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run docker compose with arbitrary args. Uses SilentlyContinue to prevent
+# PS 5.1 from promoting stderr to a terminating error.
+function Invoke-Compose {
+    # Simple function -- see Invoke-ComposeGit comment for rationale.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        docker compose @args
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+# Run docker compose exec with arbitrary (non-git) args. Uses
+# SilentlyContinue to prevent PS 5.1 from promoting stderr to a
+# terminating error.
+function Invoke-ComposeExec {
+    # Simple function -- see Invoke-ComposeGit comment for rationale.
+    $savedEAP = $ErrorActionPreference
+    try {
+        $ErrorActionPreference = "SilentlyContinue"
+        docker compose exec -T daaf-docker @args
+    } finally {
+        $ErrorActionPreference = $savedEAP
+    }
+}
+
+function Read-UserChoice {
+    param(
+        [string]$PromptText,
+        [string[]]$ValidChoices
+    )
+    # Non-interactive mode (CI, piped input): auto-select first valid choice
+    try { $interactive = [Environment]::UserInteractive -and (-not [Console]::IsInputRedirected) }
+    catch { $interactive = $false }
+    if (-not $interactive) {
+        Write-Host "  (Non-interactive mode - auto-selecting: $($ValidChoices[0]))"
+        return $ValidChoices[0]
+    }
+    while ($true) {
+        $choice = (Read-Host $PromptText).Trim().ToLower()
+        if ($ValidChoices -contains $choice) { return $choice }
+        Write-Host "  Please enter one of: $($ValidChoices -join ', ')" -ForegroundColor Yellow
+    }
+}
+
+# Override Read-UserChoice in dry-run mode (must come after the real definition
+# since the later definition overwrites the earlier one at the same scope)
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function Read-UserChoice {
+        param([string]$PromptText, [string[]]$ValidChoices)
+        $null = $PromptText  # Accept param for interface compatibility
+        Write-Host "[DRY-RUN] Auto-selecting: $($ValidChoices[0])"
+        return $ValidChoices[0]
+    }
+}
+
+function Resolve-Conflict {
+    param(
+        [string]$ConflictType,
+        [string]$AbortCmd
+    )
+
+    $conflictFiles = Invoke-ComposeGit diff --name-only --diff-filter=U
+
+    Write-Host ""
+    Write-Host "-------------------------------------------"
+    Write-Host "  Conflict detected"
+    Write-Host "-------------------------------------------"
+    Write-Host ""
+    Write-Host "The same file(s) were changed both in the update and in your local"
+    Write-Host "version. Git has marked the conflicting sections with <<<<<<< and"
+    Write-Host ">>>>>>> markers."
+    Write-Host ""
+    if ($conflictFiles) {
+        Write-Host "Conflicting files:"
+        $conflictFiles -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "  $_" } }
+        Write-Host ""
+    }
+    # Claude Code requires an interactive terminal (docker exec -it). When
+    # running non-interactively (e.g., nested from migrate_daaf.ps1), skip
+    # straight to manual resolution instructions.
+    $canInteract = $false
+    try { $canInteract = [Environment]::UserInteractive -and (-not [Console]::IsInputRedirected) } catch { Write-Verbose "Silenced: $_" }
+    $choice = "2"
+    if ($canInteract) {
+        Write-Host "Options:"
+        Write-Host "  1) Launch Claude Code to help resolve the conflicts"
+        Write-Host "     Claude Code can read the files, explain both sides, and walk"
+        Write-Host "     you through the resolution interactively."
+        Write-Host ""
+        Write-Host "  2) Exit and resolve manually"
+        Write-Host ""
+        $choice = Read-UserChoice "  Choose [1/2]" @("1", "2")
+    }
+
+    if ($choice -eq "1") {
+        Write-Host ""
+        Write-Host "Launching Claude Code inside the container..."
+        Write-Host ""
+        Write-Host "Copy and paste this prompt to get started:"
+        Write-Host ""
+        if ($conflictFiles) {
+            Write-Host "  User support mode. I just ran the DAAF updater and got"
+            Write-Host "  $ConflictType conflicts in these files:"
+            $conflictFiles -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "    $_" } }
+        } else {
+            Write-Host "  User support mode. I just ran the DAAF updater and got"
+            Write-Host "  $ConflictType conflicts."
+        }
+        Write-Host ""
+        Write-Host "  Please help me resolve them. For each conflicting file:"
+        Write-Host "  1. Read it and explain what changed on both sides of the"
+        Write-Host "     conflict markers (<<<<<<< vs >>>>>>>)"
+        Write-Host "  2. Help me decide which version to keep or how to combine them"
+        Write-Host "  3. Edit the file to remove all conflict markers"
+        Write-Host "  After all files are resolved, commit the result:"
+        Write-Host "    git add ."
+        if ($ConflictType -eq "merge") {
+            Write-Host "    git commit -m `"Resolved merge conflicts from DAAF update`""
+        } else {
+            Write-Host "    git rebase --continue"
+        }
+        Write-Host "  When finished, remind me to type /exit so the updater can"
+        Write-Host "  finish its remaining steps."
+        Write-Host ""
+        Write-Host "IMPORTANT: When Claude Code is done, type /exit to return here."
+        Write-Host "The updater still needs to finish a few steps after this."
+        Write-Host ""
+        # EAP = SilentlyContinue prevents PS 5.1 from promoting Docker's
+        # stderr to a terminating error under the script's global EAP = Stop.
+        $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+        docker compose exec daaf-docker claude
+        $ErrorActionPreference = $savedEAP
+        Write-Host ""
+
+        $remaining = Invoke-ComposeGit diff --name-only --diff-filter=U
+
+        if ([string]::IsNullOrWhiteSpace($remaining)) {
+            Write-Host "Conflicts resolved!"
+            Write-Host ""
+            $script:ConflictResolved = $true
+            return
+        } else {
+            Write-Host "Some conflicts still remain in these files:"
+            $remaining -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "  $_" } }
+            Write-Host ""
+            Write-Host "You can keep working on them - launch Claude Code and pick up"
+            Write-Host "where you left off:"
+            Write-Host "  .\run_daaf.ps1"
+            Write-Host ""
+            Write-Host "Or to undo the update entirely (your research files are not affected):"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf $AbortCmd"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+            $script:ConflictResolved = $false
+            return
+        }
+    } else {
+        Write-Host ""
+        Write-Host "To resolve the conflicts manually, enter the container:"
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host ""
+        Write-Host "Conflicting files contain markers that look like:"
+        Write-Host "  <<<<<<< HEAD"
+        Write-Host "  (your version)"
+        Write-Host "  ======="
+        Write-Host "  (the update's version)"
+        Write-Host "  >>>>>>>"
+        Write-Host "Edit each file to keep the version you want, removing all markers."
+        Write-Host ""
+        if ($ConflictType -eq "merge") {
+            Write-Host "After resolving all files (inside the container):"
+            Write-Host "  git add ."
+            Write-Host "  git commit -m `"Resolved merge conflicts`""
+            Write-Host "  exit"
+        } else {
+            Write-Host "After resolving all files (inside the container):"
+            Write-Host "  git add ."
+            Write-Host "  git rebase --continue"
+            Write-Host "  exit"
+        }
+        Write-Host ""
+        Write-Host "To undo the update instead (run from PowerShell, not the container):"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf $AbortCmd"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+        $script:ConflictResolved = $false
+        return
+    }
+}
+
+function Resolve-StashConflict {
+    Write-Host ""
+    Write-Host "The framework update was applied successfully!"
+    Write-Host ""
+    Write-Host "However, some of your uncommitted edits overlap with files that"
+    Write-Host "changed in the update. Your edits are NOT lost - they are saved"
+    Write-Host "in a temporary holding area."
+    Write-Host ""
+    # Claude Code requires an interactive terminal. When non-interactive,
+    # skip straight to manual resolution instructions.
+    $canInteract = $false
+    try { $canInteract = [Environment]::UserInteractive -and (-not [Console]::IsInputRedirected) } catch { Write-Verbose "Silenced: $_" }
+    $choice = "2"
+    if ($canInteract) {
+        Write-Host "Options:"
+        Write-Host "  1) Launch Claude Code to help resolve the conflicts"
+        Write-Host "  2) Exit and resolve manually"
+        Write-Host ""
+        $choice = Read-UserChoice "  Choose [1/2]" @("1", "2")
+    }
+
+    if ($choice -eq "1") {
+        Write-Host ""
+        Write-Host "Launching Claude Code inside the container..."
+        Write-Host ""
+        Write-Host "Copy and paste this prompt to get started:"
+        Write-Host ""
+        Write-Host "  User support mode. The DAAF updater applied the framework"
+        Write-Host "  update successfully, but re-applying my uncommitted changes"
+        Write-Host "  caused stash conflicts. Please help me resolve them:"
+        Write-Host "  1. Run git status to find the conflicting files"
+        Write-Host "  2. Read each one and explain both sides of the conflict"
+        Write-Host "  3. Help me choose what to keep and edit the file to resolve it"
+        Write-Host "  4. After all conflicts are resolved, run: git add ."
+        Write-Host "     Then: git stash drop"
+        Write-Host "     Then: git commit -m 'Resolved stash conflicts from DAAF update'"
+        Write-Host "  When done, remind me to type /exit so the updater can"
+        Write-Host "  finish its remaining steps."
+        Write-Host ""
+        Write-Host "IMPORTANT: When Claude Code is done, type /exit to return here."
+        Write-Host "The updater still needs to finish a few steps after this."
+        Write-Host ""
+        # EAP = SilentlyContinue prevents PS 5.1 from promoting Docker's
+        # stderr to a terminating error under the script's global EAP = Stop.
+        $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+        docker compose exec daaf-docker claude
+        $ErrorActionPreference = $savedEAP
+        Write-Host ""
+
+        $remaining = Invoke-ComposeGit diff --name-only --diff-filter=U
+
+        if ([string]::IsNullOrWhiteSpace($remaining)) {
+            Write-Host "Conflicts resolved!"
+            $script:StashConflictResolved = $true
+            return
+        } else {
+            Write-Host "Some conflicts still remain in these files:"
+            $remaining -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "  $_" } }
+            Write-Host ""
+            Write-Host "You can keep working on them - launch Claude Code:"
+            Write-Host "  .\run_daaf.ps1"
+            Write-Host ""
+            Write-Host "Or to undo the update:"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+            $script:StashConflictResolved = $false
+            return
+        }
+    } else {
+        Write-Host ""
+        Write-Host "To resolve, enter the container:"
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host "  (edit the conflicting files to remove the <<<<<<< markers)"
+        Write-Host "  git add ."
+        Write-Host "  git stash drop"
+        Write-Host "  exit"
+        Write-Host ""
+        Write-Host "Or to discard your uncommitted edits and keep the update"
+        Write-Host "(WARNING - this cannot be undone):"
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host "  git checkout -- ."
+        Write-Host "  git stash drop"
+        Write-Host "  exit"
+        Write-Host ""
+        Write-Host "To undo the entire update:"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+        $script:StashConflictResolved = $false
+        return
+    }
+}
+
+function Sync-HostScript {
+    param([string]$OldHead)
+
+    $newHead = Invoke-ComposeGit rev-parse HEAD
+
+    if ($OldHead -eq $newHead) { return }
+
+    # Only sync platform-appropriate scripts (.ps1 on Windows) and shared files.
+    # Excludes install.ps1 (not needed post-install) and all .sh files.
+    $changedScripts = Invoke-ComposeGit diff --name-only "$OldHead..$newHead" -- `
+        scripts/host/run_daaf.ps1 `
+        scripts/host/backup_daaf.ps1 `
+        scripts/host/restore_from_backup.ps1 `
+        scripts/host/rebuild_daaf.ps1 `
+        scripts/host/update_daaf.ps1 `
+        scripts/host/view_logs.ps1 `
+        scripts/host/view_notebooks.ps1 `
+        scripts/host/run_vscode.ps1 `
+        scripts/host/environment_settings_example.txt
+
+    if ([string]::IsNullOrWhiteSpace($changedScripts)) { return }
+
+    Write-Host "Syncing updated utility scripts..."
+    $changedScripts -split "`n" | ForEach-Object {
+        $repoPath = $_.Trim()
+        if (-not $repoPath) { return }
+        $scriptName = Split-Path $repoPath -Leaf
+        $savedEAP = $ErrorActionPreference
+        try { $ErrorActionPreference = "SilentlyContinue"; docker cp "${ContainerName}:/daaf/$repoPath" "./$scriptName" 2>$null } finally { $ErrorActionPreference = $savedEAP }
+        if ($LASTEXITCODE -eq 0) {
+            Write-Host "  Updated: $scriptName"
+        } else {
+            Write-Host "  Warning: could not copy $scriptName. You can copy it manually:" -ForegroundColor Yellow
+            Write-Host "    docker cp ${ContainerName}:/daaf/$repoPath ./$scriptName" -ForegroundColor Yellow
+        }
+    }
+    Write-Host ""
+}
+
+function Test-BuildChange {
+    param([string]$OldHead)
+
+    $newHead = Invoke-ComposeGit rev-parse HEAD
+
+    if ($OldHead -eq $newHead) {
+        Write-Host "No Dockerfile changes - no container rebuild needed."
+        Write-Host ""
+        return
+    }
+
+    $buildChanges = Invoke-ComposeGit diff --name-only "$OldHead..$newHead" -- `
+        Dockerfile docker-compose.yml
+
+    if ([string]::IsNullOrWhiteSpace($buildChanges)) {
+        Write-Host "No Dockerfile changes - no container rebuild needed."
+        Write-Host ""
+        return
+    }
+
+    Write-Host ""
+    Write-Host "Build files were updated in this release:"
+    $buildChanges -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "  $_" } }
+    Write-Host ""
+    Write-Host "A rebuild is needed for these changes to take full effect."
+    Write-Host ""
+    $choice = Read-UserChoice "  Run rebuild now? [y/n]" @("y", "n")
+
+    if ($choice -eq "y") {
+        Write-Host ""
+        if (Test-Path "rebuild_daaf.ps1") {
+            $env:DAAF_NESTED = "1"
+            & .\rebuild_daaf.ps1
+            Remove-Item Env:\DAAF_NESTED -ErrorAction SilentlyContinue
+        } else {
+            Write-Host "rebuild_daaf.ps1 is not in your daaf-docker folder."
+            Write-Host "You can retrieve it from the container and run it:"
+            Write-Host "  docker cp ${ContainerName}:/daaf/scripts/host/rebuild_daaf.ps1 .\rebuild_daaf.ps1"
+            Write-Host "  .\rebuild_daaf.ps1"
+        }
+    } else {
+        Write-Host ""
+        Write-Host "When you're ready to rebuild:"
+        Write-Host "  .\rebuild_daaf.ps1"
+    }
+}
+
+function Complete-Update {
+    param(
+        [string]$OldHead,
+        [string]$ExtraMsg = ""
+    )
+
+    Sync-HostScript $OldHead
+    Test-BuildChange $OldHead
+
+    Write-Host ""
+    Write-Host "=========================================="
+    Write-Host "  Update complete!"
+    Write-Host "=========================================="
+    Write-Host ""
+    if ($ExtraMsg) {
+        Write-Host $ExtraMsg
+        Write-Host ""
+    }
+    Write-Host "If you need to undo this update later:"
+    Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+    Write-Host ""
+    Write-Host "  (This reverts DAAF's framework files to how they were before the"
+    Write-Host "   update. Your research projects and data are not affected.)"
+    Write-Host ""
+    Write-Host "  To launch DAAF:"
+    Write-Host "    .\run_daaf.ps1"
+    Write-Host ""
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/update_daaf.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# =====================================================================
+# Concurrent-run lock (named mutex)
+# =====================================================================
+# Prevent two simultaneous update_daaf runs from corrupting git state
+# (double-stash, conflicting merges, backup branch pointing to wrong commit).
+$MutexName = "Global\DAAFUpdate"
+$Mutex = [System.Threading.Mutex]::new($false, $MutexName)
+try {
+    if (-not $Mutex.WaitOne(0)) {
+        Write-Host "ERROR: Another instance of update_daaf is already running." -ForegroundColor Red
+        Write-Host "       Wait for it to finish or restart Docker Desktop to clear the lock." -ForegroundColor Yellow
+        Wait-AndExit 1
+    }
+} catch [System.Threading.AbandonedMutexException] {
+    # Previous instance crashed without releasing -- we now own the mutex, continue
+    Write-Verbose "Silenced: $_"
+}
+
+# =====================================================================
+# Main script
+# =====================================================================
+
+Write-Host ""
+Write-Host "=========================================="
+Write-Host "  DAAF Updater"
+Write-Host "=========================================="
+Write-Host ""
+Write-Host "Tip: If Claude Code is running inside the container, exit it first"
+Write-Host "(/exit) to avoid file conflicts during the update."
+Write-Host ""
+
+# --- Preflight: docker-compose.yml ---
+if (-not (Test-Path "docker-compose.yml")) {
+    Write-Host "ERROR: docker-compose.yml not found in the current directory." -ForegroundColor Red
+    Write-Host ""
+    Write-Host "This script must be run from your daaf-docker folder. Try:"
+    Write-Host "  cd ~\daaf-docker"
+    Write-Host "  .\update_daaf.ps1"
+    Write-Host ""
+    Write-Host "If you installed DAAF somewhere else, cd to that folder first."
+    Wait-AndExit 1
+}
+
+# --- Preflight: Docker installed ---
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from PowerShell." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+# --- Preflight: Docker running ---
+$savedEAP = $ErrorActionPreference
+try { $ErrorActionPreference = "SilentlyContinue"; $null = docker info 2>&1 } finally { $ErrorActionPreference = $savedEAP }
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop does not seem to be running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Preflight: Start container if needed ---
+$savedEAP = $ErrorActionPreference
+try { $ErrorActionPreference = "SilentlyContinue"; $runningCheck = docker compose ps --status running --format '{{.Name}}' 2>$null } finally { $ErrorActionPreference = $savedEAP }
+$running = ($runningCheck | Out-String) -match "daaf-docker"
+
+if (-not $running) {
+    Write-Host "Starting DAAF container..."
+    Invoke-Compose up -d
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Failed to start the DAAF container." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "No changes were made to your installation."
+        Write-Host ""
+        Write-Host "Common causes:"
+        Write-Host "  - Another program is using the same ports"
+        Write-Host "  - Docker Desktop needs more memory (Settings > Resources)"
+        Write-Host ""
+        Write-Host "Try restarting Docker Desktop, then:  .\update_daaf.ps1"
+        Wait-AndExit 1
+    }
+
+    $retries = 0
+    $maxRetries = 30
+    $readyLog = [System.IO.Path]::GetTempFileName()
+    while ($retries -lt $maxRetries) {
+        $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+        docker compose exec -T daaf-docker true 2>> $readyLog
+        $ErrorActionPreference = $savedEAP
+        if ($LASTEXITCODE -eq 0) { break }
+        $retries++
+        Start-Sleep -Seconds 2
+    }
+    if ($retries -ge $maxRetries) {
+        Write-Host ""
+        Write-Host "ERROR: The DAAF container started but is not responding after 60 seconds." -ForegroundColor Red
+        if ((Test-Path $readyLog) -and (Get-Item $readyLog).Length -gt 0) {
+            Write-Host "  Docker reported:" -ForegroundColor Red
+            Get-Content $readyLog -Tail 5 | ForEach-Object { Write-Host "    $_" -ForegroundColor Red }
+            Write-Host ""
+        }
+        Write-Host "No changes were made to your DAAF installation."
+        Write-Host ""
+        Write-Host "This can happen if Docker Desktop is under heavy load."
+        Write-Host "Try:"
+        Write-Host "  1. Restart Docker Desktop"
+        Write-Host "  2. Re-run:  .\update_daaf.ps1"
+        Remove-Item $readyLog -ErrorAction SilentlyContinue
+        Wait-AndExit 1
+    }
+    Remove-Item $readyLog -ErrorAction SilentlyContinue
+    Write-Host "Container started."
+    Write-Host ""
+}
+
+# --- Preflight: DAAF installed ---
+$null = Invoke-ComposeExec test -f /daaf/CLAUDE.md 2>&1
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: DAAF does not appear to be installed in the container." -ForegroundColor Red
+    Write-Host "Run the installer first. See:"
+    Write-Host "  https://github.com/$UpstreamRepo#quick-start"
+    Wait-AndExit 1
+}
+
+# =====================================================================
+# Offer backup
+# =====================================================================
+Write-Host "-------------------------------------------"
+Write-Host "  Backup recommendation"
+Write-Host "-------------------------------------------"
+Write-Host ""
+Write-Host "It's a good idea to back up before updating, especially if you have"
+Write-Host "research projects or local customizations you want to protect."
+Write-Host ""
+if (Test-Path "backup_daaf.ps1") {
+    $choice = Read-UserChoice "  Run backup now? [y/n]" @("y", "n")
+    if ($choice -eq "y") {
+        Write-Host ""
+        $env:DAAF_NESTED = "1"
+        & .\backup_daaf.ps1
+        Remove-Item Env:\DAAF_NESTED -ErrorAction SilentlyContinue
+        Write-Host ""
+    }
+} else {
+    Write-Host "  (backup_daaf.ps1 not found in this directory - skipping)"
+    Write-Host ""
+}
+
+# =====================================================================
+# Create git backup branch (lightweight restore point)
+# =====================================================================
+Invoke-ComposeGitNull branch $BackupBranch
+
+$OldHead = Invoke-ComposeGit rev-parse HEAD
+
+# =====================================================================
+# Check git remote
+# =====================================================================
+$OriginUrl = Invoke-ComposeGit remote get-url origin
+
+if ([string]::IsNullOrWhiteSpace($OriginUrl)) {
+    Write-Host ""
+    Write-Host "Your DAAF installation is not connected to the update server."
+    Write-Host ""
+    Write-Host "This usually means DAAF was installed from a downloaded zip file"
+    Write-Host "instead of using the installer script. To connect it for updates,"
+    Write-Host "run these commands one at a time:"
+    Write-Host ""
+    Write-Host "  .\run_daaf.ps1 bash"
+    Write-Host "  git remote add origin https://github.com/$UpstreamRepo.git"
+    Write-Host "  git fetch origin"
+    Write-Host "  exit"
+    Write-Host ""
+    Write-Host "Then re-run:  .\update_daaf.ps1"
+    Wait-AndExit 0
+}
+
+# --- Determine upstream remote ---
+$UpstreamRemote = "origin"
+
+if ($OriginUrl -notlike "*$UpstreamRepo*") {
+    Write-Host "NOTE: Your 'origin' remote points to a fork:"
+    Write-Host "  $OriginUrl"
+    Write-Host ""
+
+    $upstreamUrl = Invoke-ComposeGit remote get-url upstream
+
+    if ($upstreamUrl) {
+        $UpstreamRemote = "upstream"
+        Write-Host "Found 'upstream' remote - will check for updates there."
+    } else {
+        Write-Host "Your installation is connected to a personal copy (fork) of DAAF,"
+        Write-Host "not the official release. To also receive official updates, run"
+        Write-Host "these commands one at a time:"
+        Write-Host ""
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host "  git remote add upstream https://github.com/$UpstreamRepo.git"
+        Write-Host "  git fetch upstream"
+        Write-Host "  exit"
+        Write-Host ""
+        Write-Host "Then re-run:  .\update_daaf.ps1"
+        Wait-AndExit 0
+    }
+    Write-Host ""
+}
+
+# =====================================================================
+# Fetch latest
+# =====================================================================
+Write-Host "Fetching latest changes from $UpstreamRemote..."
+# Use direct docker exec instead of Invoke-ComposeGitNull so we can capture stderr
+# for diagnostic output on failure (Invoke-ComposeGitNull discards all output).
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$fetchOutput = docker compose exec -T daaf-docker git -C /daaf fetch $UpstreamRemote 2>&1
+$fetchExit = $LASTEXITCODE
+$ErrorActionPreference = $savedEAP
+if ($fetchExit -ne 0) {
+    Write-Host ""
+    Write-Host "Failed to fetch from $UpstreamRemote." -ForegroundColor Red
+    if ($fetchOutput) {
+        Write-Host "  Git reported:" -ForegroundColor Red
+        $fetchOutput | ForEach-Object { Write-Host "    $_" -ForegroundColor Red }
+    }
+    Write-Host ""
+    Write-Host "No changes were made to your installation."
+    Write-Host ""
+    Write-Host "Common causes:"
+    Write-Host "  - No internet connection"
+    Write-Host "  - GitHub may be experiencing an outage (check https://www.githubstatus.com)"
+    Write-Host "  - Corporate firewall or proxy blocking the connection"
+    Write-Host ""
+    Write-Host "Once the issue is resolved, re-run:  .\update_daaf.ps1"
+    Wait-AndExit 1
+}
+
+# --- Unshallow if needed (shallow clones can't compute merge-base) ---
+$null = Invoke-ComposeExec test -f /daaf/.git/shallow 2>&1
+if ($LASTEXITCODE -eq 0) {
+    Write-Host "Deepening repository history (installed from a shallow clone)..."
+    Invoke-ComposeGitNull fetch --unshallow $UpstreamRemote
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "  (Already unshallowed or not needed.)"
+    }
+    Write-Host ""
+}
+
+# =====================================================================
+# Resolve remote branch
+# =====================================================================
+$RemoteBranch = if ($env:DAAF_BRANCH) { $env:DAAF_BRANCH } else { "" }
+
+if ($RemoteBranch) {
+    # User specified a branch - verify it exists on the remote
+    $null = Invoke-ComposeGit rev-parse --verify "$UpstreamRemote/$RemoteBranch"
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "The branch '$RemoteBranch' (from DAAF_BRANCH) was not found on" -ForegroundColor Red
+        Write-Host "$UpstreamRemote."
+        Write-Host ""
+        Write-Host "Your installation is unchanged. Double-check the branch name and try"
+        Write-Host "again, or omit DAAF_BRANCH to use the default branch."
+        Wait-AndExit 1
+    }
+    Write-Host "Using branch: $RemoteBranch (from DAAF_BRANCH)"
+} else {
+    # Auto-detect: try main, then master
+    $null = Invoke-ComposeGit rev-parse --verify "$UpstreamRemote/main"
+    if ($LASTEXITCODE -eq 0) {
+        $RemoteBranch = "main"
+    } else {
+        $null = Invoke-ComposeGit rev-parse --verify "$UpstreamRemote/master"
+        if ($LASTEXITCODE -eq 0) {
+            $RemoteBranch = "master"
+        }
+    }
+}
+
+if (-not $RemoteBranch) {
+    Write-Host ""
+    Write-Host "Could not find the update branch on the server." -ForegroundColor Red
+    Write-Host "(Looked for 'main' and 'master' on $UpstreamRemote, but neither exists.)"
+    Write-Host ""
+    Write-Host "Your installation is unchanged. No changes were made."
+    Write-Host ""
+    Write-Host "This usually means one of:"
+    Write-Host "  - The repository was recently restructured and uses a different"
+    Write-Host "    default branch name"
+    Write-Host "  - The remote URL points to an empty or misconfigured repository"
+    Write-Host "  - A network issue caused an incomplete fetch (try re-running)"
+    Write-Host ""
+    Write-Host "To troubleshoot:"
+    Write-Host "  1. Check what branches exist on the remote:"
+    Write-Host "       docker compose exec daaf-docker git -C /daaf ls-remote --heads $UpstreamRemote"
+    Write-Host "  2. If you see a branch listed, specify it explicitly:"
+    Write-Host "       `$env:DAAF_BRANCH = 'branch-name'; .\update_daaf.ps1"
+    Write-Host "  3. Verify your remote URL is correct:"
+    Write-Host "       docker compose exec daaf-docker git -C /daaf remote -v"
+    Write-Host ""
+    Write-Host "If this persists, check:"
+    Write-Host "  https://github.com/$UpstreamRepo/issues"
+    Wait-AndExit 1
+}
+
+# =====================================================================
+# Check current branch
+# =====================================================================
+$CurrentBranch = Invoke-ComposeGit branch --show-current
+
+if ([string]::IsNullOrWhiteSpace($CurrentBranch)) {
+    Write-Host ""
+    Write-Host "Your DAAF installation is not on a named branch right now."
+    Write-Host ""
+    Write-Host "This can happen after installing from a specific version tag, after"
+    Write-Host "a previous update was interrupted, or after running a manual git"
+    Write-Host "command inside the container. Not a problem - I'll handle it."
+    Write-Host ""
+
+    # Create a branch at the current HEAD to preserve any local commits.
+    # Without this, checking out another branch would orphan those commits.
+    $PreservedBranch = "local-work-$(Get-Date -Format 'yyyyMMdd-HHmmss')"
+    Write-Host "Creating branch '$PreservedBranch' to preserve your current work..."
+    Invoke-ComposeGitNull checkout -b $PreservedBranch
+    if ($LASTEXITCODE -eq 0) {
+        $CurrentBranch = $PreservedBranch
+        Write-Host "Done. Your commits are safe on branch '$PreservedBranch'."
+        Write-Host ""
+    } else {
+        Write-Host ""
+        Write-Host "Could not create a branch from the current state."
+        Write-Host ""
+        Write-Host "To fix this manually:"
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host "  git checkout -b my-work"
+        Write-Host "  exit"
+        Write-Host ""
+        Write-Host "Then re-run:  .\update_daaf.ps1"
+        Write-Host ""
+        Write-Host "No changes were made. Your research files are not affected."
+        Wait-AndExit 1
+    }
+}
+
+# =====================================================================
+# Check if already up to date
+# =====================================================================
+$Local = Invoke-ComposeGit rev-parse HEAD
+$Remote = Invoke-ComposeGit rev-parse "$UpstreamRemote/$RemoteBranch"
+
+$DirtyFiles = Invoke-ComposeGit diff --name-only HEAD
+
+if (($CurrentBranch -eq $RemoteBranch) -and ($Local -eq $Remote) -and `
+    [string]::IsNullOrWhiteSpace($DirtyFiles)) {
+    Write-Host ""
+    Write-Host "Already up to date! Nothing to do."
+    Write-Host ""
+    Wait-AndExit 0
+}
+
+# =====================================================================
+# Compute ahead/behind
+# =====================================================================
+$Ahead = Invoke-ComposeGit rev-list --count "$UpstreamRemote/$RemoteBranch..HEAD"
+if (-not $Ahead) { $Ahead = "0" }
+
+$Behind = Invoke-ComposeGit rev-list --count "HEAD..$UpstreamRemote/$RemoteBranch"
+if (-not $Behind) { $Behind = "0" }
+
+if ($Behind -ne "0") {
+    Write-Host ""
+    Write-Host "Updates available: $Behind new commit(s) on $UpstreamRemote/$RemoteBranch."
+}
+
+# =====================================================================
+# Early exit: no upstream updates for non-default branches
+# =====================================================================
+if (($CurrentBranch -ne $RemoteBranch) -and ($Behind -eq "0")) {
+    Write-Host ""
+    Write-Host "Already up to date! Your branch '$CurrentBranch' has all the latest"
+    Write-Host "changes from $UpstreamRemote/$RemoteBranch. Nothing to do."
+    Write-Host ""
+    Wait-AndExit 0
+}
+
+# =====================================================================
+# Handle non-default branch
+# =====================================================================
+if ($CurrentBranch -ne $RemoteBranch) {
+    Write-Host ""
+    Write-Host "You are on branch '$CurrentBranch', not '$RemoteBranch'."
+    Write-Host ""
+    Write-Host "DAAF updates are published to '$RemoteBranch'. This will pull the"
+    Write-Host "latest updates into '$RemoteBranch', then merge them into your branch."
+    Write-Host ""
+    Write-Host "Options:"
+    Write-Host "  1) Update: pull into $RemoteBranch, then merge into '$CurrentBranch'"
+    Write-Host "  2) Abort (no changes made)"
+    Write-Host ""
+    $choice = Read-UserChoice "  Choose [1/2]" @("1", "2")
+
+    if ($choice -eq "2") {
+        Write-Host ""
+        Write-Host "Aborted. No changes made."
+        Wait-AndExit 0
+    }
+
+    $Stashed = $false
+    if ($DirtyFiles) {
+        Write-Host ""
+        Write-Host "Setting aside your uncommitted changes for safekeeping..."
+        Invoke-ComposeGitVerbose stash push -m "DAAF update backup $Timestamp"
+        if ($LASTEXITCODE -ne 0) {
+            Write-Host ""
+            Write-Host "ERROR: Could not safely set aside your uncommitted changes." -ForegroundColor Red
+            Write-Host ""
+            Write-Host "No changes were made - your files are exactly as they were."
+            Write-Host ""
+            Write-Host "This can happen if there are new files that need to be committed first."
+            Write-Host "You can commit your changes, then re-run the updater:"
+            Write-Host "  .\run_daaf.ps1 bash"
+            Write-Host "  git add -A"
+            Write-Host "  git commit -m `"Save my changes before update`""
+            Write-Host "  exit"
+            Write-Host "  .\update_daaf.ps1"
+            Wait-AndExit 1
+        }
+        $Stashed = $true
+    }
+
+    Write-Host "Switching to $RemoteBranch..."
+    Invoke-ComposeGitVerbose checkout $RemoteBranch
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Could not switch to the '$RemoteBranch' branch." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "This is unusual. Your files are unchanged."
+        if ($Stashed) {
+            Write-Host "Your uncommitted changes are safely saved."
+            Write-Host "To restore them: docker compose exec daaf-docker git -C /daaf stash pop"
+        }
+        Write-Host ""
+        Write-Host "Your research files are not affected."
+        Wait-AndExit 1
+    }
+
+    Write-Host "Pulling updates..."
+    Invoke-ComposeGitVerbose pull $UpstreamRemote $RemoteBranch
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Could not download the latest updates." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "Common causes:"
+        Write-Host "  - No internet connection"
+        Write-Host "  - GitHub may be down (check https://www.githubstatus.com)"
+        Write-Host ""
+        Write-Host "To get back to where you were:"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf checkout $CurrentBranch"
+        if ($Stashed) {
+            Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+        }
+        Write-Host ""
+        Write-Host "Your research files are not affected."
+        Wait-AndExit 1
+    }
+
+    Write-Host "Switching back to '$CurrentBranch'..."
+    Invoke-ComposeGitVerbose checkout $CurrentBranch
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Could not switch back to your '$CurrentBranch' branch." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "The updates were downloaded successfully, but the script could"
+        Write-Host "not return to your branch. Your research files are safe."
+        Write-Host ""
+        Write-Host "To fix this, enter the container and switch manually:"
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host "  git checkout $CurrentBranch"
+        Write-Host "  exit"
+        Write-Host ""
+        Write-Host "If that also fails, you can restore to before the update:"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+        if ($Stashed) {
+            Write-Host ""
+            Write-Host "Your uncommitted changes are still saved. After switching back:"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+        }
+        Wait-AndExit 1
+    }
+
+    Write-Host "Merging $RemoteBranch into '$CurrentBranch'..."
+    Invoke-ComposeGitNull merge $RemoteBranch
+    if ($LASTEXITCODE -ne 0) {
+        # Call as statement, not expression -- if (-not (Fn)) captures
+        # stdout through a pipe, breaking Docker's TTY detection.
+        Resolve-Conflict "merge" "merge --abort"
+        if (-not $script:ConflictResolved) {
+            if ($Stashed) {
+                Write-Host ""
+                Write-Host "Your uncommitted changes are safely saved and will be"
+                Write-Host "restored after conflicts are resolved."
+                Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+            }
+            Wait-AndExit 1
+        }
+    }
+
+    if ($Stashed) {
+        Write-Host "Restoring your changes..."
+        Invoke-ComposeGitNull stash pop
+        if ($LASTEXITCODE -ne 0) {
+            Resolve-StashConflict
+            if ($script:StashConflictResolved) {
+                Complete-Update $OldHead
+            } else {
+                Complete-Update $OldHead "Note: Uncommitted changes still need attention (see above)."
+            }
+            Wait-AndExit 0
+        }
+    }
+
+    Complete-Update $OldHead
+    Wait-AndExit 0
+}
+
+# =====================================================================
+# On default branch - local commits
+# =====================================================================
+if ([int]$Ahead -gt 0) {
+    Write-Host ""
+    Write-Host "You have $Ahead local commit(s) on $RemoteBranch that aren't in"
+    Write-Host "the official DAAF release."
+    Write-Host ""
+    Write-Host "Your local commits:"
+    $logOutput = Invoke-ComposeGit log --oneline "$UpstreamRemote/$RemoteBranch..HEAD"
+    $logOutput -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "  $_" } }
+    Write-Host ""
+    Write-Host "Options:"
+    Write-Host ""
+    Write-Host "  1) MERGE (recommended)"
+    Write-Host "     Combines your changes with the update. Your commits stay as-is."
+    Write-Host "     Git creates a merge commit tying both histories together."
+    Write-Host ""
+    Write-Host "  2) REBASE (cleaner history)"
+    Write-Host "     Bundles your local changes into one commit and places it on top"
+    Write-Host "     of the latest update. Individual commit messages are combined."
+    Write-Host ""
+    Write-Host "  3) ABORT (no changes made)"
+    Write-Host ""
+    $choice = Read-UserChoice "  Choose [1/2/3]" @("1", "2", "3")
+
+    if ($choice -eq "3") {
+        Write-Host ""
+        Write-Host "Aborted. No changes made."
+        Wait-AndExit 0
+    }
+
+    $Stashed = $false
+    if ($DirtyFiles) {
+        Write-Host ""
+        Write-Host "Setting aside your uncommitted changes for safekeeping..."
+        Invoke-ComposeGitVerbose stash push -m "DAAF update backup $Timestamp"
+        if ($LASTEXITCODE -ne 0) {
+            Write-Host ""
+            Write-Host "ERROR: Could not safely set aside your uncommitted changes." -ForegroundColor Red
+            Write-Host ""
+            Write-Host "No changes were made - your files are exactly as they were."
+            Write-Host ""
+            Write-Host "This can happen if there are new files that need to be committed first."
+            Write-Host "You can commit your changes, then re-run the updater:"
+            Write-Host "  .\run_daaf.ps1 bash"
+            Write-Host "  git add -A"
+            Write-Host "  git commit -m `"Save my changes before update`""
+            Write-Host "  exit"
+            Write-Host "  .\update_daaf.ps1"
+            Wait-AndExit 1
+        }
+        $Stashed = $true
+    }
+
+    if ($choice -eq "1") {
+        # --- Merge path ---
+        Write-Host "Merging upstream updates..."
+        Invoke-ComposeGitNull merge "$UpstreamRemote/$RemoteBranch" `
+            -m "Merge DAAF upstream updates"
+        if ($LASTEXITCODE -ne 0) {
+            # Call as statement, not expression -- if (-not (Fn)) captures
+            # stdout through a pipe, breaking Docker's TTY detection.
+            Resolve-Conflict "merge" "merge --abort"
+            if (-not $script:ConflictResolved) {
+                if ($Stashed) {
+                    Write-Host ""
+                    Write-Host "Your uncommitted changes are safely saved and will be"
+                    Write-Host "restored after conflicts are resolved."
+                    Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+                }
+                Wait-AndExit 1
+            }
+        }
+    } else {
+        # --- Squash-then-rebase path ---
+        Write-Host ""
+        Write-Host "Bundling your $Ahead local commit(s) into a single commit..."
+        $MergeBase = Invoke-ComposeGit merge-base HEAD "$UpstreamRemote/$RemoteBranch"
+
+        if ([string]::IsNullOrWhiteSpace($MergeBase)) {
+            Write-Host ""
+            Write-Host "The rebase option is not available for your setup." -ForegroundColor Red
+            Write-Host ""
+            Write-Host "This happens when your local changes and the update don't share"
+            Write-Host "a common starting point. This is unusual but not a problem."
+            Write-Host ""
+            Write-Host "Re-run the updater and choose option 1 (Merge) instead:"
+            Write-Host "  .\update_daaf.ps1"
+            if ($Stashed) {
+                Write-Host ""
+                Write-Host "Your uncommitted changes are safely saved and will be"
+                Write-Host "restored automatically when you re-run the updater."
+            }
+            Wait-AndExit 1
+        }
+
+        Invoke-ComposeGitVerbose reset --soft $MergeBase
+        if ($LASTEXITCODE -ne 0) {
+            Write-Host ""
+            Write-Host "ERROR: The rebase could not proceed - an internal step failed." -ForegroundColor Red
+            Write-Host ""
+            Write-Host "To restore to your previous state:"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+            if ($Stashed) {
+                Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+            }
+            Write-Host ""
+            Write-Host "Then re-run and try option 1 (Merge) instead:"
+            Write-Host "  .\update_daaf.ps1"
+            Write-Host ""
+            Write-Host "Your research files are not affected."
+            Wait-AndExit 1
+        }
+        Invoke-ComposeGitVerbose commit `
+            -m "Local DAAF customizations ($Ahead commits, squashed before update on $Timestamp)"
+        if ($LASTEXITCODE -ne 0) {
+            Write-Host ""
+            Write-Host "ERROR: Could not bundle your local changes for the rebase." -ForegroundColor Red
+            Write-Host ""
+            Write-Host "To restore to your previous state:"
+            Write-Host "  docker compose exec daaf-docker git -C /daaf reset --hard $BackupBranch"
+            if ($Stashed) {
+                Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+            }
+            Write-Host ""
+            Write-Host "Then re-run and try option 1 (Merge) instead:"
+            Write-Host "  .\update_daaf.ps1"
+            Write-Host ""
+            Write-Host "Your research files are not affected."
+            Wait-AndExit 1
+        }
+
+        Write-Host "Rebasing on top of the latest update..."
+        Invoke-ComposeGitNull rebase "$UpstreamRemote/$RemoteBranch"
+        if ($LASTEXITCODE -ne 0) {
+            # Call as statement -- see merge path comment above
+            Resolve-Conflict "rebase" "rebase --abort"
+            if (-not $script:ConflictResolved) {
+                if ($Stashed) {
+                    Write-Host ""
+                    Write-Host "Your uncommitted changes are safely saved and will be"
+                    Write-Host "restored after conflicts are resolved."
+                    Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+                }
+                Wait-AndExit 1
+            }
+        }
+    }
+
+    # Restore stashed changes
+    if ($Stashed) {
+        Write-Host "Restoring your changes..."
+        Invoke-ComposeGitNull stash pop
+        if ($LASTEXITCODE -ne 0) {
+            Resolve-StashConflict
+            if ($script:StashConflictResolved) {
+                if ($choice -eq "1") {
+                    Complete-Update $OldHead
+                } else {
+                    Complete-Update $OldHead "Your local changes have been rebased on top of the update."
+                }
+            } else {
+                if ($choice -eq "1") {
+                    Complete-Update $OldHead "Note: Uncommitted changes still need attention (see above)."
+                } else {
+                    Complete-Update $OldHead "Your commits were rebased. Uncommitted changes still need attention (see above)."
+                }
+            }
+            Wait-AndExit 0
+        }
+    }
+
+    if ($choice -eq "1") {
+        Complete-Update $OldHead
+    } else {
+        Complete-Update $OldHead "Your local changes have been rebased on top of the update."
+    }
+    Wait-AndExit 0
+}
+
+# =====================================================================
+# On default branch, no local commits - uncommitted changes only
+# =====================================================================
+if ($DirtyFiles) {
+    Write-Host ""
+    Write-Host "You have uncommitted changes to the following files:"
+    $DirtyFiles -split "`n" | ForEach-Object { if ($_.Trim()) { Write-Host "  $_" } }
+    Write-Host ""
+    Write-Host "These will be safely set aside during the update, then re-applied."
+    Write-Host ""
+    Write-Host "Options:"
+    Write-Host "  1) Stash changes, update, then re-apply"
+    Write-Host "  2) Show what changed first"
+    Write-Host "  3) Abort (no changes made)"
+    Write-Host ""
+    $choice = Read-UserChoice "  Choose [1/2/3]" @("1", "2", "3")
+
+    if ($choice -eq "3") {
+        Write-Host ""
+        Write-Host "Aborted. No changes made."
+        Wait-AndExit 0
+    }
+
+    if ($choice -eq "2") {
+        Write-Host ""
+        Invoke-ComposeExec git -C /daaf diff 2>$null
+        Write-Host ""
+        Write-Host "Lines starting with + are additions, - are removals."
+        Write-Host ""
+        Write-Host "Options:"
+        Write-Host "  1) Stash changes, update, then re-apply"
+        Write-Host "  3) Abort"
+        Write-Host ""
+        $choice = Read-UserChoice "  Choose [1/3]" @("1", "3")
+        if ($choice -eq "3") {
+            Write-Host ""
+            Write-Host "Aborted. No changes made."
+            Wait-AndExit 0
+        }
+    }
+
+    Write-Host "Setting aside your changes for safekeeping..."
+    Invoke-ComposeGitVerbose stash push -m "DAAF update backup $Timestamp"
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Could not safely set aside your uncommitted changes." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "No changes were made - your files are exactly as they were."
+        Write-Host ""
+        Write-Host "This can happen if there are new files that need to be committed first."
+        Write-Host "You can commit your changes, then re-run the updater:"
+        Write-Host "  .\run_daaf.ps1 bash"
+        Write-Host "  git add -A"
+        Write-Host "  git commit -m `"Save my changes before update`""
+        Write-Host "  exit"
+        Write-Host "  .\update_daaf.ps1"
+        Wait-AndExit 1
+    }
+
+    Write-Host "Pulling updates..."
+    Invoke-ComposeGitVerbose pull $UpstreamRemote $RemoteBranch
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host ""
+        Write-Host "ERROR: Could not download the latest updates." -ForegroundColor Red
+        Write-Host ""
+        Write-Host "Your uncommitted changes are safely saved."
+        Write-Host ""
+        Write-Host "Common causes:"
+        Write-Host "  - No internet connection"
+        Write-Host "  - GitHub may be down (check https://www.githubstatus.com)"
+        Write-Host ""
+        Write-Host "To restore your changes:"
+        Write-Host "  docker compose exec daaf-docker git -C /daaf stash pop"
+        Write-Host ""
+        Write-Host "Your research files are not affected."
+        Wait-AndExit 1
+    }
+
+    Write-Host "Re-applying your changes..."
+    Invoke-ComposeGitNull stash pop
+    if ($LASTEXITCODE -ne 0) {
+        Resolve-StashConflict
+        if ($script:StashConflictResolved) {
+            Complete-Update $OldHead "Your local changes have been re-applied on top of the update."
+        } else {
+            Complete-Update $OldHead "Note: Uncommitted changes still need attention (see above)."
+        }
+        Wait-AndExit 0
+    }
+
+    Complete-Update $OldHead "Your local changes have been re-applied on top of the update."
+    Wait-AndExit 0
+}
+
+# =====================================================================
+# Cleanest path: on default branch, no local commits, no changes
+# =====================================================================
+Write-Host ""
+Write-Host "Pulling updates..."
+Invoke-ComposeGitVerbose pull $UpstreamRemote $RemoteBranch
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Could not download the latest updates." -ForegroundColor Red
+    Write-Host ""
+    Write-Host "No changes were made to your installation."
+    Write-Host "Your research files are not affected."
+    Write-Host ""
+    Write-Host "Common causes:"
+    Write-Host "  - No internet connection"
+    Write-Host "  - GitHub may be down (check https://www.githubstatus.com)"
+    Write-Host ""
+    Write-Host "Once the issue is resolved, re-run:  .\update_daaf.ps1"
+    Wait-AndExit 1
+}
+
+Complete-Update $OldHead
+Wait-AndExit 0
diff --git a/scripts/host/update_daaf.sh b/scripts/host/update_daaf.sh
new file mode 100755
index 0000000..f3119a3
--- /dev/null
+++ b/scripts/host/update_daaf.sh
@@ -0,0 +1,1304 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Update Script (macOS / Linux)
+# ============================================================================
+# Usage:
+#   cd daaf-docker
+#   bash update_daaf.sh
+#
+#   To update from a specific branch (default: auto-detects main/master):
+#   DAAF_BRANCH=dev bash update_daaf.sh
+#
+# What this script does:
+#   1. Optionally backs up your DAAF installation (via backup_daaf.sh)
+#   2. Checks for updates and detects your git state
+#   3. Walks you through updating safely with options at each step
+#   4. Offers Claude Code to help resolve any merge conflicts
+#   5. Syncs utility scripts and auto-rebuilds if Docker files changed
+#
+# This script runs on the host and reaches into the container for git
+# operations. It composes the existing backup and rebuild scripts rather
+# than reimplementing their logic.
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Internet connection
+#   - Run from the daaf-docker directory
+# ============================================================================
+
+set -euo pipefail
+
+# Interactivity detection: use /dev/tty instead of stdin (fd 0).
+# When users run `curl ... | bash`, stdin is the pipe -- but the user's
+# terminal is still available at /dev/tty. CI environments lack a real
+# terminal entirely.
+#
+# DAAF_NESTED is separate: it suppresses the exit prompt (so nested
+# scripts don't double-pause) but does NOT suppress interactive prompts.
+# A nested script can still prompt the user for conflict resolution,
+# merge strategy, etc. -- as long as a real terminal is available.
+IS_INTERACTIVE=false
+if [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    IS_INTERACTIVE=true
+fi
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script like migrate_daaf.sh).
+if [ "${IS_INTERACTIVE}" = "true" ] && [ -z "${DAAF_NESTED:-}" ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+UPSTREAM_REPO="DAAF-Contribution-Community/daaf"
+CONTAINER_NAME="daaf-daaf-docker-1"
+TIMESTAMP=$(date +%Y-%m-%d-%H%M%S)
+BACKUP_BRANCH="backup/pre-update-${TIMESTAMP}"
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"compose ps"*"--format"*) echo "daaf-docker" ;;
+            *"compose exec"*"true"*) return 0 ;;
+            *"compose exec"*"test -f"*) return 0 ;;
+            *"fetch"*) return 0 ;;
+            *"rev-list HEAD..origin"*"--count"*) echo "0" ;;
+            *"rev-list"*"--count"*) echo "0" ;;
+            *"status --porcelain"*) echo "" ;;
+            *"symbolic-ref"*) echo "main" ;;
+            *"branch --show-current"*) echo "main" ;;
+            *"rev-parse --verify"*"backup/"*) return 1 ;;
+            *"rev-parse --verify"*"origin/"*) return 0 ;;
+            *"rev-parse"*"origin/main"*) echo "abc123def456" ;;
+            *"rev-parse"*"HEAD"*) echo "abc123def456" ;;
+            *"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+            *"diff --name-only"*"HEAD"*) echo "" ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Trap handler for unexpected failures ---
+cleanup_on_error() {
+    [ -n "${LOCK_DIR:-}" ] && rmdir "$LOCK_DIR" 2>/dev/null || true
+    echo "" >&2
+    echo "-------------------------------------------" >&2
+    echo "  Something went wrong unexpectedly" >&2
+    echo "-------------------------------------------" >&2
+    echo "" >&2
+    echo "Your research files and data are safe -- updates only change" >&2
+    echo "framework files, not your research/ folder." >&2
+    echo "" >&2
+    echo "Most likely causes:" >&2
+    echo "  - Docker Desktop stopped (laptop sleep, lid closed)" >&2
+    echo "  - Internet connection dropped during download" >&2
+    echo "  - A temporary Docker glitch" >&2
+    echo "" >&2
+    echo "To try again:" >&2
+    echo "  1. Make sure Docker Desktop is running" >&2
+    echo "  2. Re-run:  bash update_daaf.sh" >&2
+    echo "     (It is safe to re-run -- it will pick up where it left off.)" >&2
+    echo "" >&2
+    if [ "${STASHED:-false}" = true ]; then
+        echo "Your uncommitted changes are safely saved in a stash." >&2
+        echo "To restore them after fixing the issue:" >&2
+        echo "  docker compose exec daaf-docker git -C /daaf stash pop" >&2
+        echo "" >&2
+    fi
+    if docker compose exec -T daaf-docker \
+        git -C /daaf rev-parse --verify "${BACKUP_BRANCH}" \
+        </dev/null >/dev/null 2>&1; then
+        echo "A restore point was saved before the update started. To undo" >&2
+        echo "any partial changes:" >&2
+        echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}" >&2
+        echo "" >&2
+    fi
+}
+trap cleanup_on_error ERR
+
+# =====================================================================
+# Helper functions
+# =====================================================================
+
+prompt_choice() {
+    local prompt_text="$1"
+    local valid_choices="$2"
+    local choice=""
+    # Non-interactive mode: auto-select first valid choice
+    if [ "${IS_INTERACTIVE}" != "true" ]; then
+        choice=$(echo "${valid_choices}" | awk '{print $1}')
+        echo "  (Non-interactive mode -- auto-selecting: ${choice})" >&2
+        echo "${choice}"
+        return
+    fi
+    while true; do
+        read -r -p "${prompt_text}" choice < /dev/tty
+        choice=$(echo "${choice}" | tr '[:upper:]' '[:lower:]')
+        if echo "${valid_choices}" | grep -qw "${choice}"; then
+            echo "${choice}"
+            return
+        fi
+        echo "  Please enter one of: ${valid_choices}" >&2
+    done
+}
+
+# Override prompt_choice in dry-run mode (must come after the real definition
+# since bash function definitions are global, not block-scoped)
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    prompt_choice() {
+        local valid_choices="$2"
+        local first_choice
+        first_choice=$(echo "${valid_choices}" | awk '{print $1}')
+        echo "[DRY-RUN] Auto-selecting: ${first_choice}" >&2
+        echo "${first_choice}"
+    }
+fi
+
+handle_conflict() {
+    local conflict_type="$1"
+    local abort_cmd="$2"
+
+    local conflict_files
+    conflict_files=$(docker compose exec -T daaf-docker \
+        git -C /daaf diff --name-only --diff-filter=U </dev/null 2>/dev/null \
+        | tr -d '\r' || true)
+
+    echo ""
+    echo "-------------------------------------------"
+    echo "  Conflict detected"
+    echo "-------------------------------------------"
+    echo ""
+    echo "The same file(s) were changed both in the update and in your local"
+    echo "version. Git has marked the conflicting sections with <<<<<<< and"
+    echo ">>>>>>> markers."
+    echo ""
+    if [ -n "${conflict_files}" ]; then
+        echo "Conflicting files:"
+        echo "${conflict_files}" | sed 's/^/  /'
+        echo ""
+    fi
+    # Claude Code requires an interactive terminal (-it flag). When running
+    # non-interactively (e.g., nested from migrate_daaf.sh), skip straight
+    # to manual resolution instructions since launching Claude Code would
+    # fail with "the input device is not a TTY".
+    local choice="2"
+    if [ "${IS_INTERACTIVE}" = "true" ]; then
+        echo "Options:"
+        echo "  1) Launch Claude Code to help resolve the conflicts"
+        echo "     Claude Code can read the files, explain both sides, and walk"
+        echo "     you through the resolution interactively."
+        echo ""
+        echo "  2) Exit and resolve manually"
+        echo ""
+        choice=$(prompt_choice "  Choose [1/2]: " "1 2")
+    fi
+
+    if [ "${choice}" = "1" ]; then
+        echo ""
+        echo "Launching Claude Code inside the container..."
+        echo ""
+        echo "Copy and paste this prompt to get started:"
+        echo ""
+        if [ -n "${conflict_files}" ]; then
+            echo "  User support mode. I just ran the DAAF updater and got"
+            echo "  ${conflict_type} conflicts in these files:"
+            echo "${conflict_files}" | sed 's/^/    /'
+        else
+            echo "  User support mode. I just ran the DAAF updater and got"
+            echo "  ${conflict_type} conflicts."
+        fi
+        echo ""
+        echo "  Please help me resolve them. For each conflicting file:"
+        echo "  1. Read it and explain what changed on both sides of the"
+        echo "     conflict markers (<<<<<<< vs >>>>>>>)"
+        echo "  2. Help me decide which version to keep or how to combine them"
+        echo "  3. Edit the file to remove all conflict markers"
+        echo "  After all files are resolved, commit the result:"
+        echo "    git add ."
+        if [ "${conflict_type}" = "merge" ]; then
+            echo "    git commit -m \"Resolved merge conflicts from DAAF update\""
+        else
+            echo "    git rebase --continue"
+        fi
+        echo "  When finished, remind me to type /exit so the updater can"
+        echo "  finish its remaining steps."
+        echo ""
+        echo "IMPORTANT: When Claude Code is done, type /exit to return here."
+        echo "The updater still needs to finish a few steps after this."
+        echo ""
+        # When stdin is a pipe (curl|bash), Docker rejects the -t flag with
+        # "the input device is not a TTY". Redirect from /dev/tty on the
+        # host side so Docker sees a real TTY and allocates a PTY inside
+        # the container.
+        if [ -t 0 ]; then
+            docker compose exec -it daaf-docker claude || true
+        else
+            docker compose exec -it daaf-docker claude < /dev/tty || true
+        fi
+        echo ""
+
+        local remaining
+        remaining=$(docker compose exec -T daaf-docker \
+            git -C /daaf diff --name-only --diff-filter=U </dev/null 2>/dev/null \
+            | tr -d '\r' || true)
+
+        if [ -z "${remaining}" ]; then
+            echo "Conflicts resolved!"
+            echo ""
+            return 0
+        else
+            echo "Some conflicts still remain in these files:"
+            echo "${remaining}" | sed 's/^/  /'
+            echo ""
+            echo "You can keep working on them -- launch Claude Code and pick up"
+            echo "where you left off:"
+            echo "  bash run_daaf.sh"
+            echo ""
+            echo "Or to undo the update entirely (your research files are not affected):"
+            echo "  docker compose exec daaf-docker git -C /daaf ${abort_cmd}"
+            echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}"
+            return 1
+        fi
+    else
+        echo ""
+        echo "To resolve the conflicts manually, enter the container:"
+        echo "  bash run_daaf.sh bash"
+        echo ""
+        echo "Conflicting files contain markers that look like:"
+        echo "  <<<<<<< HEAD"
+        echo "  (your version)"
+        echo "  ======="
+        echo "  (the update's version)"
+        echo "  >>>>>>>"
+        echo "Edit each file to keep the version you want, removing all markers."
+        echo ""
+        if [ "${conflict_type}" = "merge" ]; then
+            echo "After resolving all files (inside the container):"
+            echo "  git add ."
+            echo "  git commit -m \"Resolved merge conflicts\""
+            echo "  exit"
+        else
+            echo "After resolving all files (inside the container):"
+            echo "  git add ."
+            echo "  git rebase --continue"
+            echo "  exit"
+        fi
+        echo ""
+        echo "To undo the update instead (run from your host terminal):"
+        echo "  docker compose exec daaf-docker git -C /daaf ${abort_cmd}"
+        echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}"
+        return 1
+    fi
+}
+
+handle_stash_conflict() {
+    echo ""
+    echo "The framework update was applied successfully!"
+    echo ""
+    echo "However, some of your uncommitted edits overlap with files that"
+    echo "changed in the update. Your edits are NOT lost -- they are saved"
+    echo "in a temporary holding area."
+    echo ""
+    # Claude Code requires an interactive terminal. When non-interactive,
+    # skip straight to manual resolution instructions.
+    local choice="2"
+    if [ "${IS_INTERACTIVE}" = "true" ]; then
+        echo "Options:"
+        echo "  1) Launch Claude Code to help resolve the conflicts"
+        echo "  2) Exit and resolve manually"
+        echo ""
+        choice=$(prompt_choice "  Choose [1/2]: " "1 2")
+    fi
+
+    if [ "${choice}" = "1" ]; then
+        echo ""
+        echo "Launching Claude Code inside the container..."
+        echo ""
+        echo "Copy and paste this prompt to get started:"
+        echo ""
+        echo "  User support mode. The DAAF updater applied the framework"
+        echo "  update successfully, but re-applying my uncommitted changes"
+        echo "  caused stash conflicts. Please help me resolve them:"
+        echo "  1. Run git status to find the conflicting files"
+        echo "  2. Read each one and explain both sides of the conflict"
+        echo "  3. Help me choose what to keep and edit the file to resolve it"
+        echo "  4. After all conflicts are resolved, run: git add ."
+        echo "     Then: git stash drop"
+        echo "     Then: git commit -m 'Resolved stash conflicts from DAAF update'"
+        echo "  When done, remind me to type /exit so the updater can"
+        echo "  finish its remaining steps."
+        echo ""
+        echo "IMPORTANT: When Claude Code is done, type /exit to return here."
+        echo "The updater still needs to finish a few steps after this."
+        echo ""
+        if [ -t 0 ]; then
+            docker compose exec -it daaf-docker claude || true
+        else
+            docker compose exec -it daaf-docker claude < /dev/tty || true
+        fi
+        echo ""
+
+        local remaining
+        remaining=$(docker compose exec -T daaf-docker \
+            git -C /daaf diff --name-only --diff-filter=U </dev/null 2>/dev/null \
+            | tr -d '\r' || true)
+
+        if [ -z "${remaining}" ]; then
+            echo "Conflicts resolved!"
+            return 0
+        else
+            echo "Some conflicts still remain in these files:"
+            echo "${remaining}" | sed 's/^/  /'
+            echo ""
+            echo "You can keep working on them -- launch Claude Code:"
+            echo "  bash run_daaf.sh"
+            echo ""
+            echo "Or to undo the update:"
+            echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}"
+            echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+            return 1
+        fi
+    else
+        echo ""
+        echo "To resolve, enter the container:"
+        echo "  bash run_daaf.sh bash"
+        echo "  (edit the conflicting files to remove the <<<<<<< markers)"
+        echo "  git add ."
+        echo "  git stash drop"
+        echo "  exit"
+        echo ""
+        echo "Or to discard your uncommitted edits and keep the update"
+        echo "(WARNING -- this cannot be undone):"
+        echo "  bash run_daaf.sh bash"
+        echo "  git checkout -- ."
+        echo "  git stash drop"
+        echo "  exit"
+        echo ""
+        echo "To undo the entire update:"
+        echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}"
+        echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+        return 1
+    fi
+}
+
+sync_host_scripts() {
+    local old_head="$1"
+
+    local new_head
+    new_head=$(docker compose exec -T daaf-docker \
+        git -C /daaf rev-parse HEAD </dev/null 2>/dev/null | tr -d '\r')
+
+    if [ "${old_head}" = "${new_head}" ]; then
+        return
+    fi
+
+    local changed_scripts
+    # Only sync platform-appropriate scripts (.sh on Unix) and shared files.
+    # Excludes install.sh (not needed post-install) and all .ps1 files.
+    changed_scripts=$(docker compose exec -T daaf-docker \
+        git -C /daaf diff --name-only "${old_head}..${new_head}" -- \
+        scripts/host/run_daaf.sh \
+        scripts/host/backup_daaf.sh \
+        scripts/host/restore_from_backup.sh \
+        scripts/host/rebuild_daaf.sh \
+        scripts/host/update_daaf.sh \
+        scripts/host/view_logs.sh \
+        scripts/host/view_notebooks.sh \
+        scripts/host/run_vscode.sh \
+        scripts/host/environment_settings_example.txt \
+        </dev/null 2>/dev/null | tr -d '\r' || true)
+
+    if [ -z "${changed_scripts}" ]; then
+        return
+    fi
+
+    echo "Syncing updated utility scripts..."
+    while IFS= read -r repo_path; do
+        [ -z "${repo_path}" ] && continue
+        local script
+        script=$(basename "${repo_path}")
+        if docker cp "${CONTAINER_NAME}:/daaf/${repo_path}" "./${script}" 2>/dev/null; then
+            chmod +x "./${script}" 2>/dev/null || true
+            echo "  Updated: ${script}"
+        else
+            echo "  Warning: could not copy ${script}. You can copy it manually:"
+            echo "    docker cp ${CONTAINER_NAME}:/daaf/${repo_path} ./${script}"
+        fi
+    done <<< "${changed_scripts}"
+    echo ""
+}
+
+check_build_changes() {
+    local old_head="$1"
+
+    local new_head
+    new_head=$(docker compose exec -T daaf-docker \
+        git -C /daaf rev-parse HEAD </dev/null 2>/dev/null | tr -d '\r')
+
+    if [ "${old_head}" = "${new_head}" ]; then
+        echo "No Dockerfile changes -- no container rebuild needed."
+        echo ""
+        return
+    fi
+
+    local build_changes
+    build_changes=$(docker compose exec -T daaf-docker \
+        git -C /daaf diff --name-only "${old_head}..${new_head}" -- \
+        Dockerfile docker-compose.yml \
+        </dev/null 2>/dev/null | tr -d '\r' || true)
+
+    if [ -z "${build_changes}" ]; then
+        echo "No Dockerfile changes -- no container rebuild needed."
+        echo ""
+        return
+    fi
+
+    echo ""
+    echo "Build files were updated in this release:"
+    echo "${build_changes}" | sed 's/^/  /'
+    echo ""
+    echo "A rebuild is needed for these changes to take full effect."
+    echo ""
+    local choice
+    choice=$(prompt_choice "  Run rebuild now? [y/n]: " "y n")
+
+    if [ "${choice}" = "y" ]; then
+        echo ""
+        if [ -f "rebuild_daaf.sh" ]; then
+            DAAF_NESTED=1 bash rebuild_daaf.sh
+        else
+            echo "rebuild_daaf.sh is not in your daaf-docker folder."
+            echo "You can retrieve it from the container and run it:"
+            echo "  docker cp ${CONTAINER_NAME}:/daaf/scripts/host/rebuild_daaf.sh ./rebuild_daaf.sh"
+            echo "  chmod +x ./rebuild_daaf.sh"
+            echo "  bash rebuild_daaf.sh"
+        fi
+    else
+        echo ""
+        echo "When you're ready to rebuild:"
+        echo "  bash rebuild_daaf.sh"
+    fi
+}
+
+finish_update() {
+    local old_head="$1"
+    local extra_msg="${2:-}"
+
+    sync_host_scripts "${old_head}"
+    check_build_changes "${old_head}"
+
+    echo ""
+    echo "=========================================="
+    echo "  Update complete!"
+    echo "=========================================="
+    echo ""
+    if [ -n "${extra_msg}" ]; then
+        echo "${extra_msg}"
+        echo ""
+    fi
+    echo "If you need to undo this update later:"
+    echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}"
+    echo ""
+    echo "  (This reverts DAAF's framework files to how they were before the"
+    echo "   update. Your research projects and data are not affected.)"
+    echo ""
+    echo "  To launch DAAF:"
+    echo "    bash run_daaf.sh"
+    echo ""
+}
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/update_daaf.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# =====================================================================
+# Portable concurrent-run lock (mkdir)
+# =====================================================================
+# Prevent two simultaneous update_daaf runs from corrupting git state
+# (double-stash, conflicting merges, backup branch pointing to wrong commit).
+# mkdir is atomic on all POSIX systems (Linux, macOS, Git Bash on Windows).
+# The lock directory is cleaned up via the EXIT trap when the script exits,
+# including exits via the ERR trap.
+LOCK_DIR="/tmp/daaf-update.lock.d"
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+    echo "ERROR: Another instance of update_daaf is already running." >&2
+    echo "       If you believe this is stale, remove: $LOCK_DIR" >&2
+    exit 1
+fi
+_daaf_prior_exit_trap=$(trap -p EXIT | sed -n "s/^trap -- '\\(.*\\)' EXIT$/\\1/p")
+trap 'rmdir "$LOCK_DIR" 2>/dev/null || true; '"$_daaf_prior_exit_trap" EXIT
+
+# =====================================================================
+# Main script
+# =====================================================================
+
+echo ""
+echo "=========================================="
+echo "  DAAF Updater"
+echo "=========================================="
+echo ""
+echo "Tip: If Claude Code is running inside the container, exit it first"
+echo "(/exit) to avoid file conflicts during the update."
+echo ""
+
+# --- Preflight: docker-compose.yml ---
+if [ ! -f "docker-compose.yml" ]; then
+    echo "ERROR: docker-compose.yml not found in the current directory."
+    echo ""
+    echo "This script must be run from your daaf-docker folder. Try:"
+    echo "  cd ~/daaf-docker"
+    echo "  bash update_daaf.sh"
+    echo ""
+    echo "If you installed DAAF somewhere else, cd to that folder first."
+    exit 1
+fi
+
+# --- Preflight: Docker installed ---
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal."
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    exit 1
+fi
+
+# --- Preflight: Docker running ---
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop does not seem to be running. Please start it and try again."
+    exit 1
+fi
+
+# --- Preflight: Start container if needed ---
+RUNNING=$(docker compose ps --status running --format '{{.Name}}' 2>/dev/null \
+    | grep -c "daaf-docker" || true)
+
+if [ "${RUNNING}" -eq 0 ]; then
+    echo "Starting DAAF container..."
+    if ! docker compose up -d; then
+        echo "ERROR: Failed to start the DAAF container."
+        echo ""
+        echo "No changes were made to your installation."
+        echo ""
+        echo "Common causes:"
+        echo "  - Another program is using the same ports"
+        echo "  - Docker Desktop needs more memory (Settings > Resources)"
+        echo ""
+        echo "Try restarting Docker Desktop, then:  bash update_daaf.sh"
+        exit 1
+    fi
+
+    RETRIES=0
+    MAX_RETRIES=30
+    READY_LOG=$(mktemp)
+    until docker compose exec -T daaf-docker true </dev/null 2>>"$READY_LOG"; do
+        RETRIES=$((RETRIES + 1))
+        if [ "${RETRIES}" -ge "${MAX_RETRIES}" ]; then
+            echo "ERROR: The DAAF container started but is not responding after 60 seconds." >&2
+            if [ -s "$READY_LOG" ]; then
+                echo "  Docker reported:" >&2
+                tail -5 "$READY_LOG" | sed 's/^/    /' >&2
+                echo "" >&2
+            fi
+            echo "No changes were made to your DAAF installation." >&2
+            echo "" >&2
+            echo "This can happen if Docker Desktop is under heavy load." >&2
+            echo "Try:" >&2
+            echo "  1. Restart Docker Desktop" >&2
+            echo "  2. Re-run:  bash update_daaf.sh" >&2
+            rm -f "$READY_LOG"
+            exit 1
+        fi
+        sleep 2
+    done
+    rm -f "$READY_LOG"
+    echo "Container started."
+    echo ""
+fi
+
+# --- Preflight: DAAF installed ---
+if ! docker compose exec -T daaf-docker test -f /daaf/CLAUDE.md </dev/null 2>/dev/null; then
+    echo "ERROR: DAAF does not appear to be installed in the container."
+    echo "Run the installer first. See:"
+    echo "  https://github.com/${UPSTREAM_REPO}#quick-start"
+    exit 1
+fi
+
+# =====================================================================
+# Offer backup
+# =====================================================================
+echo "-------------------------------------------"
+echo "  Backup recommendation"
+echo "-------------------------------------------"
+echo ""
+echo "It's a good idea to back up before updating, especially if you have"
+echo "research projects or local customizations you want to protect."
+echo ""
+if [ -f "backup_daaf.sh" ]; then
+    CHOICE=$(prompt_choice "  Run backup now? [y/n]: " "y n")
+    if [ "${CHOICE}" = "y" ]; then
+        echo ""
+        DAAF_NESTED=1 bash backup_daaf.sh
+        echo ""
+    fi
+else
+    echo "  (backup_daaf.sh not found in this directory -- skipping)"
+    echo ""
+fi
+
+# =====================================================================
+# Create git backup branch (lightweight restore point)
+# =====================================================================
+docker compose exec -T daaf-docker \
+    git -C /daaf branch "${BACKUP_BRANCH}" </dev/null 2>/dev/null || true
+
+OLD_HEAD=$(docker compose exec -T daaf-docker \
+    git -C /daaf rev-parse HEAD </dev/null 2>/dev/null | tr -d '\r')
+
+# =====================================================================
+# Check git remote
+# =====================================================================
+ORIGIN_URL=$(docker compose exec -T daaf-docker \
+    git -C /daaf remote get-url origin </dev/null 2>/dev/null | tr -d '\r' || true)
+
+if [ -z "${ORIGIN_URL}" ]; then
+    echo ""
+    echo "Your DAAF installation is not connected to the update server."
+    echo ""
+    echo "This usually means DAAF was installed from a downloaded zip file"
+    echo "instead of using the installer script. To connect it for updates,"
+    echo "run these commands one at a time:"
+    echo ""
+    echo "  bash run_daaf.sh bash"
+    echo "  git remote add origin https://github.com/${UPSTREAM_REPO}.git"
+    echo "  git fetch origin"
+    echo "  exit"
+    echo ""
+    echo "Then re-run:  bash update_daaf.sh"
+    exit 0
+fi
+
+# --- Determine upstream remote ---
+UPSTREAM_REMOTE="origin"
+
+if ! echo "${ORIGIN_URL}" | grep -qi "${UPSTREAM_REPO}"; then
+    echo "NOTE: Your 'origin' remote points to a fork:"
+    echo "  ${ORIGIN_URL}"
+    echo ""
+
+    UPSTREAM_URL=$(docker compose exec -T daaf-docker \
+        git -C /daaf remote get-url upstream </dev/null 2>/dev/null | tr -d '\r' || true)
+
+    if [ -n "${UPSTREAM_URL}" ]; then
+        UPSTREAM_REMOTE="upstream"
+        echo "Found 'upstream' remote -- will check for updates there."
+    else
+        echo "Your installation is connected to a personal copy (fork) of DAAF,"
+        echo "not the official release. To also receive official updates, run"
+        echo "these commands one at a time:"
+        echo ""
+        echo "  bash run_daaf.sh bash"
+        echo "  git remote add upstream https://github.com/${UPSTREAM_REPO}.git"
+        echo "  git fetch upstream"
+        echo "  exit"
+        echo ""
+        echo "Then re-run:  bash update_daaf.sh"
+        exit 0
+    fi
+    echo ""
+fi
+
+# =====================================================================
+# Fetch latest
+# =====================================================================
+echo "Fetching latest changes from ${UPSTREAM_REMOTE}..."
+if ! docker compose exec -T daaf-docker \
+    git -C /daaf fetch "${UPSTREAM_REMOTE}" </dev/null; then
+    echo ""
+    echo "Failed to fetch from ${UPSTREAM_REMOTE}."
+    echo "No changes were made to your installation."
+    echo ""
+    echo "Common causes:"
+    echo "  - No internet connection"
+    echo "  - GitHub may be experiencing an outage (check https://www.githubstatus.com)"
+    echo "  - Corporate firewall or proxy blocking the connection"
+    echo ""
+    echo "Once the issue is resolved, re-run:  bash update_daaf.sh"
+    exit 1
+fi
+
+# --- Unshallow if needed (shallow clones can't compute merge-base) ---
+if docker compose exec -T daaf-docker \
+    test -f /daaf/.git/shallow </dev/null 2>/dev/null; then
+    echo "Deepening repository history (installed from a shallow clone)..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf fetch --unshallow "${UPSTREAM_REMOTE}" </dev/null 2>/dev/null; then
+        echo "  (Already unshallowed or not needed.)"
+    fi
+    echo ""
+fi
+
+# =====================================================================
+# Resolve remote branch
+# =====================================================================
+REMOTE_BRANCH="${DAAF_BRANCH:-}"
+
+if [ -n "${REMOTE_BRANCH}" ]; then
+    # User specified a branch -- verify it exists on the remote
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf rev-parse --verify "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}" \
+        </dev/null >/dev/null 2>&1; then
+        echo ""
+        echo "The branch '${REMOTE_BRANCH}' (from DAAF_BRANCH) was not found on"
+        echo "${UPSTREAM_REMOTE}."
+        echo ""
+        echo "Your installation is unchanged. Double-check the branch name and try"
+        echo "again, or omit DAAF_BRANCH to use the default branch."
+        exit 1
+    fi
+    echo "Using branch: ${REMOTE_BRANCH} (from DAAF_BRANCH)"
+else
+    # Auto-detect: try main, then master
+    if docker compose exec -T daaf-docker \
+        git -C /daaf rev-parse --verify "${UPSTREAM_REMOTE}/main" \
+        </dev/null >/dev/null 2>&1; then
+        REMOTE_BRANCH="main"
+    elif docker compose exec -T daaf-docker \
+        git -C /daaf rev-parse --verify "${UPSTREAM_REMOTE}/master" \
+        </dev/null >/dev/null 2>&1; then
+        REMOTE_BRANCH="master"
+    fi
+fi
+
+if [ -z "${REMOTE_BRANCH}" ]; then
+    echo ""
+    echo "Could not find the update branch on the server."
+    echo "(Looked for 'main' and 'master' on ${UPSTREAM_REMOTE}, but neither exists.)"
+    echo ""
+    echo "Your installation is unchanged. No changes were made."
+    echo ""
+    echo "This usually means one of:"
+    echo "  - The repository was recently restructured and uses a different"
+    echo "    default branch name"
+    echo "  - The remote URL points to an empty or misconfigured repository"
+    echo "  - A network issue caused an incomplete fetch (try re-running)"
+    echo ""
+    echo "To troubleshoot:"
+    echo "  1. Check what branches exist on the remote:"
+    echo "       docker compose exec daaf-docker git -C /daaf ls-remote --heads ${UPSTREAM_REMOTE}"
+    echo "  2. If you see a branch listed, specify it explicitly:"
+    echo "       DAAF_BRANCH=branch-name bash update_daaf.sh"
+    echo "  3. Verify your remote URL is correct:"
+    echo "       docker compose exec daaf-docker git -C /daaf remote -v"
+    echo ""
+    echo "If this persists, check:"
+    echo "  https://github.com/${UPSTREAM_REPO}/issues"
+    exit 1
+fi
+
+# =====================================================================
+# Check current branch
+# =====================================================================
+CURRENT_BRANCH=$(docker compose exec -T daaf-docker \
+    git -C /daaf branch --show-current </dev/null 2>/dev/null | tr -d '\r')
+
+if [ -z "${CURRENT_BRANCH}" ]; then
+    echo ""
+    echo "Your DAAF installation is not on a named branch right now."
+    echo ""
+    echo "This can happen after installing from a specific version tag, after"
+    echo "a previous update was interrupted, or after running a manual git"
+    echo "command inside the container. Not a problem -- I'll handle it."
+    echo ""
+
+    # Create a branch at the current HEAD to preserve any local commits.
+    # Without this, checking out another branch would orphan those commits.
+    PRESERVED_BRANCH="local-work-$(date +%Y%m%d-%H%M%S)"
+    echo "Creating branch '${PRESERVED_BRANCH}' to preserve your current work..."
+    if docker compose exec -T daaf-docker \
+        git -C /daaf checkout -b "${PRESERVED_BRANCH}" </dev/null 2>/dev/null; then
+        CURRENT_BRANCH="${PRESERVED_BRANCH}"
+        echo "Done. Your commits are safe on branch '${PRESERVED_BRANCH}'."
+        echo ""
+    else
+        echo ""
+        echo "Could not create a branch from the current state."
+        echo ""
+        echo "To fix this manually:"
+        echo "  bash run_daaf.sh bash"
+        echo "  git checkout -b my-work"
+        echo "  exit"
+        echo ""
+        echo "Then re-run:  bash update_daaf.sh"
+        echo ""
+        echo "No changes were made. Your research files are not affected."
+        exit 1
+    fi
+fi
+
+# =====================================================================
+# Check if already up to date
+# =====================================================================
+LOCAL=$(docker compose exec -T daaf-docker \
+    git -C /daaf rev-parse HEAD </dev/null 2>/dev/null | tr -d '\r')
+REMOTE=$(docker compose exec -T daaf-docker \
+    git -C /daaf rev-parse "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}" \
+    </dev/null 2>/dev/null | tr -d '\r')
+
+DIRTY_FILES=$(docker compose exec -T daaf-docker \
+    git -C /daaf diff --name-only HEAD </dev/null 2>/dev/null | tr -d '\r' || true)
+
+if [ "${CURRENT_BRANCH}" = "${REMOTE_BRANCH}" ] \
+    && [ "${LOCAL}" = "${REMOTE}" ] \
+    && [ -z "${DIRTY_FILES}" ]; then
+    echo ""
+    echo "Already up to date! Nothing to do."
+    echo ""
+    exit 0
+fi
+
+# =====================================================================
+# Compute ahead/behind
+# =====================================================================
+AHEAD=$(docker compose exec -T daaf-docker \
+    git -C /daaf rev-list --count "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}..HEAD" \
+    </dev/null 2>/dev/null | tr -d '\r' || echo "0")
+BEHIND=$(docker compose exec -T daaf-docker \
+    git -C /daaf rev-list --count "HEAD..${UPSTREAM_REMOTE}/${REMOTE_BRANCH}" \
+    </dev/null 2>/dev/null | tr -d '\r' || echo "0")
+
+if [ "${BEHIND}" != "0" ]; then
+    echo ""
+    echo "Updates available: ${BEHIND} new commit(s) on ${UPSTREAM_REMOTE}/${REMOTE_BRANCH}."
+fi
+
+# =====================================================================
+# Early exit: no upstream updates for non-default branches
+# =====================================================================
+if [ "${CURRENT_BRANCH}" != "${REMOTE_BRANCH}" ] && [ "${BEHIND}" = "0" ]; then
+    echo ""
+    echo "Already up to date! Your branch '${CURRENT_BRANCH}' has all the latest"
+    echo "changes from ${UPSTREAM_REMOTE}/${REMOTE_BRANCH}. Nothing to do."
+    echo ""
+    exit 0
+fi
+
+# =====================================================================
+# Handle non-default branch
+# =====================================================================
+if [ "${CURRENT_BRANCH}" != "${REMOTE_BRANCH}" ]; then
+    echo ""
+    echo "You are on branch '${CURRENT_BRANCH}', not '${REMOTE_BRANCH}'."
+    echo ""
+    echo "DAAF updates are published to '${REMOTE_BRANCH}'. This will pull the"
+    echo "latest updates into '${REMOTE_BRANCH}', then merge them into your branch."
+    echo ""
+    echo "Options:"
+    echo "  1) Update: pull into ${REMOTE_BRANCH}, then merge into '${CURRENT_BRANCH}'"
+    echo "  2) Abort (no changes made)"
+    echo ""
+    CHOICE=$(prompt_choice "  Choose [1/2]: " "1 2")
+
+    if [ "${CHOICE}" = "2" ]; then
+        echo ""
+        echo "Aborted. No changes made."
+        exit 0
+    fi
+
+    STASHED=false
+    if [ -n "${DIRTY_FILES}" ]; then
+        echo ""
+        echo "Setting aside your uncommitted changes for safekeeping..."
+        if ! docker compose exec -T daaf-docker \
+            git -C /daaf stash push -m "DAAF update backup ${TIMESTAMP}" </dev/null; then
+            echo ""
+            echo "ERROR: Could not safely set aside your uncommitted changes."
+            echo ""
+            echo "No changes were made -- your files are exactly as they were."
+            echo ""
+            echo "This can happen if there are new files that need to be committed first."
+            echo "You can commit your changes, then re-run the updater:"
+            echo "  bash run_daaf.sh bash"
+            echo "  git add -A"
+            echo "  git commit -m \"Save my changes before update\""
+            echo "  exit"
+            echo "  bash update_daaf.sh"
+            exit 1
+        fi
+        STASHED=true
+    fi
+
+    echo "Switching to ${REMOTE_BRANCH}..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf checkout "${REMOTE_BRANCH}" </dev/null; then
+        echo ""
+        echo "ERROR: Could not switch to the '${REMOTE_BRANCH}' branch."
+        echo ""
+        echo "This is unusual. Your files are unchanged."
+        if [ "${STASHED}" = true ]; then
+            echo "Your uncommitted changes are safely saved."
+            echo "To restore them: docker compose exec daaf-docker git -C /daaf stash pop"
+        fi
+        echo ""
+        echo "Your research files are not affected."
+        exit 1
+    fi
+
+    echo "Pulling updates..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf pull "${UPSTREAM_REMOTE}" "${REMOTE_BRANCH}" </dev/null; then
+        echo ""
+        echo "ERROR: Could not download the latest updates."
+        echo ""
+        echo "Common causes:"
+        echo "  - No internet connection"
+        echo "  - GitHub may be down (check https://www.githubstatus.com)"
+        echo ""
+        echo "To get back to where you were:"
+        echo "  docker compose exec daaf-docker git -C /daaf checkout ${CURRENT_BRANCH}"
+        if [ "${STASHED}" = true ]; then
+            echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+        fi
+        echo ""
+        echo "Your research files are not affected."
+        exit 1
+    fi
+
+    echo "Switching back to '${CURRENT_BRANCH}'..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf checkout "${CURRENT_BRANCH}" </dev/null; then
+        echo ""
+        echo "ERROR: Could not switch back to your '${CURRENT_BRANCH}' branch."
+        echo ""
+        echo "The updates were downloaded successfully, but the script could"
+        echo "not return to your branch. Your research files are safe."
+        echo ""
+        echo "To fix this, enter the container and switch manually:"
+        echo "  bash run_daaf.sh bash"
+        echo "  git checkout ${CURRENT_BRANCH}"
+        echo "  exit"
+        echo ""
+        echo "If that also fails, you can restore to before the update:"
+        echo "  docker compose exec daaf-docker git -C /daaf reset --hard ${BACKUP_BRANCH}"
+        if [ "${STASHED}" = true ]; then
+            echo ""
+            echo "Your uncommitted changes are still saved. After switching back:"
+            echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+        fi
+        exit 1
+    fi
+
+    echo "Merging ${REMOTE_BRANCH} into '${CURRENT_BRANCH}'..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf merge "${REMOTE_BRANCH}" </dev/null; then
+        if ! handle_conflict "merge" "merge --abort"; then
+            if [ "${STASHED}" = true ]; then
+                echo ""
+                echo "Your uncommitted changes are safely saved and will be"
+                echo "restored after conflicts are resolved."
+                echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+            fi
+            exit 1
+        fi
+    fi
+
+    if [ "${STASHED}" = true ]; then
+        echo "Restoring your changes..."
+        if ! docker compose exec -T daaf-docker \
+            git -C /daaf stash pop </dev/null; then
+            if handle_stash_conflict; then
+                finish_update "${OLD_HEAD}"
+            else
+                finish_update "${OLD_HEAD}" \
+                    "Note: Uncommitted changes still need attention (see above)."
+            fi
+            exit 0
+        fi
+    fi
+
+    finish_update "${OLD_HEAD}"
+    exit 0
+fi
+
+# =====================================================================
+# On default branch -- local commits
+# =====================================================================
+if [ "${AHEAD}" -gt 0 ]; then
+    echo ""
+    echo "You have ${AHEAD} local commit(s) on ${REMOTE_BRANCH} that aren't in"
+    echo "the official DAAF release."
+    echo ""
+    echo "Your local commits:"
+    docker compose exec -T daaf-docker \
+        git -C /daaf log --oneline "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}..HEAD" \
+        </dev/null | tr -d '\r' | sed 's/^/  /'
+    echo ""
+    echo "Options:"
+    echo ""
+    echo "  1) MERGE (recommended)"
+    echo "     Combines your changes with the update. Your commits stay as-is."
+    echo "     Git creates a merge commit tying both histories together."
+    echo ""
+    echo "  2) REBASE (cleaner history)"
+    echo "     Bundles your local changes into one commit and places it on top"
+    echo "     of the latest update. Individual commit messages are combined."
+    echo ""
+    echo "  3) ABORT (no changes made)"
+    echo ""
+    CHOICE=$(prompt_choice "  Choose [1/2/3]: " "1 2 3")
+
+    if [ "${CHOICE}" = "3" ]; then
+        echo ""
+        echo "Aborted. No changes made."
+        exit 0
+    fi
+
+    STASHED=false
+    if [ -n "${DIRTY_FILES}" ]; then
+        echo ""
+        echo "Setting aside your uncommitted changes for safekeeping..."
+        if ! docker compose exec -T daaf-docker \
+            git -C /daaf stash push -m "DAAF update backup ${TIMESTAMP}" </dev/null; then
+            echo ""
+            echo "ERROR: Could not safely set aside your uncommitted changes."
+            echo ""
+            echo "No changes were made -- your files are exactly as they were."
+            echo ""
+            echo "This can happen if there are new files that need to be committed first."
+            echo "You can commit your changes, then re-run the updater:"
+            echo "  bash run_daaf.sh bash"
+            echo "  git add -A"
+            echo "  git commit -m \"Save my changes before update\""
+            echo "  exit"
+            echo "  bash update_daaf.sh"
+            exit 1
+        fi
+        STASHED=true
+    fi
+
+    if [ "${CHOICE}" = "1" ]; then
+        # --- Merge path ---
+        echo "Merging upstream updates..."
+        if ! docker compose exec -T daaf-docker \
+            git -C /daaf merge "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}" \
+            -m "Merge DAAF upstream updates" </dev/null; then
+            if ! handle_conflict "merge" "merge --abort"; then
+                if [ "${STASHED}" = true ]; then
+                    echo ""
+                    echo "Your uncommitted changes are safely saved and will be"
+                    echo "restored after conflicts are resolved."
+                    echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+                fi
+                exit 1
+            fi
+        fi
+    else
+        # --- Squash-then-rebase path ---
+        echo ""
+        echo "Bundling your ${AHEAD} local commit(s) into a single commit..."
+        MERGE_BASE=$(docker compose exec -T daaf-docker \
+            git -C /daaf merge-base HEAD "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}" \
+            </dev/null 2>/dev/null | tr -d '\r' || true)
+
+        if [ -z "${MERGE_BASE}" ]; then
+            echo ""
+            echo "The rebase option is not available for your setup."
+            echo ""
+            echo "This happens when your local changes and the update don't share"
+            echo "a common starting point. This is unusual but not a problem."
+            echo ""
+            echo "Re-run the updater and choose option 1 (Merge) instead:"
+            echo "  bash update_daaf.sh"
+            if [ "${STASHED}" = true ]; then
+                echo ""
+                echo "Your uncommitted changes are safely saved and will be"
+                echo "restored automatically when you re-run the updater."
+            fi
+            exit 1
+        fi
+
+        docker compose exec -T daaf-docker \
+            git -C /daaf reset --soft "${MERGE_BASE}" </dev/null
+        docker compose exec -T daaf-docker \
+            git -C /daaf commit \
+            -m "Local DAAF customizations (${AHEAD} commits, squashed before update on ${TIMESTAMP})" \
+            </dev/null
+
+        echo "Rebasing on top of the latest update..."
+        if ! docker compose exec -T daaf-docker \
+            git -C /daaf rebase "${UPSTREAM_REMOTE}/${REMOTE_BRANCH}" </dev/null; then
+            if ! handle_conflict "rebase" "rebase --abort"; then
+                if [ "${STASHED}" = true ]; then
+                    echo ""
+                    echo "Your uncommitted changes are safely saved and will be"
+                    echo "restored after conflicts are resolved."
+                    echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+                fi
+                exit 1
+            fi
+        fi
+    fi
+
+    # Restore stashed changes
+    if [ "${STASHED}" = true ]; then
+        echo "Restoring your changes..."
+        if ! docker compose exec -T daaf-docker \
+            git -C /daaf stash pop </dev/null; then
+            if handle_stash_conflict; then
+                if [ "${CHOICE}" = "1" ]; then
+                    finish_update "${OLD_HEAD}"
+                else
+                    finish_update "${OLD_HEAD}" \
+                        "Your local changes have been rebased on top of the update."
+                fi
+            else
+                if [ "${CHOICE}" = "1" ]; then
+                    finish_update "${OLD_HEAD}" \
+                        "Note: Uncommitted changes still need attention (see above)."
+                else
+                    finish_update "${OLD_HEAD}" \
+                        "Your commits were rebased. Uncommitted changes still need attention (see above)."
+                fi
+            fi
+            exit 0
+        fi
+    fi
+
+    if [ "${CHOICE}" = "1" ]; then
+        finish_update "${OLD_HEAD}"
+    else
+        finish_update "${OLD_HEAD}" \
+            "Your local changes have been rebased on top of the update."
+    fi
+    exit 0
+fi
+
+# =====================================================================
+# On default branch, no local commits -- uncommitted changes only
+# =====================================================================
+if [ -n "${DIRTY_FILES}" ]; then
+    echo ""
+    echo "You have uncommitted changes to the following files:"
+    echo "${DIRTY_FILES}" | sed 's/^/  /'
+    echo ""
+    echo "These will be safely set aside during the update, then re-applied."
+    echo ""
+    echo "Options:"
+    echo "  1) Stash changes, update, then re-apply"
+    echo "  2) Show what changed first"
+    echo "  3) Abort (no changes made)"
+    echo ""
+    CHOICE=$(prompt_choice "  Choose [1/2/3]: " "1 2 3")
+
+    if [ "${CHOICE}" = "3" ]; then
+        echo ""
+        echo "Aborted. No changes made."
+        exit 0
+    fi
+
+    if [ "${CHOICE}" = "2" ]; then
+        echo ""
+        docker compose exec -T daaf-docker \
+            git -C /daaf diff </dev/null | tr -d '\r'
+        echo ""
+        echo "Lines starting with + are additions, - are removals."
+        echo ""
+        echo "Options:"
+        echo "  1) Stash changes, update, then re-apply"
+        echo "  3) Abort"
+        echo ""
+        CHOICE=$(prompt_choice "  Choose [1/3]: " "1 3")
+        if [ "${CHOICE}" = "3" ]; then
+            echo ""
+            echo "Aborted. No changes made."
+            exit 0
+        fi
+    fi
+
+    echo "Setting aside your changes for safekeeping..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf stash push -m "DAAF update backup ${TIMESTAMP}" </dev/null; then
+        echo ""
+        echo "ERROR: Could not safely set aside your uncommitted changes."
+        echo ""
+        echo "No changes were made -- your files are exactly as they were."
+        echo ""
+        echo "This can happen if there are new files that need to be committed first."
+        echo "You can commit your changes, then re-run the updater:"
+        echo "  bash run_daaf.sh bash"
+        echo "  git add -A"
+        echo "  git commit -m \"Save my changes before update\""
+        echo "  exit"
+        echo "  bash update_daaf.sh"
+        exit 1
+    fi
+
+    echo "Pulling updates..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf pull "${UPSTREAM_REMOTE}" "${REMOTE_BRANCH}" </dev/null; then
+        echo ""
+        echo "ERROR: Could not download the latest updates."
+        echo ""
+        echo "Your uncommitted changes are safely saved."
+        echo ""
+        echo "Common causes:"
+        echo "  - No internet connection"
+        echo "  - GitHub may be down (check https://www.githubstatus.com)"
+        echo ""
+        echo "To restore your changes:"
+        echo "  docker compose exec daaf-docker git -C /daaf stash pop"
+        echo ""
+        echo "Your research files are not affected."
+        exit 1
+    fi
+
+    echo "Re-applying your changes..."
+    if ! docker compose exec -T daaf-docker \
+        git -C /daaf stash pop </dev/null; then
+        if handle_stash_conflict; then
+            finish_update "${OLD_HEAD}" \
+                "Your local changes have been re-applied on top of the update."
+            exit 0
+        else
+            finish_update "${OLD_HEAD}" \
+                "Note: Uncommitted changes still need attention (see above)."
+            exit 0
+        fi
+    fi
+
+    finish_update "${OLD_HEAD}" \
+        "Your local changes have been re-applied on top of the update."
+    exit 0
+fi
+
+# =====================================================================
+# Cleanest path: on default branch, no local commits, no changes
+# =====================================================================
+echo ""
+echo "Pulling updates..."
+if ! docker compose exec -T daaf-docker \
+    git -C /daaf pull "${UPSTREAM_REMOTE}" "${REMOTE_BRANCH}" </dev/null; then
+    echo ""
+    echo "ERROR: Could not download the latest updates."
+    echo ""
+    echo "No changes were made to your installation."
+    echo "Your research files are not affected."
+    echo ""
+    echo "Common causes:"
+    echo "  - No internet connection"
+    echo "  - GitHub may be down (check https://www.githubstatus.com)"
+    echo ""
+    echo "Once the issue is resolved, re-run:  bash update_daaf.sh"
+    exit 1
+fi
+
+finish_update "${OLD_HEAD}"
diff --git a/scripts/host/view_logs.ps1 b/scripts/host/view_logs.ps1
new file mode 100644
index 0000000..b589d1d
--- /dev/null
+++ b/scripts/host/view_logs.ps1
@@ -0,0 +1,233 @@
+# ============================================================================
+# DAAF Log Explorer (Windows PowerShell)
+# ============================================================================
+# Opens the interactive session log viewer in your browser.
+# Starts the DAAF container if needed, recovers any orphaned session logs,
+# presents available log sources, and starts an HTTP server.
+#
+# Usage:
+#   cd daaf-docker
+#   .\view_logs.ps1              # Interactive menu
+#   .\view_logs.ps1 --archive    # Skip menu, open full archive
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Port 2719 mapped in docker-compose.yml
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*compose ps*--format*" { Write-Output "daaf-docker" }
+            "*compose up*" { return }
+            "*compose exec*" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/view_logs.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# --- Parse arguments ---
+$SkipMenu = $false
+$SelectedSource = ""
+
+foreach ($arg in $args) {
+    switch ($arg) {
+        "--archive" {
+            $SkipMenu = $true
+            $SelectedSource = "--archive"
+        }
+        { $_ -in "-h", "--help" } {
+            Write-Host "Usage: .\view_logs.ps1              # Interactive log source menu"
+            Write-Host "       .\view_logs.ps1 --archive    # Open full session archive directly"
+            exit 0
+        }
+        default {
+            Write-Host "ERROR: Unknown argument: $arg" -ForegroundColor Red
+            Write-Host "Usage: .\view_logs.ps1 [--archive]"
+            Wait-AndExit 1
+        }
+    }
+}
+
+# In non-interactive contexts, default to archive view
+if ($env:DAAF_DRY_RUN -eq "1" -or $env:CI -or $env:DAAF_NESTED) {
+    $SkipMenu = $true
+    if (-not $SelectedSource) { $SelectedSource = "--archive" }
+}
+
+# --- Preflight ---
+if (-not (Test-Path "docker-compose.yml")) {
+    Write-Host "ERROR: docker-compose.yml not found in the current directory." -ForegroundColor Red
+    Write-Host "Please run this script from your daaf-docker folder."
+    Wait-AndExit 1
+}
+
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop is not running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Start container if not running ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$RunningOutput = docker compose ps --status running --format '{{.Name}}' 2>&1
+$ErrorActionPreference = $savedEAP
+$Running = ($RunningOutput | Select-String "daaf-docker").Count
+
+if ($Running -eq 0) {
+    Write-Host "Starting DAAF container..."
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose up -d
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "ERROR: Failed to start the container." -ForegroundColor Red
+        Wait-AndExit 1
+    }
+    Write-Host "Container started."
+} else {
+    Write-Host "DAAF container is running."
+}
+
+# --- Recover orphaned session logs ---
+# The recovery hook archives transcripts from sessions that ended without
+# a clean SessionEnd (e.g., crashes). The hook's foreground portion returns
+# immediately, but actual recovery runs in a detached background subshell
+# inside the container (& disown). The sleep gives that subprocess time to
+# finish before we discover log sources.
+Write-Host "Checking for orphaned session logs..."
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+'{"session_id":"recovery","transcript_path":"/home/appuser/.claude/projects/-daaf/_.jsonl"}' | docker compose exec -T -e CLAUDE_PROJECT_DIR=/daaf daaf-docker bash /daaf/.claude/hooks/recover-session-logs.sh 2>$null
+$global:LASTEXITCODE = 0
+$ErrorActionPreference = $savedEAP
+if ($env:DAAF_DRY_RUN -ne "1") {
+    Start-Sleep -Seconds 2
+}
+
+# --- Select log source ---
+if (-not $SkipMenu) {
+    # Discover all log sources via helper script (avoids bash -c quoting issues)
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    $SourcesRaw = docker compose exec -T daaf-docker bash /daaf/scripts/discover_log_sources.sh 2>$null
+    $ErrorActionPreference = $savedEAP
+
+    # Build menu from pipe-delimited output
+    $MenuPaths = @()
+    $MenuLabels = @()
+
+    if ($SourcesRaw) {
+        foreach ($line in @($SourcesRaw)) {
+            $cleanLine = "$line".Trim()
+            if (-not $cleanLine) { continue }
+            $parts = $cleanLine -split '\|', 2
+            if ($parts.Count -lt 2) { continue }
+            $sourceId = $parts[0].Trim()
+            $sessionCount = 0
+            $null = [int]::TryParse(($parts[1] -replace '\D', '').Trim(), [ref]$sessionCount)
+            if ($sessionCount -eq 0) { continue }
+
+            $countWord = "sessions"
+            if ($sessionCount -eq 1) { $countWord = "session" }
+
+            if ($sourceId -eq "ARCHIVE") {
+                $MenuPaths += "--archive"
+                $MenuLabels += "Full session archive ($sessionCount $countWord)"
+            } else {
+                $folderName = Split-Path $sourceId -Leaf
+                $underscoreIdx = $folderName.IndexOf('_')
+                if ($underscoreIdx -gt 0) {
+                    $displayDate = $folderName.Substring(0, $underscoreIdx)
+                    $displayTitle = $folderName.Substring($underscoreIdx + 1) -replace '_', ' '
+                } else {
+                    $displayDate = ""
+                    $displayTitle = $folderName
+                }
+                $MenuPaths += $sourceId
+                $MenuLabels += "$displayDate $displayTitle ($sessionCount $countWord)"
+            }
+        }
+    }
+
+    if ($MenuPaths.Count -eq 0) {
+        Write-Host ""
+        Write-Host "No log sources found. Run a DAAF session first to generate logs."
+        Wait-AndExit 0
+    }
+
+    Write-Host ""
+    Write-Host "DAAF Log Explorer -- Select a log source:"
+    Write-Host ""
+    for ($i = 0; $i -lt $MenuLabels.Count; $i++) {
+        Write-Host ("  {0}) {1}" -f ($i + 1), $MenuLabels[$i])
+    }
+    Write-Host ""
+    $selection = Read-Host "Enter selection"
+
+    $selNum = 0
+    if (-not [int]::TryParse($selection, [ref]$selNum) -or $selNum -lt 1 -or $selNum -gt $MenuPaths.Count) {
+        Write-Host "ERROR: Invalid selection: $selection" -ForegroundColor Red
+        Wait-AndExit 1
+    }
+
+    $SelectedSource = $MenuPaths[$selNum - 1]
+}
+
+# --- Launch log viewer ---
+Write-Host ""
+Write-Host "Opening DAAF Log Explorer..."
+Write-Host ""
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+if ($SelectedSource -eq "--archive") {
+    docker compose exec daaf-docker bash /daaf/scripts/generate_log_viewer.sh --archive
+} else {
+    docker compose exec daaf-docker bash /daaf/scripts/generate_log_viewer.sh "$SelectedSource"
+}
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to generate log viewer." -ForegroundColor Red
+    Write-Host "  The container may not be running, or there may be no session logs to display." -ForegroundColor Red
+    Write-Host "  Try: docker compose logs daaf-docker" -ForegroundColor Yellow
+}
+
+# If the server was already running, the command above returns immediately
+# after printing the URL. Wait-AndExit keeps the window open so the user
+# can read/copy it.
+Wait-AndExit 0
diff --git a/scripts/host/view_logs.sh b/scripts/host/view_logs.sh
new file mode 100755
index 0000000..e0d3d11
--- /dev/null
+++ b/scripts/host/view_logs.sh
@@ -0,0 +1,208 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Log Explorer (macOS / Linux)
+# ============================================================================
+# Opens the interactive session log viewer in your browser.
+# Starts the DAAF container if needed, recovers any orphaned session logs,
+# presents available log sources, and starts an HTTP server.
+#
+# Usage:
+#   cd daaf-docker
+#   bash view_logs.sh              # Interactive menu
+#   bash view_logs.sh --archive    # Skip menu, open full archive
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Port 2719 mapped in docker-compose.yml
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script).
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"compose ps --status running"*"--format"*) echo "daaf-docker" ;;
+            *"compose exec"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/view_logs.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# --- Parse arguments ---
+SKIP_MENU=false
+SELECTED_SOURCE=""
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --archive)
+            SKIP_MENU=true
+            SELECTED_SOURCE="--archive"
+            shift
+            ;;
+        -h|--help)
+            echo "Usage: bash $0              # Interactive log source menu"
+            echo "       bash $0 --archive    # Open full session archive directly"
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown argument: $1" >&2
+            echo "Usage: bash $0 [--archive]" >&2
+            exit 1
+            ;;
+    esac
+done
+
+# In non-interactive contexts, default to archive view
+if [ "${DAAF_DRY_RUN:-}" = "1" ] || [ -n "${CI:-}" ] || [ -n "${DAAF_NESTED:-}" ] || ! [ -c /dev/tty ]; then
+    SKIP_MENU=true
+    SELECTED_SOURCE="${SELECTED_SOURCE:---archive}"
+fi
+
+# --- Preflight ---
+if [ ! -f "docker-compose.yml" ]; then
+    echo "ERROR: docker-compose.yml not found in the current directory." >&2
+    echo "Please run this script from your daaf-docker folder." >&2
+    exit 1
+fi
+
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." >&2
+    echo "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/" >&2
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop is not running. Please start it and try again." >&2
+    exit 1
+fi
+
+# --- Start container if not running ---
+RUNNING=$(docker compose ps --status running --format '{{.Name}}' 2>/dev/null | grep -c "daaf-docker" || true)
+
+if [ "${RUNNING}" -eq 0 ]; then
+    echo "Starting DAAF container..."
+    if ! docker compose up -d; then
+        echo "ERROR: Failed to start the container." >&2
+        echo "  Try: docker compose logs daaf-docker" >&2
+        exit 1
+    fi
+    echo "Container started."
+else
+    echo "DAAF container is running."
+fi
+
+# --- Recover orphaned session logs ---
+# The recovery hook archives transcripts from sessions that ended without
+# a clean SessionEnd (e.g., crashes). The hook's foreground portion returns
+# immediately, but actual recovery runs in a detached background subshell
+# inside the container (& disown). The sleep gives that subprocess time to
+# finish before we discover log sources.
+echo "Checking for orphaned session logs..."
+echo '{"session_id":"recovery","transcript_path":"/home/appuser/.claude/projects/-daaf/_.jsonl"}' | docker compose exec -T -e CLAUDE_PROJECT_DIR=/daaf daaf-docker bash /daaf/.claude/hooks/recover-session-logs.sh 2>/dev/null || true
+if [ "${DAAF_DRY_RUN:-}" != "1" ]; then
+    sleep 2
+fi
+
+# --- Select log source ---
+if [ "$SKIP_MENU" = false ]; then
+    # Discover all log sources via helper script (avoids bash -c quoting issues)
+    SOURCES_RAW=$(docker compose exec -T daaf-docker bash /daaf/scripts/discover_log_sources.sh 2>/dev/null | tr -d '\r') || SOURCES_RAW=""
+
+    # Build menu arrays from pipe-delimited output
+    declare -a MENU_PATHS=()
+    declare -a MENU_LABELS=()
+
+    if [ -n "$SOURCES_RAW" ]; then
+        while IFS='|' read -r source_id session_count; do
+            [ -z "$source_id" ] && continue
+            session_count=$(echo "$session_count" | tr -d '[:space:]')
+            if ! [[ "$session_count" =~ ^[0-9]+$ ]]; then continue; fi
+
+            if [ "$session_count" -eq 1 ]; then
+                count_label="$session_count session"
+            else
+                count_label="$session_count sessions"
+            fi
+
+            if [ "$source_id" = "ARCHIVE" ]; then
+                MENU_PATHS+=("--archive")
+                MENU_LABELS+=("Full session archive ($count_label)")
+            else
+                folder_name=$(basename "$source_id")
+                display_date="${folder_name%%_*}"
+                display_title=$(echo "${folder_name#*_}" | tr '_' ' ')
+                MENU_PATHS+=("$source_id")
+                MENU_LABELS+=("$display_date $display_title ($count_label)")
+            fi
+        done <<< "$SOURCES_RAW"
+    fi
+
+    if [ ${#MENU_PATHS[@]} -eq 0 ]; then
+        echo ""
+        echo "No log sources found. Run a DAAF session first to generate logs."
+        exit 0
+    fi
+
+    echo ""
+    echo "DAAF Log Explorer -- Select a log source:"
+    echo ""
+    for i in "${!MENU_LABELS[@]}"; do
+        printf "  %d) %s\n" "$((i + 1))" "${MENU_LABELS[$i]}"
+    done
+    echo ""
+    read -r -p "Enter selection: " SELECTION < /dev/tty
+
+    if [ -z "$SELECTION" ] || ! [[ "$SELECTION" =~ ^[0-9]+$ ]] || [ "$SELECTION" -lt 1 ] || [ "$SELECTION" -gt ${#MENU_PATHS[@]} ]; then
+        echo "ERROR: Invalid selection: $SELECTION" >&2
+        exit 1
+    fi
+
+    SELECTED_SOURCE="${MENU_PATHS[$((SELECTION - 1))]}"
+fi
+
+# --- Launch log viewer ---
+echo ""
+echo "Opening DAAF Log Explorer..."
+echo ""
+
+declare -a VIEWER_ARGS=()
+if [ "$SELECTED_SOURCE" = "--archive" ]; then
+    VIEWER_ARGS=("--archive")
+else
+    VIEWER_ARGS=("$SELECTED_SOURCE")
+fi
+
+if ! docker compose exec daaf-docker bash /daaf/scripts/generate_log_viewer.sh "${VIEWER_ARGS[@]}"; then
+    echo "" >&2
+    echo "ERROR: Failed to generate log viewer." >&2
+    echo "  The container may not be running, or there may be no session logs to display." >&2
+    echo "  Try: docker compose logs daaf-docker" >&2
+fi
+
+# If the server was already running, the command above returns immediately
+# after printing the URL. The EXIT trap keeps the terminal open so the user
+# can read/copy it.
diff --git a/scripts/host/view_notebooks.ps1 b/scripts/host/view_notebooks.ps1
new file mode 100644
index 0000000..4a64c79
--- /dev/null
+++ b/scripts/host/view_notebooks.ps1
@@ -0,0 +1,115 @@
+# ============================================================================
+# DAAF Notebook Browser (Windows PowerShell)
+# ============================================================================
+# Opens marimo's notebook browser in your browser -- browse, open, create, and
+# edit marimo notebooks across all your research projects.
+# Starts the DAAF container if needed.
+#
+# Usage:
+#   cd daaf-docker
+#   .\view_notebooks.ps1
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Port 2718 mapped in docker-compose.yml
+#
+# Supports $env:DAAF_TEST_MODE = "1" for Pester test dot-sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+$ErrorActionPreference = "Stop"
+
+function Wait-AndExit {
+    param([int]$Code = 0)
+    if (-not $env:DAAF_NESTED) {
+        Write-Host ""
+        Read-Host "Press Enter to continue"
+    }
+    exit $Code
+}
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker) for CI
+# cross-platform smoke testing without a Docker daemon.
+if ($env:DAAF_DRY_RUN -eq "1") {
+    function docker {
+        $argStr = $args -join ' '
+        $global:LASTEXITCODE = 0
+        switch -Wildcard ($argStr) {
+            "*info*" { return }
+            "*compose ps*--format*" { Write-Output "daaf-docker" }
+            "*compose up*" { return }
+            "*compose exec*" { return }
+            default {
+                Write-Host "[DRY-RUN] docker $argStr"
+                return
+            }
+        }
+    }
+}
+
+# --- Test Mode Guard ---
+# When dot-sourced for testing, define functions but skip execution.
+# Usage: $env:DAAF_TEST_MODE = "1"; . ./scripts/host/view_notebooks.ps1
+if ($env:DAAF_TEST_MODE -eq "1") {
+    return
+}
+
+# --- Preflight ---
+if (-not (Test-Path "docker-compose.yml")) {
+    Write-Host "ERROR: docker-compose.yml not found in the current directory." -ForegroundColor Red
+    Write-Host "Please run this script from your daaf-docker folder."
+    Wait-AndExit 1
+}
+
+if (-not (Get-Command docker -ErrorAction SilentlyContinue)) {
+    Write-Host "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." -ForegroundColor Red
+    Write-Host "Please install Docker Desktop: https://www.docker.com/products/docker-desktop/"
+    Wait-AndExit 1
+}
+
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$null = docker info 2>&1
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host "ERROR: Docker Desktop is not running. Please start it and try again." -ForegroundColor Red
+    Wait-AndExit 1
+}
+
+# --- Start container if not running ---
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+$RunningOutput = docker compose ps --status running --format '{{.Name}}' 2>&1
+$ErrorActionPreference = $savedEAP
+$Running = ($RunningOutput | Select-String "daaf-docker").Count
+
+if ($Running -eq 0) {
+    Write-Host "Starting DAAF container..."
+    $savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+    docker compose up -d
+    $ErrorActionPreference = $savedEAP
+    if ($LASTEXITCODE -ne 0) {
+        Write-Host "ERROR: Failed to start the container." -ForegroundColor Red
+        Wait-AndExit 1
+    }
+    Write-Host "Container started."
+} else {
+    Write-Host "DAAF container is running."
+}
+
+Write-Host ""
+Write-Host "Opening DAAF Notebook Browser..."
+Write-Host ""
+$savedEAP = $ErrorActionPreference; $ErrorActionPreference = "SilentlyContinue"
+docker compose exec daaf-docker bash /daaf/scripts/launch_marimo.sh
+$ErrorActionPreference = $savedEAP
+if ($LASTEXITCODE -ne 0) {
+    Write-Host ""
+    Write-Host "ERROR: Failed to start the notebook browser." -ForegroundColor Red
+    Write-Host "  The container may not be running, or marimo may not be installed." -ForegroundColor Red
+    Write-Host "  Try: docker compose logs daaf-docker" -ForegroundColor Yellow
+}
+
+# If marimo was already running, the container-side script returns immediately
+# after printing the URL. Wait-AndExit keeps the window open so the user
+# can read/copy it.
+Wait-AndExit 0
diff --git a/scripts/host/view_notebooks.sh b/scripts/host/view_notebooks.sh
new file mode 100755
index 0000000..07fe7cd
--- /dev/null
+++ b/scripts/host/view_notebooks.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Notebook Browser (macOS / Linux)
+# ============================================================================
+# Opens marimo's notebook browser in your browser -- browse, open, create, and
+# edit marimo notebooks across all your research projects.
+# Starts the DAAF container if needed.
+#
+# Usage:
+#   cd daaf-docker
+#   bash view_notebooks.sh
+#
+# Prerequisites:
+#   - Docker Desktop installed and running
+#   - Port 2718 mapped in docker-compose.yml
+#
+# Supports DAAF_TEST_MODE=1 for test framework sourcing (see tests/).
+# Supports DAAF_DRY_RUN=1 for CI cross-platform smoke testing (see tests/).
+# ============================================================================
+
+set -euo pipefail
+
+# Pause before exit so the user can review output.
+# Suppressed by DAAF_NESTED (to avoid double-pause when called from
+# another script).
+if [ -z "${DAAF_NESTED:-}" ] && [ -z "${CI:-}" ] && [ -c /dev/tty ] && [ -t 1 ]; then
+    trap 'echo ""; read -r -p "Press Enter to continue: " < /dev/tty' EXIT
+fi
+
+# --- Dry-Run Support ---
+# When DAAF_DRY_RUN=1, simulate external commands (Docker, curl) for CI
+# cross-platform smoke testing without a Docker daemon.
+if [ "${DAAF_DRY_RUN:-}" = "1" ]; then
+    docker() {
+        case "$*" in
+            "info") return 0 ;;
+            *"compose ps --status running"*"--format"*) echo "daaf-docker" ;;
+            *"compose exec"*) return 0 ;;
+            *)
+                echo "[DRY-RUN] docker $*" >&2
+                return 0
+                ;;
+        esac
+    }
+fi
+
+# --- Test Mode Guard ---
+# When sourced for testing, define functions but skip execution.
+# Usage: DAAF_TEST_MODE=1 source scripts/host/view_notebooks.sh
+if [ "${DAAF_TEST_MODE:-}" = "1" ]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# --- Preflight ---
+if [ ! -f "docker-compose.yml" ]; then
+    echo "ERROR: docker-compose.yml not found in the current directory." >&2
+    echo "  Please run this script from your daaf-docker folder." >&2
+    exit 1
+fi
+
+if ! command -v docker &> /dev/null; then
+    echo "ERROR: Docker is either not installed or not configured properly in your system PATH to allow it to be used from Terminal." >&2
+    echo "  Please install Docker Desktop: https://www.docker.com/products/docker-desktop/" >&2
+    exit 1
+fi
+
+if ! docker info &> /dev/null; then
+    echo "ERROR: Docker Desktop is not running. Please start it and try again." >&2
+    exit 1
+fi
+
+# --- Start container if not running ---
+RUNNING=$(docker compose ps --status running --format '{{.Name}}' 2>/dev/null | grep -c "daaf-docker" || true)
+
+if [ "${RUNNING}" -eq 0 ]; then
+    echo "Starting DAAF container..."
+    if ! docker compose up -d; then
+        echo "ERROR: Failed to start the container." >&2
+        exit 1
+    fi
+    echo "Container started."
+else
+    echo "DAAF container is running."
+fi
+
+echo ""
+echo "Opening DAAF Notebook Browser..."
+echo ""
+if ! docker compose exec daaf-docker bash /daaf/scripts/launch_marimo.sh; then
+    echo "" >&2
+    echo "ERROR: Failed to start the notebook browser." >&2
+    echo "  The container may not be running, or marimo may not be installed." >&2
+    echo "  Try: docker compose logs daaf-docker" >&2
+fi
+
+# If marimo was already running, the container-side script returns immediately
+# after printing the URL. The EXIT trap keeps the terminal open so the user
+# can read/copy it.
diff --git a/scripts/launch_code_server.sh b/scripts/launch_code_server.sh
new file mode 100755
index 0000000..08b66fa
--- /dev/null
+++ b/scripts/launch_code_server.sh
@@ -0,0 +1,168 @@
+#!/usr/bin/env bash
+# launch_code_server.sh — Launch code-server (VS Code in the browser) for DAAF
+#
+# Opens a browser-accessible VS Code instance for browsing, editing, and
+# reviewing files in the DAAF container.
+#
+# Usage:
+#   bash /daaf/scripts/launch_code_server.sh [directory] [--port PORT]
+#
+# Examples:
+#   bash /daaf/scripts/launch_code_server.sh
+#   bash /daaf/scripts/launch_code_server.sh /daaf/research/2026-04-15_My_Analysis
+#   bash /daaf/scripts/launch_code_server.sh --port 2721
+#
+# Default behavior:
+#   - Opens /daaf (the DAAF project root)
+#   - Serves on port 2720 (mapped in docker-compose.yml)
+#   - Binds to 0.0.0.0 for Docker container access
+#   - Password authentication enabled (password displayed on launch)
+#
+# Exit codes:
+#   0 — success (or server stopped by Ctrl+C)
+#   1 — usage error, invalid directory, or port conflict
+
+set -euo pipefail
+
+# --- Defaults ---
+
+PORT=2720
+OPEN_DIR="/daaf"
+PASSWORD="${PASSWORD:-daaf}"
+
+# --- Parse arguments ---
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --port)
+            if [ $# -lt 2 ]; then
+                echo "ERROR: --port requires a value." >&2
+                echo "  Usage: bash $0 [directory] [--port PORT]" >&2
+                exit 1
+            fi
+            PORT="$2"
+            shift 2
+            ;;
+        --password)
+            if [ $# -lt 2 ]; then
+                echo "ERROR: --password requires a value." >&2
+                exit 1
+            fi
+            PASSWORD="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: bash $0 [directory] [--port PORT] [--password PASSWORD]"
+            echo ""
+            echo "Launch code-server (VS Code in the browser) for DAAF."
+            echo ""
+            echo "Arguments:"
+            echo "  directory         Directory to open (default: /daaf)"
+            echo "  --port PORT       Port for the server (default: 2720)"
+            echo "  --password PASS   Set login password (default: \$PASSWORD or 'daaf')"
+            echo ""
+            echo "Examples:"
+            echo "  bash $0                                          # Open DAAF root"
+            echo "  bash $0 /daaf/research/2026-04-15_Analysis       # Specific project"
+            echo ""
+            echo "Open http://localhost:PORT in your browser after launching."
+            exit 0
+            ;;
+        *)
+            if [ "$OPEN_DIR" = "/daaf" ]; then
+                OPEN_DIR="$1"
+            else
+                echo "ERROR: Unexpected argument: $1" >&2
+                echo "  Usage: bash $0 [directory] [--port PORT]" >&2
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+# --- Validate directory ---
+
+if [ ! -d "$OPEN_DIR" ]; then
+    echo "ERROR: Directory does not exist: $OPEN_DIR" >&2
+    exit 1
+fi
+
+# --- Validate port ---
+
+if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1 ] || [ "$PORT" -gt 65535 ]; then
+    echo "ERROR: --port must be a number between 1 and 65535 (got: $PORT)" >&2
+    exit 1
+fi
+
+# --- Preflight ---
+
+if ! command -v code-server >/dev/null 2>&1; then
+    echo "ERROR: code-server is not installed." >&2
+    echo "  This should be pre-installed in the DAAF Docker image." >&2
+    echo "  If you rebuilt the image without code-server, re-run:" >&2
+    echo "    bash rebuild_daaf.sh" >&2
+    exit 1
+fi
+
+# --- Check for port conflict ---
+
+PORT_HEX=$(printf '%04X' "$PORT")
+LISTEN_INODE=$(awk -v ph="$PORT_HEX" '$2 ~ ":"ph"$" && $4 == "0A" {print $10}' /proc/net/tcp /proc/net/tcp6 2>/dev/null | head -1)
+
+if [ -n "$LISTEN_INODE" ]; then
+    LISTEN_PID=$(find /proc -maxdepth 3 -path '*/fd/*' -exec ls -la {} + 2>/dev/null \
+        | grep "socket:\[$LISTEN_INODE\]" | head -1 \
+        | sed 's|.*/proc/\([0-9]*\)/.*|\1|' || true)
+
+    if ! [[ "$LISTEN_PID" =~ ^[0-9]+$ ]]; then
+        LISTEN_PID=""
+    fi
+
+    LISTEN_CMD=""
+    [ -n "$LISTEN_PID" ] && LISTEN_CMD=$(ps -p "$LISTEN_PID" -o args= 2>/dev/null || true)
+
+    if echo "$LISTEN_CMD" | grep -q "code-server"; then
+        echo "code-server is already running on port $PORT (PID $LISTEN_PID)."
+        echo ""
+        echo "  Open in your browser:"
+        echo "  http://localhost:$PORT"
+        echo ""
+        exit 0
+    elif [ -n "$LISTEN_PID" ]; then
+        echo "ERROR: Port $PORT is in use by another process: $LISTEN_CMD (PID $LISTEN_PID)" >&2
+        echo "  Free the port or use --port to specify a different one." >&2
+        exit 1
+    else
+        echo "ERROR: Port $PORT is in use but the owning process could not be identified." >&2
+        echo "  Free the port or use --port to specify a different one." >&2
+        exit 1
+    fi
+fi
+
+# --- Launch code-server ---
+
+echo "Starting code-server (VS Code in the browser)..."
+echo "  Opening:  $OPEN_DIR"
+echo "  Port:     $PORT"
+echo ""
+echo "  ┌────────────────────────────────────────────────┐"
+printf "  │  %-46s │\n" "Open in your browser:"
+printf "  │  %-46s │\n" "http://localhost:$PORT"
+printf "  │  %-46s │\n" ""
+printf "  │  %-46s │\n" "Password: $PASSWORD"
+echo "  └────────────────────────────────────────────────┘"
+echo ""
+echo "  Press Ctrl+C to stop the server."
+echo ""
+
+export PASSWORD
+exec code-server \
+    --bind-addr "0.0.0.0:$PORT" \
+    --user-data-dir /home/appuser/.local/share/code-server \
+    --extensions-dir /home/appuser/.local/share/code-server/extensions \
+    --disable-telemetry \
+    --disable-update-check \
+    --disable-getting-started-override \
+    --auth password \
+    "$OPEN_DIR"
diff --git a/scripts/launch_marimo.sh b/scripts/launch_marimo.sh
new file mode 100755
index 0000000..3496989
--- /dev/null
+++ b/scripts/launch_marimo.sh
@@ -0,0 +1,157 @@
+#!/usr/bin/env bash
+# launch_marimo.sh — Launch marimo's notebook browser for DAAF projects
+#
+# Opens marimo's built-in home page, which provides a web-based file explorer
+# for browsing, opening, creating, and editing marimo notebooks.
+#
+# Usage:
+#   bash /daaf/scripts/launch_marimo.sh [directory] [--port PORT]
+#
+# Examples:
+#   bash /daaf/scripts/launch_marimo.sh
+#   bash /daaf/scripts/launch_marimo.sh /daaf/research/2026-04-15_My_Analysis
+#   bash /daaf/scripts/launch_marimo.sh --port 2720
+#
+# Default behavior:
+#   - Browses /daaf/research/ (where all project notebooks live)
+#   - Serves on port 2718 (mapped in docker-compose.yml)
+#   - Binds to 0.0.0.0 for Docker container access
+#   - Runs without authentication token (local development only)
+#
+# Exit codes:
+#   0 — success (or server stopped by Ctrl+C)
+#   1 — usage error, invalid directory, or port conflict
+
+set -euo pipefail
+
+# --- Resolve paths ---
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+# --- Defaults ---
+
+readonly DEFAULT_DIR="$REPO_ROOT/research"
+PORT=2718
+BROWSE_DIR=""
+
+# --- Parse arguments ---
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --port)
+            if [ $# -lt 2 ]; then
+                echo "ERROR: --port requires a value." >&2
+                echo "  Usage: bash $0 [directory] [--port PORT]" >&2
+                exit 1
+            fi
+            PORT="$2"
+            shift 2
+            ;;
+        -h|--help)
+            echo "Usage: bash $0 [directory] [--port PORT]"
+            echo ""
+            echo "Launch marimo's notebook browser for DAAF projects."
+            echo ""
+            echo "Arguments:"
+            echo "  directory     Directory to browse (default: /daaf/research)"
+            echo "  --port PORT   Port for the marimo server (default: 2718)"
+            echo ""
+            echo "Examples:"
+            echo "  bash $0                                # Browse all projects"
+            echo "  bash $0 /daaf/research/2026-04-15_Analysis  # Specific project"
+            echo ""
+            echo "Open http://localhost:PORT in your browser after launching."
+            exit 0
+            ;;
+        *)
+            if [ -z "$BROWSE_DIR" ]; then
+                BROWSE_DIR="$1"
+            else
+                echo "ERROR: Unexpected argument: $1" >&2
+                echo "  Usage: bash $0 [directory] [--port PORT]" >&2
+                exit 1
+            fi
+            shift
+            ;;
+    esac
+done
+
+# --- Resolve browse directory ---
+
+if [ -z "$BROWSE_DIR" ]; then
+    BROWSE_DIR="$DEFAULT_DIR"
+fi
+
+if [ ! -d "$BROWSE_DIR" ]; then
+    echo "ERROR: Directory does not exist: $BROWSE_DIR" >&2
+    echo "  Create a research project first, or specify a different directory." >&2
+    exit 1
+fi
+
+# --- Validate port ---
+
+if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1 ] || [ "$PORT" -gt 65535 ]; then
+    echo "ERROR: --port must be a number between 1 and 65535 (got: $PORT)" >&2
+    exit 1
+fi
+
+# --- Preflight ---
+
+if ! command -v marimo >/dev/null 2>&1; then
+    echo "ERROR: marimo is not installed." >&2
+    echo "  Install with: pip install marimo" >&2
+    exit 30
+fi
+
+# --- Check for port conflict ---
+
+PORT_HEX=$(printf '%04X' "$PORT")
+LISTEN_INODE=$(awk -v ph="$PORT_HEX" '$2 ~ ":"ph"$" && $4 == "0A" {print $10}' /proc/net/tcp /proc/net/tcp6 2>/dev/null | head -1)
+
+if [ -n "$LISTEN_INODE" ]; then
+    LISTEN_PID=$(find /proc -maxdepth 3 -path '*/fd/*' -exec ls -la {} + 2>/dev/null \
+        | grep "socket:\[$LISTEN_INODE\]" | head -1 \
+        | sed 's|.*/proc/\([0-9]*\)/.*|\1|' || true)
+
+    if ! [[ "$LISTEN_PID" =~ ^[0-9]+$ ]]; then
+        LISTEN_PID=""
+    fi
+
+    LISTEN_CMD=""
+    [ -n "$LISTEN_PID" ] && LISTEN_CMD=$(ps -p "$LISTEN_PID" -o args= 2>/dev/null || true)
+
+    if echo "$LISTEN_CMD" | grep -q "marimo"; then
+        echo "Marimo is already running on port $PORT (PID $LISTEN_PID)."
+        echo ""
+        echo "  Open in your browser:"
+        echo "  http://localhost:$PORT"
+        echo ""
+        exit 0
+    elif [ -n "$LISTEN_PID" ]; then
+        echo "ERROR: Port $PORT is in use by another process: $LISTEN_CMD (PID $LISTEN_PID)" >&2
+        echo "  Free the port or use --port to specify a different one." >&2
+        exit 1
+    else
+        echo "ERROR: Port $PORT is in use but the owning process could not be identified." >&2
+        echo "  Free the port or use --port to specify a different one." >&2
+        exit 1
+    fi
+fi
+
+# --- Launch marimo ---
+
+echo "Starting marimo notebook browser..."
+echo "  Browsing: $BROWSE_DIR"
+echo "  Port:     $PORT"
+echo ""
+echo "  Open in your browser:"
+echo "  http://localhost:$PORT"
+echo ""
+echo "  (Marimo will print its own URL below using 0.0.0.0 — ignore that,"
+echo "   use the localhost link above from your host browser.)"
+echo ""
+echo "  Press Ctrl+C to stop the server."
+echo ""
+
+exec marimo edit "$BROWSE_DIR" --host 0.0.0.0 --port "$PORT" --no-token --headless --skip-update-check
diff --git a/scripts/log_viewer.html b/scripts/log_viewer.html
new file mode 100644
index 0000000..b496231
--- /dev/null
+++ b/scripts/log_viewer.html
@@ -0,0 +1,1978 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DAAF Log Explorer</title>
+<style>
+/* --- Reset & Base --- */
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+html { font-size: 14px; }
+body {
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+  background: #f8f9fa;
+  color: #1a1a2e;
+  height: 100vh;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+}
+
+/* --- Header --- */
+.header {
+  background: #1a1a2e;
+  color: #fff;
+  padding: 8px 20px;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+.header h1 { font-size: 1.15rem; font-weight: 600; letter-spacing: 0.02em; white-space: nowrap; }
+.header .project-name {
+  font-size: 0.82rem;
+  color: #94a3b8;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+  min-width: 0;
+}
+.header .session-select {
+  background: #2d2d4e;
+  color: #e2e8f0;
+  border: 1px solid #475569;
+  border-radius: 4px;
+  padding: 4px 8px;
+  font-size: 0.8rem;
+  cursor: pointer;
+  flex-shrink: 0;
+  max-width: 360px;
+}
+.header .session-select:hover { border-color: #3b82f6; }
+
+/* --- Refresh Controls --- */
+.header .refresh-controls {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  flex-shrink: 0;
+}
+.header .refresh-btn {
+  background: #2d2d4e;
+  color: #e2e8f0;
+  border: 1px solid #475569;
+  border-radius: 4px;
+  padding: 4px 10px;
+  font-size: 0.8rem;
+  cursor: pointer;
+  white-space: nowrap;
+  transition: border-color 0.15s, opacity 0.15s;
+}
+.header .refresh-btn:hover { border-color: #3b82f6; }
+@keyframes refresh-pulse {
+  0%, 100% { opacity: 0.6; }
+  50% { opacity: 1; }
+}
+.header .refresh-btn.refreshing {
+  cursor: wait;
+  animation: refresh-pulse 1.2s ease-in-out infinite;
+}
+.header .auto-refresh-group {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+  font-size: 0.72rem;
+  color: #94a3b8;
+}
+.header .auto-refresh-group label {
+  cursor: pointer;
+  user-select: none;
+}
+.header .auto-refresh-group select {
+  background: #2d2d4e;
+  color: #e2e8f0;
+  border: 1px solid #475569;
+  border-radius: 3px;
+  padding: 2px 4px;
+  font-size: 0.72rem;
+  cursor: pointer;
+}
+.header .auto-refresh-group select:hover { border-color: #3b82f6; }
+.header .last-refreshed {
+  font-size: 0.68rem;
+  color: #64748b;
+  white-space: nowrap;
+}
+
+/* (session tabs replaced by header dropdown) */
+
+/* --- Stats Bar --- */
+.stats-bar {
+  display: flex;
+  gap: 24px;
+  padding: 8px 20px;
+  background: #fff;
+  border-bottom: 1px solid #e2e8f0;
+  font-size: 0.8rem;
+  color: #64748b;
+  flex-shrink: 0;
+  flex-wrap: wrap;
+}
+.stats-bar .stat-label { color: #94a3b8; margin-right: 4px; }
+.stats-bar .stat-value { font-weight: 600; color: #334155; }
+
+/* --- Main Content Area --- */
+.main-content {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  min-height: 0;
+}
+
+/* --- Timeline Panel (top) --- */
+.timeline-panel {
+  flex: 3;
+  overflow-y: auto;
+  overflow-x: hidden;
+  padding: 16px 20px;
+  min-height: 40px;
+}
+.section-label {
+  font-size: 0.7rem;
+  font-weight: 700;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+  color: #94a3b8;
+  margin-bottom: 8px;
+}
+
+/* --- Unified Timeline --- */
+/* --- Scroll Proxy (top scrollbar for timeline) --- */
+.scroll-proxy {
+  overflow-x: auto;
+  overflow-y: hidden;
+  height: 12px;
+  min-height: 12px;
+  flex-shrink: 0;
+}
+.scroll-proxy-inner {
+  height: 1px;
+}
+.timeline-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 2px;
+  overflow-x: auto;
+  padding-bottom: 4px;
+  min-height: 48px;
+  scrollbar-width: none;           /* Firefox: hide bottom scrollbar */
+}
+.timeline-row::-webkit-scrollbar {
+  display: none;                   /* Chrome/Safari/Edge: hide bottom scrollbar */
+}
+.timeline-column {
+  flex-shrink: 0;
+  min-width: 28px;
+  display: flex;
+  flex-direction: column;
+}
+.timeline-block {
+  height: 36px;
+  border-radius: 4px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: #fff;
+  position: relative;
+  transition: transform 0.1s, box-shadow 0.1s;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  padding: 0 6px;
+}
+.timeline-block:hover {
+  transform: scaleY(1.08);
+  box-shadow: 0 2px 8px rgba(0,0,0,0.18);
+  z-index: 2;
+}
+.timeline-block.selected {
+  outline: 2px solid #1a1a2e;
+  outline-offset: 1px;
+  box-shadow: 0 0 0 4px rgba(59,130,246,0.25);
+  transform: scaleY(1.08);
+  z-index: 3;
+}
+.timeline-block.type-user { background: #3b82f6; }
+.timeline-block.type-assistant { background: #10b981; }
+.timeline-block.type-system { background: #6b7280; }
+
+/* --- Tooltip --- */
+.timeline-block .block-tooltip {
+  display: none;
+  position: absolute;
+  bottom: calc(100% + 6px);
+  left: 50%;
+  transform: translateX(-50%);
+  background: #1e293b;
+  color: #f1f5f9;
+  padding: 6px 10px;
+  border-radius: 4px;
+  font-size: 0.72rem;
+  font-weight: 400;
+  white-space: nowrap;
+  max-width: 350px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  pointer-events: none;
+  z-index: 100;
+  box-shadow: 0 4px 12px rgba(0,0,0,0.2);
+}
+.timeline-block .block-tooltip::after {
+  content: '';
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 5px solid transparent;
+  border-top-color: #1e293b;
+}
+.timeline-block:hover .block-tooltip { display: block; }
+
+/* --- Subagent Area (nested below orchestrator block) --- */
+.subagent-area {
+  background: rgba(0, 0, 0, 0.03);
+  border-radius: 0 0 4px 4px;
+  padding: 4px 2px 2px 2px;
+  margin-top: 1px;
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+.subagent-bar {
+  height: 24px;
+  border-radius: 3px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  padding: 0 6px;
+  font-size: 0.65rem;
+  font-weight: 600;
+  color: #fff;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  transition: transform 0.1s, box-shadow 0.1s;
+  border: 1px solid rgba(255,255,255,0.2);
+  min-width: 20px;
+}
+.subagent-bar:hover {
+  transform: scaleY(1.1);
+  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  z-index: 2;
+}
+.subagent-bar.selected {
+  outline: 2px solid #1a1a2e;
+  outline-offset: 1px;
+  box-shadow: 0 0 0 4px rgba(59,130,246,0.25);
+  z-index: 3;
+}
+/* Agent type colors */
+.subagent-bar.agent-search-agent { background: #f59e0b; }
+.subagent-bar.agent-source-researcher { background: #8b5cf6; }
+.subagent-bar.agent-research-executor { background: #ef4444; }
+.subagent-bar.agent-code-reviewer { background: #06b6d4; }
+.subagent-bar.agent-data-planner { background: #ec4899; }
+.subagent-bar.agent-research-synthesizer { background: #f97316; }
+.subagent-bar.agent-plan-checker { background: #84cc16; }
+.subagent-bar.agent-report-writer { background: #a855f7; }
+.subagent-bar.agent-data-verifier { background: #0ea5e9; }
+.subagent-bar.agent-notebook-assembler { background: #64748b; }
+.subagent-bar.agent-debugger { background: #dc2626; }
+.subagent-bar.agent-integration-checker { background: #059669; }
+.subagent-bar.agent-data-ingest { background: #d946ef; }
+.subagent-bar.agent-framework-engineer { background: #7c3aed; }
+.subagent-bar.agent-default { background: #6b7280; }
+
+/* --- Unlinked Subagents (fallback section) --- */
+.unlinked-section { margin-top: 12px; }
+.unlinked-lane {
+  position: relative;
+  height: 28px;
+  margin-bottom: 3px;
+}
+.unlinked-bar {
+  height: 24px;
+  border-radius: 3px;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  padding: 0 8px;
+  font-size: 0.65rem;
+  font-weight: 600;
+  color: #fff;
+  margin-right: 4px;
+  border: 1px solid rgba(255,255,255,0.2);
+}
+
+/* --- Resize Handle (horizontal, between timeline and bottom) --- */
+.resize-handle {
+  height: 5px;
+  background: #e2e8f0;
+  cursor: row-resize;
+  flex-shrink: 0;
+  position: relative;
+  transition: background 0.15s;
+}
+.resize-handle:hover, .resize-handle.dragging { background: #3b82f6; }
+.resize-handle::after {
+  content: '';
+  position: absolute;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  width: 40px;
+  height: 3px;
+  border-top: 1px solid #94a3b8;
+  border-bottom: 1px solid #94a3b8;
+}
+
+/* --- Bottom Panels (detail + file preview) --- */
+.bottom-panels {
+  flex: 7;
+  display: flex;
+  flex-direction: row;
+  min-height: 0;
+  border-top: 1px solid #e2e8f0;
+  box-shadow: 0 -2px 8px rgba(0,0,0,0.04);
+}
+
+/* --- Detail Panel (bottom-left) --- */
+.detail-panel {
+  flex: 1;
+  background: #fff;
+  overflow-y: auto;
+  padding: 16px 20px;
+  min-width: 0;
+  min-height: 0;
+}
+.detail-empty {
+  color: #94a3b8;
+  font-size: 0.9rem;
+  text-align: center;
+  margin-top: 40px;
+}
+.detail-header {
+  display: flex;
+  align-items: baseline;
+  gap: 12px;
+  margin-bottom: 10px;
+  flex-wrap: wrap;
+}
+.detail-title { font-size: 1rem; font-weight: 700; color: #1a1a2e; }
+.detail-badge {
+  display: inline-block;
+  padding: 2px 8px;
+  border-radius: 3px;
+  font-size: 0.7rem;
+  font-weight: 600;
+  color: #fff;
+}
+.detail-badge.type-user { background: #3b82f6; }
+.detail-badge.type-assistant { background: #10b981; }
+.detail-badge.type-system { background: #6b7280; }
+.detail-meta {
+  font-size: 0.78rem;
+  color: #64748b;
+  margin-bottom: 12px;
+  line-height: 1.6;
+}
+.detail-section-title {
+  font-size: 0.75rem;
+  font-weight: 700;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+  color: #94a3b8;
+  margin: 14px 0 6px 0;
+  padding-top: 10px;
+  border-top: 1px solid #f1f5f9;
+}
+
+/* --- Vertical Resize (between detail and preview) --- */
+.vertical-resize {
+  width: 5px;
+  background: #e2e8f0;
+  cursor: col-resize;
+  flex-shrink: 0;
+  position: relative;
+  transition: background 0.15s;
+}
+.vertical-resize:hover, .vertical-resize.dragging { background: #3b82f6; }
+.vertical-resize::after {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  height: 40px;
+  width: 3px;
+  border-left: 1px solid #94a3b8;
+  border-right: 1px solid #94a3b8;
+}
+
+/* --- File Preview Panel (bottom-right) --- */
+.file-preview {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  min-width: 0;
+  min-height: 0;
+  background: #fff;
+  border-left: 1px solid #e2e8f0;
+}
+.preview-empty {
+  color: #94a3b8;
+  font-size: 0.85rem;
+  text-align: center;
+  padding: 40px 20px;
+}
+.preview-notice {
+  background: #fffbeb;
+  border-bottom: 1px solid #fde68a;
+  padding: 5px 12px;
+  font-size: 0.72rem;
+  color: #92400e;
+  flex-shrink: 0;
+  line-height: 1.4;
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+.preview-notice-text { flex: 1; }
+.preview-notice-dismiss {
+  background: none;
+  border: none;
+  color: #b45309;
+  cursor: pointer;
+  font-size: 0.85rem;
+  padding: 0 2px;
+  line-height: 1;
+  flex-shrink: 0;
+  opacity: 0.6;
+}
+.preview-notice-dismiss:hover { opacity: 1; }
+.preview-header {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 6px 12px;
+  background: #f1f5f9;
+  border-bottom: 1px solid #e2e8f0;
+  flex-shrink: 0;
+}
+.preview-path {
+  flex: 1;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  font-size: 0.75rem;
+  color: #334155;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+.preview-open-tab {
+  font-size: 0.7rem;
+  color: #3b82f6;
+  text-decoration: none;
+  white-space: nowrap;
+}
+.preview-open-tab:hover { text-decoration: underline; }
+.preview-close {
+  background: none;
+  border: none;
+  color: #94a3b8;
+  cursor: pointer;
+  font-size: 1.1rem;
+  padding: 0 4px;
+  line-height: 1;
+}
+.preview-close:hover { color: #1a1a2e; }
+.preview-content {
+  flex: 1;
+  overflow: auto;
+}
+.file-content {
+  margin: 0;
+  padding: 8px 0;
+  font-size: 0.75rem;
+  line-height: 1.6;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  white-space: pre;
+  tab-size: 4;
+}
+.file-content .ln {
+  display: inline-block;
+  width: 5em;
+  text-align: right;
+  color: #94a3b8;
+  padding-right: 1em;
+  user-select: none;
+}
+
+/* --- Activity List --- */
+.activity-list { list-style: none; }
+.activity-item {
+  display: flex;
+  align-items: flex-start;
+  gap: 8px;
+  padding: 4px 0;
+  font-size: 0.8rem;
+  line-height: 1.4;
+}
+.activity-dot {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  flex-shrink: 0;
+  margin-top: 4px;
+}
+.activity-dot.type-read { background: #3b82f6; }
+.activity-dot.type-write { background: #f97316; }
+.activity-dot.type-execute { background: #ef4444; }
+.activity-dot.type-delegate { background: #8b5cf6; }
+.activity-dot.type-skill { background: #10b981; }
+.activity-dot.type-search { background: #14b8a6; }
+.activity-dot.type-track { background: #9ca3af; }
+.activity-dot.type-other { background: #d1d5db; }
+.activity-dot.type-text { background: transparent; }
+.activity-dot.type-thinking { background: #a78bfa; }
+
+.activity-desc { color: #334155; flex: 1; min-width: 0; }
+.activity-text-block {
+  word-break: break-word;
+  color: #475569;
+  line-height: 1.5;
+  font-size: 0.8rem;
+  padding: 4px 0;
+  max-height: 300px;
+  overflow-y: auto;
+}
+.activity-thinking-block {
+  word-break: break-word;
+  color: #6b21a8;
+  line-height: 1.5;
+  font-size: 0.78rem;
+  padding: 6px 10px;
+  max-height: 200px;
+  overflow-y: auto;
+  background: #faf5ff;
+  border-radius: 4px;
+  border: 1px solid #e9d5ff;
+}
+.activity-thinking-block.collapsed {
+  max-height: 3.6em;
+  overflow: hidden;
+  position: relative;
+}
+.activity-thinking-block.collapsed::after {
+  content: '';
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  right: 0;
+  height: 1.8em;
+  background: linear-gradient(transparent, #faf5ff);
+  pointer-events: none;
+}
+.thinking-toggle {
+  font-size: 0.7rem;
+  color: #7c3aed;
+  cursor: pointer;
+  font-weight: 600;
+  padding: 2px 0;
+  user-select: none;
+}
+.thinking-toggle:hover { text-decoration: underline; }
+.activity-target {
+  color: #3b82f6;
+  text-decoration: none;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  font-size: 0.75rem;
+  cursor: pointer;
+}
+.activity-target:hover { text-decoration: underline; }
+.activity-extra-targets {
+  display: inline;
+  font-size: 0.72rem;
+}
+.activity-line-ref {
+  color: #94a3b8;
+  font-size: 0.7rem;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  flex-shrink: 0;
+  cursor: pointer;
+}
+.activity-line-ref:hover { color: #3b82f6; }
+.activity-error-badge {
+  display: inline-block;
+  background: #fef2f2;
+  color: #dc2626;
+  font-size: 0.65rem;
+  font-weight: 600;
+  padding: 1px 5px;
+  border-radius: 3px;
+  border: 1px solid #fecaca;
+  margin-left: 6px;
+  vertical-align: middle;
+}
+.delegate-arrow {
+  display: inline-block;
+  width: 0; height: 0;
+  border-top: 4px solid transparent;
+  border-bottom: 4px solid transparent;
+  border-left: 6px solid #8b5cf6;
+  margin-right: 2px;
+}
+.view-full-link {
+  font-size: 0.72rem;
+  color: #3b82f6;
+  cursor: pointer;
+  text-decoration: none;
+  font-weight: 500;
+}
+.view-full-link:hover { text-decoration: underline; }
+
+/* --- Subagent Preview Boxes (scrollable, full content) --- */
+.subagent-preview {
+  background: #f8fafc;
+  border: 1px solid #e2e8f0;
+  border-radius: 4px;
+  padding: 10px 12px;
+  font-size: 0.78rem;
+  color: #475569;
+  line-height: 1.5;
+  margin: 6px 0;
+  max-height: 400px;
+  overflow-y: auto;
+  word-break: break-word;
+}
+
+/* --- Activity Groups (visual delineation) --- */
+.activity-group {
+  margin: 6px 0;
+  border-radius: 5px;
+  padding: 6px 10px;
+}
+.activity-group.group-text {
+  background: #f8fafc;
+  border-left: 3px solid #94a3b8;
+}
+.activity-group.group-thinking {
+  background: #faf5ff;
+  border-left: 3px solid #a78bfa;
+}
+.activity-group.group-thinking .activity-group-label {
+  color: #7c3aed;
+}
+.activity-group.group-tools {
+  background: #fafbff;
+  border: 1px solid #e8ecf2;
+}
+.activity-group .activity-list { margin: 0; }
+.activity-group-label {
+  font-size: 0.65rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: #94a3b8;
+  margin-bottom: 4px;
+}
+
+/* --- Timestamp --- */
+.detail-timestamp {
+  font-size: 0.72rem;
+  color: #94a3b8;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+}
+
+/* --- Scrollable Content Box (for summaries, search results) --- */
+.content-box {
+  background: #f8fafc;
+  border: 1px solid #e2e8f0;
+  border-radius: 4px;
+  padding: 10px 12px;
+  font-size: 0.82rem;
+  color: #334155;
+  line-height: 1.5;
+  margin: 6px 0;
+  max-height: 300px;
+  overflow-y: auto;
+  word-break: break-word;
+}
+.content-box.search-results {
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  font-size: 0.75rem;
+  color: #475569;
+  max-height: 200px;
+}
+
+/* (legend removed) */
+
+/* --- Error / Loading States --- */
+.state-message {
+  text-align: center;
+  padding: 60px 20px;
+  color: #64748b;
+}
+.state-message h2 { font-size: 1.1rem; color: #334155; margin-bottom: 8px; }
+.state-message p {
+  font-size: 0.85rem;
+  line-height: 1.6;
+  max-width: 500px;
+  margin: 0 auto;
+}
+.state-message code {
+  background: #f1f5f9;
+  padding: 2px 6px;
+  border-radius: 3px;
+  font-size: 0.8rem;
+}
+
+/* --- Scrollbar --- */
+::-webkit-scrollbar { width: 6px; height: 6px; }
+::-webkit-scrollbar-track { background: transparent; }
+::-webkit-scrollbar-thumb { background: #cbd5e1; border-radius: 3px; }
+::-webkit-scrollbar-thumb:hover { background: #94a3b8; }
+</style>
+</head>
+<body>
+
+<div class="header">
+  <h1>DAAF Log Explorer</h1>
+  <div class="project-name" id="projectName">Loading...</div>
+  <select class="session-select" id="sessionSelect" style="display:none"></select>
+  <div class="refresh-controls">
+    <button class="refresh-btn" id="refreshBtn" title="Refresh session manifest">Refresh</button>
+    <div class="auto-refresh-group">
+      <label for="autoRefreshToggle"><input type="checkbox" id="autoRefreshToggle"> Auto</label>
+      <select id="autoRefreshInterval">
+        <option value="60">1m</option>
+        <option value="300" selected>5m</option>
+        <option value="600">10m</option>
+        <option value="1800">30m</option>
+      </select>
+      <span class="last-refreshed" id="lastRefreshed"></span>
+    </div>
+  </div>
+</div>
+
+<div class="stats-bar" id="statsBar"></div>
+
+<div class="main-content">
+  <div class="timeline-panel" id="timelinePanel">
+    <div class="state-message" id="loadingMsg">
+      <h2>Loading session data...</h2>
+      <p>Fetching <code>session_manifest.json</code></p>
+    </div>
+  </div>
+  <div class="resize-handle" id="resizeHandle"></div>
+  <div class="bottom-panels" id="bottomPanels">
+    <div class="detail-panel" id="detailPanel">
+      <div class="detail-empty">Click a block in the timeline to view details.</div>
+    </div>
+    <div class="vertical-resize" id="verticalResize"></div>
+    <div class="file-preview" id="filePreview">
+      <div class="preview-empty">Click a file reference to preview it here.</div>
+    </div>
+  </div>
+</div>
+
+
+<script>
+// =====================================================================
+// State
+// =====================================================================
+var manifest = null;
+var activeSessionIdx = 0;
+var selectedBlockId = null;
+var selectedSubagentId = null;
+var jsonlCache = {};
+var fileCache = {};
+var mergedBlockLookup = {};
+var previewNoticeDismissed = false;
+
+// =====================================================================
+// Helpers
+// =====================================================================
+function formatDuration(sec) {
+  if (sec == null) return '?';
+  if (sec < 60) return Math.round(sec) + 's';
+  if (sec < 3600) return Math.floor(sec / 60) + 'm ' + Math.round(sec % 60) + 's';
+  var h = Math.floor(sec / 3600);
+  var m = Math.floor((sec % 3600) / 60);
+  return h + 'h ' + m + 'm';
+}
+
+function formatTimestamp(iso) {
+  if (!iso) return '';
+  try {
+    var d = new Date(iso);
+    if (isNaN(d.getTime())) return '';
+    var hh = String(d.getUTCHours()).padStart(2, '0');
+    var mm = String(d.getUTCMinutes()).padStart(2, '0');
+    var ss = String(d.getUTCSeconds()).padStart(2, '0');
+    return hh + ':' + mm + ':' + ss + ' UTC';
+  } catch (e) { return ''; }
+}
+
+function formatDateTimestamp(iso) {
+  if (!iso) return '';
+  try {
+    var d = new Date(iso);
+    if (isNaN(d.getTime())) return '';
+    var year = d.getUTCFullYear();
+    var mon = String(d.getUTCMonth() + 1).padStart(2, '0');
+    var day = String(d.getUTCDate()).padStart(2, '0');
+    var hh = String(d.getUTCHours()).padStart(2, '0');
+    var mm = String(d.getUTCMinutes()).padStart(2, '0');
+    var ss = String(d.getUTCSeconds()).padStart(2, '0');
+    return year + '-' + mon + '-' + day + ' ' + hh + ':' + mm + ':' + ss + ' UTC';
+  } catch (e) { return ''; }
+}
+
+function escapeHtml(str) {
+  if (!str) return '';
+  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+function renderMarkdown(text) {
+  if (!text) return '';
+  var s = escapeHtml(text);
+
+  // Phase 1: Extract code blocks into placeholders (protect from later passes)
+  var codeBlocks = [];
+  s = s.replace(/```[^\n]*\n([\s\S]*?)```/g, function(m, code) {
+    var idx = codeBlocks.length;
+    codeBlocks.push('<pre style="background:#f1f5f9;padding:8px 10px;border-radius:4px;font-size:0.75rem;overflow-x:auto;margin:4px 0"><code>' + code.replace(/\n$/, '') + '</code></pre>');
+    return '\x00CODEBLOCK' + idx + '\x00';
+  });
+  s = s.replace(/`([^`\n]+)`/g, function(m, code) {
+    var idx = codeBlocks.length;
+    codeBlocks.push('<code style="background:#f1f5f9;padding:1px 4px;border-radius:2px;font-size:0.85em">' + code + '</code>');
+    return '\x00CODEBLOCK' + idx + '\x00';
+  });
+
+  // Phase 2: Formatting (safe — code blocks are placeholders)
+  s = s.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  s = s.replace(/^(#{1,4})\s+(.+)$/gm, function(m, hashes, text) {
+    var sizes = {'1':'1.15em','2':'1.05em','3':'0.95em','4':'0.88em'};
+    return '<div style="font-weight:700;font-size:' + (sizes[hashes.length] || '0.88em') + ';margin:8px 0 4px 0;color:#1a1a2e">' + text + '</div>';
+  });
+  s = s.replace(/^---+$/gm, '<hr style="border:none;border-top:1px solid #e2e8f0;margin:8px 0">');
+  s = s.replace(/^[-*]\s+(.+)$/gm, '<div style="padding-left:12px">\u2022 $1</div>');
+  s = s.replace(/^\d+\.\s+(.+)$/gm, function(m, content) {
+    var num = m.match(/^(\d+)\./)[1];
+    return '<div style="padding-left:12px">' + num + '. ' + content + '</div>';
+  });
+
+  // Phase 3: Tables
+  s = s.replace(/(^\|.+\|$\n^\|[-| :]+\|$\n(?:^\|.+\|$\n?)+)/gm, function(tableBlock) {
+    var rows = tableBlock.trim().split('\n');
+    if (rows.length < 2) return tableBlock;
+    var html = '<table style="border-collapse:collapse;font-size:0.78rem;margin:6px 0;width:100%">';
+    rows.forEach(function(row, ri) {
+      if (ri === 1 && /^[-| :]+$/.test(row.replace(/\|/g, '').trim().replace(/[- :]/g, ''))) return;
+      var cells = row.split('|').filter(function(c, i, a) { return i > 0 && i < a.length - 1; });
+      var tag = ri === 0 ? 'th' : 'td';
+      var bgStyle = ri === 0 ? 'background:#f1f5f9;font-weight:600;' : (ri % 2 === 0 ? 'background:#fafbfc;' : '');
+      html += '<tr>';
+      cells.forEach(function(cell) {
+        html += '<' + tag + ' style="' + bgStyle + 'padding:4px 8px;border:1px solid #e2e8f0;text-align:left">' + cell.trim() + '</' + tag + '>';
+      });
+      html += '</tr>';
+    });
+    html += '</table>';
+    return html;
+  });
+
+  // Phase 4: Restore code blocks
+  s = s.replace(/\x00CODEBLOCK(\d+)\x00/g, function(m, idx) {
+    return codeBlocks[parseInt(idx)];
+  });
+
+  // Phase 5: Convert remaining newlines to <br>, skip inside <pre> and <table>
+  var parts = s.split(/(<pre[^>]*>[\s\S]*?<\/pre>|<table[^>]*>[\s\S]*?<\/table>)/g);
+  s = parts.map(function(part, i) {
+    if (i % 2 === 1) return part;
+    return part.replace(/\n/g, '<br>');
+  }).join('');
+  return s;
+}
+
+function truncateStr(str, max) {
+  if (!str || str.length <= max) return str || '';
+  return str.substring(0, max - 1) + '\u2026';
+}
+
+function agentColorClass(agentType) {
+  var map = {
+    'search-agent': 'agent-search-agent',
+    'source-researcher': 'agent-source-researcher',
+    'research-executor': 'agent-research-executor',
+    'code-reviewer': 'agent-code-reviewer',
+    'data-planner': 'agent-data-planner',
+    'research-synthesizer': 'agent-research-synthesizer',
+    'plan-checker': 'agent-plan-checker',
+    'report-writer': 'agent-report-writer',
+    'data-verifier': 'agent-data-verifier',
+    'notebook-assembler': 'agent-notebook-assembler',
+    'debugger': 'agent-debugger',
+    'integration-checker': 'agent-integration-checker',
+    'data-ingest': 'agent-data-ingest',
+    'framework-engineer': 'agent-framework-engineer'
+  };
+  return map[agentType] || 'agent-default';
+}
+
+function fileUrl(path) {
+  if (!path) return '#';
+  return '/' + path.replace(/^\//, '');
+}
+
+// =====================================================================
+// JSONL Fetching
+// =====================================================================
+async function fetchJsonlLine(filePath, lineNum) {
+  var url = fileUrl(filePath);
+  if (!jsonlCache[url]) {
+    try {
+      var resp = await fetch(url);
+      if (!resp.ok) throw new Error('HTTP ' + resp.status);
+      var text = await resp.text();
+      jsonlCache[url] = text.split('\n');
+    } catch (e) {
+      return { error: 'Failed to fetch ' + filePath + ': ' + e.message };
+    }
+  }
+  var lines = jsonlCache[url];
+  var idx = lineNum - 1;
+  if (idx < 0 || idx >= lines.length) {
+    return { error: 'Line ' + lineNum + ' out of range (file has ' + lines.length + ' lines)' };
+  }
+  try {
+    return { data: JSON.parse(lines[idx]) };
+  } catch (e) {
+    return { raw: lines[idx], parseError: e.message };
+  }
+}
+
+async function fetchJsonlRange(filePath, lineStart, lineEnd) {
+  var url = fileUrl(filePath);
+  if (!jsonlCache[url]) {
+    try {
+      var resp = await fetch(url);
+      if (!resp.ok) throw new Error('HTTP ' + resp.status);
+      var text = await resp.text();
+      jsonlCache[url] = text.split('\n');
+    } catch (e) {
+      return { error: 'Failed to fetch ' + filePath + ': ' + e.message };
+    }
+  }
+  var lines = jsonlCache[url];
+  var start = Math.max(0, lineStart - 1);
+  var end = Math.min(lines.length, lineEnd);
+  return { lines: lines.slice(start, end) };
+}
+
+// =====================================================================
+// File Content Fetching (for preview panel)
+// =====================================================================
+async function fetchFileContent(path) {
+  var url = fileUrl(path);
+  if (fileCache[url]) return { content: fileCache[url] };
+  try {
+    var resp = await fetch(url);
+    if (!resp.ok) throw new Error('HTTP ' + resp.status);
+    var text = await resp.text();
+    fileCache[url] = text;
+    return { content: text };
+  } catch (e) {
+    return { error: e.message };
+  }
+}
+
+// =====================================================================
+// Session Helpers
+// =====================================================================
+function activeSession() {
+  if (!manifest || !manifest.sessions || !manifest.sessions[activeSessionIdx]) return null;
+  return manifest.sessions[activeSessionIdx];
+}
+
+function sessionStats(session) {
+  var totalInput = 0, totalOutput = 0, totalCacheRead = 0, totalCacheWrite = 0;
+  (session.blocks || []).forEach(function(b) {
+    if (b.tokenUsage) {
+      totalInput += b.tokenUsage.input || 0;
+      totalOutput += b.tokenUsage.output || 0;
+      totalCacheRead += b.tokenUsage.cacheRead || 0;
+      totalCacheWrite += b.tokenUsage.cacheWrite || 0;
+    }
+  });
+  var subagentTokens = 0;
+  (session.subagents || []).forEach(function(sa) { subagentTokens += sa.tokens || 0; });
+  return {
+    totalInput: totalInput, totalOutput: totalOutput,
+    totalCacheRead: totalCacheRead, totalCacheWrite: totalCacheWrite,
+    orchestratorTokens: totalInput + totalOutput + totalCacheRead + totalCacheWrite,
+    subagentTokens: subagentTokens,
+    totalTokens: totalInput + totalOutput + totalCacheRead + totalCacheWrite + subagentTokens,
+    subagentCount: (session.subagents || []).length,
+    blockCount: (session.blocks || []).length
+  };
+}
+
+function buildBlockSubagentMap(session) {
+  var map = {};
+  (session.subagents || []).forEach(function(sa) {
+    if (sa.parentBlockId) {
+      if (!map[sa.parentBlockId]) map[sa.parentBlockId] = [];
+      map[sa.parentBlockId].push(sa);
+    }
+  });
+  return map;
+}
+
+// =====================================================================
+// Rendering: Tabs
+// =====================================================================
+function renderSessionSelect() {
+  var el = document.getElementById('sessionSelect');
+  if (!manifest || !manifest.sessions || manifest.sessions.length === 0) {
+    el.style.display = 'none';
+    return;
+  }
+  el.style.display = '';
+  el.innerHTML = manifest.sessions.map(function(s, i) {
+    var sel = i === activeSessionIdx ? ' selected' : '';
+    var dateLabel = formatDateTimestamp(s.startTime);
+    var label = dateLabel ? dateLabel + ' \u2014 ' + escapeHtml(s.sessionId) : 'Session ' + (i + 1) + ' (' + escapeHtml(s.sessionId) + ')';
+    return '<option value="' + i + '"' + sel + '>' + label + '</option>';
+  }).join('');
+  el.onchange = function() {
+    activeSessionIdx = parseInt(this.value);
+    selectedBlockId = null;
+    selectedSubagentId = null;
+    render();
+  };
+}
+
+// =====================================================================
+// Rendering: Stats Bar
+// =====================================================================
+function renderStatsBar() {
+  var el = document.getElementById('statsBar');
+  var session = activeSession();
+  if (!session) { el.innerHTML = ''; return; }
+  var stats = sessionStats(session);
+  var parts = [];
+  parts.push('<span><span class="stat-label">Session Duration:</span><span class="stat-value">' + formatDuration(session.durationSec) + '</span></span>');
+  if (session.model) parts.push('<span><span class="stat-label">Model:</span><span class="stat-value">' + escapeHtml(session.model) + '</span></span>');
+  parts.push('<span><span class="stat-label">Interaction Turns:</span><span class="stat-value">' + stats.blockCount + '</span></span>');
+  parts.push('<span><span class="stat-label">Specialist Subagents:</span><span class="stat-value">' + stats.subagentCount + '</span></span>');
+  if (session.cliVersion) parts.push('<span><span class="stat-label">Claude Code Version:</span><span class="stat-value">' + escapeHtml(session.cliVersion) + '</span></span>');
+  if (session.daafVersion) parts.push('<span><span class="stat-label">DAAF Version:</span><span class="stat-value">' + escapeHtml(session.daafVersion) + '</span></span>');
+  el.innerHTML = parts.join('');
+}
+
+// =====================================================================
+// Rendering: Unified Timeline
+// =====================================================================
+function renderTimeline() {
+  var panel = document.getElementById('timelinePanel');
+  var session = activeSession();
+  if (!session) {
+    panel.innerHTML = '<div class="state-message"><h2>No sessions found</h2><p>The manifest contains no session data.</p></div>';
+    return;
+  }
+  var blocks = session.blocks || [];
+  if (blocks.length === 0) {
+    panel.innerHTML = '<div class="state-message"><h2>Empty session</h2><p>No recorded blocks.</p></div>';
+    return;
+  }
+
+  var saMap = buildBlockSubagentMap(session);
+  mergedBlockLookup = {};
+
+  // Preprocess: merge consecutive assistant blocks without subagents
+  var displayItems = [];
+  var mergeBuffer = [];
+  var mergeIdx = 0;
+  function flushMerge() {
+    if (mergeBuffer.length === 0) return;
+    if (mergeBuffer.length === 1) {
+      displayItems.push(mergeBuffer[0]);
+    } else {
+      var mid = 'merged_' + mergeIdx++;
+      var merged = { _merged: true, id: mid, blocks: mergeBuffer.slice(), type: 'assistant' };
+      displayItems.push(merged);
+      mergedBlockLookup[mid] = merged;
+    }
+    mergeBuffer = [];
+  }
+  blocks.forEach(function(block) {
+    var bType = block.type || 'system';
+    var hasSubs = (saMap[block.id] || []).length > 0;
+    if (bType === 'assistant' && !hasSubs) {
+      mergeBuffer.push(block);
+    } else {
+      flushMerge();
+      displayItems.push(block);
+    }
+  });
+  flushMerge();
+
+  // Compute effective durations
+  var effDurations = {};
+  displayItems.forEach(function(item) {
+    if (item._merged) {
+      var total = 0;
+      item.blocks.forEach(function(b) { total += b.durationSec || 0.5; });
+      effDurations[item.id] = total;
+    } else {
+      var eff = item.durationSec || 0.5;
+      (saMap[item.id] || []).forEach(function(sa) {
+        var saDur = (sa.durationMs || 0) / 1000;
+        if (saDur > eff) eff = saDur;
+      });
+      effDurations[item.id] = eff;
+    }
+  });
+  var totalEffDur = displayItems.reduce(function(s, item) { return s + effDurations[item.id]; }, 0) || 1;
+
+  var html = '<div class="scroll-proxy" id="scrollProxy"><div class="scroll-proxy-inner"></div></div>';
+  html += '<div class="timeline-row" id="timelineRow">';
+
+  var counters = { user: 0, assistant: 0, system: 0 };
+  displayItems.forEach(function(item) {
+    var effDur = effDurations[item.id];
+    var pct = Math.max(1.5, (effDur / totalEffDur) * 100);
+    var selCls = (selectedBlockId === item.id && !selectedSubagentId) ? ' selected' : '';
+
+    if (item._merged) {
+      var startNum = counters['assistant'] + 1;
+      counters['assistant'] += item.blocks.length;
+      var endNum = counters['assistant'];
+      var label = 'O' + startNum + '-' + endNum;
+      item._label = label;
+      var summaryParts = item.blocks.map(function(b) { return b.summary || ''; }).filter(Boolean);
+      var summary = summaryParts.length > 0 ? escapeHtml(truncateStr(summaryParts.join('; '), 120)) : '';
+
+      html += '<div class="timeline-column" style="flex-basis:' + pct.toFixed(2) + '%;min-width:28px">';
+      html += '<div class="timeline-block type-assistant' + selCls + '" data-block-id="' + escapeHtml(item.id) + '">';
+      html += label;
+      html += '<span class="block-tooltip">' + label + ' (' + item.blocks.length + ' steps, ' + formatDuration(effDur) + ')';
+      if (summary) html += ' \u2014 ' + summary;
+      html += '</span></div></div>';
+    } else {
+      var bType = item.type || 'system';
+      counters[bType] = (counters[bType] || 0) + 1;
+      var label = (bType === 'user' ? 'U' : bType === 'assistant' ? 'O' : 'S') + counters[bType];
+      var summary = item.summary ? escapeHtml(truncateStr(item.summary, 120)) : '';
+      var blockSas = saMap[item.id] || [];
+
+      html += '<div class="timeline-column" style="flex-basis:' + pct.toFixed(2) + '%;min-width:' + (blockSas.length > 0 ? '60' : '28') + 'px">';
+      html += '<div class="timeline-block type-' + bType + selCls + '" data-block-id="' + escapeHtml(item.id) + '">';
+      html += label;
+      html += '<span class="block-tooltip">' + label + ' (' + formatDuration(item.durationSec) + ')';
+      if (summary) html += ' \u2014 ' + summary;
+      html += '</span></div>';
+
+      if (blockSas.length > 0) {
+        html += '<div class="subagent-area">';
+        blockSas.forEach(function(sa) {
+          var saDurSec = (sa.durationMs || 0) / 1000;
+          var barPct = effDur > 0 ? Math.max(15, Math.min(100, (saDurSec / effDur) * 100)) : 100;
+          var colorCls = agentColorClass(sa.agentType);
+          var selSaCls = selectedSubagentId === sa.id ? ' selected' : '';
+          var displayLabel = (sa.agentType || 'agent') + ': ' + (sa.label || sa.id);
+          html += '<div class="subagent-bar ' + colorCls + selSaCls + '" data-subagent-id="' + escapeHtml(sa.id) + '" style="width:' + barPct.toFixed(1) + '%" title="' + escapeHtml(displayLabel) + ' (' + formatDuration(saDurSec) + ')">';
+          html += escapeHtml(truncateStr(displayLabel, 50));
+          html += '</div>';
+        });
+        html += '</div>';
+      }
+      html += '</div>';
+    }
+  });
+
+  html += '</div>';
+
+  var unlinked = (session.subagents || []).filter(function(sa) { return !sa.parentBlockId; });
+  if (unlinked.length > 0) {
+    html += '<div class="unlinked-section">';
+    html += '<div class="section-label">Unlinked Specialists (' + unlinked.length + ')</div>';
+    unlinked.forEach(function(sa) {
+      var colorCls = agentColorClass(sa.agentType);
+      var selCls = selectedSubagentId === sa.id ? ' selected' : '';
+      var displayLabel = (sa.agentType || 'agent') + ': ' + (sa.label || sa.id);
+      html += '<div class="unlinked-bar ' + colorCls + selCls + '" data-subagent-id="' + escapeHtml(sa.id) + '" title="' + escapeHtml(displayLabel) + '">' + escapeHtml(truncateStr(displayLabel, 50)) + '</div>';
+    });
+    html += '</div>';
+  }
+
+  panel.innerHTML = html;
+  attachTimelineHandlers();
+  initScrollProxy('scrollProxy', 'timelineRow');
+}
+
+// =====================================================================
+// Scroll Proxy Sync (top scrollbar for timeline)
+// =====================================================================
+function initScrollProxy(proxyId, contentId) {
+  var proxy = document.getElementById(proxyId);
+  var content = document.getElementById(contentId);
+  if (!proxy || !content) return;
+  var inner = proxy.firstElementChild;
+  if (inner) inner.style.width = content.scrollWidth + 'px';
+  var syncing = false;
+  proxy.addEventListener('scroll', function() {
+    if (syncing) { syncing = false; return; }
+    syncing = true;
+    content.scrollLeft = proxy.scrollLeft;
+  });
+  content.addEventListener('scroll', function() {
+    if (syncing) { syncing = false; return; }
+    syncing = true;
+    proxy.scrollLeft = content.scrollLeft;
+  });
+  // Re-sync proxy width on resize
+  if (typeof ResizeObserver !== 'undefined') {
+    new ResizeObserver(function() {
+      if (inner) inner.style.width = content.scrollWidth + 'px';
+    }).observe(content);
+  }
+}
+
+// =====================================================================
+// Timeline Click Handlers (attached once per render)
+// =====================================================================
+function attachTimelineHandlers() {
+  var panel = document.getElementById('timelinePanel');
+  panel.querySelectorAll('.timeline-block').forEach(function(el) {
+    el.addEventListener('click', function(e) {
+      e.stopPropagation();
+      var blockId = this.dataset.blockId;
+      if (selectedBlockId === blockId && !selectedSubagentId) {
+        selectedBlockId = null;
+      } else {
+        selectedBlockId = blockId;
+        selectedSubagentId = null;
+      }
+      updateTimelineSelection();
+      renderDetail();
+    });
+  });
+  panel.querySelectorAll('.subagent-bar, .unlinked-bar').forEach(function(el) {
+    el.addEventListener('click', function(e) {
+      e.stopPropagation();
+      var saId = this.dataset.subagentId;
+      if (selectedSubagentId === saId) {
+        selectedSubagentId = null;
+      } else {
+        selectedSubagentId = saId;
+        selectedBlockId = null;
+      }
+      updateTimelineSelection();
+      renderDetail();
+    });
+  });
+}
+
+// =====================================================================
+// Selection Management (CSS-only, no re-render)
+// =====================================================================
+function updateTimelineSelection() {
+  document.querySelectorAll('.timeline-block.selected, .subagent-bar.selected, .unlinked-bar.selected').forEach(function(el) {
+    el.classList.remove('selected');
+  });
+  if (selectedBlockId && !selectedSubagentId) {
+    var el = document.querySelector('.timeline-block[data-block-id="' + selectedBlockId + '"]');
+    if (el) el.classList.add('selected');
+  }
+  if (selectedSubagentId) {
+    var el = document.querySelector('[data-subagent-id="' + selectedSubagentId + '"]');
+    if (el) el.classList.add('selected');
+  }
+}
+
+// =====================================================================
+// Rendering: Detail Panel
+// =====================================================================
+function renderDetail() {
+  var panel = document.getElementById('detailPanel');
+  var session = activeSession();
+  if (!session) { panel.innerHTML = '<div class="detail-empty">No session data.</div>'; return; }
+
+  if (selectedSubagentId) {
+    var sa = (session.subagents || []).find(function(s) { return s.id === selectedSubagentId; });
+    if (sa) { renderSubagentDetail(panel, sa, session); return; }
+  }
+  if (selectedBlockId) {
+    if (mergedBlockLookup[selectedBlockId]) {
+      renderMergedBlockDetail(panel, mergedBlockLookup[selectedBlockId], session);
+      return;
+    }
+    var block = (session.blocks || []).find(function(b) { return b.id === selectedBlockId; });
+    if (block) { renderBlockDetail(panel, block, session); return; }
+  }
+  panel.innerHTML = '<div class="detail-empty">Click a block in the timeline to view details.</div>';
+}
+
+function renderBlockDetail(panel, block, session) {
+  var bType = block.type || 'system';
+  var typeLabel = bType === 'user' ? 'User Message' : bType === 'assistant' ? 'Orchestrator Step' : 'System Event';
+  var html = '';
+
+  html += '<div class="detail-header">';
+  html += '<span class="detail-title">' + typeLabel + '</span>';
+  html += '<span class="detail-badge type-' + bType + '">' + escapeHtml(block.id) + '</span>';
+  if (block.startTime) html += ' <span class="detail-timestamp">' + formatTimestamp(block.startTime) + '</span>';
+  html += '</div>';
+
+  html += '<div class="detail-meta">';
+  html += '<strong>Duration:</strong> ' + formatDuration(block.durationSec);
+  if (block.file) {
+    var lineRef = block.lineStart && block.lineEnd ? ':' + block.lineStart + '-' + block.lineEnd : '';
+    html += ' &nbsp;|&nbsp; <strong>Source:</strong> <a href="' + escapeHtml(fileUrl(block.file)) + '" class="activity-target" data-preview-path="' + escapeHtml(block.file) + '" title="' + escapeHtml(block.file) + '">' + escapeHtml(block.file + lineRef) + '</a>';
+  }
+  html += '</div>';
+
+  if (bType === 'user' && block.summary) {
+    html += '<div class="detail-section-title">Message</div>';
+    html += '<div class="content-box">' + renderMarkdown(block.summary) + '</div>';
+  }
+
+  if (block.activities && block.activities.length > 0) {
+    if (bType !== 'user') {
+      html += '<div class="detail-section-title">Activities (' + block.activities.length + ')</div>';
+    }
+    html += renderActivities(block.activities, block.file, block.startTime);
+  }
+
+  panel.innerHTML = html;
+  attachDetailHandlers(panel);
+}
+
+function renderMergedBlockDetail(panel, merged, session) {
+  var html = '';
+  var label = merged._label || 'Merged Steps';
+  var firstBlock = merged.blocks[0];
+  var lastBlock = merged.blocks[merged.blocks.length - 1];
+  var totalDur = merged.blocks.reduce(function(s, b) { return s + (b.durationSec || 0); }, 0);
+
+  html += '<div class="detail-header">';
+  html += '<span class="detail-title">Orchestrator Steps ' + label + '</span>';
+  html += '<span class="detail-badge type-assistant">' + merged.blocks.length + ' steps</span>';
+  if (firstBlock.startTime) html += ' <span class="detail-timestamp">' + formatTimestamp(firstBlock.startTime) + ' \u2013 ' + formatTimestamp(lastBlock.endTime || lastBlock.startTime) + '</span>';
+  html += '</div>';
+
+  html += '<div class="detail-meta">';
+  html += '<strong>Duration:</strong> ' + formatDuration(totalDur);
+  html += '</div>';
+
+  merged.blocks.forEach(function(block, idx) {
+    html += '<div class="detail-section-title" style="display:flex;justify-content:space-between;align-items:center">';
+    html += 'Step ' + (idx + 1);
+    if (block.startTime) html += ' <span class="detail-timestamp">' + formatTimestamp(block.startTime) + '</span>';
+    html += '</div>';
+
+    if (block.activities && block.activities.length > 0) {
+      html += renderActivities(block.activities, block.file, block.startTime);
+    }
+  });
+
+  panel.innerHTML = html;
+  attachDetailHandlers(panel);
+}
+
+function renderSubagentDetail(panel, sa, session) {
+  var html = '';
+  html += '<div class="detail-header">';
+  html += '<span class="detail-title">Subagent: ' + escapeHtml(sa.agentType || 'unknown') + ' [id: ' + escapeHtml(sa.id) + ']</span>';
+  html += '</div>';
+  if (sa.label) html += '<div style="font-size:0.85rem;color:#64748b;margin-bottom:6px">' + escapeHtml(sa.label) + '</div>';
+
+  html += '<div class="detail-meta">';
+  var durSec = sa.durationMs != null ? sa.durationMs / 1000 : null;
+  html += '<strong>Duration:</strong> ' + formatDuration(durSec);
+  if (sa.toolUseCount != null) html += ' &nbsp;|&nbsp; <strong>Tool calls:</strong> ' + sa.toolUseCount;
+  if (sa.startTime) html += ' &nbsp;|&nbsp; <span class="detail-timestamp">' + formatDateTimestamp(sa.startTime) + '</span>';
+  html += '<br>';
+  if (sa.file) html += '<strong>Log file:</strong> <a href="' + escapeHtml(fileUrl(sa.file)) + '" class="activity-target" data-preview-path="' + escapeHtml(sa.file) + '">' + escapeHtml(sa.file) + '</a>';
+  if (sa.parentBlockId) {
+    html += ' &nbsp;|&nbsp; <strong>Parent block:</strong> <span class="view-full-link" data-action="go-block" data-block-id="' + escapeHtml(sa.parentBlockId) + '">' + escapeHtml(sa.parentBlockId) + '</span>';
+  }
+  html += '</div>';
+
+  // Dispatch prompt (full, scrollable)
+  if (sa.invocation && sa.invocation.promptPreview) {
+    html += '<div class="detail-section-title">Dispatch Prompt</div>';
+    html += '<div class="subagent-preview">' + renderMarkdown(sa.invocation.promptPreview) + '</div>';
+  }
+
+  // Agent protocol
+  if (sa.agentType) {
+    var protocolPath = '.claude/agents/' + sa.agentType + '.md';
+    html += '<div class="detail-section-title">Agent Protocol</div>';
+    html += '<div style="padding:4px 0;font-size:0.8rem">';
+    html += '<a href="' + escapeHtml(fileUrl(protocolPath)) + '" class="activity-target" data-preview-path="' + escapeHtml(protocolPath) + '" title="' + escapeHtml(protocolPath) + '">' + escapeHtml(protocolPath) + '</a>';
+    html += '</div>';
+  }
+
+  // Frontmatter skills (auto-loaded from agent specification)
+  if (sa.frontmatterSkills && sa.frontmatterSkills.length > 0) {
+    html += '<div class="detail-section-title">Agent Skills <span style="text-transform:none;font-weight:400;letter-spacing:0">(from specification)</span></div>';
+    html += '<div style="padding:4px 0;font-size:0.8rem">';
+    sa.frontmatterSkills.forEach(function(skillName) {
+      var skillPath = '.claude/skills/' + skillName + '/SKILL.md';
+      html += '<div style="padding:2px 0">';
+      html += '<span class="activity-dot type-skill" style="display:inline-block;vertical-align:middle;margin-right:6px"></span>';
+      html += '<a href="' + escapeHtml(fileUrl(skillPath)) + '" class="activity-target" data-preview-path="' + escapeHtml(skillPath) + '" title="' + escapeHtml(skillPath) + '">' + escapeHtml(skillName) + '</a>';
+      html += '</div>';
+    });
+    html += '</div>';
+  }
+
+  // Activities
+  if (sa.activities && sa.activities.length > 0) {
+    html += '<div class="detail-section-title">Activities (' + sa.activities.length + ')</div>';
+    html += renderActivities(sa.activities, sa.file, sa.startTime);
+  }
+
+  panel.innerHTML = html;
+  attachDetailHandlers(panel);
+}
+
+// =====================================================================
+// Rendering: Activities
+// =====================================================================
+function renderActivities(activities, defaultFile, blockTime) {
+  // Group consecutive activities by type: thinking, text, or tool calls
+  var groups = [];
+  var currentGroup = null;
+  activities.forEach(function(act) {
+    var aType = act.type || 'text';
+    var groupType = aType === 'thinking' ? 'thinking' : aType === 'text' ? 'text' : 'tools';
+    if (!currentGroup || currentGroup.type !== groupType) {
+      currentGroup = { type: groupType, items: [] };
+      groups.push(currentGroup);
+    }
+    currentGroup.items.push(act);
+  });
+
+  var timeStr = blockTime ? ' <span class="detail-timestamp">' + formatTimestamp(blockTime) + '</span>' : '';
+  var html = '';
+  groups.forEach(function(group) {
+    html += '<div class="activity-group group-' + group.type + '">';
+    if (group.type === 'thinking') {
+      html += '<div class="activity-group-label">Thinking' + timeStr + '</div>';
+    } else if (group.type === 'text') {
+      html += '<div class="activity-group-label">Message' + timeStr + '</div>';
+    } else {
+      html += '<div class="activity-group-label">Tool Calls' + timeStr + '</div>';
+    }
+    html += '<ul class="activity-list">';
+    group.items.forEach(function(act) {
+      html += renderSingleActivity(act, defaultFile);
+    });
+    html += '</ul>';
+    html += '</div>';
+  });
+  return html;
+}
+
+function renderSingleActivity(act, defaultFile) {
+  var aType = act.type || 'text';
+  var isError = act.error === true;
+  var isSearch = act.tool === 'Glob' || act.tool === 'Grep';
+
+  // Thinking activities render as collapsible italic blocks with markdown
+  if (aType === 'thinking') {
+    var thinkText = act.description || '';
+    var charCount = thinkText.length;
+    var isLong = charCount > 300;
+    var collapsedCls = isLong ? ' collapsed' : '';
+    var html = '<li>';
+    html += '<div class="activity-thinking-block' + collapsedCls + '" data-thinking="true">' + renderMarkdown(thinkText) + '</div>';
+    if (isLong) {
+      html += '<div class="thinking-toggle" data-action="toggle-thinking">' + charCount.toLocaleString() + ' chars \u2014 click to expand</div>';
+    }
+    html += '</li>';
+    return html;
+  }
+
+  // Text activities render as block-level pre-wrapped content
+  if (aType === 'text') {
+    var descText = act.description || '';
+    return '<li><div class="activity-text-block">' + renderMarkdown(descText) + '</div></li>';
+  }
+
+  var html = '<li class="activity-item">';
+  html += '<span class="activity-dot type-' + aType + '"></span>';
+
+  var descHtml = '';
+  if (aType === 'delegate') descHtml += '<span class="delegate-arrow"></span>';
+
+  var descText = act.description || (act.tool ? act.tool : aType);
+  descHtml += '<span>' + escapeHtml(descText) + '</span>';
+  if (isError) descHtml += '<span class="activity-error-badge">error</span>';
+
+  // Primary target file link (skip for search tools — results shown in box below)
+  if (act.target && !isSearch) {
+    descHtml += ' <a href="' + escapeHtml(fileUrl(act.target)) + '" class="activity-target" data-preview-path="' + escapeHtml(act.target) + '" title="Preview: ' + escapeHtml(act.target) + '">' + escapeHtml(act.target.split('/').pop()) + '</a>';
+  }
+
+  // Extra targets (e.g., multiple files in Bash commands)
+  if (act.extraTargets && act.extraTargets.length > 0) {
+    descHtml += ' <span class="activity-extra-targets">';
+    act.extraTargets.forEach(function(t) {
+      descHtml += ' <a href="' + escapeHtml(fileUrl(t)) + '" class="activity-target" data-preview-path="' + escapeHtml(t) + '" title="Preview: ' + escapeHtml(t) + '">' + escapeHtml(t.split('/').pop()) + '</a>';
+    });
+    descHtml += '</span>';
+  }
+
+  // Subagent link
+  if (aType === 'delegate' && act.subagentId) {
+    descHtml += ' <span class="view-full-link" data-action="go-subagent" data-subagent-id="' + escapeHtml(act.subagentId) + '">[view]</span>';
+  }
+
+  html += '<span class="activity-desc' + (aType === 'text' ? ' type-text' : '') + '">' + descHtml + '</span>';
+
+  // Line reference badge: prefer resultLine (tool output) over line (tool dispatch)
+  var refLine = (act.tool && act.resultLine != null) ? act.resultLine : act.line;
+  if (refLine != null) {
+    var lineFile = defaultFile || '';
+    html += ' <span class="activity-line-ref" data-action="load-line" data-file="' + escapeHtml(lineFile) + '" data-line="' + refLine + '" title="Load raw JSONL line ' + refLine + '">[L' + refLine + ']</span>';
+  }
+
+  html += '</li>';
+
+  // Search results box (Glob/Grep)
+  if (isSearch && act.resultContent) {
+    html += '<li class="activity-item" style="padding-left:16px"><div class="content-box search-results">' + escapeHtml(act.resultContent) + '</div></li>';
+  }
+
+  return html;
+}
+
+// =====================================================================
+// Detail Panel Event Handlers (delegated)
+// =====================================================================
+function attachDetailHandlers(panel) {
+  // File preview links (click loads preview, ctrl/cmd+click opens new tab)
+  panel.querySelectorAll('[data-preview-path]').forEach(function(el) {
+    el.addEventListener('click', function(e) {
+      if (e.ctrlKey || e.metaKey) return;
+      e.preventDefault();
+      loadFilePreview(this.dataset.previewPath);
+    });
+  });
+
+  // Load single JSONL line (for [L] badges) — toggle on/off
+  panel.querySelectorAll('[data-action="load-line"]').forEach(function(el) {
+    el.addEventListener('click', async function() {
+      var file = this.dataset.file;
+      var line = parseInt(this.dataset.line);
+      if (!file || isNaN(line)) return;
+
+      // Show raw JSONL in the file preview panel (right side)
+      var previewPanel = document.getElementById('filePreview');
+      var label = file.split('/').pop() + ':' + line;
+      previewPanel.innerHTML =
+        '<div class="preview-header">' +
+        '<span class="preview-path" title="' + escapeHtml(file) + ' line ' + line + '">Raw JSONL \u2014 ' + escapeHtml(label) + '</span>' +
+        '<button class="preview-close" id="previewCloseBtn">\u00d7</button>' +
+        '</div>' +
+        '<div class="preview-content"><div style="padding:20px;color:#94a3b8;font-style:italic">Loading line ' + line + '...</div></div>';
+
+      document.getElementById('previewCloseBtn').addEventListener('click', closeFilePreview);
+
+      var contentEl = previewPanel.querySelector('.preview-content');
+      var result = await fetchJsonlLine(file, line);
+      var text = '';
+      if (result.error) {
+        text = 'Error: ' + result.error;
+      } else if (result.data) {
+        text = JSON.stringify(result.data, null, 2);
+      } else {
+        text = (result.raw || '(empty)') + (result.parseError ? '\n\nParse error: ' + result.parseError : '');
+      }
+      var lines = text.split('\n');
+      var lineHtml = lines.map(function(l, i) {
+        return '<span class="ln">' + String(i + 1).padStart(5) + '</span>' + escapeHtml(l);
+      }).join('\n');
+      contentEl.innerHTML = '<pre class="file-content"><code>' + lineHtml + '</code></pre>';
+    });
+  });
+
+  // Toggle thinking block expand/collapse
+  panel.querySelectorAll('[data-action="toggle-thinking"]').forEach(function(el) {
+    el.addEventListener('click', function() {
+      var thinkingBlock = this.previousElementSibling;
+      if (!thinkingBlock) return;
+      var isCollapsed = thinkingBlock.classList.contains('collapsed');
+      if (isCollapsed) {
+        thinkingBlock.classList.remove('collapsed');
+        this.textContent = 'click to collapse';
+      } else {
+        thinkingBlock.classList.add('collapsed');
+        var charCount = (thinkingBlock.textContent || '').length;
+        this.textContent = charCount.toLocaleString() + ' chars \u2014 click to expand';
+      }
+    });
+  });
+
+  // Navigate to subagent
+  panel.querySelectorAll('[data-action="go-subagent"]').forEach(function(el) {
+    el.addEventListener('click', function() {
+      selectedSubagentId = this.dataset.subagentId;
+      selectedBlockId = null;
+      updateTimelineSelection();
+      renderDetail();
+    });
+  });
+
+  // Navigate to block
+  panel.querySelectorAll('[data-action="go-block"]').forEach(function(el) {
+    el.addEventListener('click', function() {
+      selectedBlockId = this.dataset.blockId;
+      selectedSubagentId = null;
+      updateTimelineSelection();
+      renderDetail();
+    });
+  });
+}
+
+// =====================================================================
+// File Preview Panel
+// =====================================================================
+async function loadFilePreview(path) {
+  var panel = document.getElementById('filePreview');
+  var url = fileUrl(path);
+
+  panel.innerHTML =
+    '<div class="preview-header">' +
+    '<span class="preview-path" title="' + escapeHtml(path) + '">' + escapeHtml(path) + '</span>' +
+    '<a href="' + escapeHtml(url) + '" target="_blank" class="preview-open-tab">Open in new tab</a>' +
+    '<button class="preview-close" id="previewCloseBtn">\u00d7</button>' +
+    '</div>' +
+    (previewNoticeDismissed ? '' :
+    '<div class="preview-notice" id="previewNotice">' +
+    '<span class="preview-notice-text">Note: This file viewer shows the current version of this file on disk, which may differ from the version that existed when this session was recorded.</span>' +
+    '<button class="preview-notice-dismiss" id="previewNoticeDismiss" title="Dismiss">\u00d7</button>' +
+    '</div>') +
+    '<div class="preview-content"><div style="padding:20px;color:#94a3b8;font-style:italic">Loading...</div></div>';
+
+  document.getElementById('previewCloseBtn').addEventListener('click', closeFilePreview);
+  var noticeBtn = document.getElementById('previewNoticeDismiss');
+  if (noticeBtn) {
+    noticeBtn.addEventListener('click', function() {
+      previewNoticeDismissed = true;
+      var notice = document.getElementById('previewNotice');
+      if (notice) notice.remove();
+    });
+  }
+
+  // Detect binary/non-previewable files before fetching
+  var binaryExts = /\.(parquet|png|jpg|jpeg|gif|bmp|ico|pdf|zip|gz|tar|whl|pyc|pkl|pickle|sqlite|db|feather|arrow|xlsx|xls|doc|docx)$/i;
+  var contentEl = panel.querySelector('.preview-content');
+  if (binaryExts.test(path)) {
+    if (!contentEl) return;
+    var ext = path.match(/\.(\w+)$/)[1].toLowerCase();
+    var msg = '<div style="padding:30px 20px;text-align:center;color:#64748b">';
+    msg += '<div style="font-size:1.5rem;margin-bottom:8px">Binary file</div>';
+    msg += '<div style="font-size:0.85rem;margin-bottom:12px"><code style="background:#f1f5f9;padding:2px 6px;border-radius:3px">' + escapeHtml(path.split('/').pop()) + '</code></div>';
+    msg += '<div style="font-size:0.8rem;color:#94a3b8">.' + escapeHtml(ext) + ' files cannot be previewed in the browser.</div>';
+    msg += '</div>';
+    contentEl.innerHTML = msg;
+    return;
+  }
+
+  var result = await fetchFileContent(path);
+  if (!contentEl) return;
+
+  if (result.error) {
+    contentEl.innerHTML = '<div style="padding:20px;color:#ef4444">Failed to load: ' + escapeHtml(result.error) + '</div>';
+    return;
+  }
+
+  // Render .md files with markdown formatting
+  var isMd = /\.md$/i.test(path);
+  if (isMd) {
+    var text = result.content;
+    var maxChars = 200000;
+    if (text.length > maxChars) {
+      text = text.substring(0, maxChars) + '\n\n... (' + (text.length - maxChars) + ' more characters)';
+    }
+    contentEl.innerHTML = '<div style="padding:12px 16px;font-size:0.82rem;line-height:1.6;color:#334155;overflow:auto">' + renderMarkdown(text) + '</div>';
+    return;
+  }
+
+  var lines = result.content.split('\n');
+  var maxLines = 3000;
+  var display = lines.slice(0, maxLines);
+  var lineHtml = display.map(function(line, i) {
+    return '<span class="ln">' + String(i + 1).padStart(5) + '</span>' + escapeHtml(line);
+  }).join('\n');
+
+  if (lines.length > maxLines) {
+    lineHtml += '\n\n  ... (' + (lines.length - maxLines) + ' more lines)';
+  }
+
+  contentEl.innerHTML = '<pre class="file-content"><code>' + lineHtml + '</code></pre>';
+}
+
+function closeFilePreview() {
+  document.getElementById('filePreview').innerHTML = '<div class="preview-empty">Click a file reference to preview it here.</div>';
+}
+
+
+// =====================================================================
+// Render Entry Point
+// =====================================================================
+function render() {
+  renderSessionSelect();
+  renderStatsBar();
+  renderTimeline();
+  renderDetail();
+}
+
+// =====================================================================
+// Resize Handles
+// =====================================================================
+(function() {
+  // --- Horizontal resize (between timeline and bottom panels) ---
+  var hHandle = document.getElementById('resizeHandle');
+  var timelinePanel = document.getElementById('timelinePanel');
+  var bottomPanels = document.getElementById('bottomPanels');
+  var mainContent = document.querySelector('.main-content');
+  var hDragging = false;
+  var hStartY = 0, hStartTopFlex = 6, hStartBotFlex = 4;
+
+  hHandle.addEventListener('mousedown', function(e) {
+    hDragging = true;
+    hStartY = e.clientY;
+    var tRect = timelinePanel.getBoundingClientRect();
+    var bRect = bottomPanels.getBoundingClientRect();
+    var total = tRect.height + bRect.height;
+    hStartTopFlex = tRect.height / total * 10;
+    hStartBotFlex = bRect.height / total * 10;
+    hHandle.classList.add('dragging');
+    e.preventDefault();
+  });
+
+  document.addEventListener('mousemove', function(e) {
+    if (!hDragging && !vDragging) return;
+    if (hDragging) {
+      var dy = e.clientY - hStartY;
+      var mainRect = mainContent.getBoundingClientRect();
+      var totalH = mainRect.height - 5;
+      var deltaFlex = (dy / totalH) * 10;
+      timelinePanel.style.flex = Math.max(1, Math.min(8, hStartTopFlex + deltaFlex));
+      bottomPanels.style.flex = Math.max(2, Math.min(9, hStartBotFlex - deltaFlex));
+    }
+    if (vDragging) {
+      var dx = e.clientX - vStartX;
+      var containerRect = bottomPanels.getBoundingClientRect();
+      var totalW = containerRect.width - 5;
+      var deltaFlex = (dx / totalW) * 10;
+      detailPanelEl.style.flex = Math.max(1, Math.min(9, vStartLeftFlex + deltaFlex));
+      filePreviewEl.style.flex = Math.max(1, Math.min(9, vStartRightFlex - deltaFlex));
+    }
+  });
+
+  document.addEventListener('mouseup', function() {
+    if (hDragging) { hDragging = false; hHandle.classList.remove('dragging'); }
+    if (vDragging) { vDragging = false; vHandle.classList.remove('dragging'); }
+  });
+
+  // --- Vertical resize (between detail and file preview) ---
+  var vHandle = document.getElementById('verticalResize');
+  var detailPanelEl = document.getElementById('detailPanel');
+  var filePreviewEl = document.getElementById('filePreview');
+  var vDragging = false;
+  var vStartX = 0, vStartLeftFlex = 1, vStartRightFlex = 1;
+
+  vHandle.addEventListener('mousedown', function(e) {
+    vDragging = true;
+    vStartX = e.clientX;
+    var lRect = detailPanelEl.getBoundingClientRect();
+    var rRect = filePreviewEl.getBoundingClientRect();
+    var total = lRect.width + rRect.width;
+    vStartLeftFlex = lRect.width / total * 10;
+    vStartRightFlex = rRect.width / total * 10;
+    vHandle.classList.add('dragging');
+    e.preventDefault();
+  });
+})();
+
+// =====================================================================
+// Load Manifest (preserves session selection across refreshes)
+// =====================================================================
+async function loadManifest() {
+  // Save current session identity before reloading
+  var previousSessionId = null;
+  if (manifest && manifest.sessions && manifest.sessions[activeSessionIdx]) {
+    previousSessionId = manifest.sessions[activeSessionIdx].sessionId;
+  }
+
+  try {
+    var params = new URLSearchParams(window.location.search);
+    var manifestUrl = params.get('manifest') || './session_manifest.json';
+    // Prefix with / if it's a relative path without protocol (so it resolves from server root)
+    if (manifestUrl && !manifestUrl.startsWith('/') && !manifestUrl.startsWith('./') && !manifestUrl.startsWith('http')) {
+      manifestUrl = '/' + manifestUrl;
+    }
+    var resp = await fetch(manifestUrl + (manifestUrl.indexOf('?') >= 0 ? '&' : '?') + 't=' + Date.now());
+    if (!resp.ok) throw new Error('HTTP ' + resp.status + ' \u2014 could not load manifest from ' + manifestUrl);
+    manifest = await resp.json();
+  } catch (e) {
+    document.getElementById('timelinePanel').innerHTML =
+      '<div class="state-message">' +
+      '<h2>Failed to load session manifest</h2>' +
+      '<p>' + escapeHtml(e.message) + '</p>' +
+      '<p style="margin-top:12px">Make sure you are serving from the DAAF root directory:<br>' +
+      '<code>bash /daaf/scripts/generate_log_viewer.sh &lt;project_path&gt;</code><br>' +
+      'or <code>bash /daaf/scripts/generate_log_viewer.sh --archive</code></p></div>';
+    return;
+  }
+
+  if (manifest.project) {
+    document.getElementById('projectName').textContent = 'Project: ' + (manifest.project.name || manifest.project.path || 'Unknown');
+  }
+
+  if (!manifest.sessions || manifest.sessions.length === 0) {
+    document.getElementById('timelinePanel').innerHTML =
+      '<div class="state-message"><h2>No sessions found</h2><p>The manifest exists but contains no session data.</p></div>';
+    return;
+  }
+
+  // Restore session selection if the session still exists
+  if (previousSessionId) {
+    var found = -1;
+    for (var i = 0; i < manifest.sessions.length; i++) {
+      if (manifest.sessions[i].sessionId === previousSessionId) {
+        found = i;
+        break;
+      }
+    }
+    activeSessionIdx = found >= 0 ? found : 0;
+  } else {
+    activeSessionIdx = 0;
+  }
+
+  // Clear JSONL cache on refresh so updated log files are re-fetched
+  jsonlCache = {};
+
+  render();
+}
+
+// =====================================================================
+// Refresh Controls
+// =====================================================================
+var refreshInProgress = false;
+var autoRefreshTimerId = null;
+
+async function doRefresh() {
+  if (refreshInProgress) return;
+  refreshInProgress = true;
+  var btn = document.getElementById('refreshBtn');
+  btn.textContent = 'Refreshing\u2026';
+  btn.classList.add('refreshing');
+
+  try {
+    try {
+      var resp = await fetch('/api/refresh-manifest');
+      if (!resp.ok) {
+        var errBody = await resp.text();
+        console.error('Refresh failed:', resp.status, errBody);
+      }
+    } catch (e) {
+      console.error('Refresh request error:', e);
+    }
+
+    // Reload the manifest regardless (the endpoint may have partially succeeded)
+    await loadManifest();
+
+    // Update last-refreshed timestamp
+    var now = new Date();
+    var hh = String(now.getHours()).padStart(2, '0');
+    var mm = String(now.getMinutes()).padStart(2, '0');
+    var ss = String(now.getSeconds()).padStart(2, '0');
+    document.getElementById('lastRefreshed').textContent = 'last: ' + hh + ':' + mm + ':' + ss;
+  } finally {
+    btn.textContent = 'Refresh';
+    btn.classList.remove('refreshing');
+    refreshInProgress = false;
+  }
+}
+
+function startAutoRefresh() {
+  stopAutoRefresh();
+  var intervalSec = parseInt(document.getElementById('autoRefreshInterval').value) || 60;
+  autoRefreshTimerId = setInterval(doRefresh, intervalSec * 1000);
+}
+
+function stopAutoRefresh() {
+  if (autoRefreshTimerId !== null) {
+    clearInterval(autoRefreshTimerId);
+    autoRefreshTimerId = null;
+  }
+}
+
+// Wire up refresh button
+document.getElementById('refreshBtn').addEventListener('click', doRefresh);
+
+// Wire up auto-refresh toggle and interval
+(function() {
+  var toggle = document.getElementById('autoRefreshToggle');
+  var intervalSelect = document.getElementById('autoRefreshInterval');
+
+  // Restore from localStorage
+  var savedEnabled = localStorage.getItem('daaf-auto-refresh-enabled');
+  var savedInterval = localStorage.getItem('daaf-auto-refresh-interval');
+  if (savedInterval && ['60','300','600','1800'].indexOf(savedInterval) >= 0) {
+    intervalSelect.value = savedInterval;
+  }
+  if (savedEnabled !== 'false') {
+    toggle.checked = true;
+    startAutoRefresh();
+  }
+
+  toggle.addEventListener('change', function() {
+    localStorage.setItem('daaf-auto-refresh-enabled', toggle.checked ? 'true' : 'false');
+    if (toggle.checked) {
+      startAutoRefresh();
+    } else {
+      stopAutoRefresh();
+    }
+  });
+
+  intervalSelect.addEventListener('change', function() {
+    localStorage.setItem('daaf-auto-refresh-interval', intervalSelect.value);
+    if (toggle.checked) {
+      startAutoRefresh();
+    }
+  });
+})();
+
+loadManifest();
+</script>
+</body>
+</html>
diff --git a/scripts/log_viewer_server.py b/scripts/log_viewer_server.py
new file mode 100644
index 0000000..197c27d
--- /dev/null
+++ b/scripts/log_viewer_server.py
@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""
+log_viewer_server.py — Custom HTTP server for the DAAF Log Explorer
+
+Serves static files from REPO_ROOT (same as http.server) and provides
+a /api/refresh-manifest endpoint that recovers in-flight sessions and
+regenerates the session manifest.
+
+Usage:
+    python3 log_viewer_server.py --port 2719 --root /daaf --archive --logs-dir /daaf/.claude/logs/sessions
+    python3 log_viewer_server.py --port 2719 --root /daaf --project-path /daaf/research/2026-03-29_Analysis
+"""
+
+import argparse
+import http.server
+import json
+import os
+import socketserver
+import subprocess
+import sys
+
+# --- Parse arguments ---
+
+parser = argparse.ArgumentParser(description="DAAF Log Explorer HTTP server")
+parser.add_argument("--port", type=int, default=2719, help="Port to listen on (default: 2719)")
+parser.add_argument("--root", type=str, required=True, help="Root directory to serve files from")
+group = parser.add_mutually_exclusive_group(required=True)
+group.add_argument("--project-path", type=str, help="Absolute path to a DAAF research project")
+group.add_argument("--archive", action="store_true", help="Archive mode (use with --logs-dir)")
+parser.add_argument("--logs-dir", type=str, help="Logs directory (required with --archive)")
+args = parser.parse_args()
+
+if args.archive and not args.logs_dir:
+    print("ERROR: --archive requires --logs-dir", file=sys.stderr)
+    sys.exit(1)
+
+PORT = args.port
+ROOT_DIR = os.path.abspath(args.root)
+RECOVERY_SCRIPT = os.path.join(ROOT_DIR, ".claude", "hooks", "recover-session-logs.sh")
+GENERATOR_SCRIPT = os.path.join(ROOT_DIR, "scripts", "generate_log_viewer.py")
+
+# --- Change to serving root ---
+
+os.chdir(ROOT_DIR)
+
+# --- Build the manifest regeneration command ---
+
+if args.archive:
+    GENERATOR_CMD = [sys.executable, GENERATOR_SCRIPT, "--logs-dir", args.logs_dir]
+else:
+    GENERATOR_CMD = [sys.executable, GENERATOR_SCRIPT, args.project_path]
+
+# --- Request handler ---
+
+class LogViewerHandler(http.server.SimpleHTTPRequestHandler):
+    """Extends SimpleHTTPRequestHandler with a /api/refresh-manifest endpoint."""
+
+    def do_GET(self):
+        if self.path == "/api/refresh-manifest":
+            self.handle_refresh_manifest()
+        else:
+            super().do_GET()
+
+    def handle_refresh_manifest(self):
+        """Run recovery + manifest regeneration and return JSON status."""
+        errors = []
+
+        # Step 1: Run recover-session-logs.sh to capture in-flight sessions
+        if os.path.isfile(RECOVERY_SCRIPT):
+            recovery_input = json.dumps({
+                "session_id": "recovery",
+                "transcript_path": "/home/appuser/.claude/projects/-daaf/_.jsonl"
+            })
+            recovery_env = os.environ.copy()
+            recovery_env["CLAUDE_PROJECT_DIR"] = "/daaf"
+            recovery_env["DAAF_SYNC_RECOVERY"] = "1"
+            try:
+                subprocess.run(
+                    ["bash", RECOVERY_SCRIPT],
+                    input=recovery_input,
+                    capture_output=True,
+                    text=True,
+                    timeout=30,
+                    env=recovery_env,
+                )
+            except subprocess.TimeoutExpired:
+                errors.append("Recovery script timed out after 30s")
+            except Exception as e:
+                errors.append("Recovery script error: " + str(e))
+        else:
+            errors.append("Recovery script not found: " + RECOVERY_SCRIPT)
+
+        # Step 2: Regenerate the manifest
+        try:
+            result = subprocess.run(
+                GENERATOR_CMD,
+                capture_output=True,
+                text=True,
+                timeout=60,
+            )
+            if result.returncode != 0:
+                stderr_snippet = (result.stderr or "").strip()[:500]
+                errors.append("Manifest generation failed (exit " + str(result.returncode) + "): " + stderr_snippet)
+        except subprocess.TimeoutExpired:
+            errors.append("Manifest generation timed out after 60s")
+        except Exception as e:
+            errors.append("Manifest generation error: " + str(e))
+
+        # Step 3: Return JSON response
+        if errors:
+            response = {"status": "error", "message": "; ".join(errors)}
+            status_code = 500
+        else:
+            response = {"status": "ok"}
+            status_code = 200
+
+        response_body = json.dumps(response).encode("utf-8")
+        self.send_response(status_code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(response_body)))
+        self.end_headers()
+        self.wfile.write(response_body)
+
+    def log_message(self, format, *log_args):
+        """Suppress noisy per-request logging for static files; log API calls."""
+        if self.path.startswith("/api/"):
+            super().log_message(format, *log_args)
+
+# --- Start server ---
+
+socketserver.TCPServer.allow_reuse_address = True
+httpd = socketserver.TCPServer(("", PORT), LogViewerHandler)
+
+# Startup messages are printed by the calling shell script (generate_log_viewer.sh),
+# which knows the full viewer URL. Only print Ctrl+C reminder here.
+print("  Press Ctrl+C to stop the server.")
+print("")
+
+try:
+    httpd.serve_forever()
+except KeyboardInterrupt:
+    print("\nServer stopped.")
+    httpd.server_close()
diff --git a/scripts/run_with_capture.sh b/scripts/run_with_capture.sh
index 51d059a..5987737 100755
--- a/scripts/run_with_capture.sh
+++ b/scripts/run_with_capture.sh
@@ -1,4 +1,4 @@
-#!/bin/bash
+#!/usr/bin/env bash
 # =============================================================================
 # run_with_capture.sh - Execute Python script with output capture and logging
 # =============================================================================
@@ -16,7 +16,10 @@
 #
 # =============================================================================
 
-set -o pipefail
+# -u: catch unset variables; -o pipefail: detect pipeline failures
+# Deliberately omit -e: this script must capture non-zero exit codes from
+# the Python script it executes, not die on them.
+set -uo pipefail
 
 SCRIPT_PATH="$1"
 
@@ -50,12 +53,12 @@ echo "Started: $TIMESTAMP"
 echo "============================================================"
 echo ""
 
-# Execute with timing
-START_TIME=$(date +%s.%N)
+# Execute with timing (integer seconds — avoids bc dependency and macOS date +%N incompatibility)
+START_TIME=$(date +%s)
 python3 "$SCRIPT_PATH" 2>&1 | tee "$TEMP_LOG"
 EXIT_CODE=${PIPESTATUS[0]}
-END_TIME=$(date +%s.%N)
-DURATION=$(echo "$END_TIME - $START_TIME" | bc)
+END_TIME=$(date +%s)
+DURATION=$((END_TIME - START_TIME))
 
 echo ""
 echo "============================================================"
diff --git a/tests/bash/backup_daaf.bats b/tests/bash/backup_daaf.bats
new file mode 100755
index 0000000..ddf2d2c
--- /dev/null
+++ b/tests/bash/backup_daaf.bats
@@ -0,0 +1,525 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for backup_daaf.sh -- DAAF Backup Utility
+# ============================================================================
+# Key testable logic: date-suffix versioning (a/b/c), preflight checks,
+# volume existence validation.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    # backup_daaf.sh does not require docker-compose.yml
+}
+
+teardown() {
+    common_teardown
+}
+
+# --- Syntax ---
+
+@test "backup_daaf.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_success
+}
+
+# --- Preflight: missing Docker ---
+
+@test "backup_daaf.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "backup_daaf.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- Preflight: volume not found ---
+
+@test "backup_daaf.sh fails when Docker volume does not exist" {
+    MOCK_DOCKER_VOLUME_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "not found"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "backup_daaf.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Date-suffix versioning logic ---
+
+@test "backup_daaf.sh generates 'a' suffix when base backup exists" {
+    # Create a directory matching today's date backup name
+    local today
+    today=$(date +%Y-%m-%d)
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+
+    # Mock volume inspect to succeed, mock docker run for scan
+    # Scan now outputs 4 lines: file count, du -sk, du -sh, logical KB
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n512\t/source\n500K\t/source\n500'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    # Should show the suffixed backup name
+    assert_output --partial "${today}a_daaf_backup"
+}
+
+@test "backup_daaf.sh generates 'b' suffix when 'a' also exists" {
+    local today
+    today=$(date +%Y-%m-%d)
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+    mkdir -p "${TEST_DIR}/${today}a_daaf_backup"
+
+    # Scan now outputs 4 lines: file count, du -sk, du -sh, logical KB
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n512\t/source\n500K\t/source\n500'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "${today}b_daaf_backup"
+}
+
+# --- Banner display ---
+
+@test "backup_daaf.sh displays the DAAF Backup banner" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "DAAF Backup"
+}
+
+# --- Structural: safety features present ---
+
+@test "backup_daaf.sh contains disk space pre-check" {
+    run grep -c "Insufficient disk space" "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_success
+}
+
+@test "backup_daaf.sh contains size-based verification" {
+    run grep -c "Size verification" "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_success
+}
+
+@test "backup_daaf.sh uses cp -a (not cp -r)" {
+    run grep -c "cp -a /source" "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_success
+    run grep -c "cp -r /source" "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+}
+
+# --- Date-suffix versioning edge cases ---
+
+@test "backup: suffix picks first available letter sequentially" {
+    # Create base and 'a' -- script should pick 'b' (next in sequence)
+    local today
+    today=$(date +%Y-%m-%d)
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+    mkdir -p "${TEST_DIR}/${today}a_daaf_backup"
+    # Also create 'c' to prove the script picks 'b' (first gap), not 'd'
+    mkdir -p "${TEST_DIR}/${today}c_daaf_backup"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n512\t/source\n500K\t/source\n500'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "${today}b_daaf_backup"
+}
+
+@test "backup: 26th backup of the day reaches suffix 'z'" {
+    local today
+    today=$(date +%Y-%m-%d)
+    # Create base backup
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+    # Create suffixes a through y (25 directories)
+    for i in $(seq 0 24); do
+        suffix=$(printf "\\$(printf '%03o' $((97 + i)))")
+        mkdir -p "${TEST_DIR}/${today}${suffix}_daaf_backup"
+    done
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n512\t/source\n500K\t/source\n500'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "${today}z_daaf_backup"
+}
+
+@test "backup: errors when all 26 suffixes are exhausted" {
+    local today
+    today=$(date +%Y-%m-%d)
+    # Create base backup
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+    # Create all 26 suffixed directories (a through z)
+    for i in $(seq 0 25); do
+        suffix=$(printf "\\$(printf '%03o' $((97 + i)))")
+        mkdir -p "${TEST_DIR}/${today}${suffix}_daaf_backup"
+    done
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "Too many backups"
+}
+
+# --- Disk space checks ---
+
+@test "backup: fails when disk space is insufficient" {
+    # Mock df to report very little available space
+    df() {
+        if [ "$1" = "-P" ]; then
+            printf "Filesystem     1024-blocks    Used Available Capacity Mounted on\n"
+            printf "/dev/sda1       100000000 99999990       10 100%% /\n"
+        else
+            builtin command df "$@"
+        fi
+    }
+    export -f df
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    # Report volume size as 10000 KB (10 MB) -- much larger than 10 bytes available
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n10000\t/source\n10M\t/source\n9800'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "Insufficient disk space"
+}
+
+@test "backup: reports required vs available space on disk space failure" {
+    df() {
+        if [ "$1" = "-P" ]; then
+            printf "Filesystem     1024-blocks    Used Available Capacity Mounted on\n"
+            printf "/dev/sda1       100000000 99999990       10 100%% /\n"
+        else
+            builtin command df "$@"
+        fi
+    }
+    export -f df
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n10000\t/source\n10M\t/source\n9800'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    # Should report both required and available MB values
+    assert_output --partial "Required:"
+    assert_output --partial "Available:"
+}
+
+@test "backup: passes disk space check when sufficient space available" {
+    df() {
+        if [ "$1" = "-P" ]; then
+            printf "Filesystem     1024-blocks    Used Available Capacity Mounted on\n"
+            printf "/dev/sda1       100000000 50000000 50000000  50%% /\n"
+        else
+            builtin command df "$@"
+        fi
+    }
+    export -f df
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    # Small volume (512 KB) -- plenty of space
+    MOCK_DOCKER_RUN_OUTPUT=$'100\n512\t/source\n500K\t/source\n500'
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    # Should pass the disk space check (no "Insufficient" error)
+    refute_output --partial "Insufficient disk space"
+}
+
+# --- Integrity verification: size mismatch ---
+
+@test "backup: warns when backup size differs from source by more than 1 percent" {
+    export DAAF_NESTED=1
+
+    # Custom docker mock: scan reports 9800 logical KB source; copy creates a
+    # small file in the backup dir so FILE_COUNT > 0 and size verification triggers.
+    # The backup file is ~1 KB vs 9800 KB source -- well beyond 1% tolerance.
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"cp -a"* ]]; then
+                    # Extract the host-side bind-mount path before ":/dest"
+                    local dest_dir=""
+                    for arg in "$@"; do
+                        if [[ "${arg}" == *":/dest"* ]]; then
+                            dest_dir="${arg%%:/dest*}"
+                            break
+                        fi
+                    done
+                    if [ -n "${dest_dir}" ]; then
+                        mkdir -p "${dest_dir}"
+                        # Create a file with ~1 KB of content (far less than 9800 KB source)
+                        dd if=/dev/zero of="${dest_dir}/mock_file" bs=1024 count=1 2>/dev/null
+                    fi
+                    return 0
+                else
+                    # Scan call: file count, du -sk, du -sh, logical KB
+                    printf '10\n10000\t/source\n10M\t/source\n9800\n'
+                    return 0
+                fi
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "WARNING"
+    assert_output --partial "size mismatch"
+}
+
+# --- File count verification ---
+
+@test "backup: reports file count in output on success" {
+    export DAAF_NESTED=1
+
+    # Custom docker mock: copy step creates files so FILE_COUNT > 0
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"cp -a"* ]]; then
+                    local dest_dir=""
+                    for arg in "$@"; do
+                        if [[ "${arg}" == *":/dest"* ]]; then
+                            dest_dir="${arg%%:/dest*}"
+                            break
+                        fi
+                    done
+                    if [ -n "${dest_dir}" ]; then
+                        mkdir -p "${dest_dir}"
+                        touch "${dest_dir}/file1" "${dest_dir}/file2"
+                    fi
+                    return 0
+                else
+                    printf '5\n512\t/source\n500K\t/source\n500\n'
+                    return 0
+                fi
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "files copied"
+}
+
+# --- Core behavior ---
+
+@test "backup: creates backup directory with date-based name" {
+    export DAAF_NESTED=1
+    local today
+    today=$(date +%Y-%m-%d)
+
+    # Custom docker mock: copy step creates a file so the script reaches success
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"cp -a"* ]]; then
+                    local dest_dir=""
+                    for arg in "$@"; do
+                        if [[ "${arg}" == *":/dest"* ]]; then
+                            dest_dir="${arg%%:/dest*}"
+                            break
+                        fi
+                    done
+                    if [ -n "${dest_dir}" ]; then
+                        mkdir -p "${dest_dir}"
+                        touch "${dest_dir}/file1"
+                    fi
+                    return 0
+                else
+                    printf '5\n512\t/source\n500K\t/source\n500\n'
+                    return 0
+                fi
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_output --partial "${today}_daaf_backup"
+    assert_output --partial "Backup complete"
+}
+
+@test "backup: scan failure exits with error" {
+    MOCK_DOCKER_VOLUME_EXIT=0
+    # docker run for scanning fails
+    MOCK_DOCKER_RUN_EXIT=1
+    MOCK_DOCKER_RUN_OUTPUT=""
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Could not scan"
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "backup_daaf.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_success
+}
+
+@test "backup_daaf.sh: dry-run produces DRY-RUN markers" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/backup_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "[DRY-RUN]"
+}
+
+@test "backup_daaf.sh: dry-run shows backup summary" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/backup_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "Would create backup at"
+}
+
+# =========================================================================
+# --- Error paths ---
+# =========================================================================
+
+@test "backup: copy failure with zero files exits with error" {
+    export DAAF_NESTED=1
+
+    # Custom docker mock: scan succeeds, copy fails (non-zero exit), no files created
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"cp -a"* ]]; then
+                    # Copy fails, creates no files
+                    return 1
+                else
+                    # Scan output: file count, du -sk, du -sh, logical KB
+                    printf '50\n512\t/source\n500K\t/source\n500\n'
+                    return 0
+                fi
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+}
+
+@test "backup: copy partially succeeds with non-zero exit but files copied shows warning" {
+    export DAAF_NESTED=1
+
+    # Custom docker mock: copy returns non-zero but creates files
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"cp -a"* ]]; then
+                    # Extract the host-side bind-mount path before ":/dest"
+                    local dest_dir=""
+                    for arg in "$@"; do
+                        if [[ "${arg}" == *":/dest"* ]]; then
+                            dest_dir="${arg%%:/dest*}"
+                            break
+                        fi
+                    done
+                    if [ -n "${dest_dir}" ]; then
+                        mkdir -p "${dest_dir}"
+                        touch "${dest_dir}/file1" "${dest_dir}/file2" "${dest_dir}/file3"
+                    fi
+                    # Non-zero exit (partial failure)
+                    return 1
+                else
+                    # Scan output
+                    printf '5\n512\t/source\n500K\t/source\n500\n'
+                    return 0
+                fi
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    # Should succeed (files were copied) but note the warnings
+    assert_output --partial "warnings"
+    assert_output --partial "files were transferred"
+}
+
+@test "backup: volume scan outputs unexpected format triggers error" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=0
+
+    # Custom docker mock: scan returns garbage output
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            run)
+                # Return unexpected format
+                printf 'unexpected_garbage_output\n'
+                return 1
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/backup_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+}
diff --git a/tests/bash/install.bats b/tests/bash/install.bats
new file mode 100755
index 0000000..ea2d189
--- /dev/null
+++ b/tests/bash/install.bats
@@ -0,0 +1,503 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for install.sh -- DAAF One-Line Installer
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    mock_curl
+    # install.sh does NOT require docker-compose.yml to exist beforehand
+    # (it creates the install directory itself)
+}
+
+teardown() {
+    common_teardown
+}
+
+# --- Syntax ---
+
+@test "install.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/install.sh"
+    assert_success
+}
+
+# --- Preflight: missing Docker ---
+
+@test "install.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "install.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "install.sh suppresses pause trap when DAAF_NESTED=1" {
+    # With DAAF_NESTED=1, the script should not set the EXIT trap
+    # for read -r -p. We test this indirectly: the script will fail
+    # (mocked docker info succeeds but curl creates empty files which
+    # won't build), but the important thing is it does not hang on
+    # "Press Enter".
+    export DAAF_NESTED=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # Should not contain the pause prompt
+    refute_output --partial "Press Enter"
+}
+
+# --- Existing installation detection ---
+
+@test "install.sh detects existing installation and warns" {
+    # Create the install directory with a compose file
+    mkdir -p "${TEST_DIR}/daaf-docker"
+    create_fake_compose_file "${TEST_DIR}/daaf-docker"
+    # Mock docker volume inspect to succeed (volume exists)
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+    # Run from a directory where daaf-docker/ exists
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "WARNING"
+    assert_output --partial "existing DAAF installation"
+}
+
+# --- Download file list ---
+
+@test "install.sh attempts to download required files" {
+    export DAAF_NESTED=1
+    # curl mock creates empty files; compose build will fail but we can
+    # check that it gets past the download step
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # The script should have tried to download and then failed at build
+    assert_failure
+    assert_output --partial "Downloading"
+}
+
+# --- Branch override ---
+
+@test "install.sh respects DAAF_BRANCH environment variable" {
+    export DAAF_BRANCH="dev"
+    export DAAF_NESTED=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_output --partial "Branch: dev"
+}
+
+# --- Fresh install proceeds when no compose file exists ---
+
+@test "install.sh proceeds with downloads when no prior installation exists" {
+    # No compose file in daaf-docker/ -- fresh install path
+    export DAAF_NESTED=1
+    # Build will fail, but downloads should be attempted
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # Should reach the download step (no "existing installation" block)
+    assert_output --partial "Downloading"
+    refute_output --partial "existing DAAF installation"
+}
+
+# --- Incomplete installation detection ---
+
+@test "install.sh proceeds when compose file exists but volume does not" {
+    # Compose file present but volume inspect fails -- incomplete install
+    mkdir -p "${TEST_DIR}/daaf-docker"
+    create_fake_compose_file "${TEST_DIR}/daaf-docker"
+    MOCK_DOCKER_VOLUME_EXIT=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    export DAAF_NESTED=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # Should note incomplete install and continue
+    assert_output --partial "previous install attempt"
+    assert_output --partial "incomplete"
+    assert_output --partial "Downloading"
+}
+
+# --- DAAF_FORCE_REINSTALL bypasses existing check ---
+
+@test "install.sh proceeds when DAAF_FORCE_REINSTALL=1 despite existing installation" {
+    mkdir -p "${TEST_DIR}/daaf-docker"
+    create_fake_compose_file "${TEST_DIR}/daaf-docker"
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    export DAAF_FORCE_REINSTALL=1
+    export DAAF_NESTED=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # Should note force reinstall and proceed (not block)
+    assert_output --partial "DAAF_FORCE_REINSTALL"
+    assert_output --partial "Downloading"
+    refute_output --partial "To update DAAF instead"
+}
+
+# --- Default branch is 'main' ---
+
+@test "install.sh defaults to branch 'main' when DAAF_BRANCH is unset" {
+    unset DAAF_BRANCH
+    export DAAF_NESTED=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_output --partial "Branch: main"
+}
+
+# --- Download failure exits non-zero ---
+
+@test "install.sh exits with error when downloads fail" {
+    export DAAF_NESTED=1
+    MOCK_CURL_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to download"
+}
+
+# --- Download file list coverage ---
+
+@test "install.sh downloads all required lifecycle scripts" {
+    # Override curl to log the URLs it receives
+    curl() {
+        local outfile=""
+        local url=""
+        local args=("$@")
+        for ((i=0; i<${#args[@]}; i++)); do
+            case "${args[$i]}" in
+                -o) outfile="${args[$((i+1))]}" ;;
+                http*) url="${args[$i]}" ;;
+            esac
+        done
+        echo "CURL_URL: ${url}" >> "${TEST_DIR}/curl_log.txt"
+        if [ -n "${outfile}" ]; then
+            touch "${outfile}"
+        fi
+        return 0
+    }
+    export -f curl
+
+    export DAAF_NESTED=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+
+    # Verify all expected files were requested
+    [ -f "${TEST_DIR}/curl_log.txt" ]
+    run grep -c "CURL_URL:" "${TEST_DIR}/curl_log.txt"
+    # Should download: Dockerfile, docker-compose.yml, run_daaf.sh,
+    # backup_daaf.sh, rebuild_daaf.sh, update_daaf.sh, view_logs.sh, environment_settings_example.txt
+    [ "$output" -ge 8 ]
+
+    run cat "${TEST_DIR}/curl_log.txt"
+    assert_output --partial "Dockerfile"
+    assert_output --partial "docker-compose.yml"
+    assert_output --partial "run_daaf.sh"
+    assert_output --partial "backup_daaf.sh"
+    assert_output --partial "update_daaf.sh"
+    assert_output --partial "environment_settings_example.txt"
+}
+
+# --- Download URLs use correct path prefix ---
+
+@test "install.sh download URLs contain scripts/host/ prefix for lifecycle scripts" {
+    curl() {
+        local url=""
+        local outfile=""
+        local args=("$@")
+        for ((i=0; i<${#args[@]}; i++)); do
+            case "${args[$i]}" in
+                -o) outfile="${args[$((i+1))]}" ;;
+                http*) url="${args[$i]}" ;;
+            esac
+        done
+        echo "${url}" >> "${TEST_DIR}/curl_urls.txt"
+        if [ -n "${outfile}" ]; then
+            touch "${outfile}"
+        fi
+        return 0
+    }
+    export -f curl
+
+    export DAAF_NESTED=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+
+    [ -f "${TEST_DIR}/curl_urls.txt" ]
+    # All .sh and environment_settings_example.txt downloads should use scripts/host/ prefix
+    run grep "scripts/host/" "${TEST_DIR}/curl_urls.txt"
+    assert_success
+}
+
+# --- Creates daaf-docker directory ---
+
+@test "install.sh creates daaf-docker directory" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # The directory should have been created
+    [ -d "${TEST_DIR}/daaf-docker" ]
+}
+
+# --- Build step invoked ---
+
+@test "install.sh invokes docker compose build" {
+    export DAAF_NESTED=1
+    # Let build succeed, but up fail so we don't reach later steps
+    MOCK_DOCKER_COMPOSE_EXIT=0
+    # Actually: compose mock returns same exit for build and up.
+    # We need compose to eventually stop. Let exec fail for the readiness check.
+    MOCK_DOCKER_EXEC_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_output --partial "Building Docker image"
+}
+
+# --- Readiness check looks for CLAUDE.md ---
+
+@test "install.sh verifies CLAUDE.md exists in container" {
+    export DAAF_NESTED=1
+    # exec mock returns success -- test -f /daaf/CLAUDE.md passes
+    MOCK_DOCKER_EXEC_EXIT=0
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # If readiness + clone + verify all succeed, should reach completion
+    assert_output --partial "Installation complete"
+}
+
+# --- Existing installation suggests update_daaf.sh ---
+
+@test "install.sh suggests update_daaf.sh when blocking on existing installation" {
+    mkdir -p "${TEST_DIR}/daaf-docker"
+    create_fake_compose_file "${TEST_DIR}/daaf-docker"
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "update_daaf.sh"
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "install.sh: dry-run completes successfully" {
+    cd "${TEST_DIR}"
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_success
+    # Clean up the daaf-docker directory created by install.sh
+    rm -r "${TEST_DIR}/daaf-docker" 2>/dev/null || true
+}
+
+@test "install.sh: dry-run produces DRY-RUN markers" {
+    cd "${TEST_DIR}"
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/install.sh" 2>&1
+    assert_success
+    assert_output --partial "[DRY-RUN]"
+    # Clean up the daaf-docker directory created by install.sh
+    rm -r "${TEST_DIR}/daaf-docker" 2>/dev/null || true
+}
+
+# =========================================================================
+# Error paths
+# =========================================================================
+
+@test "install.sh: fails when docker compose build fails" {
+    export DAAF_NESTED=1
+    # Custom docker mock: volume inspect fails (no existing install),
+    # compose build returns non-zero
+    docker() {
+        case "$*" in
+            info*)   return 0 ;;
+            *volume*) return 1 ;;
+            *compose*build*) return 1 ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    mock_curl
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "build failed"
+}
+
+@test "install.sh: fails when docker compose up -d fails" {
+    export DAAF_NESTED=1
+    # Custom docker mock: build succeeds, up fails
+    docker() {
+        case "$*" in
+            info*)   return 0 ;;
+            *volume*) return 1 ;;
+            *compose*build*) return 0 ;;
+            *compose*up*) return 1 ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    mock_curl
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start"
+}
+
+@test "install.sh: fails on container readiness timeout" {
+    export DAAF_NESTED=1
+    # Custom docker mock: build and up succeed, exec always fails (readiness never achieved)
+    docker() {
+        case "$*" in
+            info*)   return 0 ;;
+            *volume*) return 1 ;;
+            *compose*build*) return 0 ;;
+            *compose*up*) return 0 ;;
+            *compose*exec*) return 1 ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    mock_curl
+    # Override MAX_RETRIES via the script's sleep loop -- we can't override
+    # the variable directly since the script sets it. Instead, trust that
+    # the loop will exit after MAX_RETRIES. To keep the test fast, override
+    # sleep to be a no-op.
+    sleep() { true; }
+    export -f sleep
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "did not become ready"
+}
+
+@test "install.sh: fails when curl download fails" {
+    export DAAF_NESTED=1
+    MOCK_CURL_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to download"
+}
+
+@test "install.sh: fails when git clone into container fails" {
+    export DAAF_NESTED=1
+    # Custom docker mock: build/up/readiness succeed, but exec for git clone fails
+    docker() {
+        case "$*" in
+            info*)   return 0 ;;
+            *volume*) return 1 ;;
+            *compose*build*) return 0 ;;
+            *compose*up*) return 0 ;;
+            *compose*exec*git*clone*) return 1 ;;
+            *compose*exec*) return 0 ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    mock_curl
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to clone"
+}
+
+@test "install.sh: fails when CLAUDE.md verification fails post-install" {
+    export DAAF_NESTED=1
+    # Custom docker mock: everything succeeds except the final test -f check
+    docker() {
+        case "$*" in
+            info*)   return 0 ;;
+            *volume*) return 1 ;;
+            *compose*build*) return 0 ;;
+            *compose*up*) return 0 ;;
+            *compose*exec*test*-f*) return 1 ;;
+            *compose*exec*) return 0 ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    mock_curl
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "CLAUDE.md was not found"
+}
+
+@test "install.sh: force reinstall proceeds with existing volume" {
+    mkdir -p "${TEST_DIR}/daaf-docker"
+    create_fake_compose_file "${TEST_DIR}/daaf-docker"
+    export DAAF_FORCE_REINSTALL=1
+    export DAAF_NESTED=1
+    # Let it proceed past existing check and then fail at build
+    # (to confirm it did NOT block on existing installation)
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    # Should have proceeded past the existing-installation check
+    assert_output --partial "DAAF_FORCE_REINSTALL"
+    assert_output --partial "Downloading"
+    # Should NOT contain the blocking message
+    refute_output --partial "To update DAAF instead"
+}
+
+@test "install.sh: existing installation detected without force flag exits 1" {
+    mkdir -p "${TEST_DIR}/daaf-docker"
+    create_fake_compose_file "${TEST_DIR}/daaf-docker"
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "WARNING"
+    assert_output --partial "existing DAAF installation"
+}
+
+@test "install.sh: fails when copy repo files into container fails" {
+    export DAAF_NESTED=1
+    # Custom docker mock: git clone succeeds, but bash -c cp fails
+    docker() {
+        case "$*" in
+            info*)   return 0 ;;
+            *volume*) return 1 ;;
+            *compose*build*) return 0 ;;
+            *compose*up*) return 0 ;;
+            *compose*exec*bash*-c*) return 1 ;;
+            *compose*exec*) return 0 ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    mock_curl
+    cd "${TEST_DIR}"
+    run bash "${REPO_ROOT}/scripts/host/install.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to copy repository files"
+}
diff --git a/tests/bash/migrate_daaf.bats b/tests/bash/migrate_daaf.bats
new file mode 100755
index 0000000..0232523
--- /dev/null
+++ b/tests/bash/migrate_daaf.bats
@@ -0,0 +1,964 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for migrate_daaf.sh -- DAAF Migration Script
+# ============================================================================
+# Key testable logic: era detection (clone vs ZIP), preflight checks,
+# helper functions (container_git, prompt_choice), idempotency markers.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    mock_curl
+}
+
+teardown() {
+    common_teardown
+    # Clean up lock directories that may be left by lock contention tests
+    rmdir /tmp/daaf-migrate.lock.d 2>/dev/null || true
+}
+
+# --- Syntax ---
+
+@test "migrate_daaf.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+}
+
+# --- Preflight: missing Docker ---
+
+@test "migrate_daaf.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "migrate_daaf.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- Preflight: volume not found ---
+
+@test "migrate_daaf.sh fails when Docker volume does not exist" {
+    MOCK_DOCKER_VOLUME_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "not found"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "migrate_daaf.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Banner display ---
+
+@test "migrate_daaf.sh displays the DAAF Migration banner" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_output --partial "DAAF Migration"
+}
+
+# --- Helper functions defined ---
+
+@test "migrate_daaf.sh defines prompt_choice helper function" {
+    run grep -c "prompt_choice()" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate_daaf.sh defines container_git helper function" {
+    run grep -c "container_git()" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate_daaf.sh defines container_git_verbose helper function" {
+    run grep -c "container_git_verbose()" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate_daaf.sh defines container_exec helper function" {
+    run grep -c "container_exec()" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- ERR trap defined ---
+
+@test "migrate_daaf.sh defines an ERR trap for cleanup" {
+    run grep -c "trap cleanup_on_error ERR" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Era detection references ---
+
+@test "migrate_daaf.sh references both Era 1 and Era 2 paths" {
+    run grep -c "ERA.*PATH" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 2 ]
+}
+
+# --- DAAF_BRANCH override ---
+
+@test "migrate_daaf.sh supports DAAF_BRANCH environment variable" {
+    run grep -c "DAAF_BRANCH" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Idempotency check ---
+
+@test "migrate_daaf.sh claims to be idempotent in its header" {
+    run grep -c "idempotent" "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Creates host directory when not in daaf-docker ---
+
+@test "migrate_daaf.sh creates daaf-docker directory when docker-compose.yml is missing" {
+    # When docker-compose.yml does not exist in cwd, the script creates daaf-docker/
+    # The script will fail later at volume check or download, but it should
+    # announce the directory creation
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_CURL_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_output --partial "daaf-docker"
+}
+
+# ============================================================================
+# Behavioral tests -- sourced functions
+# ============================================================================
+# Source the script in test mode to access helper functions directly.
+# DAAF_TEST_MODE=1 causes the script to return after defining functions,
+# skipping the main execution body.
+
+# --- container_git behavioral tests ---
+
+@test "migrate: container_git executes git in container" {
+    # Source in test mode to get the functions
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    CONTAINER_NAME="test-container"
+
+    # Mock docker to record calls and return empty output
+    docker() {
+        echo "DOCKER_CALLED: $*"
+        return 0
+    }
+    export -f docker
+
+    run container_git status
+    assert_success
+    assert_output --partial "DOCKER_CALLED:"
+    assert_output --partial "test-container"
+    assert_output --partial "git -C /daaf status"
+}
+
+@test "migrate: container_git suppresses stderr" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    CONTAINER_NAME="test-container"
+
+    # Mock docker to emit both stdout and stderr
+    docker() {
+        echo "stdout-line"
+        echo "stderr-line" >&2
+        return 0
+    }
+    export -f docker
+
+    # container_git redirects stderr to /dev/null, so only stdout should appear
+    run container_git status
+    assert_success
+    assert_output --partial "stdout-line"
+    refute_output --partial "stderr-line"
+}
+
+@test "migrate: container_git strips carriage returns" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    CONTAINER_NAME="test-container"
+
+    # Mock docker to return output with \r (Windows-style line endings)
+    docker() {
+        printf "line-with-cr\r\n"
+        return 0
+    }
+    export -f docker
+
+    run container_git status
+    assert_success
+    # Output should not contain \r
+    [[ "${output}" != *$'\r'* ]]
+    assert_output --partial "line-with-cr"
+}
+
+# --- container_git_verbose behavioral tests ---
+
+@test "migrate: container_git_verbose preserves stderr" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    CONTAINER_NAME="test-container"
+
+    # Mock docker to emit stderr
+    docker() {
+        echo "stdout-output"
+        echo "verbose-stderr" >&2
+        return 0
+    }
+    export -f docker
+
+    # container_git_verbose does NOT redirect stderr to /dev/null
+    # Use run with 3>&1 to capture stderr in output
+    run bash -c '
+        CONTAINER_NAME="test-container"
+        docker() {
+            echo "stdout-output"
+            echo "verbose-stderr" >&2
+            return 0
+        }
+        export -f docker
+        source "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh" 2>/dev/null
+        container_git_verbose status 2>&1
+    '
+    assert_success
+    assert_output --partial "verbose-stderr"
+}
+
+# --- container_exec behavioral tests ---
+
+@test "migrate: container_exec runs arbitrary command in container" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    CONTAINER_NAME="test-container"
+
+    docker() {
+        echo "EXEC_CALLED: $*"
+        return 0
+    }
+    export -f docker
+
+    run container_exec ls -la /daaf
+    assert_success
+    assert_output --partial "EXEC_CALLED:"
+    assert_output --partial "test-container"
+    assert_output --partial "ls -la /daaf"
+}
+
+# --- prompt_choice behavioral tests ---
+# Note: IS_INTERACTIVE is false inside `bash -c` subshells (no /dev/tty),
+# which triggers the non-interactive auto-select path. To test the
+# interactive read path, we define a wrapper that bypasses the check.
+
+@test "migrate: prompt_choice auto-selects first choice in non-interactive mode" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh" 2>/dev/null
+        echo "ignored" | prompt_choice "Choose [y/n]: " "y n"
+    '
+    assert_success
+    assert_output --partial "y"
+    assert_output --partial "Non-interactive"
+}
+
+@test "migrate: prompt_choice reads input interactively when stdin is a TTY" {
+    # Override prompt_choice to remove the TTY check, simulating interactive mode
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh" 2>/dev/null
+        prompt_choice() {
+            local prompt_text="$1"
+            local valid_choices="$2"
+            local choice=""
+            read -r choice
+            choice=$(echo "${choice}" | tr "[:upper:]" "[:lower:]")
+            if echo "${valid_choices}" | grep -qw "${choice}"; then
+                echo "${choice}"
+            fi
+        }
+        echo "y" | prompt_choice "Choose [y/n]: " "y n"
+    '
+    assert_success
+    assert_output --partial "y"
+}
+
+# ============================================================================
+# Era detection pattern tests
+# ============================================================================
+# These test the patterns used by the inline era detection code -- verifying
+# that the git commands used for detection produce distinguishable output
+# for each era type.
+
+@test "migrate: no remote indicates Era 1 pattern (ZIP install)" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    # Override container_git to simulate no remote configured
+    container_git() {
+        case "$1" in
+            remote) echo "" ;;  # No remote URL → empty output
+            *) echo "" ;;
+        esac
+        return 0
+    }
+
+    # Simulate the era detection logic from the script (lines 405-426):
+    # ORIGIN_URL=$(container_git remote get-url origin 2>/dev/null || true)
+    ORIGIN_URL=$(container_git remote get-url origin 2>/dev/null || true)
+
+    # When ORIGIN_URL is empty, the script goes to DETECTED_ERA="2" (ZIP install)
+    [ -z "${ORIGIN_URL}" ]
+}
+
+@test "migrate: remote with known repo URL indicates Era 2 pattern (clone)" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    # Override container_git to simulate a remote pointing to the official repo
+    container_git() {
+        case "$1" in
+            remote) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+            *) echo "" ;;
+        esac
+        return 0
+    }
+
+    ORIGIN_URL=$(container_git remote get-url origin 2>/dev/null || true)
+
+    # When ORIGIN_URL is non-empty AND contains the repo name, era is "1" (clone)
+    [ -n "${ORIGIN_URL}" ]
+    echo "${ORIGIN_URL}" | grep -qi "DAAF-Contribution-Community/daaf"
+}
+
+@test "migrate: idempotency marker detected via root commit parent check" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    # The script checks if the initial commit already has a parent (line 567-568):
+    #   INITIAL_PARENT_COUNT=$(container_git_verbose cat-file -p "$INITIAL_COMMIT" | grep -c '^parent ')
+    # If > 0, graft is already in place → skip graft step.
+
+    # Simulate a commit that already has a parent (graft already applied)
+    FAKE_CAT_FILE_OUTPUT="tree abc123
+parent def456
+author Test <test@test> 1700000000 +0000
+committer Test <test@test> 1700000000 +0000
+
+Initial commit"
+
+    INITIAL_PARENT_COUNT=$(echo "${FAKE_CAT_FILE_OUTPUT}" | grep -c '^parent ' || echo "0")
+
+    # Parent count > 0 means graft is in place → idempotency check passes
+    [ "${INITIAL_PARENT_COUNT}" -gt 0 ]
+}
+
+@test "migrate: corrupted volume (no .git) detected by container_exec test" {
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    CONTAINER_NAME="test-container"
+
+    # Override container_exec to fail for the CLAUDE.md existence check (line 385)
+    # In the script: container_exec test -f /daaf/CLAUDE.md
+    container_exec() {
+        return 1  # File not found → volume is corrupted/missing
+    }
+
+    # Verify the pattern: failed test returns non-zero
+    run container_exec test -f /daaf/CLAUDE.md
+    assert_failure
+}
+
+# ============================================================================
+# Safety tests
+# ============================================================================
+
+@test "migrate: locking uses portable mkdir (no flock)" {
+    # The script should use mkdir for locking (portable across Linux/macOS/Git Bash)
+    # and should NOT use flock (not available on macOS)
+    run grep -c 'mkdir.*LOCK' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+
+    run grep -c 'flock' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    # grep returns exit 1 when no matches -- that is the expected outcome
+    assert_failure
+}
+
+@test "migrate: ERR trap registered for cleanup after sourcing" {
+    # After sourcing in test mode, verify the ERR trap was set
+    # (we clear it in tests, but the script should have set it)
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh" 2>/dev/null
+        trap -p ERR
+    '
+    assert_success
+    assert_output --partial "cleanup_on_error"
+}
+
+@test "migrate: backup runs before destructive operations" {
+    # Verify that backup_daaf.sh is called (section 3) before the era detection
+    # and graft operations (sections 5-6). Check that "backup_daaf" appears in
+    # the script before "replace --graft" (the destructive graft operation).
+    local backup_line
+    local graft_line
+    backup_line=$(grep -n 'backup_daaf' "${REPO_ROOT}/scripts/host/migrate_daaf.sh" | head -1 | cut -d: -f1)
+    graft_line=$(grep -n 'replace --graft' "${REPO_ROOT}/scripts/host/migrate_daaf.sh" | head -1 | cut -d: -f1)
+
+    # Both patterns must exist
+    [ -n "${backup_line}" ]
+    [ -n "${graft_line}" ]
+
+    # Backup must come before the graft operation
+    [ "${backup_line}" -lt "${graft_line}" ]
+}
+
+# ============================================================================
+# Era-specific file marker tests
+# ============================================================================
+# These verify the migration script's era detection output and the file-level
+# markers that distinguish each installation era. Complements the integration
+# tests in ci-integration.yml which test against real Docker containers.
+
+@test "migrate: script emits 'clone-based' for Era 1 detection" {
+    # The script must output the Era 1 detection string
+    run grep -c 'clone-based installation' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate: script emits 'ZIP-based' for Era 2 detection" {
+    # The script must output the Era 2 detection string
+    run grep -c 'ZIP-based installation' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate: Era 1 path exists (section 6a)" {
+    # The script must have a code path for ERA 1 (clone-based)
+    run grep -c 'ERA 1 PATH' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate: Era 2 path exists (section 6b) with graft" {
+    # The script must have a code path for ERA 2 (ZIP-based) that includes grafting
+    run grep -c 'ERA 2 PATH' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+
+    # The Era 2 path must include the graft operation
+    run grep -c 'replace --graft' "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "migrate: Era 2 detection triggers when ORIGIN_URL is empty" {
+    # Simulate the era detection logic: when container_git remote returns
+    # empty string, the script should set DETECTED_ERA="2"
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    container_git() { echo ""; return 0; }
+    ORIGIN_URL=$(container_git remote get-url origin 2>/dev/null || true)
+
+    # Empty ORIGIN_URL → Era 2
+    [ -z "${ORIGIN_URL}" ]
+}
+
+@test "migrate: Era 1 detection triggers when ORIGIN_URL has repo name" {
+    # Simulate the era detection logic: when container_git remote returns
+    # the official repo URL, the script should set DETECTED_ERA="1"
+    DAAF_TEST_MODE=1 source "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    trap - ERR
+    set +eu
+
+    container_git() { echo "https://github.com/DAAF-Contribution-Community/daaf.git"; return 0; }
+    ORIGIN_URL=$(container_git remote get-url origin 2>/dev/null || true)
+
+    # Non-empty ORIGIN_URL with repo name → Era 1
+    [ -n "${ORIGIN_URL}" ]
+    echo "${ORIGIN_URL}" | grep -qi "DAAF-Contribution-Community/daaf"
+}
+
+@test "migrate: dry-run output includes era detection for simulated Era 1" {
+    # In dry-run mode, the script simulates an Era 1 installation.
+    # Verify the output includes the era detection string.
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "clone-based installation"
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+@test "migrate_daaf.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh"
+    assert_success
+}
+
+@test "migrate_daaf.sh: dry-run produces DRY-RUN markers" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "[DRY-RUN]"
+}
+
+@test "migrate_daaf.sh: dry-run completes migration" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/migrate_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "Migration complete"
+}
+
+# ============================================================================
+# Integrated state-machine tests
+# ============================================================================
+# These test the MAIN ORCHESTRATION flow. The script is run as a full process
+# with carefully crafted docker + curl mock responses that dispatch on the
+# argument string.
+
+# --- Helper: setup for integrated tests ---
+setup_migrate_integrated() {
+    export DAAF_NESTED=1
+    # Create docker-compose.yml so the script uses current dir as HOST_DIR
+    create_fake_compose_file
+    # Create stub backup_daaf.sh that exits cleanly (called in section 3)
+    cat > "${TEST_DIR}/backup_daaf.sh" <<'SH'
+#!/usr/bin/env bash
+echo "Backup completed (stub)"
+SH
+    chmod +x "${TEST_DIR}/backup_daaf.sh"
+}
+
+@test "migrate: Era 1 path (clone-based) completes successfully" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-test-1" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 0 ;;
+                *"exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"exec"*"fetch"*) return 0 ;;
+                *"exec"*"branch --set-upstream"*) return 0 ;;
+                *"exec"*"remote get-url"*"upstream"*) echo "" ; return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "clone-based installation"
+    assert_output --partial "Migration complete"
+}
+
+@test "migrate: Era 2 path (ZIP-based) completes with graft" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        CALL_COUNT_REMOTE=0
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-test-1" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 0 ;;
+                *"exec"*"remote get-url"*"origin"*) echo "" ; return 1 ;;
+                *"exec"*"fetch"*) return 0 ;;
+                *"exec"*"rev-list --max-parents=0"*) echo "aaa111rootcommit" ;;
+                *"exec"*"cat-file -p"*) printf "tree abc123\nparent def456\nauthor Test\n" ;;
+                *"exec"*"branch --set-upstream"*) return 0 ;;
+                *"exec"*"remote add"*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "ZIP-based installation"
+    assert_output --partial "Migration complete"
+}
+
+@test "migrate: already migrated (idempotency) skips graft" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-test-1" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 0 ;;
+                *"exec"*"remote get-url"*"origin"*) echo "" ; return 1 ;;
+                *"exec"*"fetch"*) return 0 ;;
+                *"exec"*"rev-list --max-parents=0"*) echo "aaa111rootcommit" ;;
+                *"exec"*"cat-file -p"*) printf "tree abc123\nparent def456\nauthor Test\n" ;;
+                *"exec"*"branch --set-upstream"*) return 0 ;;
+                *"exec"*"remote add"*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "graft already in place"
+    assert_output --partial "Migration complete"
+}
+
+# ============================================================================
+# Error path tests
+# ============================================================================
+
+@test "migrate: fetch from origin fails exits with error" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-test-1" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 0 ;;
+                *"exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"exec"*"fetch"*) echo "fatal: unable to access" >&2 ; return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "Failed to fetch"
+}
+
+@test "migrate: lock contention exits with already running" {
+    setup_migrate_integrated
+    # Create the lock directory before running
+    mkdir -p /tmp/daaf-migrate.lock.d
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        docker() { return 0; }
+        export -f docker
+        curl() { return 0; }
+        export -f curl
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "already running"
+    # Clean up
+    rmdir /tmp/daaf-migrate.lock.d 2>/dev/null || true
+}
+
+@test "migrate: DAAF not installed (CLAUDE.md missing) exits with error" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-test-1" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "DAAF does not appear to be installed"
+}
+
+@test "migrate: container not running and start fails exits with error" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "" ;;
+                *"compose up"*) echo "ERROR: Cannot start" >&2 ; return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "Failed to start"
+}
+
+@test "migrate: volume not found exits with error" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "not found"
+}
+
+# ============================================================================
+# Edge cases
+# ============================================================================
+
+@test "migrate: fork detection adds upstream remote" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) echo "daaf-test-1" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 0 ;;
+                *"exec"*"remote get-url"*"upstream"*) echo "" ; return 1 ;;
+                *"exec"*"remote get-url"*"origin"*) echo "https://github.com/user/daaf-fork.git" ;;
+                *"exec"*"fetch"*) return 0 ;;
+                *"exec"*"branch --set-upstream"*) return 0 ;;
+                *"exec"*"remote add"*"upstream"*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "clone-based installation"
+    assert_output --partial "fork"
+    assert_output --partial "Migration complete"
+}
+
+@test "migrate: multi-container on same volume shows warning" {
+    setup_migrate_integrated
+    run bash -c '
+        cd "'"${TEST_DIR}"'"
+        curl() {
+            local outfile=""
+            local args=("$@")
+            for ((i=0; i<${#args[@]}; i++)); do
+                if [ "${args[$i]}" = "-o" ]; then
+                    outfile="${args[$((i+1))]}"
+                    break
+                fi
+            done
+            if [ -n "${outfile}" ]; then
+                mkdir -p "$(dirname "${outfile}")"
+                echo "#!/usr/bin/env bash" > "${outfile}"
+                echo "exit 0" >> "${outfile}"
+            fi
+            return 0
+        }
+        export -f curl
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"volume inspect"*) return 0 ;;
+                *"ps -a"*"--filter"*"volume="*"--format"*) printf "daaf-test-1\ndaaf-test-2\n" ;;
+                *"inspect --format"*"State.Status"*) echo "running" ;;
+                *"exec"*"true"*) return 0 ;;
+                *"exec"*"test -f"*"CLAUDE.md"*) return 0 ;;
+                *"exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"exec"*"fetch"*) return 0 ;;
+                *"exec"*"branch --set-upstream"*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/migrate_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "Multiple containers"
+    assert_output --partial "Migration complete"
+}
diff --git a/tests/bash/rebuild_daaf.bats b/tests/bash/rebuild_daaf.bats
new file mode 100755
index 0000000..621f63e
--- /dev/null
+++ b/tests/bash/rebuild_daaf.bats
@@ -0,0 +1,406 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for rebuild_daaf.sh -- DAAF Rebuild Utility
+# ============================================================================
+# Key testable logic: preflight checks, docker-compose.yml requirement,
+# container existence check, file hash comparison.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    create_fake_compose_file
+}
+
+teardown() {
+    common_teardown
+}
+
+# --- Syntax ---
+
+@test "rebuild_daaf.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_success
+}
+
+# --- Preflight: missing docker-compose.yml ---
+
+@test "rebuild_daaf.sh fails when docker-compose.yml is missing" {
+    rm -f docker-compose.yml
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+# --- Preflight: missing Docker ---
+
+@test "rebuild_daaf.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "rebuild_daaf.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- Preflight: container not found ---
+
+@test "rebuild_daaf.sh fails when container does not exist" {
+    MOCK_DOCKER_INSPECT_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "not found"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "rebuild_daaf.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_INSPECT_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Banner display ---
+
+@test "rebuild_daaf.sh displays the DAAF Rebuild banner" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_INSPECT_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_output --partial "DAAF Rebuild"
+}
+
+# --- Numbered progress steps ---
+
+@test "rebuild_daaf.sh uses numbered progress steps [1/3] [2/3] [3/3]" {
+    run grep -c '\[1/3\]\|\[2/3\]\|\[3/3\]' "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_success
+    [ "${output}" -ge 3 ]
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "rebuild_daaf.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_success
+}
+
+@test "rebuild_daaf.sh: dry-run completes rebuild" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "Rebuild complete"
+}
+
+# =========================================================================
+# Error paths
+# =========================================================================
+
+@test "rebuild_daaf.sh: fails when container not found (inspect fails)" {
+    MOCK_DOCKER_INSPECT_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "not found"
+}
+
+@test "rebuild_daaf.sh: fails when Dockerfile copy from container fails" {
+    export DAAF_NESTED=1
+    # Custom docker mock: inspect succeeds, cp fails
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)
+                # Fail on copy
+                return 1
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to copy Dockerfile"
+}
+
+@test "rebuild_daaf.sh: fails when docker compose build fails and preserves pre-rebuild backup" {
+    export DAAF_NESTED=1
+    # Create a pre-existing Dockerfile so the script creates a .pre-rebuild backup
+    echo "FROM old-image" > "${TEST_DIR}/Dockerfile"
+    # Custom docker mock: inspect and cp succeed, compose build fails
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)
+                # Simulate successful copy (write new content to Dockerfile)
+                echo "FROM new-image" > ./Dockerfile
+                return 0
+                ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 1 ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Rebuild failed"
+    assert_output --partial "pre-rebuild"
+}
+
+@test "rebuild_daaf.sh: fails when docker compose up -d fails after build" {
+    export DAAF_NESTED=1
+    # Custom docker mock: build succeeds, up fails
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)      return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 0 ;;
+                    up) return 1 ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start"
+}
+
+@test "rebuild_daaf.sh: fails on container readiness timeout after rebuild" {
+    export DAAF_NESTED=1
+    # Custom docker mock: build and up succeed, exec always fails
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)      return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 0 ;;
+                    up) return 0 ;;
+                    exec) return 1 ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    # Override sleep to keep the test fast
+    sleep() { true; }
+    export -f sleep
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "did not become ready"
+}
+
+@test "rebuild_daaf.sh: fails when CLAUDE.md missing after rebuild" {
+    export DAAF_NESTED=1
+    # Custom docker mock: everything succeeds except test -f CLAUDE.md
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)      return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 0 ;;
+                    up) return 0 ;;
+                    exec)
+                        local args_str="$*"
+                        if [[ "${args_str}" == *"test -f"* ]]; then
+                            return 1
+                        fi
+                        # Readiness check (exec ... true) succeeds
+                        return 0
+                        ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "WARNING"
+    assert_output --partial "DAAF files may not be intact"
+}
+
+@test "rebuild_daaf.sh: hash comparison shows UPDATED when Dockerfile changed" {
+    export DAAF_NESTED=1
+    # Create a pre-existing Dockerfile with different content
+    echo "FROM old-image" > "${TEST_DIR}/Dockerfile"
+    # Custom docker mock: cp overwrites Dockerfile with new content
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"Dockerfile"* ]]; then
+                    echo "FROM new-image" > ./Dockerfile
+                fi
+                if [[ "${args_str}" == *"docker-compose.yml"* ]]; then
+                    # Keep compose file the same as existing
+                    true
+                fi
+                return 0
+                ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 0 ;;
+                    up) return 0 ;;
+                    exec)
+                        # All exec calls succeed (readiness + verification)
+                        return 0
+                        ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_output --partial "Dockerfile: UPDATED"
+}
+
+@test "rebuild_daaf.sh: hash comparison shows no changes when files unchanged" {
+    export DAAF_NESTED=1
+    # Create pre-existing Dockerfile and docker-compose.yml with known content
+    echo "FROM same-image" > "${TEST_DIR}/Dockerfile"
+    # Custom docker mock: cp writes the same content (no changes)
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"Dockerfile"* ]]; then
+                    echo "FROM same-image" > ./Dockerfile
+                fi
+                if [[ "${args_str}" == *"docker-compose.yml"* ]]; then
+                    # Write same content to compose file
+                    true
+                fi
+                return 0
+                ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 0 ;;
+                    up) return 0 ;;
+                    exec) return 0 ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_output --partial "No changes detected"
+}
+
+@test "rebuild_daaf.sh: hash comparison shows UPDATED when compose file changed" {
+    export DAAF_NESTED=1
+    # Custom docker mock: cp overwrites docker-compose.yml with new content
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"docker-compose.yml"* ]]; then
+                    echo "version: '3.9'" > ./docker-compose.yml
+                fi
+                return 0
+                ;;
+            compose)
+                shift
+                case "$1" in
+                    build) return 0 ;;
+                    up) return 0 ;;
+                    exec) return 0 ;;
+                    *) return 0 ;;
+                esac
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_output --partial "docker-compose.yml: UPDATED"
+}
+
+@test "rebuild_daaf.sh: fails when docker-compose.yml copy from container fails" {
+    export DAAF_NESTED=1
+    # Custom docker mock: Dockerfile copy succeeds, compose copy fails
+    docker() {
+        case "$1" in
+            info)    return 0 ;;
+            inspect) return 0 ;;
+            cp)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"Dockerfile"* ]]; then
+                    return 0
+                fi
+                if [[ "${args_str}" == *"docker-compose.yml"* ]]; then
+                    return 1
+                fi
+                return 0
+                ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+    run bash "${REPO_ROOT}/scripts/host/rebuild_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to copy docker-compose.yml"
+}
diff --git a/tests/bash/restore_from_backup.bats b/tests/bash/restore_from_backup.bats
new file mode 100644
index 0000000..23a1071
--- /dev/null
+++ b/tests/bash/restore_from_backup.bats
@@ -0,0 +1,464 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for restore_from_backup.sh -- DAAF Restore from Backup
+# ============================================================================
+# Key testable logic: backup discovery, preflight checks, running container
+# detection, destructive warning, volume clearing, and verification.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+}
+
+teardown() {
+    common_teardown
+}
+
+# --- Syntax ---
+
+@test "restore_from_backup.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+# --- Preflight: missing Docker ---
+
+@test "restore: fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "restore: fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- Preflight: volume not found ---
+
+@test "restore: fails when Docker volume does not exist" {
+    MOCK_DOCKER_VOLUME_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "not found"
+}
+
+# --- No backups found ---
+
+@test "restore: fails when no backup folders exist" {
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+    assert_output --partial "No backup folders found"
+}
+
+@test "restore: suggests daaf-docker folder when no backups found" {
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+    assert_output --partial "daaf-docker"
+}
+
+# --- Backup discovery ---
+
+@test "restore: discovers backup folders matching date pattern" {
+    local today
+    today=$(date +%Y-%m-%d)
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+    touch "${TEST_DIR}/${today}_daaf_backup/file1"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    # Pipe empty input so read fails and script exits
+    run bash -c 'echo "" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    # Should list the backup even if selection fails
+    assert_output --partial "${today}_daaf_backup"
+}
+
+@test "restore: discovers multiple backups with suffixes" {
+    local today
+    today=$(date +%Y-%m-%d)
+    mkdir -p "${TEST_DIR}/${today}_daaf_backup"
+    mkdir -p "${TEST_DIR}/${today}a_daaf_backup"
+    touch "${TEST_DIR}/${today}_daaf_backup/f1"
+    touch "${TEST_DIR}/${today}a_daaf_backup/f1"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash -c 'echo "" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_output --partial "${today}_daaf_backup"
+    assert_output --partial "${today}a_daaf_backup"
+}
+
+@test "restore: ignores directories not matching backup pattern" {
+    mkdir -p "${TEST_DIR}/2026-04-21_daaf_backup"
+    mkdir -p "${TEST_DIR}/random_folder"
+    mkdir -p "${TEST_DIR}/not_a_backup"
+    touch "${TEST_DIR}/2026-04-21_daaf_backup/f1"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash -c 'echo "" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_output --partial "2026-04-21_daaf_backup"
+    refute_output --partial "random_folder"
+    refute_output --partial "not_a_backup"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "restore: suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Banner ---
+
+@test "restore: displays the DAAF Restore banner" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_output --partial "DAAF Restore from Backup"
+}
+
+# --- Structural: safety features present ---
+
+@test "restore: contains destructive warning text" {
+    run grep -c "DESTRUCTIVE OPERATION" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+@test "restore: requires RESTORE confirmation" {
+    run grep -c "Type RESTORE to confirm" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+@test "restore: clears volume before copying" {
+    run grep -c "rm -rf /dest" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+@test "restore: uses cp -a (not cp -r) for permission-preserving copy" {
+    run grep -c "cp -a /source" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+    run grep -c "cp -r /source" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+}
+
+@test "restore: checks for running containers before restoring" {
+    run grep -c "docker ps --filter" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+@test "restore: verifies file count after restore" {
+    run grep -c "Verifying restore" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+@test "restore: includes file count mismatch check" {
+    run grep -c "File count mismatch" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+# --- Invalid selection ---
+
+@test "restore: rejects non-numeric selection" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash -c 'echo "abc" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_failure
+    assert_output --partial "Invalid selection"
+}
+
+@test "restore: rejects out-of-range selection" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash -c 'echo "99" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_failure
+    assert_output --partial "Invalid selection"
+}
+
+# --- Cancellation ---
+
+@test "restore: cancels when user does not type RESTORE" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    MOCK_DOCKER_VOLUME_EXIT=0
+    MOCK_DOCKER_RUN_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash -c 'printf "1\nno\n" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_output --partial "Restore cancelled"
+}
+
+# --- Running container detection ---
+
+@test "restore: offers to stop running containers" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=0
+
+    # Override docker to return a container name for ps --filter
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            ps)
+                echo "daaf-daaf-docker-1"
+                return 0
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    # Decline the stop prompt
+    run bash -c 'echo "n" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_output --partial "container is currently running"
+    assert_output --partial "Restore cancelled"
+}
+
+@test "restore: warns about Claude Code sessions when containers running" {
+    run grep -c "Claude Code sessions" "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "restore: dry-run completes successfully with backups present" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+}
+
+@test "restore: dry-run produces DRY-RUN markers" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh" 2>&1
+    assert_success
+    assert_output --partial "[DRY-RUN]"
+}
+
+@test "restore: dry-run shows backup count" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    mkdir -p "${TEST_DIR}/2026-01-02_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+    touch "${TEST_DIR}/2026-01-02_daaf_backup/f1"
+
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh" 2>&1
+    assert_success
+    assert_output --partial "2 backup(s)"
+}
+
+@test "restore: dry-run succeeds when no backups exist" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_success
+    assert_output --partial "No backup folders found"
+}
+
+# =========================================================================
+# --- Error paths ---
+# =========================================================================
+
+@test "restore: running container detected offers to stop" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=0
+
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            ps)
+                echo "daaf-daaf-docker-1"
+                return 0
+                ;;
+            compose)
+                shift
+                case "$1" in
+                    down) return 0 ;;
+                    *)    return 0 ;;
+                esac
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    # User answers 'y' to stop, then the script continues looking for backups
+    # No backups exist so it exits with failure
+    run bash -c 'echo "y" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"' 2>&1
+    assert_output --partial "container is currently running"
+    assert_output --partial "must be stopped before restoring"
+    assert_output --partial "Stopping containers"
+}
+
+@test "restore: user declines to stop container exits cleanly" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_VOLUME_EXIT=0
+
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            ps)
+                echo "daaf-daaf-docker-1"
+                return 0
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash -c 'echo "n" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_success
+    assert_output --partial "Restore cancelled"
+}
+
+@test "restore: volume clear fails exits with error" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    export DAAF_NESTED=1
+
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            ps)     return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"rm -rf"* ]]; then
+                    # Volume clear fails
+                    return 1
+                fi
+                return 0
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    # Select backup 1, confirm with RESTORE
+    run bash -c 'printf "1\nRESTORE\n" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to clear"
+}
+
+@test "restore: zero files after restore exits with error" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    touch "${TEST_DIR}/2026-01-01_daaf_backup/f1"
+
+    export DAAF_NESTED=1
+
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            ps)     return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"rm -rf"* ]]; then
+                    return 0
+                elif [[ "${args_str}" == *"cp -a"* ]]; then
+                    return 0
+                elif [[ "${args_str}" == *"find /dest"* ]]; then
+                    # Verification: 0 files restored
+                    echo "0"
+                    return 0
+                fi
+                return 0
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash -c 'printf "1\nRESTORE\n" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "0 files found"
+}
+
+@test "restore: file count mismatch after restore shows warning" {
+    mkdir -p "${TEST_DIR}/2026-01-01_daaf_backup"
+    # Create enough files to make mismatch significant (beyond 1% tolerance)
+    for i in $(seq 1 50); do
+        touch "${TEST_DIR}/2026-01-01_daaf_backup/f${i}"
+    done
+
+    export DAAF_NESTED=1
+
+    docker() {
+        case "$1" in
+            info)   return 0 ;;
+            volume) return 0 ;;
+            ps)     return 0 ;;
+            run)
+                shift
+                local args_str="$*"
+                if [[ "${args_str}" == *"rm -rf"* ]]; then
+                    return 0
+                elif [[ "${args_str}" == *"cp -a"* ]]; then
+                    return 0
+                elif [[ "${args_str}" == *"find /dest"* ]]; then
+                    # Return much lower count than actual (50 files, report 10)
+                    echo "10"
+                    return 0
+                fi
+                return 0
+                ;;
+            *)  return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash -c 'printf "1\nRESTORE\n" | bash "'"${REPO_ROOT}"'/scripts/host/restore_from_backup.sh"'
+    assert_output --partial "WARNING"
+    assert_output --partial "File count mismatch"
+}
+
+@test "restore: no backup folders found exits with error" {
+    # No backup directories created in TEST_DIR
+    MOCK_DOCKER_VOLUME_EXIT=0
+    export DAAF_NESTED=1
+
+    run bash "${REPO_ROOT}/scripts/host/restore_from_backup.sh"
+    assert_failure
+    assert_output --partial "No backup folders found"
+}
diff --git a/tests/bash/run_daaf.bats b/tests/bash/run_daaf.bats
new file mode 100755
index 0000000..4c88890
--- /dev/null
+++ b/tests/bash/run_daaf.bats
@@ -0,0 +1,218 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for run_daaf.sh -- DAAF Launcher
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    create_fake_compose_file
+}
+
+teardown() {
+    common_teardown
+}
+
+# --- Syntax ---
+
+@test "run_daaf.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_success
+}
+
+# --- Preflight: missing docker-compose.yml ---
+
+@test "run_daaf.sh fails when docker-compose.yml is missing" {
+    rm -f docker-compose.yml
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+# --- Preflight: missing Docker ---
+
+@test "run_daaf.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "run_daaf.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "run_daaf.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    # The mock will make compose ps return no match, then compose up succeeds,
+    # then exec for CLAUDE.md check succeeds, then exec for claude runs
+    MOCK_DOCKER_PS_OUTPUT=""
+    MOCK_DOCKER_EXEC_OUTPUT=""
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Default command ---
+
+@test "run_daaf.sh defaults to claude command" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_output --partial "Launching Claude Code"
+}
+
+# --- Custom command ---
+
+@test "run_daaf.sh accepts bash as argument" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh" bash
+    assert_output --partial "Entering container shell"
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "run_daaf.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_success
+}
+
+@test "run_daaf.sh: dry-run produces DRY-RUN markers" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/run_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "[DRY-RUN]"
+}
+
+# =========================================================================
+# --- Error paths ---
+# =========================================================================
+
+@test "run_daaf: auto-starts container when not running" {
+    export DAAF_NESTED=1
+    create_fake_compose_file
+
+    docker() {
+        case "$1" in
+            info) return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    ps) echo "" ; return 0 ;;
+                    up) return 0 ;;
+                    exec) echo "" ; return 0 ;;
+                    *) return 0 ;;
+                esac ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_output --partial "Starting"
+}
+
+@test "run_daaf: auto-start fails exits with error" {
+    export DAAF_NESTED=1
+    create_fake_compose_file
+
+    docker() {
+        case "$1" in
+            info) return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    ps) echo "" ; return 0 ;;
+                    up) return 1 ;;
+                    *) return 0 ;;
+                esac ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start"
+}
+
+@test "run_daaf: compose file missing exits with error" {
+    export DAAF_NESTED=1
+    rm -f "${TEST_DIR}/docker-compose.yml"
+
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+@test "run_daaf: DAAF not installed in container exits with error" {
+    export DAAF_NESTED=1
+    create_fake_compose_file
+
+    docker() {
+        case "$1" in
+            info) return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    ps) echo "daaf-docker" ; return 0 ;;
+                    exec)
+                        # Check if this is the CLAUDE.md test
+                        local args_str="$*"
+                        if [[ "${args_str}" == *"test -f"* ]]; then
+                            return 1
+                        fi
+                        return 0
+                        ;;
+                    *) return 0 ;;
+                esac ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_failure
+    assert_output --partial "DAAF does not appear to be installed"
+}
+
+@test "run_daaf: custom command passthrough runs correctly" {
+    export DAAF_NESTED=1
+    create_fake_compose_file
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=0
+
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh" htop
+    assert_output --partial "Running: htop"
+}
+
+@test "run_daaf: default command when no args launches claude" {
+    export DAAF_NESTED=1
+    create_fake_compose_file
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=0
+
+    run bash "${REPO_ROOT}/scripts/host/run_daaf.sh"
+    assert_output --partial "Launching Claude Code"
+}
diff --git a/tests/bash/run_vscode.bats b/tests/bash/run_vscode.bats
new file mode 100644
index 0000000..409b0a2
--- /dev/null
+++ b/tests/bash/run_vscode.bats
@@ -0,0 +1,212 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for run_vscode.sh -- DAAF Code Browser (VS Code in the browser)
+# ============================================================================
+# Thin wrapper script -- tests focus on preflight checks, container lifecycle,
+# dry-run behavior, and structural markers.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    create_fake_compose_file
+}
+
+teardown() {
+    common_teardown
+}
+
+# =========================================================================
+# Tier 1 -- Syntax
+# =========================================================================
+
+@test "run_vscode.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+}
+
+# =========================================================================
+# Tier 2 -- Preflight checks
+# =========================================================================
+
+# --- Preflight: missing docker-compose.yml ---
+
+@test "run_vscode.sh fails when docker-compose.yml is missing" {
+    rm -f docker-compose.yml
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+# --- Preflight: missing Docker ---
+
+@test "run_vscode.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "run_vscode.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "run_vscode.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_INFO_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    refute_output --partial "Press Enter"
+}
+
+# =========================================================================
+# Tier 3 -- Script structure
+# =========================================================================
+
+@test "run_vscode.sh includes set -euo pipefail" {
+    run grep -c "set -euo pipefail" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh checks for docker-compose.yml" {
+    run grep -c "docker-compose.yml" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh checks command -v docker" {
+    run grep -c "command -v docker" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh checks docker info" {
+    run grep -c "docker info" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh references launch_code_server.sh" {
+    run grep -c "launch_code_server.sh" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh mentions Code Browser in output" {
+    run grep -c "Code Browser" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh supports DAAF_TEST_MODE guard" {
+    run grep -c "DAAF_TEST_MODE" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "run_vscode.sh supports DAAF_DRY_RUN" {
+    run grep -c "DAAF_DRY_RUN" "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# =========================================================================
+# Tier 4 -- Behavioral (DAAF_TEST_MODE)
+# =========================================================================
+
+@test "run_vscode.sh exits cleanly when sourced with DAAF_TEST_MODE=1" {
+    export DAAF_TEST_MODE=1
+    run bash -c "source '${REPO_ROOT}/scripts/host/run_vscode.sh'"
+    assert_success
+}
+
+# =========================================================================
+# Tier 5 -- Dry-run
+# =========================================================================
+
+@test "run_vscode.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_success
+}
+
+@test "run_vscode.sh: dry-run completes without real Docker" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/run_vscode.sh" 2>&1
+    assert_success
+    assert_output --partial "DAAF container is running"
+    assert_output --partial "Code Browser"
+}
+
+@test "run_vscode.sh: dry-run shows Code Browser message" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/run_vscode.sh" 2>&1
+    assert_success
+    assert_output --partial "Code Browser"
+}
+
+@test "run_vscode.sh: dry-run reports container running" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/run_vscode.sh" 2>&1
+    assert_success
+    assert_output --partial "DAAF container is running"
+}
+
+# =========================================================================
+# Tier 6 -- Error paths
+# =========================================================================
+
+# --- Container not running → start attempt ---
+
+@test "run_vscode.sh attempts to start container when not running" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT=""
+    MOCK_DOCKER_COMPOSE_EXIT=0
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_output --partial "Starting DAAF container"
+}
+
+# --- Container start fails ---
+
+@test "run_vscode.sh fails when container start fails" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT=""
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start the container"
+}
+
+# --- Code-server launch fails ---
+
+@test "run_vscode.sh reports error when code-server fails to start" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start code-server"
+}
+
+# --- Container already running ---
+
+@test "run_vscode.sh reports container already running" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/run_vscode.sh"
+    assert_output --partial "DAAF container is running"
+}
diff --git a/tests/bash/test_helper.bash b/tests/bash/test_helper.bash
new file mode 100755
index 0000000..3c3bcee
--- /dev/null
+++ b/tests/bash/test_helper.bash
@@ -0,0 +1,237 @@
+#!/usr/bin/env bash
+# ============================================================================
+# BATS Test Helper -- shared setup for all DAAF shell script tests
+# ============================================================================
+# Source this from every .bats file via:  load 'test_helper'
+#
+# Provides:
+#   - common_setup / common_teardown (temp dir lifecycle)
+#   - mock_docker (function-override Docker mock)
+#   - create_fake_compose_file (minimal docker-compose.yml in TEST_DIR)
+#   - assert_success / assert_failure / assert_output helpers via bats-assert
+# ============================================================================
+
+# --- Load bats helper libraries (if available) ---
+# CI installs these via bats-core/bats-action; local runs may use submodules.
+# If not available, provide minimal fallback assertions.
+_BATS_HELPERS_LOADED=false
+for _lib_root in \
+    "${BATS_TEST_DIRNAME}/../libs" \
+    "${BATS_TEST_DIRNAME}/../../test/libs" \
+    "/usr/lib/bats"; do
+    if [ -f "${_lib_root}/bats-support/load.bash" ]; then
+        load "${_lib_root}/bats-support/load"
+        load "${_lib_root}/bats-assert/load"
+        _BATS_HELPERS_LOADED=true
+        break
+    fi
+done
+
+if [ "${_BATS_HELPERS_LOADED}" != "true" ]; then
+    # Minimal fallback assertions when bats-assert is not installed
+    assert_success() {
+        if [ "${status}" -ne 0 ]; then
+            echo "assert_success failed: status=${status}"
+            echo "output: ${output}"
+            return 1
+        fi
+    }
+    assert_failure() {
+        if [ "${status}" -eq 0 ]; then
+            echo "assert_failure failed: expected non-zero exit"
+            echo "output: ${output}"
+            return 1
+        fi
+    }
+    assert_output() {
+        if [ "$1" = "--partial" ]; then
+            shift
+            if [[ "${output}" != *"$1"* ]]; then
+                echo "assert_output --partial failed"
+                echo "expected to contain: $1"
+                echo "actual output: ${output}"
+                return 1
+            fi
+        else
+            if [ "${output}" != "$1" ]; then
+                echo "assert_output failed"
+                echo "expected: $1"
+                echo "actual: ${output}"
+                return 1
+            fi
+        fi
+    }
+    refute_output() {
+        if [ "$1" = "--partial" ]; then
+            shift
+            if [[ "${output}" == *"$1"* ]]; then
+                echo "refute_output --partial failed"
+                echo "expected NOT to contain: $1"
+                echo "actual output: ${output}"
+                return 1
+            fi
+        fi
+    }
+fi
+
+# ============================================================================
+# Common setup / teardown
+# ============================================================================
+
+# Path to the repository root (parent of tests/bash/)
+REPO_ROOT="$(cd "${BATS_TEST_DIRNAME}/../.." && pwd)"
+
+common_setup() {
+    TEST_DIR="$(mktemp -d)"
+    ORIGINAL_DIR="$(pwd)"
+    cd "${TEST_DIR}" || return 1
+    export TEST_DIR ORIGINAL_DIR REPO_ROOT
+}
+
+common_teardown() {
+    cd "${ORIGINAL_DIR}" || true
+    rm -rf "${TEST_DIR}"
+}
+
+# ============================================================================
+# Docker mock (Strategy 1 -- function override)
+# ============================================================================
+# After calling mock_docker, any `docker` invocation in the script under test
+# is intercepted. Control behavior via MOCK_DOCKER_* variables.
+#
+# Usage in tests:
+#   setup() { common_setup; mock_docker; }
+#   @test "..." { MOCK_DOCKER_INFO_EXIT=1; run bash "$REPO_ROOT/script.sh"; ... }
+
+mock_docker() {
+    DOCKER_CALLS=()
+    export MOCK_DOCKER_EXIT=0
+    export MOCK_DOCKER_INFO_EXIT=0
+    export MOCK_DOCKER_COMPOSE_EXIT=0
+    export MOCK_DOCKER_EXEC_EXIT=0
+    export MOCK_DOCKER_EXEC_OUTPUT=""
+    export MOCK_DOCKER_CP_EXIT=0
+    export MOCK_DOCKER_VOLUME_EXIT=0
+    export MOCK_DOCKER_PS_OUTPUT=""
+    export MOCK_DOCKER_RUN_EXIT=0
+    export MOCK_DOCKER_RUN_OUTPUT=""
+    export MOCK_DOCKER_INSPECT_EXIT=0
+    export MOCK_DOCKER_INSPECT_OUTPUT=""
+    export MOCK_DOCKER_START_EXIT=0
+
+    docker() {
+        DOCKER_CALLS+=("$*")
+        case "$1" in
+            info)
+                return "${MOCK_DOCKER_INFO_EXIT:-0}"
+                ;;
+            compose)
+                shift
+                case "$1" in
+                    ps)
+                        echo "${MOCK_DOCKER_PS_OUTPUT:-}"
+                        return "${MOCK_DOCKER_COMPOSE_EXIT:-0}"
+                        ;;
+                    exec)
+                        echo "${MOCK_DOCKER_EXEC_OUTPUT:-}"
+                        return "${MOCK_DOCKER_EXEC_EXIT:-0}"
+                        ;;
+                    up|build)
+                        return "${MOCK_DOCKER_COMPOSE_EXIT:-0}"
+                        ;;
+                    *)
+                        return "${MOCK_DOCKER_COMPOSE_EXIT:-0}"
+                        ;;
+                esac
+                ;;
+            cp)
+                return "${MOCK_DOCKER_CP_EXIT:-0}"
+                ;;
+            volume)
+                return "${MOCK_DOCKER_VOLUME_EXIT:-0}"
+                ;;
+            run)
+                echo "${MOCK_DOCKER_RUN_OUTPUT:-}"
+                return "${MOCK_DOCKER_RUN_EXIT:-0}"
+                ;;
+            inspect)
+                echo "${MOCK_DOCKER_INSPECT_OUTPUT:-}"
+                return "${MOCK_DOCKER_INSPECT_EXIT:-0}"
+                ;;
+            start)
+                return "${MOCK_DOCKER_START_EXIT:-0}"
+                ;;
+            exec)
+                echo "${MOCK_DOCKER_EXEC_OUTPUT:-}"
+                return "${MOCK_DOCKER_EXEC_EXIT:-0}"
+                ;;
+            ps)
+                echo "${MOCK_DOCKER_PS_OUTPUT:-}"
+                return 0
+                ;;
+            *)
+                return "${MOCK_DOCKER_EXIT:-0}"
+                ;;
+        esac
+    }
+    export -f docker
+}
+
+# ============================================================================
+# Mock for `command -v docker` preflight checks
+# ============================================================================
+# Some scripts use `command -v docker` to check Docker is installed.
+# Call mock_no_docker to make that check fail.
+
+mock_no_docker() {
+    # Override command builtin to fail for docker
+    command() {
+        if [ "$1" = "-v" ] && [ "$2" = "docker" ]; then
+            return 1
+        fi
+        builtin command "$@"
+    }
+    export -f command
+}
+
+# ============================================================================
+# Fake docker-compose.yml
+# ============================================================================
+
+create_fake_compose_file() {
+    local target_dir="${1:-${TEST_DIR}}"
+    cat > "${target_dir}/docker-compose.yml" <<'YAML'
+name: daaf
+services:
+  daaf-docker:
+    image: daaf:latest
+    volumes:
+      - daaf-data:/daaf
+volumes:
+  daaf-data:
+YAML
+}
+
+# ============================================================================
+# Mock for curl (used by install.sh and migrate_daaf.sh)
+# ============================================================================
+
+mock_curl() {
+    export MOCK_CURL_EXIT=0
+    curl() {
+        # By default, create an empty file at the -o destination
+        local outfile=""
+        local args=("$@")
+        for ((i=0; i<${#args[@]}; i++)); do
+            if [ "${args[$i]}" = "-o" ]; then
+                outfile="${args[$((i+1))]}"
+                break
+            fi
+        done
+        if [ -n "${outfile}" ]; then
+            touch "${outfile}"
+        fi
+        return "${MOCK_CURL_EXIT:-0}"
+    }
+    export -f curl
+}
diff --git a/tests/bash/update_daaf.bats b/tests/bash/update_daaf.bats
new file mode 100755
index 0000000..8e6521a
--- /dev/null
+++ b/tests/bash/update_daaf.bats
@@ -0,0 +1,847 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for update_daaf.sh -- DAAF Update Script
+# ============================================================================
+# update_daaf.sh is the most complex script: state machine with ahead/behind
+# detection, merge/rebase paths, stash handling, conflict resolution.
+# These tests focus on preflight checks and early-exit paths that can be
+# tested without a real Docker daemon.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    create_fake_compose_file
+}
+
+teardown() {
+    common_teardown
+    # Clean up lock directories that may be left by lock contention tests
+    rmdir /tmp/daaf-update.lock.d 2>/dev/null || true
+}
+
+# --- Syntax ---
+
+@test "update_daaf.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+}
+
+# --- Preflight: missing docker-compose.yml ---
+
+@test "update_daaf.sh fails when docker-compose.yml is missing" {
+    rm -f docker-compose.yml
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+# --- Preflight: missing Docker ---
+
+@test "update_daaf.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "update_daaf.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "update_daaf.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    # Will fail at some docker step, but should not pause
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    MOCK_DOCKER_PS_OUTPUT=""
+    run bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Helper function: prompt_choice ---
+
+@test "update_daaf.sh defines prompt_choice helper function" {
+    # Verify the function exists in the script source
+    run grep -c "prompt_choice()" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Helper function: handle_conflict ---
+
+@test "update_daaf.sh defines handle_conflict helper function" {
+    run grep -c "handle_conflict()" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Helper function: sync_host_scripts ---
+
+@test "update_daaf.sh defines sync_host_scripts helper function" {
+    run grep -c "sync_host_scripts()" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Helper function: check_build_changes ---
+
+@test "update_daaf.sh defines check_build_changes helper function" {
+    run grep -c "check_build_changes()" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Helper function: finish_update ---
+
+@test "update_daaf.sh defines finish_update helper function" {
+    run grep -c "finish_update()" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- ERR trap defined ---
+
+@test "update_daaf.sh defines an ERR trap for cleanup" {
+    run grep -c "trap cleanup_on_error ERR" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Banner display ---
+
+@test "update_daaf.sh displays the DAAF Updater banner" {
+    export DAAF_NESTED=1
+    # Will fail at preflight but should show banner first
+    MOCK_DOCKER_INFO_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_output --partial "DAAF Updater"
+}
+
+# --- DAAF_BRANCH override ---
+
+@test "update_daaf.sh uses DAAF_BRANCH variable in banner tip" {
+    # The script references DAAF_BRANCH for branch resolution
+    run grep -c "DAAF_BRANCH" "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# ============================================================================
+# Behavioral tests -- sourced functions
+# ============================================================================
+# Source the script in test mode so all helper functions are available
+# without executing the main state-machine logic.
+#
+# The sourcing pattern:
+#   DAAF_TEST_MODE=1 source update_daaf.sh   (defines functions, then returns)
+#   trap - ERR                                (remove ERR trap from sourced script)
+#   set +eu                                   (disable strict mode for test flexibility)
+#
+# After sourcing, these functions are callable:
+#   prompt_choice, handle_conflict, sync_host_scripts,
+#   check_build_changes, finish_update, cleanup_on_error
+# ============================================================================
+
+# --- sync_host_scripts behavioral tests ---
+
+@test "update: sync_host_scripts skips when HEAD unchanged" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+
+        # Mock docker: compose exec returns the same HEAD hash
+        docker() {
+            echo "abc1234"
+            return 0
+        }
+
+        sync_host_scripts "abc1234"
+    '
+    assert_success
+    # No "Syncing" output when HEAD is unchanged
+    refute_output --partial "Syncing"
+}
+
+@test "update: sync_host_scripts detects changed files via git diff" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+
+        docker() {
+            case "$*" in
+                *rev-parse*HEAD*) echo "new5678" ;;
+                *diff*--name-only*) echo "scripts/host/run_daaf.sh" ;;
+                cp*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+
+        sync_host_scripts "old1234"
+    '
+    assert_success
+    assert_output --partial "Syncing updated utility scripts..."
+}
+
+@test "update: sync_host_scripts copies only changed files" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+
+        docker() {
+            case "$*" in
+                *rev-parse*HEAD*) echo "new5678" ;;
+                *diff*--name-only*) printf "scripts/host/run_daaf.sh\nscripts/host/backup_daaf.sh\n" ;;
+                cp*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+
+        sync_host_scripts "old1234"
+    '
+    assert_success
+    assert_output --partial "Updated: run_daaf.sh"
+    assert_output --partial "Updated: backup_daaf.sh"
+}
+
+@test "update: sync_host_scripts handles partial failure gracefully" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+
+        docker() {
+            case "$*" in
+                *rev-parse*HEAD*) echo "new5678" ;;
+                *diff*--name-only*) printf "scripts/host/run_daaf.sh\nscripts/host/backup_daaf.sh\n" ;;
+                cp*) return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+
+        sync_host_scripts "old1234"
+    '
+    assert_success
+    assert_output --partial "Warning: could not copy run_daaf.sh"
+    assert_output --partial "Warning: could not copy backup_daaf.sh"
+}
+
+# --- check_build_changes behavioral tests ---
+
+@test "update: check_build_changes detects Dockerfile modifications" {
+    # Pipe "n" to decline the rebuild prompt
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        docker() {
+            case "$*" in
+                *rev-parse*HEAD*) echo "new5678" ;;
+                *diff*--name-only*) echo "Dockerfile" ;;
+                *) return 0 ;;
+            esac
+        }
+        echo "n" | check_build_changes "old1234"
+    '
+    assert_success
+    assert_output --partial "Build files were updated"
+}
+
+@test "update: check_build_changes detects docker-compose.yml modifications" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        docker() {
+            case "$*" in
+                *rev-parse*HEAD*) echo "new5678" ;;
+                *diff*--name-only*) echo "docker-compose.yml" ;;
+                *) return 0 ;;
+            esac
+        }
+        echo "n" | check_build_changes "old1234"
+    '
+    assert_success
+    assert_output --partial "Build files were updated"
+}
+
+@test "update: check_build_changes reports no changes when unchanged" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        docker() {
+            case "$1" in
+                compose)
+                    # rev-parse HEAD returns same hash as old_head
+                    echo "samehash"
+                    return 0
+                    ;;
+                *) return 0 ;;
+            esac
+        }
+        check_build_changes "samehash"
+    '
+    assert_success
+    assert_output --partial "No Dockerfile changes"
+}
+
+# --- finish_update behavioral tests ---
+
+@test "update: finish_update calls sync and check_build_changes" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        # Override downstream functions to track calls
+        sync_host_scripts() { echo "SYNC_CALLED:$1"; }
+        check_build_changes() { echo "CHECK_CALLED:$1"; }
+
+        finish_update "oldhash123"
+    '
+    assert_success
+    assert_output --partial "SYNC_CALLED:oldhash123"
+    assert_output --partial "CHECK_CALLED:oldhash123"
+    assert_output --partial "Update complete!"
+}
+
+@test "update: finish_update displays extra message when provided" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        sync_host_scripts() { :; }
+        check_build_changes() { :; }
+
+        finish_update "oldhash123" "Your commits were rebased."
+    '
+    assert_success
+    assert_output --partial "Update complete!"
+    assert_output --partial "Your commits were rebased."
+}
+
+# --- prompt_choice behavioral tests ---
+# Note: IS_INTERACTIVE is false inside `bash -c` subshells (no /dev/tty),
+# which triggers the non-interactive auto-select path. To test the
+# interactive read path, we define a wrapper that bypasses the check.
+
+@test "update: prompt_choice auto-selects first choice in non-interactive mode" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        echo "ignored" | prompt_choice "Continue? [y/n]: " "y n"
+    '
+    assert_success
+    assert_output --partial "y"
+}
+
+@test "update: prompt_choice auto-selects first of multi-option set" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        echo "ignored" | prompt_choice "Choose [1/2/3]: " "1 2 3"
+    '
+    assert_success
+    assert_output --partial "1"
+}
+
+@test "update: prompt_choice reads input interactively when stdin is a TTY" {
+    # Override prompt_choice to remove the TTY check, simulating interactive mode
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        prompt_choice() {
+            local prompt_text="$1"
+            local valid_choices="$2"
+            local choice=""
+            read -r choice
+            choice=$(echo "${choice}" | tr "[:upper:]" "[:lower:]")
+            if echo "${valid_choices}" | grep -qw "${choice}"; then
+                echo "${choice}"
+            fi
+        }
+        echo "y" | prompt_choice "Continue? [y/n]: " "y n"
+    '
+    assert_success
+    assert_output --partial "y"
+}
+
+@test "update: prompt_choice normalizes uppercase to lowercase" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        prompt_choice() {
+            local prompt_text="$1"
+            local valid_choices="$2"
+            local choice=""
+            read -r choice
+            choice=$(echo "${choice}" | tr "[:upper:]" "[:lower:]")
+            if echo "${valid_choices}" | grep -qw "${choice}"; then
+                echo "${choice}"
+            fi
+        }
+        echo "Y" | prompt_choice "Continue? [y/n]: " "y n"
+    '
+    assert_success
+    assert_output --partial "y"
+}
+
+# --- handle_conflict behavioral tests ---
+
+@test "update: handle_conflict shows conflicting file list" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        docker() {
+            case "$*" in
+                *diff*--diff-filter=U*) printf "CLAUDE.md\nscripts/host/run_daaf.sh\n" ;;
+                *) return 0 ;;
+            esac
+        }
+
+        # Pipe "2" to choose manual resolution (avoids interactive Claude launch)
+        echo "2" | handle_conflict "merge" "merge --abort" || true
+    '
+    assert_output --partial "CLAUDE.md"
+    assert_output --partial "scripts/host/run_daaf.sh"
+}
+
+# handle_conflict calls prompt_choice internally. Since IS_INTERACTIVE is
+# false in bash -c subshells, prompt_choice auto-selects option 1. We
+# override prompt_choice to force option 2 for testing the manual path.
+
+@test "update: handle_conflict option 2 shows manual resolution instructions" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        docker() {
+            case "$1" in
+                compose)
+                    shift
+                    case "$1" in
+                        exec) printf "file.txt\n"; return 0 ;;
+                        *) return 0 ;;
+                    esac
+                    ;;
+                *) return 0 ;;
+            esac
+        }
+
+        prompt_choice() { echo "2"; }
+        handle_conflict "merge" "merge --abort" || true
+    '
+    assert_output --partial "resolve the conflicts manually"
+}
+
+@test "update: handle_conflict merge type shows git add + commit instructions" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        docker() {
+            case "$1" in
+                compose)
+                    shift
+                    case "$1" in
+                        exec) printf "file.txt\n"; return 0 ;;
+                        *) return 0 ;;
+                    esac
+                    ;;
+                *) return 0 ;;
+            esac
+        }
+
+        prompt_choice() { echo "2"; }
+        handle_conflict "merge" "merge --abort" || true
+    '
+    assert_output --partial "git commit"
+    # Merge type should NOT show rebase --continue
+    refute_output --partial "git rebase --continue"
+}
+
+@test "update: handle_conflict rebase type shows git rebase --continue" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        docker() {
+            case "$1" in
+                compose)
+                    shift
+                    case "$1" in
+                        exec) printf "file.txt\n"; return 0 ;;
+                        *) return 0 ;;
+                    esac
+                    ;;
+                *) return 0 ;;
+            esac
+        }
+
+        prompt_choice() { echo "2"; }
+        handle_conflict "rebase" "rebase --abort" || true
+    '
+    assert_output --partial "git rebase --continue"
+}
+
+@test "update: handle_conflict returns 1 when conflicts remain" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+        BACKUP_BRANCH="backup/test-branch"
+
+        docker() {
+            case "$1" in
+                compose)
+                    shift
+                    case "$1" in
+                        exec) printf "file.txt\n"; return 0 ;;
+                        *) return 0 ;;
+                    esac
+                    ;;
+                *) return 0 ;;
+            esac
+        }
+
+        echo "2" | handle_conflict "merge" "merge --abort"
+    '
+    assert_failure
+}
+
+# --- Safety tests ---
+
+@test "update: ERR trap is registered after sourcing" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        # Do NOT clear the trap -- we want to verify it exists
+        set +eu
+        trap -p ERR
+    '
+    assert_success
+    assert_output --partial "cleanup_on_error"
+}
+
+@test "update: locking uses portable mkdir (no flock)" {
+    # Verify the script uses mkdir for locking, not flock
+    run grep -ci 'mkdir.*lock' "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+
+    run grep -c 'flock' "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    [ "${output}" = "0" ]
+}
+
+@test "update: cleanup_on_error prints recovery guidance" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+
+        # Mock docker to prevent actual docker calls in cleanup
+        docker() { return 1; }
+
+        cleanup_on_error 2>&1
+    '
+    assert_success
+    assert_output --partial "Something went wrong unexpectedly"
+    assert_output --partial "safe to re-run"
+}
+
+@test "update: cleanup_on_error mentions stash when STASHED=true" {
+    run bash -c '
+        DAAF_TEST_MODE=1 source "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+        trap - ERR
+        set +eu
+
+        docker() { return 1; }
+        STASHED=true
+
+        cleanup_on_error 2>&1
+    '
+    assert_success
+    assert_output --partial "stash pop"
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "update_daaf.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+}
+
+@test "update_daaf.sh: dry-run reports already up to date" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/update_daaf.sh" 2>&1
+    assert_success
+    assert_output --partial "Already up to date"
+}
+
+# ============================================================================
+# Integrated state-machine tests
+# ============================================================================
+# These test the MAIN ORCHESTRATION flow (not individual helper functions).
+# The script is run as a full process with carefully crafted docker mock
+# responses that dispatch on the git subcommand arguments.
+
+# --- Helper: create a dispatch-based docker mock ---
+# Sets up a docker function that dispatches on the full argument string.
+# Callers configure behavior via MOCK_* variables before running the script.
+setup_state_machine() {
+    create_fake_compose_file
+    export DAAF_NESTED=1
+}
+
+@test "update: clean pull path succeeds (behind, no local commits, no dirty files)" {
+    setup_state_machine
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *"compose exec"*"true"*) return 0 ;;
+                *"compose exec"*"test -f"*"/daaf/CLAUDE.md"*) return 0 ;;
+                *"compose exec"*"test -f"*"/daaf/.git/shallow"*) return 1 ;;
+                *"compose exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"compose exec"*"fetch"*) return 0 ;;
+                *"compose exec"*"rev-parse --verify"*"backup/"*) return 1 ;;
+                *"compose exec"*"rev-parse --verify"*"origin/main"*) return 0 ;;
+                *"compose exec"*"branch --show-current"*) echo "main" ;;
+                *"compose exec"*"rev-parse"*"origin/main"*) echo "def456remote" ;;
+                *"compose exec"*"rev-parse"*"HEAD"*) echo "abc123local" ;;
+                *"compose exec"*"diff --name-only"*"HEAD"*) echo "" ;;
+                *"compose exec"*"rev-list --count"*"origin/main..HEAD"*) echo "0" ;;
+                *"compose exec"*"rev-list --count"*"HEAD..origin/main"*) echo "3" ;;
+                *"compose exec"*"pull"*) echo "Updating abc123..def456" ; return 0 ;;
+                *"compose exec"*"branch"*) return 0 ;;
+                *"compose exec"*"symbolic-ref"*) echo "main" ;;
+                "cp"*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "Update complete!"
+    assert_output --partial "Pulling updates..."
+}
+
+@test "update: already up to date exits cleanly (same SHA, no dirty files)" {
+    setup_state_machine
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *"compose exec"*"true"*) return 0 ;;
+                *"compose exec"*"test -f"*"/daaf/CLAUDE.md"*) return 0 ;;
+                *"compose exec"*"test -f"*"/daaf/.git/shallow"*) return 1 ;;
+                *"compose exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"compose exec"*"fetch"*) return 0 ;;
+                *"compose exec"*"rev-parse --verify"*"backup/"*) return 1 ;;
+                *"compose exec"*"rev-parse --verify"*"origin/main"*) return 0 ;;
+                *"compose exec"*"branch --show-current"*) echo "main" ;;
+                *"compose exec"*"rev-parse"*"origin/main"*) echo "abc123same" ;;
+                *"compose exec"*"rev-parse"*"HEAD"*) echo "abc123same" ;;
+                *"compose exec"*"diff --name-only"*"HEAD"*) echo "" ;;
+                *"compose exec"*"branch"*) return 0 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_success
+    assert_output --partial "Already up to date"
+}
+
+@test "update: no remote configured exits with guidance" {
+    setup_state_machine
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *"compose exec"*"true"*) return 0 ;;
+                *"compose exec"*"test -f"*) return 0 ;;
+                *"compose exec"*"remote get-url"*) echo "" ; return 1 ;;
+                *"compose exec"*"branch"*) return 0 ;;
+                *"compose exec"*"rev-parse"*"HEAD"*) echo "abc123" ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    # exit 0 with guidance message
+    assert_success
+    assert_output --partial "not connected to the update server"
+}
+
+@test "update: network failure during fetch exits with error" {
+    setup_state_machine
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *"compose exec"*"true"*) return 0 ;;
+                *"compose exec"*"test -f"*) return 0 ;;
+                *"compose exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"compose exec"*"fetch"*) echo "fatal: unable to access" >&2 ; return 1 ;;
+                *"compose exec"*"branch"*) return 0 ;;
+                *"compose exec"*"rev-parse"*"HEAD"*) echo "abc123" ;;
+                *"compose exec"*"rev-parse --verify"*"backup/"*) return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "Failed to fetch"
+}
+
+@test "update: lock contention exits with already running message" {
+    setup_state_machine
+    # Create the lock directory before running the script
+    mkdir -p /tmp/daaf-update.lock.d
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "already running"
+    # Clean up the lock
+    rmdir /tmp/daaf-update.lock.d 2>/dev/null || true
+}
+
+@test "update: lock cleanup on exit (trap removes lock dir)" {
+    setup_state_machine
+    # Run the script in dry-run mode so it completes cleanly, then check that
+    # the lock directory no longer exists.
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/update_daaf.sh"
+    assert_success
+    # Lock directory should be cleaned up by the EXIT trap
+    [ ! -d /tmp/daaf-update.lock.d ]
+}
+
+# ============================================================================
+# Error path tests
+# ============================================================================
+
+@test "update: container not running and start fails exits with error" {
+    setup_state_machine
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*) echo "" ;;
+                *"compose up"*) echo "ERROR: Cannot start" >&2 ; return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "Failed to start"
+}
+
+@test "update: DAAF not installed (CLAUDE.md missing) exits with error" {
+    setup_state_machine
+    run bash -c '
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *"compose exec"*"true"*) return 0 ;;
+                *"compose exec"*"test -f"*/daaf/CLAUDE.md*) return 1 ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "DAAF does not appear to be installed"
+}
+
+@test "update: DAAF_BRANCH specifies nonexistent branch exits with error" {
+    setup_state_machine
+    run bash -c '
+        export DAAF_BRANCH="nonexistent-branch-xyz"
+        docker() {
+            local all_args="$*"
+            case "$all_args" in
+                "info") return 0 ;;
+                *"compose ps"*"--format"*) echo "daaf-docker" ;;
+                *"compose exec"*"true"*) return 0 ;;
+                *"compose exec"*"test -f"*"/daaf/CLAUDE.md"*) return 0 ;;
+                *"compose exec"*"test -f"*"/daaf/.git/shallow"*) return 1 ;;
+                *"compose exec"*"remote get-url"*"origin"*) echo "https://github.com/DAAF-Contribution-Community/daaf.git" ;;
+                *"compose exec"*"fetch"*) return 0 ;;
+                *"compose exec"*"rev-parse --verify"*"backup/"*) return 1 ;;
+                *"compose exec"*"rev-parse --verify"*"origin/nonexistent-branch-xyz"*) return 1 ;;
+                *"compose exec"*"branch"*) return 0 ;;
+                *"compose exec"*"rev-parse"*"HEAD"*) echo "abc123" ;;
+                *) return 0 ;;
+            esac
+        }
+        export -f docker
+        bash "'"${REPO_ROOT}"'/scripts/host/update_daaf.sh"
+    '
+    assert_failure
+    assert_output --partial "nonexistent-branch-xyz"
+    assert_output --partial "was not found"
+}
diff --git a/tests/bash/view_logs.bats b/tests/bash/view_logs.bats
new file mode 100755
index 0000000..c94d19f
--- /dev/null
+++ b/tests/bash/view_logs.bats
@@ -0,0 +1,271 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for view_logs.sh -- DAAF Log Explorer
+# ============================================================================
+# Thin wrapper script -- tests focus on preflight checks, argument parsing,
+# menu structure, and dry-run behavior.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    create_fake_compose_file
+}
+
+teardown() {
+    common_teardown
+}
+
+# --- Syntax ---
+
+@test "view_logs.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+}
+
+# --- Preflight: missing docker-compose.yml ---
+
+@test "view_logs.sh fails when docker-compose.yml is missing" {
+    rm -f docker-compose.yml
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+# --- Preflight: missing Docker ---
+
+@test "view_logs.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "view_logs.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "view_logs.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_INFO_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    refute_output --partial "Press Enter"
+}
+
+# --- Container start when not running ---
+
+@test "view_logs.sh attempts to start container when not running" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT=""
+    MOCK_DOCKER_COMPOSE_EXIT=0
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_output --partial "Starting DAAF container"
+}
+
+# --- Log Explorer invocation ---
+
+@test "view_logs.sh references generate_log_viewer.sh" {
+    run grep -c "generate_log_viewer.sh" "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# --- Argument parsing ---
+
+@test "view_logs.sh --archive skips menu and opens log explorer" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh" --archive
+    assert_success
+    assert_output --partial "Opening DAAF Log Explorer"
+}
+
+@test "view_logs.sh --help shows usage" {
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh" --help
+    assert_success
+    assert_output --partial "Usage"
+    assert_output --partial "--archive"
+}
+
+@test "view_logs.sh rejects unknown arguments" {
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh" --bogus
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Unknown argument"
+}
+
+# --- Script structure ---
+
+@test "view_logs.sh includes recovery step" {
+    run grep -c "recover-session-logs" "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_logs.sh includes menu selection prompt" {
+    run grep -c "Select a log source" "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_logs.sh skips menu when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+    refute_output --partial "Select a log source"
+    assert_output --partial "Opening DAAF Log Explorer"
+}
+
+# =========================================================================
+# Dry-run mode
+# =========================================================================
+
+@test "view_logs.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+}
+
+@test "view_logs.sh: dry-run opens log explorer" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_logs.sh" 2>&1
+    assert_success
+    assert_output --partial "Log Explorer"
+}
+
+@test "view_logs.sh: dry-run skips menu" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_logs.sh" 2>&1
+    assert_success
+    refute_output --partial "Select a log source"
+}
+
+@test "view_logs.sh: dry-run skips sleep" {
+    # Dry-run should not sleep 2 seconds
+    start_time=$SECONDS
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_logs.sh" 2>&1
+    elapsed=$((SECONDS - start_time))
+    assert_success
+    [ "$elapsed" -lt 2 ]
+}
+
+@test "view_logs.sh: dry-run includes recovery step" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_logs.sh" 2>&1
+    assert_success
+    assert_output --partial "orphaned session logs"
+}
+
+# =========================================================================
+# --- Error paths ---
+# =========================================================================
+
+@test "view_logs: --help flag prints usage and exits successfully" {
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh" --help
+    assert_success
+    assert_output --partial "Usage"
+    assert_output --partial "--archive"
+}
+
+@test "view_logs: unknown argument exits with error" {
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh" --invalid-flag
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Unknown argument"
+}
+
+@test "view_logs: no log sources found exits with message" {
+    export DAAF_NESTED=1
+
+    # Mock docker: container is running, exec for discovery returns empty, exec for
+    # recovery returns ok, exec for generate_log_viewer returns ok
+    docker() {
+        case "$1" in
+            info) return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    ps) echo "daaf-docker" ; return 0 ;;
+                    exec)
+                        shift
+                        local args_str="$*"
+                        if [[ "${args_str}" == *"discover_log_sources"* ]]; then
+                            # No log sources
+                            echo ""
+                            return 0
+                        elif [[ "${args_str}" == *"recover-session-logs"* ]]; then
+                            return 0
+                        elif [[ "${args_str}" == *"generate_log_viewer"* ]]; then
+                            return 0
+                        fi
+                        return 0
+                        ;;
+                    up) return 0 ;;
+                    *) return 0 ;;
+                esac ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+
+    # Force interactive mode off by NOT setting DAAF_NESTED (but the script
+    # checks for /dev/tty and -t 1 which fail in bats, so SKIP_MENU will be
+    # set anyway). In non-interactive mode, it defaults to --archive and skips
+    # the menu. We need interactive mode to test "no log sources" path.
+    # Actually, in non-interactive contexts the script sets SKIP_MENU=true
+    # and goes directly to archive view, so the "no sources" path only fires
+    # in interactive mode. Since bats is non-interactive, we verify the
+    # structural presence of the feature instead.
+    run grep -c "No log sources found" "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_success
+}
+
+@test "view_logs: --archive flag skips menu" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_EXEC_EXIT=0
+
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh" --archive
+    assert_success
+    assert_output --partial "Opening DAAF Log Explorer"
+    refute_output --partial "Select a log source"
+}
+
+@test "view_logs: container not running starts it" {
+    export DAAF_NESTED=1
+
+    docker() {
+        case "$1" in
+            info) return 0 ;;
+            compose)
+                shift
+                case "$1" in
+                    ps) echo "" ; return 0 ;;
+                    up) return 0 ;;
+                    exec) return 0 ;;
+                    *) return 0 ;;
+                esac ;;
+            *) return 0 ;;
+        esac
+    }
+    export -f docker
+
+    run bash "${REPO_ROOT}/scripts/host/view_logs.sh"
+    assert_output --partial "Starting DAAF container"
+}
diff --git a/tests/bash/view_notebooks.bats b/tests/bash/view_notebooks.bats
new file mode 100644
index 0000000..e191da8
--- /dev/null
+++ b/tests/bash/view_notebooks.bats
@@ -0,0 +1,212 @@
+#!/usr/bin/env bats
+# ============================================================================
+# Tests for view_notebooks.sh -- DAAF Notebook Browser
+# ============================================================================
+# Thin wrapper script -- tests focus on preflight checks, container lifecycle,
+# dry-run behavior, and structural markers.
+# ============================================================================
+
+load 'test_helper'
+
+setup() {
+    common_setup
+    mock_docker
+    create_fake_compose_file
+}
+
+teardown() {
+    common_teardown
+}
+
+# =========================================================================
+# Tier 1 -- Syntax
+# =========================================================================
+
+@test "view_notebooks.sh parses without errors" {
+    run bash -n "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+}
+
+# =========================================================================
+# Tier 2 -- Preflight checks
+# =========================================================================
+
+# --- Preflight: missing docker-compose.yml ---
+
+@test "view_notebooks.sh fails when docker-compose.yml is missing" {
+    rm -f docker-compose.yml
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "docker-compose.yml"
+}
+
+# --- Preflight: missing Docker ---
+
+@test "view_notebooks.sh fails when docker command is not found" {
+    mock_no_docker
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker"
+}
+
+# --- Preflight: Docker daemon not running ---
+
+@test "view_notebooks.sh fails when Docker daemon is not running" {
+    MOCK_DOCKER_INFO_EXIT=1
+    export DAAF_NESTED=1
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Docker Desktop"
+}
+
+# --- DAAF_NESTED behavior ---
+
+@test "view_notebooks.sh suppresses pause trap when DAAF_NESTED=1" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_INFO_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    refute_output --partial "Press Enter"
+}
+
+# =========================================================================
+# Tier 3 -- Script structure
+# =========================================================================
+
+@test "view_notebooks.sh includes set -euo pipefail" {
+    run grep -c "set -euo pipefail" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh checks for docker-compose.yml" {
+    run grep -c "docker-compose.yml" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh checks command -v docker" {
+    run grep -c "command -v docker" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh checks docker info" {
+    run grep -c "docker info" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh references launch_marimo.sh" {
+    run grep -c "launch_marimo.sh" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh mentions Notebook Browser in output" {
+    run grep -c "Notebook Browser" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh supports DAAF_TEST_MODE guard" {
+    run grep -c "DAAF_TEST_MODE" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+@test "view_notebooks.sh supports DAAF_DRY_RUN" {
+    run grep -c "DAAF_DRY_RUN" "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+    [ "${output}" -ge 1 ]
+}
+
+# =========================================================================
+# Tier 4 -- Behavioral (DAAF_TEST_MODE)
+# =========================================================================
+
+@test "view_notebooks.sh exits cleanly when sourced with DAAF_TEST_MODE=1" {
+    export DAAF_TEST_MODE=1
+    run bash -c "source '${REPO_ROOT}/scripts/host/view_notebooks.sh'"
+    assert_success
+}
+
+# =========================================================================
+# Tier 5 -- Dry-run
+# =========================================================================
+
+@test "view_notebooks.sh: dry-run completes successfully" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_success
+}
+
+@test "view_notebooks.sh: dry-run completes without real Docker" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_notebooks.sh" 2>&1
+    assert_success
+    assert_output --partial "DAAF container is running"
+    assert_output --partial "Notebook Browser"
+}
+
+@test "view_notebooks.sh: dry-run shows Notebook Browser message" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_notebooks.sh" 2>&1
+    assert_success
+    assert_output --partial "Notebook Browser"
+}
+
+@test "view_notebooks.sh: dry-run reports container running" {
+    run env DAAF_DRY_RUN=1 DAAF_NESTED=1 bash "${REPO_ROOT}/scripts/host/view_notebooks.sh" 2>&1
+    assert_success
+    assert_output --partial "DAAF container is running"
+}
+
+# =========================================================================
+# Tier 6 -- Error paths
+# =========================================================================
+
+# --- Container not running → start attempt ---
+
+@test "view_notebooks.sh attempts to start container when not running" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT=""
+    MOCK_DOCKER_COMPOSE_EXIT=0
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_output --partial "Starting DAAF container"
+}
+
+# --- Container start fails ---
+
+@test "view_notebooks.sh fails when container start fails" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT=""
+    MOCK_DOCKER_COMPOSE_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_failure
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start the container"
+}
+
+# --- Notebook browser launch fails ---
+
+@test "view_notebooks.sh reports error when notebook browser fails to start" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=1
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_output --partial "ERROR"
+    assert_output --partial "Failed to start the notebook browser"
+}
+
+# --- Container already running ---
+
+@test "view_notebooks.sh reports container already running" {
+    export DAAF_NESTED=1
+    MOCK_DOCKER_PS_OUTPUT="daaf-docker"
+    MOCK_DOCKER_EXEC_EXIT=0
+    run bash "${REPO_ROOT}/scripts/host/view_notebooks.sh"
+    assert_output --partial "DAAF container is running"
+}
diff --git a/tests/lint/check-daaf-conventions.sh b/tests/lint/check-daaf-conventions.sh
new file mode 100755
index 0000000..ce13aea
--- /dev/null
+++ b/tests/lint/check-daaf-conventions.sh
@@ -0,0 +1,225 @@
+#!/usr/bin/env bash
+# ============================================================================
+# DAAF Convention Lint — custom checks beyond ShellCheck / PSScriptAnalyzer
+# ============================================================================
+# Checks DAAF-specific patterns that standard linters do not cover:
+#   1. Bash preamble: shebang + set -euo pipefail (or set -eu / trap ERR)
+#   2. PowerShell preamble: $ErrorActionPreference in first 15 code lines
+#   3. DAAF_NESTED consistency: host lifecycle scripts reference DAAF_NESTED
+#   4. Numbered progress: host lifecycle scripts use [N/M] indicators (warn only)
+#
+# Usage:
+#   bash tests/lint/check-daaf-conventions.sh
+#   bash tests/lint/check-daaf-conventions.sh /path/to/repo
+#
+# Exit codes:
+#   0 — all checks pass
+#   1 — one or more checks failed
+# ============================================================================
+
+set -euo pipefail
+
+REPO_ROOT="${1:-$(cd "$(dirname "$0")/../.." && pwd)}"
+FAIL_COUNT=0
+WARN_COUNT=0
+
+# Colors (disabled if NO_COLOR is set or stdout is not a terminal)
+if [ -z "${NO_COLOR:-}" ] && [ -t 1 ]; then
+    RED='\033[0;31m'
+    YELLOW='\033[0;33m'
+    GREEN='\033[0;32m'
+    RESET='\033[0m'
+else
+    RED=''
+    YELLOW=''
+    GREEN=''
+    RESET=''
+fi
+
+fail() {
+    printf "${RED}FAIL${RESET}: %s\n" "$1"
+    FAIL_COUNT=$((FAIL_COUNT + 1))
+}
+
+warn() {
+    printf "${YELLOW}WARN${RESET}: %s\n" "$1"
+    WARN_COUNT=$((WARN_COUNT + 1))
+}
+
+pass() {
+    printf "${GREEN}PASS${RESET}: %s\n" "$1"
+}
+
+echo ""
+echo "=========================================="
+echo "  DAAF Convention Lint"
+echo "=========================================="
+echo ""
+echo "Repository: ${REPO_ROOT}"
+echo ""
+
+# =====================================================================
+# 1. Bash preamble check
+# =====================================================================
+echo "--- Bash preamble checks ---"
+
+# Find all .sh files (excluding .git, node_modules, test libs)
+while IFS= read -r -d '' shfile; do
+    # Skip files inside .git, node_modules, test libraries, .claude/, and
+    # scripts/ root-level utility scripts (which use specialized error
+    # patterns — managed separately). scripts/host/ lifecycle scripts ARE
+    # checked.
+    case "${shfile}" in
+        */.git/*|*/node_modules/*|*/libs/*|*/.claude/*|*/research/*) continue ;;
+        */scripts/*.sh) # Skip root-level scripts/ utilities (not in subdirs)
+            case "${shfile}" in
+                */scripts/host/*) ;; # Allow host lifecycle scripts through
+                *) continue ;;
+            esac
+            ;;
+    esac
+
+    filename=$(basename "${shfile}")
+    relpath="${shfile#"${REPO_ROOT}/"}"
+
+    # Check shebang (first line)
+    # Accept: #!/usr/bin/env bash, #!/usr/bin/env bats, #!/bin/bash, #!/bin/sh
+    first_line=$(head -1 "${shfile}")
+    case "${first_line}" in
+        "#!/usr/bin/env bash"|"#!/usr/bin/env bats"|"#!/bin/bash"|"#!/bin/sh")
+            ;; # Valid shebang
+        *)
+            fail "${relpath}: missing or non-standard shebang (got: '${first_line}')"
+            ;;
+    esac
+
+    # Check for error handling in first 10 non-comment, non-blank code lines.
+    # Counting code lines (not raw lines) is robust against variable-length
+    # comment headers — even a 100-line documentation block won't cause a
+    # false failure as long as error handling appears early in actual code.
+    # Accept any of:
+    #   - set -euo pipefail  (preferred)
+    #   - set -eu            (minimum)
+    #   - set -o pipefail    (used by some utility scripts)
+    #   - trap ... ERR       (fail-closed pattern used by hooks)
+    code_lines=$(awk '!/^\s*#/ && !/^\s*$/ { print; if (++n == 10) exit }' "${shfile}")
+    if ! echo "${code_lines}" | grep -qE 'set -e|trap .* ERR'; then
+        # Allow BATS test files and test helpers to skip strict mode
+        case "${filename}" in
+            *.bats|test_helper.bash) ;;
+            *)
+                fail "${relpath}: missing error handling (set -e / set -euo pipefail / trap ERR) in first 10 code lines"
+                ;;
+        esac
+    fi
+done < <(find "${REPO_ROOT}" -name '*.sh' -type f -not -path '*/.git/*' -print0)
+
+echo ""
+
+# =====================================================================
+# 2. PowerShell preamble check
+# =====================================================================
+echo "--- PowerShell preamble checks ---"
+
+while IFS= read -r -d '' ps1file; do
+    case "${ps1file}" in
+        */.git/*|*/node_modules/*|*/libs/*) continue ;;
+    esac
+
+    relpath="${ps1file#"${REPO_ROOT}/"}"
+    filename=$(basename "${ps1file}")
+
+    # Skip test files (*.Tests.ps1) and helpers (TestHelper.ps1)
+    case "${filename}" in
+        *.Tests.ps1|TestHelper.ps1) continue ;;
+    esac
+
+    # Check for $ErrorActionPreference in first 15 non-comment, non-blank code lines.
+    # PowerShell comments start with # (like bash). Counting code lines is robust
+    # against variable-length comment headers and dry-run blocks.
+    code_lines=$(awk '!/^\s*#/ && !/^\s*$/ { print; if (++n == 15) exit }' "${ps1file}")
+    if ! echo "${code_lines}" | grep -q 'ErrorActionPreference'; then
+        fail "${relpath}: missing '\$ErrorActionPreference' in first 15 code lines"
+    fi
+done < <(find "${REPO_ROOT}" -name '*.ps1' -type f -not -path '*/.git/*' -print0)
+
+echo ""
+
+# =====================================================================
+# 3. DAAF_NESTED consistency
+# =====================================================================
+echo "--- DAAF_NESTED consistency checks ---"
+
+# Host lifecycle .sh scripts (scripts/host/ — compose with each other)
+for shfile in "${REPO_ROOT}"/scripts/host/*.sh; do
+    [ -f "${shfile}" ] || continue
+    filename=$(basename "${shfile}")
+
+    if ! grep -q 'DAAF_NESTED' "${shfile}"; then
+        fail "scripts/host/${filename}: lifecycle script does not reference DAAF_NESTED"
+    else
+        pass "scripts/host/${filename}: references DAAF_NESTED"
+    fi
+done
+
+# Host lifecycle .ps1 scripts
+for ps1file in "${REPO_ROOT}"/scripts/host/*.ps1; do
+    [ -f "${ps1file}" ] || continue
+    filename=$(basename "${ps1file}")
+
+    if ! grep -q 'DAAF_NESTED' "${ps1file}"; then
+        fail "scripts/host/${filename}: lifecycle script does not reference DAAF_NESTED"
+    else
+        pass "scripts/host/${filename}: references DAAF_NESTED"
+    fi
+done
+
+echo ""
+
+# =====================================================================
+# 4. Numbered progress pattern (warn only)
+# =====================================================================
+echo "--- Progress indicator checks (warnings only) ---"
+
+for shfile in "${REPO_ROOT}"/scripts/host/*.sh; do
+    [ -f "${shfile}" ] || continue
+    filename=$(basename "${shfile}")
+
+    if ! grep -qE '\[[0-9]+/[0-9]+\]' "${shfile}"; then
+        warn "scripts/host/${filename}: no [N/M] progress indicators found"
+    else
+        pass "scripts/host/${filename}: has [N/M] progress indicators"
+    fi
+done
+
+for ps1file in "${REPO_ROOT}"/scripts/host/*.ps1; do
+    [ -f "${ps1file}" ] || continue
+    filename=$(basename "${ps1file}")
+
+    if ! grep -qE '\[[0-9]+/[0-9]+\]' "${ps1file}"; then
+        warn "scripts/host/${filename}: no [N/M] progress indicators found"
+    else
+        pass "scripts/host/${filename}: has [N/M] progress indicators"
+    fi
+done
+
+echo ""
+
+# =====================================================================
+# Summary
+# =====================================================================
+echo "=========================================="
+echo "  Summary"
+echo "=========================================="
+echo ""
+echo "  Failures: ${FAIL_COUNT}"
+echo "  Warnings: ${WARN_COUNT}"
+echo ""
+
+if [ "${FAIL_COUNT}" -gt 0 ]; then
+    printf "${RED}Convention lint FAILED with ${FAIL_COUNT} error(s).${RESET}\n"
+    exit 1
+else
+    printf "${GREEN}Convention lint passed (${WARN_COUNT} warning(s)).${RESET}\n"
+    exit 0
+fi
diff --git a/tests/powershell/TestHelper.ps1 b/tests/powershell/TestHelper.ps1
new file mode 100644
index 0000000..1e9a3f8
--- /dev/null
+++ b/tests/powershell/TestHelper.ps1
@@ -0,0 +1,95 @@
+# ============================================================================
+# Pester Test Helper -- shared setup for all DAAF PowerShell script tests
+# ============================================================================
+# Dot-source this from every .Tests.ps1 file in BeforeAll:
+#   . "$PSScriptRoot/TestHelper.ps1"
+#
+# Provides:
+#   - $RepoRoot  -- absolute path to the repository root
+#   - Common test directory setup/teardown patterns (documented below)
+#   - Notes on Docker mock patterns for Pester
+# ============================================================================
+
+# Path to the repository root (parent of tests/powershell/)
+$script:RepoRoot = (Resolve-Path "$PSScriptRoot/../..").Path
+
+# ============================================================================
+# Test Directory Lifecycle
+# ============================================================================
+# Use these patterns in your Describe/Context blocks:
+#
+#   BeforeAll {
+#       . "$PSScriptRoot/TestHelper.ps1"
+#       $script:TestDir = New-Item -ItemType Directory -Path (Join-Path $env:TEMP "daaf-test-$(Get-Random)")
+#       Push-Location $script:TestDir
+#   }
+#
+#   AfterAll {
+#       Pop-Location
+#       Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+#   }
+
+# ============================================================================
+# Docker Mock Patterns
+# ============================================================================
+# Pester cannot mock native commands directly. The pattern is:
+#
+# 1. Declare a function with the same name:
+#      function docker {}
+#
+# 2. Mock the function:
+#      Mock docker { $global:LASTEXITCODE = 0; return "mock output" }
+#
+# 3. For testing failure:
+#      Mock docker { $global:LASTEXITCODE = 1 }
+#
+# 4. Verify calls:
+#      Should -Invoke docker -Times 1
+#
+# IMPORTANT: The function declaration (step 1) must appear BEFORE the Mock
+# call. Place it in BeforeAll or Context-level BeforeAll.
+
+# ============================================================================
+# Syntax Validation Helper
+# ============================================================================
+# Validates that a PowerShell script parses without syntax errors.
+# Returns the error collection (empty array means no errors).
+
+function Test-ScriptSyntax {
+    param(
+        [Parameter(Mandatory)]
+        [string]$Path
+    )
+
+    $errors = $null
+    $tokens = $null
+    [System.Management.Automation.Language.Parser]::ParseFile(
+        $Path,
+        [ref]$tokens,
+        [ref]$errors
+    ) | Out-Null
+    return $errors
+}
+
+# ============================================================================
+# Fake docker-compose.yml Creator
+# ============================================================================
+
+function New-FakeComposeFile {
+    [Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseShouldProcessForStateChangingFunctions', '')]
+    param(
+        [string]$Directory = (Get-Location).Path
+    )
+
+    $content = @"
+name: daaf
+services:
+  daaf-docker:
+    image: daaf:latest
+    volumes:
+      - daaf-data:/daaf
+volumes:
+  daaf-data:
+"@
+    Set-Content -Path (Join-Path $Directory "docker-compose.yml") -Value $content
+}
diff --git a/tests/powershell/backup_daaf.Tests.ps1 b/tests/powershell/backup_daaf.Tests.ps1
new file mode 100644
index 0000000..b5bcb2e
--- /dev/null
+++ b/tests/powershell/backup_daaf.Tests.ps1
@@ -0,0 +1,257 @@
+# ============================================================================
+# Pester tests for backup_daaf.ps1 -- DAAF Backup Utility (Windows)
+# ============================================================================
+
+Describe "backup_daaf.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/backup_daaf.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/backup_daaf.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "checks volume exists" {
+            $Content | Should -Match 'docker volume inspect'
+        }
+
+        It "uses date-based backup naming" {
+            $Content | Should -Match 'yyyy-MM-dd'
+        }
+
+        It "implements suffix versioning (a, b, c)" {
+            $Content | Should -Match '\[char\]\(97 \+ \$SuffixNum\)'
+        }
+
+        It "limits to 26 backups per day" {
+            $Content | Should -Match '26'
+            $Content | Should -Match 'Too many backups'
+        }
+
+        It "scans Docker volume for file count" {
+            $Content | Should -Match 'Scanning Docker volume'
+        }
+
+        It "displays progress during copy" {
+            $Content | Should -Match 'Progress:'
+        }
+
+        It "verifies file count after backup" {
+            $Content | Should -Match 'files copied'
+        }
+
+        It "uses cp -a (not cp -r) for permission-preserving copy" {
+            $Content | Should -Match 'cp -a /source/\. /dest/'
+            $Content | Should -Not -Match 'cp -r /source/\. /dest/'
+        }
+
+        It "checks available disk space before copying" {
+            $Content | Should -Match 'Insufficient disk space'
+            $Content | Should -Match 'System\.IO\.DriveInfo'
+        }
+
+        It "performs size-based backup verification" {
+            $Content | Should -Match 'Size verification'
+            $Content | Should -Match 'Backup size mismatch'
+        }
+
+        It "docker scan command uses safe quoting for Windows arg passing" {
+            # Regression: embedded " in strings passed to native exes on Windows
+            # causes silent argument truncation. See shell-scripting gotchas.md.
+            $scanLine = ($Content -split "`n") | Where-Object { $_ -match 'stat.*awk' }
+            $scanLine | Should -Not -BeNullOrEmpty
+            $scanLine | Should -Match 'stat -c %s'
+            $scanLine | Should -Match "awk '"
+        }
+    }
+}
+
+# ============================================================================
+# Behavioral tests -- dot-source to verify functions + source analysis
+# ============================================================================
+
+Describe "backup_daaf.ps1 behavioral tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+
+        $env:DAAF_TEST_MODE = "1"
+        . "$RepoRoot/scripts/host/backup_daaf.ps1"
+
+        $script:Content = Get-Content "$RepoRoot/scripts/host/backup_daaf.ps1" -Raw
+    }
+
+    AfterAll {
+        Remove-Item Env:DAAF_TEST_MODE -ErrorAction SilentlyContinue
+    }
+
+    # -----------------------------------------------------------------
+    # Wait-AndExit (the only function exposed)
+    # -----------------------------------------------------------------
+    Context "Wait-AndExit function" {
+        It "is callable after dot-sourcing" {
+            Get-Command Wait-AndExit -ErrorAction SilentlyContinue |
+                Should -Not -BeNullOrEmpty
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Suffix generation logic (verified via source analysis)
+    # -----------------------------------------------------------------
+    Context "Suffix generation" {
+        It "first backup of the day has no suffix" {
+            # The initial BackupName has no suffix character
+            $Content | Should -Match '\$BackupName = "\$\{Today\}_daaf_backup"'
+        }
+
+        It "generates suffix 'a' for second backup (when unsuffixed exists)" {
+            # SuffixNum starts at 0 => [char](97 + 0) = 'a'
+            $Content | Should -Match '\[char\]\(97 \+ \$SuffixNum\)'
+            # Starting SuffixNum is 0
+            $Content | Should -Match '\$SuffixNum = 0'
+        }
+
+        It "increments suffix for subsequent backups" {
+            $Content | Should -Match '\$SuffixNum\+\+'
+        }
+
+        It "handles suffix exhaustion (a-z all used)" {
+            $Content | Should -Match '\$SuffixNum -ge 26'
+            $Content | Should -Match 'Too many backups for today \(26 max\)'
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Integrity verification
+    # -----------------------------------------------------------------
+    Context "Integrity verification" {
+        It "backup includes size verification" {
+            $Content | Should -Match 'Size verification'
+            # Compares source vs backup logical byte sums
+            $Content | Should -Match '\$SourceSizeKB'
+            $Content | Should -Match '\$BackupSizeKB'
+        }
+
+        It "backup includes file count check" {
+            $Content | Should -Match '\$FileCount'
+            # Verifies FileCount is non-zero
+            $Content | Should -Match '\$FileCount -eq 0'
+        }
+
+        It "size comparison uses 1% tolerance" {
+            $Content | Should -Match '\$SourceSizeKB / 100'
+            $Content | Should -Match '\$ToleranceKB'
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Disk space pre-check
+    # -----------------------------------------------------------------
+    Context "Disk space" {
+        It "checks available disk space before backup" {
+            $Content | Should -Match 'System\.IO\.DriveInfo'
+            $Content | Should -Match 'AvailableFreeSpace'
+        }
+
+        It "adds 10% buffer to required space" {
+            $Content | Should -Match '\$VolumeSizeKB \* 110 / 100'
+        }
+
+        It "aborts with clear message when space insufficient" {
+            $Content | Should -Match 'Insufficient disk space for backup'
+            $Content | Should -Match '\$AvailableKB -lt \$RequiredKB'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "backup_daaf.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/backup_daaf.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "produces DRY-RUN markers in output" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/backup_daaf.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*``[DRY-RUN``]*"
+    }
+}
+
+# ============================================================================
+# Error paths
+# ============================================================================
+
+Describe "backup_daaf.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/backup_daaf.ps1" -Raw
+    }
+
+    Context "Copy operation fails with zero files" {
+        It "handles copy failure resulting in zero files (exit 1, ERROR)" {
+            # The script checks FileCount -eq 0 and CopyExitCode -ne 0, outputs ERROR
+            $Content | Should -Match 'Backup failed \(exit code'
+            $Content | Should -Match '\$FileCount -eq 0'
+        }
+    }
+
+    Context "Copy partially succeeds" {
+        It "handles non-zero exit but files copied (warning, not error)" {
+            # When CopyExitCode != 0 but FileCount > 0, script shows Note about warnings
+            $Content | Should -Match 'File copy reported warnings'
+            $Content | Should -Match 'files were transferred'
+        }
+    }
+
+    Context "Volume scan unexpected format" {
+        It "handles scan failure with error" {
+            # When docker run for scan fails (LASTEXITCODE != 0), script exits with error
+            $Content | Should -Match 'Could not scan Docker volume'
+        }
+    }
+}
diff --git a/tests/powershell/install.Tests.ps1 b/tests/powershell/install.Tests.ps1
new file mode 100644
index 0000000..f14ea8c
--- /dev/null
+++ b/tests/powershell/install.Tests.ps1
@@ -0,0 +1,284 @@
+# ============================================================================
+# Pester tests for install.ps1 -- DAAF One-Line Installer (Windows)
+# ============================================================================
+
+Describe "install.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/install.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/install.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-ForUser function" {
+            $Content | Should -Match 'function Wait-ForUser'
+        }
+
+        It "checks DAAF_NESTED in Wait-ForUser" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "uses numbered progress steps [1/4] through [4/4]" {
+            ($Content | Select-String -Pattern '\[1/4\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+            ($Content | Select-String -Pattern '\[2/4\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+            ($Content | Select-String -Pattern '\[3/4\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+            ($Content | Select-String -Pattern '\[4/4\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "checks for existing installation" {
+            $Content | Should -Match 'existing DAAF installation'
+        }
+
+        It "supports DAAF_BRANCH environment variable" {
+            $Content | Should -Match 'DAAF_BRANCH'
+        }
+
+        It "supports DAAF_FORCE_REINSTALL environment variable" {
+            $Content | Should -Match 'DAAF_FORCE_REINSTALL'
+        }
+
+        It "downloads required utility scripts" {
+            $Content | Should -Match 'run_daaf\.ps1'
+            $Content | Should -Match 'backup_daaf\.ps1'
+            $Content | Should -Match 'rebuild_daaf\.ps1'
+            $Content | Should -Match 'update_daaf\.ps1'
+            $Content | Should -Match 'view_logs\.ps1'
+        }
+
+        It "verifies CLAUDE.md exists in container" {
+            $Content | Should -Match 'CLAUDE\.md'
+        }
+
+        It "sets TLS 1.2 for GitHub downloads" {
+            $Content | Should -Match 'Tls12'
+        }
+    }
+}
+
+# ============================================================================
+# Behavioral tests -- dot-source to verify functions + source analysis
+# ============================================================================
+
+Describe "install.ps1 behavioral tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+
+        $env:DAAF_TEST_MODE = "1"
+        . "$RepoRoot/scripts/host/install.ps1"
+
+        $script:Content = Get-Content "$RepoRoot/scripts/host/install.ps1" -Raw
+    }
+
+    AfterAll {
+        Remove-Item Env:DAAF_TEST_MODE -ErrorAction SilentlyContinue
+    }
+
+    # -----------------------------------------------------------------
+    # Wait-ForUser (the only function exposed)
+    # -----------------------------------------------------------------
+    Context "Wait-ForUser function" {
+        It "is callable after dot-sourcing" {
+            # Verify the function is defined in the current scope
+            Get-Command Wait-ForUser -ErrorAction SilentlyContinue |
+                Should -Not -BeNullOrEmpty
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # URL construction and branch defaults
+    # -----------------------------------------------------------------
+    Context "URL construction" {
+        It "default branch is 'main'" {
+            # When DAAF_BRANCH is not set, $Branch defaults to "main"
+            $Content | Should -Match '\$Branch = if \(\$env:DAAF_BRANCH\) \{ \$env:DAAF_BRANCH \} else \{ "main" \}'
+        }
+
+        It "DAAF_BRANCH overrides default branch" {
+            $Content | Should -Match '\$env:DAAF_BRANCH'
+            # The config section uses $Branch throughout for URL construction
+            $Content | Should -Match '\$RawBase = "https://raw\.githubusercontent\.com/\$Repo/\$Branch"'
+        }
+
+        It "download URLs use scripts/host/ prefix" {
+            $Content | Should -Match '\$RawBase/scripts/host/'
+            # Verify specific script downloads reference scripts/host/
+            $Content | Should -Match 'scripts/host/run_daaf\.ps1'
+            $Content | Should -Match 'scripts/host/backup_daaf\.ps1'
+            $Content | Should -Match 'scripts/host/update_daaf\.ps1'
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Installation detection
+    # -----------------------------------------------------------------
+    Context "Installation detection" {
+        It "checks for existing docker-compose.yml" {
+            $Content | Should -Match 'Test-Path "\$InstallDir\\docker-compose\.yml"'
+        }
+
+        It "checks for existing Docker volume" {
+            $Content | Should -Match 'docker volume inspect daaf_daaf-data'
+        }
+
+        It "DAAF_FORCE_REINSTALL bypasses existing check" {
+            $Content | Should -Match '\$env:DAAF_FORCE_REINSTALL -eq "1"'
+            $Content | Should -Match 'Proceeding with re-install'
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Readiness verification
+    # -----------------------------------------------------------------
+    Context "Readiness verification" {
+        It "readiness check looks for CLAUDE.md" {
+            $Content | Should -Match 'test -f /daaf/CLAUDE\.md'
+        }
+
+        It "readiness check has retry logic for container startup" {
+            # The container readiness check uses a retry loop
+            $Content | Should -Match '\$maxRetries = 30'
+            $Content | Should -Match 'Start-Sleep -Seconds 2'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "install.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/install.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+        # Clean up the daaf-docker directory created by install.ps1
+        $installDir = Join-Path (Get-Location).Path "daaf-docker"
+        if (Test-Path $installDir) { Remove-Item -Recurse -Force $installDir -ErrorAction SilentlyContinue }
+    }
+
+    It "completes full installation flow" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/install.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Installation complete*"
+        # Clean up the daaf-docker directory created by install.ps1
+        $installDir = Join-Path (Get-Location).Path "daaf-docker"
+        if (Test-Path $installDir) { Remove-Item -Recurse -Force $installDir -ErrorAction SilentlyContinue }
+    }
+}
+
+# ============================================================================
+# Error paths
+# ============================================================================
+
+Describe "install.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/install.ps1" -Raw
+    }
+
+    Context "Build failure" {
+        It "outputs error when docker compose build fails" {
+            # Verify the script contains the build-failure error path
+            $Content | Should -Match 'Docker image build failed'
+            $Content | Should -Match 'LASTEXITCODE -ne 0'
+        }
+
+        It "suggests re-running installer on build failure" {
+            $Content | Should -Match 'DAAF_FORCE_REINSTALL'
+            $Content | Should -Match 're-run this installer'
+        }
+    }
+
+    Context "Container start failure" {
+        It "outputs error when docker compose up -d fails" {
+            $Content | Should -Match 'Failed to start the Docker container after build'
+        }
+    }
+
+    Context "Container readiness timeout" {
+        It "reports timeout when container does not become ready" {
+            $Content | Should -Match 'did not become ready within 60 seconds'
+            $Content | Should -Match '\$maxRetries = 30'
+        }
+
+        It "shows Docker error output on timeout" {
+            $Content | Should -Match 'Docker reported'
+        }
+    }
+
+    Context "Download failure" {
+        It "outputs error when Invoke-WebRequest fails" {
+            $Content | Should -Match "Failed to download installation files from branch"
+        }
+
+        It "suggests verifying branch name on download failure" {
+            $Content | Should -Match 'verify that the branch name is correct'
+        }
+    }
+
+    Context "Git clone failure" {
+        It "outputs error when git clone into container fails" {
+            $Content | Should -Match 'Failed to clone the DAAF repository'
+        }
+
+        It "outputs error when copy repo files fails" {
+            $Content | Should -Match 'Failed to copy repository files into the container'
+        }
+    }
+
+    Context "CLAUDE.md verification failure" {
+        It "warns when CLAUDE.md is not found post-install" {
+            $Content | Should -Match 'CLAUDE\.md was not found in the container'
+        }
+    }
+
+    Context "Force reinstall with existing volume" {
+        It "proceeds when DAAF_FORCE_REINSTALL is set" {
+            $Content | Should -Match 'Proceeding with re-install \(DAAF_FORCE_REINSTALL=1\)'
+        }
+    }
+
+    Context "Existing installation without force flag" {
+        It "blocks and warns about existing installation" {
+            $Content | Should -Match 'existing DAAF installation was detected'
+        }
+
+        It "suggests update_daaf.ps1 as alternative" {
+            $Content | Should -Match 'update_daaf\.ps1'
+        }
+    }
+}
diff --git a/tests/powershell/migrate_daaf.Tests.ps1 b/tests/powershell/migrate_daaf.Tests.ps1
new file mode 100644
index 0000000..c2fcc4c
--- /dev/null
+++ b/tests/powershell/migrate_daaf.Tests.ps1
@@ -0,0 +1,885 @@
+# ============================================================================
+# Pester tests for migrate_daaf.ps1 -- DAAF Migration Script (Windows)
+# ============================================================================
+
+Describe "migrate_daaf.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/migrate_daaf.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/migrate_daaf.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-ForUser function" {
+            $Content | Should -Match 'function Wait-ForUser'
+        }
+
+        It "checks DAAF_NESTED in Wait-ForUser" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "defines Read-UserChoice helper function" {
+            $Content | Should -Match 'function Read-UserChoice'
+        }
+
+        It "defines Invoke-ContainerGit helper function" {
+            $Content | Should -Match 'function Invoke-ContainerGit\b'
+        }
+
+        It "defines Invoke-ContainerGitVerbose helper function" {
+            $Content | Should -Match 'function Invoke-ContainerGitVerbose'
+        }
+
+        It "defines Invoke-ContainerExec helper function" {
+            $Content | Should -Match 'function Invoke-ContainerExec'
+        }
+
+        It "defines Invoke-ContainerShell helper function" {
+            $Content | Should -Match 'function Invoke-ContainerShell\b'
+        }
+
+        It "defines Invoke-ContainerShellVerbose helper function" {
+            $Content | Should -Match 'function Invoke-ContainerShellVerbose'
+        }
+
+        It "has a trap handler for unexpected failures" {
+            $Content | Should -Match 'trap \{'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "checks volume exists" {
+            $Content | Should -Match 'docker volume inspect'
+        }
+
+        It "supports DAAF_BRANCH environment variable" {
+            $Content | Should -Match 'DAAF_BRANCH'
+        }
+
+        It "detects non-interactive mode" {
+            $Content | Should -Match 'NonInteractive'
+        }
+
+        It "detects Era 1 (clone-based) installations" {
+            $Content | Should -Match 'clone-based installation'
+        }
+
+        It "detects Era 2 (ZIP-based) installations" {
+            $Content | Should -Match 'ZIP-based installation'
+        }
+
+        It "performs a backup before migration" {
+            $Content | Should -Match 'backup_daaf\.ps1'
+        }
+
+        It "handles fork detection" {
+            $Content | Should -Match 'IsFork'
+        }
+
+        It "performs graft for ERA 2 installations" {
+            $Content | Should -Match 'replace --graft'
+        }
+
+        It "fixes file permissions for ZIP downloads" {
+            $Content | Should -Match 'Fixing file permissions'
+        }
+
+        It "sets upstream tracking branch" {
+            $Content | Should -Match 'set-upstream-to=origin/main'
+        }
+
+        It "offers to run update after migration" {
+            $Content | Should -Match 'Run update'
+        }
+
+        It "sets TLS 1.2 for GitHub downloads" {
+            $Content | Should -Match 'Tls12'
+        }
+
+        It "claims idempotency in its header" {
+            $Content | Should -Match 'idempotent'
+        }
+    }
+}
+
+# ============================================================================
+# Behavioral tests -- dot-source the script and call functions directly
+# ============================================================================
+
+Describe "migrate_daaf.ps1 behavioral tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+
+        $env:DAAF_TEST_MODE = "1"
+        . "$RepoRoot/scripts/host/migrate_daaf.ps1"
+
+        # Declare a docker function so Pester can mock it
+        function docker {}
+    }
+
+    AfterAll {
+        Remove-Item Env:DAAF_TEST_MODE -ErrorAction SilentlyContinue
+    }
+
+    # -----------------------------------------------------------------
+    # Invoke-ContainerGit
+    # -----------------------------------------------------------------
+    Context "Invoke-ContainerGit" {
+        It "executes git command in container" {
+            Mock docker { return "mock-sha-output" }
+            $null = Invoke-ContainerGit rev-parse HEAD
+            Should -Invoke docker -Times 1
+        }
+
+        It "strips carriage returns from output" {
+            Mock docker { return "abc123`r`ndef456`r`n" }
+            $result = Invoke-ContainerGit log --oneline
+            $result | Should -Not -Match "`r"
+        }
+
+        It "returns trimmed output" {
+            Mock docker { return "  abc123  " }
+            $result = Invoke-ContainerGit rev-parse HEAD
+            $result | Should -Not -Match '^\s'
+            $result | Should -Not -Match '\s$'
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Invoke-ContainerGitVerbose
+    # -----------------------------------------------------------------
+    Context "Invoke-ContainerGitVerbose" {
+        It "preserves output content" {
+            Mock docker { return "verbose-fetch-progress" }
+            $result = Invoke-ContainerGitVerbose fetch origin
+            $result | Should -BeLike "*verbose-fetch*"
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Invoke-ContainerExec
+    # -----------------------------------------------------------------
+    Context "Invoke-ContainerExec" {
+        It "runs arbitrary command in container" {
+            Mock docker { $global:LASTEXITCODE = 0 }
+            Invoke-ContainerExec test -f /daaf/CLAUDE.md
+            Should -Invoke docker -Times 1
+            $LASTEXITCODE | Should -Be 0
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Invoke-ContainerShell / Invoke-ContainerShellVerbose
+    # -----------------------------------------------------------------
+    Context "Invoke-ContainerShell" {
+        It "runs shell command and returns string" {
+            Mock docker { return "shell-output-here" }
+            $result = Invoke-ContainerShell "echo hello"
+            $result | Should -BeLike "*shell-output*"
+        }
+
+        It "strips carriage returns" {
+            Mock docker { return "line1`r`nline2`r`n" }
+            $result = Invoke-ContainerShell "ls /daaf"
+            $result | Should -Not -Match "`r"
+        }
+    }
+
+    Context "Invoke-ContainerShellVerbose" {
+        It "returns output including stderr content" {
+            Mock docker { return "verbose-shell-output" }
+            $result = Invoke-ContainerShellVerbose "ls -la /daaf"
+            $result | Should -BeLike "*verbose-shell*"
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Read-UserChoice
+    # -----------------------------------------------------------------
+    Context "Read-UserChoice" {
+        # On CI runners, [Environment]::UserInteractive is false, which
+        # triggers the non-interactive auto-select path before Read-Host
+        # is called. To test the interactive read path, we define a
+        # test-only version that skips the interactivity check.
+        BeforeAll {
+            function Read-UserChoiceInteractive {
+                param([string]$PromptText, [string[]]$ValidChoices)
+                while ($true) {
+                    $choice = (Read-Host $PromptText).Trim().ToLower()
+                    if ($ValidChoices -contains $choice) { return $choice }
+                    Write-Host "  Please enter one of: $($ValidChoices -join ', ')" -ForegroundColor Yellow
+                }
+            }
+        }
+
+        It "returns valid selection" {
+            Mock Read-Host { return "y" }
+            $result = Read-UserChoiceInteractive "Choose [y/n]" @("y", "n")
+            $result | Should -Be "y"
+        }
+
+        It "normalizes input to lowercase" {
+            Mock Read-Host { return "Y" }
+            $result = Read-UserChoiceInteractive "Choose [y/n]" @("y", "n")
+            $result | Should -Be "y"
+        }
+
+        It "trims whitespace from input" {
+            Mock Read-Host { return "  n  " }
+            $result = Read-UserChoiceInteractive "Choose [y/n]" @("y", "n")
+            $result | Should -Be "n"
+        }
+
+        It "auto-selects first choice in non-interactive mode" {
+            $result = Read-UserChoice "Choose [y/n]" @("y", "n")
+            $result | Should -Be "y"
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Era detection patterns (verified via source analysis)
+    # -----------------------------------------------------------------
+    Context "Era detection patterns" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/migrate_daaf.ps1" -Raw
+        }
+
+        It "no remote indicates Era 2 (ZIP-based)" {
+            # When origin URL is empty/whitespace, DetectedEra should be "2"
+            $Content | Should -Match 'IsNullOrWhiteSpace\(\$OriginUrl\)'
+            $Content | Should -Match '\$DetectedEra = "2"'
+        }
+
+        It "remote with upstream repo URL indicates Era 1" {
+            $Content | Should -Match '\$OriginUrl -match \$Repo'
+            $Content | Should -Match '\$DetectedEra = "1"'
+        }
+
+        It "idempotency: graft already in place skips graft step" {
+            $Content | Should -Match 'History graft already in place'
+            $Content | Should -Match '\$InitialParentCount -gt 0'
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Era-specific file markers and output patterns
+    # -----------------------------------------------------------------
+    # These verify the migration script has distinct detection strings
+    # and code paths for each era. Complements the integration tests
+    # in ci-integration.yml which test against real Docker containers.
+    Context "Era-specific marker patterns" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/migrate_daaf.ps1" -Raw
+        }
+
+        It "emits 'clone-based installation' for Era 1 detection" {
+            $Content | Should -Match 'clone-based installation'
+        }
+
+        It "emits 'ZIP-based installation' for Era 2 detection" {
+            $Content | Should -Match 'ZIP-based installation'
+        }
+
+        It "has distinct code paths for Era 1 and Era 2" {
+            # Era 1 path
+            $Content | Should -Match '\$DetectedEra -eq "1"'
+            # Era 2 path uses graft
+            $Content | Should -Match 'replace --graft'
+        }
+
+        It "Era 2 path includes graft operation" {
+            # The graft is the critical Era 2 operation that connects
+            # local ZIP history to upstream timeline
+            $graftPos = $Content.IndexOf('replace --graft')
+            $graftPos | Should -BeGreaterThan -1
+        }
+
+        It "Era 1 and Era 2 detection strings are distinct" {
+            # Both detection strings must exist and be different
+            $era1Pos = $Content.IndexOf('clone-based installation')
+            $era2Pos = $Content.IndexOf('ZIP-based installation')
+            $era1Pos | Should -BeGreaterThan -1
+            $era2Pos | Should -BeGreaterThan -1
+            $era1Pos | Should -Not -Be $era2Pos
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Safety mechanisms
+    # -----------------------------------------------------------------
+    Context "Safety mechanisms" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/migrate_daaf.ps1" -Raw
+        }
+
+        It "uses System.Threading.Mutex for locking" {
+            $Content | Should -Match 'System\.Threading\.Mutex'
+            $Content | Should -Not -Match 'flock'
+        }
+
+        It "mutex uses Global scope for cross-process visibility" {
+            $Content | Should -Match 'Global\\DAAFMigrate'
+        }
+
+        It "backup call precedes destructive operations" {
+            # backup_daaf.ps1 is called in section 3, before era detection/graft in sections 5-6
+            $backupPos = $Content.IndexOf('backup_daaf.ps1')
+            $graftPos = $Content.IndexOf('replace --graft')
+            $backupPos | Should -BeLessThan $graftPos
+        }
+
+        It "trap handler releases mutex on failure" {
+            $Content | Should -Match 'trap \{'
+            $Content | Should -Match 'Mutex\.ReleaseMutex'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "migrate_daaf.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/migrate_daaf.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "completes full migration flow" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/migrate_daaf.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Migration complete*"
+    }
+
+    It "dry-run output includes era detection string" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/migrate_daaf.ps1" *>&1
+        # Dry-run simulates Era 1 (clone-based) -- verify detection output
+        ($output | Out-String) | Should -BeLike "*clone-based installation*"
+    }
+}
+
+# ============================================================================
+# Integrated state-machine tests
+# ============================================================================
+# These test the MAIN ORCHESTRATION flow by running the full script with
+# custom docker mock functions to simulate specific scenarios.
+
+Describe "migrate_daaf.ps1 integrated state-machine tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    BeforeEach {
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-migrate-int-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+        # Create stub backup_daaf.ps1 that exits cleanly
+        Set-Content -Path (Join-Path $script:TestDir "backup_daaf.ps1") -Value "exit 0"
+    }
+
+    AfterEach {
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+        Remove-Item Env:DAAF_NESTED -ErrorAction SilentlyContinue
+    }
+
+    It "Era 1 path (clone-based) completes successfully" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { Write-Output "daaf-test-1" }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { return }
+        "*exec*git -C /daaf remote get-url*upstream*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git -C /daaf remote get-url*origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*exec*git -C /daaf fetch*" { return }
+        "*exec*git -C /daaf branch --set-upstream*" { return }
+        "*exec*git*" { return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+        $outputStr | Should -BeLike "*clone-based installation*"
+        $outputStr | Should -BeLike "*Migration complete*"
+    }
+
+    It "Era 2 path (ZIP-based) detects and reports correctly" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { Write-Output "daaf-test-1" }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { return }
+        "*exec*git -C /daaf remote get-url*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git -C /daaf fetch*" { return }
+        "*exec*git -C /daaf rev-list --max-parents=0*" { Write-Output "aaa111root" }
+        "*exec*git -C /daaf cat-file*" {
+            Write-Output "tree abc123"
+            Write-Output "parent def456"
+            Write-Output "author Test"
+        }
+        "*exec*git -C /daaf branch --set-upstream*" { return }
+        "*exec*git -C /daaf remote add*" { return }
+        "*exec*git*" { return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+        $outputStr | Should -BeLike "*ZIP-based installation*"
+        $outputStr | Should -BeLike "*Migration complete*"
+    }
+
+    It "already migrated (idempotency) skips graft step" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { Write-Output "daaf-test-1" }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { return }
+        "*exec*git -C /daaf remote get-url*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git -C /daaf fetch*" { return }
+        "*exec*git -C /daaf rev-list --max-parents=0*" { Write-Output "aaa111root" }
+        "*exec*git -C /daaf cat-file*" {
+            Write-Output "tree abc123"
+            Write-Output "parent def456"
+            Write-Output "author Test"
+        }
+        "*exec*git -C /daaf branch --set-upstream*" { return }
+        "*exec*git -C /daaf remote add*" { return }
+        "*exec*git*" { return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+        $outputStr | Should -BeLike "*graft already in place*"
+    }
+}
+
+# ============================================================================
+# Error path tests
+# ============================================================================
+
+Describe "migrate_daaf.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    BeforeEach {
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-migrate-err-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+        Set-Content -Path (Join-Path $script:TestDir "backup_daaf.ps1") -Value "exit 0"
+    }
+
+    AfterEach {
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+        Remove-Item Env:DAAF_NESTED -ErrorAction SilentlyContinue
+    }
+
+    It "fetch from origin fails exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { Write-Output "daaf-test-1" }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { return }
+        "*exec*git -C /daaf remote get-url*upstream*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git -C /daaf remote get-url*origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*exec*git -C /daaf fetch*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git*" { return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*Failed to fetch*"
+    }
+
+    It "DAAF not installed (CLAUDE.md missing) exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { Write-Output "daaf-test-1" }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { $global:LASTEXITCODE = 1; return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*DAAF does not appear to be installed*"
+    }
+
+    It "container not running and start fails exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { return }
+        "*compose up*" { $global:LASTEXITCODE = 1; return }
+        "*start*" { $global:LASTEXITCODE = 1; return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*Failed to start*"
+    }
+
+    It "volume not found exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { $global:LASTEXITCODE = 1; return }
+        default { return }
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*not found*"
+    }
+}
+
+# ============================================================================
+# Edge cases
+# ============================================================================
+
+Describe "migrate_daaf.ps1 edge cases" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    BeforeEach {
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-migrate-edge-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+        Set-Content -Path (Join-Path $script:TestDir "backup_daaf.ps1") -Value "exit 0"
+    }
+
+    AfterEach {
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+        Remove-Item Env:DAAF_NESTED -ErrorAction SilentlyContinue
+    }
+
+    It "fork detection adds upstream remote" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" { Write-Output "daaf-test-1" }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { return }
+        "*exec*git -C /daaf remote get-url*upstream*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git -C /daaf remote get-url*origin*" {
+            Write-Output "https://github.com/user/daaf-fork.git"
+        }
+        "*exec*git -C /daaf remote add*upstream*" { return }
+        "*exec*git -C /daaf fetch*" { return }
+        "*exec*git -C /daaf branch --set-upstream*" { return }
+        "*exec*git*" { return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+        $outputStr | Should -BeLike "*clone-based installation*"
+        $outputStr | Should -BeLike "*fork*"
+        $outputStr | Should -BeLike "*Migration complete*"
+    }
+
+    It "multi-container on same volume shows warning" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*volume inspect*" { return }
+        "*ps -a*--filter*volume=*--format*" {
+            Write-Output "daaf-test-1"
+            Write-Output "daaf-test-2"
+        }
+        "*inspect*--format*Status*" { Write-Output "running" }
+        "*exec*true*" { return }
+        "*exec*test -f*CLAUDE.md*" { return }
+        "*exec*git -C /daaf remote get-url*upstream*" { $global:LASTEXITCODE = 1; return }
+        "*exec*git -C /daaf remote get-url*origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*exec*git -C /daaf fetch*" { return }
+        "*exec*git -C /daaf branch --set-upstream*" { return }
+        "*exec*git*" { return }
+        "*exec*" { return }
+        "*start*" { return }
+        default { return }
+    }
+}
+function Invoke-WebRequest {
+    param([switch]$UseBasicParsing, [string]$Uri, [string]$OutFile)
+    $null = $UseBasicParsing, $Uri
+    if ($OutFile) {
+        $parentDir = Split-Path $OutFile -Parent
+        if ($parentDir -and -not (Test-Path $parentDir)) {
+            New-Item -ItemType Directory -Path $parentDir -Force | Out-Null
+        }
+        Set-Content -Path $OutFile -Value "exit 0"
+    }
+}
+$NonInteractive = $true
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/migrate_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+        $outputStr | Should -BeLike "*Multiple containers*"
+        $outputStr | Should -BeLike "*Migration complete*"
+    }
+
+    It "concurrent execution guard uses mutex" {
+        $content = Get-Content "$RepoRoot/scripts/host/migrate_daaf.ps1" -Raw
+        $content | Should -Match 'Global\\DAAFMigrate'
+        $content | Should -Match 'Mutex\.WaitOne'
+    }
+
+    It "mutex released in trap handler on failure" {
+        $content = Get-Content "$RepoRoot/scripts/host/migrate_daaf.ps1" -Raw
+        $content | Should -Match 'trap \{'
+        $content | Should -Match 'Mutex\.ReleaseMutex'
+    }
+}
diff --git a/tests/powershell/rebuild_daaf.Tests.ps1 b/tests/powershell/rebuild_daaf.Tests.ps1
new file mode 100644
index 0000000..4fc2fa4
--- /dev/null
+++ b/tests/powershell/rebuild_daaf.Tests.ps1
@@ -0,0 +1,215 @@
+# ============================================================================
+# Pester tests for rebuild_daaf.ps1 -- DAAF Rebuild Utility (Windows)
+# ============================================================================
+
+Describe "rebuild_daaf.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/rebuild_daaf.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/rebuild_daaf.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for docker-compose.yml" {
+            $Content | Should -Match 'docker-compose\.yml'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "checks container exists with docker inspect" {
+            $Content | Should -Match 'docker inspect'
+        }
+
+        It "uses numbered progress steps [1/3] [2/3] [3/3]" {
+            ($Content | Select-String -Pattern '\[1/3\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+            ($Content | Select-String -Pattern '\[2/3\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+            ($Content | Select-String -Pattern '\[3/3\]' -AllMatches).Matches.Count | Should -BeGreaterOrEqual 1
+        }
+
+        It "copies Dockerfile from container" {
+            $Content | Should -Match 'docker cp.*Dockerfile'
+        }
+
+        It "copies docker-compose.yml from container" {
+            $Content | Should -Match 'docker cp.*docker-compose\.yml'
+        }
+
+        It "backs up existing files before overwrite" {
+            $Content | Should -Match 'pre-rebuild'
+        }
+
+        It "compares file hashes to detect changes" {
+            $Content | Should -Match 'Get-FileHash'
+        }
+
+        It "verifies CLAUDE.md after rebuild" {
+            $Content | Should -Match 'CLAUDE\.md'
+        }
+
+        It "cleans up pre-rebuild backups on success" {
+            $Content | Should -Match 'Remove-Item.*pre-rebuild'
+        }
+
+        It "waits for container readiness after rebuild" {
+            $Content | Should -Match 'Waiting for container to be ready'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "rebuild_daaf.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-test-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/rebuild_daaf.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "completes full rebuild flow" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/rebuild_daaf.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Rebuild complete*"
+    }
+}
+
+# ============================================================================
+# Error paths
+# ============================================================================
+
+Describe "rebuild_daaf.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/rebuild_daaf.ps1" -Raw
+    }
+
+    Context "Container not found" {
+        It "outputs error when container inspect fails" {
+            $Content | Should -Match "Container.*not found"
+        }
+
+        It "suggests running the installer first" {
+            $Content | Should -Match 'Have you run the DAAF installer'
+        }
+    }
+
+    Context "Dockerfile copy failure" {
+        It "outputs error when Dockerfile copy from container fails" {
+            $Content | Should -Match 'Failed to copy Dockerfile from container'
+        }
+
+        It "suggests running the installer on copy failure" {
+            $Content | Should -Match 'Make sure DAAF is installed in the container'
+        }
+    }
+
+    Context "docker-compose.yml copy failure" {
+        It "outputs error when docker-compose.yml copy fails" {
+            $Content | Should -Match 'Failed to copy docker-compose\.yml from container'
+        }
+    }
+
+    Context "Build failure" {
+        It "outputs error when docker compose build fails" {
+            $Content | Should -Match 'Rebuild failed'
+        }
+
+        It "preserves pre-rebuild backup on build failure" {
+            $Content | Should -Match 'Dockerfile\.pre-rebuild'
+        }
+    }
+
+    Context "Container start failure after build" {
+        It "outputs error when docker compose up -d fails after build" {
+            $Content | Should -Match 'Failed to start the container after rebuild'
+        }
+    }
+
+    Context "Container readiness timeout after rebuild" {
+        It "reports timeout when container does not become ready" {
+            $Content | Should -Match 'did not become ready within 60 seconds'
+        }
+
+        It "shows Docker error output on readiness timeout" {
+            $Content | Should -Match 'Docker reported'
+        }
+    }
+
+    Context "CLAUDE.md missing after rebuild" {
+        It "warns when DAAF files may not be intact" {
+            $Content | Should -Match 'DAAF files may not be intact'
+        }
+    }
+
+    Context "Hash comparison: Dockerfile changed" {
+        It "reports UPDATED when Dockerfile hash differs" {
+            $Content | Should -Match 'Dockerfile: UPDATED'
+        }
+
+        It "uses Get-FileHash for comparison" {
+            $Content | Should -Match 'Get-FileHash'
+        }
+    }
+
+    Context "Hash comparison: no changes" {
+        It "reports no changes when hashes match" {
+            $Content | Should -Match 'no changes detected'
+        }
+
+        It "rebuilds anyway when no changes detected" {
+            $Content | Should -Match 'Rebuilding anyway to make sure the image is up to date'
+        }
+    }
+
+    Context "Hash comparison: compose file changed" {
+        It "reports UPDATED when docker-compose.yml hash differs" {
+            $Content | Should -Match 'docker-compose\.yml: UPDATED'
+        }
+    }
+}
diff --git a/tests/powershell/restore_from_backup.Tests.ps1 b/tests/powershell/restore_from_backup.Tests.ps1
new file mode 100644
index 0000000..b45325c
--- /dev/null
+++ b/tests/powershell/restore_from_backup.Tests.ps1
@@ -0,0 +1,269 @@
+# ============================================================================
+# Pester tests for restore_from_backup.ps1 -- DAAF Restore from Backup
+# ============================================================================
+
+Describe "restore_from_backup.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/restore_from_backup.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/restore_from_backup.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "checks volume exists" {
+            $Content | Should -Match 'docker volume inspect'
+        }
+
+        It "checks for running containers using the volume" {
+            $Content | Should -Match 'docker ps --filter'
+        }
+
+        It "searches for backup folders matching date pattern" {
+            $Content | Should -Match 'daaf_backup'
+            $Content | Should -Match '\\d\{4\}-\\d\{2\}-\\d\{2\}'
+        }
+
+        It "contains destructive warning text" {
+            $Content | Should -Match 'DESTRUCTIVE OPERATION'
+        }
+
+        It "requires RESTORE confirmation" {
+            $Content | Should -Match 'Type RESTORE to confirm'
+        }
+
+        It "clears volume before copying (rm -rf step)" {
+            $Content | Should -Match 'rm -rf /dest'
+        }
+
+        It "uses cp -a (not cp -r) for permission-preserving copy" {
+            $Content | Should -Match 'cp -a /source/\. /dest/'
+            $Content | Should -Not -Match 'cp -r /source/\. /dest/'
+        }
+
+        It "verifies file count after restore" {
+            $Content | Should -Match 'Verifying restore'
+        }
+
+        It "includes file count mismatch check" {
+            $Content | Should -Match 'File count mismatch'
+        }
+
+        It "displays available backups with numbered list" {
+            $Content | Should -Match 'Available backups'
+        }
+    }
+}
+
+# ============================================================================
+# Behavioral tests -- dot-source to verify functions
+# ============================================================================
+
+Describe "restore_from_backup.ps1 behavioral tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+
+        $env:DAAF_TEST_MODE = "1"
+        . "$RepoRoot/scripts/host/restore_from_backup.ps1"
+
+        $script:Content = Get-Content "$RepoRoot/scripts/host/restore_from_backup.ps1" -Raw
+    }
+
+    AfterAll {
+        Remove-Item Env:DAAF_TEST_MODE -ErrorAction SilentlyContinue
+    }
+
+    Context "Wait-AndExit function" {
+        It "is callable after dot-sourcing" {
+            Get-Command Wait-AndExit -ErrorAction SilentlyContinue |
+                Should -Not -BeNullOrEmpty
+        }
+    }
+
+    Context "Backup folder pattern matching" {
+        It "uses regex pattern for date-based backup names" {
+            $Content | Should -Match '\\d\{4\}-\\d\{2\}-\\d\{2\}'
+        }
+
+        It "matches suffixed backup names (a, b, c)" {
+            $Content | Should -Match '\[a-z\]\?'
+        }
+    }
+
+    Context "Safety features" {
+        It "sorts backups descending (newest first)" {
+            $Content | Should -Match 'Sort-Object.*-Descending'
+        }
+
+        It "validates numeric input with TryParse" {
+            $Content | Should -Match 'TryParse'
+        }
+
+        It "handles cancelled restore gracefully" {
+            $Content | Should -Match 'Restore cancelled'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "restore_from_backup.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-restore-test-$(Get-Random)")
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "dry-run succeeds when no backups exist" {
+        Push-Location $script:TestDir
+        try {
+            $env:DAAF_DRY_RUN = "1"
+            $env:DAAF_NESTED = "1"
+            $output = & "$RepoRoot/scripts/host/restore_from_backup.ps1" *>&1
+            $LASTEXITCODE | Should -BeIn @(0, $null)
+            ($output | Out-String) | Should -BeLike "*No backup folders found*"
+        } finally {
+            Pop-Location
+        }
+    }
+
+    It "dry-run completes successfully with backups present" {
+        Push-Location $script:TestDir
+        try {
+            $null = New-Item -ItemType Directory -Path (Join-Path $script:TestDir "2026-01-01_daaf_backup") -Force
+            $null = New-Item -ItemType File -Path (Join-Path $script:TestDir "2026-01-01_daaf_backup/f1") -Force
+            $env:DAAF_DRY_RUN = "1"
+            $env:DAAF_NESTED = "1"
+            $null = & "$RepoRoot/scripts/host/restore_from_backup.ps1" *>&1
+            $LASTEXITCODE | Should -BeIn @(0, $null)
+        } finally {
+            Pop-Location
+        }
+    }
+
+    It "dry-run produces DRY-RUN markers" {
+        Push-Location $script:TestDir
+        try {
+            $null = New-Item -ItemType Directory -Path (Join-Path $script:TestDir "2026-01-01_daaf_backup") -Force
+            $null = New-Item -ItemType File -Path (Join-Path $script:TestDir "2026-01-01_daaf_backup/f1") -Force
+            $env:DAAF_DRY_RUN = "1"
+            $env:DAAF_NESTED = "1"
+            $output = & "$RepoRoot/scripts/host/restore_from_backup.ps1" *>&1
+            ($output | Out-String) | Should -BeLike "*``[DRY-RUN``]*"
+        } finally {
+            Pop-Location
+        }
+    }
+}
+
+# ============================================================================
+# Error paths
+# ============================================================================
+
+Describe "restore_from_backup.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/restore_from_backup.ps1" -Raw
+    }
+
+    Context "Running container detected" {
+        It "offers to stop running containers" {
+            $Content | Should -Match 'container is currently running'
+            $Content | Should -Match 'Stop the container now'
+        }
+
+        It "stops containers when user agrees" {
+            $Content | Should -Match 'Stopping containers'
+            $Content | Should -Match 'docker compose down'
+        }
+    }
+
+    Context "User declines to stop container" {
+        It "cancels restore when user declines stop (exit 0)" {
+            $Content | Should -Match 'Restore cancelled\. Stop the container manually'
+        }
+    }
+
+    Context "Invalid backup selection" {
+        It "rejects non-numeric input (exit 1)" {
+            $Content | Should -Match 'TryParse'
+            $Content | Should -Match 'Invalid selection'
+        }
+
+        It "rejects out-of-range selection (exit 1)" {
+            $Content | Should -Match '\$ChoiceNum -lt 1 -or \$ChoiceNum -gt \$Backups\.Count'
+        }
+    }
+
+    Context "User cancels at RESTORE confirmation" {
+        It "exits cleanly when user types something other than RESTORE (exit 0)" {
+            $Content | Should -Match '\$Confirm -ne "RESTORE"'
+            $Content | Should -Match 'Restore cancelled'
+        }
+    }
+
+    Context "Volume clear fails" {
+        It "exits with error when volume clear fails (exit 1)" {
+            $Content | Should -Match 'Failed to clear Docker volume'
+            $Content | Should -Match 'inconsistent state'
+        }
+    }
+
+    Context "Zero files after restore" {
+        It "exits with error when zero files found after restore (exit 1)" {
+            $Content | Should -Match '\$RestoredCount -eq 0'
+            $Content | Should -Match '0 files found in restored volume'
+        }
+    }
+
+    Context "File count mismatch after restore" {
+        It "shows warning when file count differs beyond tolerance" {
+            $Content | Should -Match 'File count mismatch'
+            $Content | Should -Match 'restore may be incomplete'
+        }
+    }
+
+    Context "No backup folders found" {
+        It "exits with error when no backups exist (exit 1)" {
+            $Content | Should -Match 'No backup folders found'
+            $Content | Should -Match 'daaf-docker folder'
+        }
+    }
+}
diff --git a/tests/powershell/run_daaf.Tests.ps1 b/tests/powershell/run_daaf.Tests.ps1
new file mode 100644
index 0000000..dcd0050
--- /dev/null
+++ b/tests/powershell/run_daaf.Tests.ps1
@@ -0,0 +1,150 @@
+# ============================================================================
+# Pester tests for run_daaf.ps1 -- DAAF Launcher (Windows)
+# ============================================================================
+
+Describe "run_daaf.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/run_daaf.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/run_daaf.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for docker-compose.yml" {
+            $Content | Should -Match 'docker-compose\.yml'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "defaults command to claude" {
+            $Content | Should -Match '"claude"'
+        }
+
+        It "handles bash command argument" {
+            $Content | Should -Match '"bash"'
+        }
+
+        It "verifies CLAUDE.md exists in container" {
+            $Content | Should -Match 'CLAUDE\.md'
+        }
+
+        It "starts container if not running" {
+            $Content | Should -Match 'Starting DAAF container'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "run_daaf.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-test-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/run_daaf.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "launches Claude Code in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/run_daaf.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Launching Claude Code*"
+    }
+}
+
+# ============================================================================
+# Error paths
+# ============================================================================
+
+Describe "run_daaf.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/run_daaf.ps1" -Raw
+    }
+
+    Context "Container not running auto-starts" {
+        It "attempts to start container with docker compose up -d" {
+            $Content | Should -Match 'Starting DAAF container'
+            $Content | Should -Match 'docker compose up -d'
+        }
+    }
+
+    Context "Auto-start fails" {
+        It "exits with error when docker compose up fails (exit 1)" {
+            $Content | Should -Match 'Failed to start the container'
+            $Content | Should -Match 'Check Docker Desktop'
+        }
+    }
+
+    Context "Compose file missing" {
+        It "exits with error when docker-compose.yml is missing (exit 1)" {
+            $Content | Should -Match 'docker-compose\.yml not found'
+            $Content | Should -Match 'daaf-docker folder'
+        }
+    }
+
+    Context "DAAF not installed in container" {
+        It "exits with error when CLAUDE.md is missing (exit 1)" {
+            $Content | Should -Match 'DAAF does not appear to be installed'
+            $Content | Should -Match 'CLAUDE\.md'
+        }
+    }
+
+    Context "Custom command passthrough" {
+        It "handles custom commands beyond claude and bash" {
+            $Content | Should -Match 'Running: \$Command'
+            $Content | Should -Match 'docker compose exec daaf-docker \$Command'
+        }
+    }
+
+    Context "Default command" {
+        It "defaults to claude when no args provided" {
+            $Content | Should -Match '\$Command = if \(\$args\.Count -gt 0\) \{ \$args\[0\] \} else \{ "claude" \}'
+        }
+    }
+}
diff --git a/tests/powershell/run_vscode.Tests.ps1 b/tests/powershell/run_vscode.Tests.ps1
new file mode 100644
index 0000000..498bc62
--- /dev/null
+++ b/tests/powershell/run_vscode.Tests.ps1
@@ -0,0 +1,137 @@
+# ============================================================================
+# Pester tests for run_vscode.ps1 -- DAAF Code Browser (Windows)
+# ============================================================================
+# Tests cover syntax validation, script structure, dry-run behavior, and
+# structural markers. Mirrors run_vscode.bats for cross-platform parity.
+# ============================================================================
+
+Describe "run_vscode.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    # =====================================================================
+    # Tier 1 -- Syntax
+    # =====================================================================
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/run_vscode.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    # =====================================================================
+    # Tier 3 -- Script structure
+    # =====================================================================
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/run_vscode.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for docker-compose.yml" {
+            $Content | Should -Match 'docker-compose\.yml'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "starts container if not running" {
+            $Content | Should -Match 'Starting DAAF container'
+        }
+
+        It "references launch_code_server.sh" {
+            $Content | Should -Match 'launch_code_server\.sh'
+        }
+
+        It "mentions the Code Browser in output" {
+            $Content | Should -Match 'Code Browser'
+        }
+
+        It "supports DAAF_TEST_MODE guard" {
+            $Content | Should -Match 'DAAF_TEST_MODE'
+        }
+
+        It "supports DAAF_DRY_RUN" {
+            $Content | Should -Match 'DAAF_DRY_RUN'
+        }
+
+        It "handles code-server launch failure" {
+            $Content | Should -Match 'Failed to start code-server'
+        }
+
+        It "reports container already running" {
+            $Content | Should -Match 'DAAF container is running'
+        }
+    }
+}
+
+# ============================================================================
+# Tier 5 -- Dry-run mode
+# ============================================================================
+
+Describe "run_vscode.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-test-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/run_vscode.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "shows Code Browser message in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/run_vscode.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Code Browser*"
+    }
+
+    It "reports container running in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/run_vscode.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*DAAF container is running*"
+    }
+
+    It "completes quickly in dry-run (no blocking)" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $sw = [System.Diagnostics.Stopwatch]::StartNew()
+        $null = & "$RepoRoot/scripts/host/run_vscode.ps1" *>&1
+        $sw.Stop()
+        $sw.Elapsed.TotalSeconds | Should -BeLessThan 5
+    }
+}
diff --git a/tests/powershell/update_daaf.Tests.ps1 b/tests/powershell/update_daaf.Tests.ps1
new file mode 100644
index 0000000..734e477
--- /dev/null
+++ b/tests/powershell/update_daaf.Tests.ps1
@@ -0,0 +1,759 @@
+# ============================================================================
+# Pester tests for update_daaf.ps1 -- DAAF Update Script (Windows)
+# ============================================================================
+
+Describe "update_daaf.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/update_daaf.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/update_daaf.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "defines Invoke-ComposeGit helper function" {
+            $Content | Should -Match 'function Invoke-ComposeGit\b'
+        }
+
+        It "defines Invoke-ComposeGitVerbose helper function" {
+            $Content | Should -Match 'function Invoke-ComposeGitVerbose'
+        }
+
+        It "defines Invoke-ComposeGitNull helper function" {
+            $Content | Should -Match 'function Invoke-ComposeGitNull'
+        }
+
+        It "defines Invoke-Compose helper function" {
+            $Content | Should -Match 'function Invoke-Compose'
+        }
+
+        It "defines Invoke-ComposeExec helper function" {
+            $Content | Should -Match 'function Invoke-ComposeExec'
+        }
+
+        It "defines Read-UserChoice helper function" {
+            $Content | Should -Match 'function Read-UserChoice'
+        }
+
+        It "defines Resolve-Conflict helper function" {
+            $Content | Should -Match 'function Resolve-Conflict'
+        }
+
+        It "defines Sync-HostScript helper function" {
+            $Content | Should -Match 'function Sync-HostScript'
+        }
+
+        It "defines Test-BuildChange helper function" {
+            $Content | Should -Match 'function Test-BuildChange'
+        }
+
+        It "defines Complete-Update helper function" {
+            $Content | Should -Match 'function Complete-Update'
+        }
+
+        It "has a trap handler for unexpected failures" {
+            $Content | Should -Match 'trap \{'
+        }
+
+        It "checks for docker-compose.yml" {
+            $Content | Should -Match 'docker-compose\.yml'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "supports DAAF_BRANCH environment variable" {
+            $Content | Should -Match 'DAAF_BRANCH'
+        }
+
+        It "offers backup before updating" {
+            $Content | Should -Match 'Backup recommendation'
+        }
+
+        It "creates a git backup branch" {
+            $Content | Should -Match 'backup/pre-update'
+        }
+
+        It "handles merge and rebase options" {
+            $Content | Should -Match 'MERGE \(recommended\)'
+            $Content | Should -Match 'REBASE \(cleaner history\)'
+        }
+
+        It "handles non-default branch update path" {
+            $Content | Should -Match "You are on branch"
+        }
+
+        It "handles uncommitted changes (dirty files)" {
+            $Content | Should -Match 'uncommitted changes'
+        }
+
+        It "detects ahead/behind state" {
+            $Content | Should -Match 'rev-list --count'
+        }
+    }
+}
+
+# ============================================================================
+# Behavioral tests -- dot-source the script and call functions directly
+# ============================================================================
+
+Describe "update_daaf.ps1 behavioral tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+
+        $env:DAAF_TEST_MODE = "1"
+        . "$RepoRoot/scripts/host/update_daaf.ps1"
+
+        # Declare a docker function so Pester can mock it
+        function docker {}
+    }
+
+    AfterAll {
+        Remove-Item Env:DAAF_TEST_MODE -ErrorAction SilentlyContinue
+    }
+
+    # -----------------------------------------------------------------
+    # Invoke-ComposeGit / Invoke-ComposeGitVerbose / Invoke-ComposeGitNull
+    # -----------------------------------------------------------------
+    Context "Invoke-ComposeGit" {
+        It "calls docker compose exec with git args" {
+            Mock docker { return "mock-sha-output" }
+            $null = Invoke-ComposeGit rev-parse HEAD
+            Should -Invoke docker -Times 1
+        }
+
+        It "strips carriage returns from output" {
+            Mock docker { return "abc123`r`ndef456`r`n" }
+            $result = Invoke-ComposeGit rev-parse HEAD
+            $result | Should -Not -Match "`r"
+        }
+
+        It "returns trimmed output" {
+            Mock docker { return "  abc123  " }
+            $result = Invoke-ComposeGit log --oneline
+            # The Out-String + Trim logic should strip leading/trailing whitespace
+            $result | Should -Not -Match '^\s'
+            $result | Should -Not -Match '\s$'
+        }
+    }
+
+    Context "Invoke-ComposeGitVerbose" {
+        It "preserves stdout (does not redirect stderr to null)" {
+            Mock docker { return "verbose-output-here" }
+            $result = Invoke-ComposeGitVerbose fetch origin
+            $result | Should -BeLike "*verbose-output*"
+        }
+    }
+
+    Context "Invoke-ComposeGitNull" {
+        It "discards all output (returns nothing)" {
+            Mock docker { return "should-be-discarded" }
+            $result = Invoke-ComposeGitNull branch test-branch
+            $result | Should -BeNullOrEmpty
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Sync-HostScript
+    # -----------------------------------------------------------------
+    Context "Sync-HostScript" {
+        It "skips when HEAD unchanged" {
+            # Both calls to Invoke-ComposeGit return the same SHA
+            Mock docker { return "abc123" }
+
+            # Capture information stream output (Write-Host goes to stream 6)
+            $output = Sync-HostScript "abc123" 6>&1
+            # Should produce no "Syncing" output since HEAD is unchanged
+            $syncMsg = $output | Where-Object { $_ -match "Syncing" }
+            $syncMsg | Should -BeNullOrEmpty
+        }
+
+        It "detects changed files via git diff" {
+            $callCount = 0
+            Mock docker {
+                $callCount++
+                # First docker call: Invoke-ComposeGit rev-parse HEAD -> new SHA
+                # Second docker call: Invoke-ComposeGit diff -> changed file list
+                # Third docker call: docker cp
+                $allArgs = $args -join " "
+                if ($allArgs -match "rev-parse HEAD") {
+                    return "new-sha-999"
+                }
+                if ($allArgs -match "diff --name-only") {
+                    return "scripts/host/run_daaf.ps1"
+                }
+                # docker cp call
+                $global:LASTEXITCODE = 0
+                return ""
+            }
+
+            $output = Sync-HostScript "old-sha-111" 6>&1
+            $syncMsg = $output | Where-Object { $_ -match "Syncing" }
+            $syncMsg | Should -Not -BeNullOrEmpty
+        }
+
+        It "handles partial copy failure gracefully" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "rev-parse HEAD") {
+                    return "new-sha-888"
+                }
+                if ($allArgs -match "diff --name-only") {
+                    return "scripts/host/run_daaf.ps1"
+                }
+                # docker cp fails
+                $global:LASTEXITCODE = 1
+                return ""
+            }
+
+            # Should not throw -- it shows a warning instead
+            $output = Sync-HostScript "old-sha-222" 6>&1
+            $warnMsg = $output | Where-Object { $_ -match "Warning" }
+            $warnMsg | Should -Not -BeNullOrEmpty
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Test-BuildChange
+    # -----------------------------------------------------------------
+    Context "Test-BuildChange" {
+        It "reports no changes when build files unchanged" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "rev-parse HEAD") {
+                    return "new-sha-777"
+                }
+                if ($allArgs -match "diff --name-only") {
+                    # No Dockerfile or docker-compose.yml changes
+                    return ""
+                }
+                return ""
+            }
+
+            $output = Test-BuildChange "old-sha-333" 6>&1
+            $noRebuild = $output | Where-Object { $_ -match "no container rebuild needed" }
+            $noRebuild | Should -Not -BeNullOrEmpty
+        }
+
+        It "reports no changes when HEAD is unchanged" {
+            # Same SHA => no rebuild needed
+            Mock docker { return "same-sha-444" }
+
+            $output = Test-BuildChange "same-sha-444" 6>&1
+            $noRebuild = $output | Where-Object { $_ -match "no container rebuild needed" }
+            $noRebuild | Should -Not -BeNullOrEmpty
+        }
+
+        It "detects Dockerfile modifications" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "rev-parse HEAD") {
+                    return "new-sha-555"
+                }
+                if ($allArgs -match "diff --name-only") {
+                    return "Dockerfile"
+                }
+                return ""
+            }
+            # Mock Read-Host so Read-UserChoice doesn't block
+            Mock Read-Host { return "n" }
+
+            $output = Test-BuildChange "old-sha-555" 6>&1
+            $buildMsg = $output | Where-Object { $_ -match "Build files were updated" }
+            $buildMsg | Should -Not -BeNullOrEmpty
+        }
+
+        It "detects docker-compose.yml modifications" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "rev-parse HEAD") {
+                    return "new-sha-666"
+                }
+                if ($allArgs -match "diff --name-only") {
+                    return "docker-compose.yml"
+                }
+                return ""
+            }
+            Mock Read-Host { return "n" }
+
+            $output = Test-BuildChange "old-sha-666" 6>&1
+            $buildMsg = $output | Where-Object { $_ -match "Build files were updated" }
+            $buildMsg | Should -Not -BeNullOrEmpty
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Complete-Update
+    # -----------------------------------------------------------------
+    Context "Complete-Update" {
+        It "calls Sync-HostScript and Test-BuildChange" {
+            # Both return same HEAD => no action, but both run
+            Mock docker { return "same-sha-final" }
+
+            $output = Complete-Update "same-sha-final" 6>&1
+            $completeMsg = $output | Where-Object { $_ -match "Update complete" }
+            $completeMsg | Should -Not -BeNullOrEmpty
+        }
+
+        It "includes ExtraMsg when provided" {
+            Mock docker { return "same-sha-extra" }
+
+            $output = Complete-Update "same-sha-extra" "Rebased successfully." 6>&1
+            $extraMsg = $output | Where-Object { $_ -match "Rebased successfully" }
+            $extraMsg | Should -Not -BeNullOrEmpty
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Resolve-Conflict
+    # -----------------------------------------------------------------
+    Context "Resolve-Conflict" {
+        It "shows conflicting file list" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "diff --name-only") {
+                    return "CLAUDE.md`nREADME.md"
+                }
+                return ""
+            }
+            # Choose option 2 to exit
+            Mock Read-Host { return "2" }
+
+            $output = Resolve-Conflict "merge" "merge --abort" 6>&1
+            $conflictHeader = $output | Where-Object { $_ -match "Conflict detected" }
+            $conflictHeader | Should -Not -BeNullOrEmpty
+        }
+
+        # Resolve-Conflict calls Read-UserChoice, which auto-selects option 1
+        # in non-interactive mode (CI). Override Read-UserChoice to force
+        # option 2 so we can test the manual resolution output path.
+        It "option 2 shows manual resolution instructions for merge" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "diff --name-only") {
+                    return "CLAUDE.md"
+                }
+                return ""
+            }
+            function Read-UserChoice { param($P, $V) $null = $P, $V; return "2" }
+
+            $output = Resolve-Conflict "merge" "merge --abort" 6>&1
+            $mergeInst = $output | Where-Object { $_ -match 'git commit -m' }
+            $mergeInst | Should -Not -BeNullOrEmpty
+        }
+
+        It "option 2 shows rebase continue for rebase type" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "diff --name-only") {
+                    return "CLAUDE.md"
+                }
+                return ""
+            }
+            function Read-UserChoice { param($P, $V) $null = $P, $V; return "2" }
+
+            $output = Resolve-Conflict "rebase" "rebase --abort" 6>&1
+            $rebaseInst = $output | Where-Object { $_ -match 'rebase --continue' }
+            $rebaseInst | Should -Not -BeNullOrEmpty
+        }
+
+        It "returns false when conflicts remain (option 2)" {
+            Mock docker {
+                $allArgs = $args -join " "
+                if ($allArgs -match "diff --name-only") {
+                    return "CLAUDE.md"
+                }
+                return ""
+            }
+            function Read-UserChoice { param($P, $V) $null = $P, $V; return "2" }
+
+            $null = Resolve-Conflict "merge" "merge --abort" 6>&1
+            # Resolve-Conflict returns $false for option 2
+            Resolve-Conflict "merge" "merge --abort" *> $null | Should -BeFalse
+        }
+    }
+
+    # -----------------------------------------------------------------
+    # Safety: Mutex and trap
+    # -----------------------------------------------------------------
+    Context "Safety mechanisms" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/update_daaf.ps1" -Raw
+        }
+
+        It "uses System.Threading.Mutex for locking (not flock)" {
+            $Content | Should -Match 'System\.Threading\.Mutex'
+            $Content | Should -Not -Match 'flock'
+        }
+
+        It "trap registered for cleanup" {
+            $Content | Should -Match 'trap \{'
+            # Trap handler releases the mutex
+            $Content | Should -Match 'Mutex\.ReleaseMutex'
+        }
+
+        It "mutex uses Global scope for cross-process visibility" {
+            $Content | Should -Match 'Global\\DAAFUpdate'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "update_daaf.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-test-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/update_daaf.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "reports already up to date" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/update_daaf.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Already up to date*"
+    }
+}
+
+# ============================================================================
+# Integrated state-machine tests
+# ============================================================================
+# These test the MAIN ORCHESTRATION flow by running the full script
+# with mock docker responses. Unlike dry-run mode (which uses the script's
+# built-in mocks), these tests define custom docker functions to simulate
+# specific state-machine scenarios.
+
+Describe "update_daaf.ps1 integrated state-machine tests" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    BeforeEach {
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-update-int-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterEach {
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+        Remove-Item Env:DAAF_NESTED -ErrorAction SilentlyContinue
+        Remove-Item Env:DAAF_BRANCH -ErrorAction SilentlyContinue
+    }
+
+    It "clean pull path succeeds (behind, no local commits, no dirty files)" {
+        $env:DAAF_NESTED = "1"
+        # Create a wrapper script that defines a custom docker mock and sources the real script
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*--format*" { Write-Output "daaf-docker" }
+        "*compose exec*true*" { return }
+        "*compose exec*test -f*/daaf/.git/shallow*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*test -f*" { return }
+        "*compose exec*git -C /daaf remote get-url origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*compose exec*git -C /daaf fetch*" { return }
+        "*compose exec*git -C /daaf rev-parse --verify*backup/*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*git -C /daaf rev-parse --verify*origin/main*" {
+            Write-Output "def456remote"
+        }
+        "*compose exec*git -C /daaf branch*--show-current*" { Write-Output "main" }
+        "*compose exec*git -C /daaf branch*" { return }
+        "*compose exec*git -C /daaf rev-parse*origin/main*" { Write-Output "def456remote" }
+        "*compose exec*git -C /daaf rev-parse*HEAD*" { Write-Output "abc123local" }
+        "*compose exec*git -C /daaf diff --name-only*HEAD*" { return }
+        "*compose exec*git -C /daaf diff --name-only*" { return }
+        "*compose exec*git -C /daaf rev-list --count*origin/main..HEAD*" { Write-Output "0" }
+        "*compose exec*git -C /daaf rev-list --count*HEAD..origin/main*" { Write-Output "3" }
+        "*compose exec*git -C /daaf pull*" { Write-Output "Updating..." }
+        "*compose exec*git*" { return }
+        "*compose exec*" { return }
+        "*cp *" { return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $exitCode = $LASTEXITCODE
+        $outputStr = $output | Out-String
+        $exitCode | Should -Be 0
+        $outputStr | Should -BeLike "*Update complete*"
+    }
+
+    It "already up to date exits cleanly (same SHA, no dirty files)" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*--format*" { Write-Output "daaf-docker" }
+        "*compose exec*true*" { return }
+        "*compose exec*test -f*/daaf/.git/shallow*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*test -f*" { return }
+        "*compose exec*git -C /daaf remote get-url origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*compose exec*git -C /daaf fetch*" { return }
+        "*compose exec*git -C /daaf rev-parse --verify*backup/*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*git -C /daaf rev-parse --verify*origin/main*" {
+            Write-Output "abc123same"
+        }
+        "*compose exec*git -C /daaf branch*--show-current*" { Write-Output "main" }
+        "*compose exec*git -C /daaf branch*" { return }
+        "*compose exec*git -C /daaf rev-parse*origin/main*" { Write-Output "abc123same" }
+        "*compose exec*git -C /daaf rev-parse*HEAD*" { Write-Output "abc123same" }
+        "*compose exec*git -C /daaf diff --name-only*" { return }
+        "*compose exec*git*" { return }
+        "*compose exec*" { return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 0
+        $outputStr | Should -BeLike "*Already up to date*"
+    }
+
+    It "no remote configured exits with guidance" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*--format*" { Write-Output "daaf-docker" }
+        "*compose exec*true*" { return }
+        "*compose exec*test -f*" { return }
+        "*compose exec*git -C /daaf remote get-url*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*git -C /daaf branch*" { return }
+        "*compose exec*git -C /daaf rev-parse*HEAD*" { Write-Output "abc123" }
+        "*compose exec*git*" { return }
+        "*compose exec*" { return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 0
+        $outputStr | Should -BeLike "*not connected to the update server*"
+    }
+
+    It "network failure during fetch exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*--format*" { Write-Output "daaf-docker" }
+        "*compose exec*true*" { return }
+        "*compose exec*test -f*/daaf/.git/shallow*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*test -f*" { return }
+        "*compose exec*git -C /daaf remote get-url origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*compose exec*git -C /daaf fetch*" {
+            $global:LASTEXITCODE = 1
+            return
+        }
+        "*compose exec*git -C /daaf branch*" { return }
+        "*compose exec*git -C /daaf rev-parse --verify*backup/*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*git -C /daaf rev-parse*HEAD*" { Write-Output "abc123" }
+        "*compose exec*git*" { return }
+        "*compose exec*" { return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*Failed to fetch*"
+    }
+
+    It "DAAF not installed (CLAUDE.md missing) exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*--format*" { Write-Output "daaf-docker" }
+        "*compose exec*true*" { return }
+        "*compose exec*test -f*CLAUDE.md*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*" { return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*DAAF does not appear to be installed*"
+    }
+
+    It "container not running and start fails exits with error" {
+        $env:DAAF_NESTED = "1"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*" { return }
+        "*compose up*" { $global:LASTEXITCODE = 1; return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*Failed to start*"
+    }
+
+    It "DAAF_BRANCH specifies nonexistent branch exits with error" {
+        $env:DAAF_NESTED = "1"
+        $env:DAAF_BRANCH = "nonexistent-branch-xyz"
+        $wrapperScript = Join-Path $script:TestDir "test_wrapper.ps1"
+        Set-Content -Path $wrapperScript -Value @'
+$ErrorActionPreference = "Stop"
+function docker {
+    $argStr = $args -join ' '
+    $global:LASTEXITCODE = 0
+    switch -Wildcard ($argStr) {
+        "*info*" { return }
+        "*compose ps*--format*" { Write-Output "daaf-docker" }
+        "*compose exec*true*" { return }
+        "*compose exec*test -f*/daaf/.git/shallow*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*test -f*" { return }
+        "*compose exec*git -C /daaf remote get-url origin*" {
+            Write-Output "https://github.com/DAAF-Contribution-Community/daaf.git"
+        }
+        "*compose exec*git -C /daaf fetch*" { return }
+        "*compose exec*git -C /daaf rev-parse --verify*backup/*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*git -C /daaf rev-parse --verify*nonexistent*" { $global:LASTEXITCODE = 1; return }
+        "*compose exec*git -C /daaf branch*" { return }
+        "*compose exec*git -C /daaf rev-parse*HEAD*" { Write-Output "abc123" }
+        "*compose exec*git*" { return }
+        "*compose exec*" { return }
+        default { return }
+    }
+}
+'@
+        Add-Content -Path $wrapperScript -Value ". '$RepoRoot/scripts/host/update_daaf.ps1'"
+        $output = & pwsh -NoProfile -File $wrapperScript *>&1
+        $outputStr = $output | Out-String
+        $LASTEXITCODE | Should -Be 1
+        $outputStr | Should -BeLike "*was not found*"
+        Remove-Item Env:DAAF_BRANCH -ErrorAction SilentlyContinue
+    }
+
+    It "lock cleanup on exit (mutex released after dry-run)" {
+        # Verify the script structure includes mutex cleanup in trap and exit
+        $content = Get-Content "$RepoRoot/scripts/host/update_daaf.ps1" -Raw
+        # Trap handler releases mutex
+        $content | Should -Match 'Mutex\.ReleaseMutex'
+        # Wait-AndExit also releases mutex
+        $content | Should -Match 'function Wait-AndExit'
+    }
+}
+
+# ============================================================================
+# Concurrent execution guard
+# ============================================================================
+
+Describe "update_daaf.ps1 concurrency guard" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/update_daaf.ps1" -Raw
+    }
+
+    It "uses named mutex for cross-process locking" {
+        $Content | Should -Match 'Global\\DAAFUpdate'
+    }
+
+    It "releases mutex in Wait-AndExit" {
+        $Content | Should -Match 'function Wait-AndExit'
+        $Content | Should -Match 'Mutex\.ReleaseMutex'
+    }
+
+    It "releases mutex in trap handler" {
+        $Content | Should -Match 'trap \{'
+        $Content | Should -Match 'Mutex\.ReleaseMutex'
+    }
+
+    It "handles AbandonedMutexException from crashed previous instance" {
+        $Content | Should -Match 'AbandonedMutexException'
+    }
+}
diff --git a/tests/powershell/view_logs.Tests.ps1 b/tests/powershell/view_logs.Tests.ps1
new file mode 100644
index 0000000..1824859
--- /dev/null
+++ b/tests/powershell/view_logs.Tests.ps1
@@ -0,0 +1,196 @@
+# ============================================================================
+# Pester tests for view_logs.ps1 -- DAAF Log Explorer (Windows)
+# ============================================================================
+
+Describe "view_logs.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/view_logs.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/view_logs.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for docker-compose.yml" {
+            $Content | Should -Match 'docker-compose\.yml'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "starts container if not running" {
+            $Content | Should -Match 'Starting DAAF container'
+        }
+
+        It "references generate_log_viewer.sh" {
+            $Content | Should -Match 'generate_log_viewer\.sh'
+        }
+
+        It "mentions the Log Explorer in output" {
+            $Content | Should -Match 'Log Explorer'
+        }
+
+        It "includes recovery step" {
+            $Content | Should -Match 'recover-session-logs'
+        }
+
+        It "includes menu selection prompt" {
+            $Content | Should -Match 'Select a log source'
+        }
+
+        It "handles --archive argument" {
+            $Content | Should -Match '"--archive"'
+        }
+
+        It "handles --help argument" {
+            $Content | Should -Match '"--help"'
+        }
+
+        It "skips menu in non-interactive contexts" {
+            $Content | Should -Match 'DAAF_DRY_RUN'
+            $Content | Should -Match 'DAAF_NESTED'
+            $Content | Should -Match '\$SkipMenu'
+        }
+    }
+}
+
+# ============================================================================
+# Dry-run mode
+# ============================================================================
+
+Describe "view_logs.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-test-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/view_logs.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "opens log explorer in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/view_logs.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Log Explorer*"
+    }
+
+    It "skips menu in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/view_logs.ps1" *>&1
+        ($output | Out-String) | Should -Not -BeLike "*Select a log source*"
+    }
+
+    It "includes recovery step in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/view_logs.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*orphaned session logs*"
+    }
+
+    It "skips sleep in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $sw = [System.Diagnostics.Stopwatch]::StartNew()
+        $null = & "$RepoRoot/scripts/host/view_logs.ps1" *>&1
+        $sw.Stop()
+        $sw.Elapsed.TotalSeconds | Should -BeLessThan 2
+    }
+
+    It "accepts --archive flag" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/view_logs.ps1" --archive *>&1
+        ($output | Out-String) | Should -BeLike "*Log Explorer*"
+    }
+}
+
+# ============================================================================
+# Error paths
+# ============================================================================
+
+Describe "view_logs.ps1 error paths" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:Content = Get-Content "$RepoRoot/scripts/host/view_logs.ps1" -Raw
+    }
+
+    Context "--help flag" {
+        It "prints usage and exits 0 on --help" {
+            $Content | Should -Match '"--help"'
+            $Content | Should -Match 'Usage:'
+        }
+    }
+
+    Context "Unknown argument" {
+        It "exits with error on unknown argument (exit 1)" {
+            $Content | Should -Match 'Unknown argument'
+            $Content | Should -Match 'Wait-AndExit 1'
+        }
+    }
+
+    Context "No log sources found" {
+        It "exits with message when no log sources exist (exit 0)" {
+            $Content | Should -Match 'No log sources found'
+            $Content | Should -Match 'Run a DAAF session first'
+        }
+    }
+
+    Context "--archive flag skips menu" {
+        It "sets SkipMenu to true when --archive is provided" {
+            $Content | Should -Match '\$SkipMenu = \$true'
+            $Content | Should -Match '\$SelectedSource = "--archive"'
+        }
+    }
+
+    Context "Container not running starts it" {
+        It "starts container when not running" {
+            $Content | Should -Match 'Starting DAAF container'
+            $Content | Should -Match 'docker compose up -d'
+        }
+
+        It "exits with error when container start fails" {
+            $Content | Should -Match 'Failed to start the container'
+        }
+    }
+}
diff --git a/tests/powershell/view_notebooks.Tests.ps1 b/tests/powershell/view_notebooks.Tests.ps1
new file mode 100644
index 0000000..c05b97a
--- /dev/null
+++ b/tests/powershell/view_notebooks.Tests.ps1
@@ -0,0 +1,137 @@
+# ============================================================================
+# Pester tests for view_notebooks.ps1 -- DAAF Notebook Browser (Windows)
+# ============================================================================
+# Tests cover syntax validation, script structure, dry-run behavior, and
+# structural markers. Mirrors view_notebooks.bats for cross-platform parity.
+# ============================================================================
+
+Describe "view_notebooks.ps1" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+    }
+
+    # =====================================================================
+    # Tier 1 -- Syntax
+    # =====================================================================
+
+    Context "Syntax validation" {
+        It "parses without errors" {
+            $errors = Test-ScriptSyntax -Path "$RepoRoot/scripts/host/view_notebooks.ps1"
+            $errors | Should -BeNullOrEmpty
+        }
+    }
+
+    # =====================================================================
+    # Tier 3 -- Script structure
+    # =====================================================================
+
+    Context "Script structure" {
+        BeforeAll {
+            $script:Content = Get-Content "$RepoRoot/scripts/host/view_notebooks.ps1" -Raw
+        }
+
+        It "sets ErrorActionPreference to Stop" {
+            $Content | Should -Match '\$ErrorActionPreference\s*=\s*[''"]Stop[''"]'
+        }
+
+        It "defines Wait-AndExit function" {
+            $Content | Should -Match 'function Wait-AndExit'
+        }
+
+        It "checks DAAF_NESTED in Wait-AndExit" {
+            $Content | Should -Match 'DAAF_NESTED'
+        }
+
+        It "checks for docker-compose.yml" {
+            $Content | Should -Match 'docker-compose\.yml'
+        }
+
+        It "checks for Docker with Get-Command" {
+            $Content | Should -Match 'Get-Command docker'
+        }
+
+        It "checks Docker daemon with docker info" {
+            $Content | Should -Match 'docker info'
+        }
+
+        It "starts container if not running" {
+            $Content | Should -Match 'Starting DAAF container'
+        }
+
+        It "references launch_marimo.sh" {
+            $Content | Should -Match 'launch_marimo\.sh'
+        }
+
+        It "mentions the Notebook Browser in output" {
+            $Content | Should -Match 'Notebook Browser'
+        }
+
+        It "supports DAAF_TEST_MODE guard" {
+            $Content | Should -Match 'DAAF_TEST_MODE'
+        }
+
+        It "supports DAAF_DRY_RUN" {
+            $Content | Should -Match 'DAAF_DRY_RUN'
+        }
+
+        It "handles notebook browser launch failure" {
+            $Content | Should -Match 'Failed to start the notebook browser'
+        }
+
+        It "reports container already running" {
+            $Content | Should -Match 'DAAF container is running'
+        }
+    }
+}
+
+# ============================================================================
+# Tier 5 -- Dry-run mode
+# ============================================================================
+
+Describe "view_notebooks.ps1 dry-run mode" {
+    BeforeAll {
+        . "$PSScriptRoot/TestHelper.ps1"
+        $script:OrigDryRun = $env:DAAF_DRY_RUN
+        $script:OrigNested = $env:DAAF_NESTED
+        $script:TestDir = New-Item -ItemType Directory -Path (Join-Path ([System.IO.Path]::GetTempPath()) "daaf-test-$(Get-Random)")
+        Push-Location $script:TestDir
+        New-FakeComposeFile
+    }
+
+    AfterAll {
+        $env:DAAF_DRY_RUN = $script:OrigDryRun
+        $env:DAAF_NESTED = $script:OrigNested
+        Pop-Location
+        Remove-Item -Recurse -Force $script:TestDir -ErrorAction SilentlyContinue
+    }
+
+    It "completes successfully with DAAF_DRY_RUN=1" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $null = & "$RepoRoot/scripts/host/view_notebooks.ps1" *>&1
+        $LASTEXITCODE | Should -BeIn @(0, $null)
+    }
+
+    It "shows Notebook Browser message in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/view_notebooks.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*Notebook Browser*"
+    }
+
+    It "reports container running in dry-run" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $output = & "$RepoRoot/scripts/host/view_notebooks.ps1" *>&1
+        ($output | Out-String) | Should -BeLike "*DAAF container is running*"
+    }
+
+    It "completes quickly in dry-run (no blocking)" {
+        $env:DAAF_DRY_RUN = "1"
+        $env:DAAF_NESTED = "1"
+        $sw = [System.Diagnostics.Stopwatch]::StartNew()
+        $null = & "$RepoRoot/scripts/host/view_notebooks.ps1" *>&1
+        $sw.Stop()
+        $sw.Elapsed.TotalSeconds | Should -BeLessThan 5
+    }
+}
diff --git a/user_reference/01_installation_and_quickstart.md b/user_reference/01_installation_and_quickstart.md
index cbaef4e..455df7e 100644
--- a/user_reference/01_installation_and_quickstart.md
+++ b/user_reference/01_installation_and_quickstart.md
@@ -9,36 +9,43 @@ This is the complete first-time installation and setup guide for DAAF. This docu
 ## Table of Contents
 - [**Prerequisites**](#prerequisites)
 - [**Installing DAAF**](#installing-daaf)
+- [**Recommended Next Steps**](#recommended-next-steps)
 - [**Day-to-Day Start/Stop Workflow**](#day-to-day-startstop-workflow)
 - [**How to Manage DAAF Project Files and Output**](#how-to-manage-daaf-project-files-and-output)
-- [**Keeping DAAF Updated**](#keeping-daaf-updated)
 - [**Viewing Marimo Notebooks in Your Browser**](#viewing-marimo-notebooks-in-your-browser)
+- [**Viewing Session Logs in Your Browser**](#viewing-session-logs-in-your-browser)
+- [**Keeping DAAF Updated**](#keeping-daaf-updated)
+- [**Advanced Installation & Configuration**](#advanced-installation--configuration)
 - [**Setup Troubleshooting**](#setup-troubleshooting)
-- [**Recommended Next Steps**](#recommended-next-steps)
 
 ---
 
+
+**Installing DAAF is extremely easy and straightforward.** That being said, I put a LOT of explanations and detail together here so you have a strong sense and intuition for what's going on under the hood -- which I think is extremely valuable so you have a better handle on why things operate the way they do, or how to manage things in case anything goes wrong. Besides the reading, this whole process really shouldn't take you more than 10 minutes start-to-finish!
+
+
 ## Prerequisites
 
 Before installing DAAF, there are three (technically four) key prerequisites. Please read the Anthropic account requirement especially closely; the price of the necessary subscription is definitively the highest barrier to entry at this time. I hope this will change in the near future with greater testing and community support for open-source models!
 
 ### 0. A computer with internet access
 
-You'll need internet access to download the project files and interact with DAAF/Claude (which itself always requires internet). Datasets will also be downloaded from the Urban Institute Education Data Portal as you conduct research work, which will also require an internet connection. Note that all data analyses will be conducted using your actual computer hardware, so you should have a computer that's generally capable of running intermediate-level data analysis (same sort of requirements you'd face if you wanted to analyze these same datasets in R/Stata/Python regularly). Don't worry about actual R/Stata/Python packages/libraries/dependencies, that's all handled carefully for you behind the scenes!
+You'll need internet access to download the project files and interact with DAAF/Claude (which itself always requires internet). Note that all data analyses will be conducted using your actual computer hardware, so you should have a computer that's generally capable of running intermediate-level data analysis (same sort of requirements you'd face if you wanted to analyze these same datasets in R/Stata/Python regularly). Don't worry about actual Python packages/libraries/dependencies, that's all handled carefully for you behind the scenes!
 
 ### 1. Anthropic Account & Authentication
 
-Claude Code is the AI assistant that powers this project. It runs inside your terminal (not in a web browser) and needs to link in with an Anthropic account for billing/usage purposes. Because we're relying on cutting-edge frontier models and asking them to do a **LOT** of thorough work for us (deep-diving into data, writing a lot of code, checking a lot of code, rewriting code, writing intensive plans, etc., etc.), we need to have a **high-usage** Anthropic account. Unfortunately, the free and standard "Pro"-level plans will simply not be sufficient for the time being; given current pricing at $100-200/mo, this is the biggest barrier-to-entry for engaging in this work.
+Claude Code is the AI assistant platform that powers this project. It runs inside your terminal (not in a web browser) and needs to link in with an Anthropic account for billing/usage purposes. Because we're relying on cutting-edge frontier models and asking them to do a **LOT** of thorough work for us (deep-diving into data, writing a lot of code, checking a lot of code, rewriting code, writing intensive plans, etc., etc.), we need to have a **high-usage** Anthropic account. Unfortunately, the free and standard "Pro"-level plans will simply not be sufficient for the time being; given current pricing at $100-200/mo, this is the biggest barrier-to-entry for engaging in this work. Here are your main options:
 
-For the account setup, that means you have two main options:
+| Option | Cost | Setup | Key Tradeoff |
+|--------|------|-------|--------------|
+| **Anthropic Max subscription** (recommended) | $100-200/mo flat | Interactive login on first launch -- no config needed | Best value for heavy use; I rarely hit limits on the $200/mo plan. [Get one here](https://claude.com/pricing/max) or [upgrade an existing plan](https://claude.ai/upgrade). Team/Enterprise subscriptions also work, but mileage may vary based on organizational settings/limits. |
+| **Anthropic API key** | Pay-per-use (can get expensive fast) | Interactive login on first launch -- no config needed | Unlimited use, but a single straightforward analysis can cost $30-60 in API fees. I'd have paid roughly 10x more via API key than my Max subscription. [Get one here](https://console.anthropic.com/). |
+| **OpenRouter** | Pay-per-token | Configure via `environment_settings.txt` ([instructions below](#configure-authentication-via-environment_settingstxt)) | No Anthropic subscription required; solid alternative if you want to avoid a monthly commitment or already use OpenRouter. **Caveat:** DAAF requires Opus-class models -- stick with Anthropic's Opus through OpenRouter for now. GLM 5.1 and Kimi K2.6 are cheaper and fairly viable models from early scoping, but require more testing and caution. [Get a key here](https://openrouter.ai/). |
+| **Cloud providers** (Bedrock, Vertex AI) | Per your organization's arrangement | Configure via `environment_settings.txt` ([instructions below](#configure-authentication-via-environment_settingstxt)) | Route through your org's existing cloud platform. See `environment_settings_example.txt` in `daaf-docker` for required variables. |
 
-- **Anthropic Max subscription** — [Get one here](https://claude.com/pricing/max), or if you already have an active Anthropic account, you can [upgrade your plan here](https://claude.ai/upgrade). I rarely hit my usage limits running multiple projects at once on the $200/mo plan; your mileage may vary on the $100/mo plan. You can also use an existing Team or Enterprise subscription, but your mileage may vary substantially there too based on your exact organizational settings/limits.
-- **Anthropic API key** — [Get one here](https://console.anthropic.com/). This is a pay-per-use key that you'll paste into Claude Code when prompted. This allows unlimited use as long as you're willing to pay -- but this can get VERY expensive, *very* quickly. A fairly straightforward descriptive analysis with relatively few dataset joins via raw API fees can easily be between $30-60. I HIGHLY recommend getting a Max subscription for this project, instead, as they are explicitly subsidizing these sorts of costs via their subscription model. Initial testing on my end indicates I would have paid roughly 10x more for my usage going with the API key versus just my Max subscription plan.
-- **Third-party platform use** — If your company has an Amazon Bedrock or Vertex AI or similar partnership as part of your organizational plan with Anthropic, you can also leverage these settings instead. I'm not familiar enough with this myself and wouldn't be able to support much, but you should follow whatever instructions your plan admins have given you to link your account with Claude Code more generally.
+**How authentication works:** For the **Max subscription** and **API key** options, Claude Code will prompt you to authenticate interactively the first time you run it -- you don't need to configure anything in advance. For **OpenRouter** and **cloud provider** setups, you'll configure credentials via the `environment_settings.txt` file instead (instructions below). You can always switch between methods later (type `/login` inside Claude Code to change your interactive authentication, or update your `environment_settings.txt` file and restart the container). Note that many terminal interfaces "hide" any password-entry you're asked to do, so if you don't see your typing "working," it's working but hiding it from view for your privacy.
 
-Whichever route you choose, Claude Code will prompt you to choose your authentication method the first time you run it — you don't need to configure anything in advance. You can also always start with one option and change later (e.g., try billing via API for a short test and then transition to a Max subscription); you can adjust your settings by typing `/login` when chatting with Claude. Note that many terminal interfaces "hide" any password-entry you're asked to do, so if you don't see your typing "working," it's working but hiding it from view for your privacy. If you're concerned about privacy otherwise: Nothing (including your credentials) ever leave your computer in the course of this project's workflows, and I've enforced a LOT of safety checks to ensure Claude doesn't accidentally share it with anyone, either. This can be directly verified in the code. 
-
-Finally, note that you can easily port this whole project over to a CLI tool of your choice (OpenCode, Codex, Gemini CLI, etc.) with a little bit of effort (the hooks are really the only hard part -- everything like the agents and skills should port over immediately). Fork this repo, work with your favorite tool to convert it over, and please continue to share it broadly with others!!! I would be excited to have people test this on open-source models, as well -- please reach out if you've got capacity to that end.
+**A note on credentials security:** Your Claude and/or API credentials only ever sit locally on your computer or go directly to the service provider, and I've enforced a LOT of safety checks to ensure Claude doesn't accidentally share it with anyone, either. This can be directly verified in the code.
 
 ### 2. Terminal
 
@@ -54,7 +61,7 @@ It's probably going to feel a bit weird, but you'll interact with DAAF/Claude Co
 |---------------------|---------|---------|
 | See where you are | `pwd` | Shows `/Users/yourname/daaf` |
 | List files here | `ls` | Shows files and folders in current directory |
-| Move into a folder in the current directory | `cd foldername` | `cd daaf` |
+| Move into a folder in the current directory | `cd foldername` | `cd daaf-docker` |
 | Go up one folder level | `cd ..` | Goes to the parent directory |
 | Clear the screen | `clear` | Clears clutter (your history is still there) |
 | Cancel a running command | `Ctrl + C` | Stops whatever is currently running |
@@ -72,437 +79,557 @@ It's probably going to feel a bit weird, but you'll interact with DAAF/Claude Co
 
 Docker is a program designed to help people create self-contained, isolated environments (called a "container") on your computer that are strictly separated from everything else, and extremely easy to replicate and share. This protects your computer and prevents Claude Code from messing with anything it shouldn't be, and it ensures that even if somehow things go catastrophic, you can easily spin up a new virtual environment back up in minutes with zero consequences. In this project, I also use Docker to install every needed piece of software in a predictable and stress-free way to have Python, data science libraries, and Claude Code all ready to go in one step. Think of it like a lightweight virtual computer running inside your computer that gets created via a very specific recipe, every single time. Docker Desktop includes everything you need (including Docker Compose, which coordinates the setup). After installing, make sure Docker Desktop is actually running before proceeding. If you're worried, you can see exactly what is installed by reading the Dockerfile in this repository -- feel free to ask your favorite LLM to help you interpret and inspect it, if you'd like. If you run into any Docker-related errors during install, you may need to restart your computer to let the install fully sink in.
 
-> **Need additional Python packages or tools?** DAAF comes pre-installed with a comprehensive data science stack, but you can add your own packages by editing the Dockerfile and rebuilding. See [**04. Extending DAAF -- Customizing Your Python Environment**](04_extending_daaf.md#customizing-your-python-environment) for step-by-step instructions, including how to test packages at runtime before making them permanent.
-
 **Install:** [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)
 
 ---
 
 ## Installing DAAF
 
-Okay, with all the prerequisites out of the way, installation itself is only eight very easy copy-paste steps and will only take about 5 minutes start-to-finish with a decent internet connection (as evidence, here's a quick video of me finishing [all of the steps in this section in just 3 minutes](https://youtu.be/jqkVLXA1CV4)!).
+With all the prerequisites out of the way, installation is a single command that takes about 5 minutes with a decent internet connection. The installer downloads some initial helper files, builds a Docker image with the full data science stack and Claude Code in a fully replicable way, and then downloads the complete DAAF repository into the container so that Claude Code runs using all of the added DAAF files.
 
-### Step 1: Choose a project download location on your computer and open it in your terminal
+### One-Line Install
 
-Using your terminal, first navigate to the folder where you want the installation files downloaded to:
+Make sure Docker Desktop is running in the background, then open your terminal, navigate to your desired installation directory, and paste the command for your operating system:
+
+**macOS / Linux (Terminal):**
 
 ```bash
-# Change the below to the folder you want!
-cd "C:\Users\Downloads"
+curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh | bash
+```
 
+**Windows (PowerShell):**
+
+```powershell
+irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1 | iex
 ```
 
-### Step 2: Download and extract the project files
+The installer will show its progress as it works through four steps: creating a build directory, downloading the Docker files, building the image, and cloning DAAF into the container. When it finishes, it prints instructions for entering the container and launching Claude Code.
 
-Download the DAAF project files as a ZIP archive from GitHub and extract them. The commands differ slightly depending on your operating system:
+### What the installer does
 
-<table>
-<tr>
-<td><strong>macOS / Linux (Terminal)</strong></td>
-<td><strong>Windows (PowerShell)</strong></td>
-</tr>
-<tr>
-<td>
+1. **Creates an installation directory** called `daaf-docker/` in whatever folder your terminal is currently in, containing all the files you'll need to run and manage DAAF from here on. For example, if you open your terminal and it starts in your home folder (`~` on Mac/Linux, `C:\Users\YourName` on Windows), that's where `daaf-docker/` will be created. You can `cd` to a different location first if you'd prefer to install elsewhere.
+2. **Builds the Docker image** with Python 3.12, 50+ data science packages, geospatial libraries, and Claude Code pre-installed. The first build downloads everything and takes a few minutes; subsequent rebuilds use Docker's layer cache and are much faster.
+3. **Downloads the DAAF repository** directly into the Docker volume inside the container. This gives you a full file edit and version history via Git.
+4. **Enforces security controls on Claude.** One of the big benefits of using Docker is that we can really keep Claude Code under control. The Docker container runs as a non-root user with all Linux capabilities dropped (`cap_drop: ALL`) and privilege escalation explicitly blocked (`no-new-privileges`). Even if Claude Code somehow tried to do something it shouldn't, the operating system kernel would stop it.
 
-```bash
-# Download the project files
-curl -L -o daaf.zip https://github.com/DAAF-Contribution-Community/daaf/archive/refs/heads/main.zip
+### Launch Claude Code with DAAF
 
-# Extract the ZIP file
-unzip daaf.zip
+Now, you'll use your terminal to enter the DAAF installation directory it just created with all the main utility files, `daaf-docker/`. Once you're in there, you can run a helper script I created to make it easy to launch DAAF and Claude Code in the Docker container automatically.
 
-# Enter the project directory
-cd daaf-main
+**macOS / Linux (Terminal):**
+
+```bash
+cd daaf-docker
+bash run_daaf.sh
 ```
 
-</td>
-<td>
+**Windows (PowerShell):**
 
 ```powershell
-# Download the project files
-Invoke-WebRequest -Uri "https://github.com/DAAF-Contribution-Community/daaf/archive/refs/heads/main.zip" -OutFile daaf.zip
+cd daaf-docker
+.\run_daaf.ps1
+```
 
-# Extract the ZIP file
-Expand-Archive -Path daaf.zip -DestinationPath .
+On first launch, Claude Code should prompt you to authenticate (API key or subscription login). Follow its instructions to complete the process as needed based on your method. Remember that CTRL+C actually exits the terminal, so use (Windows/Linux: CTRL+SHIFT+C and CTRL+V) and (macOS: Cmd+C and Cmd+V) if you want to copy/paste.
+
+### Configure Claude Code (required)
+
+Once you're in, there are a few settings to adjust to ensure that the workflow is able to operate as expected. First, type the following into Claude's chat window:
 
-# Enter the project directory
-cd daaf-main
+```bash
+/config
 ```
 
-</td>
-</tr>
-</table>
+And then change the following settings by navigating down with your arrow keys, editing settings with left-right arrow keys, and hitting Enter when done:
 
-This creates a `daaf-main` folder containing all the project files. You should now be inside the project directory. You can confirm this worked correctly by typing `ls` (or `dir` on Windows) to list the files in this folder: you'll see files like `CLAUDE.md`, `docker-compose.yml`, `Dockerfile`, and folders like `agent_reference/`, `user_reference/`, etc.
+- **"Auto-compact"** -- set to **False**. DAAF manages its own context carefully; auto-compaction can disrupt its orchestration and cause unexpected behavior.
+- **"Verbose output"** -- set to **True**. Verbose output lets you see what DAAF's agents are actually thinking behind the scenes, making it much easier to detect shortcuts in thinking, laziness in loading proper file references, and inconsistent logic/confusion. See [Understanding DAAF — The Non-Deterministic Side](02_understanding_daaf.md#the-non-deterministic-side-when-context-doesnt-load) for a deeper explanation of why this happens and what to watch for.
 
-> **Alternative:** If you prefer, you can also download the ZIP manually through your browser. Visit the [DAAF repository](https://github.com/DAAF-Contribution-Community/daaf), click the green **"Code"** button near the top-right, select **"Download ZIP"**, and then extract the downloaded file using your operating system's built-in tools (double-click on macOS, right-click → "Extract All" on Windows). Then open your terminal and navigate into the extracted folder.
+Note that you can check which Claude model is being used by checking the indicator below the chat line (Opus, Sonnet, Haiku). DAAF defaults to using Opus 4.6. You can change which Claude model is being used at any time by typing `/model`. All development and testing of this project was done using **Opus 4.5** and **Opus 4.6**. I unfortunately think that these models are absolutely required; other models (Sonnet, Haiku) are cheaper but not nearly as capable and produce erratic, inconsistent results. The complexity of tasks embedded in the DAAF workflow (multi-agent orchestration) relies on the model's ability to follow complex, multi-step protocols reliably. This is also the reason why the Claude Max subscription is a likely prerequisite here: Opus models are very resource-intensive, and it's hard to complete the DAAF workflows under the "Pro" or "Free" tiers accordingly.
 
-**Optional Note**: The commands above give you the latest development version of DAAF. This should generally be fine for everyone. If you'd prefer to install a specific release (e.g., for returning to a specific older version you prefer), you can download a tagged release instead (browse available releases and their changelogs on the [Releases page](https://github.com/DAAF-Contribution-Community/daaf/releases)):
+Opus 4.6 (unlike Opus 4.5) also allows you to select its "thinking level" by tapping left-and-right arrow keys while Opus 4.6 is selected on the /model selector in Claude Code. All tests I've conducted to date are using the "High" setting -- as this is a case where quality is far more important than quantity, I strongly recommend doing the same. This will have usage and API limit ramifications, though, so it is a reasonable thing to test out the tradeoffs for yourself! Please do report back with any findings so we can incorporate that into our guidance here.
 
-<table>
-<tr>
-<td><strong>macOS / Linux</strong></td>
-<td><strong>Windows (PowerShell)</strong></td>
-</tr>
-<tr>
-<td>
+After these settings are done, you're ready to begin working!
+
+### First Launch: Confirming Everything Works
+
+Once you've gotten Claude Code running in your terminal and your model is set, you're ready to start interacting with the DAAF-empowered Claude Code. Before you do anything else, let's confirm that Claude is actually seeing and using all the DAAF resources/guidelines first:
 
-```bash
-# Replace v1.0.0 with your desired version
-curl -L -o daaf.zip https://github.com/DAAF-Contribution-Community/daaf/archive/refs/tags/v1.0.0.zip
+```
+Hey Claude, can you tell me more about DAAF? What does it do, and
+why is it useful for researchers wanting to use Claude Code for data
+analysis work? Give me the elevator pitch for a newcomer
 ```
 
-</td>
-<td>
+If setup was successful and everything went through correctly, you should get back something quite specific and descriptive to the effect of:
 
-```powershell
-# Replace v1.0.0 with your desired version
-Invoke-WebRequest -Uri "https://github.com/DAAF-Contribution-Community/daaf/archive/refs/tags/v1.0.0.zip" -OutFile daaf.zip
+```
+DAAF: Data Analyst Augmentation Framework
+The Elevator Pitch
+DAAF is an agent orchestration system built on top of Claude Code
+that transforms it from a general-purpose coding assistant into a
+rigorous, reproducible research pipeline. It's designed for
+researchers who want AI-assisted data analysis but can't afford
+the typical pitfalls: hallucinated results, unreproducible workflows,
+silent data errors, or black-box methodology.
+
+The Problem It Solves
+When researchers use LLMs for data analysis, several things go wrong:
+1. No validation discipline — the AI writes a transformation, moves on,
+and nobody checks if it corrupted the data
+2. No audit trail — you get a result but can't trace how it was derived
+or what decisions were made along the way
+3. Context collapse — long analyses exhaust the AI's context window,
+leading to forgotten constraints and degraded output quality
+4. Scope drift — the AI quietly expands or changes the analysis
+without the researcher noticing
+5. No reproducibility — if you wanted to re-run the analysis or hand
+it to a colleague, you couldn't
+
+How DAAF Addresses This
+DAAF wraps Claude Code in a multi-agent pipeline with 12 stages across
+5 phases...
 ```
 
-</td>
-</tr>
-</table>
+On first run, it should present you with a user acknowledgment statement telling you more about your responsibilities in using DAAF, and then it should jump right in. You should get something equally specific to the above after confirming. 
 
-### Step 3: Copy the project files into Docker
+Talking conversationally with Claude in this way is one easy way you could get oriented to using DAAF. Ask it questions, dig into features, talk about pros and cons, and so on. It will intelligently reference both the user documentation and the workflow documentation as relevant (but it never hurts to remind it, "Based on a thorough read of the DAAF project documentation, can you tell me...?").
 
-Rather than let Claude use and edit files directly on your computer, we're going to make a **secure copy** for Claude to operate on separately using Docker. Run this command next, making sure that Docker Desktop is currently running in the background:
+From here, you can interact with Claude the same way you would with any AI assistant, but it'll "kick in" its DAAF-powered workflows and skillsets whenever relevant to supercharge anything related to data analysis work, data documentation spelunking, data exploration, and so on. If you want a gentle onboarding guide for actually using DAAF, head to [**02. Understanding and Working with DAAF**](02_understanding_daaf.md) next. 
+
+The rest of this guide covers basic day-to-day workflows, file management, keeping DAAF updated, and advanced configuration options — browse those at your own pace.
+
+> **Quick tip before you go any further**: Now that you have Claude Code up and running with DAAF, you can actually start asking Claude for help! If you have any questions, concerns, issues, or confusion about **anything** you read in this guide or other parts of the User Documentation: Ask Claude about it! DAAF has a dedicated **User Support** mode for exactly this -- just ask it what DAAF is, how something works, or what to do when you're stuck, and it will load its own documentation and walk you through it in plain language. This includes questions about the underlying tools too -- Docker, Git, Claude Code -- it can look up official documentation for those online when needed. Point it to any document, section, or sentence, and then ask it to help you understand it better. It has visibility into the whole project documentation at-will, so it should be able to help you out as you go. This kind of personalized assistance should be invaluable for anyone getting onboarded into using DAAF and Claude Code more generally!
+
+---
+
+## Day-to-Day Start/Stop Workflow
+
+### Starting a New Session
+
+Once you've completed the installation, your daily workflow is just to open your terminal again and run a single command. Make sure Docker Desktop is running first!
+
+**Quick start (recommended):**
+
+**macOS / Linux (Terminal):**
 
 ```bash
-# This uses Docker to help us copy files from your installation folder into a place Docker can work in later
-docker run --rm -v "${PWD}:/source:ro" -v "daaf_daaf-data:/dest" busybox sh -c 'cp -a /source/. /dest/'
+cd daaf-docker
+bash run_daaf.sh
 ```
 
-This copies all the project files into a **"Docker volume"** — a storage area managed by Docker that will serve as the Docker container's working directory. Think of it like creating a dedicated workspace inside Docker where all your research, data, and outputs will live. The project folder on your computer (e.g., `daaf-main/`) is used as the starting point here, but going forward, the Docker volume is where the actual work happens (see "How to Manage DAAF Project Files and Output" below for more on this). File permissions inside the volume are fixed automatically on every startup (see Step 4), so you don't need to worry about ownership issues here. You can confirm this worked correctly by looking at the Volumes panel in the Docker Desktop app left-side toolbar: you should see a Volume listed named `daaf_daaf-data` in the list.
+**Windows (PowerShell):**
+
+```powershell
+cd daaf-docker
+.\run_daaf.ps1
+```
+
+The `run_daaf` script handles everything: starts the container if it's not already running, then launches Claude Code directly. To enter the container shell instead of Claude Code (for manual commands, setting API keys, etc.), pass `bash` as an argument:
+
+```bash
+bash run_daaf.sh bash        # macOS / Linux
+.\run_daaf.ps1 bash          # Windows
+```
 
-### Step 4: Use Docker to create and start the container
+**Manual alternative (if you prefer individual commands):**
 
 ```bash
-# This code uses the docker-compose.yaml file to begin the Docker container with specific pre-sets
-docker compose up -d --build
+# Navigate to your daaf-docker folder (wherever you ran the installer)
+cd daaf-docker
+
+# Start the container (if it's not already running)
+docker compose up -d
+# Enter the container
+docker compose exec daaf-docker bash
+# Launch Claude Code
+claude
 ```
 
-This builds an isolated/protected Docker container with all the necessary tools pre-installed (Python, data science packages, Claude Code) using the Dockerfile provided and the copied project files from the Docker volume we just made. The first time, this downloads base images and installs all packages — expect it to take a few minutes as it pulls in all the needed software. Subsequent starts are really fast since Docker caches everything.
+---
 
-Behind the scenes, this command does a few important things automatically:
+## How to Manage DAAF Project Files and Output
 
-- **Fixes file permissions.** An init service runs before the main container starts, ensuring all files in the Docker volume are owned by the correct user. This prevents "Permission denied" errors, especially on macOS where Docker volumes can end up with mismatched ownership.
-- **Initializes a git repository.** On first startup, the container's entrypoint script automatically creates a local git repository inside the Docker volume. This enables DAAF's version tracking and audit trail features — you don't need to set this up yourself. The git repo is local-only (no remote configured), purely for traceability within your projects.
-- **Pins Claude Code.** The Dockerfile installs a specific, tested version of Claude Code (with auto-updates disabled) to ensure consistent behavior across builds.
-- **Enforces security hardening.** The container runs as a non-root user with all Linux capabilities dropped (`cap_drop: ALL`) and privilege escalation explicitly blocked (`no-new-privileges`). Even if Claude Code somehow tried to do something it shouldn't, the operating system kernel would stop it.
+Your research files, data, and outputs live inside the **Docker volume** we created during installation — a storage area managed by Docker. Think of the `daaf-docker/` folder on your computer as just the "recipe" that was used to set everything up, while the Docker volume is the actual "kitchen" where all the work happens.
 
-You can confirm this worked correctly by looking at the Images panel in the Docker Desktop app left-side toolbar: you should see an Image listed named `daaf-daaf-docker` in the list. You'll also see one named `busybox` — this is a tiny utility image used by the init service for permission fixing.
+This means:
+- **Your work persists** — stopping or restarting the Docker container does NOT delete anything. The Docker volume retains all your research outputs, data, and notebooks across restarts, rebuilds, and even `docker compose down`.
+- **Files don't automatically appear on your computer** — unlike a traditional shared folder, files created inside the container are stored in the Docker volume, not directly on your desktop. To access them directly, you can use the included file editor (VSCode -- see below).
+- **Only the Docker volume is accessible to Claude** — Claude can only see what's in the Docker volume. Your documents, photos, and everything else are completely isolated.
 
-### Step 5: Open a terminal session inside the Docker container
+### Viewing and Editing Files
 
-Once the Docker container setup is complete, your terminal will resume in the project folder. Run the following command to "enter" the Docker container we just created and turned on.
+The easiest way to browse, edit, and manage your files is with DAAF's built-in **browser-based code editor** (VS Code in the browser). Run this from your `daaf-docker` folder on your computer (no need to enter the container):
 
 ```bash
-docker compose exec daaf-docker bash
+cd daaf-docker
+bash run_vscode.sh              # macOS / Linux
+.\run_vscode.ps1                # Windows
 ```
 
-This opens your terminal session *inside* the container, separated from the rest of your computer and running with all the software just installed. You'll notice your terminal prompt changes — that's how you know you're "inside." Think of this like activating a mini virtual computer, within your computer, that you're now interacting with exclusively via this terminal. You can confirm this worked correctly by looking at the Containers panel in the Docker Desktop app left-side toolbar: you should see a Container listed named `daaf` in the list, with a dropdown extension/accordion button that'll reveal another item in the list named `daaf-docker-1`. 
+This opens a full VS Code editor at the URL [http://localhost:2720](http://localhost:2720) running in your favorite browser where you can explore the entire DAAF file tree, edit files, preview Markdown reports, view/edit Python scripts, and track changes with the built-in Git tools. It comes pre-loaded with extensions for Python syntax highlighting, Markdown preview, Git history visualization, and CSV viewing. The password is displayed in the terminal when you launch the script (default: `daaf`). A few things worth highlighting:
 
-### Step 6: Launch Claude Code
+- **The default access password is "daaf"** but the password can be customized at any time in your environment_settings.txt file. See the environment_settings_example.txt in your daaf-docker folder for instructions there.
+- **Markdown preview:** Right-click any `.md` file and select **"Open Preview"**, or press `Shift+Ctrl+V`, to see rendered Markdown with proper formatting — headers, tables, links, and all. This is the easiest way to read DAAF's reports and plans.
+- **File management:** Use the file explorer sidebar to browse, create, rename, move, and delete files. You can also drag and drop files from your computer into the sidebar to import them into the Docker volume.
+- **Git integration:** The Source Control panel (left sidebar) shows uncommitted changes, lets you view diffs, and browse commit history — useful for reviewing what DAAF produced during a session.
+- **Search:** Use `Ctrl+Shift+F` (or `Cmd+Shift+F` on Mac) to search across all files — helpful for finding specific variables, scripts, or content across a project.
 
-Now that we're in, we should have everything we need to start working. Enter the following command to launch Claude Code, configured with everything DAAF has to offer and ready to run.
+**Importing files into the Docker volume:** To bring files from your computer into the Docker volume for DAAF to use (e.g., a dataset you want to profile), you can simply drag and drop files into the code editor's file explorer sidebar. You can also download files by right-clicking them and selecting Download.
+
+You can also use the Docker Desktop GUI to explore the DAAF docker volume by navigating to the Volumes panel, clicking the daaf_daaf-data volume, and interacting with the file navigator here.
+
+### Backing Up Your Work
+
+Since your research files live inside the Docker volume, it'll be extremely important to regularly back up your work separately from the Docker volume. The easiest way is with the included backup script:
+
+**macOS / Linux (Terminal):**
 
 ```bash
-claude
+cd daaf-docker
+bash backup_daaf.sh
 ```
-On first launch, Claude Code should prompt you to authenticate (API key or subscription login). Follow its instructions to complete the process as needed based on your method. Remember that CTRL+C actually exits the terminal, so use (Windows/Linux: CTRL+SHIFT+C and CTRL+V) and (macOS: Cmd+C and Cmd+V) if you want to copy/paste.
 
-### Step 7: Adjust some quick configuration settings
+**Windows (PowerShell):**
 
-Once you're in, there are a few settings to adjust to ensure that the workflow is able to operate as expected. First, type the following into Claude's chat window:
+```powershell
+cd daaf-docker
+.\backup_daaf.ps1
+```
+
+The backup script creates a date-versioned folder (e.g., `2026-04-21_daaf_backup/`) in your `daaf-docker` directory. Multiple backups on the same day are automatically suffixed (`2026-04-21a_daaf_backup/`, `2026-04-21b_daaf_backup/`, etc.). Feel free to move or copy these folders to another location on your computer (or an external drive) for safekeeping, or share them with colleagues as needed for collaboration purposes.
+
+You can also back up manually using Docker Desktop's GUI: go into the Docker volume file viewer (see above) and download the whole `daaf` or `research` folder to somewhere else on your computer.
+
+### Restoring from a Backup
+
+If you need to restore your DAAF installation from a backup, use the included restore script. It searches your `daaf-docker` folder for backup folders, lets you pick one, and handles replacing the Docker volume contents cleanly.
+
+**macOS / Linux (Terminal):**
 
 ```bash
-/config
+cd daaf-docker
+bash restore_from_backup.sh
 ```
 
-And then change the **"Auto-compact"** setting to **False** and **"Verbose output"** setting to **True** by navigating down with your arrow keys and hitting Enter when the option is selected. When the settings are changed correctly, you can then hit the ESC key to return to the regular Claude chat and begin working.
+**Windows (PowerShell):**
 
-**Recommended model:** You can check which Claude model is being used by checking the indicator below the chat line (Opus, Sonnet, Haiku). You can change which Claude model is being used at any time by typing `/model`. All development and testing of this project was done using **Opus 4.5** and **Opus 4.6**. I unfortunately think that these models are absolutely required; other models (Sonnet, Haiku) are not nearly as capable and produce erratic, inconsistent results. The complexity of tasks embedded in the DAAF workflow (multi-agent orchestration) relies on the model's ability to follow complex, multi-step protocols reliably. This is also the reason why the Claude Max subscription is a likely prerequisite here: Opus models are very resource-intensive, and it's hard to complete the DAAF workflows under the "Pro" or "Free" tiers accordingly.
+```powershell
+cd daaf-docker
+.\restore_from_backup.ps1
+```
 
-Opus 4.6 (unlike Opus 4.5) also allows you to select its "thinking level" by tapping left-and-right arrow keys while Opus 4.6 is selected on the /model selector in Claude Code. All tests I've conducted to date are using the "High" setting -- as this is a case where quality is far more important than quantity, I strongly recommend doing the same. This will have usage and API limit ramificiations, though, so it is a reasonable thing to test out the tradeoffs for yourself! Please do report back with any findings so we can incorporate that into our guidance here.
+**Important:** Restoring is a destructive operation -- the script completely erases the current Docker volume contents and replaces them with the backup. Make sure DAAF is not running when you restore (run `docker compose down` first if needed). The script checks for running containers and warns you if any are active.
 
-### Step 8 (Optional): Set up data source API keys
+**A note on git and DAAF:** A full git repository is set up inside the Docker volume during installation (via the `git clone` in the installer). During research sessions, DAAF's agents will make **local git commits** inside the container to track every script version, data transformation, and plan update — this creates a detailed audit trail of your research that you can review with standard git tools (like `git log`). A remote is configured by default (pointing to the upstream DAAF repository for updates), but nothing is ever pushed there without your explicit instruction. Your research work lives safely in the Docker volume, and the local git history is there purely for traceability and reproducibility within your own projects. If you want a GitHub backup for your work, ask Claude how to make your own repository and save to it accordingly.
 
-Most DAAF data sources — including all built-in education data from the Urban Institute — are **freely accessible with no authentication required**. You can skip this step entirely if you're only working with education data.
+### Viewing Session Logs in Your Browser
 
-However, some data domains require API keys from their hosting platforms. The table below shows API keys for data sources that ship with DAAF. When you onboard a new data source from an API via Data Onboarding Mode, DAAF will guide you through setting up the appropriate environment variable using the same pattern shown here. You can set multiple API keys simultaneously — each uses a unique environment variable name.
+DAAF includes an interactive timeline viewer (the **DAAF Log Explorer**) that lets you visually explore what happened during any session -- every tool call, subagent dispatch, and file reference, organized chronologically.
 
-If you plan to use any of these data sources, you'll need to set the corresponding environment variable **inside the Docker container, before launching Claude Code**:
+**Quickest way -- from your host machine (no container shell needed):**
 
-| Data Source | Environment Variable | Where to Get a Key |
-|-------------|---------------------|-------------------|
-| County Presidential Election Returns (Harvard Dataverse) | `HARVARD_DATAVERSE_API_KEY` | [dataverse.harvard.edu](https://dataverse.harvard.edu/) → Log in → Account name (top-right) → API Token → Create Token |
+```bash
+cd daaf-docker
+bash view_logs.sh            # macOS / Linux
+.\view_logs.ps1              # Windows
+```
+
+This starts the container (if needed), generates the manifest from all sessions in the overarching session logs folder, and starts the server. Open the URL it prints in your browser. Press Ctrl+C to stop.
 
-To set a key for your current session:
+**From inside the container** (for per-project viewing):
 
 ```bash
-# Run this inside the Docker container, BEFORE running `claude`
-export HARVARD_DATAVERSE_API_KEY="your_token_here"
+# 1. Copy and collect relevant logs into your project (if not already done)
+bash /daaf/scripts/collect_session_logs.sh /daaf/research/YYYY-MM-DD_Your_Project
+
+# 2. Generate the project-specific manifest and start the server
+bash /daaf/scripts/generate_log_viewer.sh /daaf/research/YYYY-MM-DD_Your_Project
 ```
 
-To make it persist across container restarts, add the `export` line to `~/.bashrc` inside the container:
+Port 2719 is mapped in `docker-compose.yml` for this purpose, alongside port 2718 (Marimo notebooks).
+
+### Viewing Marimo Notebooks in Your Browser
+
+DAAF uses a python library called "marimo" to create streamlined python code "notebooks" as part of its analysis. It can also use this library to create nice, interactive dashboards for you of analyses it has completed.
+
+**Quickest way — from your host machine (no container shell needed):**
 
 ```bash
-echo 'export HARVARD_DATAVERSE_API_KEY="your_token_here"' >> ~/.bashrc
+cd daaf-docker
+bash view_notebooks.sh       # macOS / Linux
+.\view_notebooks.ps1         # Windows
 ```
 
-> **Note:** DAAF's safety guardrails prevent Claude from reading or writing `.env` files, so environment variables must be set directly in the shell. This is by design — your credentials stay in temporary memory only and are never written to files that could be accidentally committed to a public repository or shared outside the container.
-
-If you skip this step and later try to analyze election data, DAAF will inform you that the API key is missing and point you back to these instructions.
+This opens marimo's built-in notebook browser at [http://localhost:2718](http://localhost:2718), where you can browse all your research projects and open any notebook for viewing or editing. The script handles starting the container if it isn't already running. The nice thing about these is that they're also written in regular Python code, so you can inspect its code very easily in any text editor as well.
 
 ---
 
-### First Launch: Confirming Everything Works
+## Keeping DAAF Updated
 
-Once you've gotten Claude Code running in your terminal and your model is set, you're ready to start interacting with the DAAF-empowered Claude Code. Before you do anything else, let's confirm that Claude is actually seeing and using all the DAAF resources/guidelines first:
+DAAF is actively being developed and updated. If you'd like to pull in the latest fixes, extensions, and updates (which for a while may be as often as daily!!), updating is straightforward. Before updating, I recommend backing up your Docker volume's research folder as a precaution (see "Backing Up Your Work" above).
+
+### If you installed with the one-line installer (recommended method)
 
+Assuming you used `install.sh` or `install.ps1`, your DAAF container has a full git repository with a remote configured. Updating is a single command run from your `daaf-docker` folder on the host:
+
+```bash
+cd daaf-docker
+
+bash update_daaf.sh          # macOS / Linux
+.\update_daaf.ps1            # Windows
 ```
-Hey Claude, can you tell me more about DAAF? What does it do, and 
-why is it useful for researchers wanting to use Claude Code for data 
-analysis work? Give me the elevator pitch for a newcomer
+
+The update script handles everything for you:
+- **Offers to back up first** — runs `backup_daaf` to create a full copy of your Docker volume before making any changes
+- **Checks for the GitHub remote copy** — if you used the manual install (no remote), it tells you how to add one
+- **Fetches and compares** — shows you how many new commits are available
+- **Checks for local edits** — if you've customized any framework files (CLAUDE.md, a skill, a template, etc.), it shows you exactly what you changed and presents options instead of overwriting anything
+- **Handles local commits** — if you've committed your own changes, it offers to merge or rebase them with the update
+- **Pulls safely** — if there are no local changes, it pulls the latest updates automatically
+- **Offers Claude Code for conflicts** — if a merge conflict occurs, you can launch Claude Code directly to help resolve it interactively
+- **Syncs utility scripts** — automatically copies any updated host-side scripts (run, backup, rebuild, update) from the container
+- **Auto-rebuilds if needed** — if the Dockerfile or docker-compose.yml changed, it offers to run `rebuild_daaf` automatically
+
+By default, the update script auto-detects the remote's default branch (`main` or `master`). If you installed from a specific branch (e.g., `dev` or a release tag) and want to keep updating from that branch, set the `DAAF_BRANCH` environment variable — the same one used by the installer:
+
+```bash
+# macOS / Linux
+DAAF_BRANCH=dev bash update_daaf.sh
+
+# Windows PowerShell
+$env:DAAF_BRANCH = "dev"; .\update_daaf.ps1
 ```
 
-If setup was successful and everything went through correctly, you should get back something quite specific and descriptive to the effect of:
+If `DAAF_BRANCH` is not set, the updater defaults to `main` (or `master` if `main` doesn't exist). The script validates that the specified branch exists on the remote before proceeding.
+
+Your research files in `research/` are not tracked by git (they're local to your volume), so they are completely unaffected by updates.
+
+**If the Dockerfile changed** (new packages, updated Claude Code version, etc.), you'll also need to rebuild the Docker image. The update script will detect this automatically and print instructions. 
 
+```bash
+# From your host terminal, navigate to your daaf-docker folder and rebuild
+cd daaf-docker
+bash rebuild_daaf.sh         # macOS / Linux
+.\rebuild_daaf.ps1           # Windows
 ```
-DAAF: Data Analyst Augmentation Framework
-The Elevator Pitch
-DAAF is an agent orchestration system built on top of Claude Code 
-that transforms it from a general-purpose coding assistant into a 
-rigorous, reproducible research pipeline. It's designed for 
-researchers who want AI-assisted data analysis but can't afford 
-the typical pitfalls: hallucinated results, unreproducible workflows, 
-silent data errors, or black-box methodology.
 
-The Problem It Solves
-When researchers use LLMs for data analysis, several things go wrong:
-1. No validation discipline — the AI writes a transformation, moves on,
-and nobody checks if it corrupted the data
-2. No audit trail — you get a result but can't trace how it was derived
-or what decisions were made along the way
-3. Context collapse — long analyses exhaust the AI's context window,
-leading to forgotten constraints and degraded output quality
-4. Scope drift — the AI quietly expands or changes the analysis
-without the researcher noticing
-5. No reproducibility — if you wanted to re-run the analysis or hand
-it to a colleague, you couldn't
+The rebuild script handles everything: it copies the updated Dockerfile and docker-compose.yml from the container to the host, then rebuilds the image. This copy step is needed because `docker compose up --build` reads the host copy of the Dockerfile, not the one inside the container.
 
-How DAAF Addresses This
-DAAF wraps Claude Code in a multi-agent pipeline with 12 stages across
-5 phases...
+Most updates don't change the Dockerfile, so usually `git pull` inside the container is all you need.
+
+**Prefer to update to specific releases only?** If you'd rather update in discrete, tested versions instead of tracking the latest changes on `main`, you can check out a specific tag:
+
+```bash
+# Inside the container
+git fetch --tags
+git checkout v2.1.0
 ```
 
-I promise that's genuinely the first response I got back while testing this! Talking conversationally with Claude in this way is one easy way you could get oriented to using DAAF. Ask it questions, dig into features, talk about pros and cons, and so on. It will intelligently reference both the user documentation and the workflow documentation as relevant (but it never hurts to remind it, "Based on a thorough read of the DAAF project documentation, can you tell me...?"). 
+Check the [Releases page](https://github.com/DAAF-Contribution-Community/daaf/releases) to see what's changed in each version.
 
-From here, you can interact with Claude the same way you would with any AI assistant, but it'll "kick in" its DAAF-powered workflows and skillsets whenever relevant to supercharge anything related to data analysis work, data documentation spelunking, data exploration, and so on. If you want a gentle onboarding guide for actually using DAAF (fully written by a human for other humans!), we'll cover that in the next section: [**02. Understanding and Working with DAAF**](02_understanding_daaf.md). I used to be a high school English teacher, so this is the fun part for me, honestly. 
+### Migrating from an older installation
 
-That being said, let's go over just a few more technical details and how-to's before we get there.
+If you installed DAAF **v2.0.1 or earlier** — back when the installation process involved downloading a ZIP file and copying it into Docker — you may not have the update scripts (`update_daaf.sh` / `update_daaf.ps1`) in your `daaf-docker` folder. Without these scripts, you can't use the standard update process described above.
 
-> **Quick tip before you go any further**: Now that you have Claude Code up and running with DAAF, you can actually start asking Claude for help! If you have any questions, concerns, issues, or confusion about **anything** you read in this guide or other parts of the User Documentation: Ask Claude about it! DAAF has a dedicated **User Support** mode for exactly this -- just ask it what DAAF is, how something works, or what to do when you're stuck, and it will load its own documentation and walk you through it in plain language. This includes questions about the underlying tools too -- Docker, Git, Claude Code -- it can look up official documentation for those online when needed. Point it to any document, section, or sentence, and then ask it to help you understand it better. It has visibility into the whole project documentation at-will, so it should be able to help you out as you go. This kind of personalized assistance should be invaluable for anyone getting onboarded into using DAAF and Claude Code more generally!
+**How to tell if this applies to you:** Open your `daaf-docker` folder on your computer (wherever you originally set up DAAF). If you don't see a file called `update_daaf.sh` (macOS/Linux) or `update_daaf.ps1` (Windows), you need to run the one-time update migration first.
+
+**What the migration does:**
+
+- Downloads some utility scripts (`run_daaf`, `update_daaf`, `backup_daaf`, `restore_from_backup`, `rebuild_daaf`, `view_logs`, `view_notebooks`, `run_vscode`) to your host machine so you have all the same convenience tools as a fresh install
+- Creates a full backup of your Docker volume before making any changes
+- Connects your local git history to the official DAAF repository so that future updates can merge in cleanly
+- Preserves everything — your research files, any framework customizations you've made, and your full git audit trail are all kept intact
+
+**Running the migration:**
+
+The migration is a single command, just like the original installer. Make sure Docker Desktop is running, open your terminal, navigate to your `daaf-docker` folder, and run:
+
+| Platform | One-liner |
+|----------|-----------|
+| **macOS / Linux** | `curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/migrate_daaf.sh \| bash` |
+| **Windows PowerShell** | `irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/migrate_daaf.ps1 \| iex` |
+
+The migration script is safe to re-run if it gets interrupted — it detects what's already been completed and picks up where it left off. Your research files are never modified; only git metadata (the connection to the upstream repository) is updated.
+
+**After migration:** You'll have all the same utility scripts as a fresh install. From this point forward, you can use `update_daaf.sh` / `update_daaf.ps1` for all future updates, exactly as described in the section above.
 
 ---
 
-## Day-to-Day Start/Stop Workflow
+## Advanced Installation & Configuration
 
-Now that you've got DAAF installed and running for the first time, let's talk through simple commands you'll use to get in and out of this workflow day-to-day, as well as how to manage files produced by DAAF.
+The sections below cover additional installation options for users with specific needs. If you completed the standard installation above and everything is working, you can skip this entire section and come back later if and when you need it.
 
-### Starting a New Session
+### Installing a specific version or branch
+
+By default, the installer pulls the latest code from the `main` branch. To install a specific release or branch instead, set the `DAAF_BRANCH` environment variable before running the installer:
 
-Once you've completed the above Docker installation steps, your daily workflow is just to open your terminal again and run the following commands:
+**macOS / Linux (Terminal):**
 
 ```bash
-# Get into the project directory, inputting the right file path for your own system
-cd "C:\Users\Documents\daaf-main"
-# Make sure Docker Desktop is running on your computer, then start the Docker container:
-docker compose up -d
-# Enter into the Docker container again
-docker compose exec daaf-docker bash
-# Run Claude
-claude
+# Install a tagged release
+export DAAF_BRANCH=v2.1.0
+curl -fsSL "https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/${DAAF_BRANCH}/scripts/host/install.sh" | bash
+
+# Install from a development branch
+export DAAF_BRANCH=dev
+curl -fsSL "https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/${DAAF_BRANCH}/scripts/host/install.sh" | bash
 ```
 
-### Ending a Session
+**Windows (PowerShell):**
 
-When you're ready to end a session, you have two options. The first option: Close the terminal window, and then use your Docker Desktop app window to "pause" your Docker container (click the Containers panel in the left-side toolbar, look for "daaf" in the list that appears, hit the "Stop" button). The other option is to do this fully through the terminal: 
+```powershell
+# Install a tagged release
+$env:DAAF_BRANCH="v2.1.0"; irm "https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/$env:DAAF_BRANCH/scripts/host/install.ps1" | iex
 
-```bash
-# Exit Claude Code first. You can also just press CTRL+C twice
-/exit
-# That gets you back into the terminal window, running *within* your Docker container. 
-# You'll know you're still in the Docker container if your command line says something like, "appuser@5jhfdsn54:/daaf$" before whatever you type
-# So now let's exit the Docker container
-exit
-# And then we can turn off the Docker container
-docker compose down
+# Install from a development branch
+$env:DAAF_BRANCH="dev"; irm "https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/$env:DAAF_BRANCH/scripts/host/install.ps1" | iex
+```
 
-# You can then just close your terminal. All the DAAF files and research outputs remain safe and persist in the Docker volume we created at installation time
+This fetches the installer itself from the specified branch, and also controls the Docker build files and repository clone, so everything comes from the specified branch or tag consistently. The `export` on macOS/Linux is required so that the variable is inherited by the `bash` process on the other side of the pipe. Check the [Releases page](https://github.com/DAAF-Contribution-Community/daaf/releases) to see available versions. If `DAAF_BRANCH` is not set, the installer defaults to `main`.
+
+### Re-installing DAAF
+
+If you run the installer on a system where DAAF is already installed, it will detect the existing installation and stop with a warning. This is a safety feature — re-running the installer would overwrite your framework files (CLAUDE.md, skills, agents, templates) and local git history, though your research data in `research/` would not be deleted.
+
+**To update DAAF** (recommended — preserves your local changes), use the update script instead:
+
+```bash
+cd daaf-docker
+bash update_daaf.sh          # macOS / Linux
+.\update_daaf.ps1            # Windows
 ```
 
-## How to Manage DAAF Project Files and Output
+See [**Keeping DAAF Updated**](#keeping-daaf-updated) for details on what the update script does.
 
-Your research files, data, and outputs live inside the **Docker volume** we created during installation — a storage area managed by Docker, **copied from** the project folder on your computer (e.g., `daaf-main/`). Think of that folder on your computer as the "recipe" that was used to set everything up, while the Docker volume is the actual "kitchen" where all the work happens.
+**To force a complete re-install** (overwrites all framework files), set the `DAAF_FORCE_REINSTALL` environment variable:
 
-This means:
-- **Your work persists** — stopping or restarting the container does NOT delete anything. The Docker volume retains all your research outputs, data, and notebooks across restarts, rebuilds, and even `docker compose down`.
-- **Files don't automatically appear on your computer** — unlike a traditional shared folder, files created inside the container are stored in the Docker volume, not directly on your desktop. To access them directly, you'll use Docker Desktop or simple copy commands (see below).
-- **Only the Docker volume is accessible to Claude** — Claude can only see what's in the Docker volume. Your documents, photos, and everything else are completely isolated.
+**macOS / Linux:**
+```bash
+DAAF_FORCE_REINSTALL=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.sh)"
+```
 
-### Viewing Files in Docker Desktop
+**Windows (PowerShell):**
+```powershell
+$env:DAAF_FORCE_REINSTALL = "1"; irm https://raw.githubusercontent.com/DAAF-Contribution-Community/daaf/main/scripts/host/install.ps1 | iex
+```
 
-The easiest way to browse your files is through Docker Desktop's graphical interface:
+Back up your Docker volume first (see [**Backing Up Your Work**](#backing-up-your-work)) if you have research data or framework customizations you want to preserve.
 
-1. Open **Docker Desktop**
-2. Click **Containers** in the left-side toolbar
-3. Click the "expand" arrow on the container named **`daaf`** and then click on the name **`daaf-daaf-docker-1`**
-4. Select the **Files** tab to see the file tree
-5. Navigate into `daaf` and then `research` to find your project folders
+If the installer detects a previous attempt that didn't complete successfully (e.g., the Docker build failed partway through), it will note this and proceed automatically — no override needed.
 
-From here, you can download copies of individual folders or files to your computer by right-clicking on them. You can also Import files into the Docker volume from your computer by right-clicking, as well.
+### Configure authentication via environment_settings.txt
 
-### Backing Up Your Work
+By default, Claude Code prompts you to log in interactively the first time you launch it (browser-based OAuth or pasting an API key). This works great for Max subscription and direct API key setups. However, if you're using **OpenRouter**, a **cloud provider** (Bedrock/Vertex), or simply want your authentication to persist automatically without interactive login, you can configure it through the `environment_settings.txt` file in your `daaf-docker` folder.
 
-Since your research files live inside the Docker volume, it'll be extremely important to regularly back up your work separately from the Docker volume. You can do that most easily using the Docker Desktop method above (go into the Docker volume file viewer and download the whole daaf or research folder to somewhere else on your computer).
+Your `daaf-docker` folder includes an `environment_settings_example.txt` template that documents all five supported authentication methods with the exact environment variables needed for each. To set it up:
 
-**A note on git and DAAF:** A local git repository is automatically created inside the Docker volume the first time the container starts (via the entrypoint script — see Step 4). During research sessions, DAAF's agents will make **local git commits** inside the container to track every script version, data transformation, and plan update — this creates a detailed audit trail of your research that you can review with standard git tools (like `git log`). This git repo is local-only — no remote repository is configured by default, so nothing is pushed anywhere. Your research work lives safely in the Docker volume, and the local git history is there purely for traceability and reproducibility within your own projects. If you want a GitHub backup for your work, ask Claude how to make your own repository and save to it accordingly.
+1. **Copy the template** (if you haven't already):
 
-### Viewing report Markdown (.md) files
+   **macOS / Linux (Terminal):**
+   ```bash
+   cd daaf-docker
+   cp environment_settings_example.txt environment_settings.txt
+   ```
 
-LLM assistants work best on text files, which means that proprietary document formats like Microsoft Word or Google Docs aren't great for this type of work. DAAF produces all its output report documents in Markdown (.md) format. You can open these in any basic text editor, but basic text editors tend not to display the formatting very nicely. I recommend installing a basic Markdown viewer, or you can copy the Markdown text into any free online viewer (e.g., [StackEdit](https://stackedit.io/app)) 
+   **Windows (PowerShell):**
+   ```powershell
+   cd daaf-docker
+   Copy-Item environment_settings_example.txt environment_settings.txt
+   ```
 
----
+2. **Open `environment_settings.txt` in any text editor** and uncomment the section matching your authentication method. For example, to use OpenRouter:
+   ```bash
+   # --- Option C: OpenRouter (third-party model gateway) ---
+   ANTHROPIC_BASE_URL=https://openrouter.ai/api
+   ANTHROPIC_AUTH_TOKEN=your_openrouter_api_key_here
+   ANTHROPIC_API_KEY=
+   OPENROUTER_API_KEY=your_openrouter_api_key_here
+   ```
+   Replace `your_openrouter_api_key_here` with your actual OpenRouter API key (format: `sk-or-v1-...`). Get one at [openrouter.ai/settings/keys](https://openrouter.ai/settings/keys). Note that `ANTHROPIC_API_KEY=` must be set to an empty value (not removed entirely) — this tells Claude Code to use the auth token instead of trying to authenticate directly with Anthropic.
 
-## Keeping DAAF Updated
+3. **Restart the container** to pick up the changes:
+   ```bash
+   docker compose down
+   bash run_daaf.sh            # macOS / Linux
+   .\run_daaf.ps1              # Windows
+   ```
 
-DAAF is actively being developed and updated. If you'd like to pull in the latest fixes, extensions, and updates (which for a while may be as often as daily!!), updating is straightforward. Before updating, I recommend backing up your Docker volume's research folder as a precaution (see "Backing Up Your Work" above).
+4. **If you previously logged in interactively** with Anthropic, run `/logout` inside Claude Code before switching to an `environment_settings.txt`-based method — cached credentials can take priority over environment variables.
 
-The update process has two parts: (1) copying the latest framework files into your Docker volume, and (2) rebuilding the Docker image to pick up any changes to installed software or container configuration. Your research files (everything in the `research/` folder) will not be affected by either step.
+> **Only uncomment ONE authentication section.** If multiple methods are set, Claude Code uses the highest-priority one (see the priority order documented in `environment_settings_example.txt`). This can lead to unexpected billing if, for example, you have both an API key and an OAuth token set.
 
-<table>
-<tr>
-<td><strong>macOS / Linux (Terminal)</strong></td>
-<td><strong>Windows (PowerShell)</strong></td>
-</tr>
-<tr>
-<td>
+> **Note:** The `environment_settings.txt` file is also where you'll configure data source API keys (covered in the next section). Both authentication and data source credentials live in the same file and are loaded together when the container starts.
 
-```bash
-# Navigate to wherever you'd like to download
-# the update files (e.g., your Downloads folder)
-cd ~/Downloads
-
-# Download the latest version
-curl -L -o daaf.zip https://github.com/DAAF-Contribution-Community/daaf/archive/refs/heads/main.zip
-
-# Extract it
-unzip -o daaf.zip
-
-# Enter the extracted directory
-cd daaf-main
-
-# Copy the updated framework files into your
-# Docker volume (skips research/ to preserve
-# your projects). Make sure Docker Desktop is
-# running!
-docker run --rm \
-  -v "${PWD}:/source:ro" \
-  -v "daaf_daaf-data:/dest" \
-  busybox sh -c '\
-    for item in /source/*; do \
-      name=$(basename "$item"); \
-      if [ "$name" != "research" ]; then \
-        rm -rf "/dest/$name"; \
-        cp -a "$item" "/dest/$name"; \
-      fi; \
-    done'
-
-# Rebuild the Docker image to pick up any
-# changes to installed packages, Claude Code
-# version, or container configuration
-docker compose up -d --build
-```
-
-</td>
-<td>
+### Set up data source API keys
 
-```powershell
-# Navigate to wherever you'd like to download
-# the update files (e.g., your Downloads folder)
-cd "$env:USERPROFILE\Downloads"
+Most DAAF data sources — including all built-in education data from the Urban Institute — are **freely accessible with no authentication required**. You can skip this step entirely if you're only working with education data.
 
-# Download the latest version
-Invoke-WebRequest -Uri "https://github.com/DAAF-Contribution-Community/daaf/archive/refs/heads/main.zip" -OutFile daaf.zip
+However, some data domains require API keys from their hosting platforms. The table below shows API keys for data sources that ship with DAAF. When you onboard a new data source from an API via Data Onboarding Mode, DAAF will guide you through setting up the appropriate environment variable using the same pattern shown here. You can set multiple API keys simultaneously — each uses a unique environment variable name.
 
-# Extract it (overwrite existing)
-Expand-Archive -Path daaf.zip -DestinationPath . -Force
+| Data Source | Environment Variable | Where to Get a Key |
+|-------------|---------------------|-------------------|
+| County Presidential Election Returns (Harvard Dataverse) | `HARVARD_DATAVERSE_API_KEY` | [dataverse.harvard.edu](https://dataverse.harvard.edu/) → Log in → Account name (top-right) → API Token → Create Token |
 
-# Enter the extracted directory
-cd daaf-main
+#### Recommended: Use an environment_settings.txt file (persistent across restarts)
 
-# Copy the updated framework files into your
-# Docker volume (skips research/ to preserve
-# your projects). Make sure Docker Desktop is
-# running!
-docker run --rm `
-  -v "${PWD}:/source:ro" `
-  -v "daaf_daaf-data:/dest" `
-  busybox sh -c '
-    for item in /source/*; do
-      name=$(basename "$item");
-      if [ "$name" != "research" ]; then
-        rm -rf "/dest/$name";
-        cp -a "$item" "/dest/$name";
-      fi;
-    done'
+Your `daaf-docker` folder includes an `environment_settings_example.txt` template. Copy it to `environment_settings.txt` and fill in your keys:
 
-# Rebuild the Docker image to pick up any
-# changes to installed packages, Claude Code
-# version, or container configuration
-docker compose up -d --build
+**macOS / Linux (Terminal):**
+```bash
+cd daaf-docker
+cp environment_settings_example.txt environment_settings.txt
 ```
 
-</td>
-</tr>
-</table>
+**Windows (PowerShell):**
+```powershell
+cd daaf-docker
+Copy-Item environment_settings_example.txt environment_settings.txt
+```
+
+Then open `environment_settings.txt` in any text editor and uncomment/fill in the keys you need:
 
-**What each step does:**
-- The `docker run ... busybox` command copies all framework files (agents, skills, templates, hooks, etc.) into your Docker volume while deliberately skipping the `research/` folder so your projects, data, and outputs are preserved. File permissions are fixed automatically by the init service when the container next starts.
-- The `docker compose up -d --build` command rebuilds the Docker image from the newly downloaded `Dockerfile` and `docker-compose.yml`. This ensures you pick up any changes to installed Python packages, the Claude Code version, or container configuration (like security settings). If nothing in the Dockerfile changed, Docker's layer caching makes this very fast.
+```bash
+# Remove the leading # and replace the placeholder with your actual key
+HARVARD_DATAVERSE_API_KEY=your_token_here
+```
 
-> **Note on git inside the container:** The git repository inside the Docker volume is local-only — it was created by the container's entrypoint script for DAAF's internal version tracking, and has no remote configured. Running `git pull` inside the container will not work unless you've manually added a remote. The update process above is the recommended way to stay current.
+The `environment_settings.txt` file is loaded automatically when the container starts. Edits to `environment_settings.txt` are not applied while the container is running — you need to recreate it to pick up changes:
 
-**Prefer to update to specific releases only?** If you'd rather update in discrete, tested versions instead of tracking the latest changes on `main`, download a specific release tag instead. Check the [Releases page](https://github.com/DAAF-Contribution-Community/daaf/releases) to see what's changed in each version before updating, and replace `main` in the download URL with the version tag (e.g., replace `refs/heads/main.zip` with `refs/tags/v1.0.0.zip`).
+```bash
+docker compose down
+bash run_daaf.sh            # macOS / Linux
+.\run_daaf.ps1              # Windows
+```
 
----
+> **Security note:** The `environment_settings.txt` file lives on your host machine (in `daaf-docker/`), is gitignored by default, and is never visible to Claude inside the container. DAAF's safety guardrails prevent Claude from reading or writing environment settings files by design — your credentials stay strictly on your side of the boundary.
 
-## Viewing Marimo Notebooks in Your Browser
+#### Alternative: Set keys manually in the container shell
 
-The assistant uses a python library called "marimo" to create streamlined python code "notebooks" as part of its analysis. It can also use this library to create nice, interactive dashboards for you of analyses it has completed. To **view** one in your browser:
+If you prefer not to use an `environment_settings.txt` file, you can set environment variables directly inside the container before launching Claude Code:
 
 ```bash
-# Get into the project directory, inputting the right file path for your own system
-cd "C:\Users\Documents\daaf-main"
-# Make sure Docker Desktop is running on your computer, then start the Docker container:
-docker compose up -d
-# Enter into the Docker container again
-docker compose exec daaf-docker bash
-# Inside the container, you can run the following command to view a notebook
-# Note that the first bit should be the (replace the path with your actual notebook)
-marimo run 'research/YYYY-MM-DD_Title/YYYY-MM-DD_Notebook_Name.py' --host 0.0.0.0 --port 2718 --headless
-```
+# Enter the container shell
+bash run_daaf.sh bash        # macOS / Linux
+.\run_daaf.ps1 bash          # Windows
 
-Then open [http://localhost:2718](http://localhost:2718) in your computer's browser (no need to mess with anything in the terminal here). The notebook renders there as an interactive document. The nice thing about these is that they're also written in regular Python code, so you can inspect its code very easily in any text browser as well.
+# Set the key for this session
+export HARVARD_DATAVERSE_API_KEY="your_token_here"
 
-To **edit** a notebook interactively, use `marimo edit` instead of `marimo run`:
+# Then launch Claude Code
+claude
+```
+
+To make manual exports persist across container restarts, add the `export` line to `~/.bashrc` inside the container:
 
 ```bash
-marimo edit 'research/YYYY-MM-DD_Title/YYYY-MM-DD_Notebook_Name.py' --host 0.0.0.0 --port 2718 --headless
+echo 'export HARVARD_DATAVERSE_API_KEY="your_token_here"' >> ~/.bashrc
 ```
 
+Note that the `environment_settings.txt` file approach above is simpler and recommended — it persists automatically and you can edit it with your normal text editor on your computer without entering the container.
+
+If you skip this step and later try to analyze election data, DAAF will inform you that the API key is missing and point you back to these instructions.
+
 ---
 
 ## Setup Troubleshooting
@@ -510,16 +637,19 @@ marimo edit 'research/YYYY-MM-DD_Title/YYYY-MM-DD_Notebook_Name.py' --host 0.0.0
 > **Tip:** If you run into an issue not listed here, or you want more help understanding any of these errors, try asking DAAF directly -- its **User Support** mode can help troubleshoot Docker, Git, and Claude Code problems and can look up the latest official documentation online.
 
 - **"docker: The term 'docker' is not recognized as the name of a cmdlet, function, script file, or operable program" or "docker: command not found"** — Make sure you have Docker installed successfully. You may need to restart your computer after installation for it to fully register in your Terminal.
-- **"unable to get image 'daaf-daaf-docker'"** — Make sure Docker Desktop is running and that you've run the initial `docker compose up -d --build` command during installation to create the necessary Docker image first. You can confirm it exists in the Docker Desktop app Images panel on the left-side toolbar.
-- **"service "daaf-docker" is not running"** — Make sure Docker Desktop is running and that you've run the `docker compose up -d` command to start the Docker container first. You can confirm it's running in the Docker Desktop app Containers panel on the left-side toolbar.
-- **Container seems really slow to build the first time** — The first `docker compose up -d --build` downloads base images and installs all packages. This is a one-time cost — subsequent starts are fast since Docker caches everything.
+- **"unable to get image 'daaf-daaf-docker'"** — Make sure Docker Desktop is running and that the installer completed successfully. If the installer finished without errors, the image should already exist -- you can confirm in the Docker Desktop app Images panel on the left-side toolbar. If it's missing, try running the installer again.
+- **"service "daaf-docker" is not running"** — Make sure Docker Desktop is running and that you've started the container. The `run_daaf` script handles this automatically, but you can also confirm the container is running in the Docker Desktop app Containers panel on the left-side toolbar. If the container isn't listed, try running the installer again.
+- **Container seems really slow to build the first time** — The initial installation downloads base images and installs all packages. This is a one-time cost — subsequent starts are fast since Docker caches everything.
 - **"I can't find my research files on my computer"** — With Docker volumes, your research files live inside Docker's managed storage, not in the project folder on your computer. See **How to Manage DAAF Project Files and Output** above for more information.
-- **"Port 2718 already in use" when trying to view Marimo notebooks** — Another process is using that port. Either stop it, or change the port mapping in `docker-compose.yml` (e.g., `"3000:2718"` to use port 3000 on your host).
+- **"Port 2718 already in use" when trying to view Marimo notebooks** — Another process is using that port. Either stop it, or change the port mapping in `docker-compose.yml` (e.g., `"127.0.0.1:3000:2718"` to use port 3000 on your host).
+- **"Port 2719 already in use" when trying to view session logs** — Same fix: stop the conflicting process, or change the port mapping (e.g., `"127.0.0.1:3001:2719"`). Port 2719 is used by the DAAF Log Explorer (`generate_log_viewer.sh`).
+- **"Port 2720 already in use" when trying to open the browser-based code editor** — Same fix: stop the conflicting process, or change the port mapping (e.g., `"127.0.0.1:3002:2720"`). Port 2720 is used by the browser-based code editor (`run_vscode.sh` / `run_vscode.ps1`).
 - **Permission denied errors inside the container (especially on macOS)** — If you see errors like `Permission denied` when Claude tries to read or write files, the Docker volume likely has files owned by root or your host UID instead of the container's `appuser` (UID 1000). This is a known issue with Docker Desktop on macOS. The `docker-compose.yml` includes an init service (`daaf-init`) that automatically fixes file ownership on every startup. To resolve this: stop the container (`docker compose down`), then restart it (`docker compose up -d`) — the init service will repair permissions before the main container starts. If you still have issues, you can fix permissions manually:
   ```bash
   docker run --rm -v "daaf_daaf-data:/daaf" busybox chown -R 1000:1000 /daaf
   ```
-- **Claude Code asks for an API key every time** — Claude Code stores its configuration inside the Docker volume, so it persists across normal container restarts. However, if your authentication state is lost, you can persist your API key by adding it to `~/.bashrc` inside the container: `echo 'export ANTHROPIC_API_KEY="your_key_here"' >> ~/.bashrc`. Note: DAAF's safety guardrails prevent Claude from reading `.env` files, so environment variables should be set directly in the shell or via `~/.bashrc` (consistent with the API key setup in Step 8).
+- **Claude Code asks for an API key every time** — Claude Code stores its authentication state inside the Docker volume, so it persists across normal container restarts. If your authentication state is lost, the most reliable fix is to configure your credentials in the `environment_settings.txt` file (see [**Configure authentication via environment_settings.txt**](#configure-authentication-via-environment_settingstxt) above) — this ensures authentication persists automatically on every container start. Alternatively, you can add your key to `~/.bashrc` inside the container: `echo 'export ANTHROPIC_API_KEY="your_key_here"' >> ~/.bashrc`.
+- **OpenRouter: "model not found" or authentication errors** — Double-check three things: (1) `ANTHROPIC_BASE_URL` must be exactly `https://openrouter.ai/api` with no `/v1` suffix (the `/v1` variant is for OpenAI-compatible tools, not Claude Code), (2) `ANTHROPIC_API_KEY` must be set to an empty value (`ANTHROPIC_API_KEY=`), not removed entirely — if it's unset, Claude Code falls back to Anthropic's servers, and (3) if you previously logged in with Anthropic interactively, run `/logout` inside Claude Code to clear cached credentials. You can verify your connection is working by typing `/status` inside Claude Code and checking the [OpenRouter Activity Dashboard](https://openrouter.ai/activity) for incoming requests.
 
 ---
 
@@ -528,4 +658,7 @@ marimo edit 'research/YYYY-MM-DD_Title/YYYY-MM-DD_Notebook_Name.py' --host 0.0.0
 - [**02. Understanding and Working with DAAF**](02_understanding_daaf.md) — Learn to work with DAAF for the first time: what to expect, how to use it, and how to test its strengths and limitations
 - [**06. FAQ: Philosophy**](06_faq_philosophy.md) — Grapples with the broader implications of this work, AI automation in general, model advancement pace, approaching the "exponential", environmental ethics, what this means for the next generation of researchers, and more
 - [**07. FAQ: Technical Support**](07_faq_technical.md) — Covers frequently asked questions about Docker, issues with Claude Code, usage limits, authentication errors, and other common errors
-- [**Back to main**](https://github.com/DAAF-Contribution-Community/daaf/tree/main)
+
+---
+
+[**Back to main**](https://github.com/DAAF-Contribution-Community/daaf/tree/main)
diff --git a/user_reference/02_understanding_daaf.md b/user_reference/02_understanding_daaf.md
index dadd2ba..9ef71ce 100644
--- a/user_reference/02_understanding_daaf.md
+++ b/user_reference/02_understanding_daaf.md
@@ -34,11 +34,12 @@ Alright, before we begin ANYTHING else, we need to cover the first and most foun
 
 So with that in mind, DAAF can be thought of as a way for me to help other researchers by **automating and simplifying the prompt-engineering process** specifically for core aspects of the data analysis and research process. This is how we accomplish the core requirement of making DAAF scalable. Every single thing about how I've designed DAAF is really just fundamentally designed to tell Claude exactly **what** I think it needs to know, **when** I think it needs to know it, so it does what we want **more often and with higher quality** on average. Ignoring the fancy terms like agents, subagents, skills, orchestrators, etc. -- DAAF is just a series of pre-cooked "recipes" of context that we feed to Claude before it tries to do what you ask, with the hope that it'll be thus be more successful at doing it transparently and rigorously and reproducibly like a scientist would prefer. Anyone can put this together without DAAF in simpler ways or just ad-hoc (i.e., by writing a single very long, custom prompt to regular Claude Code) -- I'm just trying to make it easier for people with sensible defaults and opinionated standards of rigor.
 
-This then leads to three (hopefully very intuitive) of the core things to be aware of when using and working with DAAF:
+This then leads to four (hopefully very intuitive) of the core things to be aware of when using and working with DAAF:
 
 * In addition to the prompt engineering DAAF orchestrates behind the scenes, **what you ask Claude to do and how you ask it to do it** is an immensely important element of getting better quality output from DAAF/Claude. So a lot of what we'll talk about here is how to do this thoughtfully and well to maximize your chances of getting something useful from DAAF.
 * The system is **designed to intelligently select and inject the right context to Claude before your query/question/chat**, based on what you provide in your query/question/chat. But this is **NOT** foolproof, and simply cannot account for every possibility. Feel free to go off the beaten path at will, but just be aware that it's going to necessarily be less supported and structured from there; you may ultimately find it's not working very well for what you want, because I wasn't able to design for that style of work. Trying to write your query in a different way can help, or you can help us improve DAAF by [opening an issue](https://github.com/DAAF-Contribution-Community/daaf/issues) and telling us about it!
 * Because thoughtfully shaping the context is our way of shaping Claude's thinking from what I lovingly describe as an over-eager recent MBA graduate to a thoughtful, careful research colleague, DAAF really only works with the cutting-edge models like Opus 4.6, and it pushes them to their limit to take advantage of their full context windows where possible. **This is why it is SO expensive to use at this time**; settling for less, we sacrifice a lot of expertise and reliability and rigor. It's a careful balancing act of optimization that no one really has fully figured out!
+* While DAAF's reference files, skills, and workflow instructions are all carefully designed to be loaded at specific moments, Claude may occasionally fail to load them, skip a step, or deviate from its instructions in subtle ways. When this happens, you get an agent working without the specialized knowledge it was supposed to have, which means it falls back on its general training -- and that's when hallucinations, fabricated variable names, and plausible-sounding-but-wrong details creep in. This is why **Verbose output** in Claude Code's `/config` settings is particularly useful: it lets you see what DAAF's agents are actually thinking behind the scenes, including what motivates which files they're reading and which skills they're loading (or what shortcuts they're deciding on, if they are).
 
 So that's the gist for now. But before we move on to how DAAF actually works, there's one more mental model that I think is really helpful for understanding *why* people have such different experiences with AI right now -- and why something like DAAF matters in the first place.
 
@@ -143,7 +144,7 @@ Before doing anything else, DAAF will tell you which mode it's classifying your
 - A stakeholder report synthesizing key findings, methodology, and limitations
 - A lessons-learned document with data and process insights
 
-**Expected time investment:** About 5-10 minutes of active engagement time spread across 4-5 "check-in" points where DAAF pauses for your review and approval, a few hours of DAAF working independently in the background, and then whatever time you (rightfully, importantly) dedicate to reviewing the final outputs. And, of course, whatever API fees you incur along the way. Full duration will depend heavily on how complex your query is: primarily how many scripts it needs to write, rewrite, and QA. Plan accordingly!
+**Expected time investment:** About 5-10 minutes of active engagement time spread across four "check-in" points where DAAF pauses for your review and approval, a few hours of DAAF working independently in the background, and then whatever time you (rightfully, importantly) dedicate to reviewing the final outputs. And, of course, whatever API fees you incur along the way. Full duration will depend heavily on how complex your query is: primarily how many scripts it needs to write, rewrite, and QA. Plan accordingly!
 
 **When to use it:** When you have a genuine research question you want to explore with data. It can be as simple as "How has enrollment in rural schools changed over the past decade?" or as complex as "What's the relationship between school-level poverty, access to advanced coursework, and disciplinary disparities, controlling for school size and urbanicity?" DAAF will scope accordingly.
 
@@ -246,49 +247,20 @@ Before doing anything else, DAAF will tell you which mode it's classifying your
 
 ### Switching Between Modes
 
-DAAF supports clean transitions between modes when it makes sense:
+DAAF supports clean transitions between modes when your work naturally evolves. You don't need to memorize every possible transition -- DAAF will suggest the right mode at natural breakpoints and wait for your confirmation. It should never silently switch modes on you.
+
+Here are the most common transitions you'll encounter:
 
 | From | To | When it happens |
 |------|----|-----------------|
-| Data Discovery | Full Pipeline | Findings suggest a feasible and valuable analysis |
-| Data Lookup | Data Discovery | Your question reveals a broader data landscape worth exploring |
-| Data Lookup | Ad Hoc Collaboration | Your question evolves into a multi-turn discussion |
-| Data Lookup | Full Pipeline | A quick lookup reveals an actionable analysis opportunity |
-| Data Discovery | Data Onboarding | Do you have a raw data file you want to profile and make reusable? |
-| Data Onboarding | Full Pipeline | Skill created — would you like to analyze this data now? |
-| Full Pipeline | Data Onboarding | Analysis needs a dataset that has no existing skill yet |
-| Full Pipeline | Revision and Extension | You just completed an analysis and want to adjust or extend something |
-| Revision and Extension | Full Pipeline | The revision scope grows beyond what targeted modification can handle |
-| Data Onboarding | Revision and Extension | You want to modify or extend the skill that was just created |
-| Full Pipeline (complete) | Reproducibility Verification | User wants to verify their analysis reproduces |
-| Reproducibility Verification | Revision and Extension | Divergence found, user wants to fix original |
-| Reproducibility Verification | Full Pipeline | Original analysis is fundamentally broken |
-| Ad Hoc Collaboration | Full Pipeline | Your working session evolves into a formal analysis |
-| Ad Hoc Collaboration | Data Discovery | You want systematic data exploration across sources |
-| Ad Hoc Collaboration | Data Onboarding | You have raw data that needs profiling |
-| Ad Hoc Collaboration | Revision and Extension | Debugging reveals an existing analysis needs revision |
-| Data Discovery | Ad Hoc Collaboration | You want to discuss findings and iterate on approach |
-| Full Pipeline (early) | Ad Hoc Collaboration | You realize you just want to talk through the approach, not run the full pipeline |
-| Full Pipeline (complete) | Ad Hoc Collaboration | You want to discuss results or plan next steps informally |
-| Ad Hoc Collaboration | Framework Development | User wants to create or modify DAAF framework components |
-| Framework Development | Data Onboarding | User wants to onboard a dataset, not just create a skill template |
-| Framework Development | Full Pipeline | User wants to test a new skill with actual analysis |
-| Framework Development | Ad Hoc Collaboration | User needs analysis help, not framework changes |
-| Framework Development | Revision and Extension | User wants to review or revise an analysis that used the framework |
-| Framework Development | Data Discovery | Framework change requires testing with a specific data source |
-| Data Onboarding (complete) | Framework Development | User wants to refine the skill beyond what Onboarding produced |
-| Full Pipeline (complete) | Framework Development | User identifies framework improvements from analysis experience, or LEARNINGS.md has actionable items to incorporate |
-| Data Onboarding (complete) | Framework Development | LEARNINGS.md from profiling has actionable framework improvements (e.g., skill template gaps) |
-| User Support | Data Lookup | User's question is really about a specific data variable or definition |
-| User Support | Data Discovery | User wants to explore what data is available for a topic |
-| User Support | Full Pipeline | User is ready to run an analysis |
-| User Support | Ad Hoc Collaboration | User wants hands-on help with code, debugging, or a specific task |
-| User Support | Data Onboarding | User wants to add or profile a new dataset |
-| User Support | Revision and Extension | User wants to modify an existing analysis |
-| User Support | Reproducibility Verification | User wants to verify an analysis reproduces |
-| User Support | Framework Development | User wants to modify DAAF itself |
-
-DAAF will always propose these escalations explicitly and wait for your confirmation. It should never silently switch modes on you.
+| Data Discovery | Full Pipeline | Your exploration revealed a feasible, interesting analysis |
+| Full Pipeline | Revision and Extension | You completed an analysis and want to adjust or extend it |
+| Data Onboarding | Full Pipeline | You profiled a dataset and now want to analyze it |
+| Ad Hoc Collaboration | Full Pipeline | Your working session evolved into something worth formalizing |
+| Full Pipeline | Reproducibility Verification | You want to verify a completed analysis reproduces |
+| Any mode | User Support | You have questions about how DAAF or its tools work |
+
+Beyond these common paths, DAAF supports transitions between any pair of modes where the shift makes sense -- for example, a Data Lookup that reveals a broader question might escalate to Data Discovery, or a completed analysis might surface framework improvements worth addressing in Framework Development mode. The full transition matrix is handled internally; the important thing to know is that DAAF will always propose a transition explicitly and explain why before making it.
 
 ---
 
@@ -463,10 +435,13 @@ research/2026-01-24_School_Poverty_Analysis/
 └── output/
     ├── analysis/
     │   └── 2026-01-24_regression_results.parquet
-    └── figures/
-        └── 2026-01-24_poverty_distribution.png
+    ├── figures/
+    │   └── 2026-01-24_poverty_distribution.png
+    └── preliminary_notes/
 ```
 
+**Tip:** The easiest way to browse a completed project is with the browser-based code editor. Run `bash run_vscode.sh` (or `.\run_vscode.ps1` on Windows) from your `daaf-docker` folder, then navigate the file tree in the sidebar. You can preview Markdown reports and plans with `Shift+Ctrl+V`, read Python scripts with syntax highlighting, and inspect the Git history to see what changed and when. See [**03. Best Practices — Using the Browser-Based Code Editor**](03_best_practices.md#using-the-browser-based-code-editor) for more.
+
 Let's go through each piece.
 
 ### The Plan Document (Plan.md)
@@ -519,11 +494,11 @@ A companion file, **Plan_Tasks.md**, contains the detailed machine-readable task
 
 **What you won't see:** New analysis code, interactive dashboards, filter widgets, or additional transformations. The notebook is a viewer, not an analysis tool. This is by design -- it ensures that what you see in the notebook is exactly what was executed and validated in the scripts, with nothing added or changed.
 
-**How to view it:** From inside your Docker container:
+**How to view it:** The easiest way is to run `bash view_notebooks.sh` (or `.\view_notebooks.ps1` on Windows) from your `daaf-docker` folder — this opens marimo's notebook browser at [http://localhost:2718](http://localhost:2718) where you can browse and open any notebook. Alternatively, from inside the container you can view a single notebook read-only with:
 ```bash
 marimo run 'research/YYYY-MM-DD_Title/YYYY-MM-DD_Notebook.py' --host 0.0.0.0 --port 2718 --headless
 ```
-Then open [http://localhost:2718](http://localhost:2718) in your normal web browser. You can also open the `.py` file in any text editor -- marimo notebooks are just Python.
+You can also open the `.py` file in any text editor -- marimo notebooks are just Python.
 
 ### The Report
 
@@ -539,7 +514,7 @@ Then open [http://localhost:2718](http://localhost:2718) in your normal web brow
 
 **How it differs from the notebook:** The notebook is for thorough *methodological inspection* -- browsing every line of code and verifying what happened. The report is for *communication* -- telling the story of what was found and what it means. They're complementary artifacts serving different audiences.
 
-**How to view it:** The report is a Markdown (.md) file. You can open it in any text editor, but it'll look much nicer in a Markdown viewer. I recommend copying the contents into a free online viewer like [StackEdit](https://stackedit.io/app), or installing a Markdown viewer extension for your code editor.
+**How to view it:** The report is a Markdown (.md) file. The easiest way to read it with proper formatting is in the browser-based code editor — run `bash run_vscode.sh` (or `.\run_vscode.ps1` on Windows) from your computer's `daaf-docker` folder (i.e., don't run the terminal inside the container for this), navigate to the report file, then right-click and select **"Open Preview"** (or press `Shift+Ctrl+V`) to see the rendered Markdown with headers, tables, and formatting. 
 
 ### Data Files (Raw and Processed)
 
@@ -555,11 +530,13 @@ Then open [http://localhost:2718](http://localhost:2718) in your normal web brow
 
 **`output/figures/`** -- Data visualizations saved as PNG images. These are the same figures referenced in the report. You can open them with any image viewer.
 
+**`output/preliminary_notes/`** -- Complete, uncompressed findings from discovery-phase specialists -- data exploration results, source-specific research, and the research synthesis. These files ensure that downstream analysis steps have access to the full detail from early research, not just summaries.
+
 ### STATE.md and LEARNINGS.md
 
 **STATE.md** -- A session state file that tracks DAAF's progress through the analysis. It records transformation progress, checkpoint statuses, runtime decisions, and any blockers encountered. It also accumulates the QA Findings Summary (aggregated quality review results across all stages), the Final Review Log (from the end-of-pipeline verification), any Runtime Risks discovered during execution, and Citations Accumulated (a running ledger of data source, methodological, software, and reporting standard citations extracted as each script executes). If a session is interrupted (context exhaustion, network issues, etc.), STATE.md allows DAAF to resume exactly where it left off. You generally don't need to read this unless debugging a session issue.
 
-**`logs/`** -- Session transcripts collected into the project folder at completion. When a project finishes, DAAF gathers all session transcripts that touched the project's files into this directory, making each project self-contained for audit purposes. If an analysis spanned multiple sessions, you'll find transcripts from each one here. These are copies of the global archives in `.claude/logs/sessions/` -- see the [Session Logs and Diagnostics FAQ](07_faq_technical.md#session-logs-and-diagnostics) for details on formats and storage.
+**`logs/`** -- Session transcripts collected into the project folder at completion. When a project finishes, DAAF gathers all session transcripts that touched the project's files into this directory, making each project self-contained for audit purposes. If an analysis spanned multiple sessions, you'll find transcripts from each one here. These are copies of the global archives in `.claude/logs/sessions/` -- see the [Session Logs and Diagnostics FAQ](07_faq_technical.md#session-logs-and-diagnostics) for details on formats and storage. You can browse these logs visually using the **DAAF Log Explorer**, an interactive timeline that shows orchestrator actions, subagent dispatches, and tool calls in your browser — run `bash view_logs.sh` (or `.\view_logs.ps1` on Windows) from your `daaf-docker` folder on the host. See the [Installation Guide — Viewing Session Logs](01_installation_and_quickstart.md#viewing-session-logs-in-your-browser) for details.
 
 **LEARNINGS.md** -- A lessons-learned document capturing insights about the data and the analysis process. This includes data idiosyncrasies discovered during the analysis, interpretation concerns, and suggested improvements to DAAF's documentation. This file is designed to be immediately actionable -- you can share it back with the community to help improve DAAF for future users.
 
@@ -758,6 +735,22 @@ DAAF will read STATE.md, understand where it stopped, and resume from that exact
 
 **Reproducibility Verification mode note:** RV mode uses `Reproduction_Report.md` as its session state document instead of STATE.md. If an RV session is interrupted, the Reproduction Report contains a "Session Continuity" section with a restart prompt. The recovery process works the same way — start a new session and paste the restart prompt, and DAAF will pick up where it left off.
 
+### How to Restart a Session
+
+When DAAF determines that context is running low, it will do three things:
+
+1. **Save progress** by updating STATE.md with everything completed so far
+2. **Provide a restart prompt** -- a pre-written message that captures exactly where the work left off, what has been done, and what needs to happen next
+3. **Tell you it's time to restart**
+
+To resume, the steps are simple:
+
+1. Type `/clear` in the Claude Code terminal to reset the session (this clears the context window but does not affect any files on disk)
+2. Paste the restart prompt that DAAF provided
+3. DAAF reads STATE.md, picks up where it left off, and continues working
+
+That's it. The restart prompt does the heavy lifting of re-establishing context so you don't have to re-explain anything. If you closed your terminal entirely (or the session crashed), just start a new Claude Code session and point DAAF to the project folder -- it will read STATE.md and figure out where to resume.
+
 ### Tips for Multi-Session Work
 
 - **Don't panic if a session ends mid-analysis.** This is undesired but not unexpected for complex analyses. The whole STATE.md system exists precisely for this reason.
@@ -776,10 +769,11 @@ Here's a quick reference for what each part of the DAAF repository contains and
 |-----------|-------------|-------------|
 | `research/` | Your analysis projects -- notebooks, data, reports, scripts | **You** (this is where all your work lives) |
 | `user_reference/` | User documentation (you're reading one right now) | **You** (human-written guides and FAQs) |
-| `.claude/agents/` | Specialized agent protocols (12 behavioral definitions) | **DAAF** (and curious users who want to understand how agents work) |
+| `.claude/agents/` | Specialized agent protocols (14 behavioral definitions) | **DAAF** (and curious users who want to understand how agents work) |
 | `agent_reference/` | Detailed workflow documentation, templates, validation rules | **DAAF** (internal reference material for the orchestrator and agents) |
 | `.claude/skills/` | Skill definitions providing domain knowledge | **DAAF** (and users who want to create new skills) |
-| `scripts/` | Shared utility scripts (like `run_with_capture.sh`) | **DAAF** (used from the DAAF root directory; not copied into projects) |
+| `scripts/` | Shared utility scripts (`run_with_capture.sh`, `collect_session_logs.sh`, `generate_log_viewer.sh`, `launch_marimo.sh`, `launch_code_server.sh`) | **DAAF** (used from the DAAF root directory; not copied into projects) |
+| `scripts/host/` (copied to your `daaf-docker/` folder during installation) | Host-side convenience scripts (`run_daaf`, `view_logs`, `view_notebooks`, `run_vscode`, `backup_daaf`, `restore_from_backup`, `rebuild_daaf`, `update_daaf` -- `.sh` and `.ps1` variants) | **You** (run from your `daaf-docker` folder on the host, outside the container) |
 
 **Key insight for new users:** Everything you need to review, share, or reproduce is inside the project folder. You can copy the entire folder to a colleague and they'd have everything needed to understand and verify the analysis. That's the whole point of reproducibility.
 
diff --git a/user_reference/03_best_practices.md b/user_reference/03_best_practices.md
index 2051df7..a312565 100644
--- a/user_reference/03_best_practices.md
+++ b/user_reference/03_best_practices.md
@@ -15,7 +15,7 @@ Practical wisdom for getting the most out of DAAF while maintaining research qua
 - [**When and How to Request Revisions**](#when-and-how-to-request-revisions)
 - [**Appropriate vs. Inappropriate Use Cases**](#appropriate-vs-inappropriate-use-cases)
 - [**Using Git Version Control**](#using-git-version-control)
-- [**Using VSCode and Similar Interfaces**](#using-vscode-and-similar-interfaces)
+- [**Using the Browser-Based Code Editor**](#using-the-browser-based-code-editor)
 - [**Safety with Claude Code**](#safety-with-claude-code)
 - [**Recommended Next Steps**](#recommended-next-steps)
 
@@ -236,6 +236,8 @@ I recommend this review order:
 
 You do *not* need to read everything in detail every time. The report is the synthesis; the notebook is the evidence; the scripts are the primary source. Go as deep as you need to based on how much you trust the results and how high-stakes the analysis is.
 
+**Tip:** Before diving into individual artifacts, consider browsing the session visually using the **DAAF Log Explorer**. Run `bash view_logs.sh` (or `.\view_logs.ps1` on Windows) from your `daaf-docker` folder to see an interactive timeline of every orchestrator action, subagent dispatch, and tool call. This gives you a high-level map of the entire session, making it easier to identify which stages or scripts deserve closer inspection.
+
 ### Reading the Report
 
 The report follows a standard structure (Executive Summary, Key Findings, Data & Methodology, Limitations, etc.). When reviewing it, focus on:
@@ -338,6 +340,30 @@ But automated validation cannot assess everything. Here is what still requires a
 
 **Ethical considerations.** DAAF does not assess the ethical dimensions of your analysis. If you are working with data that involves vulnerable populations, politically sensitive topics, or potential for misuse of findings, those considerations are entirely your responsibility.
 
+### Monitoring DAAF's Internal Reference Loading
+
+There's one oversight responsibility that's easy to overlook because it's about DAAF's own internal mechanics rather than the substance of your analysis: **making sure DAAF actually loaded the reference files and skills it was supposed to load.**
+
+LLMs are non-deterministic, and DAAF's reference loading is orchestrated by an LLM. This means that occasionally -- not often, but not never -- an agent will proceed without loading a skill it was instructed to load, or the orchestrator will skip a reference file it was supposed to read. When this happens, the agent falls back on its general training, which produces output that looks correct but is built on plausible inference rather than curated knowledge.
+
+**Verbose output is your primary monitoring tool.** When you set Verbose output to True in `/config` (which you should -- it's a [required configuration setting](01_installation_and_quickstart.md#configure-claude-code-required)), you can see the internal thought process informing the file reads that DAAF's agents make. Here's what to watch for:
+
+**Signs that something may not have loaded:**
+- An agent explicitly mentions wanting to load something but then never doing it
+- An agent notes in its thinking block instructions to load a reference file, but deciding it doesn't need to for some ambiguous reason
+- An agent makes confident claims about variable names, API endpoints, or coded values that you can't find in the actual data or documentation
+- An agent writes code that uses variable names or data structures that don't match what the data source actually provides
+- You see an agent proceed directly to writing code without any visible skill or reference loading in the verbose output
+- Error messages about unexpected columns, missing variables, or failed API calls -- these often indicate the agent was working from hallucinated rather than loaded specifications
+
+**What to do when you suspect a loading failure:**
+1. **Ask DAAF to verify.** Simply say something like: "Can you check whether the agent actually loaded the CCD skill before writing that script?" or "That variable name doesn't look right -- can you verify it against the data source documentation?"
+2. **Request a re-run.** If a script was clearly written without the right context, ask DAAF to re-run that specific step with explicit instructions to load the relevant skill first.
+3. **Check the script execution logs.** Even if the agent hallucinated a variable name, the script's execution log will show whether the code actually worked. Failed scripts with `KeyError` or unexpected empty results often point back to a loading failure.
+4. **Check Session logs to verify reference loading sequences.** DAAF's built-in session log viewer was built in part to help users monitor exactly whether and when DAAF loads proper reference files to inform its work. Load up your session and explore how the orchestrator and subagents loaded reference files accordingly.
+
+The good news is that DAAF's dual-layer validation (CP checkpoints + QA code review) will catch many loading failures *downstream* -- a script that uses fabricated variable names will typically fail at execution or get flagged during QA review. But catching failures early, at the loading stage, saves time and prevents the cascading revisions that follow a fundamentally misinformed script.
+
 ---
 
 ## When and How to Request Revisions
@@ -395,7 +421,7 @@ When you are on the fence, DAAF will offer its assessment. But a useful rule of
 
 ## Appropriate vs. Inappropriate Use Cases
 
-DAAF is still very much in its nasceny, and there is only so much that one person and his friends can do to check guardrails, test robustness, and so on. With that in mind, it is important to be extremely transparent about what that means in practice.
+DAAF is still very much still in active development, and there is only so much that one person and his friends can do to check guardrails, test robustness, and so on. With that in mind, it is important to be extremely transparent about what that means in practice.
 
 ### Appropriate Uses
 
@@ -427,7 +453,7 @@ These should not be done with DAAF (or any LLM-based system) regardless of the g
 
 ## Using Git Version Control
 
-When you start using DAAF, you'll find that it produces a LOT of files, and it does a LOT of things at once. Once best practice I'd strongly encourage is to get comfortable with using Git for version control. This is part of why I treat it as a prerequisite for using DAAF in the installation process (spoilers: there were other ways to do it!): This type of work with LLMs just benefits so immensely from having a full audit log of file edits and changes at all times, with the ability to roll back changes and identify issues quickly.
+When you start using DAAF, you'll find that it produces a LOT of files, and it does a LOT of things at once. One best practice I'd strongly encourage is to get comfortable with using Git for version control. This is part of why I treat it as a prerequisite for using DAAF in the installation process (spoilers: there were other ways to do it!): This type of work with LLMs just benefits so immensely from having a full audit log of file edits and changes at all times, with the ability to roll back changes and identify issues quickly.
 
 I would strongly recommend making a private "fork" of the DAAF repository for you to work in and back up all of your research files to (though DAAF by default will NOT back up your parquet data files to avoid accidentally sharing data up to the cloud). Teaching Git is a bit beyond the scope of this project, but you absolutely can and should ask Claude to tell you more about:
 
@@ -439,17 +465,47 @@ I would strongly recommend making a private "fork" of the DAAF repository for yo
 
 There are also a ton of guides online and on YouTube, etc. Take some time to get oriented! It's an immensely useful skillset.
 
+### Useful Git Commands for DAAF Work
+
+Here are a few concrete commands that are especially handy when working with DAAF:
+
+- **`git diff HEAD~1`** -- See exactly what changed in the last session. This is great for reviewing what DAAF produced overnight or after a long run. It shows every file that was added, modified, or deleted, with the specific changes highlighted.
+- **`git log --oneline -10`** -- See the 10 most recent commits in a compact format. Since DAAF's sessions are typically committed at the end, this gives you a quick history of recent sessions and what they produced.
+- **`git stash` / `git stash pop`** -- Temporarily set aside all uncommitted changes and restore them later. This is useful if you want to experiment with something (like testing a different analysis approach) without committing to it. Run `git stash` to save your current changes, do your experiment, and then run `git stash pop` to bring your original changes back.
+
+You can run these commands in the Claude Code terminal inside the container, or in any terminal connected to the DAAF repository.
+
 ---
 
-## Using VSCode and Similar Interfaces
+## Using the Browser-Based Code Editor
+
+In addition to using Git, and part and parcel with it: having a good file editor is essential for working with DAAF and Claude Code. You'll want a way to:
+- Browse and manage files within the Docker volume
+- Edit and preview Markdown files (reports, plans) in their rendered format
+- Track changes using Git in an intuitive interface
+- Search across files, review scripts, and inspect data
+
+DAAF ships with a **built-in browser-based code editor** ([code-server](https://github.com/coder/code-server) -- VS Code in the browser) that handles all of the above with zero installation on your host machine. I strongly recommend keeping it open in a browser tab alongside your Claude Code terminal session. To launch it, run this from your `daaf-docker` folder:
+
+```bash
+bash run_vscode.sh              # macOS / Linux
+.\run_vscode.ps1                # Windows
+```
+
+Then open **http://localhost:2720** in your browser. The password is displayed in the terminal output (default: `daaf`). The script handles starting the container if it isn't already running.
+
+The browser editor comes pre-loaded with extensions for Python syntax highlighting, Markdown preview, Git history visualization, and CSV viewing -- everything you need to comfortably browse and review DAAF's output. A few key features worth knowing:
+
+- **Markdown preview:** Right-click any `.md` file and select **"Open Preview"**, or press `Shift+Ctrl+V`, to see the rendered report with proper formatting. This is by far the easiest way to read DAAF's reports and plans.
+- **File management:** Drag and drop files from your computer into the file explorer sidebar to import them into the Docker volume (e.g., a dataset you want to profile). Create, rename, move, and delete files directly.
+- **Git integration:** The Source Control panel (left sidebar) shows uncommitted changes, lets you view diffs, and browse commit history -- invaluable for reviewing what DAAF produced during a session.
+- **Search across files:** `Ctrl+Shift+F` (or `Cmd+Shift+F` on Mac) searches across all files in the project -- great for finding specific variables, scripts, or content.
+
+### Alternative: Desktop VSCode with Dev Containers
 
-In addition to using Git, and part and parcel with it: I currently use [VSCode](https://code.visualstudio.com) as my main driver for working with DAAF and Claude Code. VSCode is basically a nice interface that collects all of the following in an easy-to-use sort of format:
-- File management within the Docker volume (using the "Dev containers" extension)
-- File editing for markdown files, and viewing markdown files in their rendered format
-- Tracking changes for files using Git in a super easy and intuitive interface
-- Doing intensive file searches, edits, and similar
+If you already have [VSCode](https://code.visualstudio.com) installed on your computer and prefer a native desktop experience, you can connect it directly to the DAAF container. Install the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and use the "Attach to Running Container" command to open the DAAF container's filesystem directly in VSCode. This gives you a full file browser, integrated terminal, and your own preferred extensions and settings.
 
-There are a bunch of similar alternatives that are also designed to be a bit more teched-up with coding agents built in (e.g., Cursor), but I've found VSCode to work great! Your mileage may vary -- the recommendation here is really just, find an interface that works for you and your workflow to make this work easier and reduce the frictions involved.
+There are also similar alternatives that are designed to be a bit more teched-up with coding agents built in (e.g., Cursor), but I've found VSCode to work great! Your mileage may vary -- the recommendation here is really just, find an interface that works for you and your workflow to make this work easier and reduce the frictions involved.
 
 ---
 
diff --git a/user_reference/04_extending_daaf.md b/user_reference/04_extending_daaf.md
index 9051ed7..ed68840 100644
--- a/user_reference/04_extending_daaf.md
+++ b/user_reference/04_extending_daaf.md
@@ -62,7 +62,7 @@ You'll need:
 If your data source is available via a REST API rather than as a downloadable file, DAAF can handle the acquisition for you during Data Onboarding. You'll need:
 
 1. **API documentation** — a URL to the API docs, or a description of how the API works (endpoints, authentication method, response format). DAAF will research the API on your behalf, but having documentation to point to dramatically improves the quality of the resulting fetch scripts.
-2. **An API key** — most APIs require authentication. Set up your key as an environment variable inside the Docker container before starting (see [Step 8 in the Installation Guide](01_installation_and_quickstart.md#step-8-optional-set-up-data-source-api-keys) for the pattern). DAAF will ask you which environment variable name holds your key.
+2. **An API key** — most APIs require authentication. Add your key to the `environment_settings.txt` file in your `daaf-docker` folder on the host machine (see [API Keys in the Installation Guide](01_installation_and_quickstart.md#set-up-data-source-api-keys) for the pattern). DAAF will ask you which environment variable name holds your key.
 3. **A sense of what you want to download** — which endpoint, what filters (date range, geography, etc.), and roughly how much data to expect.
 
 DAAF will research the API, write a fetch script for your approval, download the data, and then proceed with the standard profiling workflow. The fetch script is saved as a reproducible artifact — you (or DAAF) can re-run it any time to get fresh data.
@@ -105,7 +105,9 @@ The fetch mechanics (Stage 5) are mostly handled by the query skill and mirror c
 
 ### Preparing Your Data
 
-Place your data file anywhere accessible inside `/daaf/` — the ingest process will copy it into the research project's `data/raw/` folder during setup. A common convention is to place files in `/daaf/data/` or alongside the research folder (e.g., `/daaf/data/county-elections/election_returns_2024.csv`). If you have documentation files (codebooks, data dictionaries, etc.), put those alongside the data file. See [**01. Installation and Quickstart**](01_installation_and_quickstart.md) for reminders on managing files within the Docker volume if needed.
+Place your data file anywhere accessible inside `/daaf/` — the ingest process will copy it into the research project's `data/raw/` folder during setup. A common convention is to place files in `/daaf/data/` or alongside the research folder (e.g., `/daaf/data/county-elections/election_returns_2024.csv`). If you have documentation files (codebooks, data dictionaries, etc.), put those alongside the data file.
+
+**Getting files into the Docker volume:** The easiest way is with the browser-based code editor — run `bash run_vscode.sh` (or `.\run_vscode.ps1` on Windows) from your `daaf-docker` folder, then drag and drop files from your computer into the file explorer sidebar. You can also use Docker Desktop's GUI (Containers → Files tab → right-click → Import). See [**01. Installation and Quickstart — Viewing and Editing Files**](01_installation_and_quickstart.md#viewing-and-editing-files) for more details.
 
 A few practical considerations:
 
@@ -277,7 +279,7 @@ What data sources does DAAF know about? Can you tell me about
 [your new data source]?
 ```
 
-If the skill is properly placed, DAAF should be able to describe the data source, list key variables, and mention important caveats. If it can't find the skill or gives a generic response, verify that the skill's YAML frontmatter has a clear `description` field and that `SKILL.md` is in `.claude/skills/{skill-name}/`.
+If the skill is properly placed, DAAF should be able to describe the data source, list key variables, and mention important caveats. If it can't find the skill or gives a generic response, verify that the skill's YAML frontmatter has a clear `description` field and that `SKILL.md` is in `.claude/skills/{skill-name}/`. Note: if the skill file exists and the frontmatter looks correct, this may also be a non-deterministic loading issue rather than a content problem -- LLMs don't always load what they're told to load. Try the query again in a fresh session before assuming your skill content is wrong.
 
 ### Fetch Test
 
@@ -372,16 +374,16 @@ The best way to add packages is to ask DAAF to edit the `Dockerfile` and then re
 
 #### The Container-Host Boundary (Read This First)
 
-When you initially installed DAAF, the `docker run ... busybox cp` command copied your entire host project folder *into* the Docker volume -- including the Dockerfile. From that moment on, **there are two copies of the Dockerfile and docker-compose.yml**, and they live in different places:
+When DAAF is installed, the Docker image is built from files on your host computer, but the full DAAF codebase (including a copy of the Dockerfile) lives inside the Docker volume. This means **there are two copies of the Dockerfile and docker-compose.yml**, and they live in different places:
 
 | Copy | Location | Who edits it | Who reads it |
 |------|----------|--------------|--------------|
-| **Volume copy** (inside the container) | `/daaf/Dockerfile` as seen from inside the running container | DAAF/Claude Code, while you're running a session | Nothing -- it's just a working copy that traveled along when you installed DAAF |
-| **Host copy** (on your computer) | Your DAAF project folder on your host (e.g., `daaf-main/Dockerfile`) | You, via a "copy back" command after DAAF finishes | `docker compose up -d --build`, when run from the host |
+| **Volume copy** (inside the container) | `/daaf/Dockerfile` as seen from inside the running container | DAAF/Claude Code, while you're running a session | Nothing -- it's just a working copy inside the container |
+| **Host copy** (on your computer) | Your `daaf-docker/` build directory on your host (wherever you ran the installer, or `daaf-main/Dockerfile` if you installed manually) | You, via a "copy back" command after DAAF finishes | `docker compose up -d --build`, when run from the host |
 
-The two files start out identical, but they can drift apart as soon as either side is modified. Critically, **`docker compose up -d --build` only ever reads the host copy** -- it has no knowledge of the volume copy at all. But when you ask DAAF to add a package to the Dockerfile, DAAF edits the **volume copy** (the only one Claude can see and edit from inside the container). 
+The two files start out identical, but they can drift apart as soon as either side is modified. Critically, **`docker compose up -d --build` only ever reads the host copy** -- it has no knowledge of the volume copy at all. But when you ask DAAF to add a package to the Dockerfile, DAAF edits the **volume copy** (the only one Claude can see and edit from inside the container).
 
-**The fix is simple but easy to forget:** after DAAF edits the in-container Dockerfile (or docker-compose.yml), you need to copy that updated file back to the host project folder *before* running the container rebuild. The step-by-step process below walks through this carefully, and you should follow it exactly the first time.
+**The fix is simple but easy to forget:** after DAAF edits the in-container Dockerfile (or docker-compose.yml), you need to copy that updated file back to the host build directory *before* running the container rebuild. The step-by-step process below walks through this carefully, and you should follow it exactly the first time.
 
 #### Step-by-Step Process
 
@@ -412,7 +414,7 @@ A few things to note about the Dockerfile syntax (DAAF will handle these for you
 - Versions are pinned with `==` (e.g., `networkx==3.4.2`) for reproducibility -- DAAF can look up the latest version on [PyPI](https://pypi.org/) for you, or use a version you specify
 - If you're unsure which version to pin, you can ask DAAF to use the latest compatible version, but pinning a specific version is strongly recommended
 
-**2. Exit the container and copy the updated Dockerfile back to the host.** This is the critical step that bridges the container-host boundary. After DAAF finishes editing, exit Claude Code and the container itself:
+**2. Exit the container and rebuild.** After DAAF finishes editing the Dockerfile, exit Claude Code and the container, then run the rebuild script:
 
 ```bash
 # Inside Claude Code
@@ -421,39 +423,40 @@ A few things to note about the Dockerfile syntax (DAAF will handle these for you
 # Now you're back in the container shell (prompt looks like appuser@xxxx:/daaf$)
 # Exit the container too
 exit
-```
 
-You should now be back in your terminal on your host computer. Make sure you're in your DAAF project folder (e.g., `daaf-main/`) -- if you're not sure, type `pwd` to check, and `cd` into the right folder if needed. Then run this command to copy the updated Dockerfile out of the running container and into the host folder, replacing the host's stale copy:
-
-```bash
-docker cp daaf-daaf-docker-1:/daaf/Dockerfile ./Dockerfile
+# From your host terminal, navigate to your daaf-docker folder and rebuild
+cd daaf-docker
+bash rebuild_daaf.sh         # macOS / Linux
+.\rebuild_daaf.ps1           # Windows
 ```
 
-**Alternative (Docker Desktop GUI):** If you'd rather not use the command line, you can do the same thing through Docker Desktop's interface:
-1. Open Docker Desktop
-2. Click **Containers** in the left toolbar → expand **`daaf`** → click on **`daaf-daaf-docker-1`**
-3. Click the **Files** tab to browse the container's filesystem
-4. Navigate to `/daaf/` and find `Dockerfile`
-5. Right-click `Dockerfile` → **Save** (or **Download**), and save it directly into your host DAAF project folder, **overwriting** the existing `Dockerfile` there
+The rebuild script handles the tricky part automatically: it copies the updated Dockerfile and docker-compose.yml from inside the container back to your host build directory (where `docker compose` reads them), then rebuilds the Docker image. Docker uses **layer caching**, so only the changed layers are rebuilt -- you'll see the new package being downloaded and installed in the build output.
 
-Either approach works -- use whichever feels more comfortable. If you want to confirm the copy worked before rebuilding, open the host `Dockerfile` in any text editor and look for your new package -- it should be there.
+**Why is this step needed?** The Dockerfile lives in two places -- inside the Docker volume (where DAAF just edited it) and in your `daaf-docker/` folder on your computer (where `docker compose` reads it for builds). The rebuild script bridges this gap so the two copies stay in sync.
 
-**3. Rebuild the container.** Now that the host Dockerfile is up to date, you can rebuild. From your DAAF project folder on your host computer, run:
+**3. Re-enter the container and verify.** After the rebuild completes, re-enter the container and confirm the package is available:
 
 ```bash
-docker compose up -d --build
+bash run_daaf.sh bash        # macOS / Linux
+.\run_daaf.ps1 bash          # Windows
+pip list | grep networkx
 ```
 
-Docker uses **layer caching**, which means it only re-runs the layers that changed. Watch the build output to confirm that the `RUN uv pip install --system` block containing your new package actually runs (you'll see the packages being downloaded and installed). If you don't see your package in the build output at all, something went wrong with the copy step in #2 -- check that the host Dockerfile actually contains your changes before debugging anything else.
+You should see your new package listed with the version you pinned. That's it -- your new package is now a permanent part of your DAAF environment, and it will survive future restarts and rebuilds (as long as you keep your host Dockerfile around, which you should be backing up periodically anyway).
+
+<details>
+<summary>Manual alternative (copy and rebuild by hand)</summary>
 
-**4. Re-enter the container and verify.** After the rebuild completes, re-enter the container and confirm the package is available:
+If you'd rather run the individual commands instead of using the rebuild script:
 
 ```bash
-docker compose exec daaf-docker bash
-pip list | grep networkx
+cd daaf-docker
+docker cp daaf-daaf-docker-1:/daaf/Dockerfile ./Dockerfile
+docker compose up -d --build
 ```
 
-You should see your new package listed with the version you pinned. That's it -- your new package is now a permanent part of your DAAF environment, and it will survive future restarts and rebuilds (as long as you keep your host Dockerfile around, which you should be backing up periodically anyway).
+The copy step must come **before** the rebuild. You can also copy via Docker Desktop's GUI: Containers → expand `daaf` → click `daaf-daaf-docker-1` → Files tab → navigate to `/daaf/Dockerfile` → right-click → Save, and overwrite the host copy.
+</details>
 
 ### Adding System-Level Dependencies
 
@@ -480,9 +483,9 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
 
 **2. Add the Python package** to the appropriate `RUN uv pip install --system` block (as described above).
 
-Both changes go in the same Dockerfile, so a single copy-back step covers them both -- you don't need to copy the Dockerfile out twice. After DAAF finishes both edits, follow Steps 2-4 from "Step-by-Step Process" above: exit the container, run `docker cp daaf-daaf-docker-1:/daaf/Dockerfile ./Dockerfile` from your host project folder to bring the updated Dockerfile out of the volume, then rebuild with `docker compose up -d --build`. **Don't skip the copy-back step** -- the same container-host boundary issue applies here, and rebuilding without copying the Dockerfile back will silently produce a build that has neither the new system library nor the new Python package.
+Both changes go in the same Dockerfile, so a single rebuild covers them both. After DAAF finishes both edits, follow Steps 2-3 from "Step-by-Step Process" above: exit the container, then run `bash rebuild_daaf.sh` (or `.\rebuild_daaf.ps1` on Windows) from your `daaf-docker` folder. The rebuild script copies the updated Dockerfile and docker-compose.yml from the container to the host and rebuilds the image in one step.
 
-If you're unsure whether a Python package needs a system library, try adding just the Python package first -- the build will fail with a clear error message if a system dependency is missing, and you can ask DAAF to add the missing library then (and remember to copy the Dockerfile back to the host again before the second rebuild).
+If you're unsure whether a Python package needs a system library, try adding just the Python package first -- the build will fail with a clear error message if a system dependency is missing, and you can ask DAAF to add the missing library then (and run `rebuild_daaf` again after the second edit).
 
 ### Runtime Installation for Quick Testing
 
@@ -520,11 +523,11 @@ Before adding a package, you might want to check if it's already available. You
 
 **"I need networkx for graph analysis"**
 
-Ask DAAF to add `networkx==3.4.2` (or your preferred version) to the core data science `RUN` block in the Dockerfile, then follow Steps 2-4 from "Step-by-Step Process" above (exit, `docker cp` the Dockerfile back to the host, rebuild). No system dependencies needed.
+Ask DAAF to add `networkx==3.4.2` (or your preferred version) to the core data science `RUN` block in the Dockerfile, then follow Steps 2-3 from "Step-by-Step Process" above (exit and run `rebuild_daaf`). No system dependencies needed.
 
 **"I need a specific version of a package that's already installed"**
 
-Ask DAAF to edit the version pin in the Dockerfile. For example, to change Polars from `1.38.1` to `1.39.0`, find `polars==1.38.1` and change it to `polars==1.39.0`. Then follow the same Steps 2-4 from "Step-by-Step Process" above (exit the container, `docker cp` the updated Dockerfile to the host, then `docker compose up -d --build`) -- the container-host boundary applies to version-pin edits exactly the same way it applies to new package additions. Be cautious with version changes -- other packages may depend on the currently pinned version, so test your analysis after upgrading. Ask DAAF/Claude Code to run a `uv pip compile` dry-run to test compatibility between all the package versions before committing to the rebuild.
+Ask DAAF to edit the version pin in the Dockerfile. For example, to change Polars from `1.38.1` to `1.39.0`, find `polars==1.38.1` and change it to `polars==1.39.0`. Then follow the same Steps 2-3 from "Step-by-Step Process" above (exit and run `rebuild_daaf`) -- the container-host boundary applies to version-pin edits exactly the same way it applies to new package additions. Be cautious with version changes -- other packages may depend on the currently pinned version, so test your analysis after upgrading. Ask DAAF/Claude Code to run a `uv pip compile` dry-run to test compatibility between all the package versions before committing to the rebuild.
 
 **"I need an R package or want to use R"**
 
@@ -532,7 +535,7 @@ DAAF is a Python-based environment and does not include R. However, DAAF include
 
 **"I need a package that requires compilation and it's failing"**
 
-Some packages need a C/C++ compiler or specific development headers. Ask DAAF to check the package's installation documentation for required system dependencies, add them to the `apt-get install` block in the Dockerfile, and (if not already present) add the Python package itself to the appropriate `RUN uv pip install --system` block. Then follow Steps 2-4 from "Step-by-Step Process" above to copy the updated Dockerfile back to the host and rebuild. Common examples include packages needing `build-essential`, `libhdf5-dev`, or database client libraries.
+Some packages need a C/C++ compiler or specific development headers. Ask DAAF to check the package's installation documentation for required system dependencies, add them to the `apt-get install` block in the Dockerfile, and (if not already present) add the Python package itself to the appropriate `RUN uv pip install --system` block. Then follow Steps 2-3 from "Step-by-Step Process" above (exit and run `rebuild_daaf`). Common examples include packages needing `build-essential`, `libhdf5-dev`, or database client libraries.
 
 **"Can I use `apt-get` or `sudo` inside the running container?"**
 
diff --git a/user_reference/07_faq_technical.md b/user_reference/07_faq_technical.md
index 94ac5d6..c066b6d 100644
--- a/user_reference/07_faq_technical.md
+++ b/user_reference/07_faq_technical.md
@@ -22,15 +22,7 @@ Operational questions with concrete answers. If you're stuck, troubleshooting, o
 
 ### Q: Can I run DAAF without Docker?
 
-Technically yes, but I really don't recommend it, and it's not something I will support. Part of my installation process is, explicitly, me paternalistically enforcing some best practices and guardrails for the many people using DAAF likely to be new to AI assistants.
-
-Docker does three important things for DAAF beyond just convenience:
-
-1. **Isolation and safety.** The container runs as a non-root user with all Linux capabilities dropped (`cap_drop: ALL`) and privilege escalation explicitly blocked (`no-new-privileges`). This means even if Claude Code tried to do something destructive, the operating system itself would prevent it. Running natively on your machine without these protections in place means Claude Code has whatever permissions *you* have -- which is probably a lot more than you'd want an AI assistant to have when they suffer from context rot and act extremely erratically.
-
-2. **Reproducibility.** The Dockerfile pins every dependency -- Python 3.12, specific versions of Polars, plotnine, statsmodels, and everything else. When I say "this works," I mean it works with *that* exact stack. It also abstracts away issues with OS management (e.g., Windows versus Linux), and other extremely annoying variables that can affect how well or predictably software runs. Running natively means you're on your own for dependency management, and a surprising number of things can go wrong when library versions don't match. Python management has historically been a nightmare, and I am thoroughly shocked at how much Docker smooths over, which is time worth its weight in gold in my view.
-
-3. **Clean slate recovery.** If something goes badly wrong inside the container, you can blow it away and rebuild from scratch in minutes with basically zero consequences to your actual machine. That's a really nice safety net when you're letting an AI write and execute code.
+Technically yes, but I really don't recommend it, and it's not something I will support. Docker provides security isolation (non-root, dropped capabilities), full reproducibility (pinned dependencies), and clean-slate recovery -- all critical when an AI agent is writing and executing code on your behalf. For the full rationale, see [**01. Installation -- Prerequisites: Docker Desktop**](01_installation_and_quickstart.md#3-docker-desktop).
 
 If you want to go this route: be my guest, but you'll need to figure it out on your own. I would firmly posit that anyone who's ready and qualified to do this independently **already** knows how to do it without my help.
 
@@ -38,13 +30,7 @@ If you want to go this route: be my guest, but you'll need to figure it out on y
 
 ### Q: Should I use an API key or a Max subscription?
 
-I strongly recommend the **Max subscription** ($100/mo or $200/mo depending on tier). Here's why:
-
-DAAF is extremely usage-intensive by design. It's doing a *lot* of work: deep-diving into data documentation, writing code, having another instance of Claude review that code line by line, writing plans, writing reports, and so on. All of that consumes tokens. With an API key, you pay per token, and a single full-pipeline analysis can easily burn through $50-100+ in API costs depending on the complexity. With a Max subscription, that same analysis is covered by your flat monthly rate.
-
-From my own testing, I estimate I'd pay roughly **10x more** going with API billing versus my Max subscription. The Max plan is Anthropic explicitly subsidizing heavy usage like this -- take advantage of it.
-
-The tradeoffs:
+I strongly recommend the **Max subscription** ($100/mo or $200/mo). DAAF is extremely usage-intensive by design, and from my own testing I estimate I'd pay roughly **10x more** going with API billing versus my Max subscription. A single full-pipeline analysis can easily cost $50-100+ via the API; the Max plan covers that at a flat monthly rate.
 
 | Factor | API Key | Max Subscription |
 |--------|---------|------------------|
@@ -54,6 +40,10 @@ The tradeoffs:
 | **Rate limiting** | Minimal | May hit rate limits during very heavy sessions |
 | **Best for** | Light/occasional use, or organizational API budgets | Regular DAAF usage (recommended) |
 
+**Third option: OpenRouter.** Pay-per-token access to Claude via [OpenRouter](https://openrouter.ai/) with no monthly commitment (5.5% fee on credit purchases). Good for testing DAAF before committing to a subscription. See [**01. Installation -- Configure authentication via environment_settings.txt**](01_installation_and_quickstart.md#configure-authentication-via-environment_settingstxt) for setup.
+
+For the full comparison of all authentication options, see [**01. Installation -- Anthropic Account & Authentication**](01_installation_and_quickstart.md#1-anthropic-account--authentication).
+
 One thing to note: the Max plan does have usage limits per time window. If you're running several DAAF analyses in parallel (which you absolutely can do!), you may occasionally hit a rate limit and need to wait a bit. The API key doesn't have that issue, but your wallet will feel it instead.
 
 ### Q: Which Claude model should I use?
@@ -74,9 +64,13 @@ You can also adjust the thinking level for Opus 4.6 by pressing the left and rig
 
 ### Q: Can I use DAAF with a different AI provider (OpenAI, Google, etc.)?
 
-Not out of the box, but it's more portable than you might think.
+Yes -- partially. There are two different things this question might mean, so let me address both.
+
+**Using different models through OpenRouter (supported):** [OpenRouter](https://openrouter.ai/) is a model gateway that lets you route Claude Code through a single API key with pay-per-token billing. It's already configured as an authentication option in DAAF's `environment_settings_example.txt` template (Option C). Through OpenRouter, you can access Anthropic's Claude models without a Max subscription -- and OpenRouter technically allows routing to non-Anthropic models as well. See [**01. Installation & Quick Start -- Configure authentication via environment_settings.txt**](01_installation_and_quickstart.md#configure-authentication-via-environment_settingstxt) for setup instructions (remember to run `/logout` first if you previously authenticated with Anthropic directly).
 
-DAAF is built on Claude Code, which is Anthropic's CLI agent tool. The vast majority of what DAAF actually *is* -- the agent protocols, skill documents, workflow definitions, validation checkpoints -- is just structured text in Markdown files. None of that is Anthropic-specific. What *is* specific to Claude Code are the hooks system (the safety guardrails that block dangerous commands, scan outputs for secrets, etc.) and some of the tool invocation patterns.
+**The practical reality for non-Anthropic models:** Claude Code is optimized for Anthropic models, and DAAF's complex multi-agent workflow (detailed protocols, nuanced judgment calls, multi-step tool chains) requires Opus-class reasoning to function reliably. OpenRouter's own documentation notes that Claude Code "is optimized for Anthropic models and may not work correctly with other providers." Some non-Claude models (e.g., GPT-4o) can handle basic operations, but they struggle with the tool-calling patterns and edit formatting that DAAF depends on heavily. Extended thinking -- which DAAF uses extensively -- works through OpenRouter when using Anthropic models, but does not work with non-Anthropic models at all. **Bottom line:** Use Anthropic's Opus models through OpenRouter for reliable DAAF results. Non-Anthropic models may technically load but will produce erratic, inconsistent output for DAAF's workflows.
+
+**Porting DAAF to a different CLI tool entirely:** This is also possible but requires more effort. DAAF is built on Claude Code, which is Anthropic's CLI agent tool. The vast majority of what DAAF actually *is* -- the agent protocols, skill documents, workflow definitions, validation checkpoints -- is just structured text in Markdown files. None of that is Anthropic-specific. What *is* specific to Claude Code are the hooks system (the safety guardrails that block dangerous commands, scan outputs for secrets, etc.) and some of the tool invocation patterns.
 
 If you wanted to port DAAF to another agent harness (Gemini CLI, Codex, OpenCode, etc.), here's what would transfer immediately:
 - All agent files (`.claude/agents/*.md`)
@@ -101,18 +95,63 @@ Your data does pass through Anthropic's API when Claude Code processes it -- tha
 
 3. **The container provides additional isolation.** Because DAAF runs inside Docker with dropped capabilities and no privilege escalation, the blast radius of any unexpected behavior is contained (i.e., files it can accidentally upload to the internet, or send via email, or etc. etc.).
 
-4. **DAAF enforces credential safety.** The framework actively prevents reading, writing, or committing files that look like credentials (`.env`, `*.pem`, `*.key`, etc.). It won't prevent everything, but it'll give you a good set of starting guardrails to help protect yourself.
+4. **DAAF enforces credential safety.** The framework actively prevents reading, writing, or committing files that look like credentials (`.env`, `*.pem`, `*.key`, `environment_settings*`, etc.). It won't prevent everything, but it'll give you a good set of starting guardrails to help protect yourself.
 
 **Bottom line:** If you're working with sensitive, proprietary, or regulated data, talk to your IT team and legal counsel before using DAAF or any AI tool with that data. DAAF provides strong *local* safety guarantees, but the data still transits through Anthropic's infrastructure for inference. Do not mess around here -- do your homework and be a good steward of your data.
 
 ---
 
+### Q: Why are the notebook and log viewer ports bound to localhost only?
+
+DAAF's `docker-compose.yml` binds ports 2718 (Marimo notebook), 2719 (session log viewer), and 2720 (code-server browser editor) to `127.0.0.1` — meaning only your local machine can access them. This is a deliberate security measure: Marimo notebooks and code-server are **interactive**, so an unauthenticated server exposed to your local network would allow anyone on that network to execute arbitrary code inside your container.
+
+With localhost binding, the ports are only reachable from your own machine, not from other devices on your WiFi or LAN. code-server additionally requires a password for defense-in-depth.
+
+**If you need to revert this** (e.g., WSL2 port forwarding issues, or you need to access from another device on a trusted network), edit the `ports:` section in `docker-compose.yml` to remove the `127.0.0.1:` prefix:
+
+```yaml
+# Localhost only (default, more secure):
+- "127.0.0.1:2718:2718"
+- "127.0.0.1:2719:2719"
+- "127.0.0.1:2720:2720"
+
+# All interfaces (less secure, use only if needed):
+- "2718:2718"
+- "2719:2719"
+- "2720:2720"
+```
+
+After changing, rebuild the container — see [Keeping DAAF Updated](01_installation_and_quickstart.md#keeping-daaf-updated) for the procedure.
+
+---
+
 ### Q: Is there a free way to use DAAF?
 
 Not in a practical sense for full-pipeline analyses, unfortunately. The free and Pro tiers of Claude simply don't provide enough usage for the volume of work DAAF demands. You might be able to do some lightweight Data Discovery Mode queries (asking what data is available, looking up variable definitions), but a full analysis pipeline will exhaust a lower-tier plan very quickly.
 
+**More flexible billing via OpenRouter:** While not free, [OpenRouter](https://openrouter.ai/) offers pay-per-token access to Claude's Opus models with no monthly subscription commitment. You only pay for what you use (with a 5.5% fee on credit purchases), which can be more accessible than a $100-200/mo Max subscription if you're doing occasional analyses rather than heavy daily use. See the [Installation Guide](01_installation_and_quickstart.md#configure-authentication-via-environment_settingstxt) for setup instructions.
+
 This is genuinely the biggest barrier to entry for DAAF, and I wish it were different. I hope that as model costs continue to decrease and open-source models become more capable, a more accessible option will emerge. If you have the capacity to test DAAF with open-source models or alternative providers, please reach out -- that's high on the list of things I'd love community help with.
 
+### Q: How much disk space does DAAF use?
+
+The Docker image is roughly **3-5 GB** after building. It includes a Debian Bookworm base image, Python 3.12, 57 pinned Python packages (data science, geospatial, econometrics, visualization, ML), geospatial system libraries (GDAL/GEOS/PROJ), and Claude Code. Docker also keeps build cache layers, so total Docker disk usage may be somewhat higher.
+
+Beyond the image, your Docker volume will grow as you create research projects. Each project accumulates scripts, parquet data files, session logs, and notebooks. A typical full-pipeline project might add 50-500 MB depending on how many datasets you fetch and how large they are.
+
+**To check your Docker disk usage:**
+- Open **Docker Desktop** and check the **Images** and **Volumes** sections for size information
+- Or from the terminal: `docker system df` shows a breakdown of images, containers, and volumes
+
+**To reclaim space:**
+- `docker system prune` removes stopped containers, unused networks, and dangling images
+- `docker builder prune` clears the build cache specifically
+- Be careful not to remove your `daaf_daaf-data` volume -- that's where your research files live
+
+### Q: Can I use DAAF offline?
+
+No. DAAF requires an active internet connection for two reasons: Claude Code communicates with Anthropic's API for all AI inference (nothing runs locally), and data fetching requires access to data portals like the Urban Institute Education Data Portal. If you lose connectivity mid-session, Claude Code will fail on the next API call, but your work-in-progress files and session state are preserved in the Docker volume -- just reconnect and resume.
+
 ### Q: How do I get help understanding or using DAAF itself?
 
 Just ask! DAAF has a dedicated **User Support** mode for questions about the framework itself and the tools it runs on (Docker, Git, Claude Code) -- what it is, how it works, which mode fits your needs, how to troubleshoot setup or tool issues, or how to get the most out of the system. Simply type a question like "What is DAAF?", "How do engagement modes work?", "Something's not working right," "How do I give Docker more memory?", or "Help me understand the pipeline" and DAAF will recognize it as a User Support request. It can also look up official documentation for Docker, Git, and Claude Code online when needed.
@@ -179,12 +218,31 @@ You don't need to do anything -- just start a new session and recovery happens s
 
 Session logs are invaluable when something goes wrong. The Markdown logs show you exactly what the assistant did, in order -- every tool call, every file read/write, every subagent invocation, and the full output at each step.
 
-1. Find the relevant session log in `.claude/logs/sessions/` (sorted by timestamp)
-2. Open the `.md` file to review what happened in a readable format
-3. Look for the point where things went wrong -- you'll see the exact tool calls and their results
-4. When filing an issue, include relevant excerpts from the log (redact any sensitive data first)
+DAAF includes an interactive **DAAF Log Explorer** that renders your session transcripts as a visual timeline in your web browser. It shows the orchestrator's actions as a horizontal timeline bar, with subagent dispatches waterfalling downward. Click any block to see exactly what files were read, written, or executed -- with plain-language descriptions and clickable file references.
+
+The quickest way to access this is from your host machine (no container shell needed):
+
+```bash
+cd daaf-docker
+bash view_logs.sh            # macOS / Linux
+.\view_logs.ps1              # Windows
+```
+
+This starts the container if needed, generates an activity manifest from all sessions, and starts the server. Open the URL it prints in the terminal into your browser.
+
+For more specific per-project session log viewing and diagnostics, you can also run it from a terminal inside the container:
+
+```bash
+bash /daaf/scripts/collect_session_logs.sh /daaf/research/YYYY-MM-DD_Your_Project
+bash /daaf/scripts/generate_log_viewer.sh /daaf/research/YYYY-MM-DD_Your_Project
+```
+
+**Note:** The server requires port 2719 to be mapped in your `docker-compose.yml`. If you set up DAAF after this feature was added, it's already there. If not, add `- "127.0.0.1:2719:2719"` under the `ports:` section and restart your container with `docker compose down && docker compose up -d`.
+
+Alternatively, DAAF also processes every individual log transcript into a more intuitive markdown file showing the flow of the conversation alongside tool calling segments.
+
+You can read these by finding the relevant `.md` session log in `.claude/logs/sessions/` (sorted by timestamp). The raw `.jsonl` file contains the complete raw transcript if deeper inspection is needed.
 
-The `.jsonl` file contains the complete raw transcript if deeper inspection is needed.
 
 ### Q: Are session logs shared or uploaded anywhere?
 
@@ -194,7 +252,7 @@ No. Session logs are gitignored and stay entirely on your local machine (specifi
 
 They serve very different purposes:
 
-**Session logs** are a complete, raw transcript of everything that happened in a Claude Code session. They're automatically generated, stored in `.claude/logs/`, and are primarily useful for debugging after the fact. Think of these as a security camera recording -- comprehensive but not curated.
+**Session logs** are a complete, raw transcript of everything that happened in a Claude Code session. They're automatically generated, stored in `.claude/logs/`, and are primarily useful for debugging after the fact. Think of these as a security camera recording -- comprehensive but not curated. You can browse them visually using the DAAF Log Explorer (`bash view_logs.sh` from your `daaf-docker` folder) rather than reading the raw files.
 
 **STATE.md** is a structured progress tracker that DAAF creates during full-pipeline analyses. It lives inside your project folder (`research/[project]/STATE.md`) and tracks what stage the analysis is at, which checkpoints have passed, what decisions were made, and what needs to happen next. It also accumulates the QA Findings Summary (aggregated quality review results across all stages), the Final Review Log (from the data-verifier's end-of-pipeline check), and any Runtime Risks encountered during execution. Its primary purpose is enabling **session recovery** -- if your session runs out of context (the model's working memory fills up), you can start a fresh session and STATE.md tells the new session exactly where to pick up. Think of this as a bookmark with detailed notes.
 
@@ -344,18 +402,16 @@ Election data (county presidential returns) is hosted on Harvard Dataverse, whic
 
 1. Create a free account at [dataverse.harvard.edu](https://dataverse.harvard.edu/)
 2. Log in, click your account name (top-right) → **API Token** → **Create Token**
-3. Copy the token, then run this **inside the Docker container, before launching Claude Code**:
+3. Add the key to the `environment_settings.txt` file in your `daaf-docker/` folder on the host:
    ```bash
-   export HARVARD_DATAVERSE_API_KEY="your_token_here"
+   HARVARD_DATAVERSE_API_KEY=your_token_here
    ```
-4. Then start Claude Code with `claude` as usual
+   If you don't have an `environment_settings.txt` file yet, copy the template first: `cp environment_settings_example.txt environment_settings.txt` (macOS/Linux) or `Copy-Item environment_settings_example.txt environment_settings.txt` (Windows).
+4. Recreate the container: `docker compose down` then `bash run_daaf.sh` (or `.\run_daaf.ps1`)
 
-To make it persist across sessions, add the export line to `~/.bashrc` inside the container:
-```bash
-echo 'export HARVARD_DATAVERSE_API_KEY="your_token_here"' >> ~/.bashrc
-```
+Alternatively, you can set it manually inside the container before launching Claude Code: `export HARVARD_DATAVERSE_API_KEY="your_token_here"`
 
-See also: [Installation Guide — Data Source API Keys](01_installation_and_quickstart.md#step-8-optional-set-up-data-source-api-keys)
+See also: [Installation Guide — Data Source API Keys](01_installation_and_quickstart.md#set-up-data-source-api-keys)
 
 ### Q: How current is the education data?
 
@@ -401,7 +457,9 @@ When more than 50% of your data is suppressed, any statistical analysis on the r
 
 ### Q: The notebook won't render in my browser
 
-If you've run the `marimo run` command but can't see anything at `http://localhost:2718`, check these things in order:
+The easiest way to view notebooks is with the convenience script — run `bash view_notebooks.sh` (or `.\view_notebooks.ps1` on Windows) from your `daaf-docker` folder. This handles container startup, port binding, and flag configuration automatically, and includes built-in port conflict detection.
+
+If you're using the manual `marimo run` command and can't see anything at `http://localhost:2718`, check these things in order:
 
 1. **Is the container running?** Check Docker Desktop's Containers panel. The `daaf` container should show as running.
 
@@ -410,9 +468,9 @@ If you've run the `marimo run` command but can't see anything at `http://localho
    marimo run 'research/[your-project]/[notebook-name].py' --host 0.0.0.0 --port 2718 --headless
    ```
 
-3. **Is the port mapped correctly?** Check your `docker-compose.yml` -- the line `"2718:2718"` under `ports:` maps the container's port to your host machine. If you changed this, use the host-side port in your browser.
+3. **Is the port mapped correctly?** Check your `docker-compose.yml` -- the line `"127.0.0.1:2718:2718"` under `ports:` maps the container's port to your host machine. If you changed this, use the host-side port in your browser.
 
-4. **Is something else using port 2718?** See the port conflict question above.
+4. **Is something else using port 2718?** See the port conflict question above. (The `view_notebooks` convenience script detects this automatically.)
 
 5. **Try a different browser or incognito/private window.** Occasionally, browser extensions or cached state can interfere.
 
@@ -455,6 +513,20 @@ DAAF has several mechanisms to handle this:
 
 If you notice Claude asking questions it already asked, or making decisions that contradict earlier ones, the best course of action is to prompt it to check its STATE.md and Plan.md, or to restart the session with `/clear` and the restart prompt.
 
+### Q: Claude seems to be making things up about data variables or endpoints
+
+This is one of the most common -- and most important -- symptoms to recognize. If DAAF confidently references variable names, API endpoints, coded value schemes, or data structures that don't match reality, the most likely cause is a **skill or reference file that didn't load properly**.
+
+DAAF has extensive curated knowledge about its supported data sources, stored in skill files. When these skills load correctly, agents have access to exact variable names, precise endpoint paths, correct coded values, and known caveats. When a skill *doesn't* load -- which can happen due to the non-deterministic nature of LLMs -- the agent falls back on its general training data and fills in the gaps with plausible-sounding but potentially incorrect details.
+
+**What to do:**
+1. Make sure **Verbose output** is set to **True** in `/config`. This is your primary tool for monitoring how agents are deciding to load or not to load certain reference files.
+2. Ask DAAF to verify: "Can you double-check that variable name against the actual skill documentation?" or "Did the agent load the CCD data source skill before writing that script?"
+3. If the issue persists, try restarting the session with `/clear` -- a fresh context often resolves loading issues. For Full Pipeline mode, DAAF's session recovery system will pick up where you left off.
+4. Report persistent loading failures by [opening an issue](https://github.com/DAAF-Contribution-Community/daaf/issues) -- patterns of failure help us improve DAAF's loading reliability.
+
+For more detail, see [Best Practices — Monitoring DAAF's Internal Reference Loading](03_best_practices.md#monitoring-daafs-internal-reference-loading).
+
 ---
 
 ## Recommended Next Steps