pwn 0.5.780 → 0.5.782

data/documentation/FFI.md

@@ -1,7 +1,7 @@
 # `PWN::FFI` - Native Calls for DSP & RF Front-Ends
 
-Thin `ffi`-gem bindings to **already-installed** system shared objects. Nothing
-is compiled at `gem install` time, nothing shells out. If a `.so` is missing the
+Thin `ffi`-gem bindings to **already-installed** system shared objects. The binding wrappers do not compile at `gem install` time or shell out.
+Optional bundled DSP acceleration requires a separate explicit build. If a `.so` is missing the
 module still loads and `.available?` returns `false` so callers fall back to
 pure Ruby.
 
@@ -35,6 +35,8 @@ as `ok` / `MISSING` and knows the correct package name on `apt` / `dnf` /
 | **`HackRF`** | `libhackrf` | Open/tune/rate/gains + **callback RX streaming** (`start_rx`/`read_sync`/`stop_rx`/`capture`) of raw cs8 I/Q. |
 | **`AdalmPluto`** | `libiio` (+ `libad9361`) | ADALM-Pluto (ad9361-phy). `open`/`configure`/`start_rx`/`read_sync`/`stop_rx`/`capture` of cs16 I/Q; USB or `ip:192.168.2.1`. |
 | **`SoapySDR`** | `libSoapySDR` | Enumerate every Soapy-backed front-end (RTL-SDR, HackRF, Airspy, Pluto, LimeSDR, UHD, ...) **and** stream cs16 I/Q from any of them (`open`/`configure`/`start_rx`/`read_sync`/`stop_rx`/`close`). |
+| `DSPNative` | bundled PWN DSP shared object | Optional packed DSP kernels; requires an explicit native build |
+| `Capstone` / `Keystone` | libcapstone / libkeystone | Optional disassembly/assembly backends |
 | `Stdio` | `libc` | Classic `puts` / `printf` / `scanf` for shellcode / format-string research. |
 
 ## Design rules
@@ -44,8 +46,8 @@ as `ok` / `MISSING` and knows the correct package name on `apt` / `dnf` /
 2. **No install-time compile.** Use the system package (`libvolk-dev`,
    `libliquid-dev`, `libfftw3-dev`, `libhackrf-dev`, `libiio-dev`, ...). Install
    them all with **`pwn setup --profile sdr`** (see [Installation](Installation.md)).
-   On hosts without them every `.available?` is `false` and pure-Ruby paths
-   keep working.
+   Missing numerical backends can use supported Ruby fallbacks; missing
+   radio libraries cannot manufacture hardware I/O or protocol support.
 3. **Namespace hygiene.** `PubFFI = ::FFI` (defined once in `lib/pwn/ffi.rb`)
    avoids the `PWN::FFI` vs `::FFI` collision when modules `extend PubFFI::Library`.
 4. **Uniform front-end contract.** Every hardware binding exposes the same
@@ -86,29 +88,17 @@ PWN::FFI::SoapySDR.close(handle: h)
 iq = PWN::FFI::HackRF.capture(freq_hz: 1_090_000_000, rate_hz: 2_000_000, samples: 262_144)
 ```
 
-## True-air decode: how this drives `PWN::SDR::Decoder::*`
+## Decoder integration boundaries
 
-Every decoder module now has a **true over-the-air I/Q path** via
-`PWN::SDR::Decoder::Base.run_iq`, which:
+Shared Base/DSP code can use these bindings for integer IQ streams and numerical
+acceleration. Available bindings are not proof of a connected radio, supported
+protocol mode, sufficient sample rate or realtime throughput. A detector output
+is not a decoded payload. Protocol entry points and required native processes
+are documented in [SDR Decoder Coverage](SDR-Decoder-Coverage.md).
 
-1. Calls `Base.resolve_iq_source(source: :auto)` to pick the first working
-   front-end in order `:file` -> `:rtlsdr` -> `:adalm_pluto` -> `:hackrf` ->
-   `:soapy` (or a forced `:source`).
-2. Streams raw I/Q via the uniform `read_sync` contract above.
-3. Unpacks (`cu8`/`cs8`/`cs16`) and either hands complex samples to
-   `demod#feed_iq(iq, rate:)` or FM-demodulates first and calls
-   `demod#feed(audio)` for narrowband protocols.
-4. Emits the same JSONL-logged Hash frames every decoder already produces.
-5. Falls back to `Base.run_detector` (energy characterizer) when no hardware
-   or capture file is present, so the operator still gets structured output.
-
-| Decoder | Air path | I/Q entry point |
-|---|---|---|
-| ADSB, Bluetooth, DECT, GPS, GSM, Iridium, LoRa, LTE, P25, RFID, RTL433, WiFi, ZigBee | `run_iq` (wideband) | `#feed_iq(iq, rate:)` |
-| APT, FLEX, Morse, Pager, POCSAG, RTTY | `run_iq(fm_demod: true)` or `run_native` (GQRX 48 kHz UDP) | `#feed(audio)` |
-| RDS | GQRX built-in RDS decoder (`RDS.sample`) | n/a |
-
-No decoder shells out; Ruby remains the orchestrator.
+Some protocol modes invoke native executables (for example `rtl_433`, `proxmark3`,
+`gnss-sdr`, `redsea` and the LTE bridge); “no decoder shells out” is not a current
+contract. Keep offline fixture, native-backend and live RF evidence separate.
 
 **See also:** [SDR](SDR.md) - [Hardware](Hardware.md)
 

