pwn 0.5.617 → 0.5.618

data/documentation/NmapIt.md

@@ -1,18 +1,24 @@
-# NmapIt
+# `PWN::Plugins::NmapIt`
 
-`PWN::Plugins::NmapIt` provides a convenient Ruby wrapper around Nmap for reconnaissance.
+Thin, composable wrapper over `nmap` with structured XML parsing.
 
-## Features
+![Network & infra testing](diagrams/network-infra-testing.svg)
 
-- Easy target specification (hosts, ranges, CIDR)
-- Parsing of XML output into usable Ruby structures
-- Service version detection, script execution support
-- Integration with other plugins (e.g. feed into TransparentBrowser or Shodan)
+```ruby
+r = 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] }}" }
+```
 
-Commonly used early in agent workflows:
+CLI: `pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/`
 
-> "Run NmapIt against 10.0.0.0/24, identify web services, then spider with TransparentBrowser."
+Pairs with `extro_observe` to persist banners for later
+[correlation](Extrospection.md), and with `PWN::Plugins::Sock` /
+`PWN::Plugins::Metasploit` for follow-up.
 
-See source in `lib/pwn/plugins/nmap_it.rb`.
-
-[[Diagrams]]
+[← Home](Home.md) · [Plugins](Plugins.md)

data/documentation/Persistence.md

@@ -0,0 +1,38 @@
+# `~/.pwn/` — Persistence Map
+
+Every byte PWN remembers between processes lives here.
+
+![~/.pwn map](diagrams/persistence-filesystem.svg)
+
+| Path | Owner | Format | Reset tool | Purpose |
+|---|---|---|---|---|
+| `config.yml` | `PWN::Config` | YAML | edit by hand | engines, keys, agent options |
+| `memory.json` | `PWN::Memory` | JSON array | `memory_clear` | facts · prefs · lessons · env — injected into every prompt |
+| `skills/*.md` | `PWN::Config.load_skills` | Markdown + YAML front-matter | `skill_delete` | reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST) |
+| `learning.jsonl` | `PWN::AI::Agent::Learning` | JSON-per-line | `learning_reset` | task outcome log → success_rate |
+| `metrics.json` | `PWN::AI::Agent::Metrics` | JSON | `metrics_reset` | per-tool calls · success · avg_duration · last_error |
+| `extrospection.json` | `PWN::AI::Agent::Extrospection` | JSON | `extro_reset` | host snapshot + previous baseline + observations[] |
+| `sessions/*.jsonl` | `PWN::Sessions` | JSON-per-line | `sessions_delete` | full transcript per pwn-ai run |
+| `cron/jobs.yml` | `PWN::Cron` | YAML | `cron_remove` | scheduled prompt/ruby/script jobs |
+| `cron/log/*.log` | `PWN::Cron` | text | rm | last_run output |
+| `agents.yml` | `PWN::AI::Agent::Swarm` | YAML | edit / `agent_spawn` | persona registry |
+| `swarm/<id>/bus.jsonl` | `Swarm` | JSON-per-line | rm -rf | append-only multi-agent chat |
+| `swarm/<id>/personas.json` | `Swarm` | JSON | rm | persona → session_id map |
+| `~/.pwn_history` | Pry | text | rm | REPL input history |
+
+## Back it up
+
+```bash
+tar czf pwn-state-$(date +%F).tgz -C "$HOME" .pwn
+```
+
+## Start fresh for a new engagement
+
+```ruby
+# inside pwn-ai — keeps config & skills, wipes engagement-specific state
+extro_reset(confirm: true)     # host snapshot + observations
+learning_reset(confirm: true)  # task outcomes (optional)
+metrics_reset(confirm: true)   # tool telemetry (optional)
+```
+
+[← Home](Home.md) · [Configuration](Configuration.md)

data/documentation/Plugins.md

@@ -1,59 +1,109 @@
-# Plugins
+# `PWN::Plugins` — All 66 Modules
 
-PWN ships with **66+** plugins under `PWN::Plugins::*`.
+Every plugin is a plain Ruby module of `public_class_method def self.x(opts = {})`
+methods with self-documenting `.help`. Source: `lib/pwn/plugins/*.rb`.
 
