pwn 0.5.615 → 0.5.618

data/documentation/diagrams/cron-scheduling.svg

@@ -0,0 +1,148 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: PWN_Cron Pages: 1 -->
+<svg width="1248pt" height="391pt"
+ viewBox="0.00 0.00 1248.00 391.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(43.2 348.08)">
+<title>PWN_Cron</title>
+<polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-348.08 1204.45,-348.08 1204.45,43.2 -43.2,43.2"/>
+<text xml:space="preserve" text-anchor="start" x="372.5" y="-282.88" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">PWN::Cron — Scheduled Autonomous Jobs</text>
+<text xml:space="preserve" text-anchor="start" x="452" y="-271.43" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">prompt · ruby · script → jobs.yml → crontab → pwn&#45;ai</text>
+<g id="clust1" class="cluster">
+<title>cluster_kinds</title>
+<path fill="#022c22" stroke="#047857" stroke-width="2" d="M775.75,-30.88C775.75,-30.88 930,-30.88 930,-30.88 936,-30.88 942,-36.88 942,-42.88 942,-42.88 942,-245.88 942,-245.88 942,-251.88 936,-257.88 930,-257.88 930,-257.88 775.75,-257.88 775.75,-257.88 769.75,-257.88 763.75,-251.88 763.75,-245.88 763.75,-245.88 763.75,-42.88 763.75,-42.88 763.75,-36.88 769.75,-30.88 775.75,-30.88"/>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-234.88" font-family="sans-Serif" font-size="20.00" fill="#a7f3d0">Job Kinds</text>
+</g>
+<!-- Create -->
+<g id="node1" class="node">
+<title>Create</title>
+<path fill="#7dd3fc" stroke="#334155" stroke-width="1.4" d="M102.25,-152.13C102.25,-152.13 12,-152.13 12,-152.13 6,-152.13 0,-146.13 0,-140.13 0,-140.13 0,-115.63 0,-115.63 0,-109.63 6,-103.63 12,-103.63 12,-103.63 102.25,-103.63 102.25,-103.63 108.25,-103.63 114.25,-109.63 114.25,-115.63 114.25,-115.63 114.25,-140.13 114.25,-140.13 114.25,-146.13 108.25,-152.13 102.25,-152.13"/>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-137.68" font-family="sans-Serif" font-size="11.00" fill="#0f172a">cron_create</text>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-124.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">name · schedule</text>
+<text xml:space="preserve" text-anchor="middle" x="57.12" y="-110.68" font-family="sans-Serif" font-size="11.00" fill="#0f172a">prompt | ruby | script</text>
+</g>
+<!-- Jobs -->
+<g id="node2" class="node">
+<title>Jobs</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.4" d="M355.88,-184.6C355.88,-186.41 330.1,-187.88 298.38,-187.88 266.65,-187.88 240.88,-186.41 240.88,-184.6 240.88,-184.6 240.88,-155.15 240.88,-155.15 240.88,-153.34 266.65,-151.88 298.38,-151.88 330.1,-151.88 355.88,-153.34 355.88,-155.15 355.88,-155.15 355.88,-184.6 355.88,-184.6"/>
+<path fill="none" stroke="#334155" stroke-width="1.4" d="M355.88,-184.6C355.88,-182.8 330.1,-181.33 298.38,-181.33 266.65,-181.33 240.88,-182.8 240.88,-184.6"/>
+<text xml:space="preserve" text-anchor="middle" x="298.38" y="-166.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">~/.pwn/cron/jobs.yml</text>
+</g>
+<!-- Create&#45;&gt;Jobs -->
+<g id="edge1" class="edge">
+<title>Create&#45;&gt;Jobs</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" d="M114.82,-137.83C149.58,-143.93 194.24,-151.77 230.69,-158.17"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="229.95,-160.88 238.32,-159.51 230.92,-155.37 229.95,-160.88"/>
+<text xml:space="preserve" text-anchor="middle" x="177" y="-153.34" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">write</text>
+</g>
+<!-- Crontab -->
+<g id="node3" class="node">
+<title>Crontab</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.4" d="M345,-109.88C345,-109.88 251.75,-109.88 251.75,-109.88 245.75,-109.88 239.75,-103.88 239.75,-97.88 239.75,-97.88 239.75,-85.88 239.75,-85.88 239.75,-79.88 245.75,-73.88 251.75,-73.88 251.75,-73.88 345,-73.88 345,-73.88 351,-73.88 357,-79.88 357,-85.88 357,-85.88 357,-97.88 357,-97.88 357,-103.88 351,-109.88 345,-109.88"/>
+<text xml:space="preserve" text-anchor="middle" x="298.38" y="-94.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">system crontab</text>
+<text xml:space="preserve" text-anchor="middle" x="298.38" y="-81.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">(install_crontab: true)</text>
+</g>
+<!-- Create&#45;&gt;Crontab -->
+<g id="edge2" class="edge">
+<title>Create&#45;&gt;Crontab</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M114.83,-112.81C129.83,-109.26 146.08,-105.81 161.25,-103.38 183.28,-99.85 207.51,-97.36 229.34,-95.62"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="229.46,-98.42 237.22,-95.03 229.03,-92.84 229.46,-98.42"/>
+<text xml:space="preserve" text-anchor="middle" x="177" y="-105.33" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">append</text>
+</g>
+<!-- Runner -->
+<g id="node4" class="node">
+<title>Runner</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.4" d="M611,-146.88C611,-146.88 528.25,-146.88 528.25,-146.88 522.25,-146.88 516.25,-140.88 516.25,-134.88 516.25,-134.88 516.25,-122.88 516.25,-122.88 516.25,-116.88 522.25,-110.88 528.25,-110.88 528.25,-110.88 611,-110.88 611,-110.88 617,-110.88 623,-116.88 623,-122.88 623,-122.88 623,-134.88 623,-134.88 623,-140.88 617,-146.88 611,-146.88"/>
+<text xml:space="preserve" text-anchor="middle" x="569.62" y="-125.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">PWN::Cron.run(id)</text>
+</g>
+<!-- Jobs&#45;&gt;Runner -->
+<g id="edge4" class="edge">
+<title>Jobs&#45;&gt;Runner</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M356.48,-161.18C400.34,-154.5 460.86,-145.29 506.04,-138.41"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="506.29,-141.2 513.78,-137.23 505.45,-135.67 506.29,-141.2"/>
+<text xml:space="preserve" text-anchor="middle" x="436.62" y="-155" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">load job</text>
+</g>
+<!-- Crontab&#45;&gt;Runner -->
+<g id="edge3" class="edge">
+<title>Crontab&#45;&gt;Runner</title>
+<path fill="none" stroke="#fb7185" stroke-width="2" d="M357.47,-99.86C400.88,-105.83 460.2,-113.98 504.92,-120.12"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="2" points="504.36,-122.87 512.66,-121.19 505.12,-117.32 504.36,-122.87"/>
+<text xml:space="preserve" text-anchor="middle" x="436.62" y="-116.73" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">fire on schedule</text>
+</g>
+<!-- Prompt -->
+<g id="node5" class="node">
+<title>Prompt</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M894.62,-218.88C894.62,-218.88 811.12,-218.88 811.12,-218.88 805.12,-218.88 799.12,-212.88 799.12,-206.88 799.12,-206.88 799.12,-194.88 799.12,-194.88 799.12,-188.88 805.12,-182.88 811.12,-182.88 811.12,-182.88 894.62,-182.88 894.62,-182.88 900.62,-182.88 906.62,-188.88 906.62,-194.88 906.62,-194.88 906.62,-206.88 906.62,-206.88 906.62,-212.88 900.62,-218.88 894.62,-218.88"/>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-203.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">:prompt</text>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-190.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">→ pwn&#45;ai one&#45;shot</text>
+</g>
+<!-- Runner&#45;&gt;Prompt -->
+<g id="edge5" class="edge">
+<title>Runner&#45;&gt;Prompt</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M623.65,-144.21C638.6,-148.43 654.91,-152.93 670,-156.88 709.5,-167.22 754.05,-178.01 789.18,-186.32"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="788.48,-189.03 796.91,-188.14 789.76,-183.58 788.48,-189.03"/>
+</g>
+<!-- Ruby -->
+<g id="node6" class="node">
+<title>Ruby</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M922,-146.88C922,-146.88 783.75,-146.88 783.75,-146.88 777.75,-146.88 771.75,-140.88 771.75,-134.88 771.75,-134.88 771.75,-122.88 771.75,-122.88 771.75,-116.88 777.75,-110.88 783.75,-110.88 783.75,-110.88 922,-110.88 922,-110.88 928,-110.88 934,-116.88 934,-122.88 934,-122.88 934,-134.88 934,-134.88 934,-140.88 928,-146.88 922,-146.88"/>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-131.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">:ruby</text>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-118.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">→ TOPLEVEL_BINDING.eval</text>
+</g>
+<!-- Runner&#45;&gt;Ruby -->
+<g id="edge6" class="edge">
+<title>Runner&#45;&gt;Ruby</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M623.53,-128.88C662.29,-128.88 715.87,-128.88 761.38,-128.88"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="761.29,-131.68 769.29,-128.88 761.29,-126.08 761.29,-131.68"/>
+</g>
+<!-- Script -->
+<g id="node7" class="node">
+<title>Script</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M896.12,-74.88C896.12,-74.88 809.62,-74.88 809.62,-74.88 803.62,-74.88 797.62,-68.88 797.62,-62.88 797.62,-62.88 797.62,-50.88 797.62,-50.88 797.62,-44.88 803.62,-38.88 809.62,-38.88 809.62,-38.88 896.12,-38.88 896.12,-38.88 902.12,-38.88 908.12,-44.88 908.12,-50.88 908.12,-50.88 908.12,-62.88 908.12,-62.88 908.12,-68.88 902.12,-74.88 896.12,-74.88"/>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-59.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">:script</text>
+<text xml:space="preserve" text-anchor="middle" x="852.88" y="-46.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">→ exec external file</text>
+</g>
+<!-- Runner&#45;&gt;Script -->
+<g id="edge7" class="edge">
+<title>Runner&#45;&gt;Script</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M623.53,-115.33C670.17,-103.39 738.24,-85.97 787.93,-73.25"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="788.33,-76.03 795.39,-71.34 786.94,-70.61 788.33,-76.03"/>
+</g>
+<!-- Log -->
+<g id="node8" class="node">
+<title>Log</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.4" d="M1161.25,-148.56C1161.25,-150.98 1131.61,-152.94 1095.12,-152.94 1058.64,-152.94 1029,-150.98 1029,-148.56 1029,-148.56 1029,-109.19 1029,-109.19 1029,-106.78 1058.64,-104.81 1095.12,-104.81 1131.61,-104.81 1161.25,-106.78 1161.25,-109.19 1161.25,-109.19 1161.25,-148.56 1161.25,-148.56"/>
+<path fill="none" stroke="#334155" stroke-width="1.4" d="M1161.25,-148.56C1161.25,-146.15 1131.61,-144.19 1095.12,-144.19 1058.64,-144.19 1029,-146.15 1029,-148.56"/>
+<text xml:space="preserve" text-anchor="middle" x="1095.12" y="-131.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">~/.pwn/cron/log/&lt;id&gt;.log</text>
+<text xml:space="preserve" text-anchor="middle" x="1095.12" y="-118.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">last_run · last_status</text>
+</g>
+<!-- Prompt&#45;&gt;Log -->
+<g id="edge8" class="edge">
+<title>Prompt&#45;&gt;Log</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M907.19,-184.9C940.2,-175.01 983.08,-162.16 1019.44,-151.26"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="1019.79,-154.08 1026.65,-149.1 1018.18,-148.71 1019.79,-154.08"/>
+</g>
+<!-- Ruby&#45;&gt;Log -->
+<g id="edge9" class="edge">
+<title>Ruby&#45;&gt;Log</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M934.54,-128.88C961.74,-128.88 991.97,-128.88 1018.74,-128.88"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="1018.47,-131.68 1026.47,-128.88 1018.47,-126.08 1018.47,-131.68"/>
+</g>
+<!-- Script&#45;&gt;Log -->
+<g id="edge10" class="edge">
+<title>Script&#45;&gt;Log</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M908.69,-73.3C941.36,-83.1 983.3,-95.66 1019.02,-106.37"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="1018.09,-109.01 1026.55,-108.63 1019.69,-103.65 1018.09,-109.01"/>
+</g>
+<!-- Log&#45;&gt;Jobs -->
+<g id="edge11" class="edge">
+<title>Log&#45;&gt;Jobs</title>
+<path fill="none" stroke="#fbbf24" stroke-width="1.3" stroke-dasharray="5,2" d="M1069.63,-104.26C1041.6,-78 992.95,-38 942,-21.88 759.1,36 698.93,-34.31 516.25,-92.88 461.31,-110.49 399.34,-132.73 355.76,-148.78"/>
+<polygon fill="#fbbf24" stroke="#fbbf24" stroke-width="1.3" points="354.85,-146.13 348.32,-151.53 356.79,-151.38 354.85,-146.13"/>
+<text xml:space="preserve" text-anchor="middle" x="697.38" y="-35.59" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">update status</text>
+</g>
+</g>
+</svg>

