pwn 0.5.617 → 0.5.620

data/documentation/Mistakes.md

@@ -0,0 +1,96 @@
+# Mistakes — The Negative-Feedback Loop
+
+`PWN::AI::Agent::Mistakes` is the **negative** half of the pwn-ai learning
+loop. Where [Learning](Skills-Memory-Learning.md) records *what worked* and
+[Metrics](Skills-Memory-Learning.md) records *how often* a tool worked,
+Mistakes records **specific failure patterns** with a stable fingerprint so
+the agent can (a) recognise it is repeating itself, (b) be told exactly what
+**not** to do again in every future system prompt, and (c) capture the **fix**
+once one is found so the avoidance lesson becomes an actionable correction.
+
+![Mistakes negative-feedback loop](diagrams/mistakes-negative-feedback.svg)
+
+## The failure fingerprint
+
+A "mistake" is keyed by `sha12(tool + normalised_error)`. Normalisation 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
+detector**, and it survives across sessions.
+
+| Field | Meaning |
+|---|---|
+| `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) |
+| `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]` |
+| `sessions` | last 10 session_ids that hit it |
+
+## How the loop closes (why it does **not** repeat mistakes)
+
+```text
+Loop.run --(tool failure)---------> Mistakes.record         (persist + count++)
+Loop.run --(same sig, count≥3)----> guard_repeated_failure  (uses PERSISTENT count →
+                                                             fires on the 1st recurrence
+                                                             in a NEW session, not the 3rd)
+Loop.run --(failure w/ known fix)-> inline correction_hint  ("seen 5×, sig=…, KNOWN FIX: …"
+                                                             → self-corrects NEXT iteration)
+Loop.run --(user says "wrong")----> check_user_correction   (flip last outcome + record)
+PromptBuilder <-------------------- Mistakes.to_context     (KNOWN MISTAKES + KNOWN FIXES)
+model --(tool call)---------------> mistakes_record / mistakes_resolve
+```
+
+## Four ingest paths — nothing slips through
+
+| Source | Trigger | What is recorded |
+|---|---|---|
+| `:tool` | any tool dispatch returns `success:false` / raises | *automatic* — `Loop.record_metrics` |
+| `:loop` | iteration budget exhausted with no final answer | *automatic* — `Loop.run` epilogue |
+| `:user_correction` | next user message matches `CORRECTION_RX` (*"no that's wrong"*, *"still broken"*, *"try again"*, …) | `check_user_correction` — also flips the previous `Learning` outcome to `success:false` |
+| `:model` | the model itself calls `mistakes_record` | wrong assumption, wrong file, hallucinated API — failures that are **not** dispatch errors |
+
+## Tools
+
+| Tool | Does |
+|---|---|
+| `mistakes_list` | count-sorted fingerprints (signature · tool · error · count · resolved · fix) |
+| `mistakes_record` | proactively fingerprint a semantic mistake YOU just made |
+| `mistakes_resolve` | attach the **fix** → promoted to `PWN::Memory` `:lesson` **and** handed straight back inline via `correction_hint` on the next recurrence. If the same sig recurs it auto-reopens as `[REGRESSED]`. |
+| `mistakes_reset` | wipe `~/.pwn/mistakes.json` (new engagement) |
+
+## What the model sees every turn
+
+`PromptBuilder` injects `Mistakes.to_context` between the `LEARNING` and
+`TOOL EFFECTIVENESS` blocks:
+
+```text
+KNOWN MISTAKES (do NOT repeat — call mistakes_resolve once fixed)
+  ✗ [a1b2c3d4e5f6] shell ×4 [REPEATING]: nmpa: command not found
+  ✗ [7f8e9d0c1b2a] pwn_eval ×2 [REGRESSED]: nomethoderror: undefined method `scan_range' — last fix (insufficient): use fast_scan_range
+KNOWN FIXES (apply these instead of repeating the mistake)
+  ✓ [c0ffee123456] shell: connection refused port N — FIX: start ZAP first via PWN::Plugins::Zaproxy.start
+```
+
+…and every failed dispatch gets an **inline** postscript:
+
+```text
+[pwn-ai/mistakes] seen 4× across 3 session(s), sig=a1b2c3d4e5f6 | KNOWN FIX: binary is spelled `nmap`
+```
+
+so the very next iteration self-corrects without re-discovering the fix.
+
+## Regression detection
+
+Resolving a mistake does **not** delete it. If the same signature fires again
+after `mistakes_resolve`, `record()` clears `:resolved`, sets `:regressed`,
+and the entry re-enters the `KNOWN MISTAKES` block tagged `[REGRESSED]` with
+its (now-insufficient) previous fix shown inline — the strongest possible
+"your last fix didn't hold" signal.
+
+**See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[Extrospection](Extrospection.md) · [Persistence](Persistence.md) ·
+[pwn-ai Agent](pwn-ai-Agent.md)
+
+[← Home](Home.md)

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,40 @@
+# `~/.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 |
+| **`mistakes.json`** | **`PWN::AI::Agent::Mistakes`** | **JSON `{sig → entry}`** | **`mistakes_reset`** | **failure fingerprints · cross-session count · fix · `[REPEATING]` · `[REGRESSED]`** |
+| `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/net/toolchain/repo/env/**rf** 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
+mistakes_reset(confirm: true)  # failure fingerprints (host-specific errors)
+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,58 @@
+# `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 — median noise floor, DC/LO-leakage null, band-edge guard), `fast_scan_range` |
+| `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::*`** | 20 protocol demodulators/decoders — `ADSB APT Bluetooth DECT FLEX GPS GSM Iridium LoRa LTE Morse P25 Pager POCSAG RDS RFID RTL433 RTTY WiFi ZigBee` |
+
+## CLI
+
+```bash
+# FFT sweep — SNR-gated peak detection (no false-positive flood)
+pwn_gqrx_scanner --start 430e6 --stop 440e6 --fft-scan \
+                 --avg 8 --min-snr-db 10 --capture-secs 0.10
+
+# Classic iterative S-meter scan
+pwn_gqrx_scanner --start 118e6 --stop 137e6 --step 12.5e3 \
+                 --strength-lock -60 --audio-gain-db 6
+```
+
+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', …] }
+```
+
+## RF ↔ Extrospection
+
+The AI agent is RF-aware. `extro_snapshot(sections: [:rf])` runs `probe_rf`
+(RTL-SDR / HackRF / SoapySDR / Flipper / GQRX-socket inventory) and RF signal
+intel is recorded with a first-class `:rf` observation category:
+
+```ruby
+extro_observe(source: 'gqrx', category: :rf, target: '433.920MHz',
+              data: 'peak -34.2 dBFS bw=200k FSK — likely garage remote')
+```
+
+`extro_correlate` then cross-references `:rf` observations against missing
+`RF_BINS` / unplugged hardware so the agent can tell "no signal" from "no
+dongle".
+
+**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)