-## Browsing Plugins
+![Plugin ecosystem](diagrams/plugin-ecosystem.svg)
+
+## Discover in the REPL
 
 ```ruby
 PWN::Plugins.constants.sort
-PWN::Plugins::BurpSuite.methods(false).sort   # preferred web proxy/scanner
+PWN::Plugins::BurpSuite.help
+ls PWN::Plugins::NmapIt
+show-source PWN::Plugins::Fuzz.generate
 ```
 
-## Major Categories & Highlights
-
-### Web / Proxy / Scanning
-- **burp_suite** (preferred) — Headless + live interaction with Burp Suite Professional
-- **zaproxy** — OWASP ZAP support (fallback)
-- **transparent_browser** — Headless/visible browser automation, spidering, JS execution
-- **spider**
-- **nmap_it** — Nmap wrapper + parsing
-- **nessus_cloud**, **nexpose_vuln_scan**, **openvas**
-
-### Exploitation & Post-Exploitation
-- **metasploit**
-- **assembly**
-- **fuzz**
-- **packet**
-- **beef** (Browser Exploitation Framework)
-- **tor**
-
-### Recon / OSINT
-- **shodan**
-- **hunter**
-- **ip_info**
-- **github**
-- **hacker_one**
-
-### Data & Auth
-- **authentication_helper**, **basic_auth**, **oauth2**
-- **dao_ldap**, **dao_mongo**, **dao_postgres**, **dao_sqlite3**
-- **vault**
-
-### Mobile / Hardware / Misc
-- **android**
-- **serial**, **bus_pirate**, **msr206**
-- **ocr**, **pdf_parse**, **voice**
-- **blockchain**, **bounty** (HackerOne), **defect_dojo**
+## By category
 
-### Utility
-- **file_fu**, **json_pathify**, **log**, **pwn_logger**, **thread_pool**
-- **monkey_patch**, **xxd**, **char**, **vin**, **ssn**, **credit_card**
+### Web / Proxy / Browser
+| Module | Purpose | Doc |
+|---|---|---|
+| **`BurpSuite`** ⭐ | Headless + REST control of Burp Pro; active/passive scan | [BurpSuite](BurpSuite.md) |
+| `Zaproxy` | OWASP ZAP (fallback) | — |
+| **`TransparentBrowser`** | Watir/Chrome headless or visible; devtools; proxy-aware | [Transparent-Browser](Transparent-Browser.md) |
+| `Spider` | Recursive crawler | — |
+| `OpenAPI` | Swagger/OpenAPI parse + fuzz targets | — |
+| `URIScheme` | URI helpers | — |
+
+### Network
+| Module | Purpose | Doc |
+|---|---|---|
+| **`NmapIt`** | Nmap wrapper + XML parse | [NmapIt](NmapIt.md) |
+| `Sock` | Raw TCP/UDP client; banner grab | — |
+| `Packet` | Craft/sniff L2/L3 (PacketFu) | — |
+| `Tor` | Start/rotate Tor for egress | — |
+| `IPInfo` | Geo/ASN lookup | — |
+
+### Exploitation
+| Module | Purpose | Doc |
+|---|---|---|
+| **`Metasploit`** | msfrpcd client; run modules; sessions | [Metasploit](Metasploit.md) |
+| **`Fuzz`** | Mutation/generation fuzzer | [Fuzzing](Fuzzing.md) |
+| `BeEF` | Browser Exploitation Framework hooks | — |
+| `Assembly` | asm ↔ opcodes (multi-arch, keystone/capstone) | — |
+
+### OSINT / Recon
+| Module | Purpose |
+|---|---|
+| `Shodan` | host/search/GraphQL introspection |
+| `Hunter` | email discovery |
+| `Github` | code/secret search |
+| `HackerOne` | program/report API |
+
+### Data Access / Parsing
+| Module | Purpose |
+|---|---|
+| `DAOLdap` · `DAOMongo` · `DAOPostgres` · `DAOSqlite3` | DB clients |
+| `JSONPathify` | JSONPath query |
+| `PDFParse` · `OCR` | document extraction |
+| `ScannableCodes` | QR/barcode gen/read |
 
