pwn 0.5.628 → 0.5.629

data/documentation/Installation.md

@@ -1,73 +1,237 @@
 # Installation
 
-PWN is tested on **Debian-based Linux** (Kali, Ubuntu) and **macOS**, using
-Ruby via **RVM**.
+PWN ships as a **single Ruby gem** whose runtime is 100 % `autoload`ed —
+a plugin whose native extension or OS binary is missing costs nothing until
+you actually touch that constant. That means the install is **two steps**:
+
+```bash
+gem install pwn      # 1. get the gem (pure-Ruby core always works)
+pwn setup            # 2. doctor + provision this host's capabilities
+```
+
+`pwn setup` is the built-in **doctor / provisioner** (`PWN::Setup`). It
+detects your OS package manager (`apt` · `dnf` · `pacman` · `brew` · `port`),
+reports which `PWN::` capabilities are usable on *this* host, and — when
+asked — installs exactly the OS headers, external tools, and native gems
+needed to unlock the ones you want. No `/opt/pwn` checkout, no `rvmsudo`
+chain, no bash provisioners required.
+
+Tested on **Kali / Debian / Ubuntu**, **Fedora**, **Arch**, and **macOS**
+(Homebrew or MacPorts). Ruby ≥ 3.4 (RVM, rbenv, asdf, or system Ruby).
+
+---
 
 ## Quick install (recommended)
 
 ```bash
-cd /opt
-sudo git clone https://github.com/0dayinc/pwn
-cd /opt/pwn
-./install.sh          # system deps (nmap, chromium, graphviz, …)
-./install.sh ruby-gem # rvm gemset + bundle install + rake install
-pwn                   # launch the REPL
+gem install pwn
+pwn setup                      # read-only doctor: what's usable, what's missing
+pwn setup --profile full --yes # install everything for every PWN:: namespace
+pwn                            # launch the REPL
+```
+
+```text
+pwn[v0.5.628]:001 >>> PWN.help
+```
+
+If you only need a subset (e.g. web testing on a CI runner, SDR on a lab
+box), install just that **capability profile** — see below.
+
+---
+
+## `pwn setup` — the post-install doctor & provisioner
+
+Three equivalent spellings ship with the gem:
+
+| Invocation | Same as |
+|---|---|
+| `pwn setup [opts]` | bare-word subcommand of `bin/pwn` |
+| `pwn_setup [opts]` | standalone driver (`bin/pwn_setup`) |
+| `pwn --setup[=PROFILE]` | flag form; no `PROFILE` = check, `PROFILE` = deps |
+
+### Read-only doctor (default)
+
+```bash
+$ pwn setup            # or: pwn setup --check   / pwn --setup / pwn_setup
+```
+
+Prints a per-capability report and **exits non-zero if anything is degraded**
+(so you can gate CI on it):
+
+```text
+PWN v0.5.628 · ruby 4.0.5 · linux x86_64 · pkg-manager: apt
+
+~/.pwn/                    ok   (11 entries)
+~/.pwn/pwn.yaml            ok   (encrypted, decryptor present)
+AI engine                  ok   anthropic (key set)
+
+Ruby extensions
+  pg             MISSING  (needs: postgresql-server-dev-all)  → PWN::Plugins::DAOPostgres
+  pcaprub        ok                                            → PWN::Plugins::Packet, extro_packet
+  nokogiri       ok                                            → PWN::Plugins::TransparentBrowser, PWN::WWW
+  …
+
+External toolchain                              used by
+  nmap           ok    /usr/bin/nmap            PWN::Plugins::NmapIt
+  gqrx           MISSING                        PWN::SDR, extro_rf_tune
+  …
+
+31 / 36 capabilities usable · 5 degraded
+
+Run `pwn setup --deps` to install missing OS headers/tools, or
+    `pwn setup --profile <name>` for a subset. See `pwn setup --list-profiles`.
+```
+
+### Install dependencies
+
+```bash
+pwn setup --deps                     # profile :full — everything
+pwn setup --profile web              # just TransparentBrowser · Burp · ZAP · Tor
+pwn setup --profile sdr --yes        # non-interactive (CI / packer / docker)
+pwn setup --profile net --dry-run    # print the apt/dnf/brew/… commands only
+pwn setup --list-profiles
 ```
 