data/documentation/diagrams/dot/_THEME.md

@@ -0,0 +1,27 @@
+# PWN Diagram Visual Theme
+
+All `.dot` files in this directory share one visual language so the rendered
+SVGs feel like a single coherent product.
+
+| Element              | Color     | Hex       |
+|----------------------|-----------|-----------|
+| Background           | slate-900 | `#0f172a` |
+| Cluster border       | slate-700 | `#334155` |
+| Cluster fill         | slate-800 | `#1e293b` |
+| Actor / Entry (blue) | sky-300   | `#7dd3fc` |
+| AI / Agent (purple)  | violet-300| `#c4b5fd` |
+| Capability (green)   | emerald-300| `#6ee7b7`|
+| Persistence (amber)  | amber-300 | `#fcd34d` |
+| Target / Danger (red)| rose-300  | `#fda4af` |
+| Edge default         | slate-400 | `#94a3b8` |
+| Edge highlight       | sky-400   | `#38bdf8` |
+
+Layout rules (to avoid criss-crossed edges):
+1. `rankdir=TB` (or `LR` for pipelines), `newrank=true`, `splines=spline`.
+2. Group every layer with `{rank=same; ...}` — edges go layer→layer only.
+3. Side/back edges use `constraint=false` + `style=dashed` and are kept to ≤3 per diagram.
+4. One `subgraph cluster_*` per logical layer with a translucent fill.
+5. Node order inside a rank matches edge destinations in the next rank
+   (Graphviz then draws parallel non-crossing edges).
+
+Rebuild everything: `./build.sh` (from `documentation/diagrams/`).

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

