pwn 0.5.613 → 0.5.617

data/documentation/diagrams/dot/overall-pwn-architecture.dot

@@ -0,0 +1,115 @@
+digraph "PWN_Overall_Architecture" {
+  graph [
+    label=<<B>PWN — Offensive Security Automation Framework</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Overall Architecture · lib/pwn/*</FONT>>,
+    labelloc=t, fontsize=22, fontname="Helvetica",
+    rankdir=TB, splines=spline, nodesep=0.55, ranksep=1.15,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, compound=true, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=11, style="filled,rounded",
+        shape=box, penwidth=1.4, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  /* ───────── L0 · ACTORS ───────── */
+  subgraph cluster_actors {
+    label="Actors"; fontcolor="#94a3b8"; style="rounded,dashed";
+    color="#334155"; bgcolor="#1e293b";
+    User   [label="👤  Researcher\nRed Team · Bug Hunter", fillcolor="#7dd3fc"];
+    CI     [label="⚙️  CI / CD\nHeadless pipelines",       fillcolor="#7dd3fc"];
+    LLM    [label="🤖  LLM Providers\nOpenAI · Anthropic\nGrok · Gemini · Ollama", fillcolor="#c4b5fd"];
+    Target [label="🎯  Attack Surface\nHosts · Web · Cloud\nRadio · Hardware", fillcolor="#fda4af"];
+  }
+  {rank=same; User; CI; LLM; Target}
+
+  /* ───────── L1 · ENTRY POINTS ───────── */
+  subgraph cluster_entry {
+    label="Entry Points  (bin/)"; fontcolor="#7dd3fc";
+    style=rounded; color="#0369a1"; bgcolor="#0c4a6e"; penwidth=2;
+    REPL  [label="🐚  pwn REPL\nPry + PWN:: preload",       fillcolor="#7dd3fc"];
+    PwnAI [label="✨  pwn-ai\nAgent TUI · pwn --ai",         fillcolor="#7dd3fc"];
+    CLI   [label="📜  bin/pwn_*\n52 CLI drivers",            fillcolor="#7dd3fc"];
+    Cronb [label="⏱  PWN::Cron\nScheduled jobs",            fillcolor="#7dd3fc"];
+  }
+  {rank=same; REPL; PwnAI; CLI; Cronb}
+
+  /* ───────── L2 · AI AGENT CORE ───────── */
+  subgraph cluster_agent {
+    label="PWN::AI::Agent"; fontcolor="#ddd6fe";
+    style=rounded; color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
+    Loop     [label="Loop\nplan → dispatch → observe",      fillcolor="#c4b5fd"];
+    Registry [label="Registry\n10 toolsets · 45+ tools",    fillcolor="#c4b5fd"];
+    Swarm    [label="Swarm\npersonas · debate · bus",        fillcolor="#c4b5fd"];
+    Prompt   [label="PromptBuilder\nMEMORY · SKILLS · EXTRO",fillcolor="#c4b5fd"];
+  }
+  {rank=same; Loop; Registry; Swarm; Prompt}
+
+  /* ───────── L3 · CAPABILITY NAMESPACES ───────── */
+  subgraph cluster_caps {
+    label="Capability Namespaces  (lib/pwn/*)"; fontcolor="#a7f3d0";
+    style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
+    Plugins [label="Plugins\n66 modules",     fillcolor="#6ee7b7"];
+    SAST    [label="SAST\n48 rules",          fillcolor="#6ee7b7"];
+    WWW     [label="WWW\n21 site drivers",    fillcolor="#6ee7b7"];
+    AWS     [label="AWS\n90 services",        fillcolor="#6ee7b7"];
+    SDR     [label="SDR\nGQRX · Flipper · RFID", fillcolor="#6ee7b7"];
+    Chain   [label="Blockchain\nBTC · ETH",   fillcolor="#6ee7b7"];
+    Bounty  [label="Bounty\nlifecycle replay", fillcolor="#6ee7b7"];
+    Reports [label="Reports\nHTML · JSON",    fillcolor="#6ee7b7"];
+  }
+  {rank=same; Plugins; SAST; WWW; AWS; SDR; Chain; Bounty; Reports}
+
+  /* ───────── L4 · PERSISTENCE (~/.pwn) ───────── */
+  subgraph cluster_persist {
+    label="Persistence  ~/.pwn/"; fontcolor="#fde68a";
+    style=rounded; color="#a16207"; bgcolor="#422006"; penwidth=2;
+    Memory   [label="memory.json",       shape=cylinder, fillcolor="#fcd34d"];
+    Skills   [label="skills/*.md",        shape=cylinder, fillcolor="#fcd34d"];
+    Learn    [label="learning.jsonl",     shape=cylinder, fillcolor="#fcd34d"];
+    Metrics  [label="metrics.json",       shape=cylinder, fillcolor="#fcd34d"];
+    Extro    [label="extrospection.json", shape=cylinder, fillcolor="#fcd34d"];
+    Sessions [label="sessions/*.jsonl",   shape=cylinder, fillcolor="#fcd34d"];
+    SwarmB   [label="swarm/*/bus.jsonl",  shape=cylinder, fillcolor="#fcd34d"];
+    CronF    [label="cron/jobs.yml",      shape=cylinder, fillcolor="#fcd34d"];
+  }
+  {rank=same; Memory; Skills; Learn; Metrics; Extro; Sessions; SwarmB; CronF}
+
+  /* ── L0 → L1 ── */
+  User -> REPL   [color="#38bdf8"];
+  User -> PwnAI  [color="#38bdf8"];
+  CI   -> CLI    [color="#38bdf8"];
+  CI   -> Cronb  [label="crontab", color="#38bdf8"];
+
+  /* ── L1 → L2 ── */
+  REPL  -> Loop     [color="#a78bfa"];
+  PwnAI -> Loop     [label="natural language", color="#a78bfa", penwidth=2];
+  PwnAI -> Registry [color="#a78bfa"];
+  CLI   -> Swarm    [style=invis];
+  Cronb -> Prompt   [style=invis];
+
+  /* ── L2 → L3 ── */
+  Loop     -> Plugins [label="pwn_eval", color="#34d399", penwidth=2];
+  Loop     -> SAST    [color="#34d399"];
+  Registry -> WWW     [color="#34d399"];
+  Registry -> AWS     [color="#34d399"];
+  Swarm    -> SDR     [color="#34d399"];
+  Swarm    -> Chain   [color="#34d399"];
+  Prompt   -> Bounty  [style=invis];
+  Prompt   -> Reports [style=invis];
+  CLI      -> Plugins [color="#34d399", constraint=false];
+
+  /* ── L3 → L4 ── */
+  Plugins -> Memory   [color="#f59e0b"];
+  SAST    -> Skills   [color="#f59e0b"];
+  WWW     -> Learn    [color="#f59e0b"];
+  AWS     -> Metrics  [color="#f59e0b"];
+  SDR     -> Extro    [color="#f59e0b"];
+  Chain   -> Sessions [color="#f59e0b"];
+  Bounty  -> SwarmB   [color="#f59e0b"];
+  Reports -> CronF    [color="#f59e0b"];
+
+  /* ── side flows (few, non-constraining) ── */
+  Loop    -> LLM    [label="tool-use API", color="#c4b5fd", constraint=false, penwidth=2];
+  Plugins -> Target [label="attack",       color="#fb7185", constraint=false, penwidth=2];
+  Prompt  -> Memory [label="inject", dir=back, color="#fbbf24", constraint=false, style=dashed];
+  Reports -> User   [label="findings", color="#38bdf8", constraint=false, penwidth=2];
+}

data/documentation/diagrams/dot/penetration-testing-workflow.dot

@@ -0,0 +1,60 @@
+digraph "PWN_Pentest" {
+  graph [
+    label=<<B>End-to-End Penetration Testing with PWN</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">recon → enumerate → exploit → post-ex → report</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.45, ranksep=1.2,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=10, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  Scope [label="🎯  Scope\ntargets · rules", fillcolor="#7dd3fc"];
+
+  subgraph cluster_recon {
+    label="1 · Recon"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Shodan [label="Plugins::Shodan\nHunter · IPInfo", fillcolor="#6ee7b7"];
+    CrtSh  [label="bin/pwn_crt_sh\nWWW::WaybackMachine", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_enum {
+    label="2 · Enumerate"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Nmap  [label="Plugins::NmapIt\nTCP/UDP discover", fillcolor="#6ee7b7"];
+    Spider[label="Plugins::Spider\nTransparentBrowser", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_vuln {
+    label="3 · Vuln Scan"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Burp   [label="Plugins::BurpSuite\nactive scan", fillcolor="#fcd34d"];
+    Nessus [label="NessusCloud\nOpenVAS · Nexpose", fillcolor="#fcd34d"];
+  }
+  subgraph cluster_xpl {
+    label="4 · Exploit"; fontcolor="#fecaca"; style=rounded;
+    color="#b91c1c"; bgcolor="#450a0a";
+    MSF  [label="Plugins::Metasploit", fillcolor="#fda4af"];
+    Fuzz [label="Plugins::Fuzz\nPacket · Sock", fillcolor="#fda4af"];
+  }
+  subgraph cluster_post {
+    label="5 · Post-Ex"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Beef [label="Plugins::BeEF\nAndroid · Serial", fillcolor="#c4b5fd"];
+    Tor  [label="Plugins::Tor\npivot / exfil",     fillcolor="#c4b5fd"];
+  }
+  Report [label="PWN::Reports\nHTML · JSON · DefectDojo", fillcolor="#7dd3fc"];
+
+  Scope  -> Shodan [color="#38bdf8"];
+  Scope  -> CrtSh  [color="#38bdf8"];
+  Shodan -> Nmap   [color="#34d399"];
+  CrtSh  -> Spider [color="#34d399"];
+  Nmap   -> Burp   [color="#f59e0b"];
+  Nmap   -> Nessus [color="#f59e0b"];
+  Spider -> Burp   [color="#f59e0b"];
+  Burp   -> MSF    [color="#fb7185"];
+  Nessus -> Fuzz   [color="#fb7185"];
+  MSF    -> Beef   [color="#a78bfa"];
+  Fuzz   -> Tor    [color="#a78bfa"];
+  Beef   -> Report [color="#38bdf8", penwidth=2];
+  Tor    -> Report [color="#38bdf8", penwidth=2];
+}

data/documentation/diagrams/dot/plugin-ecosystem.dot

@@ -0,0 +1,45 @@
+digraph "PWN_Plugins" {
+  graph [
+    label=<<B>PWN::Plugins — 66 Modules by Category</B>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.25, ranksep=1.5,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=9, style="filled,rounded",
+        shape=box, penwidth=1.2, color="#334155", fontcolor="#0f172a"];
+  edge [color="#94a3b8", penwidth=1.0, arrowsize=0.6];
+
+  Root [label="PWN::Plugins", fillcolor="#7dd3fc", fontsize=14, penwidth=2];
+
+  subgraph cluster_cat {
+    label=""; style=invis;
+    Web  [label="Web / Proxy",   fillcolor="#6ee7b7"];
+    Net  [label="Network",       fillcolor="#6ee7b7"];
+    Xpl  [label="Exploitation",  fillcolor="#6ee7b7"];
+    Osint[label="OSINT",         fillcolor="#6ee7b7"];
+    Data [label="Data / DAO",    fillcolor="#6ee7b7"];
+    Auth [label="Auth",          fillcolor="#6ee7b7"];
+    HW   [label="Hardware",      fillcolor="#6ee7b7"];
+    CI   [label="CI / DevOps",   fillcolor="#6ee7b7"];
+    Comm [label="Comms",         fillcolor="#6ee7b7"];
+    Util [label="Utility",       fillcolor="#6ee7b7"];
+  }
+  {rank=same; Web; Net; Xpl; Osint; Data; Auth; HW; CI; Comm; Util}
+
+  node [fillcolor="#fcd34d"];
+  w  [label="BurpSuite ⭐ · Zaproxy\nTransparentBrowser · Spider\nOpenAPI · URIScheme"];
+  n  [label="NmapIt · Sock · Packet\nTor · IPInfo"];
+  x  [label="Metasploit · Fuzz\nBeEF · Assembly"];
+  o  [label="Shodan · Hunter\nGithub · HackerOne"];
+  d  [label="DAO::LDAP/Mongo/PG/SQLite\nJSONPathify · PDFParse · OCR"];
+  a  [label="OAuth2 · BasicAuth\nAuthenticationHelper · Vault"];
+  h  [label="Serial · BusPirate\nMSR206 · Android · BareSIP"];
+  c  [label="Jenkins · Git · vSphere\nDefectDojo · BlackDuck"];
+  m  [label="MailAgent · SlackClient\nIRC · RabbitMQ · TwitterAPI · Voice"];
+  u  [label="FileFu · ThreadPool · Log\nChar · XXD · DetectOS\nScannableCodes · CreditCard\nSSN · EIN · VIN · Pony · PS"];
+
+  Root->Web; Root->Net; Root->Xpl; Root->Osint; Root->Data;
+  Root->Auth; Root->HW; Root->CI; Root->Comm; Root->Util;
+  Web->w; Net->n; Xpl->x; Osint->o; Data->d;
+  Auth->a; HW->h; CI->c; Comm->m; Util->u;
+}

data/documentation/diagrams/dot/pwn-ai-feedback-learning-loop.dot

@@ -0,0 +1,98 @@
+digraph "PWN_AI_Feedback_Learning_Loop" {
+  graph [
+    label=<<B>pwn-ai — Closed Self-Improvement Loop</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Introspection (self)  ⟷  Extrospection (world)</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=spline, nodesep=0.6, ranksep=1.0,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true, compound=true
+  ];
+  node [fontname="Helvetica", fontsize=11, style="filled,rounded",
+        shape=box, penwidth=1.4, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  /* L0 ─ actors */
+  User  [label="👤  Researcher", fillcolor="#7dd3fc"];
+  LLM   [label="🤖  LLM Provider", fillcolor="#c4b5fd"];
+  World [label="🌍  Host · Net · Repo\nToolchain · Intel feeds", fillcolor="#fda4af"];
+  {rank=same; User; LLM; World}
+
+  /* L1 ─ agent core */
+  subgraph cluster_core {
+    label="PWN::AI::Agent::Loop"; fontcolor="#ddd6fe";
+    style=rounded; color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
+    Prompt   [label="PromptBuilder\ninject context", fillcolor="#c4b5fd"];
+    Dispatch [label="Dispatch\ntool calls",           fillcolor="#c4b5fd"];
+    Result   [label="Result\nfinal answer",           fillcolor="#c4b5fd"];
+  }
+  {rank=same; Prompt; Dispatch; Result}
+
+  /* L2 ─ dual engines */
+  subgraph cluster_intro {
+    label="INTROSPECTION  (self)"; fontcolor="#a7f3d0";
+    style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
+    Metrics  [label="Metrics\nper-tool success · avg ms", fillcolor="#6ee7b7"];
+    Learning [label="Learning\nnote_outcome · reflect\nconsolidate · distill_skill", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_extro {
+    label="EXTROSPECTION  (world)"; fontcolor="#fde68a";
+    style=rounded; color="#a16207"; bgcolor="#422006"; penwidth=2;
+    Snapshot  [label="snapshot · drift\nhost/net/toolchain/repo", fillcolor="#fcd34d"];
+    Observe   [label="observe · intel\nrecon facts · CVE feed",   fillcolor="#fcd34d"];
+  }
+  {rank=same; Metrics; Learning; Snapshot; Observe}
+
+  /* L3 ─ correlate */
+  Correlate [label="extro_correlate()\n\"I did it wrong\"  vs  \"the world changed\"",
+             fillcolor="#fda4af", penwidth=2, fontsize=12];
+
+  /* L4 ─ persistence */
+  subgraph cluster_store {
+    label="~/.pwn/"; fontcolor="#94a3b8";
+    style="rounded,dashed"; color="#334155"; bgcolor="#1e293b";
+    Fmet [label="metrics.json",       shape=cylinder, fillcolor="#fcd34d"];
+    Flrn [label="learning.jsonl",     shape=cylinder, fillcolor="#fcd34d"];
+    Fmem [label="memory.json",        shape=cylinder, fillcolor="#fcd34d"];
+    Fskl [label="skills/*.md",         shape=cylinder, fillcolor="#fcd34d"];
+    Fext [label="extrospection.json", shape=cylinder, fillcolor="#fcd34d"];
+  }
+  {rank=same; Fmet; Flrn; Fmem; Fskl; Fext}
+
+  /* L0 → L1 */
+  User -> Prompt   [label="task", color="#38bdf8", penwidth=2];
+  LLM  -> Dispatch [label="tool_calls", dir=both, color="#a78bfa", penwidth=2];
+  World-> Result   [style=invis];
+
+  /* L1 internal */
+  Prompt -> Dispatch [color="#a78bfa"];
+  Dispatch -> Result [color="#a78bfa"];
+
+  /* L1 → L2 */
+  Dispatch -> Metrics  [label="record()", color="#34d399"];
+  Result   -> Learning [label="auto_reflect", color="#34d399"];
+  Dispatch -> Snapshot [label="probe", color="#f59e0b"];
+  Result   -> Observe  [label="auto_extrospect", color="#f59e0b"];
+  World    -> Snapshot [color="#fb7185", constraint=false];
+  World    -> Observe  [color="#fb7185", constraint=false];
+
+  /* L2 → L3 */
+  Metrics  -> Correlate [color="#34d399"];
+  Learning -> Correlate [color="#34d399"];
+  Snapshot -> Correlate [color="#f59e0b"];
+  Observe  -> Correlate [color="#f59e0b"];
+
+  /* L3 → L4 */
+  Correlate -> Fmet [style=invis];
+  Metrics   -> Fmet [color="#94a3b8"];
+  Learning  -> Flrn [color="#94a3b8"];
+  Learning  -> Fmem [label="lesson", color="#94a3b8"];
+  Learning  -> Fskl [label="skill",  color="#94a3b8"];
+  Observe   -> Fext [color="#94a3b8"];
+
+  /* feedback (dashed, non-constraining) */
+  Fmem -> Prompt [label="MEMORY block",  style=dashed, color="#fbbf24", constraint=false];
+  Fskl -> Prompt [label="SKILLS block",  style=dashed, color="#fbbf24", constraint=false];
+  Fext -> Prompt [label="EXTRO block",   style=dashed, color="#fbbf24", constraint=false];
+  Correlate -> Prompt [label="findings → next run", style=dashed, color="#fb7185",
+                       constraint=false, penwidth=2];
+  Result -> User [label="answer", color="#38bdf8", constraint=false, penwidth=2];
+}

data/documentation/diagrams/dot/pwn-repl-prototyping.dot

@@ -0,0 +1,56 @@
+digraph "PWN_REPL" {
+  graph [
+    label=<<B>The pwn REPL — Interactive Prototyping</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Pry + full PWN:: preload + custom commands</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=spline, nodesep=0.55, ranksep=0.9,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=10, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  User [label="👤  $ pwn", fillcolor="#7dd3fc"];
+
+  subgraph cluster_repl {
+    label="Plugins::REPL  (Pry)"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
+    Prompt  [label="pwn[v0.5.x]:001 >>>", fillcolor="#c4b5fd"];
+    Preload [label="autoload PWN::*\nBanner · MonkeyPatch", fillcolor="#c4b5fd"];
+    Hist    [label="~/.pwn_history\nreplay · edit", fillcolor="#c4b5fd"];
+  }
+  {rank=same; Prompt; Preload; Hist}
+
+  subgraph cluster_cmds {
+    label="Custom Commands"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    CAI   [label="pwn-ai",         fillcolor="#6ee7b7"];
+    CASM  [label="pwn-asm",        fillcolor="#6ee7b7"];
+    CMEM  [label="pwn-ai-memory",  fillcolor="#6ee7b7"];
+    CSESS [label="pwn-ai-sessions",fillcolor="#6ee7b7"];
+    CCRON [label="pwn-ai-cron",    fillcolor="#6ee7b7"];
+    CDEL  [label="pwn-ai-delegate",fillcolor="#6ee7b7"];
+  }
+  {rank=same; CAI; CASM; CMEM; CSESS; CCRON; CDEL}
+
+  subgraph cluster_ns {
+    label="Live Namespace"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    NS [label="PWN::Plugins  ·  PWN::SAST  ·  PWN::AWS  ·  PWN::SDR\nPWN::WWW  ·  PWN::Reports  ·  PWN::AI  ·  PWN::Memory",
+        fillcolor="#fcd34d", fontsize=11];
+  }
+
+  User -> Prompt  [color="#38bdf8", penwidth=2];
+  User -> Preload [style=invis];
+  User -> Hist    [style=invis];
+  Prompt  -> CAI   [color="#34d399"];
+  Prompt  -> CASM  [color="#34d399"];
+  Preload -> CMEM  [color="#34d399"];
+  Preload -> CSESS [color="#34d399"];
+  Hist    -> CCRON [color="#34d399"];
+  Hist    -> CDEL  [color="#34d399"];
+  CAI  -> NS [color="#f59e0b"];
+  CASM -> NS [color="#f59e0b"];
+  CMEM -> NS [color="#f59e0b"];
+  Prompt -> NS [label="direct call", color="#f59e0b", constraint=false, penwidth=2];
+}

data/documentation/diagrams/dot/reporting-pipeline.dot

@@ -0,0 +1,46 @@
+digraph "PWN_Reports" {
+  graph [
+    label=<<B>PWN::Reports — Findings Pipeline</B>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.45, ranksep=1.2,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=10, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  subgraph cluster_src {
+    label="Finding Sources"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Sast [label="PWN::SAST",     fillcolor="#6ee7b7"];
+    Fuzz [label="Plugins::Fuzz", fillcolor="#6ee7b7"];
+    Uri  [label="URI Buster",    fillcolor="#6ee7b7"];
+    Phone[label="BareSIP recon", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_gen {
+    label="Generators"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Rsast [label="Reports::SAST",      fillcolor="#fcd34d"];
+    Rfuzz [label="Reports::Fuzz",      fillcolor="#fcd34d"];
+    Ruri  [label="Reports::URIBuster", fillcolor="#fcd34d"];
+    Rphone[label="Reports::Phone",     fillcolor="#fcd34d"];
+  }
+  subgraph cluster_out {
+    label="Delivery"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    HTML [label="HTML\n(Header/Footer)", fillcolor="#c4b5fd"];
+    JSON [label="JSON",                   fillcolor="#c4b5fd"];
+    DD   [label="DefectDojo\nimport/reimport", fillcolor="#c4b5fd"];
+    Jira [label="JiraDataCenter",          fillcolor="#c4b5fd"];
+  }
+
+  Sast  -> Rsast  [color="#f59e0b"];
+  Fuzz  -> Rfuzz  [color="#f59e0b"];
+  Uri   -> Ruri   [color="#f59e0b"];
+  Phone -> Rphone [color="#f59e0b"];
+  Rsast  -> HTML [color="#a78bfa"];
+  Rfuzz  -> JSON [color="#a78bfa"];
+  Ruri   -> DD   [color="#a78bfa"];
+  Rphone -> Jira [color="#a78bfa"];
+}

data/documentation/diagrams/dot/reverse-engineering-flow.dot

@@ -0,0 +1,43 @@
+digraph "PWN_RE" {
+  graph [
+    label=<<B>Reverse Engineering &amp; Binary Exploitation</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">pwn-asm · Assembly · XXD · FFI · Radare2 banners</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.45, ranksep=1.2,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=10, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  Bin [label="🔎  Binary / Firmware", fillcolor="#7dd3fc"];
+
+  subgraph cluster_static {
+    label="Static"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    XXD  [label="Plugins::XXD\nhex dump / patch", fillcolor="#6ee7b7"];
+    BDBA [label="BlackDuckBinaryAnalysis\nSBOM · CVE match", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_disasm {
+    label="Disassemble"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Asm    [label="Plugins::Assembly\nopcodes ↔ asm\nmulti-arch", fillcolor="#fcd34d"];
+    PwnAsm [label="pwn-asm REPL\nmultiline shellcode",             fillcolor="#fcd34d"];
+  }
+  subgraph cluster_dyn {
+    label="Dynamic"; fontcolor="#fecaca"; style=rounded;
+    color="#b91c1c"; bgcolor="#450a0a";
+    FFI  [label="PWN::FFI::Stdio\nnative calls",   fillcolor="#fda4af"];
+    Fuzz [label="Plugins::Fuzz\ntargeted crashes",  fillcolor="#fda4af"];
+  }
+  Xpl [label="Exploit PoC\nMetasploit module", fillcolor="#c4b5fd"];
+
+  Bin -> XXD  [color="#38bdf8"];
+  Bin -> BDBA [color="#38bdf8"];
+  XXD  -> Asm    [color="#f59e0b"];
+  BDBA -> PwnAsm [color="#f59e0b"];
+  Asm    -> FFI  [color="#fb7185"];
+  PwnAsm -> Fuzz [color="#fb7185"];
+  FFI  -> Xpl [color="#a78bfa"];
+  Fuzz -> Xpl [color="#a78bfa"];
+}

data/documentation/diagrams/dot/sdr-radio-flow.dot

@@ -0,0 +1,45 @@
+digraph "PWN_SDR" {
+  graph [
+    label=<<B>PWN::SDR — Software-Defined Radio &amp; RF Hacking</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">GQRX · FlipperZero · RFIDler · SonMicro · FrequencyAllocation</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.45, ranksep=1.2,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=10, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  RF [label="📡  RF Spectrum", fillcolor="#fda4af"];
+
+  subgraph cluster_hw {
+    label="Hardware"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    SDRhw   [label="RTL-SDR / HackRF\n(via GQRX)",   fillcolor="#6ee7b7"];
+    Flipper [label="SDR::FlipperZero",               fillcolor="#6ee7b7"];
+    RFID    [label="SDR::RFIDler\nSonMicroRFID",     fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_ctrl {
+    label="Control"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    GQRX  [label="SDR::GQRX\nremote control · scan\nspectrum snapshot", fillcolor="#fcd34d"];
+    Freq  [label="SDR::FrequencyAllocation\nband lookup",               fillcolor="#fcd34d"];
+    Scan  [label="bin/pwn_gqrx_scanner\nfast · iterative",               fillcolor="#fcd34d"];
+  }
+  subgraph cluster_dec {
+    label="Decode"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Dec [label="SDR::Decoder::*\ndemod · protocol",  fillcolor="#c4b5fd"];
+    Obs [label="extro_observe\nrecord signal intel", fillcolor="#c4b5fd"];
+  }
+
+  RF -> SDRhw   [color="#fb7185"];
+  RF -> Flipper [color="#fb7185"];
+  RF -> RFID    [color="#fb7185"];
+  SDRhw   -> GQRX [color="#f59e0b"];
+  Flipper -> Freq [color="#f59e0b"];
+  RFID    -> Scan [color="#f59e0b"];
+  GQRX -> Dec [color="#a78bfa"];
+  Freq -> Dec [color="#a78bfa"];
+  Scan -> Obs [color="#a78bfa"];
+}

data/documentation/diagrams/dot/sessions-cron-automation.dot

@@ -0,0 +1,44 @@
+digraph "PWN_SessionsCron" {
+  graph [
+    label=<<B>Sessions ↔ Cron ↔ Swarm — Cross-Session Continuity</B>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.5, ranksep=1.3,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=10, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  Now [label="pwn-ai\n(interactive turn)", fillcolor="#7dd3fc"];
+
+  subgraph cluster_p {
+    label="~/.pwn/"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Sess  [label="sessions/<id>.jsonl", shape=cylinder, fillcolor="#fcd34d"];
+    Cron  [label="cron/jobs.yml",       shape=cylinder, fillcolor="#fcd34d"];
+    Swarm [label="swarm/<id>/bus.jsonl",shape=cylinder, fillcolor="#fcd34d"];
+  }
+  {rank=same; Sess; Cron; Swarm}
+
+  subgraph cluster_later {
+    label="Later / Elsewhere"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Reflect [label="learning_reflect\n(session_id)",   fillcolor="#c4b5fd"];
+    Fire    [label="crontab → PWN::Cron.run",           fillcolor="#c4b5fd"];
+    Resume  [label="agent_debate\n(swarm_id: ...)",     fillcolor="#c4b5fd"];
+  }
+  {rank=same; Reflect; Fire; Resume}
+
+  Next [label="Next pwn-ai session\ncontext restored", fillcolor="#7dd3fc"];
+
+  Now -> Sess  [label="append", color="#f59e0b"];
+  Now -> Cron  [label="cron_create", color="#f59e0b"];
+  Now -> Swarm [label="agent_ask", color="#f59e0b"];
+  Sess  -> Reflect [color="#a78bfa"];
+  Cron  -> Fire    [color="#a78bfa"];
+  Swarm -> Resume  [color="#a78bfa"];
+  Reflect -> Next [color="#38bdf8"];
+  Fire    -> Next [color="#38bdf8"];
+  Resume  -> Next [color="#38bdf8"];
+}

data/documentation/diagrams/dot/swarm-multi-agent.dot

@@ -0,0 +1,70 @@
+digraph "PWN_Swarm" {
+  graph [
+    label=<<B>PWN::AI::Agent::Swarm — Native Multi-Agent Orchestration</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">personas · ask · debate · broadcast · shared bus (no daemon)</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=spline, nodesep=0.65, ranksep=1.0,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true, compound=true
+  ];
+  node [fontname="Helvetica", fontsize=11, style="filled,rounded",
+        shape=box, penwidth=1.4, color="#334155", fontcolor="#0f172a"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  /* L0 ─ orchestrator */
+  Orchestrator [label="👤  Orchestrator\n(you, in pwn-ai)", fillcolor="#7dd3fc"];
+
+  /* L1 ─ swarm verbs */
+  subgraph cluster_verbs {
+    label="Swarm Verbs  (toolset: swarm)"; fontcolor="#ddd6fe";
+    style=rounded; color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
+    Spawn     [label="agent_spawn\ndefine persona",          fillcolor="#c4b5fd"];
+    Ask       [label="agent_ask\n1 turn → 1 persona",         fillcolor="#c4b5fd"];
+    Debate    [label="agent_debate\nround-robin critique",    fillcolor="#c4b5fd"];
+    Broadcast [label="agent_broadcast\nfan-out ensemble",     fillcolor="#c4b5fd"];
+  }
+  {rank=same; Spawn; Ask; Debate; Broadcast}
+
+  /* L2 ─ personas */
+  subgraph cluster_personas {
+    label="Personas  (each = full PWN::AI::Agent::Loop)"; fontcolor="#a7f3d0";
+    style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
+    Red   [label="🔴  red_team\nengine: grok\ntoolsets: terminal,pwn",     fillcolor="#6ee7b7"];
+    Blue  [label="🔵  blue_team\nengine: anthropic\ntoolsets: pwn,extro",  fillcolor="#6ee7b7"];
+    Recon [label="🛰  recon\nengine: ollama\ntoolsets: terminal,memory",  fillcolor="#6ee7b7"];
+    Xpl   [label="💥  exploit_dev\nengine: openai\ntoolsets: pwn,skills",  fillcolor="#6ee7b7"];
+  }
+  {rank=same; Red; Blue; Recon; Xpl}
+
+  /* L3 ─ shared state */
+  subgraph cluster_state {
+    label="Shared State  ~/.pwn/"; fontcolor="#fde68a";
+    style=rounded; color="#a16207"; bgcolor="#422006"; penwidth=2;
+    Agents [label="agents.yml\npersona registry",         shape=cylinder, fillcolor="#fcd34d"];
+    Bus    [label="swarm/<id>/bus.jsonl\nappend-only chat", shape=cylinder, fillcolor="#fcd34d"];
+    Pmap   [label="swarm/<id>/personas.json\nname → session_id", shape=cylinder, fillcolor="#fcd34d"];
+    Sess   [label="sessions/*.jsonl\nper-persona transcript",     shape=cylinder, fillcolor="#fcd34d"];
+  }
+  {rank=same; Agents; Bus; Pmap; Sess}
+
+  /* edges */
+  Orchestrator -> Spawn     [color="#38bdf8"];
+  Orchestrator -> Ask       [color="#38bdf8"];
+  Orchestrator -> Debate    [color="#38bdf8", penwidth=2];
+  Orchestrator -> Broadcast [color="#38bdf8"];
+
+  Spawn     -> Red   [style=invis];
+  Ask       -> Red   [color="#34d399"];
+  Debate    -> Blue  [color="#34d399"];
+  Debate    -> Recon [color="#34d399"];
+  Broadcast -> Xpl   [color="#34d399"];
+
+  Red   -> Agents [style=invis];
+  Red   -> Bus  [label="append reply", color="#f59e0b"];
+  Blue  -> Bus  [color="#f59e0b"];
+  Recon -> Pmap [color="#f59e0b"];
+  Xpl   -> Sess [color="#f59e0b"];
+
+  Spawn -> Agents [label="write", color="#f59e0b", constraint=false];
+  Bus   -> Debate [label="tail → context", style=dashed, color="#fbbf24", constraint=false];
+  Bus   -> Orchestrator [label="swarm_bus()", style=dashed, color="#38bdf8", constraint=false];
+}