docs: plain-language pass -- README, index, where we stand, scanning, examples, threat model

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Claude-Session: https://claude.ai/code/session_01EmM1j46qgKMh3zqD1QMwEo

docs/examples.md

@@ -1,7 +1,7 @@
 # End-to-end examples
 
-Each example is self-contained. Artifacts land under
-`<target>/.openultrasast/runs/<scan-id>/` and `.openultrasast/` is gitignored.
+Each example stands on its own. Artifacts land under `<target>/.openultrasast/runs/<scan-id>/`.
+`.openultrasast/` is gitignored.
 
 ## 1. Quick scan a local repo (deterministic, no keys)
 
@@ -21,7 +21,7 @@ ousast scan . --mode standard       # Joern model layer, container network off:
 ousast-with-judge scan . --mode standard   # network on, so the model is asked (needs DEEPSEEK_API_KEY)
 ```
 
-Without a key the graph still decides: its entailed findings are reported, and the LLM's residual
+Without a key, the graph still decides. Its entailed findings are reported. The LLM's residual
 and suspicion questions go unasked.
 
 ## 3. CI gate
@@ -52,10 +52,11 @@ uv run ousast pairs --split holdout --profile human   # filter by declared split
 uv run python -m openultrasast.pair_gate         # CI: local pairs must all pass
 ```
 
-Each case is two isolated trees (vuln file vs patched file, same relative path).
-`pair_correct` means the harness fired on the vuln side and stayed silent on the
-fix. Misses and fix-side leaks become `miss`/`fp` signals for `ousast improve`.
-The catalog and public dataset pointers live in `benchmarks/pairs/`.
+Each case is two isolated trees: the vuln file and the patched file, at the same relative path.
+
+- `pair_correct` means the harness fired on the vuln side and stayed silent on the fix.
+- Misses become `miss` signals and fix-side leaks become `fp` signals for `ousast improve`.
+- The catalog and public dataset pointers live in `benchmarks/pairs/`.
 
 ## 6. Self-improve the ruleset from benchmark feedback
 
@@ -68,10 +69,11 @@ uv run ousast improve benchmarks/manifests/java-spring-boot-vulnerable.toml
 
 ## 7. Running the agentic plane
 
-Model work over whole repositories runs as a Run manifest on ax, one isolated actor
-per task (bring-up: [ops/ax/README.md](ops/ax/README.md)). The provider key is
-read from the environment (or `.env`, which never overrides an exported variable) by
-`ousast` and sent only in each task's start request.
+Model work over whole repositories runs as a Run manifest on ax. Each task gets one isolated
+actor. Bring-up is in [ops/ax/README.md](ops/ax/README.md).
+
+`ousast` reads the provider key from the environment, or from `.env`. `.env` never overrides an
+exported variable. The key is sent only in each task's start request.
 
 ```bash
 uv run ousast plane doctor                               # kind, Agent Substrate, ax controller, runner image
@@ -83,16 +85,25 @@ uv run ousast plane remember validation-46               # re-ingest the run's m
 uv run ousast improve benchmarks/manifests/java-spring-boot-vulnerable.toml --dry-run --memory
 ```
 
-Each task in the Run carries its own Model and `budget: {usd, calls}`; a task that
-reaches its ceiling stops as `unfinished` and resumes on a rerun with a larger
-budget. `ousast plane status` prints the token attribution table: calls, prompt,
-cache-hit and output tokens and USD per task.
+Each task in the Run carries its own Model and `budget: {usd, calls}`.
+
+- A task that reaches its ceiling stops as `unfinished`. It resumes on a rerun with a larger
+  budget.
+- `ousast plane status` prints the token attribution table. It shows calls, prompt, cache-hit and
+  output tokens, and USD per task.
 
 ## 8. Drive it from an MCP client (OpenCode / IDE)
 
+MCP (Model Context Protocol) lets an editor or agent call the tool's functions.
+
 ```jsonc
 { "command": "uv", "args": ["run", "ousast", "mcp"] }
 ```
 
-Then: `openultrasast.scan {path}` → `run_dir` → `openultrasast.findings {run_dir}` →
-`openultrasast.explain {run_dir, finding_id}`. See the README section "Agent integrations".
+Then call the tools in this order:
+
+1. `openultrasast.scan {path}` returns a `run_dir`.
+2. `openultrasast.findings {run_dir}` lists the findings.
+3. `openultrasast.explain {run_dir, finding_id}` explains one.
+
+See the README section "Agent integrations".