@@ -1,23 +1,50 @@
-digraph "PWN AI Integration & Tool Calling" {
-  rankdir=LR;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+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];
 
-  User [label="User Prompt"];
-  Agent [label="PWN::AI::Agent", shape=ellipse, fillcolor=lightblue];
-  LLM [label="LLM (Grok OAuth,\nOpenAI, etc.)", shape=box];
-  Tools [label="Tool Registry\n(pwn_eval, shell,\nmemory_*, skill_*, \nlearning_*)", shape=box];
-  PWNNS [label="PWN Namespace\n(Plugins, SAST,\nReports, etc.)", shape=box];
-  External [label="External Tools\n(curl, nmap, msf, burp)", shape=box];
+  Loop [label="PWN::AI::Agent::Loop\ntool-calling harness", fillcolor="#7dd3fc", penwidth=2];
 
-  User -> Agent;
-  Agent -> LLM [label="build prompt +\ntools schema"];
-  LLM -> Agent [label="tool_calls[]"];
-  Agent -> Tools [label="dispatch"];
-  Tools -> PWNNS [label="PWN::Plugins::XXX.method"];
-  Tools -> External [label="shell commands"];
-  PWNNS -> Tools [label="return value\nor exception"];
-  External -> Tools [label="stdout/stderr"];
-  Tools -> Agent [label="results"];
-  Agent -> LLM [label="continue conversation"];
-  Agent -> User [label="final answer + artifacts"];
+  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