data/documentation/Fuzzing.md

@@ -8,31 +8,31 @@
 ## Generate
 
 ```ruby
-payloads = PWN::Plugins::Fuzz.generate(
-  seed: "GET / HTTP/1.1\r\nHost: t\r\n\r\n",
-  strategy: :radamsa,       # :radamsa | :bitflip | :dictionary
-  count: 500
+payloads = PWN::Plugins::Fuzz.http(
+  request: "GET /FUZZ HTTP/1.1\r\nHost: lab.invalid\r\n\r\n",
+  dictionary: ['a', 'long-input', '%00']
 )
-enc = PWN::Plugins::Char.url_encode(str: payloads.first)
 ```
 
 ## Deliver
 
 ```ruby
-payloads.each do |p|
-  PWN::Plugins::Sock.connect(target: '10.0.0.5', port: 8080) do |s|
-    s.write(p); s.read
-  end
-end
+# For authorized network tests, Fuzz.socket accepts target:, port:, request:,
+# payload: and fuzz_delimeter:. Inspect its help for timeout/encoding controls.
+PWN::Plugins::Fuzz.help
 ```
 
 For raw L2/L3: `PWN::Plugins::Packet`.
-CLI network fuzzer: `pwn_fuzz_net_app_proto -t HOST -p PORT -f seeds/`
+CLI network fuzzer: `pwn_fuzz_net_app_proto --help` (requires a payload **file**,
+request template and output directory; not `-f seeds/`).
 
 ## Monitor & report
 
-`PWN::Plugins::PS` watches the target process; `PWN::Plugins::Log` tails its
-log; `PWN::Reports::Fuzz` renders crash → HTML/JSON.
+`Fuzz.http` expands templates only; it does not send traffic. `Fuzz.file_format`
+appends dictionary blobs to a seed. `Fuzz.triage` deduplicates existing crash
+files by hash and selects the smallest reproducer. `PWN::Reports::Fuzz.generate`
+expects a `results_hash:` and output `dir_path:`; it is not a crash detector.
+Use explicit target monitoring and retain actual crash evidence.
 
 Feed unique crashes back as new seeds (`Log → Fuzz` dashed edge in the diagram).
 

data/documentation/General-PWN-Usage.md

@@ -5,7 +5,7 @@
 ```bash
 $ pwn                         # interactive REPL
 $ pwn --ai "scan 10.0.0.0/24 with NmapIt and summarize open services"
-$ pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/   # headless driver
+$ pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -r out/   # headless driver
 ```
 
 ## Check / provision this host
@@ -24,7 +24,7 @@ See [Installation](Installation.md) for every flag and the
 
 ```ruby
 PWN.help                            # top-level help
-PWN::Plugins.constants.sort         # list all 67 plugins
+PWN::Plugins.constants.sort         # list all 107 plugins
 PWN::Plugins::NmapIt.help           # per-plugin usage
 PWN::Setup.check                    # capability doctor from inside the REPL
 PWN::Migrate.status                 # ~/.pwn state-file compatibility rows
@@ -45,7 +45,7 @@ history                             # what you've typed → copy into a driver
 | `pwn-ai-sessions` | List / view / delete transcripts |
 | `pwn-ai-cron` | List / run scheduled jobs |
 | `pwn-ai-delegate` | Hand a task to a Swarm persona |
-| `toggle-debug` | Stage log per request to `/tmp/pwn-ai-DEBUG-<SESSION_ID>-RN.log` |
+| `toggle-debug` | Stage log per request to `~/.pwn/logs/pwn-ai-DEBUG-<SESSION_ID>-R<N>.log` (or `PWN_DEBUG_DIR`) |
 | `toggle-trace` | Same as `toggle-debug` plus TracePoint; ENTER after each loop step. Pry.config, not Env. Off turns both off. |
 | `toggle-pwn-ai-speaks` | TTS every final answer on/off |
 | `welcome-banner` | Redraw a random `PWN::Banner` |
@@ -141,7 +141,10 @@ scan = PWN::Plugins::BurpSuite.active_scan(burp_obj: burp,
          target_url: 'http://scanme.nmap.org')
 
 # 4. report
-PWN::Reports::SAST.generate(dir_path: '/tmp/src', output_dir: '/tmp/out')
+# Burp output is not SAST input; use its own report generator.
+PWN::Plugins::BurpSuite.generate_scan_report(
+  burp_obj: burp, target_url: 'http://scanme.nmap.org',
+  output_dir: '/tmp/out', report_type: 'HTML')
 ```
 
 Then say the same thing in English inside `pwn-ai` and watch the agent do it.

