RubyGems - pwn - Versions diffs - 0.5.651 → 0.5.652 - Mend

pwn 0.5.651 → 0.5.652

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

checksums.yaml +4 -4
data/README.md +41 -30
data/documentation/AI-Integration.md +1 -1
data/documentation/Configuration.md +2 -2
data/documentation/Cron.md +5 -5
data/documentation/Extrospection.md +5 -5
data/documentation/General-PWN-Usage.md +1 -1
data/documentation/Home.md +1 -2
data/documentation/How-PWN-Works.md +13 -13
data/documentation/Installation.md +4 -4
data/documentation/Mistakes.md +4 -4
data/documentation/Reinforcement-Learning.md +23 -23
data/documentation/SDR.md +4 -4
data/documentation/Sessions.md +2 -2
data/documentation/Skills-Memory-Learning.md +1 -1
data/documentation/Transparent-Browser.md +1 -1
data/documentation/Troubleshooting.md +2 -2
data/documentation/What-is-PWN.md +22 -24
data/documentation/Why-PWN.md +16 -15
data/documentation/pwn-REPL.md +3 -3
data/documentation/pwn-ai-Agent.md +2 -2
data/lib/pwn/version.rb +1 -1
metadata +1 -1

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87ce6374516629bc195970447a1af7654566791f1493711e69f418bd72d60836
-  data.tar.gz: 1bc09b0d752bd2545150c2cf9c9bb42972481af3dfc39c05d98cfe13507005a4
+  metadata.gz: 6fd0197b1fa729406ea99bbe598d3730d27e3c6881251c374af0f894ea541729
+  data.tar.gz: 492617f851780cf17c04fcdecdd4eb491e54b2bcf115b04997f3972507528d3a
 SHA512:
-  metadata.gz: 5b2969e88240d7e28fd15fc4eff26338e7f1cbe8260696a5315049bb687613144988ba40d021c35a6d5605f143459b89a5bc65fc850db5c07f67015ca85251fa
-  data.tar.gz: 43cdfb1b3a4129cacfe3767d14d19f5bf138732e7234b9092e5ddf4ad10e4f7c5390759646f9c8e16d1ead8ab6b87fbe7109779901d0f3cf2c17ff714825c266
+  metadata.gz: ad8894f7551643e63ec4819d7a2513e3114d0f2649eb21ea8b9554e150319a7df0d62e6c46d9979d5c0462c5617f054f93f2140c81704b74fa3d8f763c428d90
+  data.tar.gz: f84e73f55040588558281b2941a41b602b2f3a6471c5cbbacdd7afc42a9b2dbf91c8c9c01e68079dcaedee03a25aad25eb17558d3ffec62f0ce8539f5e6ef1a5

data/README.md CHANGED Viewed

@@ -24,57 +24,68 @@
 #### **What is PWN** ####
-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
-**self-improving, tool-calling, multi-agent AI** on top of it.
+PWN (pronounced *pone*, like "own" with a p) is an open-source Ruby toolkit for
+**offensive security automation**. One workspace ties together the tools you
+already use: OSINT, network scanning, web and cloud testing, hardware and
+radio, reporting, and disclosure. A **tool-calling AI agent** sits on top and
+can run those same methods for you.
+Red teamers, pentesters, and vulnerability researchers get one place to script
+and automate instead of gluing together a pile of separate CLIs.
 **In numbers:** 66 `PWN::Plugins` · 48 `PWN::SAST` rules · 90 `PWN::AWS`
 service wrappers · 21 `PWN::WWW` site drivers · 53 `bin/pwn_*` CLI drivers ·
-5 LLM engines · 10 agent toolsets · 45+ LLM-callable tools.
+5 LLM engines · 12 agent toolsets · 78 LLM-callable tools.
 Full page: [What is PWN](documentation/What-is-PWN.md)
 #### **Why PWN** ####
-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,
-which matters when the caller is autonomous.
+Offensive work is hard because the *tools* do not fit together. PWN's fix is
+simple: every capability is a plain Ruby method with the same `opts = {}`
+shape. That one idea means the *same* code runs:
+- live in the REPL
+- from an LLM agent in a tool loop
+- in a shell script or CI job
+- on a cron schedule while you sleep
+The whole stack is open source and easy to read. That matters when software
+is driving security decisions without you watching every click.
 Full page: [Why PWN](documentation/Why-PWN.md)
 #### **How PWN Works** ####
-Five layers, edges only ever go down:
+PWN is five layers. Dependencies only point downward, so each level stays
+small and easy to swap:
 ![PWN Overall Architecture](documentation/diagrams/overall-pwn-architecture.svg)
-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 -
-**and does not repeat the same mistake twice**:
+On every turn the AI layer runs a **feedback loop**. It checks inward
+(Metrics, Learning, and **Mistakes**: what failed last time) and outward
+(Snapshot, Drift, Intel, RF, and **Web**: did the host or network change?).
+Live checks use browser-backed **`extro_verify`** / **`extro_watch`** and RF
+**`extro_rf_tune`**. `extro_correlate` joins those views so the agent can tell
+*"I messed up"* from *"the world moved"*, and **does not repeat the same
+mistake**:
 ![pwn-ai Feedback Learning Loop](documentation/diagrams/pwn-ai-feedback-learning-loop.svg)
-Failures are fingerprinted cross-session (`~/.pwn/mistakes.json`), tagged
-`[REPEATING]` / `[REGRESSED]`, and their **fix** is handed straight back inline
-on the next recurrence:
+Failures are fingerprinted across sessions (`~/.pwn/mistakes.json`), tagged
+`[REPEATING]` / `[REGRESSED]`, and when the same slip shows up again the saved
+**fix** is dropped straight back into the prompt:
 ![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:
+**Swarm** runs several personas at once. Each is a full tool-calling agent,
+optionally on a *different* LLM engine, talking over a shared append-only
+message bus:
 ![Swarm Multi-Agent](documentation/diagrams/swarm-multi-agent.svg)
 Full pages: [How PWN Works](documentation/How-PWN-Works.md) ·
-[All 27 Data-Flow Diagrams](documentation/Diagrams.md)
+[All data-flow diagrams](documentation/Diagrams.md)
 ---
@@ -105,7 +116,7 @@ Rebuild every SVG from its Graphviz source:
 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
+`brew` · `port`) and installs the OS headers and external tools each
 `PWN::` capability needs. Tested on Kali/Debian/Ubuntu, Fedora, Arch, macOS.
 ```
@@ -166,7 +177,7 @@ $ cd /opt/pwn && git pull && rake install && pwn setup
 ```
 $ pwn --ai 'What ports are listening on this host?'
 $ echo "$LONG_PROMPT" | pwn --ai -