+`--deps` / `--profile` will:
+
+1. Resolve the profile → set of native gems + external binaries.
+2. Map those to OS packages for **your** package manager (data lives in
+   `PWN::Setup::NATIVE_GEMS` / `::TOOLCHAIN` — versioned with the gem, so
+   `gem install pwn`, git checkout, Docker, Packer and Vagrant all read the
+   same table).
+3. Show the exact commands, prompt (unless `--yes`), run them, then
+   `gem pristine` / `gem install` any native extension that still fails to
+   load, and re-run the doctor.
+
+### Capability profiles
+
+`pwn setup --list-profiles` (source of truth: `PWN::Setup::PROFILES`)
+
+| Profile | Unlocks |
+|---|---|
+| `core` | `~/.pwn` bootstrap · vault · REPL — always applied |
+| `ai` | verify at least one AI engine key/oauth in `~/.pwn/pwn.yaml` |
+| `web` | `TransparentBrowser` · `BurpSuite` · `Zaproxy` · `extro_verify` · `extro_watch` · `sqlmap` · `tor` |
+| `net` | `NmapIt` · `Packet` · `extro_packet` · `extro_osint` · `tshark`/`tcpdump` |
+| `db` | `DAOPostgres` · `DAOSqlite3` · `DAOMongo` |
+| `sdr` | `PWN::SDR` · GQRX · `PWN::FFI` DSP backends · `extro_rf_tune` · rtl-sdr / hackrf / SoapySDR |
+| `vision` | `OCR` · `ScannableCodes` · `Reports` · `extro_vision` · tesseract / zbar / graphviz |
+| `voice` | `PWN::Plugins::Voice` · `extro_voice` · espeak-ng / sox |
+| `exploit` | `Metasploit` · `sqlmap` |
+| `hardware` | `Serial` · `BusPirate` · `Android` · `BareSIP` · `extro_serial` · `extro_telecomm` |
+| `full` | everything above |
+
+### All flags
+
 ```text
-pwn[v0.5.616]:001 >>> PWN.help
+pwn setup [--check] [--deps] [--profile NAME] [--list-profiles]
+          [--yes] [--dry-run]
 ```
 
-## Gem-only install
+| Flag | Meaning |
+|---|---|
+| *(none)* / `-c`, `--check` | Read-only doctor. Exit 1 if any capability degraded. |
+| `-d`, `--deps` | Install OS packages + rebuild native gems for `--profile` (default `full`). |
+| `-p`, `--profile NAME` | One of the profiles above. Implies `--deps`. |
+| `-l`, `--list-profiles` | Print profile table and exit. |
+| `-y`, `--yes` | Assume yes; non-interactive (CI / Docker / Packer). |
+| `-n`, `--dry-run` | Print the commands that *would* run, do nothing. |
+
+---
+
+## From a git checkout (contributors)
 
 ```bash
-rvm install ruby-4.0.5
-rvm use     ruby-4.0.5@pwn --create
-gem install --verbose pwn
-pwn
+git clone https://github.com/0dayinc/pwn /opt/pwn
+cd /opt/pwn
+bundle install
+rake install                         # or: rvmsudo rake install (multi-user RVM)
+pwn setup --profile full --yes       # same provisioner, same data tables
 ```
 
+The legacy `./install.sh` / `packer/provisioners/pwn.sh` bash paths still
+work, but they now simply delegate to `pwn setup` — the `case $os` package
+lists have been consolidated into `PWN::Setup::NATIVE_GEMS` / `::TOOLCHAIN`.
+
+---
+
+## Docker / Packer / Vagrant / CI
+
+`pwn setup` is the single provisioning entry point for every image builder:
+
+```dockerfile
+FROM kalilinux/kali-rolling
+RUN gem install pwn && pwn setup --profile full --yes
+```
+
+```yaml
+# .gitlab-ci.yml — fail the job if the runner is missing a capability
+before_script:
+  - pwn setup --profile web --yes
+  - pwn setup --check
+```
+
+```bash
+# packer / vagrant provisioner
+pwn setup --profile ${PWN_PROFILE:-full} --yes
+```
+
+---
+
 ## Upgrading
 
 ```bash
-rvm use ruby-4.0.5@pwn
-gem uninstall --all --executables pwn
-gem install --verbose pwn
+gem update pwn         # or: gem uninstall --all --executables pwn && gem install pwn
+pwn setup              # re-doctor — new versions may add capabilities
 ```
 