data/documentation/Harness-Evaluation.md

@@ -1,5 +1,90 @@
 # Deployment fingerprints and fair harness evaluation
 
+## Evidence-backed improvement lifecycle
+
+This extends the existing `Verification` → `Reward` → `Learning` ledger and
+`PolicyEvaluation`/RSpec harness; there is no second evaluator or automatic
+self-promotion loop.
+
+### Completion accounting
+
+`Reward.resolve_outcome` exposes `verified_completion` independently of the
+legacy judge-quality `success` field. It is true only for complete host check
+coverage, false for a verifier failure, and null when evidence is unavailable.
+`Reward.judge` preserves the evaluator's pre-verification `solved` verdict in
+`claimed_completion`. `false_completion` is true when that claim is independently
+refuted, null when a claim has not been checked, and false for a checked pass or
+an explicit nonclaim. These are **judge claims**, not a semantic classifier of
+arbitrary assistant prose. Trusted host callers may explicitly supply the claim
+to `resolve_outcome`; model-facing tools cannot create trusted checks.
+
+`Learning.note_outcome` persists these fields without reinterpreting them.
+`Learning.stats` reports completion claims, checked claims, verified completions,
+false completions, and a false-completion rate whose denominator is **checked
+claims**, not all attempts. The rate is null without checked claims. Old ledger
+rows remain unknown for these new metrics; no migration fabricates labels.
+Existing quality scores and training eligibility retain their previous semantics;
+use verified completion, not legacy success rate, as acceptance evidence.
+
+The executable harness independently counts a released success marker as false
+success whenever the whole run is not PASS. Empty checks, failed processes and
+resource-capped runs cannot hide behind correct bytes or vacuous `all?` checks.
+The locked `completion_regressions.json` corpus records those source-reproduced
+accounting defects; RSpec executes it alongside the existing CLI fault lanes.
+
+### Turn observed failures into reviewable regressions
+
+Use the exact persisted outcome ID, original request, and independently authored
+expected bytes (never derive gold from the failed answer):
+
+```ruby
+recipe = PWN::AI::Agent::Learning.regression_task(
+  outcome_id: failure_id,
+  request: original_request,
+  checks: [{ requirement: original_request, kind: :file,
+             path: 'result.txt', expected: "correct\n" }]
+)
+# Within an RSpec example, using a fresh disposable fixture directory:
+report = PWN::AI::Agent::Verification.run(recipe[:contract].merge(root: fixture_root))
+expect(report[:status]).to eq(:pass)
+```
+
+Export is read-only and only accepts a persisted verifier failure among the most
+recent 10,000 outcomes. The request digest and original requirement coverage must
+match. Recipes contain source outcome identity, verification/contract SHA-256,
+and a fixed `regression` split. Only relative file/JSON checks are supported;
+commands, HTTP checks and raw tool traces are not mined or executed. Expected
+content remains an operator-reviewed input, not independently attested history.
+Review/redact the request and gold before saving a recipe in `spec/fixtures/harness`
+and add its reproduction/setup under RSpec. Do not put an inspected regression in
+the held-out split. The recipe itself verifies outputs; it does not autonomously
+replay potentially destructive historical actions.
+
+### Frozen acceptance and versioned local promotion
+
+Reuse the existing policy CLI (`pwn-ai --policy evaluate`, `promote`, `rollback`)
+and frozen snapshots, rather than updating live stores during evaluation.
+`PolicyEvaluation.evaluate` runs the existing standalone worker with a cleared
+environment and disposable HOME; off/baseline/candidate use frozen policy bytes
+and independently checked tasks. The split-corpus executable experiments clone
+frozen training HOMEs per trial, check input/snapshot hashes and reject duplicate
+cross-split prompts or inputs. The held-out set is public and fixed: it tests
+infrastructure and this local controller, not general live model intelligence.
+
+Promotion still re-executes each submitted acceptance report, checks provenance,
+requires both filesystem environments, rejects aggregate **and per-task**
+regressions, and requires an independent held-out gain. Successful receipts now
+include `receipt_version: 1`, `change_kind: routing_policy`, and
+`acceptance_sha256` over deterministic fresh reports in addition to exact baseline
+and candidate digests. Preserve the returned JSON in a distinct receipt file.
+Rollback requires that successful versioned receipt and refuses intervening live
+updates or changed backups. Old unversioned receipts are deliberately rejected;
+retain their backups for explicit operator recovery rather than guessing a version.
+These receipts are local audit records, not cryptographic attestations against a
+hostile local writer. Both writes still require explicit approval, an explicit
+live path and operator-attested stopped policy writers. This does not promote
+arbitrary skills, model weights or external service changes.
+
 ## Deployment diagnosis
 
 `PWN::RuntimeFingerprint.report(expected_root: '/intended/gem/lib')` is read-only.
