pwn 0.5.628 → 0.5.631

data/documentation/Configuration.md

@@ -1,4 +1,4 @@
-# Configuration — `~/.pwn/pwn.yaml`
+# Configuration - `~/.pwn/pwn.yaml`
 
 Everything configurable in PWN lives in **one encrypted YAML file**, loaded by
 `PWN::Config.refresh_env` at driver startup and exposed in-process as the
@@ -8,20 +8,25 @@ frozen constant **`PWN::Env`** (a redacted copy is available as
 The file is **AES-encrypted at rest** by `PWN::Plugins::Vault`. Its key/IV
 live in a sibling **`~/.pwn/pwn.yaml.decryptor`** file (or in
 `PWN_DECRYPTOR_KEY` / `PWN_DECRYPTOR_IV` env vars). Never edit `pwn.yaml`
-by hand — use the **`pwn-vault`** REPL command, which decrypts → opens
+by hand - use the **`pwn-vault`** REPL command, which decrypts → opens
 `$EDITOR` → re-encrypts → reloads `PWN::Env`.
 
 If `~/.pwn/pwn.yaml` does not exist on first run, `PWN::Config.default_env`
 writes a fully-commented template with every key below (values set to
-`'optional - …'` / `'required - …'` placeholder strings), encrypts it, and
+`'optional - ...'` / `'required - ...'` placeholder strings), encrypts it, and
 generates the decryptor.
 