-or from a checkout:
+From a checkout:
 
 ```bash
-cd /opt/pwn && git pull && rvmsudo rake install
+cd /opt/pwn && git pull && rake install && pwn setup
 ```
 
+---
+
 ## First-run configuration
 
-`pwn` creates `~/.pwn/` on first launch. Add at least one LLM engine to
-`~/.pwn/config.yml` to enable `pwn-ai` — see [Configuration](Configuration.md).
+The first `pwn` launch creates `~/.pwn/` and an **encrypted**
+`~/.pwn/pwn.yaml` template. Add at least one LLM engine key with the
+`pwn-vault` REPL command to enable `pwn-ai` — see
+[Configuration](Configuration.md). `pwn setup` will report the AI-engine
+row as `MISSING` until a key is set.
 
-## Optional external tools
+---
 
-PWN wraps these when present on `$PATH`; none are hard requirements:
+## Programmatic API — `PWN::Setup`
 
-| Tool | Used by |
-|---|---|
-| `nmap` | `PWN::Plugins::NmapIt` |
-| Burp Suite Pro (+ REST API) | `PWN::Plugins::BurpSuite` |
-| `msfconsole` / msfrpcd | `PWN::Plugins::Metasploit` |
-| `chromium` / `google-chrome` | `PWN::Plugins::TransparentBrowser` |
-| `zaproxy` | `PWN::Plugins::Zaproxy` (fallback) |
-| `gqrx` | `PWN::SDR::GQRX` |
-| `adb` | `PWN::Plugins::Android` |
-| `graphviz` (`dot`) | rebuilding these diagrams |
-| `tor` | `PWN::Plugins::Tor` |
+Everything above is a thin CLI over one autoloaded module:
+
+```ruby
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, pkg_manager:, os:, arch: }
+PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
+PWN::Setup.list_profiles
+PWN::Setup.pkg_manager                    # → { key: :apt, install: 'sudo apt-get install -y', sudo: true }
+
+# The data tables — single source of truth, versioned with the gem:
+PWN::Setup::NATIVE_GEMS   # native ext  → { apt:, dnf:, pacman:, brew:, port:, plugins: }
+PWN::Setup::TOOLCHAIN     # external bin → { apt:, dnf:, pacman:, brew:, port:, plugins: }
+PWN::Setup::PROFILES      # profile      → { desc:, gems:, bins: }
+```
+
+Adding a new native dependency or wrapped binary? Add **one row** to the
+appropriate constant in `lib/pwn/setup.rb` — every install path (gem, git,
+Docker, Packer, Vagrant, CI) picks it up automatically.
+
+---
 
 ## Verify
 
 ```ruby
-pwn[v0.5.616]:001 >>> PWN::Plugins.constants.count   # => 66
-pwn[v0.5.616]:002 >>> PWN::SAST.constants.count      # => 48
-pwn[v0.5.616]:003 >>> pwn-ai                         # launches agent TUI
+pwn[v0.5.628]:001 >>> PWN::Setup.check[:ok]          # => true
+pwn[v0.5.628]:002 >>> PWN::Plugins.constants.count   # => 66
+pwn[v0.5.628]:003 >>> PWN::SAST.constants.count      # => 48
+pwn[v0.5.628]:004 >>> pwn-ai                         # launches agent TUI
 ```
 
 **Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md)

data/documentation/Metasploit.md

@@ -3,10 +3,13 @@
 RPC client for `msfrpcd` — search modules, set options, run exploits, interact
 with sessions, all from Ruby.
 
+> **Install:** `pwn setup --profile exploit` — metasploit-framework ·
+> sqlmap. See [Installation](Installation.md).
+
 ## Configure
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml  (edit via `pwn-vault`)
 metasploit:
   host: 127.0.0.1
   port: 55553

data/documentation/NmapIt.md

@@ -4,6 +4,9 @@ Thin, composable wrapper over `nmap` with structured XML parsing.
 
 ![Network & infra testing](diagrams/network-infra-testing.svg)
 