@@ -179,10 +264,12 @@ Unknown usage/cost and uninstrumented all-learning activity remain null. The
 parent supervisor kills the process group on wall cap and records INCOMPLETE,
 never success. A generic child error is not silently converted into a pass.
 
-## Recorded offline integration acceptance
+## Historical offline integration acceptance
 
-Final integration artifacts are retained under `/tmp/pwn-harness-final-acceptance`.
-These are local execution results, not live provider scores:
+The prior integration recorded artifacts under `/tmp/pwn-harness-final-acceptance`.
+That temporary path is not a shipped or durable evidence archive. The following
+counts describe that historical run, not a rerun of the current checkout or live
+provider scores; reproduce the commands above for current acceptance:
 
 - `HOME=/tmp/pwn-harness-final-acceptance/home bundle exec rake`:
   **4369 examples, 0 failures**, then **1150 files, no RuboCop offenses**, exit 0

data/documentation/Home.md

@@ -2,7 +2,7 @@
 
 > **PWN** (/pōn/) - an open-source offensive-security automation framework and
 > continuous-security-integration platform written in Ruby.
-> 67 plugins · 48 SAST modules · 90 AWS wrappers · 22 WWW drivers · 54 CLI
+> 107 plugins · 48 SAST modules · 90 AWS wrappers · 22 WWW drivers · 56 CLI
 > executables · 6 LLM engines · a self-improving multi-agent AI · one REPL.
 
 **Repo root:** `/opt/pwn` · **This wiki:** `/opt/pwn/documentation/` ·
@@ -19,6 +19,7 @@
 | [How PWN Works](How-PWN-Works.md) | The five layers, with the architecture diagram |
 | [Installation](Installation.md) | `gem install --verbose pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
+| [Operability and Evidence](Operability.md) | Completion, regressions, frozen evaluation, mesh and deployment boundaries |
 | [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
 | **[All Data-Flow Diagrams](Diagrams.md)** | **29 SVGs** in one scrollable page |
 
@@ -28,7 +29,7 @@
 |---|---|
 | [The `pwn` REPL](pwn-REPL.md) | Pry shell with the whole `PWN::` namespace pre-loaded |
 | [`pwn-ai` Autonomous Agent](pwn-ai-Agent.md) | Natural-language TUI + `pwn --ai PROMPT` one-shot · **TaskSummarizer** briefs · CORE_TOOLS until `may_finalize?` |
-| [CLI Drivers `bin/pwn_*`](CLI-Drivers.md) | 54 headless executables (`pwn` + 53 `pwn_*`) for CI/CD |
+| [CLI Drivers `bin/pwn_*`](CLI-Drivers.md) | 56 executables (`pwn`, `pwn-ai`, `pwn-capd` + 53 `pwn_*`) for CI/CD |
 | [Drivers (build your own)](Drivers.md) | Turn a REPL session into a shipped binary |
 
 ## 🤖 AI Subsystem  (`PWN::AI`)
@@ -37,7 +38,7 @@
 |---|---|
 | [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama · Open WebUI |
 | [Agent Tool Registry](Agent-Tool-Registry.md) | 16 toolsets · **150** LLM-callable tools |
-| [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection - self-improvement loop + 10 bundled skills on first launch |
+| [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection, reviewed skill updates and bundled SOP/module skills on first launch |
 | [Mistakes](Mistakes.md) | **Negative feedback** - fingerprint failures · do-NOT-repeat · `[REPEATING]`/`[REGRESSED]` · inline self-correction |
 | [Reinforcement Learning](Reinforcement-Learning.md) | **`Reward` + `Curriculum` + `Policy`** - outcome/process judges · preference ledger · self-play practice · live Q / REINFORCE (advisory) · export-ready LoRA gate |
 | [Extrospection](Extrospection.md) | World-awareness - snapshot · drift · intel · **watch** · **verify** · **rf_tune** · **osint** · serial · telecomm · packet · vision · voice · correlate |
@@ -50,7 +51,7 @@
 
 | | |
 |---|---|
-| [Plugins (67)](Plugins.md) | Every `PWN::Plugins::*` module by category |
+| [Plugins (107)](Plugins.md) | Every `PWN::Plugins::*` module by category |
 |   ↳ [BurpSuite](BurpSuite.md) ⭐ | Preferred web proxy / scanner |
 |   ↳ [TransparentBrowser](Transparent-Browser.md) | Headless / visible browser automation |
 |   ↳ [NmapIt](NmapIt.md) | Network discovery |
@@ -60,7 +61,7 @@
 | [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
 | [WWW (22 drivers)](WWW.md) | Browser automations for real sites |
 | [AWS (90 services)](AWS.md) | Cloud-security enumeration |
-| [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro · **Decoder::* (20 protocols + Base/DSP)** · FFI-accelerated DSP |
+| [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro · **Decoder::* (21 protocols + Base/DSP)** · FFI-accelerated DSP |
 | [Blockchain](Blockchain.md) | BTC · ETH helpers |
 | [Bounty](Bounty.md) | Lifecycle / auth-replay tooling |
 | [Reports](Reporting.md) | HTML/JSON output + DefectDojo/Jira |

data/documentation/How-PWN-Works.md

@@ -1,8 +1,7 @@
 # How PWN Works
 
-PWN is five layers, each visible in the source tree. Edges only go
-**down** one layer (or sideways within a layer), which is why the diagrams
-below have no criss-crossing lines.
+This conceptual layer map groups entry points, agent control, capabilities and
+persistence. Feedback and cross-layer calls are explicit; layout is not a call graph.
 
 ![Overall Architecture](diagrams/overall-pwn-architecture.svg)
 
@@ -20,7 +19,7 @@ hardware).
 | `pwn-ai` | `lib/pwn/ai/agent/loop.rb` | Agent TUI inside the REPL |
 | `pwn --ai PROMPT` | `bin/pwn` | Headless one-shot agent (CI-friendly) |
 | `pwn setup` | `lib/pwn/setup.rb` · `bin/pwn_setup` | Post-install doctor + capability provisioner + `--migrate` state doctor (also `pwn --setup[=PROFILE]`) |
-| `bin/pwn_*` + `pwn` | 54 files | Thin OptionParser wrappers plus the `pwn` REPL / one-shot agent |
+| `bin/` (including `pwn-ai` and `pwn-capd`) | 56 files | Thin OptionParser wrappers plus the `pwn` REPL / one-shot agent |
 | `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs + background worker (`pwn setup`). Fresh install seeds hygiene on (`learning_consolidate_nightly`, `pwn_stores_lean_nightly`) and curriculum practice/judge/train off |
 
 ## L2 - AI agent core (`lib/pwn/ai/agent/`)
