pwn 0.5.779 → 0.5.781

data/documentation/diagrams/dot/_THEME.md

@@ -16,12 +16,14 @@ SVGs feel like a single coherent product.
 | Edge default         | slate-400 | `#94a3b8` |
 | Edge highlight       | sky-400   | `#38bdf8` |
 
-Layout rules (to avoid criss-crossed edges):
+Layout guidelines (reduce crossings without inventing dependencies):
 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.
+2. Group related layers when helpful. Actual feedback and cross-layer calls must
+   remain explicit; do not add false edges solely to align nodes.
+3. Side/back edges may use `constraint=false` + `style=dashed`. Label whether
+   an edge is automatic, optional, or an operator-composed handoff.
 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).
+   (Graphviz may still produce crossings; inspect the rendered SVG).
 
 Rebuild everything: `./build.sh` (from `documentation/diagrams/`).

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

@@ -1,6 +1,6 @@
 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">13 toolsets · 87 callable tools · lib/pwn/ai/agent/tools/*</FONT>>,
+    label=<<B>PWN::AI::Agent::Registry - Toolsets exposed to the LLM</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">16 toolsets · 150 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
@@ -27,13 +27,16 @@ digraph "PWN_Agent_Tool_Registry" {
     reward   [label="reward",   fillcolor="#6ee7b7"];
     curric   [label="curriculum", fillcolor="#6ee7b7"];
     policy   [label="policy",   fillcolor="#6ee7b7"];
+    http [label="http\nproxy lifecycle / replay", fillcolor="#6ee7b7"];
+    mcp [label="mcp\nbackend broker", fillcolor="#6ee7b7"];
+    manifest [label="manifest\nYAML declarations", 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\n(ToolGuard)"];
+    t_shell   [label="shell · job_run/status/tail/result/kill\n(runtime permissions + ToolGuard)"];
     t_eval    [label="pwn_eval\n(ToolGuard)"];
     t_mem     [label="memory_remember\nrecall · forget · clear\nlean"];
     t_skill   [label="skills_recall · skill_list\nview · create · add_reference\ndelete · migrate_legacy"];
@@ -52,6 +55,7 @@ digraph "PWN_Agent_Tool_Registry" {
   Registry -> skills; Registry -> sessions; Registry -> learning;
   Registry -> metrics; Registry -> extro; Registry -> cron; Registry -> swarm;
   Registry -> reward; Registry -> curric; Registry -> policy;
+  Registry -> http; Registry -> mcp; Registry -> manifest;
 
   terminal -> t_shell  [color="#f59e0b"];
   pwn      -> t_eval   [color="#f59e0b"];

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

@@ -27,7 +27,7 @@ digraph "PWN_AI_Integration" {
   subgraph cluster_api {
     label="Provider APIs"; fontcolor="#fecaca"; style="rounded,dashed";
     color="#b91c1c"; bgcolor="#450a0a";
-    A1 [label="api.openai.com",    fillcolor="#fda4af"];
+    A1 [label="api.openai.com (API key)\nchatgpt.com/backend-api/codex (OAuth)",    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"];

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

@@ -1,6 +1,6 @@
 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>>,
+    label=<<B>PWN::SAST - Static Application Security Testing</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">48 modules · 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
@@ -15,11 +15,11 @@ digraph "PWN_SAST" {
   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"];
+    Factory [label="pwn_sast\nrule orchestration",       fillcolor="#6ee7b7"];
+    TCE     [label="TestCaseEngine\nexecute filters",   fillcolor="#6ee7b7"];
   }
   subgraph cluster_rules {
-    label="Rule Families (48)"; fontcolor="#fde68a"; style=rounded;
+    label="Selected rule families"; 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"];
@@ -39,11 +39,11 @@ digraph "PWN_SAST" {
   Factory -> Cmd  [color="#f59e0b"];
   Factory -> Web  [color="#f59e0b"];
   Factory -> Cryp [color="#f59e0b"];
-  TCE     -> Data [color="#f59e0b"];
-  TCE     -> Mem  [color="#f59e0b"];
+  Factory -> Data [color="#f59e0b"];
+  Factory -> Mem  [color="#f59e0b"];
   Cmd  -> Report [color="#a78bfa"];
   Web  -> Report [color="#a78bfa"];
   Cryp -> Report [color="#a78bfa"];
-  Data -> DD     [color="#a78bfa"];
-  Mem  -> DD     [color="#a78bfa"];
+  Data -> Report     [color="#a78bfa"];
+  Mem  -> Report     [color="#a78bfa"];
 }

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

@@ -39,6 +39,8 @@ digraph "PWN_Cron" {
   }
   {rank=same; Practice; Offline; Train; MemGC; Lean}
 
+  Cleanup [label="session_cleanup\n45 3 * * * ON\nleases / pins / backup before delete", fillcolor="#c4b5fd"];
+  Ruby -> Cleanup; Cleanup -> Log;
   Log [label="~/.pwn/cron/log/<id>.log\nlast_run · last_status", shape=cylinder, fillcolor="#fcd34d"];
 
   Create  -> Jobs    [label="write", color="#38bdf8"];

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

@@ -1,6 +1,6 @@
 digraph "PWN_Driver" {
   graph [
-    label=<<B>Driver Anatomy - bin/pwn_*</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">54 executables (pwn + 53 pwn_*) · thin CLI over PWN::Plugins</FONT>>,
+    label=<<B>Driver Anatomy - bin/pwn_*</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">56 executables (pwn / pwn-ai / pwn-capd + 53 pwn_*) · 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

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

@@ -43,7 +43,7 @@ digraph "PWN_Extrospection" {
     Obs   [label="extro_observe\nrecon · vuln · intel · target\nnetwork · env · rf · web\nosint · serial · telecomm\npacket · vision · voice", fillcolor="#fcd34d"];
     Intel [label="extro_intel\nCVE / exploit lookup",  fillcolor="#fcd34d"];
     Watch [label="extro_watch\nrender → DOM SHA-256\nscreenshot · TLS fp", fillcolor="#fcd34d"];
-    Verify[label="extro_verify\n:cve · :version · :doc · :generic\n→ :confirmed | :refuted | :unknown", fillcolor="#fcd34d", penwidth=2];
+    Verify[label="extro_verify\n:cve · :version · :doc · :generic\nheuristic: confirmed | refuted | unknown", fillcolor="#fcd34d", penwidth=2];
     RFTune[label="extro_rf_tune  📡\ntune GQRX · demod · strength\nRDS PI/PS/RadioText → now_playing", fillcolor="#fcd34d", penwidth=2];
     OsintT[label="extro_osint  🕵️\npublic APIs aggregate\nphone · FCC · patent · person", fillcolor="#fcd34d", penwidth=2];
     SerT  [label="extro_serial  🔌\nopen · payload · drain\nPWN::Plugins::Serial", fillcolor="#fcd34d", penwidth=2];
@@ -51,7 +51,7 @@ digraph "PWN_Extrospection" {
     PktT  [label="extro_packet  📦\ncapture · summarise pcap\ntshark/PacketFu", fillcolor="#fcd34d", penwidth=2];
     VisT  [label="extro_vision  👁\nOCR · barcode/QR", fillcolor="#fcd34d", penwidth=2];
     VoxT  [label="extro_voice  🔊\nTTS · STT · inventory", fillcolor="#fcd34d", penwidth=2];
-    Corr  [label="extro_correlate\njoin with Learning\n+ Mistakes + Memory", fillcolor="#fcd34d", penwidth=2];
+    Corr  [label="extro_correlate\ncandidate correlations\nLearning + Mistakes + Memory", fillcolor="#fcd34d", penwidth=2];
   }
   {rank=same; Snap; Drift; Obs; Intel; Watch; Verify; RFTune; OsintT; SerT; TelT; PktT; VisT; VoxT; Corr}
 

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

@@ -15,7 +15,7 @@ digraph "PWN_Fuzz" {
   subgraph cluster_gen {
     label="Generate"; fontcolor="#a7f3d0"; style=rounded;
     color="#047857"; bgcolor="#022c22";
-    Fuzz [label="Plugins::Fuzz\nmutate · generate", fillcolor="#6ee7b7"];
+    Fuzz [label="Plugins::Fuzz\nhttp · file_format · socket", fillcolor="#6ee7b7"];
     Char [label="Plugins::Char\nencodings",         fillcolor="#6ee7b7"];
   }
   subgraph cluster_deliver {
@@ -31,7 +31,7 @@ digraph "PWN_Fuzz" {
     PS  [label="Plugins::PS\nprocess health", fillcolor="#fda4af"];
     Log [label="Plugins::Log\ncrash detect",   fillcolor="#fda4af"];
   }
-  Report [label="Reports::Fuzz\ncrash triage", fillcolor="#7dd3fc"];
+  Report [label="Reports::Fuzz\nrender results_hash", fillcolor="#7dd3fc"];
 
   Seed -> Fuzz [color="#38bdf8"];
   Seed -> Char [color="#38bdf8"];
@@ -43,5 +43,5 @@ digraph "PWN_Fuzz" {
   NetApp -> Log [color="#fb7185"];
   PS  -> Report [color="#38bdf8"];
   Log -> Report [color="#38bdf8"];
-  Log -> Fuzz [label="minimise + reseed", style=dashed, color="#fbbf24", constraint=false];
+  Log -> Fuzz [label="operator triage + reseed", style=dashed, color="#fbbf24", constraint=false];
 }

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

@@ -11,7 +11,7 @@ digraph "PWN_HistToDriver" {
         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"];
+  Hist    [label="~/.pwn/pwn_history\nPry `history` cmd", shape=cylinder, fillcolor="#fcd34d"];
   Extract [label="copy working lines", fillcolor="#6ee7b7"];
 
   subgraph cluster_out {

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

@@ -16,11 +16,11 @@ digraph "PWN_MemorySkills" {
     Rem    [label="memory_remember · lean\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"];
+    Dist   [label="learning_distill_skill\n(explicit reviewed distillation)",   fillcolor="#6ee7b7"];
     Mrec   [label="mistakes_record\nmistakes_resolve",           fillcolor="#6ee7b7"];
     Xft    [label="Learning.export_finetune\n(sessions → dataset)", fillcolor="#6ee7b7"];
     Rdpo   [label="Reward.record_preference\nexport_dpo", fillcolor="#6ee7b7"];
-    PolW   [label="Policy.begin / observe / finish\n(Q + REINFORCE)", fillcolor="#6ee7b7"];
+    PolW   [label="Policy.begin_episode / observe_step / finish\neligible attributed credit only", fillcolor="#6ee7b7"];
   }
   {rank=same; Rem; Skc; Note; Dist; Mrec; Xft; Rdpo; PolW}
 
@@ -79,7 +79,7 @@ digraph "PWN_MemorySkills" {
   Rem  -> Fidx [label="incremental\nre-embed", style=dashed, color="#fbbf24"];
   Xft  -> Fftn [color="#f59e0b"];
   Xft  -> Fses [dir=back, style=dashed, color="#fbbf24", label="mine"];
-  Xft  -> Flrn [dir=back, style=dashed, color="#fbbf24", label="success:true"];
+  Xft  -> Flrn [dir=back, style=dashed, color="#fbbf24", label="eligible verified outcomes"];
   
   Fidx -> Midx [color="#a78bfa"];
   Fmem -> Midx [style=dashed, color="#a78bfa"];

data/documentation/diagrams/dot/mistakes-negative-feedback.dot

@@ -15,7 +15,7 @@ digraph "PWN_Mistakes_Negative_Feedback" {
     label="Five ingest paths"; fontcolor="#fecaca"; style="rounded,dashed";
     color="#b91c1c"; bgcolor="#450a0a";
     ToolFail [label=":tool\nDispatch → success:false",           fillcolor="#fda4af"];
-    LoopFail [label=":loop\niteration budget exhausted",          fillcolor="#fda4af"];
+    LoopFail [label=":loop\nlegacy budget scar (not emitted)",          fillcolor="#fda4af"];
     UserCorr [label=":user_correction\n\"no that's wrong\" / \"still broken\"", fillcolor="#fda4af"];
     ModelRec [label=":model\nmistakes_record(tool, error)",       fillcolor="#fda4af"];
     Verify  [label=":model (proactive)\nextro_verify → :refuted\n(browser-caught assumption)", fillcolor="#fda4af", penwidth=2];
@@ -40,7 +40,7 @@ digraph "PWN_Mistakes_Negative_Feedback" {
     label="Reactions inside Loop.run"; fontcolor="#ddd6fe"; style=rounded;
     color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
     Guard [label="guard_repeated_failure\nmax(turn, PERSISTENT count) ≥ 3\n→ trips on 1st recurrence\nin a new session", fillcolor="#c4b5fd"];
-    Hint  [label="correction_hint\nappend to failed result:\n\"seen N×, sig=..., KNOWN FIX: ...\"\n→ self-correct NEXT iter",  fillcolor="#c4b5fd"];
+    Hint  [label="correction_hint\nappend to failed result:\n\"seen N×, sig=..., KNOWN FIX: ...\"\n→ correction guidance next iter",  fillcolor="#c4b5fd"];
     Regr  [label="[REGRESSED]\nresolved sig recurs\n→ reopen + tag",                                                       fillcolor="#c4b5fd"];
   }
   {rank=same; Guard; Hint; Regr}

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

@@ -1,122 +1,34 @@
-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 · Grok\nGemini · Ollama · Open WebUI", 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_*\n54 executables",            fillcolor="#7dd3fc"];
-    Cronb [label="⏱  PWN::Cron\nJobs + background worker", fillcolor="#7dd3fc"];
-  }
-  {rank=same; REPL; PwnAI; CLI; Cronb}
-
-  /* ───────── L2 · AI AGENT CORE ───────── */
-  subgraph cluster_agent {
-    label="PWN::AI::Agent"; fontcolor="#ddd6fe";
-    style=rounded; color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
-    Loop     [label="Loop\nTaskSummarizer briefs\nplan → dispatch → observe\nmax_iters 777 (scars do not shrink)\nlast-iter tools only if done",      fillcolor="#c4b5fd"];
-    Registry [label="Registry\n13 toolsets · 87 tools\ntool_router (CORE+topK)",    fillcolor="#c4b5fd"];
-    Swarm    [label="Swarm\npersonas · debate · bus",        fillcolor="#c4b5fd"];
-    Prompt   [label="PromptBuilder\nengine-budgeted blocks\nMEMORY · SKILLS · POLICY\nMemoryIndex → relevance-ranked",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\n67 modules",     fillcolor="#6ee7b7"];
-    SAST    [label="SAST\n48 rules",          fillcolor="#6ee7b7"];
-    WWW     [label="WWW\n22 site drivers",    fillcolor="#6ee7b7"];
-    AWS     [label="AWS\n90 services",        fillcolor="#6ee7b7"];
-    SDR     [label="SDR\nGQRX · Flipper · RFID\nDecoder::* (20+Base/DSP)", 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"];
-    MemIdx   [label="memory.idx\n(embed index)", shape=cylinder, fillcolor="#fcd34d"];
-    Skills   [label="skills/<n>/SKILL.md",        shape=cylinder, fillcolor="#fcd34d"];
-    Learn    [label="learning.jsonl",     shape=cylinder, fillcolor="#fcd34d"];
-    Metrics  [label="metrics.json",       shape=cylinder, fillcolor="#fcd34d"];
-    MistF    [label="mistakes.json",      shape=cylinder, fillcolor="#fcd34d"];
-    Extro    [label="extrospection.json\nrf · web · observations", 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"];
-    Finetune [label="finetune/*.jsonl", shape=cylinder, fillcolor="#fcd34d"];
-    Prefs    [label="preferences.jsonl", shape=cylinder, fillcolor="#fcd34d"];
-    PolicyF  [label="policy.json\npolicy_traj.jsonl", shape=cylinder, fillcolor="#fcd34d"];
-  }
-  {rank=same; Memory; MemIdx; Skills; Learn; Metrics; MistF; Extro; Sessions; SwarmB; CronF; Finetune; Prefs; PolicyF}
-
-  /* ── 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     -> MistF    [style=invis];
-  SDR     -> Extro    [color="#f59e0b"];
-  Chain   -> Sessions [color="#f59e0b"];
-  Bounty  -> SwarmB   [color="#f59e0b"];
-  Reports -> CronF    [color="#f59e0b"];
-  Reports -> Prefs    [style=invis];
-
-  /* ── 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];
+digraph PWN_Architecture {
+  graph [label="PWN - runtime ownership and evidence flow", labelloc=t, fontsize=22,
+    fontname="Helvetica", rankdir=TB, bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6];
+  node [fontname="Helvetica", fontsize=11, shape=box, style="rounded,filled", fillcolor="#c4b5fd", color="#334155"];
+  edge [fontname="Helvetica", fontsize=9, color="#94a3b8", fontcolor="#cbd5e1"];
+  Operator [label="Operator / CI", fillcolor="#7dd3fc"];
+  Entry [label="pwn / pwn-ai CLI and curses\n56 executables total", fillcolor="#7dd3fc"];
+  Mesh [label="pwn-mesh\nprimary radio or MQTT + optional secondary MQTT\n@ai / private channel / whitelist gate", fillcolor="#7dd3fc"];
+  Runtime [label="RequestRuntime + Loop\noriginal objective / additive steering\ncheckpoint / permissions / uncertain effects"];
+  Prompt [label="PromptBuilder\nmemory / skills / lessons / mistakes / policy\nHOST: DetectOS summary + PreflightChecker"];
+  Registry [label="Registry: 16 toolsets / 150 tools\nnormal Loop: core-only + relevant MCP"];
+  Provider [label="Configured provider adapter\nrequest-local routing and retry ownership", fillcolor="#fda4af"];
+  Dispatch [label="Dispatch / ToolGuard / confirmation / sandbox"];
+  Capabilities [label="107 plugin modules / 48 SAST modules\n90 AWS wrappers / 22 WWW drivers\nSDR / blockchain / reports / FFI", fillcolor="#6ee7b7"];
+  Target [label="Authorized target / external service / hardware\nrequires separate live validation", fillcolor="#fda4af"];
+  Evidence [label="Host observations / exact-target artifacts\nSessions / request checkpoints", shape=cylinder, fillcolor="#fcd34d"];
+  Verify [label="Finalization arbiter + Verification\ncurrent bytes / authored checks / complete coverage"];
+  Outcome [label="Verified / failed / unknown or incomplete\nnot model prose alone", fillcolor="#7dd3fc"];
+  Learn [label="Reward / Learning / Mistakes / Metrics\nclaim and verified-completion fields\nPolicy positive credit needs attribution"];
+  Stores [label="Default ~/.pwn stores\nplus explicit artifact/worktree paths", shape=cylinder, fillcolor="#fcd34d"];
+  Swarm [label="Swarm nested Loop / Solve\nparent rechecks child artifact receipts"];
+  Cron [label="Cron scheduler\nhygiene on / curriculum opt-in"];
+  Operator -> Entry; Operator -> Mesh;
+  Entry -> Runtime; Mesh -> Runtime [label="eligible received @ai only"];
+  Runtime -> Prompt; Runtime -> Registry; Prompt -> Provider; Registry -> Provider;
+  Provider -> Dispatch [label="tool calls"]; Dispatch -> Capabilities;
+  Capabilities -> Target; Dispatch -> Evidence; Evidence -> Runtime [label="observations"];
+  Runtime -> Verify; Evidence -> Verify; Verify -> Outcome;
+  Outcome -> Learn; Learn -> Stores; Stores -> Prompt [style=dashed];
+  Dispatch -> Swarm; Swarm -> Runtime [label="child turn", style=dashed];
+  Cron -> Runtime [label="prompt jobs"]; Cron -> Learn [label="explicit maintenance"];
+  Outcome -> Entry [label="release result", style=dashed];
+  Outcome -> Mesh [label="origin-bound reply; submission != RF delivery", style=dashed];
 }

data/documentation/diagrams/dot/persistence-filesystem.dot

@@ -1,6 +1,6 @@
 digraph "PWN_Persistence" {
   graph [
-    label=<<B>~/.pwn/ - Everything PWN Persists Across Sessions</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">verified / auto-repaired by PWN::Migrate  ·  pwn setup --migrate --fix</FONT>>,
+    label=<<B>~/.pwn/ - Default User-State Map</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">registered state checked / repaired by PWN::Migrate  ·  pwn setup --migrate --fix</FONT>>,
     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
@@ -32,7 +32,7 @@ digraph "PWN_Persistence" {
   cur  [label="curriculum/ + curriculum_kpi.jsonl\nself-play · A/B eval · KPI trend"];
   ftn  [label="finetune/*.jsonl\nShareGPT / OpenAI SFT + DPO"];
   bkp  [label="backup/<ts>/ · quarantine/\nMigrate autofix snapshots"];
-  hist [label="~/.pwn_history\nREPL history"];
+  hist [label="~/.pwn/pwn_history\nREPL history"];
 
   Root->cfg;  Root->schm; Root->mem;  Root->midx; Root->skl;  Root->lrn;
   Root->prf;  Root->mis;  Root->met;  Root->pol;  Root->rws;  Root->ext;  Root->eart;

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

@@ -1,6 +1,6 @@
 digraph "PWN_Plugins" {
   graph [
-    label=<<B>PWN::Plugins - 67 Modules by Category</B>>,
+    label=<<B>PWN::Plugins - Selected categories from 107 plugin modules</B>>,
     labelloc=t, fontsize=20, fontname="Helvetica",
     rankdir=LR, splines=spline, nodesep=0.25, ranksep=1.5,
     bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
@@ -34,7 +34,7 @@ digraph "PWN_Plugins" {
   d  [label="DAO::LDAP/Mongo/PG/SQLite\nJSONPathify · PDFParse · OCR"];
   a  [label="OAuth2 · BasicAuth\nAuthenticationHelper · Vault"];
   h  [label="Serial · BusPirate\nMSR206 · Android · BareSIP"];
-  c  [label="Jenkins · Git · vSphere\nDefectDojo · BlackDuck"];
+  c  [label="Jenkins · Git · Vsphere\nDefectDojo · BlackDuck"];
   m  [label="MailAgent · SlackClient\nIRC · RabbitMQ · TwitterAPI · Voice"];
   u  [label="FileFu · ThreadPool · Log\nChar · XXD · DetectOS\nScannableCodes · CreditCard\nSSN · EIN · VIN · Pony · PS\nTTYSpinner"];