pwn 0.5.613 → 0.5.617

data/documentation/diagrams/dot/agent-tool-registry.dot

@@ -0,0 +1,59 @@
+digraph "PWN_Agent_Tool_Registry" {
+  graph [
+    label=<<B>PWN::AI::Agent::Registry — Toolsets exposed to the LLM</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">10 toolsets · 45+ callable tools · lib/pwn/ai/agent/tools/*</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.35, 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];
+
+  Registry [label="Registry\nJSON-Schema\nfunction defs", fillcolor="#c4b5fd", fontsize=12, penwidth=2];
+
+  subgraph cluster_ts {
+    label="Toolsets"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22"; penwidth=2;
+    terminal [label="terminal", fillcolor="#6ee7b7"];
+    pwn      [label="pwn",      fillcolor="#6ee7b7"];
+    memory   [label="memory",   fillcolor="#6ee7b7"];
+    skills   [label="skills",   fillcolor="#6ee7b7"];
+    sessions [label="sessions", fillcolor="#6ee7b7"];
+    learning [label="learning", fillcolor="#6ee7b7"];
+    metrics  [label="metrics",  fillcolor="#6ee7b7"];
+    extro    [label="extrospection", fillcolor="#6ee7b7"];
+    cron     [label="cron",     fillcolor="#6ee7b7"];
+    swarm    [label="swarm",    fillcolor="#6ee7b7"];
+  }
+
+  subgraph cluster_tools {
+    label="Tools  (LLM-callable)"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006"; penwidth=2;
+    node [fillcolor="#fcd34d", fontsize=9];
+    t_shell   [label="shell"];
+    t_eval    [label="pwn_eval"];
+    t_mem     [label="memory_remember\nrecall · forget · clear"];
+    t_skill   [label="skill_list · view\ncreate · add_reference · delete"];
+    t_sess    [label="sessions_list · view\ncurrent · delete · stats"];
+    t_learn   [label="learning_note_outcome\nreflect · distill_skill\nconsolidate · outcomes · reset"];
+    t_metric  [label="metrics_summary\nmetrics_reset"];
+    t_extro   [label="extro_snapshot · drift\nobserve · intel · correlate\nobservations · stats · reset"];
+    t_cron    [label="cron_list · create · run\nenable · disable · remove"];
+    t_swarm   [label="agent_list · spawn · ask\ndebate · broadcast\nswarm_bus · swarm_list"];
+  }
+
+  Registry -> terminal; Registry -> pwn; Registry -> memory;
+  Registry -> skills; Registry -> sessions; Registry -> learning;
+  Registry -> metrics; Registry -> extro; Registry -> cron; Registry -> swarm;
+
+  terminal -> t_shell  [color="#f59e0b"];
+  pwn      -> t_eval   [color="#f59e0b"];
+  memory   -> t_mem    [color="#f59e0b"];
+  skills   -> t_skill  [color="#f59e0b"];
+  sessions -> t_sess   [color="#f59e0b"];
+  learning -> t_learn  [color="#f59e0b"];
+  metrics  -> t_metric [color="#f59e0b"];
+  extro    -> t_extro  [color="#f59e0b"];
+  cron     -> t_cron   [color="#f59e0b"];
+  swarm    -> t_swarm  [color="#f59e0b"];
+}

data/documentation/diagrams/dot/ai-integration-tool-calling.dot

@@ -0,0 +1,50 @@
+digraph "PWN_AI_Integration" {
+  graph [
+    label=<<B>PWN::AI — Multi-Provider LLM Integration</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">one Agent Loop · five interchangeable engines</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=LR, splines=spline, nodesep=0.45, 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];
+
+  Loop [label="PWN::AI::Agent::Loop\ntool-calling harness", fillcolor="#7dd3fc", penwidth=2];
+
+  subgraph cluster_c {
+    label="PWN::AI::* Clients"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    OpenAI    [label="OpenAI",           fillcolor="#c4b5fd"];
+    Anthropic [label="Anthropic",        fillcolor="#c4b5fd"];
+    Grok      [label="Grok\nOAuth device flow", fillcolor="#c4b5fd"];
+    Gemini    [label="Gemini",           fillcolor="#c4b5fd"];
+    Ollama    [label="Ollama\n(local)",  fillcolor="#c4b5fd"];
+  }
+  {rank=same; OpenAI; Anthropic; Grok; Gemini; Ollama}
+
+  subgraph cluster_api {
+    label="Provider APIs"; fontcolor="#fecaca"; style="rounded,dashed";
+    color="#b91c1c"; bgcolor="#450a0a";
+    A1 [label="api.openai.com",    fillcolor="#fda4af"];
+    A2 [label="api.anthropic.com", fillcolor="#fda4af"];
+    A3 [label="api.x.ai\nauth.x.ai", fillcolor="#fda4af"];
+    A4 [label="generativelanguage\n.googleapis.com", fillcolor="#fda4af"];
+    A5 [label="localhost:11434",   fillcolor="#fda4af"];
+  }
+  {rank=same; A1; A2; A3; A4; A5}
+
+  Cfg [label="PWN::Config\n~/.pwn/config.yml\nengine · key · oauth", shape=cylinder, fillcolor="#fcd34d"];
+
+  Loop -> OpenAI    [color="#a78bfa"];
+  Loop -> Anthropic [color="#a78bfa"];
+  Loop -> Grok      [color="#a78bfa"];
+  Loop -> Gemini    [color="#a78bfa"];
+  Loop -> Ollama    [color="#a78bfa"];
+  OpenAI    -> A1 [color="#fb7185"];
+  Anthropic -> A2 [color="#fb7185"];
+  Grok      -> A3 [color="#fb7185"];
+  Gemini    -> A4 [color="#fb7185"];
+  Ollama    -> A5 [color="#fb7185"];
+  Cfg -> Loop [label="active engine", style=dashed, color="#fbbf24", constraint=false];
+}

data/documentation/diagrams/dot/aws-cloud-security.dot

@@ -0,0 +1,48 @@
+digraph "PWN_AWS" {
+  graph [
+    label=<<B>PWN::AWS — Cloud Security (90 service wrappers)</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">enumerate → misconfig → escalate → persist</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];
+
+  Creds [label="🔑  AWS Creds\nSTS · env · profile", fillcolor="#7dd3fc"];
+
+  subgraph cluster_enum {
+    label="Enumerate"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    IAM [label="IAM · STS\nOrganizations",       fillcolor="#6ee7b7"];
+    EC2 [label="EC2 · ECS · ECR\nLambda · Lightsail", fillcolor="#6ee7b7"];
+    Net [label="Route53 · ELB\nAPI Gateway · CloudFront", fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_mis {
+    label="Misconfig"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    S3   [label="S3 · Glacier\npublic buckets",   fillcolor="#fcd34d"];
+    KMS  [label="KMS · CloudHSM\nSecrets · SSM",   fillcolor="#fcd34d"];
+    Log  [label="CloudTrail\nCloudWatch · Config", fillcolor="#fcd34d"];
+  }
+  subgraph cluster_esc {
+    label="Escalate / Persist"; fontcolor="#fecaca"; style=rounded;
+    color="#b91c1c"; bgcolor="#450a0a";
+    Priv [label="iam:PassRole\nlambda invoke",   fillcolor="#fda4af"];
+    Back [label="new access key\nEC2 userdata",  fillcolor="#fda4af"];
+  }
+  Rep [label="pwn_aws_describe_resources\nReports", fillcolor="#c4b5fd"];
+
+  Creds -> IAM [color="#38bdf8"];
+  Creds -> EC2 [color="#38bdf8"];
+  Creds -> Net [color="#38bdf8"];
+  IAM -> S3  [color="#f59e0b"];
+  EC2 -> KMS [color="#f59e0b"];
+  Net -> Log [color="#f59e0b"];
+  S3  -> Priv [color="#fb7185"];
+  KMS -> Priv [color="#fb7185"];
+  Log -> Back [color="#fb7185"];
+  Priv -> Rep [color="#a78bfa"];
+  Back -> Rep [color="#a78bfa"];
+}

data/documentation/diagrams/dot/burp-vs-zap-preference.dot

@@ -0,0 +1,26 @@
+digraph "PWN_BurpVsZap" {
+  graph [
+    label=<<B>Web Proxy Selection — BurpSuite ⭐ preferred over ZAP</B>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=spline, nodesep=0.7, 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];
+
+  Need [label="Need web proxy /\nactive scanner?", shape=diamond,
+        style=filled, fillcolor="#7dd3fc", height=1.1];
+  Burp [label="PWN::Plugins::BurpSuite\nheadless · REST · richer scanner\nBApp ecosystem",
+        fillcolor="#6ee7b7", penwidth=2];
+  Zap  [label="PWN::Plugins::Zaproxy\nOSS fallback",
+        fillcolor="#fcd34d"];
+  Both [label="Same downstream:\nTransparentBrowser proxy · Reports · DefectDojo",
+        fillcolor="#c4b5fd"];
+
+  Need -> Burp [label="Burp Pro available", color="#34d399", penwidth=2];
+  Need -> Zap  [label="fallback", color="#f59e0b"];
+  Burp -> Both [color="#a78bfa"];
+  Zap  -> Both [color="#a78bfa"];
+}

data/documentation/diagrams/dot/code-scanning-sast.dot

@@ -0,0 +1,49 @@
+digraph "PWN_SAST" {
+  graph [
+    label=<<B>PWN::SAST — Static Application Security Testing</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">48 rules · multi-language · bin/pwn_sast · Reports::SAST</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];
+
+  Src [label="📁  Source Tree\ngit clone / repo", fillcolor="#7dd3fc"];
+
+  subgraph cluster_engine {
+    label="SAST Engine"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Factory [label="SAST::Factory\nrule loader",       fillcolor="#6ee7b7"];
+    TCE     [label="TestCaseEngine\ngenerate probes",   fillcolor="#6ee7b7"];
+  }
+  subgraph cluster_rules {
+    label="Rule Families (48)"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006";
+    Cmd  [label="cmd_execution_*\njava · py · ruby · go · scala", fillcolor="#fcd34d"];
+    Web  [label="csrf · redirect · redos\ninner/outer_html · location_hash", fillcolor="#fcd34d"];
+    Cryp [label="md5 · ssl · keystore\npadding_oracle · private_key", fillcolor="#fcd34d"];
+    Data [label="sql · eval · deserial_java\nlog4j · php_type_juggling", fillcolor="#fcd34d"];
+    Mem  [label="banned_c_calls\nuse_after_free",                       fillcolor="#fcd34d"];
+  }
+  subgraph cluster_out {
+    label="Output"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Report [label="Reports::SAST\nHTML + JSON",   fillcolor="#c4b5fd"];
+    DD     [label="DefectDojo\nimport / reimport", fillcolor="#c4b5fd"];
+  }
+
+  Src -> Factory [color="#38bdf8"];
+  Src -> TCE     [color="#38bdf8"];
+  Factory -> Cmd  [color="#f59e0b"];
+  Factory -> Web  [color="#f59e0b"];
+  Factory -> Cryp [color="#f59e0b"];
+  TCE     -> Data [color="#f59e0b"];
+  TCE     -> Mem  [color="#f59e0b"];
+  Cmd  -> Report [color="#a78bfa"];
+  Web  -> Report [color="#a78bfa"];
+  Cryp -> Report [color="#a78bfa"];
+  Data -> DD     [color="#a78bfa"];
+  Mem  -> DD     [color="#a78bfa"];
+}

data/documentation/diagrams/dot/cron-scheduling.dot

@@ -0,0 +1,40 @@
+digraph "PWN_Cron" {
+  graph [
+    label=<<B>PWN::Cron — Scheduled Autonomous Jobs</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">prompt · ruby · script → jobs.yml → crontab → pwn-ai</FONT>>,
+    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=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];
+
+  Create [label="cron_create\nname · schedule\nprompt | ruby | script", fillcolor="#7dd3fc"];
+  Jobs   [label="~/.pwn/cron/jobs.yml", shape=cylinder, fillcolor="#fcd34d"];
+  Crontab[label="system crontab\n(install_crontab: true)", fillcolor="#fda4af"];
+  Runner [label="PWN::Cron.run(id)", fillcolor="#c4b5fd"];
+
+  subgraph cluster_kinds {
+    label="Job Kinds"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22"; penwidth=2;
+    Prompt [label=":prompt\n→ pwn-ai one-shot", fillcolor="#6ee7b7"];
+    Ruby   [label=":ruby\n→ TOPLEVEL_BINDING.eval", fillcolor="#6ee7b7"];
+    Script [label=":script\n→ exec external file", fillcolor="#6ee7b7"];
+  }
+  {rank=same; Prompt; Ruby; Script}
+
+  Log [label="~/.pwn/cron/log/<id>.log\nlast_run · last_status", shape=cylinder, fillcolor="#fcd34d"];
+
+  Create  -> Jobs    [label="write", color="#38bdf8"];
+  Create  -> Crontab [label="append", color="#fb7185"];
+  Crontab -> Runner  [label="fire on schedule", color="#fb7185", penwidth=2];
+  Jobs    -> Runner  [label="load job", color="#f59e0b"];
+  Runner  -> Prompt  [color="#34d399"];
+  Runner  -> Ruby    [color="#34d399"];
+  Runner  -> Script  [color="#34d399"];
+  Prompt  -> Log     [color="#f59e0b"];
+  Ruby    -> Log     [color="#f59e0b"];
+  Script  -> Log     [color="#f59e0b"];
+  Log     -> Jobs    [label="update status", style=dashed, color="#fbbf24", constraint=false];
+}

data/documentation/diagrams/dot/driver-framework.dot

@@ -0,0 +1,39 @@
+digraph "PWN_Driver" {
+  graph [
+    label=<<B>Driver Anatomy — bin/pwn_*</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">52 shipped drivers · thin CLI over PWN::Plugins</FONT>>,
+    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];
+
+  Sh [label="$ pwn_burp_suite_pro_active_scan \\ \n    -t https://target -o out/", fillcolor="#7dd3fc"];
+
+  subgraph cluster_d {
+    label="Driver Body"; fontcolor="#a7f3d0"; style=rounded;
+    color="#047857"; bgcolor="#022c22";
+    Opt  [label="OptionParser\nARGV → opts{}", fillcolor="#6ee7b7"];
+    Req  [label="require 'pwn'",               fillcolor="#6ee7b7"];
+    Call [label="PWN::Plugins::X.method(opts)", fillcolor="#6ee7b7"];
+  }
+  {rank=same; Opt; Req; Call}
+
+  subgraph cluster_o {
+    label="Output"; fontcolor="#ddd6fe"; style=rounded;
+    color="#6d28d9"; bgcolor="#2e1065";
+    Std [label="STDOUT / STDERR", fillcolor="#c4b5fd"];
+    Rep [label="PWN::Reports",    fillcolor="#c4b5fd"];
+    Ex  [label="exit code",       fillcolor="#c4b5fd"];
+  }
+
+  Sh -> Opt [color="#38bdf8"];
+  Sh -> Req [color="#38bdf8"];
+  Opt -> Call [color="#34d399"];
+  Req -> Call [color="#34d399"];
+  Call -> Std [color="#a78bfa"];
+  Call -> Rep [color="#a78bfa"];
+  Call -> Ex  [color="#a78bfa"];
+}

data/documentation/diagrams/dot/extrospection-world-awareness.dot

@@ -0,0 +1,55 @@
+digraph "PWN_Extrospection" {
+  graph [
+    label=<<B>PWN::AI::Agent::Extrospection — World Awareness</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">snapshot · drift · observe · intel · correlate</FONT>>,
+    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=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];
+
+  /* col 0 ─ world */
+  subgraph cluster_world {
+    label="Outside World"; fontcolor="#fecaca"; style="rounded,dashed";
+    color="#b91c1c"; bgcolor="#450a0a";
+    Host  [label="host\nuname · distro · arch",     fillcolor="#fda4af"];
+    Net   [label="net\ninterfaces · listening ports", fillcolor="#fda4af"];
+    Tool  [label="toolchain\nnmap · burp · msf · git", fillcolor="#fda4af"];
+    Repo  [label="repo\nHEAD · dirty · branch",      fillcolor="#fda4af"];
+    Feeds [label="intel feeds\nNVD · CIRCL · Exploit-DB", fillcolor="#fda4af"];
+  }
+  {rank=same; Host; Net; Tool; Repo; Feeds}
+
+  /* col 1 ─ engine */
+  subgraph cluster_eng {
+    label="Extrospection Engine"; fontcolor="#fde68a"; style=rounded;
+    color="#a16207"; bgcolor="#422006"; penwidth=2;
+    Snap  [label="extro_snapshot\nfingerprint host",   fillcolor="#fcd34d"];
+    Drift [label="extro_drift\ndelta vs baseline",     fillcolor="#fcd34d"];
+    Obs   [label="extro_observe\nrecord recon fact",   fillcolor="#fcd34d"];
+    Intel [label="extro_intel\nCVE / exploit lookup",  fillcolor="#fcd34d"];
+    Corr  [label="extro_correlate\njoin with Learning", fillcolor="#fcd34d", penwidth=2];
+  }
+  {rank=same; Snap; Drift; Obs; Intel; Corr}
+
+  /* col 2 ─ store + prompt */
+  Store  [label="~/.pwn/\nextrospection.json", shape=cylinder, fillcolor="#fcd34d"];
+  Prompt [label="EXTROSPECTION\nblock in system prompt", fillcolor="#c4b5fd"];
+  {rank=same; Store; Prompt}
+
+  Host  -> Snap  [color="#fb7185"];
+  Net   -> Snap  [color="#fb7185"];
+  Tool  -> Drift [color="#fb7185"];
+  Repo  -> Drift [color="#fb7185"];
+  Feeds -> Intel [color="#fb7185"];
+
+  Snap  -> Store [color="#f59e0b"];
+  Drift -> Store [color="#f59e0b"];
+  Obs   -> Store [color="#f59e0b"];
+  Intel -> Store [label="record:true", color="#f59e0b"];
+  Corr  -> Prompt[label="findings", color="#a78bfa", penwidth=2];
+  Store -> Prompt[label="inject", style=dashed, color="#fbbf24"];
+  Store -> Corr  [style=dashed, color="#fbbf24", constraint=false];
+}

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

@@ -0,0 +1,47 @@
+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];
+
+  Seed [label="Seed corpus /\nprotocol grammar", fillcolor="#7dd3fc"];
+
+  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/history-to-drivers.dot

@@ -0,0 +1,34 @@
+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];
+
+  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"];
+
+  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

@@ -0,0 +1,60 @@
+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];
+
+  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}
+
+  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

@@ -0,0 +1,54 @@
+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];
+
+  CIDR [label="CIDR / ASN\nscope", fillcolor="#7dd3fc"];
+
+  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"];
+}