+> **Install:** `pwn setup --profile net` — nmap · tshark · tcpdump ·
+> pcaprub headers · whois. See [Installation](Installation.md).
+
 ```ruby
 r = PWN::Plugins::NmapIt.port_scan(
   target: '10.0.0.0/24',

data/documentation/Persistence.md

@@ -6,12 +6,15 @@ Every byte PWN remembers between processes lives here.
 
 | Path | Owner | Format | Reset tool | Purpose |
 |---|---|---|---|---|
-| `config.yml` | `PWN::Config` | YAML | edit by hand | engines, keys, agent options |
+| `pwn.yaml` | `PWN::Config` · `PWN::Plugins::Vault` | AES-encrypted YAML | `pwn-vault` | engines, keys, agent options |
+| `pwn.yaml.decryptor` | `PWN::Plugins::Vault` | key/IV | — | decrypts `pwn.yaml` (or set `PWN_DECRYPTOR_KEY`/`_IV`) |
 | `memory.json` | `PWN::Memory` | JSON array | `memory_clear` | facts · prefs · lessons · env — injected into every prompt |
+| `memory.idx` | `PWN::MemoryIndex` | JSON `{key → {sha,vec}}` | `PWN::MemoryIndex.reset` | local embedding index over `memory.json` — powers **relevance-ranked** MEMORY injection (incremental; only re-embeds changed entries) |
+| `finetune/*.jsonl` | `PWN::AI::Agent::Learning.export_finetune` | ShareGPT / OpenAI JSONL | `rm` | supervised dataset cut from every successful session — feed to a LoRA over the local model |
 | `skills/*.md` | `PWN::Config.load_skills` | Markdown + YAML front-matter | `skill_delete` | reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST) |
 | `learning.jsonl` | `PWN::AI::Agent::Learning` | JSON-per-line | `learning_reset` | task outcome log → success_rate |
 | **`mistakes.json`** | **`PWN::AI::Agent::Mistakes`** | **JSON `{sig → entry}`** | **`mistakes_reset`** | **failure fingerprints · cross-session count · fix · `[REPEATING]` · `[REGRESSED]`** |
-| `metrics.json` | `PWN::AI::Agent::Metrics` | JSON | `metrics_reset` | per-tool calls · success · avg_duration · last_error |
+| `metrics.json` | `PWN::AI::Agent::Metrics` | JSON | `metrics_reset` | per-tool calls · success · avg_duration · last_error · **per-engine** sub-buckets |
 | `extrospection.json` | `PWN::AI::Agent::Extrospection` | JSON | `extro_reset` | host/net/toolchain/repo/env/**rf**/**web** snapshot + previous baseline + observations[] |
 | `extrospection/web/*.png` | `PWN::AI::Agent::Extrospection` | PNG | `rm -rf` | headless-browser screenshots from `probe_web` / `extro_watch` (opt-in) |
 | `sessions/*.jsonl` | `PWN::Sessions` | JSON-per-line | `sessions_delete` | full transcript per pwn-ai run |

data/documentation/Reporting.md

@@ -2,6 +2,9 @@
 
 ![Reporting pipeline](diagrams/reporting-pipeline.svg)
 
+> **Install:** `pwn setup --profile vision` — imagemagick · graphviz ·
+> rmagick / gruff headers. See [Installation](Installation.md).
+
 ## Generators  (`lib/pwn/reports/*.rb`)
 
 | Module | Consumes | Emits |

data/documentation/SDR.md

@@ -2,6 +2,10 @@
 
 ![SDR flow](diagrams/sdr-radio-flow.svg)
 
+> **Install:** `pwn setup --profile sdr` — GQRX · rtl-sdr · hackrf ·
+> SoapySDR · multimon-ng · sox · libsndfile · libusb. See
+> [Installation](Installation.md).
+
 ## Modules  (`lib/pwn/sdr/*.rb`)
 
 | Module | Purpose |

data/documentation/Skills-Memory-Learning.md

@@ -10,27 +10,38 @@ its own performance, turns wins into permanent capability, and — critically
 
 | Store | File | Write tool | Read tool | Injected as |
 |---|---|---|---|---|