@@ -29,7 +28,7 @@ hardware).
 |---|---|
 | `Loop` | plan → **TaskSummarizer** briefs → dispatch tool_calls → observe → repeat until `may_finalize?`. No iteration-budget abort |
 | **`TaskSummarizer`** | Executive UX: every request gets an English task compass (`emit_plan!` · `about_to` as `task k/n`) - no statement/question/goal type |
-| `Registry` | JSON-Schema function definitions grouped into 16 **toolsets** · **150 tools** · `CORE_TOOLS` = `DEFAULT_PREFERENCE` (`memory_recall` · `session_recall` · `skills_recall` · `pwn_eval` · `shell` · `mistakes_record` · `mistakes_resolve` · `learning_note_outcome` · `memory_remember` · `skills_update` · `artifact_read` · `artifact_grep`) |
+| `Registry` | JSON-Schema function definitions grouped into 16 **toolsets** · **150 tools** · `CORE_TOOLS` = `DEFAULT_PREFERENCE` (`memory_recall` · `session_recall` · `skills_recall` · `pwn_eval` · `shell` · `mistakes_record` · `mistakes_resolve` · `learning_note_outcome` · `memory_remember` · `skills_update` · `artifact_read` · `artifact_grep` · `job_run` · `job_status` · `job_tail` · `job_result` · `job_kill`) |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / **POLICY** / EXTROSPECTION / RECENT TURNS |
 | `Metrics` · `Learning` · `Reflect` · **`Policy`** | **introspection** - how well am I doing? (Policy is live Q / REINFORCE, advisory rank only) |
@@ -45,14 +44,14 @@ call, and [Reinforcement Learning](Reinforcement-Learning.md) for how
 
 ## L3 - Capability namespaces (`lib/pwn/*`)
 
-`Plugins` (67) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
+`Plugins` (107) · `SAST` (48) · `WWW` (22) · `AWS` (90) · `SDR` · `Blockchain` ·
 `Bounty` · `Reports` · `FFI` · `Banner` · **`Setup`** · **`Migrate`**. First launch also seeds bundled skills from `etc/default_skills/`. Each is
 a plain module of `public_class_method def self.x(opts = {})` methods -
 callable the same way from the REPL, from `pwn_eval`, or from a driver.
 
 ## L4 - Persistence (`~/.pwn/`)
 
-Everything the framework remembers between processes lives in one directory.
+Most default user state lives under `~/.pwn`; explicit outputs and worktrees may live elsewhere.
 `PWN::Migrate` (schema-stamped, idempotent, dry-run capable) verifies and
 autofixes every file in it after a `gem update pwn`:
 
@@ -64,14 +63,14 @@ for the migrator.
 
 ## The feedback loop
 
