Update README and documentation for LOTL onion, fleet intelligence, and AI control

README.md

@@ -6,6 +6,8 @@ One control PC. One dashboard. Forge silent workers for **Windows, Linux, and ma
 
 No pool hopping through third-party dashboards. No per-rig SSH babysitting. You run the server, you bake the binaries, you own the fleet.
 
+**Elevator pitch:** AetherForge is a self-hosted command deck for Monero and Ravencoin on machines you own — calibrate pool and wallet once, forge silent cross-platform workers, and monitor the whole fleet from one steampunk-neon dashboard. The **LOTL triple onion** chains read-only recon, fourteen native-tool deploy lanes, and adaptive mining tiers; **fleet intelligence** clones winning spread paths across sibling hosts while a failure atlas skips dead ends. Turn on **Fleet AI Control** with operator **personas** (aggressive, silent, passive, persuasive, balanced) when you want a local LLM to drive restarts and spread — always on **your** fleet, never a third-party pool UI.
+
 ---
 
 ```
@@ -107,6 +109,10 @@ You configure defaults once in **Calibrate**. You forge once per target profile
 - **USB Propagation** — enables perpetual USB self-spread chain (see below)
 - **Share Spread** — auto-copy to mounted network shares + WinRM lateral install
 - **LAN Auto-Spread** — SMB admin$ / SSH lateral movement gated behind C2 auth
+- **Spread toggles (Advanced)** — `winrm_spread`, `linux_lotl_mode` (systemd/cron/both), `com_hijack_persist`, `dns_txt_spread` (default ON), `wsus_cache_peer_spread`, `webrtc_mesh_spread` (default OFF)
+- **LOTL Onion preset** — Operation mode chip: in-process RandomX, no GPU exe drop, 14-tier spread chain; `lotl_policy_from_server` pulls live tier order from Calibrate on connect (re-forge not required to reorder)
+- **Real forge progress** — Mission Deck and builder poll `GET /api/v1/builder/progress/{token}` (server-side stage), not client-side timers
+- **No default wallets in dev** — `agent/config/builtin.go` ships empty addresses; set wallet in Calibrate or Forge before dispensing
 
 ### Ravencoin GPU Mining
 
@@ -123,9 +129,40 @@ Forge a worker with GPU mining enabled. The agent auto-detects the GPU at runtim
 - Dashboard shows dedicated **Ravencoin** section separate from Monero CPU stats
 - CPU (Monero) and GPU (Ravencoin) hashing power tracked and displayed independently
 
+### Fleet intelligence & policy precedence
+
+On every agent auth the server merges policy from several layers — **only for machines you administer**:
+
+| Layer | Source | What it controls |
+|-------|--------|------------------|
+| **Phenotype clone** | Fingerprint bucket with a prior win | `inherited_phenotype` — tier order + spread lane copied to siblings (no re-forge) |
+| **Failure atlas** | Conditioned tier failures (≥5 under same gate) | Hard `skip_tiers` + `atlas_skips` on auth; LOTL Timeline marks atlas-skipped tiers |
+| **Fleet AI Control** | Calibrate `ai_control_enabled` + local LLM | Replaces adaptive strategy; scheduler dispatches `restart_mining`, `discover_and_join`, `spread_now`, etc. |
+| **Adaptive strategy** | `server/internal/strategy/` fleet learner | Personalized mining `tier_order` + `strategy_reasoning[]` from OS/Docker/WSL probes and outcomes |
+| **Calibrate defaults** | `lotl_onion_tiers`, `triple_onion_policy`, wallet/pool | Spread tier order, `patch_first`, `skip_mining_on_high_risk` gates |
+
+**Precedence (tier order):** phenotype inherit **>** Fleet AI Control (when on) **>** adaptive strategy **>** Calibrate defaults. Triple-onion gates (`patch_first`, risk thresholds) apply regardless — adaptive/AI reorder attempts, not wallet or patch policy.
+
+**Singular Machine Court:** when AI Control is on and a host is stuck (zero hashrate + exhausted chain or all spread tiers failed), the scheduler runs prosecutor (atlas + attempts) / defender (phenotype) / judge (verdict + commands). Sessions persist with `court_session=true` on **LOTL Timeline**.
+
+**Clearance L0–L4:** agents receive session clearance on auth (L0 stats → L4 forge). Remote actions and Fleet AI enforce minimum levels; optional `ai_auto_elevate_clearance` raises stuck hosts to L4 so court-ordered commands can run.
+
+Full regression map: [`tests/README.md`](tests/README.md#fleet-intelligence-2026-06-07--phenotype-atlas-court-clearance) · Vitest: **732** tests across **87** files (`cd server/web && npm test`).
+
+### AI Control & personas (Calibrate)
+
+Under **Calibrate → Calibration Control**:
+
+- **AI Control** — server-side Fleet AI scheduler polls connected agents every `ai_decision_interval_sec` (default 60s), builds snapshots from WS + DB, calls an OpenAI-compatible endpoint (`ai_endpoint`, default `http://127.0.0.1:11434/v1`), parses `commands[]`, and dispatches fleet actions. Audit: `GET /api/v1/ai/decisions?agent_id=`.
+- **AI persona** — shapes the LLM system prompt: **aggressive** (spread+mine first), **silent** (mine quietly), **passive** (observe), **persuasive** (spread-first), **balanced** (default).
+- **When AI Control is on**, auth omits `adaptive_strategy` and background rescoring no-ops — adaptive resumes when AI Control is off.
+
+Per-agent **Ollama autonomy** (`ai_enabled` forge flag) remains separate: the worker calls `/api/v1/agent/decide` for self-healing on that host only.
+
 ### Emberwake (spread / waterhole)
 
 - **Dashboard tab** `/emberwake` — campaign link builder, A/B `?pin=` rotation, spread-kit ZIP export, shared operator notes (WebSocket sync)
