pwn 0.5.628 → 0.5.631

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 44fdb9e4897d83ad9ab54d65bc774eed6be14c379eea42b1a7984abab23c03bd
-  data.tar.gz: ba801dabf738c43b3fe7ce9cf40bdfb38d1cf62f7a0b98b05861626c33d2d008
+  metadata.gz: f125b1fd9398d2de99e6b311a1950e646992736f38552b818cb269e9d8704a6d
+  data.tar.gz: a84266bb38a93fecb6e8c5fa0b5c73b638dcaa9196838a436c31127f95eedf31
 SHA512:
-  metadata.gz: 205805e3088246b711249ba3b778e9418fb1616ad576dde6c22c0c632409de88b2545fda88ee30316fe7a203a2ff9a46236136e94ba291a7dc27c800d7b8c02c
-  data.tar.gz: 4e439c01661f7707c9bf79e8e4be656e76f9d57d5bb17cf9778536bd1a8ebbc63aebd4effbcce38d4ed89f4cfdbe188072ab710a7374d0a951fd8a0c7bd7d0fd
+  metadata.gz: 9a2114b37283201211235e16fb558b51e5eb64ebec22d164898fc5b40db763696f56fdea8a99e9cf3905701fa3738a866726822a797e970a1de64c3ded54503d
+  data.tar.gz: fb3452718e38139450c34b8de7905188906e5d10935aabb592f6c96c0789e61ab1e29d4b4bc6e4563c1c124ffa87c835c4c417bccd99a0c919a93443e757f70f

data/README.md

@@ -1,7 +1,7 @@
 <!-- ![PWN](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/PWN.png) -->
 
 <p align="center">
-  <img src="documentation/pwn_silent_help_learn_demo.gif" alt="PWN Silent Demo — Help Surfaces + Learning Feedback Loop" width="640">
+  <img src="documentation/pwn_silent_help_learn_demo.gif" alt="PWN Silent Demo - Help Surfaces + Learning Feedback Loop" width="640">
 </p>
 
 ### **Table of Contents** ###
@@ -24,16 +24,16 @@
 
 #### **What is PWN** ####
 
-PWN (pronounced /pōn/ — *pone*) is an open-source **offensive-security
+PWN (pronounced /pōn/ - *pone*) is an open-source **offensive-security
 automation framework** and **continuous-security-integration** platform.
 It gives security researchers, red teamers, penetration testers and
 vulnerability researchers a single, scriptable Ruby surface over the entire
-offensive toolchain — from OSINT and network discovery, through web / cloud /
-hardware / radio exploitation, to reporting and disclosure — and puts a
+offensive toolchain - from OSINT and network discovery, through web / cloud /
+hardware / radio exploitation, to reporting and disclosure - and puts a
 **self-improving, tool-calling, multi-agent AI** on top of it.
 
 **In numbers:** 66 `PWN::Plugins` · 48 `PWN::SAST` rules · 90 `PWN::AWS`
-service wrappers · 21 `PWN::WWW` site drivers · 52 `bin/pwn_*` CLI drivers ·
+service wrappers · 21 `PWN::WWW` site drivers · 53 `bin/pwn_*` CLI drivers ·
 5 LLM engines · 10 agent toolsets · 45+ LLM-callable tools.
 
 Full page: [What is PWN](documentation/What-is-PWN.md)
@@ -43,7 +43,7 @@ Full page: [What is PWN](documentation/What-is-PWN.md)
 Offensive security is a *toolchain problem*. PWN's bet is that the right
 abstraction is **plain Ruby methods with a uniform `opts = {}` signature**,
 exposed simultaneously to a human in a REPL, an LLM in a tool-calling loop, a
-shell script in CI, and a cron job at 3 am — all open-source and auditable,
+shell script in CI, and a cron job at 3 am - all open-source and auditable,
 which matters when the caller is autonomous.
 
 Full page: [Why PWN](documentation/Why-PWN.md)
@@ -54,10 +54,10 @@ Five layers, edges only ever go down:
 
 ![PWN Overall Architecture](documentation/diagrams/overall-pwn-architecture.svg)
 
