docs: detailed white-box & grey-box instructions (TUTORIAL + README + /help)

- TUTORIAL 5.2 white-box: how source review works (context collection, agent
  selection, source→sink dataflow, file:line symbolic grounding, validation),
  examples and tips.
- TUTORIAL 5.3 grey-box: code review leads → live exploitation flow, auth via
  creds.yaml, MCP, REPL repo+target = greybox.
- README quick-start gains white-box / grey-box / host one-liners + tutorial link.
- REPL /help shows the MODES line (black/white/grey/host) and Ctrl-O hint.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

README.md

@@ -120,11 +120,24 @@ neurosploit
 # or one-liner (subscription login, no API key needed):
 neurosploit run http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 -v
 
+# white-box — review a source repository (SAST agents, file:line evidence):
+git clone https://github.com/digininja/DVWA /tmp/DVWA
+neurosploit whitebox /tmp/DVWA --subscription --model anthropic:claude-opus-4-8 -v
+
+# grey-box — review the code AND exploit the running app together:
+neurosploit greybox /tmp/DVWA --url http://localhost:8080/ --creds creds.yaml \
+  --subscription --model anthropic:claude-opus-4-8 --mcp -v
+
+# host / infra — Linux / Windows / Active Directory (SSH/Win creds in creds.yaml):
+neurosploit host 10.0.0.10 --creds creds.yaml --subscription --model anthropic:claude-opus-4-8 -v
+
 # 🛰  Mission Control TUI — live panels (header/feed/findings/targets) + a composer
 #    you can type in WHILE the run streams (summary · pause · errors · notes):
 neurosploit tui http://testphp.vulnweb.com/ --subscription --model anthropic:claude-opus-4-8 --mcp
 ```
 
+> Full step-by-step for every mode (black/white/grey/host) is in **[TUTORIAL.md](TUTORIAL.md)**.
+
 No login? Use an **API key** instead — see [Authentication](#authentication--run-via-api-key-or-subscription).
 
 ---

TUTORIAL.md

@@ -188,24 +188,72 @@ neurosploit run http://testphp.vulnweb.com/ \
 
 ### 5.2 White-box (source repo)
 
+Reviews a **local code repository** with the 78 source-review (SAST) agents:
+SQLi, command injection, SSRF, XSS, path traversal, insecure deserialization,
+hardcoded secrets, weak crypto, auth/IDOR, XXE, SSTI, language-specific sinks
+(PHP/Java/.NET/Go/Node/Python), and more.
+
 ```bash
+# 1. clone or point at the code you own
 git clone https://github.com/digininja/DVWA /tmp/DVWA
+
+# 2. review it (subscription or --model with an API key)
 neurosploit whitebox /tmp/DVWA --subscription --model anthropic:claude-opus-4-8 -v
+
+# focus a specific class, cap agents, raise the voting bar:
+neurosploit whitebox /tmp/DVWA --focus "injection and access control" \
+  --max-agents 8 --vote-n 2 --model openai:gpt-5.5
 ```
 
-Findings carry `file:line` evidence; grounding is **symbolic** (the location must
-exist in the reviewed source).
+**How it works**
+
+1. **Collects source context** — walks the repo (skips `.git/node_modules/target/
+   vendor`), reads supported source files into a bounded review context.
+2. **Selects code agents** for the languages/frameworks it sees.
+3. Each agent traces **source → sink** dataflow and must quote the **exact
+   vulnerable lines as `file:line`**.
+4. **Grounding is symbolic**: a finding is only kept if its `file:line` / quoted
+   code actually exists in the reviewed source (no hallucinated locations).
+5. **Validated** by cross-model voting, then reported with the code reference,
+   CWE/OWASP, PoC and remediation.
+
+**Tips**
+- No `--mcp` is used in white-box (there's no live app to browse).
+- For huge repos, narrow with `--focus` or point at a subdirectory.
+- Each finding's `endpoint` field is the `file:line`; `evidence` quotes the code;
+  `payload` is the PoC / vulnerable snippet — view it all with `/finding`.
 
 ### 5.3 Grey-box (code + live app)
 
-Best of both: review the source **and** prove issues against the running app —
-code findings become *leads* for live exploitation.
+The strongest mode: review the **source** *and* exploit the **running app**
+together. Code-review findings become **leads** that the live agents confirm
+against the deployed application (so a SQLi spotted in code is proven exploitable
+on the running endpoint).
 
 ```bash
+# code repo + the URL where that code is actually running
 neurosploit greybox /tmp/DVWA --url http://localhost:8080/ \
-  --creds creds.yaml --focus "auth and IDOR" --subscription --model anthropic:claude-opus-4-8 -v
+  --creds creds.yaml --focus "auth and IDOR" \
+  --subscription --model anthropic:claude-opus-4-8 --mcp -v
 ```
 
+**How it works**
+
+1. **Recon** the live app (`--url`).
+2. **Review the source** with the code agents → produces a list of *leads*
+   (suspected vulns with file:line).
+3. **Live exploitation** runs with those leads injected as context, so agents go
+   straight for the proven-in-code weaknesses and **prove them on the live app**
+   (empirical receipt: real request/response).
+4. Validate (cross-model) → chain → report.
+
+**Notes**
+- Pass `--creds creds.yaml` so agents test **authenticated** flows (login / JWT /
+  cookie) — essential for IDOR/BOLA/auth findings.
+- `--mcp` enables the Playwright browser for client-side proof (e.g. XSS firing).
+- In the REPL: set **both** `/repo <path>` and `/target <url>` → grey-box is
+  auto-selected; `/show` displays `mode: greybox (code + live)`.
+
 ### 5.4 Host / Infra (Linux / Windows / AD)
 
 Target an IP/host with SSH or Windows/AD credentials from `creds.yaml`:

neurosploit-rs/app/src/repl.rs

@@ -948,7 +948,8 @@ fn help() {
     h("/votes <n>",         "validator votes           /agents <n>  cap agents");
     h("/theme color|mono",  "/show (config)            /clear        /quit");
 
-    println!("\n  \x1b[2m↑/↓ history · Tab completes commands & @paths · Ctrl-A/E/K edit · \\ for multiline\x1b[0m\n");
+    println!("\n  \x1b[2mMODES — black-box: set /target · white-box: set /repo · grey-box: set BOTH /repo + /target · host: /target <ip> + /creds\x1b[0m");
+    println!("  \x1b[2m↑/↓ history · Tab completes commands & @paths · Ctrl-A/E/K edit · Ctrl-O full cmd · \\ for multiline\x1b[0m\n");
 }
 
 /// Scan a line for @path tokens, attach each referenced file/dir to context.