-| **Memory** | `memory.json` | `memory_remember` | `memory_recall` | `MEMORY` block — durable facts / prefs / lessons / env |
+| **Memory** | `memory.json` (+ `memory.idx`) | `memory_remember` | `memory_recall` · `PWN::MemoryIndex.recall_semantic` | `MEMORY` block — durable facts / prefs / lessons / env. **Relevance-ranked** for the current request via a local embedding index when `ai.ollama.embed_model` is available; falls back to newest-first otherwise. |
 | **Skills** | `skills/*.md` | `skill_create` · `learning_distill_skill` | `skill_list` · `skill_view` | `SKILLS` list — reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST/URL) |
-| **Learning** | `learning.jsonl` | `learning_note_outcome` · `learning_reflect` | `learning_outcomes` · `learning_stats` | `LEARNING` block — recent outcomes + success_rate |
+| **Learning** | `learning.jsonl` | `learning_note_outcome` · `learning_reflect` | `learning_outcomes` · `learning_stats` · `Learning.exemplars_for` | `LEARNING` block — recent outcomes + success_rate. Prior *successful* traces are also spliced in as **few-shot exemplars** for local models. |
 | **Mistakes** | `mistakes.json` | `mistakes_record` · `mistakes_resolve` · *auto on failure* | `mistakes_list` | `KNOWN MISTAKES` + `KNOWN FIXES` blocks — do-NOT-repeat + do-THIS-instead |
-| **Metrics** | `metrics.json` | *automatic* (every Dispatch) | `metrics_summary` | `TOOL EFFECTIVENESS` block — steer tool choice |
+| **Metrics** | `metrics.json` | *automatic* (every Dispatch) | `metrics_summary` | `TOOL EFFECTIVENESS` block — steer tool choice. **Segmented per engine** (`engine=…`) so a local model's telemetry never blends with a frontier model's. |
 
 ## The lifecycle of a lesson
 
 ```text
-1. Dispatch runs a tool              → Metrics.record(tool, ok?, ms)
+1. PromptBuilder.budget picks per-engine caps → MemoryIndex.recall_semantic
+     picks the N MOST-RELEVANT memories for THIS request (not the N newest).
+2. (local model) Learning.exemplars_for(request) splices a compressed prior
+     successful trace between system and user — 1 concrete example beats 25
+     abstract lessons for a small model.
+3. (local model) Loop.plan_first forces a numbered tool plan BEFORE dispatch.
+4. Dispatch runs a tool              → Metrics.record(tool, ok?, ms, engine:)
    ↳ tool FAILED?                    → Mistakes.record(tool, error)  (count++, cross-session)
    ↳ same sig ≥3×?                   → guard_repeated_failure + inline correction_hint
-2. Agent senses the world (opt)      → extro_verify / watch / rf_tune / osint / serial / telecomm / packet / vision / voice / intel / observe
+   ↳ (local) ≥ ESCALATE_AFTER_FAILS  → Swarm.ask(escalation_persona) → 3-line frontier hint
+5. Agent senses the world (opt)      → extro_verify / watch / rf_tune / osint / serial / telecomm / packet / vision / voice / intel / observe
    ↳ extro_verify → :refuted         → Mistakes.record(tool:'assumption', …)  # proactive
    ↳ extro_verify → :confirmed       → observe(:intel, ttl:30d)
-3. Final answer produced             → Learning.auto_introspect(session_id)
+6. Final answer produced             → Learning.auto_introspect(session_id)
+   ↳ (local) fact_check_local_final  → auto extro_verify every CVE/version claim in the answer
    ↳ if auto_extrospect enabled      → Extrospection.auto_extrospect  # AUTO_SECTIONS only
-4. Reflect finds a durable insight   → Memory.remember(lesson_xxxx, …)
-5. A whole workflow succeeded         → Learning.distill_skill(name, session_id, references:)
-6. Found a fix for a mistake          → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X — FIX: Y"
-7. Next launch: PromptBuilder injects all six blocks → the model already knows:
+7. Reflect.on(engine: reflect_engine)→ Memory.remember(lesson_xxxx, …)   # teacher-student: a
+                                       frontier engine may WRITE the lesson a local engine READS
+8. A whole workflow succeeded         → Learning.distill_skill(name, session_id, references:)
+9. Found a fix for a mistake          → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X — FIX: Y"
+10. (weekly, cron) Learning.export_finetune → ~/.pwn/finetune/*.jsonl → LoRA over the local
+     model — the ONLY step that changes weights, not just the scaffold.
+11. Next launch: PromptBuilder injects the budgeted blocks → the model already knows:
      MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS · EXTROSPECTION
 ```
 