-Full list (current as of build):
-`android assembly authentication_helper baresip basic_auth beef black_duck_binary_analysis burp_suite bus_pirate char credit_card dao_ldap dao_mongo dao_postgres dao_sqlite3 defect_dojo detect_os ein file_fu fuzz git github hacker_one hunter ip_info irc jenkins jira_data_center json_pathify log mail_agent metasploit monkey_patch msr206 nessus_cloud nexpose_vuln_scan nmap_it oauth2 ocr open_api openvas packet pdf_parse pony ps pwn_logger rabbit_mq repl scannable_codes serial shodan slack_client sock spider ssn thread_pool tor transparent_browser twitter_api uri_scheme vault vin voice vsphere xxd zaproxy`
+### Auth / Secrets
+| Module | Purpose |
+|---|---|
+| `OAuth2` · `BasicAuth` · `AuthenticationHelper` | credential flows |
+| `Vault` | HashiCorp Vault |
+
+### Hardware / Physical
+| Module | Purpose | Doc |
+|---|---|---|
+| `Serial` · `BusPirate` | UART/SPI/I²C | [Hardware](Hardware.md) |
+| `MSR206` | magstripe reader/writer | [Hardware](Hardware.md) |
+| `Android` | adb push/pull/shell/screencap | [Hardware](Hardware.md) |
+| `BareSIP` · `Voice` | VoIP war-dialing / TTS | [Hardware](Hardware.md) |
+
+### CI / DevOps / Vuln-Mgmt
+| Module | Purpose |
+|---|---|
+| `Jenkins` | jobs/views/plugins/users |
+| `Git` | repo helpers |
+| `vSphere` | VMware inventory |
+| `DefectDojo` | import/reimport findings |
+| `BlackDuckBinaryAnalysis` | SBOM + CVE match |
+| `NessusCloud` · `NexposeVulnScan` · `OpenVAS` | commercial/OSS scanners |
+| `JiraDataCenter` | ticket findings |
+
+### Comms
+| Module | Purpose |
+|---|---|
+| `MailAgent` · `Pony` | SMTP send |
+| `SlackClient` · `IRC` · `TwitterAPI` | chat/notify |
+| `RabbitMQ` | AMQP |
+
+### Utility
+`FileFu` · `ThreadPool` · `Log` · `PwnLogger` · `Char` · `XXD` · `DetectOS` ·
+`CreditCard` · `SSN` · `EIN` · `VIN` · `PS` · `MonkeyPatch` · `REPL`
 
-Each plugin has self-documenting method signatures viewable via the REPL or source in `lib/pwn/plugins/`.
+## Full alphabetical list
 
-See individual plugin pages or source for details. Many plugins accept common options and return rich Ruby objects.
+`Android Assembly AuthenticationHelper BareSIP BasicAuth BeEF
+BlackDuckBinaryAnalysis BurpSuite BusPirate Char CreditCard DAOLdap DAOMongo
+DAOPostgres DAOSqlite3 DefectDojo DetectOS EIN FileFu Fuzz Git Github
+HackerOne Hunter IPInfo IRC Jenkins JiraDataCenter JSONPathify Log MailAgent
+Metasploit MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt OAuth2 OCR
+OpenAPI OpenVAS Packet PDFParse Pony PS PwnLogger RabbitMQ REPL ScannableCodes
+Serial Shodan SlackClient Sock Spider SSN ThreadPool Tor TransparentBrowser
+TwitterAPI URIScheme Vault VIN Voice Vsphere XXD Zaproxy`
 
-[[Diagrams]]
+[← Home](Home.md) · [Diagrams](Diagrams.md)

data/documentation/Reporting.md

@@ -1,28 +1,35 @@
-# Reporting
+# `PWN::Reports` — Findings Pipeline
 
-`PWN::Reports` generates structured output from scans, agent runs, SAST results, and manual findings.
+![Reporting pipeline](diagrams/reporting-pipeline.svg)
 
-## Capabilities
+## Generators  (`lib/pwn/reports/*.rb`)
 