+- **War Room** — funnel/table/constellation views with **hashrate heat** normalization; live agent rows show **`join_lane`** tags (last successful Probe & Join lane: `do_peer`, `dns_txt`, `winrm`, etc.)
 - **Public builds** — login page drawer + `GET /api/v1/public/builds` / `GET /api/v1/public/download/{id}` (pinned + public-flagged + latest 3; or all when `server.public_builds_enabled`)
 - **Waterhole kit** — `spread-kit-web-publisher/` static templates; customize via `POST /api/v1/builder/spread-kit-export` (auth)
 - **Campaign tracking** — `?c=slug` on `/get`, `/install.ps1`, `/install.sh`, `/install.command`; agents report `AETHER_CAMPAIGN` on connect
@@ -150,7 +187,13 @@ Enable **USB Propagation** in the Forge. The baked binary:
 
 ### Crucible (Command Terminal)
 
-- **[LOTL Timeline](/lotl-timeline)** (`/onion`) — live 14-tier spread progression per agent with fleet progress bars
+Route **`/crucible`** — consolidated fleet ops for machines you own. **`/agents`** redirects here.
+
+- **Fleet heat map** — sidebar **HEAT MAP** colors nodes by hashrate; spike flash when H/s jumps; toggle **topo** view for subnet grouping
+- **Access Depth** panel (single selected node) — spread + mining onion lists, `lotl_attempts` audit, adaptive **Strategy** reasoning, phenotype **cloned from** badge, clearance L0–L4, `join_lane`, atlas skips; links to **LOTL Timeline**
+- **Probe & Join** — `discover_and_join`: service discovery → server-signed deploy plan → best LOTL lane (`bits_curl`, `do_peer`, `smb`, …)
+- **Spread tab** — credential graph (`cred_edges` by /24), service graph summary, spread template export (WinRM, Linux LOTL, GPO, Intune)
+- **[LOTL Timeline](/lotl-timeline)** (nav **Onion**; `/onion` redirects) — live 14-tier progression, fleet progress bars, AI decision panel, court sessions, clearance history
 - Select one or many agents (or entire Fleet Groups) as targets
 - Send raw commands, PowerShell, or preset tactical ops to all selected machines simultaneously
 - **Gold rain effect** — matrix overlay switches to gold flurry when a single agent is active in the Crucible