@@ -75,6 +86,8 @@ the `## References` section, deduplicates, and exposes them via
 | `metrics_reset(confirm: true)` | fixed a broken tool; stale 0 % is misleading |
 | `skill_delete(name)` | auto-distilled skill turned out low-quality |
 | `learning_auto_introspect_toggle(enabled: false)` | during noisy fuzz loops |
+| `PWN::MemoryIndex.reset` | new engagement — drop the local embedding index (`memory.idx`) so it rebuilds against the fresh `memory.json` |
+| `PWN::AI::Agent::Learning.export_finetune(format: :sharegpt)` | you have enough successful sessions to cut a supervised dataset for the local model |
 
 ## Example questions that trigger Introspection
 
@@ -85,7 +98,7 @@ when deciding which side of the loop to exercise.
 
 ### Memory (`memory_remember`, `memory_recall`, `memory_forget`, `memory_clear`)
 
-- “Remember that our preferred AI engine for long recon chains is grok-4.5.”
+- “Remember that our preferred AI engine for long recon chains is `grok`.”
 - “What do we already know about OpenSSH 8.2p1 from prior sessions?”
 - “Forget the stale fact about the old HackRF serial — it was replaced.”
 - “Store this as a durable lesson: always back up source files before patching.”

data/documentation/Swarm.md

