pwn 0.5.615 → 0.5.618

data/documentation/Diagrams.md

@@ -1,57 +1,140 @@
-# PWN Data Flow Diagrams (DFDs)
+# PWN Data-Flow Diagrams
 
-This page provides visual SVG Data Flow Diagrams illustrating how the PWN offensive cybersecurity framework operates across its key components and workflows.
+26 SVG diagrams, all rendered from Graphviz sources in
+[`diagrams/dot/`](diagrams/dot/) with a single shared visual theme
+(see [`_THEME.md`](diagrams/dot/_THEME.md)). Rebuild everything with:
 
-## Core Architecture & Learning
+```bash
+cd documentation/diagrams && ./build.sh
+```
 
-- **PWN-AI Feedback Learning Loop**: The closed-loop self-improvement system using Memory, Skills, Metrics, and Learning to evolve capabilities.
-  ![PWN AI Feedback Learning Loop](diagrams/pwn-ai-feedback-learning-loop.svg)
+Every diagram uses strict layer→layer edges (`newrank=true` + `{rank=same}`
+groups) so lines never criss-cross.
 
-- **PWN REPL Prototyping**: Interactive development and rapid prototyping inside the full PWN namespace.
-  ![PWN REPL Prototyping](diagrams/pwn-repl-prototyping.svg)
+---
 
-- **History Command to Driver Generation**: How REPL exploration and `history` are turned into reusable Drivers and Skills.
-  ![History to Drivers](diagrams/history-to-drivers.svg)
+## 1 · Architecture
 
-## Primary Security Workflows
+### Overall PWN Architecture
+[source](diagrams/dot/overall-pwn-architecture.dot) · doc: [How PWN Works](How-PWN-Works.md)
+![overall-pwn-architecture](diagrams/overall-pwn-architecture.svg)
 
-- **Penetration Testing Workflow**: End-to-end red teaming from recon to reporting, leveraging all PWN capabilities.
-  ![Penetration Testing Workflow](diagrams/penetration-testing-workflow.svg)
+### `~/.pwn/` Persistence Map
+[source](diagrams/dot/persistence-filesystem.dot) · doc: [Persistence](Persistence.md)
+![persistence-filesystem](diagrams/persistence-filesystem.svg)
 
-- **Network & Infrastructure Testing**: Discovery, enumeration, scanning, packet crafting, and infra-specific testing (AWS, Jenkins, etc.).
-  ![Network & Infrastructure Testing](diagrams/network-infra-testing.svg)
+### Plugin Ecosystem (66 modules)
+[source](diagrams/dot/plugin-ecosystem.dot) · doc: [Plugins](Plugins.md)
+![plugin-ecosystem](diagrams/plugin-ecosystem.svg)
 
-- **Web Application Testing**: Proxy-driven spidering, active scanning, manual assisted testing, and API security assessment. (BurpSuite preferred)
-  ![Web Application Testing](diagrams/web-application-testing.svg)
+---
 
-- **Code Scanning & SAST**: Static analysis, test case generation, and vulnerability reporting using `PWN::SAST`.
-  ![Code Scanning SAST](diagrams/code-scanning-sast.svg)
+## 2 · Entry Points
 
-- **Fuzzing Workflows**: Protocol, file, network, and web fuzzing with monitoring and corpus refinement.
-  ![Fuzzing Workflows](diagrams/fuzzing-workflow.svg)
+### `pwn` REPL Prototyping
+[source](diagrams/dot/pwn-repl-prototyping.dot) · doc: [pwn REPL](pwn-REPL.md)
+![pwn-repl-prototyping](diagrams/pwn-repl-prototyping.svg)
 
-- **Reverse Engineering Flow**: Binary/firmware analysis, patching, targeted fuzzing, and exploit crafting.
-  ![Reverse Engineering Flow](diagrams/reverse-engineering-flow.svg)
+### REPL History → Reusable Driver / Skill
+[source](diagrams/dot/history-to-drivers.dot) · doc: [Drivers](Drivers.md)
+![history-to-drivers](diagrams/history-to-drivers.svg)
 
-## Additional Notes
+### Driver Anatomy (`bin/pwn_*`)
+[source](diagrams/dot/driver-framework.dot) · doc: [CLI Drivers](CLI-Drivers.md)
+![driver-framework](diagrams/driver-framework.svg)
 