-$ pwn -Y ./ci/pwn.yaml --ai 'Run pwn_sast against ./src and summarise HIGH findings' > findings.txt
+$ pwn -Y ./ci/pwn.yaml --ai 'Run pwn_sast against ./src and summarize HIGH findings' > findings.txt
 ```
 **Provision a CI runner / Docker image:**
@@ -206,13 +217,13 @@ Highlights:
 [SAST](documentation/SAST.md) ·
 [AI Integration](documentation/AI-Integration.md)
-I hope you enjoy PWN - and remember: **always have permission** before any
-security testing. Now go pwn all the things (responsibly)!
+Remember: **always have permission** before any security testing. Then go
+pwn all the things (responsibly).
 ---
 ### **Keep Us Caffeinated** ###
-If you've found this project useful and you're interested in supporting our efforts, we invite you to take a brief moment to keep us caffeinated:
+If this project helped you and you want to support the work, keep us caffeinated:
 [![Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoff.ee/0dayinc)

data/documentation/AI-Integration.md CHANGED Viewed

@@ -1,7 +1,7 @@
 # AI / LLM Integration - `PWN::AI`
 One agent loop, five interchangeable engines. Swap providers by changing one
-line in `~/.pwn/pwn.yaml`; the tool-calling contract is normalised so the
+line in `~/.pwn/pwn.yaml`; the tool-calling contract is normalized so the
 agent code never cares which model is behind it.
 ![Multi-provider integration](diagrams/ai-integration-tool-calling.svg)

data/documentation/Configuration.md CHANGED Viewed

@@ -20,7 +20,7 @@ generates the decryptor.
 > [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.
-> After `gem update pwn`, run `pwn setup --migrate --fix` — `PWN::Migrate`
+> After `gem update pwn`, run `pwn setup --migrate --fix` - `PWN::Migrate`
 > deep-merges any keys the new `PWN::Config.env_template` added into your
 > encrypted `pwn.yaml` **without overwriting your values**.
@@ -269,7 +269,7 @@ PWN::Config.refresh_env
 | `ai.agent.critic` | Boolean | `false` | `PWN::AI::Agent::Curriculum.critic` (S3) | Tool-armed constitutional self-critic reviews (and may `shell`/`extro_verify`) every final answer before it is returned. |
 | `ai.agent.red_team_plan` | Boolean | `false` | `PWN::AI::Agent::Curriculum.red_team_plan` (S4) | Adversarial review of the `plan_first` numbered plan, grounded in Metrics/Mistakes/`extro_drift` telemetry, before the first dispatch. |
 | `ai.agent.counterfactual` | Boolean | `false` | `PWN::AI::Agent::Curriculum.counterfactual` (S2) | On `[REPEATING]`, fork an alt-persona branch, judge both, and record the `(loser, winner)` DPO preference pair. |
-| `ai.agent.hindsight` | Boolean | `true` | `PWN::AI::Agent::Curriculum.hindsight` (C3) | Hindsight Experience Replay — relabel a failed trajectory as `success:true` for whatever it *did* accomplish. Free positive samples from failures. |
+| `ai.agent.hindsight` | Boolean | `true` | `PWN::AI::Agent::Curriculum.hindsight` (C3) | Hindsight Experience Replay - relabel a failed trajectory as `success:true` for whatever it *did* accomplish. Free positive samples from failures. |
 | `ai.agent.verify_as_reward` | Boolean | `false` | `PWN::AI::Agent::Reward.verify_as_reward` (E3) | Ground the LLM judge score by browser-verifying any checkable claim in the final via `extro_verify`; verdict caps/floors `Reward.judge`. |
 | `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`). |

data/documentation/Cron.md CHANGED Viewed

@@ -36,11 +36,11 @@ invokes `PWN::Cron.run(<id>)` on schedule.
 | `curriculum_train_weekly` | `0 4 * * 0` | `PWN::AI::Agent::Curriculum.train_and_gate(dry_run: true)` |
 | `learning_consolidate_nightly` | `0 5 * * *` | `PWN::AI::Agent::Learning.consolidate` |
-- **practice** — top unresolved `Mistakes` under `Reward.judge`; auto-`resolve` with ≥2 holdouts
-- **offline_judge** — P3 backfill of ORM/PRM labels + W3 calibration from PLAN `p(success)=` so `:failure_only` local introspect does not starve the corpus; also runs **P10** `Reward.warm_sentinel` so the R3 ring can fill on local hosts
-- **dedupe (P13)** — legacy alias `offline_judge_nightly` counts as the same job; `install_defaults` will not double-seed `30 3 * * *` and disables the alias when both exist
-- **train** — export SFT + balanced DPO, LoRA-train `pwn-vN+1`, replay Mistakes.top, promote only on win. `dry_run: false` only with a trainer+GPU
-- **consolidate** — M1/M3 memory GC so the injected MEMORY block stays high-signal
+- **practice** - top unresolved `Mistakes` under `Reward.judge`; auto-`resolve` with ≥2 holdouts
+- **offline_judge** - P3 backfill of ORM/PRM labels + W3 calibration from PLAN `p(success)=` so `:failure_only` local introspect does not starve the corpus; also runs **P10** `Reward.warm_sentinel` so the R3 ring can fill on local hosts
+- **dedupe (P13)** - legacy alias `offline_judge_nightly` counts as the same job; `install_defaults` will not double-seed `30 3 * * *` and disables the alias when both exist
+- **train** - export SFT + balanced DPO, LoRA-train `pwn-vN+1`, replay Mistakes.top, promote only on win. `dry_run: false` only with a trainer+GPU
+- **consolidate** - M1/M3 memory GC so the injected MEMORY block stays high-signal
 See [Reinforcement Learning](Reinforcement-Learning.md).

data/documentation/Extrospection.md CHANGED Viewed

@@ -84,7 +84,7 @@ Override / extend via `PWN::Env[:ai][:agent][:extrospection][:web][:anchors]`; s
 | **`extro_osint`** | **Aggregate public OSINT APIs (phone / IP / domain / FCC ID / patent / VIN / MAC / callsign / person / company / SEC / CourtListener / Federal Register / UK Police / OTX / URLHaus / openFDA / NPPES / Nominatim / EPSS / CISA KEV / Microlink / vital records / Shodan / Hunter / AbuseIPDB / VT / HIBP / Wayback) + social/identity feeds (Keybase / Gravatar / Mastodon / Bluesky / HN / StackExchange / npm / PyPI / RubyGems / crates / DockerHub / Codeberg / Steam / Telegram + ~100-site presence sweep) + local-tool bridges (theHarvester / spiderfoot / amass / recon-ng)** | `observations[]` (`category: :osint`) |
 | **`extro_serial`** | **Open serial device · optional payload · drain response · disconnect** | `observations[]` (`category: :serial`) |
 | **`extro_telecomm`** | **BareSIP inventory / status / dial / hangup (never launches baresip)** | `observations[]` (`category: :telecomm`) |
-| **`extro_packet`** | **Inventory · bounded live capture · pcap summarise (tshark/PacketFu)** | `observations[]` (`category: :packet`) |
+| **`extro_packet`** | **Inventory · bounded live capture · pcap summarize (tshark/PacketFu)** | `observations[]` (`category: :packet`) |
 | **`extro_vision`** | **OCR (tesseract/RTesseract) · barcode/QR (zbarimg)** | `observations[]` (`category: :vision`) |
 | **`extro_voice`** | **TTS (espeak-ng/festival/spd-say) · STT (whisper) · inventory** | `observations[]` (`category: :voice`) |
 | `extro_correlate` | **Join** introspection ↔ extrospection | - actionable findings |
@@ -397,7 +397,7 @@ PWN::Env[:ai][:agent][:extrospection][:telecomm] = {
 ## `extro_packet` - Packet sense organ
-Bounded L2/L3 sensing via `tshark` / `tcpdump` + pcap summarisation through
+Bounded L2/L3 sensing via `tshark` / `tcpdump` + pcap summarization through
 `PWN::Plugins::Packet` / tshark hierarchy & conversations:
 | action | Effect |
@@ -498,7 +498,7 @@ use **Chicago** so the catalog stays portable.
 ### RF / SDR sense organ (`extro_rf_tune` + `:rf` observations)
 - "Tune 433.92 MHz - is the target's garage/gate remote fixed-code or rolling?"
-- "Sweep the 900 MHz ISM band near the badge reader and log anything > −40 dBFS."
+- "Sweep the 900 MHz ISM band near the badge reader and log anything > -40 dBFS."
 - "What's broadcasting on 101.1 FM right now - grab RDS PI/PS so we can prove SDR is live."
 - "Sample 868.3 MHz for 15 s - does the smart-meter mesh look like Wireless M-Bus?"
 - "Any ADS-B traffic squawking over the client's campus (near ORD)?"
@@ -551,7 +551,7 @@ use **Chicago** so the catalog stays portable.
 ### Packet sense organ (`extro_packet`)
 - "Capture 30 s on `eth0` while I trigger the IoT hub - what does it phone home to?"
-- "Summarise `/tmp/eng.pcap` - top talkers, cleartext creds, weird ports."
+- "Summarize `/tmp/eng.pcap` - top talkers, cleartext creds, weird ports."
 - "BPF `udp port 5353` - is mDNS leaking hostnames and service records on the guest VLAN?"
 - "Grab 50 packets of the OT segment - Modbus/TCP or something proprietary?"
 - "Do we see the camera's RTSP creds in the clear during that capture?"
@@ -625,7 +625,7 @@ use **Chicago** so the catalog stays portable.
 | "subdomain / CT log / ASN / whois / FCC ID / VIN / MAC OUI / EPSS / KEV / Wayback / pivot @user / Keybase / Gravatar / social sweep / theHarvester / amass" | `extro_osint` |
 | "UART / ttyUSB / U-Boot / AT command / Flipper / JTAG banner" | `extro_serial` |
 | "SIP / PBX / IVR / BareSIP / dial / hangup" | `extro_telecomm` |
-| "capture on iface / summarise pcap / mDNS / Modbus / RTSP creds" | `extro_packet` |
+| "capture on iface / summarize pcap / mDNS / Modbus / RTSP creds" | `extro_packet` |
 | "OCR sticker / decode QR / read badge / BIOS screenshot" | `extro_vision` |
 | "transcribe wav / TTS pretext / whisper offline" | `extro_voice` |
 | "watch URL / did the page change / silent patch / scope updated / TLS rotated" | `extro_watch` |

data/documentation/General-PWN-Usage.md CHANGED Viewed

@@ -4,7 +4,7 @@
 ```bash
 $ pwn                         # interactive REPL