@@ -49,6 +49,26 @@ agent_spawn(name: 'blue_team',
 | `swarm_bus(swarm_id)` | Tail a bus to inspect a prior/concurrent conversation |
 | `swarm_list` | Find a `swarm_id` to resume |
 
+
+## Escalation persona (local-model circuit-breaker)
+
+`Loop.run` also uses Swarm *implicitly*. When the active engine is `ollama`
+and `ai.agent.escalation_persona` names a persona here, the loop counts
+in-turn tool failures; once ≥ `Loop::ESCALATE_AFTER_FAILS` (default 4) it
+calls `Swarm.ask(name: <persona>, request: "Local agent is stuck on: … Give a
+3-line corrective hint")` and injects the reply as a synthetic
+`frontier_hint` tool result. The **local model still authors the final
+answer** — Learning / Metrics stay attributed to `:ollama`, and every
+escalation is fingerprinted into `Mistakes` (tool: `'escalation'`) so
+`export_finetune` can later teach the local model to *not* need it.
+
+```yaml
+# ~/.pwn/pwn.yaml
+ai:
+  agent:
+    escalation_persona: blue_team   # any persona in ~/.pwn/agents.yml
+```
+
 ## Example: adversarial exploit review
 
 ```ruby

data/documentation/Transparent-Browser.md

@@ -6,6 +6,9 @@ capture. It's the traffic source for [BurpSuite](BurpSuite.md), the engine
 under every [`PWN::WWW`](WWW.md) driver, and the agent's go-to for anything
 JS-heavy.
 
+> **Install:** `pwn setup --profile web` — chromium · geckodriver · tor ·
+> nokogiri headers. See [Installation](Installation.md).
+
 ## Open
 
 ```ruby

data/documentation/Troubleshooting.md

@@ -1,5 +1,50 @@
 # Troubleshooting
 
+## "Which capabilities are broken on this host?"
+
+Run the built-in doctor — it tells you exactly which native gem or external
+binary is missing, what OS package provides it, and which `PWN::` constants
+are degraded as a result:
+
+```bash
+$ pwn setup            # or: pwn_setup / pwn --setup
+```
+
+Then fix a subset:
+
+```bash
+$ pwn setup --profile web        # or: net · sdr · vision · voice · db · hardware · exploit · full
+$ pwn setup --deps --dry-run     # show the apt/dnf/pacman/brew/port commands without running them
+```
+
+See [Installation](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
+for the full profile table and `PWN::Setup` API.
+
+## `LoadError` / `cannot load such file -- pg` (or rmagick, pcaprub, …)
+
+A native extension failed to compile because its OS headers weren't present
+at `gem install` time. `pwn setup` knows the mapping for every package
+manager and will install the headers **and** rebuild the gem:
+
+```bash
+$ pwn setup --profile db      # pg / sqlite3
+$ pwn setup --profile vision  # rmagick / rtesseract / oily_png / gruff
+$ pwn setup --profile net     # pcaprub
+```
+
+The runtime is `autoload`ed, so a missing extension only surfaces when you
+touch the constant that needs it — the rest of PWN keeps working.
+
+## `nmap` / `chromium` / `gqrx` / … not found on `$PATH`
+
+Same fix — `PWN::Setup::TOOLCHAIN` maps every wrapped binary to its OS
+package on `apt` / `dnf` / `pacman` / `brew` / `port`:
+
+```bash
+$ pwn setup --profile web     # chromium · geckodriver · burpsuite · zaproxy · sqlmap · tor
+$ pwn setup --profile sdr     # gqrx · rtl_sdr · hackrf_info · SoapySDRUtil · multimon-ng · sox
+```
+
 ## SHIFT+ENTER submits instead of newline
 
 `pwn-ai` / `pwn-asm` need the terminal to send a *distinct* code for
@@ -25,16 +70,17 @@ ss -tlnp | grep -E ':8080|:1337'
 ```
 
 Restart via `PWN::Plugins::BurpSuite.start` / `PWN::Plugins::Zaproxy.start` or
-fix the port in `~/.pwn/config.yml`.
+fix the port via `pwn-vault` (`~/.pwn/pwn.yaml`).
 
 ## `Psych::DisallowedClass` on cron/agents YAML
 
 Fixed in current `PWN::Cron` / `Swarm` — both loaders now pass
-`permitted_classes: [Symbol]`. If you see it, `git pull && rake install`.
+`permitted_classes: [Symbol]`. If you see it, `gem update pwn`.
 
 ## Agent stops early ("max iterations")
 
-Raise `ai.agent.max_iters` in `~/.pwn/config.yml`, or split the request.
+Raise `ai.agent.max_iters` in `~/.pwn/pwn.yaml` (edit via `pwn-vault`), or
+split the request.
 
 ## A tool is stuck at 0 % success
 
@@ -46,12 +92,22 @@ the agent away: `metrics_reset(confirm: true)`.
 | Engine | Fix |
 |---|---|
 | grok `oauth: true` | first run prints a `https://accounts.x.ai/…` URL — open it, approve, token is cached |
-| ollama | ensure `ollama serve` is running and `base_url:` matches |
-| others | check `key:` under `ai.<engine>` in `~/.pwn/config.yml` |
+| ollama | ensure `ollama serve` is running and `base_uri:` matches |
+| others | check `key:` under `ai.<engine>` in `~/.pwn/pwn.yaml` (edit via `pwn-vault`) |
+
+`pwn setup` reports the `AI engine` row as `MISSING` until a key is set.
 
 ## Diagrams won't rebuild
 
-`sudo apt install graphviz` (need `dot` on `$PATH`), then
-`cd documentation/diagrams && ./build.sh`.
+```bash
+$ pwn setup --profile vision   # installs graphviz (dot)
+$ cd documentation/diagrams && ./build.sh
+```
+
+## `No supported package manager found`
+
+`PWN::Setup` supports `apt-get`, `dnf`, `pacman`, `brew`, and `port`. On other
+systems use `pwn setup --dry-run --profile <name>` to print the package
+list, then install equivalents by hand.
 
 [← Home](Home.md)

data/documentation/What-is-PWN.md

@@ -20,7 +20,7 @@ tool-calling AI agent** on top of it.
 | `PWN::WWW::*` | **21** | Site-specific browser automations (HackerOne, BugCrowd, Google, LinkedIn, …) |
 | `PWN::SDR::*` | **6** | GQRX, FlipperZero, RFIDler, SonMicro, decoders, band tables |
 | `PWN::AI::*` | **5** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama |
-| `bin/pwn_*` | **52** | Headless CLI drivers for CI/CD |
+| `bin/pwn_*` | **53** | Headless CLI drivers for CI/CD |
 | Agent toolsets | **10** | terminal · pwn · memory · skills · sessions · learning · metrics · extrospection · cron · swarm |
 
 ## The three ways to use it