+> **Before configuring**, run `pwn setup` - the
+> [doctor](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
+> reports whether `~/.pwn/`, `pwn.yaml`, its decryptor, and an AI-engine key
+> are present, and exits non-zero for CI if any are missing.
+
 ---
 
 ## Full annotated example
 
 ```yaml
-# ~/.pwn/pwn.yaml  (shown DECRYPTED — file is AES-encrypted on disk)
+# ~/.pwn/pwn.yaml  (shown DECRYPTED - file is AES-encrypted on disk)
 
 ai:
   active: grok                     # Which engine backs `pwn-ai`. One of: openai | anthropic | grok | gemini | ollama.
@@ -29,12 +34,12 @@ ai:
 
   grok:
     base_uri: https://api.x.ai/v1  # xAI API base URL. Override for a self-hosted proxy / private endpoint.
-    key: xai-…                     # xAI API key. If blank AND no oauth.* below, PWN prompts interactively at load.
-    model: grok-4.5                # Model id sent on every chat / tool-loop request.
+    key: xai-...                     # xAI API key. If blank AND no oauth.* below, PWN prompts interactively at load.
+    model: <model-id>              # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking xAI Grok agent.'   # Base system prompt (MEMORY/SKILLS/LEARNING/EXTROSPECTION blocks are appended to this).
     temp: 1.0                      # Sampling temperature passed to the chat endpoint.
     max_prompt_length: 256000      # Soft input-context ceiling (chars) used for prompt truncation / chunking.
-    oauth:                         # RFC-8628 device-flow (SuperGrok subscription) — public client, no client_secret.
+    oauth:                         # RFC-8628 device-flow (SuperGrok subscription) - public client, no client_secret.
       refresh_token: ~             # Durable OAuth refresh token; enables silent re-auth without an API key.
       bearer_token: ~              # Short-lived OAuth access JWT; auto-refreshed each run when refresh_token is set.
       client_id: b1a00492-073a-47ea-816f-4c329264a828   # xAI's PUBLIC OAuth client id for the "Grok CLI" application (not sensitive).
@@ -45,8 +50,8 @@ ai:
 
   openai:
     base_uri: https://api.openai.com/v1   # OpenAI API base URL. Override for Azure OpenAI / VPC gateway / local proxy.
-    key: sk-…                             # OpenAI API key (`sk-…`). Prompted interactively if blank.
-    model: gpt-4o                         # Model id sent on every chat / tool-loop request.
+    key: sk-...                             # OpenAI API key (`sk-...`). Prompted interactively if blank.
+    model: <model-id>                     # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking OpenAI agent.'   # Base system prompt for this engine.
     temp: 1.0                             # Sampling temperature.
     max_prompt_length: 128000             # Soft input-context ceiling (chars) for truncation / chunking.
@@ -54,8 +59,8 @@ ai:
 
   anthropic:
     base_uri: https://api.anthropic.com/v1   # Anthropic API base URL. Override for Bedrock / private gateway.
-    key: sk-ant-…                            # Anthropic API key (`sk-ant-…`). Prompted interactively if blank.
-    model: claude-3-5-sonnet-20240620        # Model id sent on every chat / tool-loop request.
+    key: sk-ant-...                            # Anthropic API key (`sk-ant-...`). Prompted interactively if blank.
+    model: <model-id>                        # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking Anthropic agent.'   # Base system prompt for this engine.
     temp: 1.0                                # Sampling temperature.
     max_tokens: 8192                         # Max OUTPUT tokens per response. Raise if tool-call JSON truncates.
@@ -63,26 +68,40 @@ ai:
 
   gemini:
     base_uri: https://generativelanguage.googleapis.com/v1beta   # Google Generative Language API base URL.
-    key: AIza…                               # Google AI Studio API key (`AIza…`). Prompted interactively if blank.
-    model: gemini-2.5-pro                    # Model id sent on every chat / tool-loop request.
+    key: AIza...                               # Google AI Studio API key (`AIza...`). Prompted interactively if blank.
+    model: <model-id>                        # Model id sent on every chat / tool-loop request. See provider docs / API for currently-supported ids.
     system_role_content: 'You are an ethically hacking Gemini agent.'   # Base system prompt for this engine.
     temp: 1.0                                # Sampling temperature.
-    max_prompt_length: 1000000               # Soft input-context ceiling (chars) — Gemini supports very large contexts.
+    max_prompt_length: 1000000               # Soft input-context ceiling (chars) - Gemini supports very large contexts.
 
   ollama:
-    base_uri: https://ollama.local           # REQUIRED for ollama — Open WebUI / ollama-serve base URL (no vendor default).
-    key: eyJ…                                # Open WebUI JWT (Settings → Account → API Key). Prompted if blank.
-    model: llama3.1:70b                      # Local model tag as `ollama list` shows it.
+    base_uri: https://ollama.local           # REQUIRED for ollama - Open WebUI / ollama-serve base URL (no vendor default).
+    key: eyJ...                                # Open WebUI JWT (Settings → Account → API Key). Prompted if blank.
+    model: <local-model-tag>                 # Local model tag exactly as `ollama list` shows it.
+    embed_model: <embed-model-tag>           # Embedding model for PWN::MemoryIndex (relevance-ranked MEMORY). Must be pulled locally.
     system_role_content: 'You are an ethically hacking Ollama agent.'   # Base system prompt for this engine.
-    temp: 1.0                                # Sampling temperature.
-    max_prompt_length: 32000                 # Soft input-context ceiling (chars) — tune per local model's real context window.
+    temp: 1.0                                # Sampling temperature (used on the FINAL text-only turn - tool-bearing turns are pinned low for deterministic routing).
+    num_ctx: 32768                           # Context window passed to /api/chat options.num_ctx. Ollama's default (2048) is too small for the pwn-ai system prompt.
+    keep_alive: 30m                          # How long ollama keeps the model resident between iterations (avoids reload latency mid-turn).
+    prompt_budget:                           # Per-block caps applied by PromptBuilder.budget so a small model spends attention on the request, not the harness.
+      memory: 6                              # Max MEMORY entries injected (relevance-ranked via PWN::MemoryIndex when available).
+      metrics: 3                             # Max TOOL EFFECTIVENESS rows.
+      mistakes: 3                            # Max KNOWN MISTAKES / FIXES rows.
+      learning: 2                            # Max recent LEARNING outcomes shown.
+      extro: false                           # Gate the (heaviest) EXTROSPECTION block entirely for local models.
+    max_prompt_length: 32000                 # Soft input-context ceiling (chars) - tune per local model's real context window.
+
+  reflect_engine: ~                # Teacher-student reflection: EXECUTE on ai.active, but write durable lessons via THIS engine (nil = same as active). Lets a local model act while a frontier model authors the Memory :lesson entries it reads back.
 
   agent:
     native_tools: true             # Use provider-native tool_calls / function-calling. false → legacy text-parsed tool protocol.
     max_iters: 25                  # Hard cap on tool-call rounds per user turn before a forced final answer.
     max_depth: 3                   # Recursion guard: how many levels deep agent_ask/agent_debate sub-agents may spawn sub-agents.
     auto_introspect: true          # Run Learning.auto_introspect (outcome logging + lesson mining) after every final answer.
-    auto_extrospect: false         # Optional ambient baseline (host/repo/env ONLY — never launches burpsuite/zaproxy/msf/gqrx). Sense tools (intel/verify/watch/rf_tune/observe) stay on-demand.
+    auto_extrospect: false         # Optional ambient baseline (host/repo/env ONLY - never launches burpsuite/zaproxy/msf/gqrx). Sense tools (intel/verify/watch/rf_tune/observe) stay on-demand.
+    plan_first: ~                  # Plan-then-act pre-pass: force the model to externalise a numbered tool plan BEFORE its first dispatch. nil = auto (true when ai.active == ollama).
+    tool_router: false             # Dynamic tool-set slimming: ship only Registry::CORE_TOOLS + top-K keyword-relevant schemas per turn (helps small models route correctly).
+    escalation_persona: ~          # Swarm persona name to ask for a 3-line corrective hint once a local model burns ≥ Loop::ESCALATE_AFTER_FAILS in-turn failures. nil = disabled.
     toolsets: ~                    # Allow-list of toolsets exposed to the agent. nil = all. Valid: cron, extrospection, learning, memory, metrics, pwn, sessions, skills, swarm, terminal.
     extrospection:
       web:
@@ -93,12 +112,12 @@ ai:
         max_anchors: 8             # Cap on how many anchors are rendered per snapshot (protects run time).
         per_page_timeout: 15       # Seconds before a single page render is abandoned and recorded as unreachable.
         screenshot: false          # Persist a PNG per anchor to ~/.pwn/extrospection/web/ (disk-heavy; off by default).
-        allow_targets: false       # true → also merge top-level `targets:` into anchors (opt-in — off so in-scope hosts aren't touched unprompted).
+        allow_targets: false       # true → also merge top-level `targets:` into anchors (opt-in - off so in-scope hosts aren't touched unprompted).
       rf:
         host: 127.0.0.1            # GQRX remote-control host for extro_rf_tune.
         port: 7356                 # GQRX remote-control port.
         settle_secs: 8             # Seconds to sample RDS after tuning (max 30).
-        ttl: 300                   # Observation TTL for :rf (songs change — keep short).
+        ttl: 300                   # Observation TTL for :rf (songs change - keep short).
 
 plugins:
   asm:
@@ -108,15 +127,15 @@ plugins:
     bitcoin:
       rpc_host: localhost          # bitcoind JSON-RPC host for PWN::Blockchain::BTC.
       rpc_port: 8332               # bitcoind JSON-RPC port.
-      rpc_user: …                  # bitcoind RPC username (rpcauth / rpcuser in bitcoin.conf).
-      rpc_pass: …                  # bitcoind RPC password. Redacted in PWN::EnvRedacted.
+      rpc_user: ...                  # bitcoind RPC username (rpcauth / rpcuser in bitcoin.conf).
+      rpc_pass: ...                  # bitcoind RPC password. Redacted in PWN::EnvRedacted.
   hunter:
-    api_key: …                     # hunter.how API key — passed as api_key: to PWN::Plugins::Hunter.search.
+    api_key: ...                     # hunter.how API key - passed as api_key: to PWN::Plugins::Hunter.search.
   jira_data_center:
     base_uri: https://jira.company.com/rest/api/latest   # Jira Data Center REST base URL.
-    token: …                       # Jira Personal Access Token for PWN::Plugins::JiraDataCenter. Redacted.
+    token: ...                       # Jira Personal Access Token for PWN::Plugins::JiraDataCenter. Redacted.
   meshtastic:
-    admin_key: …                   # Public key authorised to send admin messages to mesh nodes via `pwn-mesh`.
+    admin_key: ...                   # Public key authorised to send admin messages to mesh nodes via `pwn-mesh`.
     serial:
       port: /dev/ttyUSB0           # Serial device path for a locally-attached Meshtastic node.
       baud: 115200                 # Serial baud rate.
@@ -131,33 +150,33 @@ plugins:
       pass: large4cats             # MQTT password (public Meshtastic broker default shown). Redacted.
     channel:
       active: LongFast             # Which named channel block below `pwn-mesh` uses for TX/RX.
-      LongFast:                    # Channel definition — name is arbitrary, referenced by `active:` above.
+      LongFast:                    # Channel definition - name is arbitrary, referenced by `active:` above.
         psk: 'AQ=='                # Channel pre-shared key (base64). 'AQ==' = Meshtastic default public key. Redacted.
         region: US/UT              # LoRa region tag (regulatory band).
         topic: 2/e/#               # MQTT topic filter to subscribe/publish for this channel.
         channel_num: 8             # Meshtastic channel index (slot number on the device).
-        from: '!deadbeef'          # Sender node id used on outbound packets. Optional — defaults to !<mqtt client_id>.
+        from: '!deadbeef'          # Sender node id used on outbound packets. Optional - defaults to !<mqtt client_id>.
       PWN:                         # Example second (private) channel definition.
-        psk: …                     # Private channel pre-shared key (base64). Redacted.
+        psk: ...                     # Private channel pre-shared key (base64). Redacted.
         region: US/UT              # LoRa region tag for this channel.
         topic: 2/e/PWN/#           # MQTT topic filter for this channel.
         channel_num: 99            # Meshtastic channel index for this channel.
   shodan:
-    api_key: …                     # Shodan API key — passed as api_key: to PWN::Plugins::Shodan.*. Redacted.
+    api_key: ...                     # Shodan API key - passed as api_key: to PWN::Plugins::Shodan.*. Redacted.
 
 memory:
-  enabled: true                    # Reserve — persistent-memory subsystem on/off (currently always active; future gate).
+  enabled: true                    # Reserve - persistent-memory subsystem on/off (currently always active; future gate).
   provider: file                   # Storage backend for PWN::Memory: file (~/.pwn/memory.json). `sqlite` reserved.
 
 sessions:
-  enabled: true                    # Reserve — transcript recording on/off (currently always active; future gate).
+  enabled: true                    # Reserve - transcript recording on/off (currently always active; future gate).
   provider: jsonl                  # Transcript format under ~/.pwn/sessions/ (one .jsonl per session).
 
 cron:
-  enabled: true                    # Reserve — scheduled-job subsystem on/off (currently always active; future gate).
+  enabled: true                    # Reserve - scheduled-job subsystem on/off (currently always active; future gate).
   provider: yaml                   # Job store format for PWN::Cron (~/.pwn/cron/jobs.yml).
 
-targets:                           # Optional — engagement-scope URLs/hosts. Merged into :web snapshot anchors
+targets:                           # Optional - engagement-scope URLs/hosts. Merged into :web snapshot anchors
   - https://target.example.com     #   ONLY when ai.agent.extrospection.web.allow_targets: true.
 | `ai.agent.extrospection.rf.host` | String | `127.0.0.1` | `Extrospection.rf_tune` | GQRX remote-control host for the RF sense organ. |
 | `ai.agent.extrospection.rf.port` | Integer | `7356` | `Extrospection.rf_tune` | GQRX remote-control port. |
@@ -172,7 +191,7 @@ targets:                           # Optional — engagement-scope URLs/hosts. M
 ```ruby
 PWN::Env[:ai][:active]                          # => :grok
 PWN::Env.dig(:ai, :agent, :max_iters)           # => 25
-PWN::EnvRedacted[:ai][:grok][:key]              # => ">>> REDACTED >>> …"
+PWN::EnvRedacted[:ai][:grok][:key]              # => ">>> REDACTED >>> ..."
 
 # Edit + re-encrypt + reload without leaving the REPL:
 pwn-vault
@@ -185,29 +204,34 @@ PWN::Config.refresh_env
 
 ## Exhaustive key reference
 
-### `ai` — AI engines & agent loop
+### `ai` - AI engines & agent loop
 
 | Key path | Type | Default | Consumed by | Purpose |
 |---|---|---|---|---|
 | `ai.active` | String | `grok` | `PWN::Config.refresh_env`, `PWN::AI::Agent::Loop`, `PWN::Plugins::REPL`, `PWN::Cron` | Which AI engine backs `pwn-ai`. One of `openai` · `anthropic` · `grok` · `gemini` · `ollama`. |
 | `ai.module_reflection` | Boolean | `false` | `PWN::AI::Agent::Reflect`, `PWN::SAST::*`, `PWN::Plugins::BurpSuite` | Master gate for LLM-driven self-analysis (SAST triage, Burp finding enrichment, `Learning.llm_reflect`). |
 | `ai.<engine>.base_uri` | String | provider default | `PWN::AI::<Engine>.rest_call` | Override the API base URL (self-hosted proxy, private endpoint, Azure/VPC gateway). **Required** for `ollama`. |
-| `ai.<engine>.key` | String | — | `PWN::AI::<Engine>` | API key / bearer token. If blank AND no OAuth is configured, PWN prompts interactively at load. |
-| `ai.<engine>.model` | String | provider default | `PWN::AI::<Engine>.chat` / `.chat_tool_loop` | Model id sent on every request (e.g. `grok-4.5`, `gpt-4o`, `claude-3-5-sonnet-20240620`, `gemini-2.5-pro`, `llama3.1:70b`). |
+| `ai.<engine>.key` | String | - | `PWN::AI::<Engine>` | API key / bearer token. If blank AND no OAuth is configured, PWN prompts interactively at load. |
+| `ai.<engine>.model` | String | provider default | `PWN::AI::<Engine>.chat` / `.chat_tool_loop` | Model id sent on every request. Use whatever id the provider / `ollama list` currently exposes - PWN never hard-codes a specific model. |
 | `ai.<engine>.system_role_content` | String | ethical-hacker persona | `PWN::AI::Agent::PromptBuilder`, `PWN::Plugins::REPL` | Base system prompt prepended to MEMORY / SKILLS / LEARNING / EXTROSPECTION blocks. |
 | `ai.<engine>.temp` | Float | `1.0` | `PWN::AI::<Engine>.chat` | Sampling temperature. |
 | `ai.<engine>.max_prompt_length` | Integer | per-engine | `PWN::AI::<Engine>`, `PWN::Plugins::REPL` | Soft input-context ceiling used for prompt truncation / chunking. |
 | `ai.anthropic.max_tokens` | Integer | `8192` | `PWN::AI::Anthropic.chat_tool_loop` | Max **output** tokens per response. Raise if tool-call JSON truncates. |
 | `ai.openai.max_tokens` | Integer | `16384` | `PWN::AI::OpenAI.chat` | Max **output** tokens per response. Mapped to OpenAI's wire param `max_completion_tokens` (legacy env key `max_completion_tokens` still accepted). |
-| `ai.grok.oauth.refresh_token` | String | — | `PWN::AI::Grok.resolve_auth` | Durable OAuth refresh token (from `PWN::AI::Grok.obtain_oauth_bearer_token` device flow). Enables silent re-auth without an API key. |
-| `ai.grok.oauth.bearer_token` | String | — | `PWN::AI::Grok.resolve_auth` | Short-lived OAuth access JWT. Auto-refreshed each run when `refresh_token` is present; live-cached back into this hash. |
+| `ai.ollama.embed_model` | String | provider default | `PWN::MemoryIndex` | Local embedding model tag used to build `~/.pwn/memory.idx` for **relevance-ranked** MEMORY injection. Falls back to substring recall when unset / unreachable. |
+| `ai.ollama.num_ctx` | Integer | `32768` | `PWN::AI::Ollama.chat_with_tools` | Context window sent as `options.num_ctx` on the native `/api/chat` call. Ollama's own default (2048) truncates the pwn-ai system prompt. |
+| `ai.ollama.keep_alive` | String | `30m` | `PWN::AI::Ollama.chat_with_tools` | How long the model stays resident in ollama between iterations of a single turn. |
+| `ai.ollama.prompt_budget` | Hash | `{memory:6, metrics:3, mistakes:3, learning:2, extro:false}` | `PWN::AI::Agent::PromptBuilder.budget` | Per-block caps on injected context so a small local model spends its attention on the request, not the harness. Any engine may set this. |
+| `ai.reflect_engine` | Symbol \| `nil` | `nil` (= `ai.active`) | `PWN::AI::Agent::Reflect.on`, `Learning.reflect` | **Teacher-student** override: run the task on `ai.active`, but generate durable lessons via *this* engine. Lets a local model execute while a frontier model writes the Memory it reads back. |
+| `ai.grok.oauth.refresh_token` | String | - | `PWN::AI::Grok.resolve_auth` | Durable OAuth refresh token (from `PWN::AI::Grok.obtain_oauth_bearer_token` device flow). Enables silent re-auth without an API key. |
+| `ai.grok.oauth.bearer_token` | String | - | `PWN::AI::Grok.resolve_auth` | Short-lived OAuth access JWT. Auto-refreshed each run when `refresh_token` is present; live-cached back into this hash. |
 | `ai.grok.oauth.client_id` | String | Grok-CLI public id | `PWN::AI::Grok` | Override the public OAuth client id used for device-flow / refresh. |
-| `ai.grok.oauth.client_secret` | String | — | `PWN::Config.refresh_env`, `PWN::AI::Grok` | Only for confidential-client OAuth flows. Unused by the default public Grok-CLI client. |
+| `ai.grok.oauth.client_secret` | String | - | `PWN::Config.refresh_env`, `PWN::AI::Grok` | Only for confidential-client OAuth flows. Unused by the default public Grok-CLI client. |
 | `ai.grok.oauth.scope` | String | see example | `PWN::AI::Grok` | OAuth scope string requested during device-flow enrollment. |
 | `ai.grok.oauth.token_uri` | String | `https://auth.x.ai/oauth2/token` | `PWN::AI::Grok` | OAuth token endpoint (override for enterprise IdP). |
 | `ai.grok.oauth.enroll` | Boolean | `false` | `PWN::AI::Grok` | `true` → always run RFC-8628 device-flow enrollment on load, even when `ai.grok.key` is set. |
 
-### `ai.agent` — pwn-ai autonomous loop
+### `ai.agent` - pwn-ai autonomous loop
 
 | Key path | Type | Default | Consumed by | Purpose |
 |---|---|---|---|---|
@@ -217,27 +241,30 @@ PWN::Config.refresh_env
 | `ai.agent.auto_introspect` | Boolean | `true` | `PWN::AI::Agent::Learning.auto_introspect` | Run outcome logging + lesson mining after every final answer. Toggle live via `learning_auto_introspect_toggle`. |
 | `ai.agent.auto_extrospect` | Boolean | `false` | `PWN::AI::Agent::Extrospection.auto_extrospect` | Optional ambient baseline after every final answer (`AUTO_SECTIONS` = host/repo/env only; never spawns GUI/JVM tools). Prefer on-demand sense tools (`intel`/`verify`/`watch`/`rf_tune`/`observe`). Toggle live via `extro_auto_toggle`. |
 | `ai.agent.toolsets` | Array\<String\> \| `nil` | `nil` (all) | `bin/pwn`, `PWN::Plugins::REPL`, `PWN::AI::Agent::Registry` | Allow-list of toolsets exposed to the agent. Valid: `cron`, `extrospection`, `learning`, `memory`, `metrics`, `pwn`, `sessions`, `skills`, `swarm`, `terminal`. |
+| `ai.agent.plan_first` | Boolean \| `nil` | `nil` (auto: `true` when `ai.active == ollama`) | `PWN::AI::Agent::Loop.plan_first` | Plan-then-act pre-pass: the model must emit a numbered tool plan (as an assistant message) *before* it may dispatch anything. Cheap chain-of-thought scaffolding for local models. |
+| `ai.agent.tool_router` | Boolean | `false` | `PWN::AI::Agent::Registry.definitions` | Dynamic tool-set slimming: expose only `Registry::CORE_TOOLS` + the top-K keyword-relevant schemas for *this* request. Ties break on historical `Metrics` success rate so the router itself is a learned component. |
+| `ai.agent.escalation_persona` | String \| `nil` | `nil` | `PWN::AI::Agent::Loop.escalate` → `Swarm.ask` | Circuit-breaker: once a local model accumulates ≥ `Loop::ESCALATE_AFTER_FAILS` in-turn failures, ask this Swarm persona for a 3-line corrective hint (injected as a synthetic tool result). The local model still authors the final answer so Learning/Metrics stay attributed. |
 | `ai.agent.extrospection.web.anchors` | Array\<String\> | `DEFAULT_WEB_ANCHORS` | `PWN::AI::Agent::Extrospection.probe_web` | URLs the headless browser fingerprints on `extro_snapshot(sections:[:web])`. Alias: `web_anchors`. |
-| `ai.agent.extrospection.web.proxy` | String | — | `Extrospection.probe_web` / `.verify` / `.watch` | Upstream proxy for `PWN::Plugins::TransparentBrowser` (e.g. `tor`, `http://127.0.0.1:8080`). |
+| `ai.agent.extrospection.web.proxy` | String | - | `Extrospection.probe_web` / `.verify` / `.watch` | Upstream proxy for `PWN::Plugins::TransparentBrowser` (e.g. `tor`, `http://127.0.0.1:8080`). |
 | `ai.agent.extrospection.web.max_anchors` | Integer | `8` | `Extrospection.probe_web` | Cap on anchors rendered per snapshot. |
 | `ai.agent.extrospection.web.per_page_timeout` | Integer | `15` | `Extrospection` (headless browser) | Seconds before a page render is abandoned. |
 | `ai.agent.extrospection.web.screenshot` | Boolean | `false` | `Extrospection.probe_web` / `.watch` | Persist a PNG per anchor to `~/.pwn/extrospection/web/`. |
-| `ai.agent.extrospection.web.allow_targets` | Boolean | `false` | `Extrospection.web_anchors` | Merge top-level `targets:` into the anchor list (opt-in — off by default to avoid touching in-scope hosts unprompted). |
+| `ai.agent.extrospection.web.allow_targets` | Boolean | `false` | `Extrospection.web_anchors` | Merge top-level `targets:` into the anchor list (opt-in - off by default to avoid touching in-scope hosts unprompted). |
 
-### `plugins` — module credentials & wiring
+### `plugins` - module credentials & wiring
 
 | Key path | Type | Default | Consumed by | Purpose |
 |---|---|---|---|---|
-| `plugins.asm.arch` | String | `DetectOS.arch` | `PWN::Plugins::REPL` (`pwn-asm`) | Target architecture for the inline assembler / disassembler prompt (`x86_64`, `arm64`, …). |
+| `plugins.asm.arch` | String | `DetectOS.arch` | `PWN::Plugins::REPL` (`pwn-asm`) | Target architecture for the inline assembler / disassembler prompt (`x86_64`, `arm64`, ...). |
 | `plugins.asm.endian` | String | `DetectOS.endian` | `PWN::Plugins::REPL` (`pwn-asm`) | Endianness for the inline assembler (`little` / `big`). |
 | `plugins.blockchain.bitcoin.rpc_host` | String | `localhost` | `PWN::Blockchain::BTC` | bitcoind JSON-RPC host. |
 | `plugins.blockchain.bitcoin.rpc_port` | Integer | `8332` | `PWN::Blockchain::BTC` | bitcoind JSON-RPC port. |
-| `plugins.blockchain.bitcoin.rpc_user` | String | — | `PWN::Blockchain::BTC` | bitcoind RPC username. |
-| `plugins.blockchain.bitcoin.rpc_pass` | String | — | `PWN::Blockchain::BTC` | bitcoind RPC password. |
-| `plugins.hunter.api_key` | String | — | `PWN::Plugins::Hunter` | hunter.how API key (passed as `api_key:` to `Hunter.search`). |
-| `plugins.jira_data_center.base_uri` | String | — | `PWN::Plugins::JiraDataCenter` | Jira DC REST base (e.g. `https://jira.company.com/rest/api/latest`). |
-| `plugins.jira_data_center.token` | String | — | `PWN::Plugins::JiraDataCenter` | Jira Personal Access Token. |
-| `plugins.meshtastic.admin_key` | String | — | `PWN::Plugins::REPL` (`pwn-mesh`) | Public key authorised to send admin messages to mesh nodes. |
+| `plugins.blockchain.bitcoin.rpc_user` | String | - | `PWN::Blockchain::BTC` | bitcoind RPC username. |
+| `plugins.blockchain.bitcoin.rpc_pass` | String | - | `PWN::Blockchain::BTC` | bitcoind RPC password. |
+| `plugins.hunter.api_key` | String | - | `PWN::Plugins::Hunter` | hunter.how API key (passed as `api_key:` to `Hunter.search`). |
+| `plugins.jira_data_center.base_uri` | String | - | `PWN::Plugins::JiraDataCenter` | Jira DC REST base (e.g. `https://jira.company.com/rest/api/latest`). |
+| `plugins.jira_data_center.token` | String | - | `PWN::Plugins::JiraDataCenter` | Jira Personal Access Token. |
+| `plugins.meshtastic.admin_key` | String | - | `PWN::Plugins::REPL` (`pwn-mesh`) | Public key authorised to send admin messages to mesh nodes. |
 | `plugins.meshtastic.serial.port` | String | `/dev/ttyUSB0` | `pwn-mesh` (serial) | Serial device path for a locally-attached Meshtastic node. |
 | `plugins.meshtastic.serial.baud` | Integer | `115200` | `pwn-mesh` (serial) | Serial baud rate. |
 | `plugins.meshtastic.serial.bits` | Integer | `8` | `pwn-mesh` (serial) | Serial data bits. |
@@ -250,28 +277,28 @@ PWN::Config.refresh_env
 | `plugins.meshtastic.mqtt.pass` | String | `large4cats` | `pwn-mesh` | MQTT password. |
 | `plugins.meshtastic.channel.active` | String | `LongFast` | `pwn-mesh` | Which named channel block below is used for TX/RX. |
 | `plugins.meshtastic.channel.<NAME>.psk` | String (b64) | `AQ==` | `pwn-mesh` | Channel pre-shared key. |
-| `plugins.meshtastic.channel.<NAME>.region` | String | — | `pwn-mesh` | LoRa region tag (e.g. `US/UT`). |
-| `plugins.meshtastic.channel.<NAME>.topic` | String | — | `pwn-mesh` | MQTT topic filter to subscribe/publish (e.g. `2/e/#`). |
-| `plugins.meshtastic.channel.<NAME>.channel_num` | Integer | — | `pwn-mesh` | Meshtastic channel index. |
+| `plugins.meshtastic.channel.<NAME>.region` | String | - | `pwn-mesh` | LoRa region tag (e.g. `US/UT`). |
+| `plugins.meshtastic.channel.<NAME>.topic` | String | - | `pwn-mesh` | MQTT topic filter to subscribe/publish (e.g. `2/e/#`). |
+| `plugins.meshtastic.channel.<NAME>.channel_num` | Integer | - | `pwn-mesh` | Meshtastic channel index. |
 | `plugins.meshtastic.channel.<NAME>.from` | String | `!<mqtt client_id>` | `pwn-mesh` | Sender node id used on outbound packets. |
-| `plugins.shodan.api_key` | String | — | `PWN::Plugins::Shodan` | Shodan API key (passed as `api_key:` to `Shodan.*`). |
+| `plugins.shodan.api_key` | String | - | `PWN::Plugins::Shodan` | Shodan API key (passed as `api_key:` to `Shodan.*`). |
 
 ### `memory` / `sessions` / `cron`
 
 | Key path | Type | Default | Consumed by | Purpose |
 |---|---|---|---|---|
-| `memory.enabled` | Boolean | `true` | `PWN::Memory` | Reserve — persistent memory on/off (currently always active; future gate). |
+| `memory.enabled` | Boolean | `true` | `PWN::Memory` | Reserve - persistent memory on/off (currently always active; future gate). |
 | `memory.provider` | String | `file` | `PWN::Memory` | Storage backend: `file` (`~/.pwn/memory.json`). `sqlite` reserved. |
-| `sessions.enabled` | Boolean | `true` | `PWN::Sessions` | Reserve — transcript recording on/off (currently always active; future gate). |
+| `sessions.enabled` | Boolean | `true` | `PWN::Sessions` | Reserve - transcript recording on/off (currently always active; future gate). |
 | `sessions.provider` | String | `jsonl` | `PWN::Sessions` | Transcript format under `~/.pwn/sessions/`. |
-| `cron.enabled` | Boolean | `true` | `PWN::Cron` | Reserve — scheduled-job subsystem on/off (currently always active; future gate). |
+| `cron.enabled` | Boolean | `true` | `PWN::Cron` | Reserve - scheduled-job subsystem on/off (currently always active; future gate). |
 | `cron.provider` | String | `yaml` | `PWN::Cron` | Job store format (`~/.pwn/cron/jobs.yml`). |
 
 ### Top-level / miscellaneous
 
 | Key path | Type | Default | Consumed by | Purpose |
 |---|---|---|---|---|
-| `targets` | Array\<String\> | — | `PWN::AI::Agent::Extrospection.web_anchors` | Engagement-scope URLs/hosts. Merged into `:web` snapshot anchors when `ai.agent.extrospection.web.allow_targets: true`. |
+| `targets` | Array\<String\> | - | `PWN::AI::Agent::Extrospection.web_anchors` | Engagement-scope URLs/hosts. Merged into `:web` snapshot anchors when `ai.agent.extrospection.web.allow_targets: true`. |
 
 ---
 
@@ -309,11 +336,11 @@ agent system prompt.
 
 `pwn.yaml` is the only file you edit; everything else is machine-written
 state. See **[Persistence](Persistence.md)** for the full map
-(`memory.json`, `learning.jsonl`, `mistakes.json`, `metrics.json`,
-`extrospection.json`, `sessions/`, `skills/`, `cron/`, `agents.yml`,
-`swarm/`).
+(`memory.json`, `memory.idx`, `learning.jsonl`, `mistakes.json`,
+`metrics.json`, `extrospection.json`, `sessions/`, `skills/`,
+`finetune/`, `cron/`, `agents.yml`, `swarm/`).
 
-Multi-agent personas are **not** configured here — they live in
+Multi-agent personas are **not** configured here - they live in
 `~/.pwn/agents.yml` and are managed with `agent_spawn` / `agent_list`
 (see **[Swarm](Swarm.md)**).
 

data/documentation/Contributing.md

@@ -4,10 +4,11 @@
 
 ```text
 lib/pwn/                # all namespaces
+lib/pwn/setup.rb        # PWN::Setup - doctor/provisioner data tables
 lib/pwn/plugins/        # 66 plugin modules
 lib/pwn/ai/agent/       # agent core
 lib/pwn/ai/agent/tools/ # LLM tool registrations
-bin/                    # 52 pwn_* drivers
+bin/                    # 53 pwn_* drivers (incl. pwn_setup)
 spec/                   # RSpec (incl. conventions_spec)
 documentation/          # this wiki + diagrams
 ```
@@ -15,7 +16,7 @@ documentation/          # this wiki + diagrams
 ## Conventions (enforced by `spec/conventions_spec.rb`)
 
 1. Every public module method is `public_class_method def self.name(opts = {})`.
-2. Every arg-accepting `def self.*` uses **exactly** `(opts = {})` — no
+2. Every arg-accepting `def self.*` uses **exactly** `(opts = {})` - no
    positional args, no keyword args.
 3. Every module has `self.help` returning a usage string.
 4. `# frozen_string_literal: true` at the top of every `.rb`.
@@ -23,9 +24,11 @@ documentation/          # this wiki + diagrams
 ## Quality gates
 
 ```bash
-rvmsudo rake            # rubocop + rspec — must be zero offenses
+rake            # rubocop + rspec - must be zero offenses
 ```
 
+(`rvmsudo rake` on multi-user RVM installs.)
+
 ## Adding a plugin
 
 1. `lib/pwn/plugins/my_thing.rb` following the conventions above.
@@ -34,7 +37,14 @@ rvmsudo rake            # rubocop + rspec — must be zero offenses
 4. Optional `bin/pwn_my_thing` driver (see [Drivers](Drivers.md)).
 5. Optional agent tool in `lib/pwn/ai/agent/tools/` (see
    [Agent Tool Registry](Agent-Tool-Registry.md)).
-6. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
+6. **If it needs a native gem or external binary**, add **one row** to
+   `PWN::Setup::NATIVE_GEMS` or `PWN::Setup::TOOLCHAIN` in
+   `lib/pwn/setup.rb` (with `apt:`/`dnf:`/`pacman:`/`brew:`/`port:` package
+   names + the `plugins:` it unlocks) and, if it belongs in a capability
+   set, reference it from `PWN::Setup::PROFILES`. That single edit makes
+   `pwn setup` install it on every OS and every install path (gem, git,
+   Docker, Packer, Vagrant, CI). **Do not** add a new bash provisioner.
+7. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
    relevant `.dot` in `documentation/diagrams/dot/` → `./build.sh`.
 
 ## Commit / release

data/documentation/Cron.md

@@ -1,4 +1,4 @@
-# Cron — Scheduled Autonomous Jobs
+# Cron - Scheduled Autonomous Jobs
 
 `PWN::Cron` (`lib/pwn/cron.rb`) stores job definitions in
 `~/.pwn/cron/jobs.yml` and can install a matching system-`crontab` line that
@@ -22,7 +22,7 @@ invokes `PWN::Cron.run(<id>)` on schedule.
 | `cron_list` | id · name · schedule · enabled · last_run · last_status |
 | `cron_run(id:)` | Fire immediately (updates last_run/last_status) |
 | `cron_enable` / `cron_disable` | Toggle without deleting |
-| `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab — `crontab -e` yourself) |
+| `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab - `crontab -e` yourself) |
 
 ## Example
 