-- Vulnerability report templating (Markdown + other formats)
-- Integration with defect trackers (`PWN::Plugins::DefectDojo`, Jira, etc.)
-- Automated report generation after agent tasks or plugin runs
-- Custom report drivers
+| Module | Consumes | Emits |
+|---|---|---|
+| `Reports::SAST` | `PWN::SAST::Factory` output | HTML (with `HTMLHeader`/`HTMLFooter`) + JSON |
+| `Reports::Fuzz` | `PWN::Plugins::Fuzz` crash log | HTML + JSON |
+| `Reports::URIBuster` | `pwn_www_uri_buster` output | HTML |
+| `Reports::Phone` | `PWN::Plugins::BareSIP` recon | HTML |
+| `Reports::HTMLHeader` / `HTMLFooter` | — | shared chrome for all HTML reports |
 
-## Template
+## Delivery integrations
 
-See example report templates in the PWN repo (or generate with `PWN::Reports`). Full pipeline in [Diagrams](Diagrams.md).
+| Plugin | Purpose |
+|---|---|
+| `PWN::Plugins::DefectDojo` | `importscan` / `reimportscan` / `engagement_create` (also `bin/pwn_defectdojo_*`) |
+| `PWN::Plugins::JiraDataCenter` | Create issues from findings |
+| `PWN::Plugins::SlackClient` / `MailAgent` | Notify |
 
-## Usage Patterns
-
-Typically invoked at the end of reconnaissance → scanning → exploitation → analysis workflows:
+## Example
 
 ```ruby
-PWN::Reports.generate(...)
+findings = PWN::SAST::Factory.start(dir_path: './src')
+PWN::Reports::SAST.generate(
+  dir_path: './src', results_hash: findings, output_dir: './out'
+)
+PWN::Plugins::DefectDojo.importscan(
+  engagement_id: 42, file: './out/report.json', scan_type: 'PWN SAST'
+)
 ```
 
-The `pwn-ai` agent is frequently instructed to "analyze findings and produce a report."
-
-Combined with `PWN::Plugins::HackerOne` / bounty modules for streamlined disclosure workflows.
-
-[[Diagrams]]
+[← Home](Home.md) · [SAST](SAST.md) · [Fuzzing](Fuzzing.md)

data/documentation/SAST.md

@@ -1,32 +1,49 @@
-# SAST (Static Application Security Testing)
+# `PWN::SAST` — Static Application Security Testing
 
-`PWN::SAST` provides a growing collection of static analysis signatures and test case generators.
+48 language-aware rule modules + a `TestCaseEngine` + a `Factory` loader.
+Source: `lib/pwn/sast/*.rb`. CLI: `bin/pwn_sast`.
 
-## Location
+![SAST pipeline](diagrams/code-scanning-sast.svg)
 
-`lib/pwn/sast/` — one file per vulnerability class or mechanism.
+## Run it
 
-## Current Coverage (examples)
-
-- Command execution (multiple languages)
-- Deserialization (Java, etc.)
-- Eval / dangerous functions
-- CSRF, redirect, inner HTML, postMessage issues
-- Log4j, ReDoS, path traversal patterns
-- Credential / secret patterns (keystore, passwords, AWS keys)
-- Modern issues: prototype pollution, etc.
-- Custom signature engine + factory
-
-## Usage
+```bash
+# CLI driver
+pwn_sast -d /path/to/src -o /tmp/sast_out
+```
 
 ```ruby
-PWN::SAST.constants
-PWN::SAST::TestCaseEngine.generate(...)
-# Or call specific check modules
+# REPL / pwn_eval
+findings = PWN::SAST::Factory.start(dir_path: '/path/to/src')
+PWN::Reports::SAST.generate(dir_path: '/path/to/src',
+                            results_hash: findings,
+                            output_dir: '/tmp/sast_out')
 ```
 