-L2 exists to close this loop on every turn - successes become skills and
-lessons, **failures become fingerprinted mistakes with fixes**, **world state
+L2 records outcomes and may propose skills or lessons; routine success does not
+automatically create a skill. In the feedback loop, **failures become fingerprinted mistakes with fixes**, **world state
 is sensed on demand** (`extro_verify` / `extro_watch` / `extro_rf_tune` /
 `extro_osint` / `extro_serial` / `extro_telecomm` / `extro_packet` /
 `extro_vision` / `extro_voice` / `extro_intel`) and correlated against those
 failures, a **cheap LLM judge scores the final answer** (token overlap only if the engine is unavailable) and a **process reward
 model tags each tool step**, **Policy records the live MDP step** and updates
-Q / REINFORCE when the judge scores the turn, and **the prompt blocks**
+Q / REINFORCE only for eligible resolved outcomes with independently attributed positive credit, and **the prompt blocks**
 (MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS ·
 POLICY · EXTROSPECTION · RECENT TURNS) are re-injected into the next system
 prompt.

data/documentation/Installation.md

@@ -5,7 +5,7 @@ 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 --verbose pwn      # 1. get the gem (pure-Ruby core always works)
+gem install --verbose pwn      # 1. install the gem and its Ruby/native dependencies
 pwn setup            # 2. doctor + provision this host's capabilities
 ```
 
@@ -16,7 +16,7 @@ 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**
+Provisioning mappings cover **Kali / Debian / Ubuntu**, **Fedora**, **Arch**, and **macOS**
 (Homebrew or MacPorts). Ruby ≥ 3.3 (RVM, rbenv, asdf, or system Ruby).
 
 ---
@@ -230,9 +230,8 @@ malformed or unsafe stores; cleanup fails closed when it is nonempty.
 The shared index follows defined structural fields, not ID-looking text.
 Dependency-backed sessions remain visible and resumable, not archived away.
 Vault/config/credential payloads and historical backups are not scanned.
-Same-user interactive PWN
-processes defer deletion because existing writers have no lifetime leases; this is a
-conservative guard, not a cross-process session lease. Inspect without deleting:
+Current writers hold per-session lifetime leases; legacy installed writers
+without that protocol cause conservative ownership uncertainty. Inspect without deleting:
 `ruby ~/.pwn/cron/session_cleanup.rb --dry-run`.
 
 `--apply` backs up eligible transcript/metadata bytes under
@@ -334,10 +333,12 @@ lists have been consolidated into `PWN::Setup::NATIVE_GEMS` / `::TOOLCHAIN`.
 
 `pwn setup` is the single provisioning entry point for every image builder:
 
-```dockerfile
-FROM kalilinux/kali-rolling
-RUN gem install --verbose pwn && pwn setup --profile full --yes
-```
+Start from an image with a supported Ruby, RubyGems, compiler and required
+native gem headers already installed. A bare `kalilinux/kali-rolling` image does
+not establish those prerequisites. Review the repository Dockerfile/provisioners,
+pin the base and gem version for reproducible deployments, then explicitly run
+`gem install --verbose pwn` and the chosen `pwn setup --profile` command.
+Image build success is not live provider/radio/browser acceptance.
 
 ```yaml
 # .gitlab-ci.yml - fail the job if the runner is missing a capability
@@ -378,7 +379,7 @@ The first `pwn` launch creates `~/.pwn/` and an **encrypted**
 Source lives in the gem at `etc/default_skills/`. `PWN::Config.install_default_skills`
 walks every `SKILL.md` recursively (idempotent SOP copies; never overwrites an
 edited SOP `SKILL.md`). Generated module skills under `etc/default_skills/pwn/`
-`PWN::` module, plus `references/` when the source has CWE/NIST/URLs) are
+(one per `PWN::` module, plus `references/` when the source has CWE/NIST/URLs) are
 copied to `~/.pwn/skills/pwn/` and **are** overwritten on
 `pwn setup --migrate` / first launch so they stay in sync with `lib/pwn`.
 `bundle exec rake` does not rewrite `etc/default_skills/pwn`. `rake module_skills`
@@ -449,7 +450,7 @@ Vagrant, CI) picks it up automatically.
 ```ruby
 pwn[CURRENT_VERSION]:001 >>> PWN::Setup.check[:ok]          # => true
 pwn[CURRENT_VERSION]:002 >>> PWN::Migrate.needed?           # => false
-pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 67
+pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 107
 pwn[CURRENT_VERSION]:004 >>> PWN::SAST.constants.count      # => 48
 pwn[CURRENT_VERSION]:005 >>> pwn-ai                         # launches agent TUI
 ```

data/documentation/Metasploit.md

@@ -8,30 +8,24 @@ with sessions, all from Ruby.
 
 ## Configure
 
