pwn 0.5.615 → 0.5.618

data/documentation/diagrams/dot/fuzzing-workflow.dot

@@ -1,27 +1,47 @@
-digraph "PWN Fuzzing Workflows" {
-  rankdir=LR;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+digraph "PWN_Fuzz" {
+  graph [
+    label=<<B>Fuzzing with PWN</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Plugins::Fuzz · Sock · Packet · Reports::Fuzz</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];
 
-  Input [label="Input Corpus\n(Seeds, Mutators)", shape=box];
-  FuzzProto [label="Protocol Fuzz\n(pwn_fuzz_net_app_proto)"];
-  FuzzFile [label="File / Format Fuzz"];
-  FuzzNet [label="Network Service Fuzz"];
-  FuzzWeb [label="Web App Fuzz\n(XSS vectors, etc.)"];
-  PWNfuzz [label="PWN::Plugins::Fuzz", shape=ellipse];
-  Monitor [label="Monitor Crashes\n(PS, logging, core dumps)"];
-  Corpus [label="Interesting Inputs\n(saved for replay)", shape=cylinder];
-  Crash [label="Crash Analysis\n(identify root cause)", shape=ellipse];
+  Seed [label="Seed corpus /\nprotocol grammar", fillcolor="#7dd3fc"];
 
-  Input -> PWNfuzz;
-  PWNfuzz -> FuzzProto;
-  PWNfuzz -> FuzzFile;
-  PWNfuzz -> FuzzNet;
-  PWNfuzz -> FuzzWeb;
-  FuzzProto -> Monitor;
-  FuzzFile -> Monitor;
-  FuzzNet -> Monitor;
-  FuzzWeb -> Monitor;
-  Monitor -> Corpus;
-  Monitor -> Crash;
-  Crash -> Input [label="refine mutators"];
+  subgraph cluster_gen {
+    label="Generate"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Fuzz [label="Plugins::Fuzz\nmutate · generate", fillcolor="#6ee7b7"];
+    Char [label="Plugins::Char\nencodings",         fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_deliver {
+    label="Deliver"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Sock   [label="Plugins::Sock\nTCP/UDP",           fillcolor="#fcd34d"];
+    Packet [label="Plugins::Packet\nraw L2/L3",       fillcolor="#fcd34d"];
+    NetApp [label="pwn_fuzz_net_app_proto\nCLI driver", fillcolor="#fcd34d"];
+  }
+  subgraph cluster_mon {
+    label="Monitor"; fontcolor="#fecaca"; style=rounded;
+    color="#b91c1c"; bgcolor="#450a0a";
+    PS  [label="Plugins::PS\nprocess health", fillcolor="#fda4af"];
+    Log [label="Plugins::Log\ncrash detect",   fillcolor="#fda4af"];
+  }
+  Report [label="Reports::Fuzz\ncrash triage", fillcolor="#7dd3fc"];
+
+  Seed -> Fuzz [color="#38bdf8"];
+  Seed -> Char [color="#38bdf8"];
+  Fuzz -> Sock   [color="#f59e0b"];
+  Fuzz -> Packet [color="#f59e0b"];
+  Char -> NetApp [color="#f59e0b"];
+  Sock   -> PS  [color="#fb7185"];
+  Packet -> Log [color="#fb7185"];
+  NetApp -> Log [color="#fb7185"];
+  PS  -> Report [color="#38bdf8"];
+  Log -> Report [color="#38bdf8"];
+  Log -> Fuzz [label="minimise + reseed", style=dashed, color="#fbbf24", constraint=false];
 }

data/documentation/diagrams/dot/hardware-hacking.dot

@@ -0,0 +1,48 @@
+digraph "PWN_Hardware" {
+  graph [
+    label=<<B>Hardware &amp; Physical-Layer Hacking</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Serial · BusPirate · MSR206 · Android · BareSIP · SDR</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.4, 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_dev {
+    label="Physical Devices"; fontcolor="#fecaca"; style="rounded,dashed";
+    color="#b91c1c"; bgcolor="#450a0a";
+    Uart  [label="UART / JTAG\nembedded target", fillcolor="#fda4af"];
+    Mag   [label="Magstripe card",               fillcolor="#fda4af"];
+    Phone [label="Android device",               fillcolor="#fda4af"];
+    VoIP  [label="SIP / PSTN",                   fillcolor="#fda4af"];
+    RF    [label="RF spectrum",                  fillcolor="#fda4af"];
+  }
+  subgraph cluster_pl {
+    label="PWN::Plugins / SDR"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Serial [label="Serial · BusPirate", fillcolor="#6ee7b7"];
+    MSR    [label="MSR206",             fillcolor="#6ee7b7"];
+    Adb    [label="Android (adb)",      fillcolor="#6ee7b7"];
+    Sip    [label="BareSIP · Voice",    fillcolor="#6ee7b7"];
+    Sdr    [label="SDR::GQRX · Flipper",fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_out {
+    label="Analysis"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    XXD [label="XXD · Assembly",     fillcolor="#c4b5fd"];
+    Rep [label="Reports · Skills",   fillcolor="#c4b5fd"];
+  }
+
+  Uart  -> Serial [color="#fb7185"];
+  Mag   -> MSR    [color="#fb7185"];
+  Phone -> Adb    [color="#fb7185"];
+  VoIP  -> Sip    [color="#fb7185"];
+  RF    -> Sdr    [color="#fb7185"];
+  Serial -> XXD [color="#a78bfa"];
+  MSR    -> XXD [color="#a78bfa"];
+  Adb    -> Rep [color="#a78bfa"];
+  Sip    -> Rep [color="#a78bfa"];
+  Sdr    -> Rep [color="#a78bfa"];
+}

data/documentation/diagrams/dot/history-to-drivers.dot

@@ -1,20 +1,34 @@
-digraph "History Command to Driver Generation" {
-  rankdir=TB;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+digraph "PWN_HistToDriver" {
+  graph [
+    label=<<B>From REPL History → Reusable Driver / Skill</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">explore → history → bin/pwn_* driver → distill_skill</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.5, 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];
 
-  User [label="User in REPL"];
-  Pry [label="PWN REPL\n(history, edit, save)"];
-  HistoryFile [label="~/.pry_history\n(raw commands)", shape=cylinder, fillcolor=lightyellow];
-  Script [label="Prototype Script\n(.rb or bin/)", shape=box];
-  Driver [label="PWN Driver\n(/opt/pwn/bin/ example\nor PWN::Driver::Parser)", shape=box];
-  Skill [label="Distilled Skill\n(~/.pwn/skills/)", shape=cylinder, fillcolor=lightyellow];
-  Agent [label="pwn-ai Agent\n(future automation)"];
+  Explore [label="🐚  Explore in REPL\ncall PWN::Plugins::*", fillcolor="#7dd3fc"];
+  Hist    [label="~/.pwn_history\nPry `history` cmd", shape=cylinder, fillcolor="#fcd34d"];
+  Extract [label="copy working lines", fillcolor="#6ee7b7"];
 
-  User -> Pry [label="run exploration cmds"];
-  Pry -> HistoryFile [label="appends each line"];
-  Pry -> Script [label="history | grep > my_proto.rb\nor edit -n"];
-  Script -> Driver [label="wrap in PWN::Driver\nadd opts, orchestration"];
-  Script -> Skill [label="manually or via\ndistill_skill after success"];
-  Driver -> Agent [label="invoked by agent\nor cron"];
-  Skill -> Agent [label="loaded in prompt context"];
+  subgraph cluster_out {
+    label="Reusable Artefacts"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Driver [label="bin/pwn_<name>\nOptionParser + PWN calls", fillcolor="#c4b5fd"];
+    Skill  [label="~/.pwn/skills/<name>.md\nlearning_distill_skill",  fillcolor="#c4b5fd"];
+    Cron   [label="cron_create\nprompt: | ruby:",              fillcolor="#c4b5fd"];
+  }
+  CI [label="⚙️  CI / CD\nheadless run", fillcolor="#7dd3fc"];
+
+  Explore -> Hist    [label="auto-log", color="#38bdf8"];
+  Hist    -> Extract [color="#f59e0b"];
+  Extract -> Driver  [color="#a78bfa"];
+  Extract -> Skill   [color="#a78bfa"];
+  Extract -> Cron    [color="#a78bfa"];
+  Driver  -> CI      [color="#38bdf8", penwidth=2];
+  Skill   -> CI      [label="pwn --ai", color="#38bdf8"];
+  Cron    -> CI      [color="#38bdf8"];
 }

data/documentation/diagrams/dot/memory-skills-detailed.dot

@@ -1,28 +1,60 @@
-digraph "PWN Memory & Skills Detailed Data Flow" {
-  rankdir=TB;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+digraph "PWN_MemorySkills" {
+  graph [
+    label=<<B>Persistent Knowledge — Memory · Skills · Sessions</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">everything under ~/.pwn/ that shapes future prompts</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=spline, nodesep=0.55, ranksep=0.95,
+    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];
 
-  Input [label="Successful Task\nOutcome in Agent"];
-  Learn [label="PWN::AI::Agent::Learning\nnote_outcome"];
-  Metrics [label="Metrics (success/duration)"];
-  Introspect [label="learning_reflect\n+ LLM introspection"];
-  Distill [label="learning_distill_skill"];
-  SkillCreate [label="skill_create / edit"];
-  SkillStore [label="~/.pwn/skills/*.md\n(YAML frontmatter\n+ markdown + references)", shape=cylinder, fillcolor=lightyellow];
-  MemStore [label="~/.pwn/memory.json", shape=cylinder, fillcolor=lightyellow];
-  SkillList [label="skill_list / skill_view"];
-  AgentPrompt [label="Agent System Prompt\n(injects skills + memory)"];
-  Recall [label="memory_recall"];
+  subgraph cluster_write {
+    label="Write-Side Tools"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Rem    [label="memory_remember\nkey · value · category",   fillcolor="#6ee7b7"];
+    Skc    [label="skill_create\nskill_add_reference",           fillcolor="#6ee7b7"];
+    Note   [label="learning_note_outcome\nlearning_reflect",     fillcolor="#6ee7b7"];
+    Dist   [label="learning_distill_skill\n(session → skill)",   fillcolor="#6ee7b7"];
+  }
+  {rank=same; Rem; Skc; Note; Dist}
 
-  Input -> Learn;
-  Learn -> Metrics;
-  Learn -> Introspect;
-  Introspect -> Distill;
-  Distill -> SkillCreate;
-  SkillCreate -> SkillStore;
-  SkillStore -> SkillList;
-  SkillList -> AgentPrompt;
-  Input -> MemStore [label="remember key facts"];
-  Recall -> AgentPrompt;
-  MemStore -> Recall;
+  subgraph cluster_files {
+    label="~/.pwn/"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Fmem [label="memory.json\nfact · pref · lesson · env", shape=cylinder, fillcolor="#fcd34d"];
+    Fskl [label="skills/*.md\nYAML front-matter refs",       shape=cylinder, fillcolor="#fcd34d"];
+    Flrn [label="learning.jsonl\noutcome log",               shape=cylinder, fillcolor="#fcd34d"];
+    Fses [label="sessions/*.jsonl\ntranscripts",              shape=cylinder, fillcolor="#fcd34d"];
+  }
+  {rank=same; Fmem; Fskl; Flrn; Fses}
+
+  subgraph cluster_read {
+    label="Read-Side / Injection"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Rec  [label="memory_recall",       fillcolor="#c4b5fd"];
+    Skv  [label="skill_list · view",   fillcolor="#c4b5fd"];
+    Out  [label="learning_outcomes\nlearning_stats", fillcolor="#c4b5fd"];
+    Sesv [label="sessions_view\nsessions_current",   fillcolor="#c4b5fd"];
+  }
+  {rank=same; Rec; Skv; Out; Sesv}
+
+  Prompt [label="PromptBuilder\nMEMORY + SKILLS + LEARNING blocks", fillcolor="#7dd3fc", penwidth=2];
+
+  Rem  -> Fmem [color="#f59e0b"];
+  Skc  -> Fskl [color="#f59e0b"];
+  Note -> Flrn [color="#f59e0b"];
+  Dist -> Fskl [color="#f59e0b"];
+  Dist -> Fses [dir=back, style=dashed, color="#fbbf24", label="mine"];
+
+  Fmem -> Rec  [color="#a78bfa"];
+  Fskl -> Skv  [color="#a78bfa"];
+  Flrn -> Out  [color="#a78bfa"];
+  Fses -> Sesv [color="#a78bfa"];
+
+  Rec  -> Prompt [color="#38bdf8"];
+  Skv  -> Prompt [color="#38bdf8"];
+  Out  -> Prompt [color="#38bdf8"];
+  Sesv -> Prompt [color="#38bdf8"];
 }

data/documentation/diagrams/dot/network-infra-testing.dot

@@ -1,22 +1,54 @@
-digraph "Network & Infrastructure Testing with PWN" {
-  rankdir=TB;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+digraph "PWN_Network" {
+  graph [
+    label=<<B>Network &amp; Infrastructure Testing</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">discovery → service enum → auth attacks → cloud / CI</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];
 
-  Targets [label="Targets\n(IPs, Domains, ASNs)", shape=box];
-  Discovery [label="Discovery\n(NmapIt, pwn_nmap_discover,\nShodan, IPInfo, crt.sh)"];
-  Enum [label="Service Enum\n(portscan, version, scripts)"];
-  Auth [label="Auth Testing\n(basic_auth, DAOs,\ncredential spray)"];
-  VulnScan [label="Vuln Scanning\n(NessusCloud, OpenVAS,\nNexpose, Zaproxy)"];
-  Packet [label="Packet Crafting\n(PWN::Plugins::Packet,\nSock, Tor)"];
-  Infra [label="Infra Specific\n(AWS, Jenkins, Jira,\nVsphere, RabbitMQ)"];
-  ExploitNet [label="Network Exploits"];
+  CIDR [label="CIDR / ASN\nscope", fillcolor="#7dd3fc"];
 
-  Targets -> Discovery;
-  Discovery -> Enum;
-  Enum -> Auth;
-  Auth -> VulnScan;
-  VulnScan -> Packet;
-  Packet -> ExploitNet;
-  VulnScan -> Infra;
-  Infra -> ExploitNet;
+  subgraph cluster_disc {
+    label="Discover"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Nmap   [label="NmapIt\npwn_nmap_discover_tcp_udp", fillcolor="#6ee7b7"];
+    Packet [label="Plugins::Packet\nraw craft / sniff", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_svc {
+    label="Service Enum"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Sock [label="Plugins::Sock\nbanner grab", fillcolor="#fcd34d"];
+    DAO  [label="DAO::LDAP · Mongo\nPostgres · SQLite3", fillcolor="#fcd34d"];
+    MQ   [label="RabbitMQ\nSlack · IRC · Mail", fillcolor="#fcd34d"];
+  }
+  subgraph cluster_auth {
+    label="Auth / Exploit"; fontcolor="#fecaca"; style=rounded;
+    color="#b91c1c"; bgcolor="#450a0a";
+    MSF  [label="Metasploit\nmsf_postgres_login", fillcolor="#fda4af"];
+    Auth [label="BasicAuth · OAuth2\nAuthenticationHelper", fillcolor="#fda4af"];
+  }
+  subgraph cluster_cloud {
+    label="Cloud / CI"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    AWS  [label="PWN::AWS::*\n90 services",  fillcolor="#c4b5fd"];
+    Jenk [label="Plugins::Jenkins\nvSphere · Vault", fillcolor="#c4b5fd"];
+  }
+  Report [label="Reports · DefectDojo", fillcolor="#7dd3fc"];
+
+  CIDR   -> Nmap   [color="#38bdf8"];
+  CIDR   -> Packet [color="#38bdf8"];
+  Nmap   -> Sock   [color="#f59e0b"];
+  Nmap   -> DAO    [color="#f59e0b"];
+  Packet -> MQ     [color="#f59e0b"];
+  Sock   -> MSF    [color="#fb7185"];
+  DAO    -> Auth   [color="#fb7185"];
+  MQ     -> Auth   [color="#fb7185"];
+  MSF    -> AWS    [color="#a78bfa"];
+  Auth   -> Jenk   [color="#a78bfa"];
+  AWS    -> Report [color="#38bdf8"];
+  Jenk   -> Report [color="#38bdf8"];
 }

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

@@ -1,49 +1,115 @@
-digraph "PWN Overall Architecture" {
-  rankdir=TB;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
-  edge [fontname="Arial", fontsize=8];
-
-  User [label="End User\n(Researcher, pwn-ai)", shape=box];
-  REPL [label="PWN REPL\n(pry + pwn)", shape=ellipse, fillcolor=lightgreen, style=filled];
-  AI [label="PWN::AI\n(Agent + Providers)", shape=ellipse, fillcolor=lightblue, style=filled];
-
-  subgraph cluster_core {
-    label="Core PWN";
-    color=darkblue;
-    Plugins [label="PWN::Plugins\n(67+ modules:\nBurp, NmapIt,\nMetasploit, Fuzz,\nTransparentBrowser...)" , shape=box];
-    SAST [label="PWN::SAST", shape=box];
-    Reports [label="PWN::Reports", shape=box];
-    Driver [label="PWN::Driver", shape=box];
-    Memory [label="PWN::Memory", shape=box];
+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}
 
-  subgraph cluster_persistent {
-    label="Persistent Layer";
-    color=darkgreen;
-    Skills [label="PWN::Skills\n(~/.pwn/skills)", shape=cylinder, fillcolor=lightyellow];
-    Sess [label="PWN::Sessions", shape=cylinder, fillcolor=lightyellow];
-    Cron [label="PWN::Cron", shape=cylinder, fillcolor=lightyellow];
-    Learn [label="Learning\n(Metrics + JSONL)", shape=cylinder, fillcolor=lightyellow];
+  /* ───────── 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"];
 
-  BinDrivers [label="/opt/pwn/bin/\n(Drivers & CLIs)", shape=box];
-
-  User -> REPL [label="pwn / pwn-ai"];
-  REPL -> AI [label="launch pwn-ai"];
-  REPL -> Plugins [label="direct invocation"];
-  REPL -> SAST;
-  REPL -> Reports;
-  REPL -> Driver;
-  AI -> Plugins [label="tool calls\npwn_eval"];
-  AI -> Memory [label="remember/recall"];
-  REPL -> Memory;
-  REPL -> BinDrivers;
-  Driver -> BinDrivers;
-  Plugins -> Learn;
-  AI -> Learn [label="distill skills"];
-  Learn -> Skills [label="promote successful"];
-  Skills -> AI [label="context injection"];
-  Skills -> REPL;
-  Cron -> REPL [label="schedule drivers/agents"];
-  Sess -> REPL [label="replay / audit"];
+  /* ── 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

@@ -1,29 +1,60 @@
-digraph "PWN Penetration Testing Workflow" {
-  rankdir=TB;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
-  edge [fontname="Arial", fontsize=8];
+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];
 
-  Target [label="Target System\n(Host, Network, App)", shape=box];
+  Scope [label="🎯  Scope\ntargets · rules", fillcolor="#7dd3fc"];
 
-  Recon [label="Recon\n(NmapIt, Shodan,\nIPInfo, crt.sh)", shape=ellipse, fillcolor=lightblue];
-  Scanning [label="Vuln Scanning\n(OpenVAS, Nessus,\nNexpose, ZAP/Burp)", shape=ellipse, fillcolor=lightblue];
-  Web [label="Web App Testing\n(TransparentBrowser,\nBurpSuite, Zaproxy,\nURI Buster)", shape=ellipse, fillcolor=lightblue];
-  Fuzz [label="Fuzzing\n(PWN::Plugins::Fuzz,\npwn_fuzz_net_app_proto)", shape=ellipse, fillcolor=lightblue];
-  Exploit [label="Exploitation\n(Metasploit, custom\nBeEF, Serial, etc.)", shape=ellipse, fillcolor=lightcoral];
-  Post [label="Post-Exploitation\n(PS, FileFu, SSH,\ncredential extraction)", shape=ellipse, fillcolor=lightcoral];
-  Report [label="Reporting\n(PWN::Reports)", shape=ellipse, fillcolor=lightgreen];
+  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"];
 
-  MemorySkills [label="Memory + Skills\n(persistent context)", shape=cylinder];
-
-  Target -> Recon;
-  Recon -> Scanning;
-  Scanning -> Web;
-  Web -> Fuzz;
-  Fuzz -> Exploit;
-  Exploit -> Post;
-  Post -> Report;
-
-  Report -> MemorySkills [label="note outcomes"];
-  MemorySkills -> Recon [label="recall previous\nfindings"];
-  MemorySkills -> Exploit [label="reuse exploits"];
+  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/persistence-filesystem.dot

@@ -0,0 +1,29 @@
+digraph "PWN_Persistence" {
+  graph [
+    label=<<B>~/.pwn/ — Everything PWN Persists Across Sessions</B>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.3, ranksep=1.4,
+    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 [color="#94a3b8", penwidth=1.1, arrowsize=0.7];
+
+  Root [label="~/.pwn/", shape=folder, fillcolor="#7dd3fc", fontsize=13];
+
+  node [shape=cylinder, fillcolor="#fcd34d"];
+  cfg  [label="config.yml\nengines · keys · agent opts"];
+  mem  [label="memory.json\nfacts · prefs · lessons · env"];
+  skl  [label="skills/*.md\nreusable procedures + refs"];
+  lrn  [label="learning.jsonl\ntask outcomes"];
+  met  [label="metrics.json\nper-tool telemetry"];
+  ext  [label="extrospection.json\nhost snapshot + observations"];
+  ses  [label="sessions/*.jsonl\ntranscripts"];
+  crn  [label="cron/jobs.yml\nscheduled jobs + logs"];
+  agt  [label="agents.yml\npersona registry"];
+  swm  [label="swarm/<id>/bus.jsonl\nmulti-agent chat"];
+  hist [label="~/.pwn_history\nREPL history"];
+
+  Root->cfg; Root->mem; Root->skl; Root->lrn; Root->met; Root->ext;
+  Root->ses; Root->crn; Root->agt; Root->swm; Root->hist;
+}