docs: add complete System Analysis Book (companion to Founder Playbook)

23-section end-to-end engineering reference covering recent dependency-fix change log, DigitalOcean primary + OpenRouter fallback provider chain, container/Dockerfile mechanics, runtime topology, every Python module, the Architect tier-routing/sandbox/skills/night-mode subsystem, the Mythos multi-agent + RL + 17 native MCP servers subsystem, every entry in the 34-server MCP suite, the test suite, on-disk data + SQLite schemas, complete env var reference, failure modes + recovery, security model + trust boundaries, and HF Space -> paid server migration playbook. Founder Playbook remains the canonical investor narrative; this book is the engineering source of truth.

SYSTEM_ANALYSIS_BOOK.md

@@ -0,0 +1,1533 @@
+# Rhodawk AI — System Analysis Book
+### Complete End-to-End Mechanics, Logic, and Operational Reference
+#### Companion to `FOUNDER_PLAYBOOK.md` — written from the live source tree
+
+---
+
+> **Purpose of this document.**
+> The existing `FOUNDER_PLAYBOOK.md` is the canonical investor-facing narrative
+> of what Rhodawk does and why it matters. It remains the source of truth for
+> mission, business model, and high-level architecture and is **not** modified.
+>
+> This book sits beside it and answers a different question: **how does every
+> piece actually work, end-to-end, in the code as it stands today?** It is
+> written for engineers who must run, debug, extend, or migrate the system,
+> and it intentionally crosses every layer — from Dockerfile, through provider
+> routing, through each Python module, into the MCP servers, into the test
+> suite, and out to the data on disk.
+>
+> Where the playbook says *"the system has a 5-layer safety pipeline,"* this
+> book says *"`process_failing_test` in `app.py` calls `sast_gate.run_sast`,
+> which forks bandit and semgrep, parses their JSON, returns a `SastVerdict`
+> dataclass, and on `BLOCK` raises an early-exit that `verification_loop`
+> converts into a retry prompt with the SAST critique inlined."*
+>
+> Read the playbook for **what and why**. Read this book for **how**.
+
+---
+
+## Table of Contents
+
+1. [Recent Change Log — The Last Mile of Fixes](#1-recent-change-log)
+2. [Provider Routing — DO Primary, OpenRouter Fallback](#2-provider-routing)
+3. [Top-Level Topology](#3-top-level-topology)
+4. [Container & Build — Dockerfile and Requirements](#4-container--build)
+5. [Process Map at Runtime](#5-process-map-at-runtime)
+6. [Master Orchestrator — `app.py`](#6-master-orchestrator)
+7. [Hermes Six-Phase Pipeline — `hermes_orchestrator.py`](#7-hermes-pipeline)
+8. [Safety Gate Modules](#8-safety-gates)
+9. [Memory, Learning, and Data Flywheel](#9-memory-learning)
+10. [Autonomous Operation — Harvester, Worker Pool, Job Queue](#10-autonomous-operation)
+11. [GitHub Surface — `github_app.py`, `webhook_server.py`, `commit_watcher.py`](#11-github-surface)
+12. [Red Team & Offense Modules](#12-red-team--offense)
+13. [Notification, Audit, Disclosure, Bounty](#13-notification-audit)
+14. [Architect Subsystem — Tier Routing, Sandbox, Skills, Night Mode](#14-architect)
+15. [Mythos Subsystem — Multi-Agent + RL + 17 MCP Servers](#15-mythos)
+16. [MCP Suite — Every Server, Every Domain](#16-mcp-suite)
+17. [Test Suite — What Each Test Asserts](#17-test-suite)
+18. [Data on Disk — Files, SQLite Schemas, Audit Chain](#18-data-on-disk)
+19. [Complete Environment Variable Reference (Updated)](#19-env-vars)
+20. [Failure Modes and Recovery Procedures](#20-failure-modes)
+21. [Security Model — Trust Boundaries and Threat Mitigation](#21-security-model)
+22. [Migration Playbook — HF Space → Paid Server](#22-migration)
+23. [Glossary of Internal Names](#23-glossary)
+
+---
+
+## 1. Recent Change Log — The Last Mile of Fixes
+<a id="1-recent-change-log"></a>
+
+The Space went through five iterative dependency-and-build fixes after the
+original `FOUNDER_PLAYBOOK.md` was written at commit `8a23fcf`. These changes
+do not appear in the playbook because they post-date it. They are critical
+to understand because they affect both runtime behaviour (provider selection)
+and build behaviour (how the container is assembled).
+
+| Order | Commit  | What changed | Why |
+|---|---|---|---|
+| 1 | `504dde2` | Added DigitalOcean Serverless Inference as primary, OpenRouter as fallback, in `app.py::run_aider` and `hermes_orchestrator.py::_hermes_llm_call`. Added env vars `DO_INFERENCE_API_KEY`, `DO_INFERENCE_BASE_URL`, `DO_INFERENCE_MODEL`, `HERMES_DO_MODEL`. | Move the hot path off the OpenRouter free tier (rate-limit-prone) onto DigitalOcean's paid llama3.3-70b-instruct. Keep OpenRouter as resilience. |
+| 2 | `1e909b0` | Bumped `aider-chat` to `0.87.0` to fix the `module 'litellm' has no attribute 'APIConnectionError'` crash. | The aider 0.86.x series hard-pinned `litellm==1.75.0`, whose top-level module was missing public symbols at runtime. **This bump failed because aider 0.87.0 was never published to PyPI.** |
+| 3 | `da5ce03` | Reverted to `aider-chat==0.86.2` and added a Dockerfile post-step: `pip install --no-cache-dir --upgrade --no-deps "litellm==1.78.5"`. | aider only consumes litellm via `getattr` and a small public surface; replacing the broken pin with a known-good newer release restores `APIConnectionError`, `_logging`, `encode`, `token_counter`. |
+| 4 | `ad06d84` | Added `gitpython==3.1.46` to `requirements.txt`. | aider 0.86.2 hard-pins gitpython; pip's resolver was bouncing between our floor (`>=3.1.40`) and aider's pin. Pinning explicitly removes the resolver thrash. |
+| 5 | `a913714` | Switched the Space SDK from `gradio` to `docker` in `README.md` front-matter and bumped `gradio>=5.49.0,<6` in `requirements.txt`. | HF was auto-injecting `gradio[oauth,mcp]==5.29.0` because the Space was registered as `sdk: gradio`. That injection conflicted with aider's `pillow==12.1.1` pin. `sdk: docker` tells HF to use the existing Dockerfile verbatim, with no auto-injection. |
+| 6 | `dd4ccce` | Removed `aider-chat` from `requirements.txt` entirely. The Dockerfile now installs it with `--no-deps` plus a curated runtime-deps list. | Even with `sdk: docker`, aider's `pillow==12.1.1` pin still conflicted with gradio's `pillow<12` constraint at the resolver level. `--no-deps` lets gradio's pillow 11 win, and the curated dep list provides everything aider actually imports at runtime. |
+
+**Net effect today.** The Space SDK is `docker`. The build runs the
+Dockerfile end-to-end. `requirements.txt` does **not** mention `aider-chat`.
+The Dockerfile installs requirements normally, then layers in
+(a) `aider-chat==0.86.2 --no-deps`, (b) `litellm==1.78.5 --no-deps --upgrade`,
+(c) a curated set of aider's actual runtime imports (configargparse,
+jsonschema, rich, prompt_toolkit, pyyaml, pathspec, diskcache, networkx,
+scipy, beautifulsoup4, pypandoc, flake8, importlib_resources, pyperclip,
+pexpect, json5, psutil, watchfiles, socksio, mixpanel, posthog, tree-sitter,
+grep_ast, oslex, tokenizers, google-generativeai, openai, diff-match-patch,
+soundfile, sounddevice).
+
+**Provider behaviour today.** When `DO_INFERENCE_API_KEY` is present the hot
+path uses DigitalOcean Serverless Inference at
+`https://inference.do-ai.run/v1` with model `llama3.3-70b-instruct`.
+OpenRouter is the configured fallback for any non-zero exit, 429, or 5xx.
+When DO is absent the system silently runs OpenRouter-only.
+
+---
+
+## 2. Provider Routing — DigitalOcean Primary, OpenRouter Fallback
+<a id="2-provider-routing"></a>
+
+Two independent code paths need an LLM: **aider** (the patch generator) and
+**Hermes** (the multi-phase research orchestrator + adversarial reviewer).
+Both have been wired to the same provider chain.
+
+### 2.1 Aider path — `app.py::run_aider`
+
+```
+caller passes model=None
+  │
+  ├─► DEFAULT_MODEL  (constructed at import time)
+  │     ├── DO_INFERENCE_API_KEY set?  → "openai/llama3.3-70b-instruct"
+  │     └── otherwise                  → "openrouter/qwen/qwen-2.5-coder-32b-instruct:free"
+  │
+  ├─► FALLBACK_MODELS list = ["openrouter/qwen/qwen-2.5-coder-32b-instruct:free"]
+  │
+  └─► provider chain executes [primary, *fallbacks]:
+        for each model m:
+          if m starts with "openai/" and DO_INFERENCE_API_KEY:
+              env OPENAI_API_KEY      = DO_INFERENCE_API_KEY
+              env OPENAI_API_BASE     = https://inference.do-ai.run/v1
+              env OPENAI_BASE_URL     = https://inference.do-ai.run/v1
+              args += --openai-api-base, --openai-api-key
+              run aider; if exit==0 → return
+          elif m starts with "openrouter/" and OPENROUTER_API_KEY:
+              env OPENROUTER_API_KEY  = OPENROUTER_API_KEY
+              run aider; if exit==0 → return
+          else: skip
+        if all skipped → "No inference provider configured" message
+        if all failed  → return last error with provider chain printed
+```
+
+The `openai/<model>` prefix is litellm's convention for "treat this as an
+OpenAI-API-compatible endpoint." DigitalOcean's Serverless Inference exposes
+the OpenAI Chat Completions schema verbatim, so litellm + aider need no
+DO-specific code path — only env vars and a base URL override.
+
+### 2.2 Hermes path — `hermes_orchestrator.py::_hermes_llm_call`
+
+```
+build provider list:
+  if DO_INFERENCE_API_KEY:
+      providers.append( ("DigitalOcean", DO_INFERENCE_BASE, DO_KEY, HERMES_DO_MODEL, {}) )
+  if OPENROUTER_API_KEY:
+      providers.append( ("OpenRouter", OPENROUTER_BASE, OR_KEY, HERMES_OR_MODEL, {HTTP-Referer: ...}) )
+
+for (name, base, key, model, extra_headers) in providers:
+    POST {base}/chat/completions  with Bearer key, body {model, messages, ...}
+    on HTTP 429:
+        sleep exponential(attempt) and retry up to N times
+    on other 5xx or network error:
+        record reason, continue to next provider
+    on 200:
+        return {"content": choice.message.content, "provider": name, "model": model}
+
+if all providers exhausted:
+    return {"error": "all providers failed", "details": [...]}
+```
+
+This is implemented in the helpers `_post_chat_completion` (raw HTTP +
+retry), `_strip_provider_prefix` (litellm-style prefix removal so the
+DigitalOcean endpoint sees a clean model name), and `_hermes_llm_call`
+(orchestrates the chain). The same chain is used by adversarial reviewer
+calls because they delegate through `_hermes_llm_call`.
+
+### 2.3 Why DO first
+
+DigitalOcean's Serverless Inference is paid, predictable, and sized for the
+hot path. OpenRouter's free tier exists, but rate limits and 429s during
+adversarial bursts (3 concurrent reviewer models) make it unreliable as a
+primary. Keeping OpenRouter as a fallback preserves resilience without
+making the burst case the steady state.
+
+### 2.4 Required env vars
+
+| Var | Purpose | Default |
+|---|---|---|
+| `DO_INFERENCE_API_KEY` | DigitalOcean Serverless Inference key | none — if unset, DO path is skipped |
+| `DO_INFERENCE_BASE_URL` | Endpoint base | `https://inference.do-ai.run/v1` |
+| `DO_INFERENCE_MODEL` | Aider's primary model name on DO | `llama3.3-70b-instruct` |
+| `HERMES_DO_MODEL` | Hermes' primary model name on DO (may differ) | falls back to `DO_INFERENCE_MODEL` |
+| `OPENROUTER_API_KEY` | OpenRouter key for fallback + adversarial models | none — if unset, OR path is skipped |
+| `HERMES_OR_MODEL` | Hermes' OpenRouter fallback model | `qwen/qwen-2.5-coder-32b-instruct:free` |
+
+If neither DO nor OpenRouter is configured the system logs a single explicit
+error per audit. There is no silent degradation — by design.
+
+---
+
+## 3. Top-Level Topology
+<a id="3-top-level-topology"></a>
+
+The Space is a single Docker container that runs:
+
+```
+┌────────────────────────────────────────────────────────────────────────┐
+│ Container (port 7860 exposed, 7861 + 7862 internal)                    │
+│                                                                         │
+│  ┌──────────────────────┐    ┌──────────────────────┐                  │
+│  │ Gradio dashboard     │    │ Webhook server       │                  │
+│  │ app.py:demo          │    │ webhook_server.py    │                  │
+│  │ port 7860            │    │ port 7861            │                  │
+│  │ 10 tabs + chat inbox │    │ /webhook/github      │                  │
+│  └──────────┬───────────┘    └──────────┬───────────┘                  │
+│             │                            │                              │
+│             └─────────┬──────────────────┘                              │
+│                       ▼                                                  │
+│           ┌────────────────────────┐                                    │
+│           │ enterprise_audit_loop  │  ← background threads dispatched   │
+│           │ (app.py)               │     for each repo audit            │
+│           └─────────┬──────────────┘                                    │
+│                     │                                                    │
+│                     ▼                                                    │
+│           ┌────────────────────────┐                                    │
+│           │ Worker Pool            │  ← ThreadPoolExecutor, optionally  │
+│           │ worker_pool.py         │    process-isolated per job        │
+│           └─────────┬──────────────┘                                    │
+│                     │                                                    │
+│                     ▼                                                    │
+│           process_failing_test() … 15-step healing loop                 │
+│                                                                          │
+│  Background daemons (started conditionally):                             │
+│  • repo_harvester.py  (autonomous target selection, every 6h)           │
+│  • commit_watcher.py  (silent-patch detection)                          │
+│  • lora_scheduler.py  (training-data export)                            │
+│  • red_team_fuzzer.py (when all tests are green)                        │
+│  • mythos.api.fastapi_server (optional, port 7863)                      │
+│  • public_leaderboard.py (optional, port 7862)                          │
+│                                                                          │
+│  Persistent storage (mounted at /data):                                  │
+│  • job_queue.sqlite                                                      │
+│  • training_store.sqlite                                                 │
+│  • embedding_index.sqlite (or Qdrant remote)                             │
+│  • audit_trail.jsonl                                                     │
+│  • harvester_feed.json                                                   │
+│  • lora_exports/*.jsonl                                                  │
+│  • disclosure_vault/                                                     │
+│  • repo/  (cloned target repositories, ephemeral)                        │
+│                                                                          │
+│  External calls:                                                         │
+│  • GitHub API (clone, PR, fork, check_run, merge)                       │
+│  • DigitalOcean Inference (primary)                                      │
+│  • OpenRouter (fallback + adversarial models)                            │
+│  • OpenRouter for adversarial trio (Qwen/Gemma/Mistral)                 │
+│  • Telegram & Slack (notifications)                                      │
+│  • HackerOne / Bugcrowd (bounty submissions, optional)                  │
+│  • NVD / OSV / Snyk (CVE intelligence)                                   │
+│  • Shodan, Wayback, crt.sh (recon, optional)                            │
+└────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 4. Container & Build — Dockerfile and Requirements
+<a id="4-container--build"></a>
+
+### 4.1 `README.md` front-matter (the HF Space manifest)
+
+```yaml
+title: Rhodawk AI DevSecOps Engine
+sdk: docker
+app_port: 7860
+license: apache-2.0
+```
+
+`sdk: docker` is the critical line. With `sdk: gradio`, HF Spaces injects
+`gradio[oauth,mcp]==<sdk_version>` plus `uvicorn`, `websockets`, `spaces`,
+and `mcp` into the build's pip command — overriding our explicit pins and
+breaking the resolver. With `sdk: docker`, HF runs the Dockerfile verbatim
+and exposes only `app_port` to the public preview iframe.
+
+### 4.2 `Dockerfile` (logical structure)
+
+```dockerfile
+FROM python:3.12-slim AS base
+# system deps for: git (clone), build-essential (some wheels),
+# libpq-dev (psycopg2), libssl/libffi (cryptography), curl, jq, nodejs (MCP servers)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        git build-essential libpq-dev libssl-dev libffi-dev curl jq \
+        nodejs npm && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY requirements.txt /app/requirements.txt
+
+# Stage A: install everything pip can solve cleanly
+RUN pip install --no-cache-dir -r requirements.txt mcp-server-fetch && \
+    # Stage B: install aider WITHOUT its strict pins (pillow==12.1.1, litellm==1.75.0)
+    pip install --no-cache-dir --no-deps "aider-chat==0.86.2" && \
+    # Stage C: replace aider's broken litellm pin with a working release
+    pip install --no-cache-dir --upgrade --no-deps "litellm==1.78.5" && \
+    # Stage D: provide aider's actual runtime imports (subset of its setup.py)
+    pip install --no-cache-dir \
+        configargparse jsonschema rich prompt_toolkit pyyaml \
+        packaging pathspec diskcache networkx scipy \
+        beautifulsoup4 pypandoc flake8 importlib_resources \
+        pyperclip pexpect json5 psutil watchfiles socksio \
+        mixpanel posthog tree-sitter grep_ast oslex \
+        tokenizers google-generativeai openai diff-match-patch \
+        soundfile sounddevice
+
+COPY . /app
+EXPOSE 7860 7861
+CMD ["python", "app.py"]
+```
+
+**Why this layered install pattern works.** The pip resolver cannot satisfy
+`pillow<12` (gradio) and `pillow==12.1.1` (aider) simultaneously. By
+installing aider with `--no-deps` we let gradio's pillow 11 win. Aider only
+imports a small fraction of its declared deps at runtime, and those that
+matter are installed explicitly in Stage D. The litellm replacement is
+necessary because the version aider pins (1.75.0) ships a broken module
+surface — `litellm.APIConnectionError`, `litellm._logging`,
+`litellm.encode`, and `litellm.token_counter` are all referenced by aider
+but not exported by 1.75.0. 1.78.5 restores them.
+
+### 4.3 `requirements.txt` (resolved set)
+
+The file declares: `requests`, `pytest`, `uv>=0.7.0`, `gitpython==3.1.46`,
+`gradio>=5.49.0,<6`, `jinja2==3.1.6`, `ruff`, `tenacity`, `bandit[toml]`,
+`pip-audit`, `radon`, `hypothesis[cli]>=6.100.0`, `semgrep>=1.45.0`,
+`sentence-transformers>=2.7.0`, `sqlite-vec>=0.1.1`, `pygithub>=2.3.0`,
+`PyJWT>=2.8.0`, `datasets>=2.19.0`, `numpy>=1.26.0`, `psycopg2-binary>=2.9.9`,
+`rapidfuzz>=3.0.0`, `z3-solver>=4.12.0`, `qdrant-client>=1.9.0`,
+`transformers>=4.40.0`, `torch>=2.2.0`, `starlette`, plus optional FastAPI
+deps used by the Mythos API server.
+
+`aider-chat` is intentionally absent — see Stage B above.
+
+---
+
+## 5. Process Map at Runtime
+<a id="5-process-map-at-runtime"></a>
+
+| Process / Thread | Started by | Lifetime | Listens on | Purpose |
+|---|---|---|---|---|
+| Main Python process | `python app.py` | container lifetime | — | imports modules, starts threads, hosts Gradio |
+| Gradio Uvicorn worker | Gradio's `demo.launch()` | container lifetime | 7860 | serves the dashboard UI |
+| Webhook Uvicorn worker | `webhook_server.start()` thread | container lifetime | 7861 | receives GitHub & CI webhooks |
+| Audit threads | `submit_repo_audit()` per request | per audit | — | runs `enterprise_audit_loop` for one repo |
+| Worker pool threads | `worker_pool.run()` inside an audit | per audit | — | parallel test repair |
+| Worker subprocesses | optional, when `RHODAWK_PROCESS_ISOLATE=true` | per job | — | per-job blast radius isolation |
+| Aider subprocess | `subprocess.Popen` per fix attempt | per attempt | — | LLM patch generation |
+| MCP server processes | `npx`/`uvx` spawned by aider | per attempt | stdio | tools (fetch, github, filesystem, etc.) |
+| Adversarial review threads | `concurrent.futures` in `adversarial_reviewer` | per gate | — | 3-model parallel review |
+| Harvester daemon | `repo_harvester.start_daemon()` if enabled | container lifetime | — | autonomous target search |
+| Commit watcher | `commit_watcher.start_daemon()` if enabled | container lifetime | — | silent-patch correlation |
+| LoRA scheduler | `lora_scheduler.start_daemon()` if enabled | container lifetime | — | training data export trigger |
+| Mythos FastAPI | optional | container lifetime | 7863 | external programmatic API |
+| Leaderboard | optional | container lifetime | 7862 | public stats Gradio |
+
+All daemons are gated by their respective `RHODAWK_*_ENABLED` env vars and
+are off by default to keep the cold-start container minimal.
+
+---
+
+## 6. Master Orchestrator — `app.py`
+<a id="6-master-orchestrator"></a>
+
+`app.py` is 2,704 lines. It is the wiring file. Conceptually it has six
+sections.
+
+### 6.1 Module imports & global config
+Lines ~1–200. Imports every other module in the project. Reads
+~50 environment variables into module-level constants
+(`DEFAULT_MODEL`, `MAX_RETRIES`, `WORKERS`, `OPENROUTER_API_KEY`,
+`DO_INFERENCE_API_KEY`, `DO_INFERENCE_BASE_URL`, `DO_INFERENCE_MODEL`,
+`FALLBACK_MODELS`, `RHODAWK_TENANT_ID`, audit/disclosure/training paths,
+adversarial config, conviction thresholds, harvester config, etc.).
+
+### 6.2 MCP runtime config writer
+Lines ~200–470. Reads `mcp_config.json` (the template), substitutes
+`__INJECTED_BY_APP_AT_RUNTIME__` placeholders with real values from env,
+and writes the materialized config to `/tmp/mcp_runtime.json`. Aider is
+launched with `--mcp-config /tmp/mcp_runtime.json` so that all MCP tools
+(fetch-docs, github-manager, filesystem-research, semgrep-sast, …) are
+available during patch generation.
+
+### 6.3 `run_aider(prompt, repo_dir, model=None)` — provider chain
+Lines ~600–700. The function described in §2.1. Chooses the provider list
+based on which API keys are set, runs `aider` as a subprocess with the
+right env and CLI flags, captures stdout/stderr, parses the diff, and
+returns `(stdout, stderr, exit_code, model_used)`. On non-zero exit it
+moves to the next provider.
+
+### 6.4 `process_failing_test(...)` — the 15-step healing loop
+The single most important function in the project.
+
+```
+1.  Memory retrieval — embedding_memory.retrieve_similar_fixes_v2(failure_text)
+2.  Build prompt    — verification_loop.build_initial_prompt(test_path, failure, similar)
+3.  Aider call      — run_aider(prompt, repo_dir)              (provider chain)
+4.  Re-run test     — runtime.run_tests(test_path)
+5.  If still FAIL   — append failure delta, build_retry_prompt, GOTO 3 (up to MAX_RETRIES)
+6.  SAST gate       — sast_gate.run_sast(repo_dir, diff)
+7.  If BLOCK        — append SAST critique, GOTO 3
+8.  Supply chain    — supply_chain.run_supply_chain(diff, language)
+9.  If BLOCK        — append supply-chain critique, GOTO 3
+10. Z3 verify       — formal_verifier.verify(diff)             (if enabled)
+11. If UNSAFE       — append Z3 critique, GOTO 3
+12. Adversarial     — adversarial_reviewer.review_concurrent(diff, failure, repo)
+13. If REJECT       — append adversarial critique, GOTO 3 (with extended budget)
+14. Persist         — training_store.record_attempt(...)
+15. Return verdict  — VerificationResult(success, attempts, verdicts...)
+```
+
+The retry budget is normally `MAX_RETRIES` (default 5) but is multiplied by
+`ADVERSARIAL_REJECTION_MULTIPLIER` when the retry was triggered by an
+adversarial reject — to give the model more chances when the gate is the
+strict adversarial trio rather than a hard test failure.
+
+### 6.5 `process_audit_test(...)` — wraps healing with PR + conviction
+Calls `process_failing_test`, then on success:
+- `github_app.open_pr_for_repo(repo, branch, title, body)` → URL
+- `conviction_engine.evaluate(verification_result, adversarial_result, memory_match)` → `Conviction`
+- If `Conviction.met` and `RHODAWK_AUTO_MERGE=true`: `github_app.merge_pr(url)`
+- `audit_logger.append({event: PR_OPENED, ...})`
+- `notifier.notify_pr_opened(repo, url)`
+
+### 6.6 `enterprise_audit_loop(repo)` — the per-audit driver
+- Clones the repo into `/data/repo/<sanitized-owner>__<repo>`
+- `RuntimeFactory.for_repo(repo_dir)` returns the right `LanguageRuntime`
+- `runtime.setup_env()` (creates venv, installs deps)
+- `runtime.discover_tests()` returns a list of test file paths
+- Runs each test once to find the failing set
+- Submits each failing test to the worker pool, which calls `process_audit_test`
+- On completion: `red_team_fuzzer.start(repo_dir)` if all tests are now green
+- Logs a final `AUDIT_COMPLETE` event
+
+### 6.7 Gradio UI
+The `demo` block defines 10 tabs:
+1. **Chat Inbox** — submit `owner/repo` to start an audit
+2. **Live Agent Log** — real-time tail of the audit log with auto-refresh (3 s)
+3. **Audit Trail** — paginated view of `audit_trail.jsonl` with filters
+4. **Memory Browser** — search the embedding memory by failure text
+5. **Training Store** — stats and JSONL export trigger
+6. **Harvester** — refresh feed, view ranked candidates, dispatch manually
+7. **Findings** — vulnerability findings from Hermes / red team
+8. **Hermes Sessions** — list of research sessions with phases & VES scores
+9. **System Status** — env-var presence, daemon status, queue depth
+10. **Settings** — read-only display of effective configuration
+
+The Live Agent Log uses a `gr.Timer` that fires every 3 seconds to repaint
+the latest 200 lines of the in-memory log buffer.
+
+---
+
+## 7. Hermes Six-Phase Pipeline — `hermes_orchestrator.py`
+<a id="7-hermes-pipeline"></a>
+
+The Hermes orchestrator is a research-and-disclosure pipeline parallel to
+the test-healing loop. It runs against a target codebase or live host and
+produces structured `VulnerabilityFinding` records.
+
+### 7.1 Phases
+
+| # | Enum value | Module(s) called | Output |
+|---|---|---|---|
+| 1 | `RECON` | `repo_harvester`, `mythos.mcp.reconnaissance_mcp`, `subdomain_enum_mcp`, `httpx_probe_mcp`, `wayback_mcp`, `shodan_mcp` | target inventory + tech fingerprint |
+| 2 | `STATIC` | `taint_analyzer`, `semantic_extractor`, `mythos.static.{treesitter_cpg, joern_bridge, codeql_bridge, semgrep_bridge}` | candidate sinks + CWE hits |
+| 3 | `DYNAMIC` | `fuzzing_engine`, `harness_factory`, `mythos.dynamic.{aflpp_runner, klee_runner, qemu_harness, frida_instr, gdb_automation}` | crashes, traces, coverage |
+| 4 | `EXPLOIT` | `exploit_primitives`, `mythos.exploit.{pwntools_synth, rop_chain, heap_exploit, privesc_kb}` | working PoC artifacts |
+| 5 | `CONSENSUS` | `adversarial_reviewer`, `_run_acts_consensus()` | model-quorum verdict + ACTS score |
+| 6 | `DISCLOSURE` | `disclosure_vault`, `bounty_gateway`, `notifier` | encrypted writeup + optional submission |
+
+### 7.2 Tool dispatch
+Each phase exposes a small set of `HermesTool` subclasses
+(`ReconTool`, `TaintTool`, `SymbolicTool`, `FuzzTool`, `ExploitTool`,
+`CVETool`, `CommitWatchTool`, `SSECTool`, `ChainAnalyzerTool`). The
+`_dispatch_tool(tool_name, args, session)` function looks up the class by
+name and runs it with the session context. Tool output is appended to
+`session.findings` and persisted via `persist_hermes_session(session)`.
+
+### 7.3 Scoring
+- `compute_ves(...)` — Vulnerability Evidence Score: weighted combination of
+  reproducibility, exploitability, impact, and code-confidence signals.
+- `compute_acts(model_verdicts)` — Adversarial Consensus Trust Score:
+  measures inter-model agreement on the diff/exploit, used as an additional
+  gate before disclosure.
+
+### 7.4 LLM call surface
+Every Hermes-triggered LLM call goes through `_hermes_llm_call`, which
+implements the DO-primary / OpenRouter-fallback chain described in §2.2.
+This means even adversarial review and disclosure-prose generation
+benefit from the same provider resilience.
+
+### 7.5 Session persistence
+`HermesSession` is a dataclass (`session_id`, `target`, `phase`,
+`findings`, `tool_invocations`, `started_at`, `finished_at`,
+`provider_history`, `ves`, `acts`). `persist_hermes_session(session)`
+writes a JSON artifact under `/data/hermes_sessions/<session_id>.json`
+and appends an audit-trail event. The Gradio "Hermes Sessions" tab reads
+from this directory.
+
+### 7.6 TVG — Threat-Vector Graph
+`build_tvg(repo_dir, findings)` produces a directed graph of
+`(source → sink, primitive, finding_id)` edges suitable for downstream
+visualization or LLM-driven exploit-chain reasoning. Used by
+`mythos/reasoning/attack_graph.py` to compute reachable attack chains.
+
+---
+
+## 8. Safety Gate Modules
+<a id="8-safety-gates"></a>
+
+### 8.1 `sast_gate.py`
+Runs **bandit** on Python diffs, **semgrep** with language-appropriate rule
+sets on every diff, and a hand-rolled 16-pattern secret scanner over diff
+additions only. Patterns include: AWS access keys (`AKIA[0-9A-Z]{16}`),
+generic API keys (`api[_-]?key.*[=:].{20,}`), JWTs (`eyJ[\w-]+\.[\w-]+\.[\w-]+`),
+private key headers (`-----BEGIN (RSA|EC|OPENSSH|PGP) PRIVATE KEY-----`),
+`.env`-style assignments, OAuth tokens, SSH host keys, hardcoded passwords
+in connection strings, etc. Returns `SastVerdict(level, findings, raw)`
+where `level ∈ {PASS, BLOCK}`. A single CRITICAL or HIGH finding flips to
+BLOCK; MEDIUM/LOW are surfaced but advisory.
+
+### 8.2 `supply_chain.py`
+Two passes per diff:
+1. **Known CVEs.** Extract added packages from `requirements.txt`,
+   `package.json`, `pom.xml`, `go.mod`, `Cargo.toml`, `Gemfile`. Run the
+   matching CVE scanner: `pip-audit`, `npm audit --json`, OWASP
+   `dependency-check`, `govulncheck`, `cargo audit`, `bundler-audit`.
+2. **Typosquatting.** For each new package name, compute Levenshtein
+   distance against a 40+ entry list of canonical popular package names.
+   Anything within distance 1 of a popular name (and not equal to it)
+   is flagged as a likely typosquat.
+
+### 8.3 `formal_verifier.py`
+Three Z3-backed checks over diff additions:
+- **Div-by-zero.** Pattern-extract `expr / divisor` and `expr % divisor`,
+  parse `divisor` as a Z3 expr, query `solver.check(divisor == 0)`.
+- **Negative literal index.** Find `arr[k]` where `k` is an integer literal,
+  query satisfiability of `k < 0`.
+- **Always-false assert.** For each `assert expr`, walk the surrounding
+  scope for `name = literal` constants, substitute, query
+  `solver.check(Not(expr))`.
+Returns `FormalVerdict(SAFE | UNSAFE | SKIP, witnesses)`. Disabled by
+default (`RHODAWK_Z3_ENABLED=false`) because Z3 is a heavy import.
+
+### 8.4 `adversarial_reviewer.py`
+Sends the diff + failure + repo identity to three reviewer models in
+parallel via `concurrent.futures.ThreadPoolExecutor(max_workers=3)`. Each
+model receives an instruction template that demands a strict JSON envelope:
+`{verdict, confidence, critical_issues[], warnings[], retry_guidance}`.
+The reviewer parses each envelope, computes:
+- `consensus_votes = Counter(verdicts)`
+- `consensus_fraction = max(votes.values()) / 3`
+- final verdict = majority (≥`RHODAWK_CONSENSUS_THRESHOLD` of 0.67)
+- `critical_issues = union(per-model critical lists)`
+
+Sequential mode (`RHODAWK_ADVERSARY_SEQUENTIAL=true`) runs the same models
+serially. Used as a fallback when concurrent calls hit OpenRouter's
+per-key concurrency limits.
+
+### 8.5 `conviction_engine.py`
+Seven boolean criteria, all of which must be true to allow autonomous
+merge:
+1. `adversarial.verdict == APPROVE` (not just CONDITIONAL)
+2. `adversarial.confidence ≥ RHODAWK_CONVICTION_CONFIDENCE` (default 0.92)
+3. `adversarial.consensus_fraction ≥ RHODAWK_CONVICTION_CONSENSUS` (0.85)
+4. `verification.attempts == 1` (fixed on first try)
+5. `sast.findings == []` (zero SAST findings)
+6. `supply_chain.added_packages == []` (no new deps)
+7. `memory.best_match.similarity ≥ RHODAWK_CONVICTION_MEMORY_SIM` AND
+   `memory.best_match.merged_by_human == True`
+
+Returns `Conviction(met: bool, missing_criteria: list, score: float)`.
+The `score` is a weighted combination useful for analytics even when
+`met` is False.
+
+### 8.6 `taint_analyzer.py`
+Lightweight per-language source/sink dataflow analyzer used during the
+Hermes STATIC phase (not in the patch healing loop). Tracks tainted
+variables from common sources (HTTP request data, file reads, env vars,
+CLI args) to dangerous sinks (eval, subprocess, raw SQL, `pickle.loads`,
+`yaml.load`, `etree.fromstring`).
+
+### 8.7 `symbolic_engine.py`
+Wraps Z3 for richer symbolic execution beyond the single-statement checks
+in `formal_verifier.py`. Used by Hermes `SymbolicTool`.
+
+### 8.8 `vuln_classifier.py`
+Maps raw findings (from SAST tools, taint, fuzzers) to CWE IDs and
+estimated CVSS using a rule table. Output feeds `disclosure_vault` and
+`bounty_gateway`.
+
+---
+
+## 9. Memory, Learning, and Data Flywheel
+<a id="9-memory-learning"></a>
+
+### 9.1 `embedding_memory.py`
+Two interchangeable backends:
+
+**SQLite + MiniLM (default).** `sentence-transformers/all-MiniLM-L6-v2` for
+encoding. Embeddings stored in a SQLite table `(id, failure_norm, embedding
+BLOB, fix_diff, outcome, repo, ts)` and queried by cosine similarity using
+`sqlite-vec`. Lightweight, runs entirely in-process, no external service.
+
+**Qdrant + CodeBERT (optional).** `microsoft/codebert-base` for code-aware
+encoding. Vectors pushed to a Qdrant collection (HNSW index) — local or
+remote. Switched on via `RHODAWK_EMBEDDING_BACKEND=qdrant`.
+
+Public API used by the rest of the system:
+- `retrieve_similar_fixes_v2(failure_text, top_k=5)` → list of past fixes
+- `record_fix(failure_text, diff, outcome, repo)` → persists for future retrieval
+- `rebuild_embedding_index()` → re-encode entire training_store on demand
+
+Failure normalization strips file paths, line numbers, addresses, and
+hex IDs so that semantically identical failures across different repos
+collide in embedding space.
+
+### 9.2 `memory_engine.py`
+Legacy v1 store. Exact-key lookup by normalized failure signature. Kept
+for cold-start scenarios where the embedding index has zero entries.
+
+### 9.3 `training_store.py`
+SQLite database (`/data/training_store.sqlite`) with two tables:
+- `fix_attempts(id, ts, repo, test_path, failure, diff, model, attempt, success)`
+- `fix_patterns(signature, success_count, attempt_count, last_seen)`
+
+Entry points:
+- `record_attempt(...)` — every fix attempt, success or failure
+- `export_training_data(jsonl_path)` — writes
+  `{"messages": [{"role": "system", ...}, {"role": "user", ...},
+  {"role": "assistant", "content": diff}]}` — directly compatible with
+  HuggingFace TRL/PEFT SFT trainers.
+- `get_statistics()` — counts for the dashboard
+
+### 9.4 `lora_scheduler.py`
+Background daemon. Polls the training store. When **either**
+`RHODAWK_LORA_MIN_SAMPLES` (default 50) new successful fix pairs accumulate
+**or** `RHODAWK_LORA_MAX_AGE_HOURS` (default 168 = 1 week) elapse since the
+last export, it calls `training_store.export_training_data()` to a new
+JSONL file under `/data/lora_exports/lora_<timestamp>.jsonl`.
+
+### 9.5 `knowledge_rag.py`
+Retrieval-augmented generation helper for Hermes. Indexes long-form security
+documentation (the `architect/skills/*.md` library plus optionally fetched
+CVE writeups) and exposes a `retrieve(query, top_k)` helper that the
+research planner can call to ground exploit reasoning in vetted prior art.
+
+---
+
+## 10. Autonomous Operation — Harvester, Worker Pool, Job Queue
+<a id="10-autonomous-operation"></a>
+
+### 10.1 `repo_harvester.py`
+- Background daemon, gated by `RHODAWK_HARVESTER_ENABLED=true`.
+- Cycle period: `RHODAWK_HARVESTER_POLL_SECONDS` (default 21600 = 6 h).
+- Per cycle: GitHub Search API for repos in 7 supported languages
+  (`language:python`, `language:javascript`, …) with at least
+  `RHODAWK_HARVESTER_MIN_STARS` (default 100) and recent activity.
+- Cross-references each candidate's `check-runs` API to find currently
+  failing CI.
+- Scoring: `0.35*log(stars+1)/log(MAX_STARS+1) + 0.40*recency_score +
+  0.25*failing_check_count_score`.
+- Persists ranked feed to `/data/harvester_feed.json`.
+- Dispatches the top `RHODAWK_HARVESTER_MAX_REPOS` (default 20) targets
+  into the audit loop via `submit_repo_audit()`.
+
+### 10.2 `worker_pool.py`
+- `ThreadPoolExecutor(max_workers=RHODAWK_WORKERS)` (default 8).
+- When `RHODAWK_PROCESS_ISOLATE=true`: each job runs in
+  `multiprocessing.get_context("fork").Process` with a result `Queue`
+  and a hard timeout of `RHODAWK_ISOLATE_TIMEOUT` seconds (default 600).
+- On timeout: process is `terminate()`d then `kill()`ed if still alive,
+  job is marked `FAILED`, audit-trail event recorded.
+- Falls back gracefully to in-process execution if `fork` is not available
+  (e.g., Windows host — irrelevant to HF but matters for self-hosters).
+
+### 10.3 `job_queue.py`
+- SQLite-backed (`/data/job_queue.sqlite`).
+- Schema: `(tenant_id, repo, test_path)` UNIQUE → `(status, pr_url,
+  model_version, started_at, updated_at, attempts, last_error)`.
+- States: `PENDING`, `RUNNING`, `DONE`, `FAILED`, `SAST_BLOCKED`,
+  `ADVERSARIAL_REJECTED`, `CONVICTION_NOT_MET`.
+- Idempotency: a `DONE` row is skipped on resubmission. A `RUNNING` row
+  older than 1 hour (stale, from a crashed previous container) is reset to
+  `PENDING` after a branch-cleanup pass.
+- `prune_done_jobs(older_than_hours=72)` keeps the table from growing
+  unbounded.
+
+---
+
+## 11. GitHub Surface — `github_app.py`, `webhook_server.py`, `commit_watcher.py`
+<a id="11-github-surface"></a>
+
+### 11.1 `github_app.py`
+- **PAT mode (default).** Uses `GITHUB_TOKEN` directly via PyGithub.
+- **GitHub App mode.** Uses `RHODAWK_APP_ID` + `RHODAWK_APP_PRIVATE_KEY`
+  to issue a 10-minute JWT, exchange it for a 1-hour installation token,
+  and refresh on each call. Enterprise-grade auth.
+- `open_pr_for_repo(repo, branch, title, body)` — chooses standard or
+  fork mode based on `RHODAWK_FORK_MODE`.
+- **Standard mode.** Push branch to upstream, open PR upstream→upstream.
+- **Fork mode.** `fork_repo(repo)` (waits for GitHub's async fork to
+  complete by polling), push branch to fork, open cross-repo PR
+  fork→upstream. This is what enables fixing repos you don't own.
+- `merge_pr(url)` — used by the conviction engine when criteria are met.
+
+### 11.2 `webhook_server.py`
+HTTP server on port 7861. Endpoints:
+- `POST /webhook/github` — validates `X-Hub-Signature-256` HMAC against
+  `RHODAWK_WEBHOOK_SECRET`. Handles `push` and `check_run` events.
+- `POST /webhook/ci` — generic CI failure trigger (token in header).
+- `POST /webhook/trigger` — manual trigger (admin token).
+- `GET /webhook/health` — liveness.
+- `GET /webhook/queue` — current queue depth + last 20 events.
+Per-IP token bucket rate limiter (default 30 req/min per IP).
+
+### 11.3 `commit_watcher.py`
+Daemon for **silent-patch detection**. Polls a configured set of
+high-value upstream repos for new commits. Heuristics flag commits whose
+message says "fix" / "security" / "CVE" but which have no associated
+public advisory — a known pattern for CAD (Coordinated Asynchronous
+Disclosure) or under-the-radar security fixes. Findings are routed to
+`disclosure_vault` for downstream attribution.
+
+### 11.4 `chain_analyzer.py`
+Walks PR commit chains and groups related commits into "fix series" so
+that the training store records the *full* fix, not just the first commit
+in a multi-commit fix. Important for accurate (failure → fix) pair
+generation.
+
+---
+
+## 12. Red Team & Offense Modules
+<a id="12-red-team--offense"></a>
+
+### 12.1 `red_team_fuzzer.py`
+1,561 lines. The Blue Team-to-Red Team transition. When
+`process_audit_test` finishes and all tests are green, this module:
+- Generates property-based tests using **Hypothesis** strategies inferred
+  from function signatures.
+- Runs them with `pytest --hypothesis-show-statistics`.
+- Captures shrunken counterexamples.
+- Feeds the counterexamples into a CEGIS loop: each refuted property
+  becomes the spec for the next attack synthesis round.
+- Zero-day candidates are written as JSON artifacts under `/data/findings/`
+  and handed back to the Blue Team healing loop so the bug becomes a fix.
+
+### 12.2 `fuzzing_engine.py`
+Lower-level fuzzing primitives consumed by both `red_team_fuzzer.py` and
+the Hermes DYNAMIC phase. Bridges to `mythos/dynamic/aflpp_runner.py`,
+`klee_runner.py`, and `qemu_harness.py` when those are available.
+
+### 12.3 `harness_factory.py`
+Generates fuzz harnesses from function signatures: type inference,
+seed corpus extraction from existing tests, AFL++/libFuzzer wrapper
+emission. Used by `red_team_fuzzer.py` and Hermes.
+
+### 12.4 `exploit_primitives.py`
+Catalogs reusable exploitation primitives: arbitrary read/write,
+function-pointer overwrite, format-string leak, integer-overflow ladder,
+heap-grooming templates. Each primitive has a `match(finding) → bool`
+predicate and an `apply(finding) → ExploitArtifact` synthesizer.
+
+### 12.5 `cve_intel.py`
+NVD/OSV/Snyk lookup for prior-art correlation. Given a finding, returns
+the closest known CVE and similarity score so the disclosure isn't a
+duplicate.
+
+---
+
+## 13. Notification, Audit, Disclosure, Bounty
+<a id="13-notification-audit"></a>
+
+### 13.1 `notifier.py`
+- Telegram via Bot API (`TELEGRAM_BOT_TOKEN` + `TELEGRAM_CHAT_ID`).
+- Slack via incoming webhook (`SLACK_WEBHOOK_URL`).
+- All sends are non-blocking (background threads with bounded queue).
+- Templates for: AUDIT_START, TEST_FAIL, PR_CREATED, PATCH_FAIL,
+  SAST_BLOCK, AUDIT_COMPLETE, ZERO_DAY_FOUND, DISCLOSURE_SUBMITTED.
+
+### 13.2 `audit_logger.py`
+Append-only JSONL at `/data/audit_trail.jsonl`. Each entry:
+```json
+{
+  "ts": "2026-04-22T12:34:56Z",
+  "event": "ADVERSARIAL_REVIEW",
+  "tenant": "acme",
+  "repo": "owner/name",
+  "payload": {...},
+  "prev_hash": "sha256:...",
+  "hash": "sha256:..."
+}
+```
+`prev_hash` is the hash of the previous entry; `hash` is the SHA-256 of
+the current entry (excluding the `hash` field itself). The genesis entry
+has `prev_hash = "0"*64`.
+
+`verify_chain_integrity()` walks the file from genesis, recomputes each
+hash, and asserts equality. Any tamper anywhere breaks the chain at the
+tampered point and every subsequent entry. SOC 2 / ISO 27001 evidence
+artifact.
+
+### 13.3 `disclosure_vault.py`
+Encrypted at-rest storage for vulnerability writeups. Uses Fernet with a
+key derived from `DISCLOSURE_VAULT_PASSPHRASE`. Each entry:
+finding metadata + full PoC + suggested fix + CVE correlation. Read API
+requires the same passphrase. Used by Hermes DISCLOSURE phase before
+any public submission.
+
+### 13.4 `bounty_gateway.py`
+Programmatic submission to HackerOne, Bugcrowd, Intigriti, YesWeHack via
+their REST APIs. Submission requires:
+- Finding has passed adversarial CONSENSUS phase
+- VES ≥ configured floor
+- Manual approval flag (default: required) OR
+  `RHODAWK_BOUNTY_AUTO_SUBMIT=true` (off by default — kept off in
+  production)
+
+### 13.5 `oss_guardian.py`
+Stewardship layer for fixes pushed to OSS repos. Tracks PR status,
+maintainer responses, and time-to-merge. Feeds analytics for the public
+leaderboard and for the conviction engine's "merged by human" signal.
+
+### 13.6 `oss_target_scorer.py`
+Scoring helper used by both the harvester and the public leaderboard to
+rank repos by community impact (stars, dependents, ecosystem centrality).
+
+### 13.7 `public_leaderboard.py`
+Standalone Gradio interface (port 7862) showing PRs submitted, PRs
+merged, repos touched, patterns learned, zero-days reported. All numbers
+read directly from `audit_trail.jsonl` and `training_store.sqlite` —
+no synthetic metrics.
+
+### 13.8 `swebench_harness.py`
+Runs the Rhodawk healing loop against SWE-bench Verified instances.
+Reports pass@1. Same pipeline as production — no special-cased logic.
+Provides reproducible benchmarks for investor/customer claims.
+
+---
+
+## 14. Architect Subsystem — Tier Routing, Sandbox, Skills, Night Mode
+<a id="14-architect"></a>
+
+The `architect/` package is the higher-order control layer that sits above
+the per-test healing loop and decides which model, which skill, and which
+sandbox each task should use.
+
+### 14.1 `architect/model_router.py`
+Five-tier model router. Each task is classified by complexity and routed
+to the cheapest tier that can satisfy it:
+- **Tier 1 — Ultra.** DeepSeek 3.2, MiniMax 2.5. Used for global strategy
+  and multi-repo planning.
+- **Tier 2 — Strong.** Qwen 2.5 Coder 32B. Default patch generator.
+- **Tier 3 — Balanced.** Llama 3.3 70B (DigitalOcean), DeepSeek V3,
+  Gemma 2 27B. Adversarial reviewers.
+- **Tier 4 — Lite.** Mistral 7B, Gemma 2 9B. Cheap second-opinion calls.
+- **Tier 5 — Local.** Embedded MiniLM/CodeBERT for embeddings — no LLM call.
+
+The router consumes `(task_type, code_size_tokens, security_sensitivity,
+required_capabilities)` and returns a routing decision with `provider`,
+`model`, and `expected_cost_usd`.
+
+### 14.2 `architect/sandbox.py`
+`SandboxManager` — abstraction over (a) plain subprocess, (b) `bwrap`
+(bubblewrap) namespace isolation, (c) Firecracker microVM (planned).
+Currently used in subprocess + bwrap modes for any tool execution that
+must not touch the host filesystem outside `/tmp/sandbox/<id>/`.
+
+### 14.3 `architect/skill_registry.py`
+Registers the 28 skill markdown files under `architect/skills/` as
+discoverable knowledge units. Each skill file declares: domain
+(api-security, container-escape, smart-contract-audit, …), required
+tools, suggested model tier, and reference references. The registry
+exposes `find_skills(query) → list[Skill]` for the planner.
+
+### 14.4 `architect/skills/`
+28 long-form security playbooks covering: api-security, ai-ml-security,
+automotive-security, aviation-aerospace, binary-analysis, browser-engine
+security, ci-cd-pipeline-attack, cloud-security, container-escape,
+cryptographic-implementation, cryptography-attacks, firmware-analysis,
+hardware-protocols, ics-scada, linux-kernel-exploitation, llm-system-
+prompt-injection, memory-safety, mobile-android, mobile-ios, network-
+protocol, reverse-engineering, rf-radio-security, satellite-comms,
+smart-contract-audit, supply-chain, vibe-coded-app-hunter, web-security
+advanced, zero-day-research, plus `bb-methodology-claude.md` and
+`bug-bounty-reference-index.md`.
+
+### 14.5 `architect/nightmode.py`
+The autonomous "night mode" loop. When enabled, between human-driven
+audits the system pulls in scope from connected bug-bounty platforms
+(via `mythos.mcp.scope_parser_mcp`), enumerates targets, and runs
+Hermes pipelines against authorized scope only — submitting findings
+through `bounty_gateway`. Hard-gated by `ARCHITECT_NIGHTMODE_ENABLED=true`
+and a per-platform scope-acceptance check.
+
+### 14.6 `architect/godmode_consensus.py`
+A heavier-weight consensus protocol used by night mode that runs the
+adversarial trio AND a Tier 1 model, requiring unanimous agreement
+before any external submission. Higher false-negative rate, near-zero
+false-positive rate — appropriate when the action is irreversible.
+
+### 14.7 `architect/master_redteam_prompt.py`
+Centralizes the master prompt used by the red-team modules. Externalizing
+the prompt makes it tunable without code changes and auditable for
+prompt-injection resistance.
+
+### 14.8 `architect/parseltongue.py`
+Internal DSL for declaring multi-step research plans. Compiles to a
+sequence of `HermesTool` invocations. Used by the Mythos planner agent.
+
+### 14.9 `architect/embodied_bridge.py`
+Bridge to the EmbodiedOS / OpenClaw / Hermes Agent runtime when present
+externally. Stubs gracefully when EmbodiedOS is not reachable.
+
+### 14.10 `architect/rl_feedback_loop.py`
+RL feedback collector. After each fix, an outcome reward is computed
+(merge=+1, rejected=-0.5, never-reviewed-after-30-days=-0.1) and the
+plan-level statistics are updated for the planner's policy table.
+
+---
+
+## 15. Mythos Subsystem — Multi-Agent + RL + 17 MCP Servers
+<a id="15-mythos"></a>
+
+`mythos/` is the deepest research layer — designed to close the gap between
+Rhodawk's deterministic 6-phase pipeline and a Mythos-class autonomous
+research agent.
+
+### 15.1 `mythos/MYTHOS_PLAN.md`
+Living blueprint document mapping Rhodawk's gaps to concrete Mythos
+modules. Read this first to understand the design intent.
+
+### 15.2 `mythos/agents/`
+- `base.py` — abstract `Agent` class with `observe`, `plan`, `act`.
+- `planner.py` — generates research plans from a target description.
+  Uses the Tier 1 model + RL policy table.
+- `explorer.py` — enumeration agent for recon and surface mapping.
+- `executor.py` — runs concrete tools (calls into `mythos/static`,
+  `mythos/dynamic`, `mythos/exploit`).
+- `orchestrator.py` — top-level coordinator that wires planner →
+  explorer → executor → consensus and persists the trace.
+
+### 15.3 `mythos/static/`
+- `treesitter_cpg.py` — Tree-sitter–based Code Property Graph builder.
+- `joern_bridge.py` — Joern CPG queries for taint chains.
+- `codeql_bridge.py` — CodeQL pack runner with predefined query sets.
+- `semgrep_bridge.py` — Semgrep with curated security rule packs.
+
+### 15.4 `mythos/dynamic/`
+- `aflpp_runner.py` — AFL++ harness execution.
+- `klee_runner.py` — KLEE symbolic execution wrapper.
+- `qemu_harness.py` — full-system QEMU with snapshot/restore.
+- `frida_instr.py` — Frida runtime instrumentation sessions.
+- `gdb_automation.py` — scripted GDB triage of crashes.
+
+### 15.5 `mythos/exploit/`
+- `pwntools_synth.py` — pwntools-based PoC synthesis.
+- `rop_chain.py` — ROP gadget search + chain assembly via ROPGadget.
+- `heap_exploit.py` — heap exploitation primitives (tcache, fastbin,
+  unsafe-unlink).
+- `privesc_kb.py` — privilege escalation knowledge base + matcher.
+
+### 15.6 `mythos/learning/`
+- `rl_planner.py` — RL planner using the reward signal from
+  `architect/rl_feedback_loop.py`.
+- `curriculum.py` — curriculum learning over progressively harder
+  vulnerability classes.
+- `episodic_memory.py` — episodic store of full
+  (target, plan, action, observation, reward) trajectories.
+- `mlflow_tracker.py` — MLflow run tracking for training experiments.
+- `lora_adapters.py` — LoRA adapter loader; lets the system swap in
+  domain-specific adapters per task.
+
+### 15.7 `mythos/reasoning/`
+- `probabilistic.py` — probabilistic attack-vector reasoning.
+- `attack_graph.py` — attack-graph construction over `(asset, action,
+  result)` triples; computes minimum-cost reachable goal paths.
+
+### 15.8 `mythos/api/`
+- `fastapi_server.py` — optional FastAPI server (port 7863) exposing
+  `/audit`, `/research`, `/findings`, `/leaderboard` JSON APIs.
+- `auth.py` — bearer-token auth middleware.
+- `schemas.py` — Pydantic request/response models.
+- `webhooks.py` — webhook delivery on async events.
+
+### 15.9 `mythos/skills/`
+- `registry.py` — runtime skill discovery and ranking. Bridges to
+  `architect/skill_registry.py` to expose skills via MCP.
+
+### 15.10 `mythos/integration.py`
+Top-level wiring. Initializes the Mythos subsystem from `app.py`'s
+startup. If Mythos modules fail to import (optional dependencies
+missing), it logs a warning and lets the system continue without the
+Mythos features.
+
+### 15.11 `mythos/diagnostics.py`
+Self-test CLI. `python -m mythos.diagnostics` prints which agents,
+MCP servers, and external tools are reachable, and exits non-zero if
+any required component is broken. Used by the `mythos.__main__` entry
+point and by container health checks.
+
+### 15.12 `mythos/__main__.py`
+Allows `python -m mythos` to launch the Mythos subsystem standalone.
+
+---
+
+## 16. MCP Suite — Every Server, Every Domain
+<a id="16-mcp-suite"></a>
+
+The `mcp_config.json` template declares **34 MCP server entries** (with
+some duplicates — see note below). Aider is launched with the rendered
+`/tmp/mcp_runtime.json` so all of these tools become callable during
+patch generation. Hermes also calls them directly.
+
+### 16.1 Generic / shared servers
+| Server | Command | Purpose |
+|---|---|---|
+| `fetch-docs` | `uvx mcp-server-fetch` | HTTP fetch with SSRF allow-list (60+ domains) |
+| `github-manager` | `npx @modelcontextprotocol/server-github` | full GitHub API |
+| `filesystem-research` | `npx @modelcontextprotocol/server-filesystem` | RO access to `/data/repo`, `/tmp/research`, `/tmp/findings` |
+| `memory-store` | `npx @modelcontextprotocol/server-memory` | persistent KG of exploit chains |
+| `sequential-thinking` | `npx @modelcontextprotocol/server-sequential-thinking` | structured CoT |
+| `web-search` | `npx @modelcontextprotocol/server-brave-search` | Brave search API |
+| `git-forensics` | `npx @modelcontextprotocol/server-git` | deep git-history analysis |
+| `postgres-intelligence` | `npx @modelcontextprotocol/server-postgres` | findings DB queries |
+| `sqlite-findings` | `npx @modelcontextprotocol/server-sqlite` | local findings DB |
+
+### 16.2 Security tooling shells (`mcp-server-shell` allow-list)
+| Server | Allowed binaries | Purpose |
+|---|---|---|
+| `nuclei-scanner` | `nuclei,nuclei-templates` | DAST + CVE templates |
+| `semgrep-sast` | `semgrep` | taint + CWE + secrets |
+| `trufflehog-secrets` | `trufflehog` | git-history secret scan |
+| `bandit-sast` | `bandit` | Python AST SAST |
+| `pip-audit-sca` | `pip-audit,pip` | OSV-backed Python SCA |
+| `osv-scanner` | `osv-scanner` | multi-ecosystem SCA |
+| `z3-formal-verifier` | `python3` | Z3 verification scripts |
+| `hypothesis-fuzzer` | `python3,pytest,hypothesis` | property-based testing |
+| `atheris-fuzzer` | `python3,atheris` | coverage-guided fuzzing |
+| `angr-symbolic` | `python3` | binary symbolic execution |
+| `radon-complexity` | `radon` | complexity / attack surface |
+| `ruff-linter` | `ruff` | anti-pattern detection |
+| `aider-patcher` | `aider` | patch synthesis (recursive — careful) |
+
+### 16.3 Intelligence + bounty
+| Server | Purpose |
+|---|---|
+| `cve-intelligence` | NVD / CVE.org / OSV fetch |
+| `bounty-platform` | HackerOne/Bugcrowd/Intigriti/YesWeHack APIs |
+| `supply-chain-monitor` | PyPI/npm/crates typosquatting + dep-confusion |
+
+### 16.4 Mythos-native MCP servers (Python modules)
+| Server | Module | Purpose |
+|---|---|---|
+| `reconnaissance-mcp` | `mythos.mcp.reconnaissance_mcp` | language/framework/dep fingerprinting + attack surface |
+| `static-analysis-mcp` | `mythos.mcp.static_analysis_mcp` | Tree-sitter CPG + Joern + CodeQL + Semgrep |
+| `dynamic-analysis-mcp` | `mythos.mcp.dynamic_analysis_mcp` | AFL++ + KLEE + QEMU + Frida + GDB |
+| `exploit-generation-mcp` | `mythos.mcp.exploit_generation_mcp` | Pwntools + ROP + heap + privesc |
+| `vulnerability-database-mcp` | `mythos.mcp.vulnerability_database_mcp` | NVD/OSV/Exploit-DB lookup |
+| `web-security-mcp` | `mythos.mcp.web_security_mcp` | OWASP ZAP + nuclei + sqlmap orchestration |
+| `browser-agent-mcp` | `mythos.mcp.browser_agent_mcp` | Playwright live browser |
+| `scope-parser-mcp` | `mythos.mcp.scope_parser_mcp` | bug-bounty scope ingestion |
+| `subdomain-enum-mcp` | `mythos.mcp.subdomain_enum_mcp` | subfinder + amass + dnsx + crt.sh |
+| `httpx-probe-mcp` | `mythos.mcp.httpx_probe_mcp` | concurrent HTTP probing + tech fingerprint |
+| `shodan-mcp` | `mythos.mcp.shodan_mcp` | Shodan REST passive recon |
+| `wayback-mcp` | `mythos.mcp.wayback_mcp` | Wayback / CommonCrawl historical URL recall |
+| `frida-runtime-mcp` | `mythos.mcp.frida_runtime_mcp` | live Frida instrumentation |
+| `ghidra-bridge-mcp` | `mythos.mcp.ghidra_bridge_mcp` | headless Ghidra / radare2 bridge |
+| `can-bus-mcp` | `mythos.mcp.can_bus_mcp` | automotive CAN-bus + UDS (ISO 14229) |
+| `sdr-analysis-mcp` | `mythos.mcp.sdr_analysis_mcp` | GNU Radio / rtl_sdr RF capture |
+
+> **Duplicate-key note.** `mcp_config.json` currently declares
+> `scope-parser-mcp`, `subdomain-enum-mcp`, `wayback-mcp`, `httpx-probe-mcp`,
+> and `shodan-mcp` twice. JSON parse semantics use the last value, so the
+> ARCHITECT-flavored variants (with `env` injections for HackerOne/Shodan
+> tokens) are what wins at runtime. The earlier entries are dead weight
+> and could be removed in a future cleanup commit.
+
+### 16.5 Runtime materialization
+On startup, `app.py` reads `mcp_config.json`, recursively replaces every
+`__INJECTED_BY_APP_AT_RUNTIME__` placeholder with the corresponding env
+var value (`OPENROUTER_API_KEY`, `BRAVE_API_KEY`, `DATABASE_URL`,
+`HACKERONE_API_TOKEN`, `BUGCROWD_API_TOKEN`, `INTIGRITI_API_TOKEN`,
+`SHODAN_API_KEY`, `NVD_API_KEY`, `NUCLEI_API_KEY`, `SEMGREP_APP_TOKEN`,
+`GITHUB_PERSONAL_ACCESS_TOKEN`), drops any server whose required secret
+is missing, and writes the result to `/tmp/mcp_runtime.json`. Aider
+launches with `--mcp-config /tmp/mcp_runtime.json`. **Secrets are never
+committed.**
+
+---
+
+## 17. Test Suite — What Each Test Asserts
+<a id="17-test-suite"></a>
+
+`tests/` contains 9 test modules and one `conftest.py`.
+
+| Test file | What it asserts |
+|---|---|
+| `test_audit_chain.py` | The SHA-256 audit chain in `audit_logger.py` rejects tampering. Writes synthetic events, mutates one entry, expects `verify_chain_integrity()` to flag the break point. |
+| `test_job_queue.py` | Idempotency guarantees: identical `(tenant, repo, test_path)` submissions don't duplicate. Stale RUNNING rows older than 1h reset to PENDING. Status transitions are valid. |
+| `test_mcp_servers_load.py` | The MCP runtime config materializes correctly: all `__INJECTED__` placeholders are resolved or the server is dropped. No secrets leak into the rendered file. |
+| `test_model_router.py` | The 5-tier router produces deterministic routing for the same input. Tier promotions happen on capability misses. Cost estimates are monotonic with tier. |
+| `test_mythos_diagnostics.py` | `mythos.diagnostics.run_diagnostics()` exits 0 in healthy state and non-zero when any required Mythos module is missing. |
+| `test_nightmode_smoke.py` | Architect night mode initializes without external services and refuses to act when no scope source is configured. |
+| `test_scope_parser.py` | The HackerOne / Bugcrowd / Intigriti scope parsers correctly partition assets into IN_SCOPE / OUT_OF_SCOPE buckets with edge cases (wildcards, port specs, regex policies). |
+| `test_skill_registry.py` | The 28 skill files in `architect/skills/` are all parseable, declare required metadata, and are discoverable by `find_skills(query)`. |
+| `test_webhook_hmac.py` | `webhook_server.py` rejects requests with invalid HMAC signatures and accepts valid ones. Constant-time comparison is used (no timing side channel). |
+
+`conftest.py` defines fixtures for: temporary `/data` overrides, mock
+GitHub API, mock OpenRouter API, in-memory SQLite for the job queue and
+training store, and a synthetic failing-test repo factory.
+
+---
+
+## 18. Data on Disk — Files, SQLite Schemas, Audit Chain
+<a id="18-data-on-disk"></a>
+
+```
+/data/
+├── job_queue.sqlite                 # job_queue.py
+├── training_store.sqlite            # training_store.py (fix_attempts, fix_patterns)
+├── embedding_index.sqlite           # embedding_memory.py SQLite backend
+├── memory_engine.sqlite             # legacy v1 pattern memory
+├── rhodawk_findings.db              # MCP sqlite-findings server
+├── audit_trail.jsonl                # SHA-256 chained event log
+├── harvester_feed.json              # ranked candidate repos
+├── disclosure_vault/
+│   └── <finding_id>.fernet          # encrypted writeups
+├── lora_exports/
+│   └── lora_<timestamp>.jsonl       # SFT-ready training data
+├── hermes_sessions/
+│   └── <session_id>.json            # persisted Hermes research sessions
+├── findings/
+│   └── <finding_id>.json            # raw findings from red team / Mythos
+├── repo/
+│   └── <owner>__<name>/             # cloned target repos (ephemeral)
+├── nuclei-templates/                # nuclei DAST templates cache
+└── research/                        # MCP filesystem-research scratch
+```
+
+`/tmp/`:
+```
+/tmp/
+├── mcp_runtime.json                 # rendered MCP config (with secrets)
+├── sandbox/<id>/                    # bwrap sandbox roots
+└── findings/                        # MCP filesystem-research output
+```
+
+### 18.1 SQLite schemas (effective)
+
+```sql
+-- training_store.sqlite
+CREATE TABLE fix_attempts (
+  id INTEGER PRIMARY KEY,
+  ts TEXT NOT NULL,
+  repo TEXT NOT NULL,
+  test_path TEXT NOT NULL,
+  failure TEXT NOT NULL,
+  diff TEXT,
+  model TEXT,
+  attempt INTEGER,
+  success INTEGER NOT NULL
+);
+CREATE INDEX ix_fix_attempts_repo ON fix_attempts(repo);
+CREATE INDEX ix_fix_attempts_success ON fix_attempts(success);
+
+CREATE TABLE fix_patterns (
+  signature TEXT PRIMARY KEY,
+  success_count INTEGER NOT NULL DEFAULT 0,
+  attempt_count INTEGER NOT NULL DEFAULT 0,
+  last_seen TEXT NOT NULL
+);
+
+-- job_queue.sqlite
+CREATE TABLE jobs (
+  tenant_id TEXT NOT NULL,
+  repo TEXT NOT NULL,
+  test_path TEXT NOT NULL,
+  status TEXT NOT NULL,
+  pr_url TEXT,
+  model_version TEXT,
+  started_at TEXT,
+  updated_at TEXT NOT NULL,
+  attempts INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  PRIMARY KEY (tenant_id, repo, test_path)
+);
+
+-- embedding_index.sqlite (sqlite-vec)
+CREATE TABLE embeddings (
+  id INTEGER PRIMARY KEY,
+  failure_norm TEXT,
+  embedding BLOB,           -- vector serialized via sqlite-vec
+  fix_diff TEXT,
+  outcome TEXT,
+  repo TEXT,
+  ts TEXT
+);
+CREATE VIRTUAL TABLE embedding_index USING vec0(
+  embedding float[384]
+);
+```
+
+### 18.2 Audit chain entry shape
+```json
+{
+  "ts":  "2026-04-22T13:14:15.123Z",
+  "event": "ADVERSARIAL_REVIEW",
+  "tenant": "default",
+  "repo": "owner/name",
+  "test_path": "tests/test_x.py",
+  "payload": {
+    "verdict": "APPROVE",
+    "confidence": 0.93,
+    "consensus_fraction": 1.0,
+    "models": ["qwen-2.5-7b", "gemma-2-9b", "mistral-7b"],
+    "critical_issues": [],
+    "warnings": ["minor style nit"]
+  },
+  "prev_hash": "sha256:f3a1...c0",
+  "hash": "sha256:9b22...ee"
+}
+```
+
+---
+
+## 19. Complete Environment Variable Reference (Updated)
+<a id="19-env-vars"></a>
+
+This table supersedes the playbook's reference for everything related to
+inference providers and the build-changed paths.
+
+### 19.1 Required for any meaningful run
+| Var | Purpose |
+|---|---|
+| `GITHUB_TOKEN` | PAT with `repo` scope (or use App mode below) |
+| `OPENROUTER_API_KEY` | needed for fallback + adversarial trio |
+| `DO_INFERENCE_API_KEY` | strongly recommended — enables paid DO primary |
+
+### 19.2 Inference providers (new since playbook)
+| Var | Default | Description |
+|---|---|---|
+| `DO_INFERENCE_API_KEY` | — | DigitalOcean Serverless Inference key |
+| `DO_INFERENCE_BASE_URL` | `https://inference.do-ai.run/v1` | DO endpoint |
+| `DO_INFERENCE_MODEL` | `llama3.3-70b-instruct` | Aider's primary model on DO |
+| `HERMES_DO_MODEL` | `${DO_INFERENCE_MODEL}` | Hermes' primary model on DO |
+| `HERMES_OR_MODEL` | `qwen/qwen-2.5-coder-32b-instruct:free` | Hermes' OpenRouter fallback |
+| `OPENROUTER_API_KEY` | — | Fallback + adversarial models |
+
+### 19.3 Models, retries, consensus
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_MODEL` | (computed: DO if available else OR free) | Aider primary model |
+| `RHODAWK_ADVERSARY_MODEL` | `openrouter/qwen/qwen-2.5-7b-instruct:free` | lead reviewer |
+| `RHODAWK_CONSENSUS_THRESHOLD` | `0.67` | majority fraction |
+| `RHODAWK_ADVERSARY_SEQUENTIAL` | `false` | serial vs concurrent reviewers |
+| `MAX_RETRIES` | `5` | healing-loop retry budget |
+| `ADVERSARIAL_REJECTION_MULTIPLIER` | `2` | extra retries when reject reason is adversarial |
+
+### 19.4 Conviction (auto-merge)
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_AUTO_MERGE` | `false` | enable autonomous merge |
+| `RHODAWK_CONVICTION_CONFIDENCE` | `0.92` | min adversarial confidence |
+| `RHODAWK_CONVICTION_CONSENSUS` | `0.85` | min consensus fraction |
+| `RHODAWK_CONVICTION_MEMORY_SIM` | `0.85` | min memory similarity |
+
+### 19.5 Memory backend
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_EMBEDDING_BACKEND` | `sqlite` | `sqlite` or `qdrant` |
+| `RHODAWK_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | SQLite backend encoder |
+| `RHODAWK_CODEBERT_MODEL` | `microsoft/codebert-base` | Qdrant backend encoder |
+| `QDRANT_URL` | — | Qdrant remote URL when not local |
+| `QDRANT_API_KEY` | — | Qdrant cloud auth |
+
+### 19.6 LoRA scheduler
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_LORA_ENABLED` | `false` | enable scheduler |
+| `RHODAWK_LORA_MIN_SAMPLES` | `50` | min new fixes per export |
+| `RHODAWK_LORA_MAX_AGE_HOURS` | `168` | max time between exports |
+| `RHODAWK_LORA_OUTPUT_DIR` | `/data/lora_exports` | JSONL destination |
+
+### 19.7 Harvester
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_HARVESTER_ENABLED` | `false` | start daemon |
+| `RHODAWK_HARVESTER_POLL_SECONDS` | `21600` | cycle interval |
+| `RHODAWK_HARVESTER_MIN_STARS` | `100` | min stars to consider |
+| `RHODAWK_HARVESTER_MAX_REPOS` | `20` | targets per cycle |
+
+### 19.8 Worker pool & isolation
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_WORKERS` | `8` | parallel workers |
+| `RHODAWK_PROCESS_ISOLATE` | `false` | per-job subprocess isolation |
+| `RHODAWK_ISOLATE_TIMEOUT` | `600` | per-job timeout (seconds) |
+
+### 19.9 GitHub
+| Var | Default | Description |
+|---|---|---|
+| `GITHUB_TOKEN` | — | PAT auth |
+| `RHODAWK_FORK_MODE` | `false` | enable fork-and-PR for any public repo |
+| `RHODAWK_FORK_OWNER` | _(authenticated user)_ | org to fork into |
+| `RHODAWK_APP_ID` | — | GitHub App ID |
+| `RHODAWK_APP_PRIVATE_KEY` | — | GitHub App PEM |
+| `RHODAWK_WEBHOOK_SECRET` | — | HMAC for `/webhook/github` |
+
+### 19.10 Adversarial / red team / formal
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_RED_TEAM_ENABLED` | `true` | enable CEGIS fuzzer when all tests green |
+| `RHODAWK_Z3_ENABLED` | `false` | enable Z3 formal verification gate |
+
+### 19.11 Architect / Mythos / night mode
+| Var | Default | Description |
+|---|---|---|
+| `ARCHITECT_NIGHTMODE_ENABLED` | `false` | enable autonomous night mode |
+| `ARCHITECT_GODMODE_REQUIRED` | `true` | require unanimous consensus before external action |
+| `MYTHOS_API_ENABLED` | `false` | start FastAPI on 7863 |
+| `MYTHOS_API_TOKEN` | — | bearer token for the FastAPI |
+| `DISCLOSURE_VAULT_PASSPHRASE` | — | Fernet key derivation passphrase |
+| `RHODAWK_BOUNTY_AUTO_SUBMIT` | `false` | auto-submit to bounty platforms |
+
+### 19.12 External intelligence
+| Var | Description |
+|---|---|
+| `BRAVE_API_KEY` | Brave Search MCP |
+| `SHODAN_API_KEY` | Shodan recon MCP |
+| `NVD_API_KEY` | NVD CVE intelligence MCP |
+| `NUCLEI_API_KEY` | Nuclei templates premium feed |
+| `SEMGREP_APP_TOKEN` | Semgrep Cloud rules |
+| `HACKERONE_USERNAME`, `HACKERONE_API_TOKEN`, `HACKERONE_API_KEY` | HackerOne |
+| `BUGCROWD_API_TOKEN` | Bugcrowd |
+| `INTIGRITI_API_TOKEN` | Intigriti |
+
+### 19.13 Notifications
+| Var | Description |
+|---|---|
+| `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | Telegram alerts |
+| `SLACK_WEBHOOK_URL` | Slack alerts |
+
+### 19.14 Multitenancy
+| Var | Default | Description |
+|---|---|---|
+| `RHODAWK_TENANT_ID` | `default` | namespace prefix for jobs, audits, exports |
+
+---
+
+## 20. Failure Modes and Recovery Procedures
+<a id="20-failure-modes"></a>
+
+| Symptom | Most likely cause | Recovery |
+|---|---|---|
+| Build fails on `pillow` resolver conflict | `requirements.txt` re-lists `aider-chat` | Remove it; aider must be `--no-deps` only in Dockerfile |
+| Build fails with `gradio[oauth,mcp]==5.29.0` injection | Space SDK reverted to `gradio` | Confirm `sdk: docker` in `README.md` front-matter |
+| Aider crashes `litellm has no attribute APIConnectionError` | litellm 1.75.0 reinstalled by transitive dep | Re-run the `pip install --no-deps litellm==1.78.5` step or pin in Dockerfile |
+| All LLM calls fail with 429 | OpenRouter rate-limited and DO not configured | Set `DO_INFERENCE_API_KEY`; calls will route to DO first |
+| All LLM calls fail with `No inference provider configured` | Both `DO_INFERENCE_API_KEY` and `OPENROUTER_API_KEY` missing | Set at least one; restart container |
+| Webhook 401 from GitHub | `RHODAWK_WEBHOOK_SECRET` mismatch | Re-set the secret in the GitHub repo's webhook config to match |
+| Audit hangs forever on a single test | Aider subprocess wedged | Set `RHODAWK_PROCESS_ISOLATE=true` and `RHODAWK_ISOLATE_TIMEOUT=600` |
+| `embedding_index.sqlite` corrupted | Hard kill mid-write | Delete the file; `rebuild_embedding_index()` will reconstruct from `training_store.sqlite` |
+| Audit chain integrity fails | Manual edit of `audit_trail.jsonl` | The chain is correctly rejecting tamper. To start a new chain, archive and remove the file; a new genesis entry will be written. |
+| Conviction never fires | Memory has zero matches at threshold ≥0.85 | Expected on cold start; lower `RHODAWK_CONVICTION_MEMORY_SIM` to 0.75 in early life if you want auto-merge sooner — but be honest with yourself about what you're trading. |
+| MCP server fails to spawn | `npx`/`uvx` missing or required env var unset | Check container has nodejs+npm and uvx (uv); confirm injected env var is present at startup |
+| Harvester feed empty | Token lacks search scope or rate limited | Confirm `GITHUB_TOKEN` has `public_repo`; raise `RHODAWK_HARVESTER_MIN_STARS` |
+| Mythos FastAPI 401 | Wrong bearer token | Confirm `MYTHOS_API_TOKEN` matches client header |
+
+---
+
+## 21. Security Model — Trust Boundaries and Threat Mitigation
+<a id="21-security-model"></a>
+
+### 21.1 Trust boundaries
+1. **Container ↔ host.** Container runs as root in the Docker image but
+   touches only `/data` (mounted) and `/tmp` (ephemeral). No host paths
+   leak.
+2. **Container ↔ target repo.** Cloned repos live in `/data/repo/<id>/`.
+   They are treated as untrusted: scripts in target repos are never
+   `python <target_script>`'d directly — only the runtime's allowed
+   commands (`pytest`, `npm test`, `go test`, …) are invoked.
+3. **Container ↔ LLM provider.** Code snippets and failure traces are
+   sent over the wire to DigitalOcean Inference and OpenRouter. This is
+   the primary data-leakage surface — controlled by deployment mode (HF
+   Spaces is multi-tenant; self-hosted is single-tenant).
+4. **MCP fetch ↔ internet.** `fetch-docs` and similar fetch MCPs use
+   `FETCH_ALLOWED_DOMAINS` allow-lists to prevent SSRF against internal
+   services.
+5. **Webhook ↔ public internet.** All webhook endpoints validate HMAC
+   signatures with constant-time comparison. Per-IP rate limiting in
+   front. No untrusted JSON is unpickled.
+
+### 21.2 Threat mitigation by attack
+| Threat | Mitigation |
+|---|---|
+| Prompt injection in target source | Multi-model adversarial review catches divergent reactions; SAST/supply-chain catch the resulting bad diffs |
+| LLM-introduced typosquat (`reqeusts`) | `supply_chain.py` Levenshtein typosquatting check |
+| LLM-introduced backdoor | SAST + adversarial trio + zero-package-introduction conviction criterion |
+| Tampered audit trail | SHA-256 chain detects any post-hoc edit |
+| Webhook spoofing | HMAC-SHA256 with constant-time compare |
+| Secret leakage via logs | Secret scanner runs over diffs; `mcp_runtime.json` is in `/tmp` not the repo |
+| Subprocess sandbox escape | Runtime command allow-lists; optional bwrap; planned Firecracker |
+| Bug-bounty submission of duplicate finding | `cve_intel.py` correlation + manual approval default |
+| Auto-merge of an unsafe diff | 7 conviction criteria; default OFF; passes only the cleanest fixes |
+| Provider compromise (e.g., OpenRouter MITM) | TLS verification; provider chain falls back rather than blindly trusting bad responses |
+
+### 21.3 Secret hygiene
+- `mcp_config.json` is a **template** with `__INJECTED_BY_APP_AT_RUNTIME__`
+  placeholders. The realized config goes to `/tmp/mcp_runtime.json` which
+  is not committed and is recreated on each startup.
+- `.env`-style files are never read; everything goes through
+  `os.getenv`. HF Spaces / Docker `-e` are the only injection paths.
+- The disclosure vault uses Fernet with key derived from
+  `DISCLOSURE_VAULT_PASSPHRASE`. Lose that passphrase, lose the vault —
+  by design.
+
+---
+
+## 22. Migration Playbook — HF Space → Paid Server
+<a id="22-migration"></a>
+
+The Space is a great PoC environment but has hard limits: ephemeral
+storage on free tier, single-container topology, and shared GPU resources.
+The paid-server migration target is a single Linux box (DigitalOcean
+Droplet, Hetzner CCX, or AWS EC2) running the same Docker image.
+
+### 22.1 Pre-migration checklist
+- [ ] All env vars from §19 documented and stored in a secrets manager
+- [ ] `/data` directory size on Space measured (`du -sh /data`) and
+      provisioned on the new host (recommend ≥50 GB to start)
+- [ ] DigitalOcean Inference key budgeted for the expected request volume
+- [ ] Webhook secret rotated for the new endpoint URL
+- [ ] DNS or reverse-proxy plan in place if you want HTTPS in front of
+      ports 7860/7861/7862/7863
+- [ ] Decision made on Qdrant: keep SQLite/MiniLM (simpler) or stand up
+      a Qdrant container alongside (better recall on large corpora)
+
+### 22.2 Migration steps
+1. **Snapshot data.** On the Space:
+   ```bash
+   tar czf /tmp/rhodawk-data.tgz /data
+   ```
+   Download via the HF Spaces file browser or via git LFS.
+2. **Provision the new host.** Install Docker + Docker Compose. Mount a
+   block volume at `/var/lib/rhodawk-data`.
+3. **Restore data.**
+   ```bash
+   sudo mkdir -p /var/lib/rhodawk-data
+   sudo tar xzf rhodawk-data.tgz -C /var/lib/rhodawk-data --strip-components=1
+   ```
+4. **Build the image** (or pull from a private registry if you've pushed
+   one):
+   ```bash
+   git clone https://huggingface.co/spaces/Architect8999/rhodawk-ai-devops-engine
+   cd rhodawk-ai-devops-engine
+   docker build -t rhodawk:latest .
+   ```
+5. **Run with all env vars + persistent volume.**
+   ```bash
+   docker run -d --name rhodawk \
+     -p 7860:7860 -p 7861:7861 \
+     -v /var/lib/rhodawk-data:/data \
+     -e DO_INFERENCE_API_KEY=... \
+     -e OPENROUTER_API_KEY=... \
+     -e GITHUB_TOKEN=... \
+     -e RHODAWK_WEBHOOK_SECRET=... \
+     -e RHODAWK_TENANT_ID=acme \
+     -e RHODAWK_AUTO_MERGE=false \
+     -e RHODAWK_HARVESTER_ENABLED=true \
+     rhodawk:latest
+   ```
+6. **Update GitHub webhook** payload URL to the new host.
+7. **Verify the audit chain integrity** on the new host:
+   ```bash
+   docker exec rhodawk python -c \
+     "from audit_logger import verify_chain_integrity; verify_chain_integrity()"
+   ```
+8. **Run a known-failing-test repo** through the chat inbox or a webhook
+   to confirm end-to-end.
+
+### 22.3 Recommended additions on paid host
+- Reverse proxy (Caddy or Traefik) terminating TLS, fronting 7860/7861.
+- Docker Compose file checking the container into a restart-policy.
+- `cron` or systemd timer that runs `docker exec rhodawk python -m
+  mythos.diagnostics` every 5 minutes and pages on non-zero exit.
+- Off-host backup of `/var/lib/rhodawk-data` nightly. The training store
+  is the proprietary asset — losing it loses the moat.
+- Optional Qdrant container (`qdrant/qdrant:latest`) on a private network,
+  with `RHODAWK_EMBEDDING_BACKEND=qdrant` + `QDRANT_URL=http://qdrant:6333`.
+
+### 22.4 What changes at scale (later)
+- Move `job_queue` from SQLite to PostgreSQL (`psycopg2-binary` already
+  installed, see `mcp_config.json` postgres-intelligence server).
+- Move audit trail to S3 with versioning (the SHA-256 chain remains; only
+  the storage backend changes).
+- Replace single-host worker pool with a queue + worker fleet
+  (Redis/RQ or Celery).
+- Replace Gradio dashboard with a Next.js front-end calling the
+  `mythos.api.fastapi_server` JSON API.
+
+---
+
+## 23. Glossary of Internal Names
+<a id="23-glossary"></a>
+
+| Name | Meaning |
+|---|---|
+| **Aider** | Open-source AI pair-programming CLI, used as the patch generator |
+| **APIConnectionError** | Symbol that aider expects in `litellm`; missing in 1.75.0 — fixed by upgrading to 1.78.5 |
+| **ACTS** | Adversarial Consensus Trust Score (Hermes) |
+| **Audit chain** | The SHA-256-chained JSONL log in `audit_logger.py` |
+| **Architect** | Higher-order control package (`architect/`) — tier router, sandbox, skills, night mode |
+| **CEGIS** | Counterexample-Guided Inductive Synthesis (red team loop) |
+| **Conviction** | The 7-criteria gate that allows autonomous merge |
+| **DO** | DigitalOcean Serverless Inference (the new primary inference provider) |
+| **EmbodiedOS** | External persistent runtime that hosts OpenClaw + Hermes Agent (optional bridge) |
+| **Fork mode** | Forking any public repo and PR'ing back — enables fixing repos you don't own |
+| **Godmode consensus** | Stricter consensus (adversarial trio + Tier 1) used by night mode |
+| **Harvester** | Daemon that finds its own targets on GitHub |
+| **Hermes** | The 6-phase research orchestrator (`hermes_orchestrator.py`) |
+| **LoRA scheduler** | Daemon that exports successful (failure, fix) pairs as SFT JSONL |
+| **MCP** | Model Context Protocol — Anthropic's tool-server protocol |
+| **Mythos** | The deepest research package (`mythos/`) — multi-agent + RL + 17 native MCP servers |
+| **Mythos-level** | Aspirational target capability class — autonomous frontier vulnerability research |
+| **Night mode** | Autonomous bug-bounty loop running between human-driven audits |
+| **OpenClaw** | Local-gateway component of EmbodiedOS |
+| **OR** | OpenRouter (the new fallback inference provider) |
+| **PoC** | Proof of Concept (exploit) |
+| **Provider chain** | The ordered list `[DO_primary, OpenRouter_fallback]` consulted on every LLM call |
+| **Sandbox** | bwrap (or planned Firecracker) isolation for tool execution |
+| **SAST gate** | Static analysis security gate (bandit + semgrep + secret patterns) |
+| **Supply chain gate** | CVE + typosquatting check on newly added packages |
+| **Tier 1–5** | Five-tier model router classification |
+| **Training store** | SQLite DB of every fix attempt — the proprietary data asset |
+| **TVG** | Threat-Vector Graph |
+| **VES** | Vulnerability Evidence Score (Hermes) |
+| **Z3 gate** | Optional formal-verification gate using the Z3 SMT solver |
+
+---
+
+*Rhodawk AI — System Analysis Book*
+*Companion to `FOUNDER_PLAYBOOK.md` v4.0 (which remains the canonical investor narrative)*
+*Generated from the live source tree; last updated to reflect the DigitalOcean primary / OpenRouter fallback inference chain, the `--no-deps` aider install pattern, and the Docker-SDK Space configuration.*