-```yaml
-# ~/.pwn/pwn.yaml  (edit via `pwn-vault`)
-metasploit:
-  host: 127.0.0.1
-  port: 55553
-  user: msf
-  pass: ...
-```
-
-Start the daemon: `msfrpcd -U msf -P ... -a 127.0.0.1 -p 55553 -S`
+`connect(yaml_conf:)` reads a separate operator-owned YAML file, not the
+`metasploit:` block in the encrypted PWN vault. Required keys are
+`msfrpcd_host`, `port`, `username`, and `password`. Keep that file private and
+use only a trusted local daemon or protected transport. Without `yaml_conf`,
+the legacy provider file is resolved using `PWN_ROOT` and `PWN_PROVIDER`.
+Review `msfrpcd --help` for daemon transport/authentication settings; no daemon
+or credential enrollment is performed by this documentation check.
 
 ## Use
 
 ```ruby
-msf = PWN::Plugins::Metasploit.connect
-mods = PWN::Plugins::Metasploit.search(msf_obj: msf, query: 'jenkins')
-PWN::Plugins::Metasploit.use(msf_obj: msf,
-  module_type: 'exploit',
-  module_name: 'multi/http/jenkins_script_console')
-PWN::Plugins::Metasploit.set_option(msf_obj: msf, opt: 'RHOSTS', val: '10.0.0.5')
-job = PWN::Plugins::Metasploit.run(msf_obj: msf)
-PWN::Plugins::Metasploit.sessions(msf_obj: msf)
+console = PWN::Plugins::Metasploit.connect(yaml_conf: '/path/to/metasploit.yaml')
+PWN::Plugins::Metasploit.console_exec(console_obj: console, cmd: 'search jenkins')
+# Further commands use the same console_exec interface; inspect results before
+# executing a module. This example does not launch an exploit.
+PWN::Plugins::Metasploit.disconnect(console_obj: console)
 ```
 
-CLI: `pwn_msf_postgres_login -H 10.0.0.5 -U users.txt -P pass.txt`
+CLI: `pwn_msf_postgres_login /path/to/private-msfrpcd.yaml 10.0.0.5 5432`
 
 [← Home](Home.md) · [Plugins](Plugins.md)

data/documentation/Mistakes.md

@@ -28,7 +28,7 @@ detector**, and it survives across sessions.
 | `regressed` | auto-set when a *resolved* signature recurs - reopened as `[REGRESSED]` |
 | `sessions` | last 10 session_ids that hit it |
 
-## How the loop closes (why it does **not** repeat mistakes)
+## How the loop responds to repeated mistakes
 
 ```text
 Loop.run --(tool failure)---------> Mistakes.record         (persist + count++)
@@ -45,7 +45,7 @@ model --(tool call)---------------> mistakes_record / mistakes_resolve
 
 Repeating shell failures with a known recipe (`command is required`, missing path, not-found junk, syntax, raw-socket deny) are resolved in place instead of parked as "needs human". Only scars the loop cannot close stay in the operator inbox.
 
-## Five ingest paths - nothing slips through
+## Recorded ingest paths (not universal error detection)
 
 | Source | Trigger | What is recorded |
 |---|---|---|

data/documentation/NmapIt.md

@@ -8,17 +8,20 @@ Thin, composable wrapper over `nmap` with structured XML parsing.
 > pcaprub headers · whois. See [Installation](Installation.md).
 
 ```ruby