@@ -1,15 +1,26 @@
-digraph "PWN BurpSuite vs Zaproxy Preference" {
-  rankdir=LR;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+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];
 
-  Decision [label="Web Proxy Choice\nin PWN", shape=diamond, fillcolor=lightyellow];
-  Burp [label="PWN::Plugins::BurpSuite\n(preferred for most cases)\n- Comprehensive scanning\n- Rich ecosystem\n- Active scan + extensions", shape=box, fillcolor=lightgreen];
-  Zap [label="PWN::Plugins::Zaproxy\n(fallback)\n- Open source\n- REST API scans", shape=box, fillcolor=lightblue];
+  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"];
 
-  UserTask [label="Web App Test Task"];
-  UserTask -> Decision;
-  Decision -> Burp [label="default / most features"];
-  Decision -> Zap [label="if Burp unavailable\nor specific REST need"];
-  Burp -> "Scan / Proxy / Exploit";
-  Zap -> "Scan / Proxy / Exploit";
+  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

@@ -1,21 +1,49 @@
-digraph "PWN Code Scanning & SAST" {
-  rankdir=LR;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+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];
 
-  Source [label="Source Code\n(Git, Local Dir)", shape=box];
-  SAST [label="PWN::SAST\n(analyze, testgen)", shape=ellipse, fillcolor=lightgreen];
-  Static [label="Static Analysis\n(RuboCop, Brakeman,\nSemgrep, custom rules)"];
-  TestGen [label="Test Case Gen\n(unit/integration fuzz)"];
-  Findings [label="Vulns / Findings\n(CWE mapped)", shape=box];
-  Reports [label="PWN::Reports\n(generate PDF/MD/JSON)", shape=ellipse, fillcolor=lightgreen];
-  REPL [label="REPL / Agent\n(inspect findings)"];
+  Src [label="📁  Source Tree\ngit clone / repo", fillcolor="#7dd3fc"];
 
-  Source -> SAST;
-  SAST -> Static;
-  SAST -> TestGen;
-  Static -> Findings;
-  TestGen -> Findings;
-  Findings -> Reports;
-  Reports -> REPL;
-  REPL -> Source [label="patch & re-scan"];
+  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

@@ -1,17 +1,39 @@
-digraph "PWN Driver Framework" {
-  rankdir=LR;
-  node [shape=box, style=rounded, fontname="Arial", fontsize=9];
+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];
 
-  Parser [label="PWN::Driver::Parser\n(OptionParser + auto_opts)"];
-  Script [label="Driver Script\n(bin/pwn_* or custom)"];
-  PWNLoad [label="require 'pwn'\nFull namespace"];
-  Orchestrate [label="Orchestration Logic\n(plugins + AI + loops)"];
-  Outputs [label="Reports, Logs,\nFindings"];
+  Sh [label="$ pwn_burp_suite_pro_active_scan \\ \n    -t https://target -o out/", fillcolor="#7dd3fc"];
 
-  Script -> Parser;
-  Parser -> Script;
-  Script -> PWNLoad;
-  PWNLoad -> Orchestrate;
-  Orchestrate -> Outputs;
-  Script -> "standalone | cron | pwn-ai";
+  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];
+}