-$ pwn --ai "scan 10.0.0.0/24 with NmapIt and summarise open services"
+$ 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
 ```

data/documentation/Home.md CHANGED Viewed

@@ -76,5 +76,4 @@
 ---
-<sub>Generated by pwn-ai. Edit any `.md` directly; edit any diagram in
-`documentation/diagrams/dot/*.dot` then run `./build.sh`.</sub>
+<sub>Edit any `.md` directly. Edit diagrams in `documentation/diagrams/dot/*.dot`, then run `./build.sh`.</sub>

data/documentation/How-PWN-Works.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # How PWN Works
-PWN is five layers, each visible in the source tree. Edges only ever go
+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.
@@ -47,7 +47,7 @@ call, and [Reinforcement Learning](Reinforcement-Learning.md) for how
 `Plugins` (66) · `SAST` (48) · `WWW` (21) · `AWS` (90) · `SDR` · `Blockchain` ·
 `Bounty` · `Reports` · `FFI` · `Banner` · **`Setup`** · **`Migrate`**. Each is
 a plain module of `public_class_method def self.x(opts = {})` methods -
-callable identically from the REPL, from `pwn_eval`, or from a driver.
+callable the same way from the REPL, from `pwn_eval`, or from a driver.
 ## L4 - Persistence  (`~/.pwn/`)
@@ -57,22 +57,22 @@ autofixes every file in it after a `gem update pwn`:
 ![~/.pwn map](diagrams/persistence-filesystem.svg)
-See [Persistence](Persistence.md) for the byte-level layout of each file and
+See [Persistence](Persistence.md) for the layout of each file and
 [Installation § Upgrading](Installation.md#upgrading--pwn-state-migration-pwnmigrate)
 for the migrator.
 ## The feedback loop
-The reason L2 exists is to close this loop on every turn - successes
-become skills/lessons, **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, an **LLM judge scores the final** and a
-**process reward model tags each tool step**, and **all six prompt blocks**
-(MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS ·
-EXTROSPECTION) are re-injected into the very next system prompt.
-Nightly cron practises the top unresolved Mistakes; weekly cron cuts a
+L2 exists to close this loop on every turn - successes become skills and
+lessons, **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, an **LLM judge scores the final answer** and a **process reward
+model tags each tool step**, and **all six prompt blocks** (MEMORY · SKILLS ·
+LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS · EXTROSPECTION) are
+re-injected into the next system prompt.
+Nightly cron practices the top unresolved Mistakes; weekly cron builds a
 LoRA and only promotes it if it beats the previous adapter on that same
 mistake set:

data/documentation/Installation.md CHANGED Viewed

@@ -147,11 +147,11 @@ pwn setup [--check] [--deps] [--profile NAME] [--list-profiles]
 ---
-## Upgrading — `~/.pwn` state migration (`PWN::Migrate`)
+## Upgrading - `~/.pwn` state migration (`PWN::Migrate`)
 PWN persists a growing set of files under `~/.pwn` (encrypted config,
 memory, learning, metrics, mistakes, extrospection, cron, agents, skills,
-sessions, swarm, curriculum, finetune, …). Each file is owned by a different
+sessions, swarm, curriculum, finetune, ...). Each file is owned by a different
 module and each release can add keys or change shape. `PWN::Migrate` closes
 that gap so `gem update pwn` never leaves you with a `KeyError` or a silent
 empty-fallback.
@@ -185,7 +185,7 @@ Everything is idempotent and dry-run capable. The plain `pwn` launcher also
 prints a one-line drift warning on startup whenever `~/.pwn/.schema`
 predates the running gem (`PWN::Migrate.needed?`).
-Schema `v1` also seeds `PWN::Cron.install_defaults` — the nightly
+Schema `v1` also seeds `PWN::Cron.install_defaults` - the nightly
 `curriculum_practice` and weekly `curriculum_train` self-improvement jobs
 (see [Reinforcement Learning](Reinforcement-Learning.md)).
@@ -269,7 +269,7 @@ PWN::Migrate.check                        # human report + { compatible:[], inco
 PWN::Migrate.run(fix: true, dry_run:false)# backup → ordered migrations → per-file repair → vault backfill
 PWN::Migrate.vault_drift                  # keys env_template has that your pwn.yaml is missing
 PWN::Migrate.backfill_vault               # deep-merge those keys under your values, re-encrypt
-PWN::Migrate::STATE_FILES                 # declarative registry of every ~/.pwn artefact
+PWN::Migrate::STATE_FILES                 # declarative registry of every ~/.pwn artifact
 PWN::Migrate::SCHEMA_VERSION              # bump when a state file changes shape
 ```

data/documentation/Mistakes.md CHANGED Viewed

@@ -12,7 +12,7 @@ once one is found so the avoidance lesson becomes an actionable correction.
 ## The failure fingerprint
-A "mistake" is keyed by `sha12(tool + normalised_error)`. Normalisation strips
+A "mistake" is keyed by `sha12(tool + normalised_error)`. Normalization strips
 volatile bits - paths, hex addresses, `:LINE`, `port N`, timestamps, UUIDs,
 PIDs - so `NoMethodError ... at foo.rb:42` and `... at foo.rb:99` collapse to
 **one** signature and its `:count` climbs. **That count *is* the repeat
@@ -22,7 +22,7 @@ detector**, and it survives across sessions.
 |---|---|
 | `signature` | 12-hex-char sha of `(tool, normalised_error)` - stable across runs |
 | `tool` | component the failure was in (`shell`, `pwn_eval`, `assumption`, `assistant_answer`, a module name...) |
-| `error` | normalised error text (paths/lines/addrs/ts stripped) |
+| `error` | normalized error text (paths/lines/addrs/ts stripped) |
 | `count` | **cross-session** recurrence count - drives `[REPEATING]` at ≥ 3 |
 | `resolved` / `fix` | set by `mistakes_resolve` - promoted to a `PWN::Memory` `:lesson` |
 | `regressed` | auto-set when a *resolved* signature recurs - reopened as `[REGRESSED]` |
@@ -104,8 +104,8 @@ upgraded", "the HackRF was unplugged", or "the target DOM moved". See
 `Mistakes.resolve` writes a DPO preference into `~/.pwn/preferences.jsonl`:
-- **rejected** — the failing snippet / action
-- **chosen** — prefers `structured_fix.winning_trace` (+ strategy/tool) when
+- **rejected** - the failing snippet / action
+- **chosen** - prefers `structured_fix.winning_trace` (+ strategy/tool) when
   present; falls back to `AVOID_ARGS` / fix prose only when no trace exists
 Curriculum auto-resolve always attaches a winning tool trace so the ledger

data/documentation/Reinforcement-Learning.md CHANGED Viewed

@@ -37,34 +37,34 @@ path closes the weight loop; without a trainer the path is **export-ready**
                     Metrics.changepoints (E1 CUSUM) ──► Mistakes(cause: :env_drift)
 ```
-## Tier 1 — Reward signal (`PWN::AI::Agent::Reward`)
+## Tier 1 - Reward signal (`PWN::AI::Agent::Reward`)
 | ID | Method | What it does | Beats |
 |----|--------|-------------|-------|
 | **R1** | `.judge` | LLM Outcome Reward Model → `{score:0..1, verdict:, rationale:, key_step:}`. Replaces `infer_success` regex. | Reflexion (binary self-eval) |
-| **R2** | `.prm` | Process Reward Model — per-tool-step `+1/0/−1` written into `Sessions[:step_reward]`. | Lightman '23 (math only) — first PRM on security tooling |
-| **R3** | `.sentinel` | proxy vs judge vs (1 − user_correction_rate); >0.15 gap → `Mistakes.record(tool:'reward_signal')`. | — novel |
-| **R4** | `.semantic_ok` | `grep exit 1` ≠ failure. `Loop.record_metrics` records Metrics on `:ok`, Mistakes on `!semantic_ok`. Kills phantom `31f1871b8a15`. | — bugfix |
+| **R2** | `.prm` | Process Reward Model - per-tool-step `+1/0/-1` written into `Sessions[:step_reward]`. | Lightman '23 (math only) - first PRM on security tooling |
+| **R3** | `.sentinel` | proxy vs judge vs (1 - user_correction_rate); >0.15 gap → `Mistakes.record(tool:'reward_signal')`. | - novel |
+| **R4** | `.semantic_ok` | `grep exit 1` ≠ failure. `Loop.record_metrics` records Metrics on `:ok`, Mistakes on `!semantic_ok`. Kills phantom `31f1871b8a15`. | - bugfix |
-## Tier 2 — Credit assignment & replay
+## Tier 2 - Credit assignment & replay
 | ID | Where | What |
 |----|-------|------|
 | **C1** | `Registry.rank` + `Metrics.{ucb,thompson,advantage}` | score = α·keyword_sim + β·advantage + γ·UCB1. Untried tools get exploration bonus. |
-| **C2** | `Learning.exemplars_for` | priority = judge_score × e^(−Δt/30d) × keyword_sim. |
-| **C3** | `Curriculum.hindsight` | HER — relabel failed trajectory with achieved-goal as `success: 'soft'` + tags `hindsight/her/soft`. Soft rows are excluded from SFT and 0.35×-weighted in C2 exemplars. |
-| **C4** | `Learning.{compress_exemplar,build_skill_from_session}` | keep only `step_reward > 0` — minimal sufficient trace. |
+| **C2** | `Learning.exemplars_for` | priority = judge_score × e^(-Δt/30d) × keyword_sim. |
+| **C3** | `Curriculum.hindsight` | HER - relabel failed trajectory with achieved-goal as `success: 'soft'` + tags `hindsight/her/soft`. Soft rows are excluded from SFT and 0.35×-weighted in C2 exemplars. |
+| **C4** | `Learning.{compress_exemplar,build_skill_from_session}` | keep only `step_reward > 0` - minimal sufficient trace. |
-## Tier 3 — Memory that stays high-signal
+## Tier 3 - Memory that stays high-signal
 | ID | Where | What |
 |----|-------|------|
 | **M1** | `Learning.consolidate` → `semantic_merge` | embed `:lesson`, greedy cosine ≥0.92, `Reflect.on("merge → 1 imperative")`. |
 | **M2** | `MemoryIndex.recall_semantic` | score = 0.6·sim + 0.25·recency + 0.15·importance (Park '23). |
-| **M3** | `Memory.remember(source:,confidence:,importance:,ttl:)` | consolidate evicts by `(age/ttl)/(importance×confidence)` — heuristic garbage self-evicts. |
+| **M3** | `Memory.remember(source:,confidence:,importance:,ttl:)` | consolidate evicts by `(age/ttl)/(importance×confidence)` - heuristic garbage self-evicts. |
 | **M4** | `Learning.note_outcome` | outcomes → `learning.jsonl` ONLY. Memory `:lesson` reserved for reflect/resolve/human. `purge_noise` GCs pre-R1 garbage. |
-## Tier 4 — Curriculum & self-play (`PWN::AI::Agent::Curriculum`)
+## Tier 4 - Curriculum & self-play (`PWN::AI::Agent::Curriculum`)
 | ID | Method | What |
 |----|--------|------|
@@ -73,7 +73,7 @@ path closes the weight loop; without a trainer the path is **export-ready**
 | **S3** | `.critic` | tool-armed constitutional critic (can `shell`/`extro_verify` the claim). |
 | **S4** | `.red_team_plan` | adversarial plan review grounded in Metrics/Mistakes/extro_drift telemetry. |
-## Tier 5 — Close the weight loop
+## Tier 5 - Close the weight loop
 | ID | Where | What |
 |----|-------|------|
@@ -81,7 +81,7 @@ path closes the weight loop; without a trainer the path is **export-ready**
 | **W2** | `Curriculum.train_and_gate` | SFT+DPO → unsloth/axolotl LoRA → `ollama create pwn-vN+1` → **gate v2** (resolved margin + mean judge + smoke). **Without a trainer: export-only** (`weight_loop: :export_ready`). |
 | **W3** | `Curriculum.calibrate` + `Metrics.{record_calibration,calibration}` | plan_first `p(success)` vs actual → per-engine Brier/overconfidence. |
-## Tier 6 — Deepen the intro↔extro join
+## Tier 6 - Deepen the intro↔extro join
 | ID | Where | What |
 |----|-------|------|
@@ -95,11 +95,11 @@ path closes the weight loop; without a trainer the path is **export-ready**
 :ai:
   :module_reflection: false  # gates Reflect lesson writing (not ORM alone)
   :agent:
-    :critic: null            # S3 — nil = ON for remote engines, OFF for ollama
-    :red_team_plan: null     # S4 — same auto policy
-    :counterfactual: null    # S2 — same auto policy
+    :critic: null            # S3 - nil = ON for remote engines, OFF for ollama
+    :red_team_plan: null     # S4 - same auto policy
+    :counterfactual: null    # S2 - same auto policy
     :hindsight: true         # C3 (default true; soft-success, 0.35× in C2)
-    :verify_as_reward: null  # E3 — nil = auto (~10% local / always remote on CLAIM_RX)
+    :verify_as_reward: null  # E3 - nil = auto (~10% local / always remote on CLAIM_RX)
     :reward_llm: null        # nil = ORM/PRM use LLM teacher on remote even if module_reflection is false
     :local_introspect: :failure_only   # ollama cost policy; remote always introspects
     :introspect_every_n: 3
@@ -124,7 +124,7 @@ PWN::Cron.install_defaults
 `curriculum_hindsight` · `curriculum_offline_judge` ·
 `curriculum_preference_balance` · `learning_purge_noise`
-## Design claims (architecture — weight promotion requires a trainer)
+## Design claims (architecture - weight promotion requires a trainer)
 1. **Process reward on real security tool traces** (R2)
 2. **Automatic blame attribution** self vs env-drift via CUSUM×correlate (E1+E2)
@@ -140,18 +140,18 @@ PWN::Cron.install_defaults
 | **P1** | `Curriculum.practice` cooldown + natural prompts | Hard-skips `reward_signal` / parked / `needs_code_change`; N-night zero-score cooldown parks thrash; reproducers are natural user tasks, never signature dumps. |
 | **P2** | R4 `semantic_ok` + structured resolve | `31f1871b8a15`-class exit≠0 phantoms stay closed via structured holdouts. |
 | **P3** | `Curriculum.offline_judge` | Scores last-24h sessions under ORM/PRM so local `:failure_only` introspect does not starve labels. Cron nightly. |
-| **P4** | `Reward.proxy_distrust` | When sentinel fires, Metrics.to_context / Registry.rank haircut proxy rates — actionable, not just another Mistakes row. |
+| **P4** | `Reward.proxy_distrust` | When sentinel fires, Metrics.to_context / Registry.rank haircut proxy rates - actionable, not just another Mistakes row. |
 | **R3** | `Reward.sentinel` ring buffer | Fixed-N (`SENTINEL_WINDOW=40`) `{judge,proxy}` window replaces decaying `proxy_sum`/`proxy_n`. Means are always ∈[0,1]; `set_proxy_distrust` refuses proxy∉[0,1]; `reset_sentinel` wipes corrupt state without touching prefs. Legacy decay×`to_i` files auto-clear stuck distrust on load. |
 | **P5** | `Curriculum.preference_balance` + `export_dpo` source-cap | Surfaces W1 monoculture **and enforces** ≤40% per source at export (`DPO_SOURCE_CAP`); critic/counterfactual auto-ON for remote engines so the diet rebalances online. |
 | **P6** | W2 honesty | Docs + `train_and_gate` return `weight_loop: :export_ready` when `trainer: null`. |
 | **P7** | W3 as controller | Engine Brier > 0.35 or overconfidence > 0.25 (n≥8) → force plan_first + critic, cap max_iters at 12. `offline_judge` also records calibration from PLAN `p(success)=` so the controller can fire under `:failure_only`. |
-| **P8** | Remote reward teacher | `agent.reward_llm` nil → ORM/PRM use the LLM teacher on remote engines even when `module_reflection` is false. Local ollama stays heuristic unless explicitly enabled. PRM prompts carry R4 tags so benign recon exits score 0 not −1. |
+| **P8** | Remote reward teacher | `agent.reward_llm` nil → ORM/PRM use the LLM teacher on remote engines even when `module_reflection` is false. Local ollama stays heuristic unless explicitly enabled. PRM prompts carry R4 tags so benign recon exits score 0 not -1. |
 | **P9** | W1 pair geometry + write-time quota | Critic chosen = **revised full answer** (not `CORRECTION:` flaw prose). Resolve prefers `structured_fix.winning_trace`. Counterfactual tags `:real_dispatch` vs `:imagined`. `record_preference` enforces `WRITE_SOURCE_CAP=0.40` online (trajectory shapes force-land). |
 | **P10** | `Reward.warm_sentinel` | Backfills R3 ring from scored Learning outcomes so local `:failure_only` hosts reach `SENTINEL_WINDOW` without waiting for live remote introspect. `offline_judge` calls it every night. |
 | **P11** | W2 gate v2 | Promote only when candidate wins on resolved margin **and** mean judge **and** frozen smoke set (uname/pwd/ruby) does not regress. Coarse `resolved(N+1)>resolved(N)` alone cannot self-promote eval memorisation. |
 | **P12** | SFT quality gate | `export_finetune` drops HER/soft + score&lt;`SFT_MIN_SCORE` (0.6), de-dupes per session by best score, PRM-compresses traces (`compress_finetune_trace`). |
 | **P13** | Cron offline_judge dedupe | `install_defaults` treats `offline_judge_nightly` as alias of `curriculum_offline_judge` and disables duplicates so the 30 3 * * * slot runs once. |
-| **P14** | Practice → DPO geometry | `Curriculum.practice` records `chosen: winning_trace` (+ final), `shape: :winning_trace` — never first-3-lines fix prose. |
+| **P14** | Practice → DPO geometry | `Curriculum.practice` records `chosen: winning_trace` (+ final), `shape: :winning_trace` - never first-3-lines fix prose. |
 | **P15** | Ledger hygiene | `Reward.usable_preference?` / `scrub_preferences` / geometry filter in `export_dpo` drop `CORRECTION:` prose, resolve-without-trace, and chosen≪rejected. `preference_balance(scrub:true)` reports `trajectory_fraction`. |
 | **P16** | R3 warm for real | `warm_sentinel` fills from scored **and** success-boolean outcomes, returns `proxy_distrust`, runs `sentinel` once full so controllers can engage. |
 | **P17** | Budget-exhaustion skill | Practice prioritises `agent_loop`/`assistant_answer`; natural prompts teach finish-under-N; Loop hard-stops empty-final thrash and tightens max_iters when budget fingerprints dominate. |
@@ -161,7 +161,7 @@ PWN::Cron.install_defaults
 | **P21** | Resolve trajectory-only | `Mistakes.resolve` writes W1 only when `structured_fix.winning_trace` ≥40 chars (`shape: :winning_trace`). Prose-only resolve still updates Memory + structured_fix; it does **not** flood DPO. |
 | **P22** | W3 calibration live | `Loop.plan_first` stashes `p(success)=` on `Thread.current[:pwn_plan_predicted]`; `Learning.recover_predicted_from_session` + `Curriculum.calibrate` light the Brier/overconfidence controller under `:failure_only`. |
 | **P23** | Short-horizon budget practice | Budget-exhaustion fingerprints get natural "finish under N" prompts; practice auto-resolve requires N≥2 holdouts at judge≥0.7 **and** a real winning_trace (no long-prose resolve). |
-| **P24** | Critic cost under budget-hot | When `budget_exhaustion_hot?`, `auto_introspect` forces `critic(text_only: true)` — single Reflect/heuristic shot, no tool-armed persona swarm that burns the remaining iteration budget. |
+| **P24** | Critic cost under budget-hot | When `budget_exhaustion_hot?`, `auto_introspect` forces `critic(text_only: true)` - single Reflect/heuristic shot, no tool-armed persona swarm that burns the remaining iteration budget. |
 | **P25** | Write-time trajectory gate | `Reward.record_preference` refuses non-`TRAJECTORY_SHAPES` unless `force:` / `user_correction`. Write-time source quota **still** applies to trajectory pairs so winning_trace cannot re-monoculture the ledger. |
 ## Preference / trajectory signal quality (current ops posture)
@@ -180,7 +180,7 @@ and source diversity, not missing tiers:
 8. Resolve/record_preference are trajectory-only at write time (P21/P25); write-time source quota still caps traj monoculture.
 9. Without unsloth/axolotl **or** a clean preference diet, `train_and_gate` stays `weight_loop: :export_ready` (honest).
-## Design-priority STATUS (post P14–P25)
+## Design-priority STATUS (post P14-P25)
 Collapse of the review-driven priority order into a living table. Stop minting new P-numbers for chores already covered; track these outcomes instead.

data/documentation/SDR.md CHANGED Viewed

@@ -10,7 +10,7 @@
 | Module | Purpose |
 |---|---|
-| **`GQRX`** | Remote-control a running GQRX instance over TCP: tune, set demod, squelch, record, `get_spectrum_snapshot` (pure-Ruby FFT - median NF, relative peak/prominence, **plan-parametric** min-distance & −6 dB BW), `fast_scan_range` (**always RAW @ sample_rate** panoramic capture; band-plan IF deferred to refine/decoder; `#fft_plan_geometry` derives sep/merge/refine/snap from `(plan_bw, step, res)`; local-FFT refine + S-meter confirm; schema-parity with `scan_range`) |
+| **`GQRX`** | Remote-control a running GQRX instance over TCP: tune, set demod, squelch, record, `get_spectrum_snapshot` (pure-Ruby FFT - median NF, relative peak/prominence, **plan-parametric** min-distance & -6 dB BW), `fast_scan_range` (**always RAW @ sample_rate** panoramic capture; band-plan IF deferred to refine/decoder; `#fft_plan_geometry` derives sep/merge/refine/snap from `(plan_bw, step, res)`; local-FFT refine + S-meter confirm; schema-parity with `scan_range`) |
 | `FlipperZero` | Serial control of Flipper (sub-GHz, NFC, IR, iButton) |
 | `RFIDler` | 125 kHz RFID reader/emulator |
 | `SonMicroRFID` | SM130 13.56 MHz reader |
@@ -20,7 +20,7 @@
 ## CLI
 ```bash
-# FFT sweep - plan-parametric peak geometry + local-FFT refine for exact centres
+# FFT sweep - plan-parametric peak geometry + local-FFT refine for exact centers
 # Works for ALL band plans (CW 150 Hz → FLEX 20 kHz → FM 200 kHz → GPS 30 MHz)
 pwn_gqrx_scanner -a pager_flex --fft-scan                 # alias: flex_pager
 pwn_gqrx_scanner -a fm_radio   --fft-scan --min-snr-db 18
@@ -46,8 +46,8 @@ invariants already on each plan (`bandwidth` → `plan_bw_hz`, `precision` →
 | Capture IF | **Always** `M RAW sample_rate` (IQRECORD is demod IF - never plan FM/20 kHz) |
 | Peak height / prom | Relative: `median_nf + 12 dB`, prom ≥ 8 dB |
 | Peak min-distance | `#fft_plan_geometry` → `sep_hz = max(0.5·plan, step, floor)` |
-| Occupied BW | −6 dB-from-peak contour, hard-capped to `± plan_bw` |
-| Center | Power-weighted centroid of −6 dB lobe → raster snap |
+| Occupied BW | -6 dB-from-peak contour, hard-capped to `± plan_bw` |
+| Center | Power-weighted centroid of -6 dB lobe → raster snap |
 | Merge | `tol = max(½ plan, step, ½ measured_bw, 2·res)` |
 | Refine window | ~0.6·plan (capped so next neighbour is outside); local high-res FFT |
 | Strength lock | Auto from live S-meter NF + 8 dB unless `-S` given |

data/documentation/Sessions.md CHANGED Viewed

@@ -9,10 +9,10 @@ appended as JSON-per-line to `~/.pwn/sessions/<id>.jsonl`.
 - `learning_reflect(session_id:)` mines them for durable lessons → Memory.
 - `learning_distill_skill(name:, session_id:)` turns a winning run into a
-  reusable Skill (only steps with `step_reward > 0` are kept — the minimal
+  reusable Skill (only steps with `step_reward > 0` are kept - the minimal
   sufficient trace).
 - `Reward.prm(request:, session_id:)` back-labels every tool step in the
-  transcript with `step_reward: +1/0/−1` for credit assignment.
+  transcript with `step_reward: +1/0/-1` for credit assignment.
 - `Reward.judge(request:, final:, session_id:)` grades the whole run.
 - `sessions_view` lets you (or a later agent) re-read exactly what happened.
 - Swarm maps each persona to its own session so its private context survives

data/documentation/Skills-Memory-Learning.md CHANGED Viewed

@@ -41,7 +41,7 @@ its own performance, turns wins into permanent capability, and - critically -
 9. Found a fix for a mistake          → mistakes_resolve(sig, fix) → Memory :lesson "AVOID X - FIX: Y"
 10. (weekly, cron) Learning.export_finetune (P12: min_score + PRM-compress) +
      Reward.export_dpo (≤40%/src, P15 geometry scrub) → ~/.pwn/finetune/*.jsonl → LoRA over the local
-     model via Curriculum.train_and_gate (P11 gate v2) — the ONLY step that
+     model via Curriculum.train_and_gate (P11 gate v2) - the ONLY step that
      changes weights, not just the scaffold. Without a trainer this stays export-ready.
 11. Next launch: PromptBuilder injects the budgeted blocks → the model already knows:
      MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS · EXTROSPECTION

data/documentation/Transparent-Browser.md CHANGED Viewed

@@ -48,7 +48,7 @@ fallback) as its **web sense organ** - the counterpart to `probe_rf`'s ears:
 | `extro_verify(claim:, kind:)` | **Proactive self fact-check** - render NVD/CVE.org, rubygems/PyPI, a cited URL, or DuckDuckGo HTML and return `:confirmed` / `:refuted` / `:unknown`. `:refuted` → `Mistakes.record(tool:'assumption', ...)` |
 | `revalidate_memory` (cron) | Garbage-collect stale `PWN::Memory` `:fact` entries by re-`verify()`ing every one containing a CVE / version / URL |
-All four honour `proxy:` (Burp / `tor`) so attribution stays controlled, reuse
+All four honor `proxy:` (Burp / `tor`) so attribution stays controlled, reuse
 **one** browser handle across anchors, and `close` in an `ensure`. See
 [Extrospection](Extrospection.md) for the full loop.

data/documentation/Troubleshooting.md CHANGED Viewed

@@ -20,7 +20,7 @@ $ pwn setup --deps --dry-run     # show the apt/dnf/pacman/brew/port commands wi
 See [Installation](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
 for the full profile table and `PWN::Setup` API.
-## `[pwn] ~/.pwn schema is stale — run pwn setup --migrate` on launch
+## `[pwn] ~/.pwn schema is stale - run pwn setup --migrate` on launch
 Your `~/.pwn` state files were written by an older PWN release than the one
 now running. The launcher checks `PWN::Migrate.needed?` on every start.
@@ -39,7 +39,7 @@ your encrypted `~/.pwn/pwn.yaml` **under** your existing values. See
 ## `KeyError` / `NoMethodError for nil` reading memory / metrics / mistakes / cron / agents
-Same cause — the on-disk shape predates the current loader.
+Same cause - the on-disk shape predates the current loader.
 `pwn setup --migrate --fix` will quarantine or repair the offending file
 and re-seed a valid one on next write.

data/documentation/What-is-PWN.md CHANGED Viewed

@@ -1,20 +1,18 @@
 # What is PWN
-**PWN** (pronounced /pōn/ - "pone") is an open-source **offensive-security
-automation framework** and **continuous-security-integration** platform,
-distributed as a Ruby gem.
+**PWN** (pronounced /pon/ - "pone") is an open-source **offensive security
+automation** framework, shipped as a Ruby gem.
-It gives security researchers, red teamers, bug-bounty hunters and DevSecOps
-engineers a single, scriptable surface over the entire offensive toolchain -
-from OSINT and network discovery, through web/cloud/hardware/radio
-exploitation, to reporting and disclosure - and puts a **self-improving,
-tool-calling AI agent** on top of it.
+It gives security researchers, red teamers, bug-bounty hunters, and DevSecOps
+engineers one scriptable surface over the offensive toolchain - OSINT and
+network discovery, web/cloud/hardware/radio work, reporting, and disclosure -
+with a **tool-calling AI agent** on top that can run the same methods.
 ## In numbers
 | Namespace | Count | What it is |
 |---|---|---|
-| `PWN::Plugins::*` | **66** | Wrappers for external + native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
+| `PWN::Plugins::*` | **66** | Wrappers for external and native tooling (Burp, Nmap, Metasploit, Shodan, browsers, serial, ...) |
 | `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
 | `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
 | `PWN::WWW::*` | **21** | Site-specific browser automations (HackerOne, BugCrowd, Google, LinkedIn, ...) |
@@ -24,32 +22,32 @@ tool-calling AI agent** on top of it.
 | `bin/pwn_*` | **53** | Headless CLI drivers for CI/CD |
 | Agent toolsets | **12** · **78 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · extrospection · cron · swarm |
-## The three ways to use it
+## Three ways to use it
-1. **`pwn` REPL** - a Pry shell with the whole `PWN::` namespace pre-loaded.
-   Prototype an attack chain interactively, one method call at a time.
+1. **`pwn` REPL** - a Pry shell with the whole `PWN::` namespace loaded.
+   Prototype an attack chain one method call at a time.
 2. **`pwn-ai`** - a natural-language TUI (or `pwn --ai "..."` one-shot) where an
-   LLM plans and executes those same method calls for you, records what
-   worked, and gets better at it.
+   LLM plans and runs those same method calls, records what worked, and
+   improves over time.
 3. **`bin/pwn_*` drivers** - thin CLIs over the plugins, for cron and CI/CD.
 ## What makes it different
-- **Everything is Ruby, everything is a method.** No YAML DSLs, no plugins-in-a-
-  black-box. If you can call it in the REPL, the AI agent can call it, a driver
+- **Everything is Ruby, everything is a method.** No YAML DSLs, no black-box
+  plugins. If you can call it in the REPL, the AI agent can call it, a driver
   can call it, and a cron job can call it.
-- **Closed self-improvement loop.** Metrics + Learning + **Reward** (ORM/PRM
-  judge, sentinel) + **Curriculum** (mistake-driven self-play, HER,
-  regression-gated LoRA) on the introspection side; Snapshot + Drift + Intel
-  + Verify on the extrospection side; joined by `extro_correlate`, which
-  tells the agent whether a failure was *its* fault or *the world* changed -
-  and writes the lesson back into the prompt for next time.
+- **Closed feedback loop.** Metrics + Learning + **Reward** (ORM/PRM judge,
+  sentinel) + **Curriculum** (mistake-driven self-play, HER, regression-gated
+  LoRA) on the introspection side; Snapshot + Drift + Intel + Verify on the
+  extrospection side; joined by `extro_correlate`, which tells the agent
+  whether a failure was *its* fault or *the world* changed - and writes the
+  lesson back into the next prompt.
 - **Native multi-agent.** `PWN::AI::Agent::Swarm` runs personas (each a full
   tool-calling agent, optionally on a *different* LLM engine) that debate,
-  broadcast and share an append-only bus - no IRC daemon, no external service.
+  broadcast, and share an append-only bus - no IRC daemon, no external service.
 - **Self-healing state.** `PWN::Setup` (doctor/provisioner) + `PWN::Migrate`
   (schema-stamped `~/.pwn` verifier/auto-migrator) make `gem install pwn` →
-  `pwn setup` the entire install *and* upgrade story on every OS.
+  `pwn setup` the full install and upgrade path on every supported OS.
 ![Overall Architecture](diagrams/overall-pwn-architecture.svg)

data/documentation/Why-PWN.md CHANGED Viewed

@@ -2,20 +2,20 @@
 ## The problem
-Offensive security is a **toolchain problem**. A single engagement touches
+Offensive security is a **toolchain problem**. One engagement may touch
 `nmap`, `burp`, `msfconsole`, a headless browser, `adb`, `gqrx`, three cloud
 consoles, a fuzzer, `radare2`, a spreadsheet of findings, and a bug-bounty
-submission form. Each tool has its own config, its own output format, and its
-own idea of what a "target" is. Gluing them together is 80 % of the job - and
-that glue is rewritten, badly, on every engagement.
+form. Each tool has its own config, its own output format, and its own idea
+of what a "target" is. Gluing them together is most of the job - and that
+glue gets rewritten, badly, on every engagement.
-Meanwhile, LLM agents are extraordinary at *planning* attack chains but have no
-reliable, auditable way to *execute* them against a real host.
+LLM agents are strong at *planning* attack chains, but they still need a
+reliable, auditable way to *run* those steps on a real host.
 ## The design bet
 PWN bets that the right abstraction is **plain Ruby methods with a uniform
-`opts = {}` signature**, exposed simultaneously to:
+`opts = {}` signature**, exposed at the same time to:
 - a human in a REPL,
 - an LLM in a tool-calling loop,
@@ -23,8 +23,8 @@ PWN bets that the right abstraction is **plain Ruby methods with a uniform
 - a cron job at 3 am.
 Because every capability is a method, the same line of code works in all four
-contexts. Because every method is open-source Ruby, it's auditable - critical
-when the caller is an autonomous agent.
+places. Because every method is open-source Ruby, you can read it - which is
+critical when the caller is an autonomous agent.
 ## Why open primitives matter
@@ -35,13 +35,14 @@ when the caller is an autonomous agent.
 | Agent output is a PDF | Agent output is a `PWN::Reports` object *and* a distilled skill *and* a memory entry |
 | One vendor's model | Five interchangeable engines; swarm can pit them against each other |
-## Why the self-improvement loop matters
+## Why the feedback loop matters
-A pentest framework that doesn't learn repeats the same dead-end scans forever.
-PWN records **per-tool success rate**, **per-task outcome**, **host drift**,
-and **external CVE intel**, then correlates them so tomorrow's run starts where
-today's finished. See [Skills, Memory & Learning](Skills-Memory-Learning.md),
-[Reinforcement Learning](Reinforcement-Learning.md) and
+A pentest framework that does not learn repeats the same dead-end scans
+forever. PWN records **per-tool success rate**, **per-task outcome**, **host
+drift**, and **external CVE intel**, then correlates them so tomorrow's run
+can start where today's left off. See
+[Skills, Memory & Learning](Skills-Memory-Learning.md),
+[Reinforcement Learning](Reinforcement-Learning.md), and
 [Extrospection](Extrospection.md).
 **Next:** [How PWN Works](How-PWN-Works.md)

data/documentation/pwn-REPL.md CHANGED Viewed

@@ -41,14 +41,14 @@ commands.
 | Keystroke | Works on | Notes |
 |---|---|---|
 | **SHIFT + ENTER** | kitty · wezterm · foot · alacritty · ghostty · xterm · Konsole · iTerm2 · Windows Terminal · Terminator¹ | preferred; requires the emulator to encode modified Enter |
-| **ALT + ENTER** | *everything*, incl. all VTE terminals | universal fallback — every emulator sends `\e\r` |
+| **ALT + ENTER** | *everything*, incl. all VTE terminals | universal fallback - every emulator sends `\e\r` |
 | trailing **`\`** + ENTER | *everything* | bash/irb/psql-style continuation; `\` is stripped on submit |
-¹ Terminator (and every other libvte host — GNOME Terminal, Tilix,
+¹ Terminator (and every other libvte host - GNOME Terminal, Tilix,
 xfce4-terminal, Guake, Ptyxis) cannot distinguish SHIFT+ENTER from
 ENTER at the escape-sequence level ([GNOME/vte #2601](https://gitlab.gnome.org/GNOME/vte/-/issues/2601),
 [#2607](https://gitlab.gnome.org/GNOME/vte/-/issues/2607)). For
-Terminator specifically, pwn ships a GTK plugin that fixes it — install
+Terminator specifically, pwn ships a GTK plugin that fixes it - install
 with:
 ```console

data/documentation/pwn-ai-Agent.md CHANGED Viewed

@@ -72,7 +72,7 @@ $ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
    by `Curriculum.hindsight`; `Reflect.on` writes durable lessons via
    `ai.reflect_engine` (teacher-student - a frontier engine may author the
    lesson a local engine reads); `Reward.sentinel` warns when success_rate ≠
-   judge_mean ≠ (1 − user_correction_rate); when `auto_extrospect` is also on,
+   judge_mean ≠ (1 - user_correction_rate); when `auto_extrospect` is also on,
    `Extrospection.auto_extrospect` runs (`AUTO_SECTIONS = host/repo/env` only -
    never toolchain/rf/web, never launches Burp/ZAP/msf/gqrx). Transcript is
    flushed to `~/.pwn/sessions/`.
@@ -118,7 +118,7 @@ full `Loop.run` under a persona overlay) that share a JSONL bus. See
   local.
 - `PWN::AI::Agent::Learning.export_finetune` + `Reward.export_dpo` turn every
   successful session and every preference pair into supervised / DPO
-  datasets under `~/.pwn/finetune/` — `Curriculum.train_and_gate` then
+  datasets under `~/.pwn/finetune/` - `Curriculum.train_and_gate` then
   LoRA-tunes the local model and promotes only under **gate v2** (resolved
   margin + mean judge + frozen smoke set). Preference pairs use trajectory
   geometry (P9/P14/P15): revised answers / winning traces, not `CORRECTION:` prose; `scrub_preferences` + export filter; practice lands `shape: :winning_trace`.

data/lib/pwn/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module PWN
-  VERSION = '0.5.651'
+  VERSION = '0.5.652'
 end

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pwn
 version: !ruby/object:Gem::Version
-  version: 0.5.651
+  version: 0.5.652
 platform: ruby
 authors:
 - 0day Inc.