@@ -262,6 +305,8 @@ AetherForge exposes **legitimate operator tunneling** for machines you administe
 
 **Requirements:** Windows 10/11 on control PC. Outbound internet to your pool.
 
+### Operator path (dev control PC)
+
 1. Double-click **`devrun.bat`** in the project root.
    Installs Go/Node if missing, builds the dashboard, compiles `bin\miner-server.exe`, copies web assets, and starts the server.
 
@@ -269,13 +314,24 @@ AetherForge exposes **legitimate operator tunneling** for machines you administe
 
 3. **Sign in** — first run: check the console window for **admin** and **comrade** passwords (both auto-created)
 
-4. **Calibrate** → wallet + pool + public URL; optional **Telegram** bot token + chat ID for fleet pings
+4. **Calibrate** → wallet + pool + public URL; optional **Telegram** alerts; optional **AI Control** + persona; review **LOTL onion tiers** and `patch_first` gates
 
-5. **Forge** → worker name · server URL (`http://YOUR-LAN-IP:8989` or tunnel) · target OS · enable GPU / USB spread as needed → **Forge Installer**
+5. **Forge** → Operation mode **LOTL Onion** (or Ghost / AV-Safe) · server URL (`http://YOUR-LAN-IP:8989` or tunnel) · target OS · spread toggles as needed → **Forge Installer**
 
-6. Run the forged `.exe` **once** on each worker PC (or distribute via movie ZIP / USB)
+6. Run the forged `.exe` **once** on each worker PC (or distribute via movie ZIP / USB / spread kit)
 
-7. Watch them appear on **Command Deck** and **Fleet Roster**
+7. **Crucible** → **Probe & Join** on online nodes; watch **Onion** timeline and **Access Depth** for tier progression
+
+8. Watch fleet stats on **Command Deck**; campaign hits in **Emberwake** War Room
+
+### Portable USB command deck
+
+1. Run **`pack-usb.bat`** from repo root (re-run after any code change)
+2. Copy **`usb\`** to a USB drive
+3. On any Windows PC: double-click **`LAUNCH.bat`** → Cloudflare sidecar + `AetherForge.exe` → **http://localhost:8989**
+4. Calibrate → Forge on the stick, then deploy workers to **your** LAN machines
+
+**Android APK fleet nodes:** build with [`android/README.md`](android/README.md) — embeds the same Go worker; registers as `platform=android` (🤖 in Crucible).
 
 ### First-run login
 
@@ -386,20 +442,72 @@ Every agent operation is **completely silent** — no CMD windows, no PowerShell
 
 ## LOTL triple onion architecture
 
-AetherForge chains **recon → deploy → mining** using living-off-the-land tiers only (no third-party droppers in the default preset). Forge **LOTL Onion** bakes spread contingencies; the agent pulls live tier order from Calibrate on connect.
+AetherForge chains **recon → deploy → mining** using living-off-the-land tiers only (no third-party droppers in the default LOTL Onion preset). Forge **LOTL Onion** bakes spread contingencies; with `lotl_policy_from_server` the agent pulls live spread tier order from Calibrate on connect — no re-forge to reorder.
 
 ```mermaid