-SAST results feed directly into reporting and can be orchestrated by the `pwn-ai` agent or custom drivers.
+## Rule families (48 modules)
+
+| Family | Modules |
+|---|---|
+| **Command execution** | `CmdExecutionJava` · `CmdExecutionPython` · `CmdExecutionRuby` · `CmdExecutionGoLang` · `CmdExecutionScala` · `Shell` · `Sudo` |
+| **Web / DOM** | `CSRF` · `Redirect` · `ReDOS` · `InnerHTML` · `OuterHTML` · `LocationHash` · `WindowLocationHash` · `PostMessage` · `LocalStorage` · `BeefHook` |
+| **Injection / eval** | `SQL` · `Eval` · `DeserialJava` · `Log4J` · `PHPInputMechanisms` · `PHPTypeJuggling` · `TypeScriptTypeJuggling` |
+| **Crypto / secrets** | `MD5` · `SSL` · `Keystore` · `PaddingOracle` · `PrivateKey` · `Signature` · `Token` · `Password` · `Base64` · `HTTPAuthorizationHeader` |
+| **Memory / native** | `BannedFunctionCallsC` · `UseAfterFree` |
+| **Infra / meta** | `AWS` · `AMQPConnectAsGuest` · `ApacheFileSystemUtilAPI` · `PomVersion` · `Version` · `Port` · `Logger` · `ThrowErrors` · `TaskTag` · `Emoticon` |
+| **Engine** | `Factory` (loader) · `TestCaseEngine` (probe generator) |
+
+## Write a rule
+
+Each rule implements `self.scan(opts = {})` taking `dir_path:` and returning an
+array of `{file:, line:, match:, cwe:, severity:}` hashes. Copy any existing
+rule in `lib/pwn/sast/`, add your regex/AST logic, and it's auto-loaded by
+`Factory`.
+
+## Downstream
+
+`PWN::Reports::SAST` → HTML + JSON → `PWN::Plugins::DefectDojo.importscan` →
+`PWN::Plugins::JiraDataCenter` tickets.
 
-See `lib/pwn/sast/` source for the full and growing list of modules.
+**See also:** [Reporting](Reporting.md) · [CLI Drivers](CLI-Drivers.md)
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/SDR.md

@@ -0,0 +1,40 @@
+# `PWN::SDR` — Software-Defined Radio & RF
+
+![SDR flow](diagrams/sdr-radio-flow.svg)
+
+## Modules  (`lib/pwn/sdr/*.rb`)
+
+| Module | Purpose |
+|---|---|
+| **`GQRX`** | Remote-control a running GQRX instance over TCP: tune, set demod, squelch, record, `get_spectrum_snapshot` (pure-Ruby FFT), scan ranges |
+| `FlipperZero` | Serial control of Flipper (sub-GHz, NFC, IR, iButton) |
+| `RFIDler` | 125 kHz RFID reader/emulator |
+| `SonMicroRFID` | SM130 13.56 MHz reader |
+| `FrequencyAllocation` | ITU/FCC band-plan lookup — "what lives at 433.92 MHz?" |
+| `Decoder::*` | Demodulator/protocol helpers |
+
+## CLI
+
+```bash
+pwn_gqrx_scanner --start 430e6 --stop 440e6 --step 12.5e3 --mode fast
+pwn_gqrx_scanner --start 118e6 --stop 137e6 --mode iterative --squelch -60
+```
+
+See skill `pwn_gqrx_scanner_fast_vs_iterative_scanning` for the trade-off.
+
+## REPL example
+
+```ruby
+g = PWN::SDR::GQRX.connect(host: '127.0.0.1', port: 7356)
+PWN::SDR::GQRX.set_freq(gqrx_sock: g, freq: 433_920_000)
+PWN::SDR::GQRX.set_demod(gqrx_sock: g, demod: 'AM')
+snap = PWN::SDR::GQRX.get_spectrum_snapshot(gqrx_sock: g)
+PWN::SDR::FrequencyAllocation.lookup(freq: 433_920_000)
+# => { band: 'ISM 433', typical: ['garage doors', 'weather stations', …] }
+```
+
+Record signal intel with `extro_observe(source: 'gqrx', category: 'recon', …)`.
+
+**See also:** [Hardware](Hardware.md) · [Extrospection](Extrospection.md)
+
+[← Home](Home.md)

data/documentation/Sessions.md