@@ -38,8 +38,8 @@ cron_create(
 
 At 02:00 the system cron fires `PWN::Cron.run`, which spins up a headless
 `pwn-ai` turn. With `auto_introspect` on (and optional `auto_extrospect` for
-the cheap `AUTO_SECTIONS` baseline), the run updates Learning/Metrics — and,
-if enabled, host/repo/env posture — so tomorrow's interactive session already
+the cheap `AUTO_SECTIONS` baseline), the run updates Learning/Metrics - and,
+if enabled, host/repo/env posture - so tomorrow's interactive session already
 knows what changed overnight. Sense tools (`intel`/`verify`/`watch`) stay
 on-demand; cron is not expected to launch Burp/ZAP/msf/GQRX.
 
@@ -54,7 +54,7 @@ cron_create(
 Weekly, headless-browser fact-check of every `PWN::Memory` `:fact` containing
 a CVE / version string / URL. Refuted entries get prefixed `[UNVERIFIED
 yyyy-mm-dd]` so the injected MEMORY block stops calcifying into
-confidently-wrong priors — see [Extrospection § revalidate_memory](Extrospection.md).
+confidently-wrong priors - see [Extrospection § revalidate_memory](Extrospection.md).
 
 **See also:** [Sessions](Sessions.md) · [Extrospection](Extrospection.md) ·
 [CLI Drivers](CLI-Drivers.md)

data/documentation/Diagrams.md

@@ -51,7 +51,7 @@ groups) so lines never criss-cross.
 [source](diagrams/dot/pwn-ai-feedback-learning-loop.dot) · doc: [Skills, Memory & Learning](Skills-Memory-Learning.md)
 ![pwn-ai-feedback-learning-loop](diagrams/pwn-ai-feedback-learning-loop.svg)
 