-r = PWN::Plugins::NmapIt.port_scan(
+PWN::Plugins::NmapIt.port_scan(
   target: '10.0.0.0/24',
   ports:  '1-1024',
   service_scan: true,
   script:  'default,vuln',
   output_xml: '/tmp/scan.xml'
 )
-r[:hosts].each { |h| puts "#{h[:ip]} → #{h[:ports].map { |p| p[:portid] }}" }
+r = PWN::Plugins::NmapIt.inventory(xml_file: '/tmp/scan.xml')
+r[:hosts].each { |h| puts "#{h[:host]} → #{h[:ports].map { |p| p[:port] }}" }
 ```
 
-CLI: `pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/`
+`port_scan` invokes `Nmap::Command.sudo`; it is not an unprivileged parser and
+its return is not the inventory Hash. `inventory` reads an existing XML file.
+Use `pwn_nmap_discover_tcp_udp --help` for the driver's separate options.
 
 Pairs with `extro_observe` to persist banners for later
 [correlation](Extrospection.md), and with `PWN::Plugins::Sock` /

data/documentation/Operability.md

@@ -0,0 +1,99 @@
+# Operability and evidence boundaries
+
+This guide connects the documentation to the current source interfaces. A module
+or command being present is not proof that its external service, device or model
+works on a particular deployment. Examples with targets, credentials or devices
+require an operator-configured environment; they are not offline smoke tests.
+
+## Three different feedback paths
+
+| Path | Authority and limit |
+| --- | --- |
+| Introspection | Metrics, Learning, Mistakes, Reward and Reflect record outcomes and propose corrections. A judge score, stored lesson or tool exit zero is not verified completion. |
+| Extrospection | On-demand source observations and optional host/repo/env baselines support diagnosis. Correlation and browser token-overlap checks are fallible, not causal or semantic proof. |
+| Living off the land | `DetectOS.living_off_the_land` returns OS metadata and `native` executable names discovered on PATH. PromptBuilder injects its OS summary alongside separate PreflightChecker health. Presence is neither authorization nor successful execution. |
+
+Relevant source: `lib/pwn/plugins/detect_os.rb`,
+`lib/pwn/ai/agent/{prompt_builder,extrospection,reward,learning,policy}.rb`.
+See [Extrospection](Extrospection.md) and [Introspection](Skills-Memory-Learning.md).
+
+## Completion, regressions and evaluation
+
+The original objective and additive amendments remain authoritative. A generated
+plan, exhausted counter, child reply or empty tool-call list cannot independently
+establish completion. Exact-target host observations and applicable authored
+Verification checks must agree with current artifacts. Checks prove their own
+assertions, not every possible interpretation of natural-language intent.
+
+`claimed_completion` preserves the judge's claim; `verified_completion` is
+true/false/null for checked pass/failure/unknown. `false_completion_rate` uses
+checked claims as its denominator and is null with none. The executable harness
+has a different false-success measure: a released success marker is false when
+the whole run is not PASS, including empty checks, nonzero exit and resource caps.
+Do not combine those denominators or substitute legacy `success_rate`.
+
+Export a regression only from an exact persisted verifier failure and original
+request digest, with independently authored expected file/JSON content. The
+`Learning.regression_task` recipe is inert acceptance data, not a command replay.
+Its split remains `regression`; an inspected failure is not held-out evidence.
+
+Policy evaluation uses explicit frozen baseline/candidate snapshots and fresh
+isolated workers. Promotion reruns reports, requires both filesystem environments,
+rejects per-task and aggregate regressions, and needs operator approval, stopped
+writers and an explicit target. Preserve the versioned receipt and prior bytes.
+Rollback refuses intervening writes. This routing-policy gate does not promote
+arbitrary skills or model weights and the public fixed local benchmark does not
+establish live LLM improvement. See [Harness Evaluation](Harness-Evaluation.md)
+and [Policy Benchmark](Policy-Benchmark.md) for exact commands and limits.
+
+## Mesh is a separate transport boundary
+
+`pwn-mesh` uses the selected primary serial/Bluetooth/TCP/MQTT connection;
+a configured secondary MQTT receiver is not automatic dual transmission or a
+bridge. Eligible `@ai` requests require the dispatch toggle, private channel
+and whitelist; replies retain their origin connection and durable session scope.
+A local TX header or accepted PhoneAPI write is not RF delivery evidence. MQTT
+PKI DMs remain unsupported. Topic `region` is an opaque prefix, not the radio's
+regulatory-band setting; `radio_index` is distinct from legacy `channel_num`.
+See [General Usage](General-PWN-Usage.md) and [REPL](pwn-REPL.md).
+
+## Deployment and safe verification
+
+1. Inspect the intended checkout and preserve existing changes before upgrading.
+   A source edit does not update the activated gem or a running process.
+2. Use `/status` or `RuntimeFingerprint.report` to compare loaded source paths and
+   observed/current digests. Unknown pre-observer bytes are not a match.
+3. Install the reviewed build, restart old processes, and recheck. Keep request
+   checkpoints; restoration is not permission to repeat an uncertain mutation.
+4. Apply configuration migration only to the intended user state after review.
+   A runtime default does not backfill an already-stamped encrypted vault.
+5. Run offline gates with installed dependencies and no live integration opt-ins:
+
+```sh
+bundle check
+bundle exec rspec spec/integration/documentation_sync_spec.rb spec/documentation spec/conventions_spec.rb
+bundle exec rake
+git diff --check
+documentation/diagrams/build.sh
+```
+
+The full rake gate includes RSpec, RuboCop and RDoc: await actual exit, not just
+an RSpec zero-failure line. Serialize gates in one checkout because RDoc rebuilds
+share an output directory. Missing dependencies are a blocked gate, not a pass;
+do not weaken the Gemfile to hide them. Optional native/live suites remain
+explicit opt-ins documented in [Contributing](Contributing.md).
+
+## Historical assets and scope
+
+`PWN.png` and `pwn_wallpaper.jpg` are branding/artwork. `pwn_install.png`,
+`pwn_android_war_dialer_session.png` and `pwn_silent_help_learn_demo.gif` are
+historical presentation assets, not current installation or TUI acceptance.
+The fax/ringing waveform and spectrogram pairs illustrate recorded signal
+shapes; images alone cannot validate current telephony or decoder operation.
+They remain preserved rather than being relabeled as newly executed evidence.
+
+The SDR coverage matrix preserves historical per-mode evidence and explicit OPEN
+requirements. Current registry enumeration does not close those rows. Native
+backends, synthetic fixtures and live RF acceptance must remain separate.
+
+[Home](Home.md) · [Installation](Installation.md) · [Diagrams](Diagrams.md)