-The AI layer closes a **self-improvement loop** on every turn — Metrics +
+The AI layer closes a **self-improvement loop** on every turn - Metrics +
 Learning + **Mistakes** (introspection / negative feedback) joined with
-Snapshot + Drift + Intel + RF + **Web** (extrospection) — plus browser-backed **`extro_verify`** / **`extro_watch`** and RF **`extro_rf_tune`** sensing — via `extro_correlate`, so the
-agent knows whether a failure was *its* fault or *the world* changed —
+Snapshot + Drift + Intel + RF + **Web** (extrospection) - plus browser-backed **`extro_verify`** / **`extro_watch`** and RF **`extro_rf_tune`** sensing - via `extro_correlate`, so the
+agent knows whether a failure was *its* fault or *the world* changed -
 **and does not repeat the same mistake twice**:
 
 ![pwn-ai Feedback Learning Loop](documentation/diagrams/pwn-ai-feedback-learning-loop.svg)
@@ -68,8 +68,8 @@ on the next recurrence:
 
 ![Mistakes Negative-Feedback Loop](documentation/diagrams/mistakes-negative-feedback.svg)
 
-And **Swarm** runs multiple personas — each a full tool-calling agent,
-optionally on a *different* LLM engine — over a shared append-only bus:
+And **Swarm** runs multiple personas - each a full tool-calling agent,
+optionally on a *different* LLM engine - over a shared append-only bus:
 
 ![Swarm Multi-Agent](documentation/diagrams/swarm-multi-agent.svg)
 