-### Mistakes — Negative-Feedback Loop
+### Mistakes - Negative-Feedback Loop
 [source](diagrams/dot/mistakes-negative-feedback.dot) · doc: [Mistakes](Mistakes.md)
 ![mistakes-negative-feedback](diagrams/mistakes-negative-feedback.svg)
 
@@ -67,15 +67,15 @@ groups) so lines never criss-cross.
 [source](diagrams/dot/memory-skills-detailed.dot) · doc: [Skills, Memory & Learning](Skills-Memory-Learning.md)
 ![memory-skills-detailed](diagrams/memory-skills-detailed.svg)
 
-### Extrospection — World Awareness
+### Extrospection - World Awareness
 [source](diagrams/dot/extrospection-world-awareness.dot) · doc: [Extrospection](Extrospection.md)
 ![extrospection-world-awareness](diagrams/extrospection-world-awareness.svg)
 
-### Swarm — Native Multi-Agent
+### Swarm - Native Multi-Agent
 [source](diagrams/dot/swarm-multi-agent.dot) · doc: [Swarm](Swarm.md)
 ![swarm-multi-agent](diagrams/swarm-multi-agent.svg)
 
-### Cron — Scheduled Jobs
+### Cron - Scheduled Jobs
 [source](diagrams/dot/cron-scheduling.dot) · doc: [Cron](Cron.md)
 ![cron-scheduling](diagrams/cron-scheduling.svg)
 

data/documentation/Drivers.md

@@ -1,4 +1,4 @@
-# Drivers — Turn a REPL Session into a Shipped Binary
+# Drivers - Turn a REPL Session into a Shipped Binary
 
 A **driver** is a small executable in `bin/` that wires `OptionParser` to one
 or more `PWN::` calls. All 52 shipped `pwn_*` binaries follow the same
@@ -38,13 +38,13 @@ PWN::Reports::Fuzz.generate(result: result, dir_path: opts[:out]) if opts[:out]
 puts result
 ```
 
-## Three artefact types from one REPL session
+## Three artifact types from one REPL session
 
-| Artefact | Made with | Consumed by |
+| Artifact | Made with | Consumed by |
 |---|---|---|
 | `bin/pwn_<name>` | template above | shell / CI |
 | `~/.pwn/skills/<name>.md` | `learning_distill_skill` | every future pwn-ai prompt |
-| `cron` job | `cron_create(ruby: '…')` | system crontab → unattended |
+| `cron` job | `cron_create(ruby: '...')` | system crontab → unattended |
 
 **See also:** [CLI Drivers](CLI-Drivers.md) · [Cron](Cron.md) ·
 [Skills, Memory & Learning](Skills-Memory-Learning.md)