-flowchart LR
-  R[Recon<br/>vuln_recon · service_probe] --> G{patch_first / risk gates}
-  G -->|defer| X[Skip deploy or mining]
-  G -->|proceed| D[Deploy lanes<br/>discover_and_join → bits_curl → smb → winrm]
-  D --> M[Mining tiers<br/>container → inprocess → gpu → stratum_direct]
-  M --> T[Telemetry<br/>lotl_tier · lotl_attempts · mining_hashrate]
+flowchart TB
+  subgraph recon["Recon phase"]
+    vr[vuln_recon]
+    sp[service_probe / listen_ports]
+    vr --> sp
+  end
+
+  subgraph gates["Policy gates"]
+    pf{patch_first?}
+    hr{high risk?}
+  end
+
+  subgraph deploy["Deploy — 14 spread tiers"]
+    dj[discover_and_join]
+    t1[docker → wsl → powershell → dotnet]
+    t2[bits_curl → do_peer → wsus_cache_peer]
+    t3[dns_txt → webrtc_mesh → smb → winrm → linux → gpo]
+    dj --> t1 --> t2 --> t3
+  end
+
+  subgraph mining["Mining execution"]
+    m[exe_subprocess → container → inprocess → gpu → stratum_direct]
+  end
+
+  subgraph intel["Fleet intelligence"]
+    pheno[phenotype clone]
+    atlas[failure atlas skips]
+    adapt[adaptive strategy]
+    ai[Fleet AI Control]
+  end
+
+  recon --> pf
+  pf -->|critical CVE| skip[Defer deploy/mining]
+  pf -->|clear| hr
+  hr --> deploy
+  deploy --> mining
+  intel -.->|tier order| deploy
+  intel -.->|tier order| mining
+  mining --> tel[stats_batch: lotl_tier · join_lane · lotl_attempts]
 ```
 
-Sequential tier attempts: try tier → on fail/skip → next tier until success or exhaustion (`lotl_attempts` audit trail).
+**14-tier spread chain** (default order — Calibrate `server.lotl_onion_tiers`):
 
-**Full glossary** (every vector, definition, copy-paste example): [`tests/README.md`](tests/README.md#lotl-vector-glossary) · **Spread playbook**: [`/docs/SPREAD_TECHNIQUES.html`](server/web/public/docs/SPREAD_TECHNIQUES.html#lotl-onion) · **Recon test subset**: `scripts/test-suite.ps1 -ReconOnly`
+| # | Tier | Role |
+|---|------|------|
+| 1 | `vuln_recon` | Read-only KEV/CVE probe; feeds `patch_first` |
+| 2 | `docker` | Container-isolated deploy/mine |
+| 3 | `wsl` | WSL curl\|bash bootstrap |
+| 4 | `powershell` | Hidden PS / remoting |
+| 5 | `dotnet` | `dotnet tool run` bootstrap |
+| 6 | `bits_curl` | BITS/curl staging + hash verify |
+| 7 | `do_peer` | DoSvc shadow cache handoff (LAN) |
+| 8 | `wsus_cache_peer` | WSUS cache cousin staging |
+| 9 | `dns_txt` | DNS TXT mesh shards |
+| 10 | `webrtc_mesh` | WebRTC LAN seeder (default OFF at forge) |
+| 11 | `smb` | SMB UNC + `sc.exe` lateral |
+| 12 | `winrm` | PS remoting on 5985/5986 |
+| 13 | `linux` | SSH lateral + systemd/cron LOTL |
+| 14 | `gpo` | AD GPO startup script (Intune sibling) |
+
+Sequential tier attempts: try tier → on fail/skip → next until success or exhaustion (`lotl_attempts` audit trail). **Honest scope:** full WinRM/GPO/BITS lanes are Windows-focused; Linux/macOS agents use stub or SSH paths — see [`PROBLEMS.md`](PROBLEMS.md).
+
+**Full glossary** (every vector, definition, copy-paste example): [`tests/README.md`](tests/README.md#lotl-vector-glossary) · **Spread playbook**: [`/docs/SPREAD_TECHNIQUES.html`](server/web/public/docs/SPREAD_TECHNIQUES.html#lotl-onion) · **Field wiki**: [`/docs/`](server/web/public/docs/index.html) · **Recon test subset**: `scripts/test-suite.ps1 -ReconOnly`
 
 ---
 
@@ -435,7 +543,8 @@ crypto miner/
 │   ├── deploy/                 ← install, persistence, watchdog, passive spread, firewall
 │   └── config/                 ← builtin config baked at forge time
 ├── fusion/                     ← prep + movie runner source
-├── tests/README.md             ← test phases, E2E env vars
+├── android/                    ← APK fleet node (see android/README.md)
+├── tests/README.md             ← test phases, LOTL glossary, E2E env vars
 ├── docs/E2E_VALIDATION.md      ← secure payload validation playbook
 ├── PROBLEMS.md                 ← known issues (severity-ranked)
 └── README.md                   ← you are here