@@ -86,7 +86,7 @@ The complete wiki lives in this repo at **[`documentation/Home.md`](documentatio
 |---|---|---|---|
 | [What is PWN](documentation/What-is-PWN.md) | [`pwn` REPL](documentation/pwn-REPL.md) | [AI / LLM Integration](documentation/AI-Integration.md) | [Plugins (66)](documentation/Plugins.md) |
 | [Why PWN](documentation/Why-PWN.md) | [`pwn-ai` Agent](documentation/pwn-ai-Agent.md) | [Agent Tool Registry](documentation/Agent-Tool-Registry.md) | [SAST (48)](documentation/SAST.md) |
-| [How PWN Works](documentation/How-PWN-Works.md) | [CLI Drivers (52)](documentation/CLI-Drivers.md) | [Memory · Skills · Learning](documentation/Skills-Memory-Learning.md) | [AWS (90)](documentation/AWS.md) |
+| [How PWN Works](documentation/How-PWN-Works.md) | [CLI Drivers (53)](documentation/CLI-Drivers.md) | [Memory · Skills · Learning](documentation/Skills-Memory-Learning.md) | [AWS (90)](documentation/AWS.md) |
 | [Installation](documentation/Installation.md) | [Build a Driver](documentation/Drivers.md) | [Mistakes (neg-feedback)](documentation/Mistakes.md) | [WWW (21)](documentation/WWW.md) |
 | [General Usage](documentation/General-PWN-Usage.md) | | [Extrospection](documentation/Extrospection.md) | [SDR / Radio](documentation/SDR.md) |
 | [Configuration](documentation/Configuration.md) | | [Swarm (multi-agent)](documentation/Swarm.md) | [Hardware](documentation/Hardware.md) |
@@ -103,18 +103,31 @@ Rebuild every SVG from its Graphviz source:
 
 ### **Installation** ###
 
-Tested on Debian-based Linux & macOS, Ruby via RVM.
+PWN is a **single gem** with a built-in post-install doctor/provisioner -
+`pwn setup` - that detects your package manager (`apt` · `dnf` · `pacman` ·
+`brew` · `port`) and installs exactly the OS headers + external tools each
+`PWN::` capability needs. Tested on Kali/Debian/Ubuntu, Fedora, Arch, macOS.
 
 ```
-$ cd /opt
-$ sudo git clone https://github.com/0dayinc/pwn
-$ cd /opt/pwn
-$ ./install.sh
-$ ./install.sh ruby-gem
+$ gem install pwn
+$ pwn setup                        # read-only doctor: which capabilities are usable?
+$ pwn setup --profile full --yes   # provision everything (or: web | net | sdr | vision | ...)
 $ pwn
-pwn[v0.5.628]:001 >>> PWN.help
+pwn[v0.5.631]:001 >>> PWN.help
 ```
 
+Only need a subset?
+
+```
+$ pwn setup --list-profiles
+$ pwn setup --profile web          # TransparentBrowser · Burp · ZAP · Tor · sqlmap
+$ pwn setup --profile sdr --yes    # GQRX · rtl-sdr · hackrf · SoapySDR · FFI DSP
+$ pwn setup --profile net --dry-run
+```
+
+Also available as `pwn_setup` (standalone driver) and `pwn --setup[=PROFILE]`.
+The doctor exits non-zero when capabilities are degraded, so CI can gate on it.
+
 [![Installing the pwn Security Automation Framework](https://raw.githubusercontent.com/0dayInc/pwn/master/documentation/pwn_install.png)](https://youtu.be/G7iLUY4FzsI)
 
 Full page: [Installation](documentation/Installation.md) ·
@@ -127,29 +140,25 @@ Full page: [Installation](documentation/Installation.md) ·
 [General Usage Quick-Start](https://github.com/0dayinc/pwn/wiki/General-PWN-Usage) ·
 local: [General PWN Usage](documentation/General-PWN-Usage.md)
 
-Update PWN frequently — new plugins, agent tools, skills and zero-day tooling
+Update PWN frequently - new plugins, agent tools, skills and zero-day tooling
 land regularly:
 
 ```
-$ rvm list gemsets
-$ rvm use ruby-4.0.5@pwn
-$ gem uninstall --all --executables pwn
-$ gem install --verbose pwn
+$ gem update pwn
+$ pwn setup            # re-doctor - new versions may add capabilities
 $ pwn
-pwn[v0.5.628]:001 >>> PWN.help
+pwn[v0.5.631]:001 >>> PWN.help
 ```
 
-If using a multi-user RVM install:
+From a git checkout:
 
 ```
-$ rvm use ruby-4.0.5@pwn
-$ rvmsudo gem uninstall --all --executables pwn
-$ rvmsudo gem install --verbose pwn
+$ cd /opt/pwn && git pull && rake install && pwn setup
 ```
 
 **Inside the `pwn` REPL:**
 - Full access to every `PWN::` module.
-- `pwn-ai` — launch the autonomous agent TUI (SHIFT+ENTER newline, ENTER submit).
+- `pwn-ai` - launch the autonomous agent TUI (SHIFT+ENTER newline, ENTER submit).
 - `pwn-asm`, `pwn-ai-memory`, `pwn-ai-sessions`, `pwn-ai-cron`, `pwn-ai-delegate`.
 
 **Headless / CI one-shot (`pwn --ai`):**
@@ -160,11 +169,10 @@ $ echo "$LONG_PROMPT" | pwn --ai -
 $ pwn -Y ./ci/pwn.yaml --ai 'Run pwn_sast against ./src and summarise HIGH findings' > findings.txt
 ```
 
-PWN periodically upgrades to the latest Ruby (`/opt/pwn/.ruby-version`).
-Easiest upgrade of Ruby + pwn from a previous install:
+**Provision a CI runner / Docker image:**
 
 ```
-$ /opt/pwn/vagrant/provisioners/pwn.sh
+$ pwn setup --profile web --yes && pwn setup --check   # exits 1 if degraded
 ```
 
 ---
@@ -173,7 +181,7 @@ $ /opt/pwn/vagrant/provisioners/pwn.sh
 
 Contributions that expand PWN's offensive capabilities are welcome. If you can
 provide access to additional commercial LLMs, security scanners, or bounty
-platforms — or wish to contribute plugins, AI skills, or exploit modules —
+platforms - or wish to contribute plugins, AI skills, or exploit modules -
 please [email us](mailto:support@0dayinc.com). See
 [CONTRIBUTING.md](https://github.com/0dayInc/pwn/blob/master/CONTRIBUTING.md)
 and the local [Contributing](documentation/Contributing.md) page.
@@ -182,7 +190,7 @@ and the local [Contributing](documentation/Contributing.md) page.
 
 ### **Module Documentation** ###
 
-**Primary:** [`documentation/Home.md`](documentation/Home.md) — the full local
+**Primary:** [`documentation/Home.md`](documentation/Home.md) - the full local
 wiki with 30+ pages and 26 SVG data-flow diagrams.
 
 **API reference:** [rubydoc.info/gems/pwn](https://www.rubydoc.info/gems/pwn),
@@ -198,7 +206,7 @@ Highlights:
 [SAST](documentation/SAST.md) ·
 [AI Integration](documentation/AI-Integration.md)
 
-I hope you enjoy PWN — and remember: **always have permission** before any
+I hope you enjoy PWN - and remember: **always have permission** before any
 security testing. Now go pwn all the things (responsibly)!
 
 ---

data/bin/pwn

@@ -3,6 +3,19 @@
 
 require 'pwn'
 
+# ----------------------------------------------------------------------
+# Bare-word subcommand: `pwn setup [...]` → delegate to bin/pwn_setup so
+# `gem install pwn && pwn setup` is the canonical two-step install path.
+# Must be handled BEFORE OptionParser (which would reject `setup`).
+# ----------------------------------------------------------------------
+if ARGV.first == 'setup'
+  ARGV.shift
+  setup_bin = File.expand_path('pwn_setup', __dir__)
+  setup_bin = Gem.bin_path('pwn', 'pwn_setup') unless File.file?(setup_bin)
+  load setup_bin
+  exit
+end
+
 opts = PWN::Env[:driver_opts]
 pwn_driver = PWN::Driver::Parser.new do |options|
   options.on(
@@ -14,6 +27,16 @@ pwn_driver = PWN::Driver::Parser.new do |options|
   ) do |a|
     opts[:ai] = a
   end
+
+  options.on(
+    '-S[PROFILE]',
+    '--setup[=PROFILE]',
+    '<Optional - Post-install doctor / capability provisioner. With no ' \
+    "PROFILE runs a read-only check; with PROFILE (#{PWN::Setup::PROFILES.keys.join('|')}) " \
+    'installs OS deps for that capability set. Same as `pwn setup` / `pwn_setup`>'
+  ) do |p|
+    opts[:setup] = p || true
+  end
 end
 pwn_driver.auto_opts_help = false
 pwn_driver.parse!
@@ -21,7 +44,18 @@ pwn_driver.parse!
 begin
   pwn_pid = Process.pid
 
-  if opts[:ai]
+  if opts[:setup]
+    # ------------------------------------------------------------------
+    # `pwn --setup`            → PWN::Setup.check   (read-only doctor)
+    # `pwn --setup=web`        → PWN::Setup.deps(profile: :web)
+    # ------------------------------------------------------------------
+    if opts[:setup] == true
+      r = PWN::Setup.check
+      exit(r[:ok] ? 0 : 1)
+    else
+      PWN::Setup.deps(profile: opts[:setup])
+    end
+  elsif opts[:ai]
     # ------------------------------------------------------------------
     # Headless pwn-ai: behave as if the user typed PROMPT at the pwn-ai
     # TUI, but non-interactively — a single agent-loop turn with native

data/bin/pwn_setup

@@ -0,0 +1,64 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'pwn'
+
+opts = PWN::Env[:driver_opts]
+pwn_driver = PWN::Driver::Parser.new do |options|
+  options.banner = "USAGE: #{File.basename($PROGRAM_NAME)} [opts]\n       " \
+                   "Post-install doctor & capability provisioner for the PWN gem.\n       " \
+                   "With no options, runs a read-only capability check.\n"
+
+  options.on('-c', '--check',
+             '<Optional - Read-only doctor: which PWN capabilities are usable on this host? (default action)>') do |o|
+    opts[:check] = o
+  end
+
+  options.on('-d', '--deps',
+             '<Optional - Install OS headers + external tools + rebuild native gems for --profile (default: full)>') do |o|
+    opts[:deps] = o
+  end
+
+  options.on('-pNAME', '--profile=NAME',
+             "<Optional - Capability profile: #{PWN::Setup::PROFILES.keys.join(' | ')} (default: full)>") do |o|
+    opts[:profile] = o
+  end
+
+  options.on('-l', '--list-profiles',
+             '<Optional - List capability profiles and exit>') do |o|
+    opts[:list] = o
+  end
+
+  options.on('-y', '--yes',
+             '<Optional - Assume yes; non-interactive (CI-friendly)>') do |o|
+    opts[:yes] = o
+  end
+
+  options.on('-n', '--dry-run',
+             '<Optional - Print the commands that would run, do not execute>') do |o|
+    opts[:dry_run] = o
+  end
+end
+pwn_driver.auto_opts_help = false
+pwn_driver.parse!
+
+begin
+  if opts[:list]
+    PWN::Setup.list_profiles
+  elsif opts[:deps] || opts[:profile]
+    PWN::Setup.deps(
+      profile: opts[:profile],
+      yes: opts[:yes],
+      dry_run: opts[:dry_run]
+    )
+  else
+    r = PWN::Setup.check
+    exit 1 unless r[:ok]
+  end
+rescue Interrupt
+  puts "\naborted."
+  exit 130
+rescue StandardError => e
+  warn "pwn_setup: #{e.class}: #{e.message}"
+  exit 1
+end

data/documentation/AI-Integration.md

@@ -1,7 +1,7 @@
-# AI / LLM Integration — `PWN::AI`
+# AI / LLM Integration - `PWN::AI`
 
 One agent loop, five interchangeable engines. Swap providers by changing one
-line in `~/.pwn/config.yml`; the tool-calling contract is normalised so the
+line in `~/.pwn/pwn.yaml`; the tool-calling contract is normalised so the
 agent code never cares which model is behind it.
 
 ![Multi-provider integration](diagrams/ai-integration-tool-calling.svg)
@@ -12,25 +12,60 @@ agent code never cares which model is behind it.
 |---|---|---|---|
 | `openai` | `PWN::AI::OpenAI` | `key:` | function-calling native |
 | `anthropic` | `PWN::AI::Anthropic` | `key:` | tool-use native |
-| `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) — see skill `xai_grok_oauth_device_flow` |
+| `grok` | `PWN::AI::Grok` | `key:` **or** `oauth: true` | OAuth = RFC-8628 device-code flow using xAI's public Grok-CLI client id (no secret) - see skill `xai_grok_oauth_device_flow` |
 | `gemini` | `PWN::AI::Gemini` | `key:` | function-calling native |
-| `ollama` | `PWN::AI::Ollama` | none | local, `base_url:` + `model:` |
+| `ollama` | `PWN::AI::Ollama` | none | local - native `/api/chat` (`num_ctx`, `keep_alive`, low-temp + `format:'json'` on tool turns) and `/api/embed` for `PWN::MemoryIndex` |
+
+> PWN is **model-agnostic**. `ai.<engine>.model` is passed straight through to
+> the provider - the codebase and docs deliberately never name a specific
+> model id so you can point each engine at whatever the vendor currently
+> ships (or whatever `ollama list` shows locally).
 
 ## Selecting an engine
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml
 ai:
-  engine: grok
+  active: grok
   grok:
-    oauth: true   # first run opens https://accounts.x.ai/… device page
+    oauth:
+      enroll: true    # first run opens https://accounts.x.ai/... device page
 ```
 
 ```ruby
 # at runtime
-PWN::Env[:ai][:engine] = :ollama
+PWN::Env[:ai][:active] = :ollama
 ```
 
+## Engine-aware behavior
+
+The harness adapts to the *class* of engine, not the model name:
+
+| Concern | Frontier (`openai` · `anthropic` · `grok` · `gemini`) | Local (`ollama`) |
+|---|---|---|
+| **PromptBuilder.budget** | full MEMORY / METRICS / MISTAKES / LEARNING / EXTRO blocks | tightened via `ai.ollama.prompt_budget` (extro off by default) |
+| **MEMORY ranking** | relevance-ranked when a local Ollama `embed_model` is reachable, else newest-first | relevance-ranked via `PWN::MemoryIndex` (`~/.pwn/memory.idx`) |
+| **Tool schemas shipped** | all toolsets | `CORE_TOOLS` + top-K keyword matches when `ai.agent.tool_router` is on |
+| **Pre-pass** | none | `plan_first` numbered tool plan before first dispatch |
+| **Few-shot** | none | `Learning.exemplars_for(request)` splices a prior successful trace |
+| **Dispatch parsing** | strict | tolerant - Levenshtein tool-name repair + JSON5-ish arg cleanup, each repair fingerprinted into `Mistakes` |
+| **Post-answer** | `auto_introspect` | `auto_introspect` **+** `fact_check_local_final` (auto `extro_verify` on CVE/version-shaped claims) |
+| **Metrics bucket** | `metrics.json[:tools][name][:engines][:<engine>]` | same - the `TOOL EFFECTIVENESS` block is per-engine so local telemetry never blends with frontier |
+
+## Teacher-student reflection
+
+`ai.reflect_engine` decouples *doing* from *learning-about-doing*:
+
+```yaml
+ai:
+  active: ollama            # the local model executes tools and answers
+  reflect_engine: anthropic # a frontier model writes the durable Memory :lesson
+```
+
+`PWN::AI::Agent::Reflect.on` temporarily flips the active engine for the
+introspection call only, so the local model reads back distilled reasoning it
+could not have produced itself.
+
 ## Direct client use (no agent)
 
 ```ruby
@@ -43,10 +78,14 @@ puts resp[:content]
 ## Model diversity in Swarm
 
 Because each persona in [`agents.yml`](Swarm.md) can override `engine:`, an
-`agent_debate` can literally pit Claude against Grok against a local Llama —
-real antagonism, not one model role-playing three voices.
+`agent_debate` can pit five *different providers* against each other - real
+antagonism, not one model role-playing three voices. The same mechanism backs
+`ai.agent.escalation_persona`: when a local model is stuck, `Loop.run` asks a
+frontier persona for a 3-line corrective hint and injects it as a synthetic
+tool result.
 
 **See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
-[Agent Tool Registry](Agent-Tool-Registry.md) · [Swarm](Swarm.md)
+[Agent Tool Registry](Agent-Tool-Registry.md) · [Swarm](Swarm.md) ·
+[Configuration](Configuration.md)
 
 [← Home](Home.md)

data/documentation/AWS.md

@@ -1,4 +1,4 @@
-# `PWN::AWS` — Cloud Security (90 service wrappers)
+# `PWN::AWS` - Cloud Security (90 service wrappers)
 
 One thin module per AWS service, each wrapping the official `aws-sdk-*` gem
 with the PWN `opts = {}` convention so they compose in the REPL and in
@@ -10,7 +10,7 @@ with the PWN `opts = {}` convention so they compose in the REPL and in
 
 Standard AWS SDK chain: `~/.aws/credentials` profile, env vars
 (`AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` / `AWS_SESSION_TOKEN`), or
-instance profile. Optionally pin in `~/.pwn/config.yml` under `aws:`.
+instance profile. Optionally pin in `~/.pwn/pwn.yaml` under `aws:`.
 
 ## Quick enumeration
 
@@ -51,7 +51,7 @@ CLI: `pwn_aws_describe_resources -r us-east-1 -o out/`
   `ec2:RunInstances` with instance profile.
 - **Persist** → new access key, Lambda backdoor, EC2 userdata.
 
-Record everything with `extro_observe(source: 'aws', …)` so
+Record everything with `extro_observe(source: 'aws', ...)` so
 [Extrospection](Extrospection.md) can correlate later.
 
 [← Home](Home.md)

data/documentation/Agent-Tool-Registry.md

@@ -21,6 +21,30 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 | `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
 | `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
 
+
+## Dynamic tool-set slimming (`ai.agent.tool_router`)
+
+Shipping every schema on every turn overwhelms a small local model - the
+choice space is huge and it mis-routes (e.g. picks an RF tool for a git
+question). When `ai.agent.tool_router: true` **and** `Loop.run` passes the
+user request through as `relevance:`, `Registry.definitions` shrinks the
+pool to:
+
+```text
+CORE_TOOLS  = shell · pwn_eval · memory_remember · memory_recall
+              mistakes_record · mistakes_resolve · learning_note_outcome
+            + top-K keyword-ranked matches for THIS request
+              (ties break on Metrics per-engine success_rate → the router
+               itself is a learned component)
+```
+
+```ruby
+PWN::AI::Agent::Registry.definitions(relevance: 'nmap sweep 10.0.0.0/8', top_k: 10)
+PWN::AI::Agent::Registry.rank(query: 'run a shell command')   # inspect ranking
+```
+
+Frontier engines leave `tool_router` off and receive the full set.
+
 ## Adding a tool
 
 ```ruby

data/documentation/Banner.md

@@ -1,4 +1,4 @@
-# `PWN::Banner` — Startup Art
+# `PWN::Banner` - Startup Art
 
 15 ANSI banners; one is picked at random every time the REPL starts. Purely
 cosmetic, entirely necessary.

data/documentation/Blockchain.md

@@ -1,4 +1,4 @@
-# `PWN::Blockchain` — BTC · ETH
+# `PWN::Blockchain` - BTC · ETH
 
 Lightweight helpers for on-chain recon and wallet interaction.
 Source: `lib/pwn/blockchain/*.rb`.
@@ -11,8 +11,8 @@ Source: `lib/pwn/blockchain/*.rb`.
 Also exposed to the agent via `PWN::AI::Agent::BTC` for wallet-aware prompts.
 
 ```ruby
-PWN::Blockchain::BTC.balance(address: 'bc1q…')
-PWN::Blockchain::ETH.call(contract: '0x…', method: 'owner()')
+PWN::Blockchain::BTC.balance(address: 'bc1q...')
+PWN::Blockchain::ETH.call(contract: '0x...', method: 'owner()')
 ```
 
 [← Home](Home.md)

data/documentation/Bounty.md

@@ -1,4 +1,4 @@
-# `PWN::Bounty` — Bug-Bounty Lifecycle Tooling
+# `PWN::Bounty` - Bug-Bounty Lifecycle Tooling
 
 | Module | Purpose |
 |---|---|
@@ -6,9 +6,9 @@
 
 Pairs naturally with:
 
-- [`PWN::WWW::HackerOne`](WWW.md) / `BugCrowd` / `Synack` — programme navigation
-- `PWN::Plugins::HackerOne` — submissions API
-- [`PWN::Plugins::BurpSuite`](BurpSuite.md) — capture the session to replay
+- [`PWN::WWW::HackerOne`](WWW.md) / `BugCrowd` / `Synack` - programme navigation
+- `PWN::Plugins::HackerOne` - submissions API
+- [`PWN::Plugins::BurpSuite`](BurpSuite.md) - capture the session to replay
 
 ```ruby
 PWN::Bounty::LifecycleAuthzReplay.start(

data/documentation/BurpSuite.md

@@ -6,10 +6,13 @@ Professional's headless mode + REST API.
 
 ![Web application testing](diagrams/web-application-testing.svg)
 
+> **Install:** `pwn setup --profile web` - burpsuite · zaproxy · chromium ·
+> geckodriver · sqlmap · tor. See [Installation](Installation.md).
+
 ## Configure
 
 ```yaml
-# ~/.pwn/config.yml
+# ~/.pwn/pwn.yaml  (edit via `pwn-vault`)
 burp:
   jar: /opt/burpsuite_pro/burpsuite_pro.jar
   api_key: <REST-API-KEY>
@@ -39,7 +42,7 @@ PWN::Plugins::BurpSuite.stop(burp_obj: burp)
 ## CLI drivers
 
 - `pwn_burp_suite_pro_active_scan -t URL -o out/`
-- `pwn_burp_suite_pro_active_rest_api_scan` — pure REST, no JVM spawn
+- `pwn_burp_suite_pro_active_rest_api_scan` - pure REST, no JVM spawn
 
 ## Why preferred over ZAP
 

data/documentation/CLI-Drivers.md

@@ -1,6 +1,6 @@
-# CLI Drivers — `bin/pwn_*`
+# CLI Drivers - `bin/pwn_*`
 
-52 headless executables, each a thin `OptionParser` wrapper over one plugin
+53 headless executables, each a thin `OptionParser` wrapper over one plugin
 (or one workflow). They exist so CI/CD can call PWN without a REPL or an LLM.
 
 ![Driver anatomy](diagrams/driver-framework.svg)
@@ -26,19 +26,34 @@ pwn_crt_sh                       pwn_serial_check_voicemail
 pwn_defectdojo_engagement_create pwn_serial_msr206
 pwn_defectdojo_importscan        pwn_serial_qualcomm_commands
 pwn_defectdojo_reimportscan      pwn_serial_son_micro_sm132_rfid
-pwn_diff_csv_files_w_column_exclude  pwn_shodan_graphql_introspection
-pwn_domain_reversewhois          pwn_shodan_search
-pwn_fuzz_net_app_proto           pwn_simple_http_server
-pwn_gqrx_scanner                 pwn_web_cache_deception
-pwn_jenkins_create_job           pwn_www_checkip
-pwn_jenkins_create_view          pwn_www_uri_buster
-pwn_jenkins_install_plugin       pwn_xss_dom_vectors
-                                 pwn_zaproxy_active_rest_api_scan
-                                 pwn_zaproxy_active_scan
+pwn_diff_csv_files_w_column_exclude  pwn_setup
+pwn_domain_reversewhois          pwn_shodan_graphql_introspection
+pwn_fuzz_net_app_proto           pwn_shodan_search
+pwn_gqrx_scanner                 pwn_simple_http_server
+pwn_jenkins_create_job           pwn_web_cache_deception
+pwn_jenkins_create_view          pwn_www_checkip
+pwn_jenkins_install_plugin       pwn_www_uri_buster
 ```
 
 Run any with `--help` for its flags.
 
+## `pwn_setup` - post-install doctor & capability provisioner
+
+The one driver that isn't a plugin wrapper. It grows a bare `gem install pwn`
+into a fully-armed host by installing OS headers / external tools for whatever
+capability profile you ask for. Also reachable as `pwn setup` and
+`pwn --setup[=PROFILE]`.
+
+```bash
+pwn_setup                        # read-only doctor; exit 1 if degraded
+pwn_setup --list-profiles
+pwn_setup --profile web --yes    # CI-friendly, non-interactive
+pwn_setup --deps --dry-run       # print the apt/dnf/pacman/brew/port commands only
+```
+
+See [Installation](Installation.md) for the full profile table and
+`PWN::Setup` API.
+
 ## Typical CI usage
 
 ```yaml
@@ -46,13 +61,15 @@ Run any with `--help` for its flags.
 sast:
   image: 0dayinc/pwn:latest
   script:
+    - pwn_setup --profile net --yes
+    - pwn_setup --check                                   # gate: exit 1 if degraded
     - pwn_sast -d "$CI_PROJECT_DIR" -o sast_out/
     - pwn_defectdojo_importscan -f sast_out/report.json -e "$DD_ENGAGEMENT"
 ```
 
 ## Write your own
 
-See [Drivers](Drivers.md) — copy any file in `bin/`, swap the plugin call,
+See [Drivers](Drivers.md) - copy any file in `bin/`, swap the plugin call,
 `rake install`, done.
 
 [← Home](Home.md)