-- Diagrams are generated using Graphviz (dot) from source `.dot` files in `diagrams/dot/`.
-- These visualize the integration of:
-  - `PWN::Plugins` (67+ modules)
-  - `PWN::AI::Agent` + tool calling + LLM providers
-  - `PWN::Memory`, `PWN::Skills`, and Learning loop
-  - `PWN::SAST`, `PWN::Reports`, `PWN::Driver`
-- For the source definitions, see `diagrams/dot/*.dot`.
-- Update these diagrams by editing the `.dot` files and re-rendering with `dot -Tsvg`.
+---
 
-## Related Wiki Pages
+## 3 · AI Agent
 
-- [How PWN Works](How-PWN-Works.md)
-- [pwn-ai Agent](pwn-ai-Agent.md)
-- [pwn REPL](pwn-REPL.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
-- [Plugins](Plugins.md)
-- [SAST](SAST.md)
-- [Drivers](Drivers.md)
+### pwn-ai Closed Self-Improvement Loop
+[source](diagrams/dot/pwn-ai-feedback-learning-loop.dot) · doc: [Skills, Memory & Learning](Skills-Memory-Learning.md)
+![pwn-ai-feedback-learning-loop](diagrams/pwn-ai-feedback-learning-loop.svg)
 
-[[Diagrams]]
+### Multi-Provider LLM Integration
+[source](diagrams/dot/ai-integration-tool-calling.dot) · doc: [AI Integration](AI-Integration.md)
+![ai-integration-tool-calling](diagrams/ai-integration-tool-calling.svg)
+
+### Agent Tool Registry (10 toolsets)
+[source](diagrams/dot/agent-tool-registry.dot) · doc: [Agent Tool Registry](Agent-Tool-Registry.md)
+![agent-tool-registry](diagrams/agent-tool-registry.svg)
+
+### Memory · Skills · Sessions Detail
+[source](diagrams/dot/memory-skills-detailed.dot) · doc: [Skills, Memory & Learning](Skills-Memory-Learning.md)
+![memory-skills-detailed](diagrams/memory-skills-detailed.svg)
+
+### Extrospection — World Awareness
+[source](diagrams/dot/extrospection-world-awareness.dot) · doc: [Extrospection](Extrospection.md)
+![extrospection-world-awareness](diagrams/extrospection-world-awareness.svg)
+
+### Swarm — Native Multi-Agent
+[source](diagrams/dot/swarm-multi-agent.dot) · doc: [Swarm](Swarm.md)
+![swarm-multi-agent](diagrams/swarm-multi-agent.svg)
+
+### Cron — Scheduled Jobs
+[source](diagrams/dot/cron-scheduling.dot) · doc: [Cron](Cron.md)
+![cron-scheduling](diagrams/cron-scheduling.svg)
+
+### Sessions ↔ Cron ↔ Swarm Continuity
+[source](diagrams/dot/sessions-cron-automation.dot) · doc: [Sessions](Sessions.md)
+![sessions-cron-automation](diagrams/sessions-cron-automation.svg)
+
+---
+
+## 4 · Security Workflows
+
+### End-to-End Penetration Test
+[source](diagrams/dot/penetration-testing-workflow.dot)
+![penetration-testing-workflow](diagrams/penetration-testing-workflow.svg)
+
+### Web Application Testing
+[source](diagrams/dot/web-application-testing.dot) · doc: [BurpSuite](BurpSuite.md)
+![web-application-testing](diagrams/web-application-testing.svg)
+
+### Burp ⭐ vs ZAP Selection
+[source](diagrams/dot/burp-vs-zap-preference.dot)
+![burp-vs-zap-preference](diagrams/burp-vs-zap-preference.svg)
+
+### Network & Infrastructure Testing
+[source](diagrams/dot/network-infra-testing.dot) · doc: [NmapIt](NmapIt.md)
+![network-infra-testing](diagrams/network-infra-testing.svg)
+
+### SAST / Code Scanning
+[source](diagrams/dot/code-scanning-sast.dot) · doc: [SAST](SAST.md)
+![code-scanning-sast](diagrams/code-scanning-sast.svg)
+
+### Fuzzing
+[source](diagrams/dot/fuzzing-workflow.dot) · doc: [Fuzzing](Fuzzing.md)
+![fuzzing-workflow](diagrams/fuzzing-workflow.svg)
+
+### Reverse Engineering & Binary Exploitation
+[source](diagrams/dot/reverse-engineering-flow.dot) · doc: [Hardware](Hardware.md)
+![reverse-engineering-flow](diagrams/reverse-engineering-flow.svg)
+
+### Zero-Day Research Lifecycle
+[source](diagrams/dot/zero-day-research-flow.dot)
+![zero-day-research-flow](diagrams/zero-day-research-flow.svg)
+
+### Reporting Pipeline
+[source](diagrams/dot/reporting-pipeline.dot) · doc: [Reporting](Reporting.md)
+![reporting-pipeline](diagrams/reporting-pipeline.svg)
+
+---
+
+## 5 · Domain-Specific
+
+### AWS Cloud Security (90 services)
+[source](diagrams/dot/aws-cloud-security.dot) · doc: [AWS](AWS.md)
+![aws-cloud-security](diagrams/aws-cloud-security.svg)
+
+### SDR / Radio Hacking
+[source](diagrams/dot/sdr-radio-flow.dot) · doc: [SDR](SDR.md)
+![sdr-radio-flow](diagrams/sdr-radio-flow.svg)
+
+### Hardware & Physical-Layer
+[source](diagrams/dot/hardware-hacking.dot) · doc: [Hardware](Hardware.md)
+![hardware-hacking](diagrams/hardware-hacking.svg)
+
+---
+
+[← Back to Home](Home.md)

data/documentation/Drivers.md

@@ -1,25 +1,52 @@
-# Drivers & Custom Automation
+# Drivers — Turn a REPL Session into a Shipped Binary
 
-`PWN::Driver` and the `/opt/pwn/bin/` directory provide patterns for packaging reusable security automation.
+A **driver** is a small executable in `bin/` that wires `OptionParser` to one
+or more `PWN::` calls. All 52 shipped `pwn_*` binaries follow the same
+15-line template.
 
-## What is a Driver?
+![History → Driver → CI](diagrams/history-to-drivers.svg)
 
-A self-contained Ruby script or gem that:
-- Loads the `pwn` environment
-- Orchestrates multiple plugins, AI calls, or custom logic
-- Can be scheduled via cron or run standalone
+## Workflow
 
-## Examples
+1. **Prototype in the REPL** until the calls work.
+2. `history` → copy the winning lines.
+3. Drop them into the template below as `bin/pwn_<name>`.
+4. `chmod +x bin/pwn_<name>` · add to `pwn.gemspec` executables · `rake install`.
+5. (Optional) `learning_distill_skill(name: '<name>')` so the agent knows the
+   procedure too.
 
-Look in `/opt/pwn/bin/` (shipped with the gem).
+## Template
 
-## Creating New Drivers
+```ruby
+#!/usr/bin/env ruby
+# frozen_string_literal: true
 
-1. Study existing examples in `bin/`.
-2. Use `PWN::Driver` helpers where appropriate.
-3. Leverage the full plugin + AI surface.
-4. Distill recurring successful patterns into **Skills**.
+require 'optparse'
+require 'pwn'
 
-Drivers + Skills + Agent = extremely powerful autonomous red teaming / research platform.
+opts = {}
+OptionParser.new do |o|
+  o.banner = "USAGE: #{File.basename($PROGRAM_NAME)} [opts]"
+  o.on('-tTARGET', '--target=TARGET', 'Required target') { |v| opts[:target] = v }
+  o.on('-oDIR',    '--out=DIR',       'Output directory') { |v| opts[:out]    = v }
+end.parse!
 
-[[Diagrams]]
+raise OptionParser::MissingArgument, '-t' unless opts[:target]
+
+result = PWN::Plugins::NmapIt.port_scan(target: opts[:target])
+PWN::Reports::Fuzz.generate(result: result, dir_path: opts[:out]) if opts[:out]
+puts result
+```
+
+## Three artefact types from one REPL session
+
+| Artefact | Made with | Consumed by |
+|---|---|---|
+| `bin/pwn_<name>` | template above | shell / CI |
+| `~/.pwn/skills/<name>.md` | `learning_distill_skill` | every future pwn-ai prompt |
+| `cron` job | `cron_create(ruby: '…')` | system crontab → unattended |
+
+**See also:** [CLI Drivers](CLI-Drivers.md) · [Cron](Cron.md) ·
+[Skills, Memory & Learning](Skills-Memory-Learning.md)
+
+[← Home](Home.md)

data/documentation/Extrospection.md

@@ -0,0 +1,54 @@
+# Extrospection — World Awareness
+
+`PWN::AI::Agent::Extrospection` is the **outward-facing** counterpart to
+[Learning](Skills-Memory-Learning.md). Where Learning/Metrics ask *"how well
+did **I** do?"*, Extrospection asks *"what does the **world** look like right
+now, and has it changed under me?"*
+
+![Extrospection engine](diagrams/extrospection-world-awareness.svg)
+
+## Verbs
+
+| Tool | Does | Persists to |
+|---|---|---|
+| `extro_snapshot` | Fingerprint host/net/toolchain/repo/env → hash | `extrospection.json` (`snapshot` + rotates `previous`) |
+| `extro_drift` | Diff live-vs-stored (or stored-vs-previous) | — returns `{changed, added, removed}` with dotted keys |
+| `extro_observe` | Record a recon fact (banner, CVE match, topology note) | `observations[]` |
+| `extro_observations` | Query recorded facts by source/category/target/tag | — |
+| `extro_intel` | Query NVD / CIRCL / Exploit-DB for keyword or CVE | optional `record: true` → `:intel` observations |
+| `extro_correlate` | **Join** introspection ↔ extrospection | — actionable findings |
+| `extro_stats` | snapshot age · observation count · drift counts | — |
+| `extro_reset` | Wipe snapshot + observations (new engagement) | — |
+| `extro_auto_toggle` | Enable/disable auto-snapshot after every final answer | `PWN::Env[:ai][:agent][:auto_extrospect]` |
+
+## `extro_correlate` — the point of the whole thing
+
+```text
+(a) Metrics tools with <50 % success   ×  toolchain drift / missing binaries
+(b) Learning failures on day X         ×  host/net/repo drift on day X
+(c) recorded :intel observations       ×  installed component versions
+```
+
+Output tells the agent whether a failure was **its own fault** ("I called the
+API wrong") or **the world changed** ("nmap was upgraded and the flag moved")
+— and that distinction is written back into MEMORY so the next run doesn't
+waste iterations rediscovering it.
+
+## Typical engagement flow
+
+```ruby
+extro_reset(confirm: true)             # clean slate for new scope
+extro_snapshot                         # baseline
+# … recon …
+extro_observe(source: 'nmap', target: '10.0.0.5',
+              category: 'recon', data: 'OpenSSH 8.2p1 Ubuntu')
+extro_intel(query: 'OpenSSH 8.2p1', record: true)
+# … days later, something breaks …
+extro_drift                            # what moved?
+extro_correlate                        # why did it break?
+```
+
+**See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[pwn-ai Agent](pwn-ai-Agent.md)
+
+[← Home](Home.md)

data/documentation/FFI.md

@@ -0,0 +1,14 @@
+# `PWN::FFI` — Native Calls
+
+`PWN::FFI::Stdio` (`lib/pwn/ffi/stdio.rb`) exposes libc functions to Ruby via
+the `ffi` gem — useful for shellcode testing, format-string research and
+low-level RE without leaving the REPL.
+
+```ruby
+PWN::FFI::Stdio.printf(fmt: "leak: %p\n", args: [0x41414141])
+```
+
+Combine with `PWN::Plugins::Assembly` (opcodes ↔ asm) and `pwn-asm` for a
+minimal in-process exploit-dev workbench.
+
+[← Home](Home.md) · [Hardware](Hardware.md)

data/documentation/Fuzzing.md

@@ -0,0 +1,36 @@
+# Fuzzing — `PWN::Plugins::Fuzz` · `Sock` · `Packet`
+
+![Fuzzing workflow](diagrams/fuzzing-workflow.svg)
+
+## Generate
+
+```ruby
+payloads = PWN::Plugins::Fuzz.generate(
+  seed: "GET / HTTP/1.1\r\nHost: t\r\n\r\n",
+  strategy: :radamsa,       # :radamsa | :bitflip | :dictionary
+  count: 500
+)
+enc = PWN::Plugins::Char.url_encode(str: payloads.first)
+```
+
+## Deliver
+
+```ruby
+payloads.each do |p|
+  PWN::Plugins::Sock.connect(target: '10.0.0.5', port: 8080) do |s|
+    s.write(p); s.read
+  end
+end
+```
+
+For raw L2/L3: `PWN::Plugins::Packet`.
+CLI network fuzzer: `pwn_fuzz_net_app_proto -t HOST -p PORT -f seeds/`
+
+## Monitor & report
+
+`PWN::Plugins::PS` watches the target process; `PWN::Plugins::Log` tails its
+log; `PWN::Reports::Fuzz` renders crash → HTML/JSON.
+
+Feed unique crashes back as new seeds (`Log → Fuzz` dashed edge in the diagram).
+
+[← Home](Home.md) · [Reporting](Reporting.md)

data/documentation/General-PWN-Usage.md

@@ -1,40 +1,60 @@
-# General PWN Usage
+# General Usage — Day-One Cheat Sheet
 
-## Launching PWN
+## Launch
 
 ```bash
-$ pwn
-pwn[v0.5.613]:001 >>>
+$ pwn                         # interactive REPL
+$ pwn --ai "scan 10.0.0.0/24 with NmapIt and summarise open services"
+$ pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/   # headless driver
 ```
 
-## Essential Commands Inside REPL
+## Inside the REPL
 
-- `PWN.help` — overview of top-level modules
-- `PWN::Plugins.constants.sort` — list all plugins
-- `pwn-ai` — start the autonomous AI agent TUI (recommended)
-- `pwn-asm` — assembly/REPL for low-level work
-- `pwn-ai-memory`, `pwn-ai-sessions`, `pwn-ai-cron` — management helpers
-- `back` — exit `pwn-ai` mode
-- Full Ruby expressions work at any time.
-
-## Recommended Workflow
-
-1. Launch `pwn`
-2. Start `pwn-ai`
-3. Give natural language tasks that leverage plugins, skills, memory.
-4. Use `SHIFT+ENTER` for multi-line prompts.
-
-## Updating PWN
+```ruby
+PWN.help                            # top-level help
+PWN::Plugins.constants.sort         # list all 66 plugins
+PWN::Plugins::NmapIt.help           # per-plugin usage
+ls PWN::Plugins::BurpSuite          # Pry: list methods
+show-source PWN::SAST::SQL.scan     # Pry: read the code
+history                             # what you've typed → copy into a driver
+```
 
-See [Installation](Installation.md).
+## Custom REPL commands
+
+| Command | Does |
+|---|---|
+| `pwn-ai` | Enter the agent TUI (SHIFT+ENTER = newline, ENTER = submit) |
+| `pwn-asm` | Multi-line assembly ↔ opcode workbench |
+| `pwn-ai-memory` | Inspect / edit `~/.pwn/memory.json` |
+| `pwn-ai-sessions` | List / view / delete transcripts |
+| `pwn-ai-cron` | List / run scheduled jobs |
+| `pwn-ai-delegate` | Hand a task to a Swarm persona |
+| `welcome-banner` | Redraw a random `PWN::Banner` |
+| `toggle-pager` | Pry pager on/off |
+
+## A 60-second attack chain
+
+```ruby
+# 1. discover
+nmap = PWN::Plugins::NmapIt.port_scan(target: 'scanme.nmap.org')
+
+# 2. drive traffic through Burp
+burp = PWN::Plugins::BurpSuite.start(headless: true)
+b    = PWN::Plugins::TransparentBrowser.open(
+         browser_type: :headless, proxy: 'http://127.0.0.1:8080')
+b[:browser].goto 'http://scanme.nmap.org'
+
+# 3. active scan
+scan = PWN::Plugins::BurpSuite.active_scan(burp_obj: burp,
+         target_url: 'http://scanme.nmap.org')
+
+# 4. report
+PWN::Reports::SAST.generate(dir_path: '/tmp/src', output_dir: '/tmp/out')
+```
 
-## Persistent State
+Then say the same thing in English inside `pwn-ai` and watch the agent do it.
 
-Everything lives under `~/.pwn/`:
-- `skills/`
-- `memory.json`
-- `learning.jsonl`
-- `metrics.json`
-- sessions, cron jobs, etc.
+**Next:** [pwn REPL](pwn-REPL.md) · [pwn-ai Agent](pwn-ai-Agent.md) ·
+[CLI Drivers](CLI-Drivers.md)
 
-[[Diagrams]]
+[← Home](Home.md)

data/documentation/Hardware.md

@@ -0,0 +1,40 @@
+# Hardware & Physical-Layer Hacking
+
+![Hardware hacking](diagrams/hardware-hacking.svg)
+![Reverse engineering](diagrams/reverse-engineering-flow.svg)
+
+## Serial / Bus
+
+| Module | Use |
+|---|---|
+| `PWN::Plugins::Serial` | Generic UART (`/dev/ttyUSB*`) — read/write, baud detect |
+| `PWN::Plugins::BusPirate` | SPI/I²C/1-Wire via Bus Pirate |
+| `PWN::Plugins::MSR206` | ISO magstripe read/write (tracks 1-3) |
+
+CLI: `pwn_serial_msr206`, `pwn_serial_qualcomm_commands`,
+`pwn_serial_check_voicemail`, `pwn_serial_son_micro_sm132_rfid`
+
+## Mobile
+
+`PWN::Plugins::Android` — `adb_net_connect`, `adb_sh`, `adb_push/pull`,
+`take_screenshot`, `screen_record`, `list_installed_apps`, `dumpsys`,
+`open_app`, `find_hidden_codes`, `swipe`, `input`, `input_special`,
+`invoke_event_listener`. CLI war-dialer: `pwn_android_war_dialer`.
+
+## Voice / Telephony
+
+`PWN::Plugins::BareSIP` (SIP recon/war-dial), `PWN::Plugins::Voice` (TTS).
+CLI: `pwn_phone`.
+
+## Radio
+
+See [SDR](SDR.md) — GQRX, FlipperZero, RFIDler, SonMicro.
+
+## Binary / RE
+
+- `PWN::Plugins::XXD` — hex dump / patch
+- `PWN::Plugins::Assembly` + `pwn-asm` REPL — opcodes ↔ asm, multi-arch
+- `PWN::Plugins::BlackDuckBinaryAnalysis` — SBOM + CVE match on firmware
+- [`PWN::FFI`](FFI.md) — call libc from Ruby
+
+[← Home](Home.md) · [SDR](SDR.md) · [FFI](FFI.md)

data/documentation/Home.md

@@ -1,51 +1,78 @@
-# PWN Wiki
-
-Welcome to the PWN (pronounced /pōn/) Security Automation Framework Wiki.
-
-PWN is an open-source offensive cybersecurity automation framework and continuous security integration platform. It enables researchers, red teamers, penetration testers, and vulnerability researchers to discover zero-days, automate exploitation, perform web application testing, conduct SAST, orchestrate reconnaissance, and execute AI-augmented autonomous operations.
-
-## Visual Overview (Data Flow Diagrams)
-
-**Start here for visual understanding** — see [Diagrams.md](Diagrams.md) for 18+ SVG DFDs covering:
-
-- AI feedback learning loop & self-improvement
-- REPL prototyping + history → drivers
-- End-to-end penetration testing
-- Network / infrastructure testing
-- Web application testing (Burp preferred)
-- Code scanning / SAST
-- Fuzzing
-- Reverse engineering
-- Zero-day research flow
-- Overall architecture
-- Tool calling, plugins, memory/skills, reporting, etc.
-
-## Quick Navigation
-
-- [What is PWN](What-is-PWN.md)
-- [Why PWN](Why-PWN.md)
-- [How PWN Works](How-PWN-Works.md)
-- [Installation](Installation.md)
-- [General Usage](General-PWN-Usage.md)
-- [The pwn REPL](pwn-REPL.md)
-- [pwn-ai Autonomous Agent](pwn-ai-Agent.md)
-- [Plugins Overview](Plugins.md)
-- [AI & LLM Integration](AI-Integration.md)
-- [Skills, Memory & Learning](Skills-Memory-Learning.md)
-- [SAST](SAST.md)
-- [Reporting](Reporting.md)
-- [Drivers & Custom Automation](Drivers.md)
-- [Diagrams (All SVGs)](Diagrams.md)
-- [Troubleshooting](Troubleshooting.md)
-- [Contributing](Contributing.md)
-
-## Core Commands
-
-Inside the `pwn` REPL:
-- `PWN.help`
-- `pwn-ai` — launch AI agent TUI
-- See full list via `pwn` command help.
-
-**Local Wiki Root:** This wiki lives in `/opt/pwn/documentation/`.
-
-For the latest upstream see the [GitHub Project](https://github.com/0dayInc/pwn) and [rubydoc.info](https://www.rubydoc.info/gems/pwn).
+# PWN Documentation
+
+> **PWN** (/pōn/) — an open-source offensive-security automation framework and
+> continuous-security-integration platform written in Ruby.
+> 66 plugins · 48 SAST rules · 90 AWS wrappers · 21 WWW drivers · 52 CLI
+> drivers · 5 LLM engines · a self-improving multi-agent AI · one REPL.
+
+**Repo root:** `/opt/pwn` · **This wiki:** `/opt/pwn/documentation/` ·
+**Rebuild diagrams:** `documentation/diagrams/build.sh`
+
+---
+
+## 🗺️ Start Here
+
+| | |
+|---|---|
+| [What is PWN](What-is-PWN.md) | One-paragraph elevator pitch |
+| [Why PWN](Why-PWN.md) | Design philosophy — why another framework |
+| [How PWN Works](How-PWN-Works.md) | The five layers, with the architecture diagram |
+| [Installation](Installation.md) | RVM, gem, `./install.sh`, first launch |
+| [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
+| [Configuration](Configuration.md) | `~/.pwn/config.yml` — engines, keys, agent options |
+| **[All Data-Flow Diagrams](Diagrams.md)** | **26 SVGs** in one scrollable page |
+
+## 🚪 Entry Points
+
+| | |
+|---|---|
+| [The `pwn` REPL](pwn-REPL.md) | Pry shell with the whole `PWN::` namespace pre-loaded |
+| [`pwn-ai` Autonomous Agent](pwn-ai-Agent.md) | Natural-language TUI + `pwn --ai PROMPT` one-shot |
+| [CLI Drivers `bin/pwn_*`](CLI-Drivers.md) | 52 headless executables for CI/CD |
+| [Drivers (build your own)](Drivers.md) | Turn a REPL session into a shipped binary |
+
+## 🤖 AI Subsystem  (`PWN::AI`)
+
+| | |
+|---|---|
+| [AI / LLM Integration](AI-Integration.md) | OpenAI · Anthropic · Grok (OAuth) · Gemini · Ollama |
+| [Agent Tool Registry](Agent-Tool-Registry.md) | 10 toolsets · 45+ LLM-callable tools |
+| [Memory · Skills · Learning](Skills-Memory-Learning.md) | Introspection — the self-improvement loop |
+| [Extrospection](Extrospection.md) | World-awareness — snapshot · drift · intel · correlate |
+| [Swarm (Multi-Agent)](Swarm.md) | Personas · ask · debate · broadcast · shared bus |
+| [Sessions](Sessions.md) | Transcript persistence + reflection |
+| [Cron](Cron.md) | Scheduled autonomous jobs |
+
+## 🧩 Capability Namespaces  (`lib/pwn/*`)
+
+| | |
+|---|---|
+| [Plugins (66)](Plugins.md) | Every `PWN::Plugins::*` module by category |
+|   ↳ [BurpSuite](BurpSuite.md) ⭐ | Preferred web proxy / scanner |
+|   ↳ [TransparentBrowser](Transparent-Browser.md) | Headless / visible browser automation |
+|   ↳ [NmapIt](NmapIt.md) | Network discovery |
+|   ↳ [Metasploit](Metasploit.md) | RPC exploitation |
+|   ↳ [Fuzzing](Fuzzing.md) | `Fuzz` · `Sock` · `Packet` |
+|   ↳ [Hardware](Hardware.md) | Serial · BusPirate · MSR206 · Android · BareSIP |
+| [SAST (48 rules)](SAST.md) | Static analysis + test-case engine |
+| [WWW (21 drivers)](WWW.md) | Browser automations for real sites |
+| [AWS (90 services)](AWS.md) | Cloud-security enumeration |
+| [SDR](SDR.md) | GQRX · FlipperZero · RFIDler · SonMicro |
+| [Blockchain](Blockchain.md) | BTC · ETH helpers |
+| [Bounty](Bounty.md) | Lifecycle / auth-replay tooling |
+| [Reports](Reporting.md) | HTML/JSON output + DefectDojo/Jira |
+| [FFI](FFI.md) | Native calls |
+| [Banner](Banner.md) | 15 startup banners |
+
+## 🛠️ Meta
+
+| | |
+|---|---|
+| [`~/.pwn/` Filesystem Map](Persistence.md) | Every file PWN writes and why |
+| [Troubleshooting](Troubleshooting.md) | Common errors and fixes |
+| [Contributing](Contributing.md) | Conventions, RuboCop, spec rules |
+
+---
+
+<sub>Generated by pwn-ai. Edit any `.md` directly; edit any diagram in
+`documentation/diagrams/dot/*.dot` then run `./build.sh`.</sub>