@@ -0,0 +1,39 @@
+# Sessions — Transcript Persistence
+
+Every `pwn-ai` conversation (top-level *and* per-persona in a Swarm) is
+appended as JSON-per-line to `~/.pwn/sessions/<id>.jsonl`.
+
+![Sessions ↔ Cron ↔ Swarm](diagrams/sessions-cron-automation.svg)
+
+## Why keep transcripts?
+
+- `learning_reflect(session_id:)` mines them for durable lessons → Memory.
+- `learning_distill_skill(name:, session_id:)` turns a winning run into a
+  reusable Skill.
+- `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
+  across `agent_ask` calls.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `sessions_current` | The id *this* conversation is being written to |
+| `sessions_list(limit:)` | Newest-first index (id · size · mtime · lines) |
+| `sessions_view(session_id:, truncate:)` | Read entries |
+| `sessions_delete(session_id:)` | Prune noisy/dev transcripts so `reflect` corpus stays clean |
+| `sessions_stats` | totals across the whole directory |
+
+## File format
+
+```json
+{"role":"system","ts":"2026-07-07T22:08:02Z","content":"…"}
+{"role":"user","ts":"…","content":"…"}
+{"role":"assistant","ts":"…","content":"…","tool_calls":[…]}
+{"role":"tool","ts":"…","name":"shell","content":"…"}
+```
+
+**See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[Swarm](Swarm.md) · [Persistence](Persistence.md)
+
+[← Home](Home.md)

data/documentation/Skills-Memory-Learning.md

@@ -1,44 +1,64 @@
-# Skills, Memory & Learning
+# Memory · Skills · Learning · Metrics — Introspection
 
-One of PWN's most powerful features is its self-improving closed loop.
+The **inward-facing** half of the pwn-ai feedback loop: how the agent measures
+its own performance and turns wins into permanent capability.
 
-## Memory (`PWN::Memory`)
+![Memory / Skills detail](diagrams/memory-skills-detailed.svg)
 
-Persistent facts, preferences, lessons, and environment data stored in `~/.pwn/memory.json`.
+## The four stores
 
-Use from REPL / agent:
-- `PWN::Memory.remember(key, value, category: :fact)`
-- `PWN::Memory.recall(query)`
+| Store | File | Write tool | Read tool | Injected as |
+|---|---|---|---|---|
+| **Memory** | `memory.json` | `memory_remember` | `memory_recall` | `MEMORY` block — durable facts / prefs / lessons / env |
+| **Skills** | `skills/*.md` | `skill_create` · `learning_distill_skill` | `skill_list` · `skill_view` | `SKILLS` list — reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST/URL) |
+| **Learning** | `learning.jsonl` | `learning_note_outcome` · `learning_reflect` | `learning_outcomes` · `learning_stats` | `LEARNING` block — recent outcomes + success_rate |
+| **Metrics** | `metrics.json` | *automatic* (every Dispatch) | `metrics_summary` | `TOOL EFFECTIVENESS` block — steer tool choice |
 
-Injected into every future `pwn-ai` session.
+## The lifecycle of a lesson
 
-## Skills
+```text
+1. Dispatch runs a tool           → Metrics.record(tool, ok?, ms)
+2. Final answer produced          → Learning.auto_reflect(session_id)
+3. Reflect finds a durable insight → Memory.remember(lesson_xxxx, …)
+4. A whole workflow succeeded      → Learning.distill_skill(name, session_id, references:)
+5. Next launch: PromptBuilder injects all four blocks → the model already knows.
+```
 
-Reusable, versionable markdown procedures stored in `~/.pwn/skills/`.
+## Skill file format
 
-- Created automatically via distillation of successful agent runs.
-- Manually via `skill_create` or editing YAML+markdown files.
-- Contain front-matter `references:` (CWE, CVE, ATT&CK, NIST, URLs).
-- Exposed to the agent and listed via `skill_list` / `skill_view`.
+```markdown
+---
+references:
+  - CWE-89
+  - T1190
+  - https://portswigger.net/web-security/sql-injection
+---
+# sqli_union_enum
 
-Example skills:
-- `deep_exploitation`
-- `vulnerability_research_fundamentals`
-- `xai_grok_oauth_device_flow`
+1. Confirm injection with `' AND 1=1 --`.
+2. Find column count with `ORDER BY n`.
+3. …
 
-## Learning Loop
+## References
+- CWE-89
+- T1190
+```
 
-- `PWN::AI::Agent::Metrics` — per-tool success rate + duration (`~/.pwn/metrics.json`)
-- `PWN::AI::Agent::Learning` — outcomes, reflections, skill distillation (`~/.pwn/learning.jsonl`)
-- Successful workflows become durable skills available to all future sessions.
+`PWN::Config.parse_skill_references` reads both the YAML front-matter **and**
+the `## References` section, deduplicates, and exposes them via
+`skill_view(name)[:references]`.
 
-## Management Commands (REPL)
+## Housekeeping
 
-- `pwn-ai-memory`
-- `pwn-ai-sessions`
-- `pwn-ai-cron`
-- `skill_list`, `skill_view`, `skill_create`, `skill_add_reference`
+| Tool | When |
+|---|---|
+| `learning_consolidate(max_entries: 200)` | MEMORY block getting long/noisy |
+| `learning_reset(confirm: true)` | dev-experiment noise polluted success_rate |
+| `metrics_reset(confirm: true)` | fixed a broken tool; stale 0 % is misleading |
+| `skill_delete(name)` | auto-distilled skill turned out low-quality |
+| `learning_auto_reflect_toggle(enabled: false)` | during noisy fuzz loops |
 
-This system turns one-off wins into institutional knowledge.
+**See also:** [Extrospection](Extrospection.md) — the outward-facing half ·
+[Sessions](Sessions.md) · [Persistence](Persistence.md)
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/Swarm.md

@@ -0,0 +1,71 @@
+# Swarm — Native Multi-Agent Orchestration
+
+`PWN::AI::Agent::Swarm` replaces the legacy `pwn-irc` (inspircd + weechat +
+PRIVMSG) transport with **first-class sub-agents** built directly on
+`PWN::AI::Agent::Loop`. Each persona is a *full* tool-calling agent — Memory,
+Skills, Learning, Metrics and Extrospection all apply — so the
+self-improvement loop covers the whole swarm.
+
+![Swarm](diagrams/swarm-multi-agent.svg)
+
+## Files
+
+| Path | Contains |
+|---|---|
+| `~/.pwn/agents.yml` | Persona registry (name → role/engine/toolsets/max_iters) |
+| `~/.pwn/swarm/<id>/bus.jsonl` | Append-only chat every persona reads/writes |
+| `~/.pwn/swarm/<id>/personas.json` | persona name → `PWN::Sessions` id |
+
+No daemon. Cross-session / cross-process communication == another `pwn-ai` (or
+a `PWN::Cron` job) calling `Swarm.ask` with the same `swarm_id`.
+
+## Define personas
+
+```ruby
+agent_spawn(name: 'red_team',
+            role: 'Offensive operator. Propose the most aggressive next step.',
+            engine: 'grok',
+            toolsets: %w[terminal pwn memory skills extrospection])
+
+agent_spawn(name: 'blue_team',
+            role: 'Defender. Critique red_team, flag detection risk & OPSEC.',
+            engine: 'anthropic',
+            toolsets: %w[pwn memory extrospection])
+```
+
+> Omit `swarm` from a persona's toolsets to stop it recursively spawning
+> further sub-agents. Recursion is also hard-capped by
+> `PWN::Env[:ai][:agent][:max_depth]` (default 3).
+
+## Verbs
+
+| Tool | Use for |
+|---|---|
+| `agent_list` | See who's defined |
+| `agent_spawn` | Define / overwrite a persona |
+| `agent_ask(name, request)` | One turn of one persona → reply comes back to *you* |
+| `agent_debate(names, topic, rounds:)` | Round-robin critique — each sees the bus tail |
+| `agent_broadcast(request)` | Fan-out; returns `{name => reply}` for voting |
+| `swarm_bus(swarm_id)` | Tail a bus to inspect a prior/concurrent conversation |
+| `swarm_list` | Find a `swarm_id` to resume |
+
+## Example: adversarial exploit review
+
+```ruby
+tx = agent_debate(
+  names:  %w[red_team blue_team exploit_dev],
+  topic:  'Target runs Jenkins 2.426.2 on :8080 — plan initial access.',
+  rounds: 3
+)
+# later, in a different pwn-ai process:
+agent_ask(name: 'red_team', swarm_id: tx[:swarm_id],
+          request: 'blue_team raised WAF concerns — revise the payload.')
+```
+
+Because each persona can pin a **different engine**, the debate is real model
+diversity, not one model role-playing.
+
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) ·
+[Agent Tool Registry](Agent-Tool-Registry.md) · [Sessions](Sessions.md)
+
+[← Home](Home.md)