pwn 0.5.779 → 0.5.781

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

@@ -1,168 +1,32 @@
-digraph "PWN_AI_Feedback_Learning_Loop" {
-  graph [
-    label=<<B>pwn-ai - Closed Self-Improvement Loop</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Introspection (self)  ⟷  Extrospection (world)  ·  Mistakes (negative)  ·  Reward + Curriculum + Policy (RL)  ·  Local-model scaffolding</FONT>>,
-    labelloc=t, fontsize=20, fontname="Helvetica",
-    rankdir=TB, splines=spline, nodesep=0.6, ranksep=1.0,
-    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true, compound=true
-  ];
-  node [fontname="Helvetica", fontsize=11, style="filled,rounded",
-        shape=box, penwidth=1.4, color="#334155", fontcolor="#0f172a"];
-  edge [fontname="Helvetica", fontsize=9, color="#94a3b8",
-        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
-
-  /* L0 ─ actors */
-  User  [label="👤  Researcher", fillcolor="#7dd3fc"];
-  LLM   [label="🤖  LLM Provider", fillcolor="#c4b5fd"];
-  World [label="🌍  Host · Net · Repo\nToolchain · RF · Web · Intel", fillcolor="#fda4af"];
-  {rank=same; User; LLM; World}
-
-  /* L1 ─ agent core */
-  subgraph cluster_core {
-    label="PWN::AI::Agent::Loop  ·  budget pressure · TaskSummarizer"; fontcolor="#ddd6fe";
-    style=rounded; color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
-    Prompt   [label="PromptBuilder\nbudget · MemoryIndex\nrelevance-ranked ctx", fillcolor="#c4b5fd"];
-    Dispatch [label="Dispatch\ntolerant parse\nToolGuard · repair_name", fillcolor="#c4b5fd"];
-Router   [label="Registry\ntool_router\nCORE + top-K",   fillcolor="#c4b5fd"];
-Plan     [label="plan_first\n(pre-pass, local)",         fillcolor="#c4b5fd"];
-TaskSum  [label="TaskSummarizer\nemit_plan! · about_to\ndedup last_brief_fp", fillcolor="#c4b5fd", penwidth=2];
-Escalate [label="escalate\n>=N fails → Swarm hint",        fillcolor="#c4b5fd", penwidth=2];
-    Result   [label="Result\nfinal answer",           fillcolor="#c4b5fd"];
-  }
-  {rank=same; Prompt; Router; Plan; TaskSum; Dispatch; Escalate; Result}
-
-  /* L2 ─ triple engines */
-  subgraph cluster_intro {
-    label="INTROSPECTION  (self)"; fontcolor="#a7f3d0";
-    style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
-    Metrics  [label="Metrics\nESR = verified exploit tools / vulnerable tools\nASR = successful attacks / attempts", fillcolor="#6ee7b7"];
-    Learning [label="Learning\nnote_outcome · reflect\nexemplars_for · SFT quality gate\nfact_check_local_final", fillcolor="#6ee7b7"];
-    Mistakes [label="Mistakes\nrecord · resolve\nguard · correction_hint\n[REPEATING] · [REGRESSED]", fillcolor="#6ee7b7", penwidth=2];
-    ReflectT [label="Reflect\nteacher-student\n(reflect_engine)", fillcolor="#6ee7b7", penwidth=2];
-    Reward   [label="Reward\njudge · prm · semantic_ok\nsentinel warm\nDPO scrub <=40%/src", fillcolor="#6ee7b7", penwidth=2];
-    Curric   [label="Curriculum\npractice · offline_judge\ncritic/CF geometry · gate + diet", fillcolor="#6ee7b7", penwidth=2];
-    Policy   [label="Policy\nlive Q / REINFORCE\nbegin · observe · finish\nadvisory rank only", fillcolor="#6ee7b7", penwidth=2];
-  }
-  subgraph cluster_extro {
-    label="EXTROSPECTION  (world)"; fontcolor="#fde68a";
-    style=rounded; color="#a16207"; bgcolor="#422006"; penwidth=2;
-    Snapshot  [label="snapshot · drift\nhost/net/toolchain\nrepo/env/rf/web\n(AUTO_SECTIONS=host/repo/env)", fillcolor="#fcd34d"];
-    Observe   [label="observe · intel · watch\nrecon · CVE · web DOM",             fillcolor="#fcd34d"];
-    Verify    [label="verify (browser)\nfact-check own claims\nrevalidate_memory", fillcolor="#fcd34d", penwidth=2];
-    RFTune    [label="rf_tune  📡\ntune GQRX · demod\nRDS → now_playing",           fillcolor="#fcd34d", penwidth=2];
-  }
-  {rank=same; Metrics; Learning; Mistakes; ReflectT; Reward; Curric; Policy; Snapshot; Observe; Verify; RFTune}
-
-  /* L3 ─ correlate */
-  Correlate [label="extro_correlate()\n\"I did it wrong\"  vs  \"the world changed\"",
-             fillcolor="#fda4af", penwidth=2, fontsize=12];
-
-  /* L4 ─ persistence */
-  subgraph cluster_store {
-    label="~/.pwn/"; fontcolor="#94a3b8";
-    style="rounded,dashed"; color="#334155"; bgcolor="#1e293b";
-    Fmet [label="metrics.json",       shape=cylinder, fillcolor="#fcd34d"];
-    Flrn [label="learning.jsonl",     shape=cylinder, fillcolor="#fcd34d"];
-    Fmis [label="mistakes.json",      shape=cylinder, fillcolor="#fcd34d"];
-    Fmem [label="memory.json",        shape=cylinder, fillcolor="#fcd34d"];
-    Fidx [label="memory.idx",         shape=cylinder, fillcolor="#fcd34d"];
-    Fskl [label="skills/<n>/SKILL.md",         shape=cylinder, fillcolor="#fcd34d"];
-    Fext [label="extrospection.json", shape=cylinder, fillcolor="#fcd34d"];
-    Fftn [label="finetune/*.jsonl",   shape=cylinder, fillcolor="#fcd34d"];
-    Fprf [label="preferences.jsonl", shape=cylinder, fillcolor="#fcd34d"];
-    Fpol [label="policy.json\npolicy_traj.jsonl", shape=cylinder, fillcolor="#fcd34d"];
-  }
-  {rank=same; Fmet; Flrn; Fmis; Fmem; Fidx; Fskl; Fext; Fftn; Fprf; Fpol}
-
-  /* L0 → L1 */
-  User -> Prompt   [label="task", color="#38bdf8", penwidth=2];
-  LLM  -> Dispatch [label="tool_calls", dir=both, color="#a78bfa", penwidth=2];
-  World-> Result   [style=invis];
-
-  /* L1 internal */
-  Prompt -> Router   [color="#a78bfa"];
-  Router -> Plan     [color="#a78bfa"];
-  Plan   -> TaskSum  [color="#a78bfa"];
-  TaskSum -> Dispatch [color="#a78bfa"];
-  Dispatch -> Escalate [label="turn_fails >= N", color="#fb7185", style=dashed];
-  Dispatch -> Result [color="#a78bfa"];
-  Escalate -> Result [style=invis];
-
-  /* L1 → L2 */
-  Dispatch -> Metrics  [label="record(engine:)", color="#34d399"];
-  Dispatch -> Policy   [label="observe_step", color="#34d399"];
-  Result   -> Learning [label="auto_introspect\n(deferred after reply)", color="#34d399"];
-  Result   -> Policy   [label="finish (judge)", color="#34d399"];
-  Dispatch -> Mistakes [label="on failure\nrecord()", color="#fb7185", penwidth=2];
-  User     -> Mistakes [label="\"that's wrong\"\ncheck_user_correction", color="#fb7185",
-                        style=dashed, constraint=false];
-  Dispatch -> Snapshot [label="probe", color="#f59e0b"];
-  Result   -> Observe  [label="auto_extrospect\n(AUTO_SECTIONS only)", color="#f59e0b"];
-  World    -> Snapshot [color="#fb7185", constraint=false];
-  World    -> Observe  [color="#fb7185", constraint=false];
-  World    -> Verify   [label="TransparentBrowser\n:headless", color="#38bdf8", constraint=false, penwidth=2];
-  World    -> RFTune   [label="GQRX remote\n:7356 + SDR", color="#fb7185", constraint=false, penwidth=2];
-  Dispatch -> Observe  [label="sense tools\nverify/watch/rf_tune/intel", color="#f59e0b", style=dashed, constraint=false];
-
-  /* L2 → L3 */
-  Metrics  -> Correlate [color="#34d399"];
-  Learning -> Correlate [color="#34d399"];
-  Learning -> Metrics [label="rsi_tick\nESR drop writes a lesson", style=dashed, color="#34d399", constraint=false];
-  Mistakes -> Correlate [color="#34d399"];
-  Snapshot -> Correlate [color="#f59e0b"];
-  Observe  -> Correlate [color="#f59e0b"];
-  Verify   -> Correlate [color="#f59e0b"];
-  RFTune   -> Correlate [color="#f59e0b"];
-
-  /* L3 → L4 */
-  Correlate -> Fmet [style=invis];
-  Metrics   -> Fmet [color="#94a3b8"];
-  Policy    -> Fpol [color="#94a3b8"];
-  Learning  -> Flrn [color="#94a3b8"];
-  Mistakes  -> Fmis [color="#94a3b8"];
-  Mistakes  -> Fmem [label="resolve→lesson", color="#94a3b8"];
-  Learning  -> Fmem [label="lesson", color="#94a3b8"];
-  Learning  -> Fskl [label="skill",  color="#94a3b8"];
-  Observe   -> Fext [color="#94a3b8"];
-  RFTune    -> Fext [label=":rf obs\nttl 300s", color="#94a3b8"];
-  Verify    -> Fmis [label=":refuted →\nassumption mistake", color="#fb7185", penwidth=2];
-  Verify    -> Mistakes [label=":refuted", color="#fb7185", style=dashed, constraint=false];
-  Verify    -> Fmem [label="mark stale\n[UNVERIFIED]", color="#a78bfa", style=dashed];
-  Verify    -> Fext [label=":confirmed\n:intel obs", color="#94a3b8"];
-  Learning -> Fftn [label="export_finetune", color="#94a3b8"];
-  Learning -> ReflectT [label="reflect()", color="#34d399", constraint=false];
-  ReflectT -> Fmem [label="frontier :lesson", color="#94a3b8"];
-  ReflectT -> LLM  [label="reflect_engine ≠ active", style=dashed, color="#a78bfa", constraint=false];
-  Result   -> Verify [label="fact_check_local_final\n(CVE / version claims)", color="#f59e0b", style=dashed, constraint=false];
-
-  /* feedback (dashed, non-constraining) */
-  Fmem -> Prompt [label="MEMORY block",  style=dashed, color="#fbbf24", constraint=false];
-  Fskl -> Prompt [label="SKILLS block",  style=dashed, color="#fbbf24", constraint=false];
-  Fmis -> Prompt [label="KNOWN MISTAKES\n+ KNOWN FIXES", style=dashed, color="#fb7185",
-                  constraint=false, penwidth=2];
-  Fext -> Prompt [label="EXTRO block",   style=dashed, color="#fbbf24", constraint=false];
-  Mistakes -> Dispatch [label="correction_hint\n(inline, next iter)", style=dashed,
-                        color="#fb7185", constraint=false, penwidth=2];
-  Correlate -> Prompt [label="findings → next run", style=dashed, color="#fb7185",
-                       constraint=false, penwidth=2];
-  Fidx -> Prompt [label="MemoryIndex\ncosine top-K", style=dashed, color="#fbbf24", constraint=false, penwidth=2];
-  Flrn -> Plan   [label="exemplars_for\n(few-shot, local)", style=dashed, color="#fbbf24", constraint=false];
-  Fmet -> Router [label="success_rate\n→ tie-break", style=dashed, color="#fbbf24", constraint=false];
-  Fpol -> Prompt [label="POLICY block", style=dashed, color="#fbbf24", constraint=false];
-  Fpol -> Router [label="Q-advantage\nvisits≥2", style=dashed, color="#fbbf24", constraint=false];
-  Escalate -> LLM [label="Swarm.ask(persona)\nfrontier hint", color="#a78bfa", constraint=false, penwidth=2, style=dashed];
-  Escalate -> Mistakes [label="record\n(tool:'escalation')", color="#fb7185", constraint=false, style=dashed];
-  Fftn -> LLM  [label="LoRA (weights)\ncron weekly", style=dashed, color="#fb7185", constraint=false, penwidth=2];
-  Result -> User [label="answer", color="#38bdf8", constraint=false, penwidth=2];
-  Result   -> Reward   [label="judge · prm", color="#34d399", penwidth=2];
-  Result   -> Curric   [label="critic · hindsight", color="#34d399"];
-  Dispatch -> Curric   [label="counterfactual\n[REPEATING]", color="#fb7185", style=dashed, constraint=false];
-  Reward   -> Verify   [label="verify_as_reward", style=dashed, color="#fbbf24", constraint=false];
-  Reward   -> Fprf     [label="record_preference", color="#94a3b8"];
-  Reward   -> Mistakes [label="sentinel gap", color="#fb7185", style=dashed, constraint=false];
-  Curric   -> Fprf     [label="(loser,winner)", color="#94a3b8"];
-  Curric   -> Fmis     [label="practice → resolve", color="#34d399", style=dashed];
-  Curric   -> Fftn     [label="train_and_gate", color="#94a3b8"];
-  User     -> Fprf     [label="user_correction\n→ DPO pair", color="#fb7185", style=dashed, constraint=false];
-  Fprf     -> LLM      [label="DPO (weights)\ncron weekly", style=dashed, color="#fb7185", constraint=false, penwidth=2];
-
+digraph PWN_Feedback {
+  graph [label="pwn-ai - evidence-backed feedback, not automatic improvement", labelloc=t,
+    fontsize=20, 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"];
+  Request [label="Original request + additive amendments", fillcolor="#7dd3fc"];
+  Host [label="Living off the land\nDetectOS native PATH inventory API\nHOST injects OS summary + PreflightChecker health", fillcolor="#6ee7b7"];
+  Prompt [label="PromptBuilder\nbudgeted memory / skills / lessons / mistakes / policy"];
+  Loop [label="Loop / request-owned runtime\nTaskSummarizer compass is UX, not acceptance"];
+  Tools [label="Registry -> Dispatch -> actual tools\npermissions / confirmation / sandbox"];
+  World [label="Extrospection\non-demand observe / intel / watch / verify / RF etc.\nauto baseline: host / repo / env only", fillcolor="#fcd34d"];
+  Evidence [label="Host receipts / exact-target stat + digest\nexecuted authored checks; failed/unknown stay distinct", shape=cylinder, fillcolor="#fcd34d"];
+  Final [label="Completion arbiter\nno tool calls != done; all original obligations apply"];
+  Reward [label="Reward + Learning\nclaimed_completion (judge claim)\nverified_completion / false_completion\nrate denominator: checked claims", fillcolor="#6ee7b7"];
+  Mistakes [label="Mistakes / Metrics / Reflect\nfailures, fixes and diagnostic lessons\ncorrelation is not causal proof", fillcolor="#6ee7b7"];
+  Policy [label="Policy accounting + advisory ranking\npositive training credit requires independent action attribution", fillcolor="#6ee7b7"];
+  Regression [label="Learning.regression_task\nexact failure/request digest + operator-authored expected bytes\ninert file/JSON recipe; split remains regression"];
+  Eval [label="Frozen local snapshot evaluation\nnew HOME / off + baseline + candidate\npublic held-out tasks; no live LLM gain claim"];
+  Promote [label="Operator approval + stopped writers + explicit target\nfresh replay / per-task + aggregate gates\nversioned receipt / digest-bound rollback"];
+  Skill [label="SkillReview default recommend\nauto-safe limited to proven additions to existing SOPs"];
+  Weights [label="Curriculum export / optional trainer path\nseparate from routing-policy promotion\nnot proof that a live adapter improved"];
+  Request -> Loop; Host -> Prompt; Prompt -> Loop; Loop -> Tools;
+  Tools -> Evidence; Tools -> World; World -> Prompt [style=dashed];
+  Evidence -> Final; Loop -> Final; Final -> Reward;
+  Tools -> Mistakes; World -> Mistakes [label="correlate", style=dashed];
+  Reward -> Policy; Reward -> Regression [label="persisted verifier failure"];
+  Regression -> Eval [label="regression replay only; never relabel held-out", style=dashed];
+  Policy -> Eval [label="explicit frozen snapshots"]; Eval -> Promote;
+  Promote -> Policy [label="explicit local replace / rollback", style=dashed];
+  Mistakes -> Prompt [style=dashed]; Reward -> Skill; Skill -> Prompt [style=dashed];
+  Reward -> Weights [label="explicit opt-in"]; Policy -> Prompt [style=dashed];
 }

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

@@ -17,7 +17,7 @@ digraph "PWN_REPL" {
     color="#6d28d9"; bgcolor="#2e1065"; penwidth=2;
     Prompt  [label="pwn[v0.5.x]:001 >>>", fillcolor="#c4b5fd"];
     Preload [label="autoload PWN::*\nBanner · MonkeyPatch", fillcolor="#c4b5fd"];
-    Hist    [label="~/.pwn_history\nreplay · edit", fillcolor="#c4b5fd"];
+    Hist    [label="~/.pwn/pwn_history\nreplay · edit", fillcolor="#c4b5fd"];
   }
   {rank=same; Prompt; Preload; Hist}
 

data/documentation/diagrams/dot/reinforcement-learning.dot

@@ -24,7 +24,7 @@ digraph "PWN_Reinforcement_Learning" {
     R3 [label="sentinel (ring N=40)\nproxy != judge != (1-corr)\nwarm + proxy distrust", fillcolor="#c4b5fd"];
     R4 [label="semantic_ok\ngrep exit 1 != failure", fillcolor="#c4b5fd"];
     R5 [label="Policy (live MDP)\nplan · complete · usable\nwarm Q + episode budget", fillcolor="#c4b5fd", penwidth=2];
-    E3 [label="verify_as_reward\nextro_verify caps/floors judge", fillcolor="#c4b5fd"];
+    E3 [label="verify_as_reward\nclaim diagnostics; refutation caps", fillcolor="#c4b5fd"];
   }
   {rank=same; R1; R2; R3; R4; R5; E3}
 
@@ -75,7 +75,7 @@ digraph "PWN_Reinforcement_Learning" {
   Loop -> R2   [label="session", color="#a78bfa"];
   Loop -> R3   [color="#a78bfa"];
   R1   -> E3   [label="ground", style=dashed, color="#fbbf24"];
-  R1   -> R5   [label="terminal", color="#a78bfa"];
+  R1 -> Claims [label="fallible judgment", color="#a78bfa"];
   R5   -> Fpol [color="#f59e0b"];
   Loop -> S4   [label="plan_first", color="#34d399"];
   Loop -> S3   [label="final", color="#34d399"];
@@ -89,13 +89,13 @@ digraph "PWN_Reinforcement_Learning" {
   S1 -> Fcur [color="#f59e0b"];
   S2 -> W1   [label="(loser,winner)", color="#fb7185"];
   S3 -> W1   [color="#fb7185"];
-  C3 -> Fses [label="success:true", color="#f59e0b"];
+  C3 -> Fses [label="success:soft", color="#f59e0b"];
 
   W1 -> Fprf [color="#f59e0b", penwidth=2];
   Fprf -> W2 [label="export_dpo", color="#f59e0b"];
   Fses -> W2 [label="export_finetune", color="#f59e0b"];
   W2 -> Fftn [color="#f59e0b"];
-  W2 -> Ollama [label="LoRA", color="#fb7185", penwidth=2];
+  W2 -> Ollama [label="optional configured trainer", color="#fb7185", penwidth=2];
   Fmis -> W2 [label="eval set", style=dashed, color="#fbbf24", constraint=false];
   W3 -> Loop [label="calibration", style=dashed, color="#fbbf24", constraint=false];
   Loop -> Rates [label="rsi_tick", color="#34d399", style=dashed, constraint=false];
@@ -104,12 +104,20 @@ digraph "PWN_Reinforcement_Learning" {
   Cron [label="⏱  PWN::Cron.install_defaults\npractice · offline_judge\ntrain dry_run · consolidate", fillcolor="#7dd3fc"];
   OJ [label="offline_judge\njudges + calibrate + warm sentinel", fillcolor="#6ee7b7"];
   MemGC [label="Learning.consolidate\nnightly memory GC", fillcolor="#6ee7b7"];
-  Cron -> S1 [label="0 3 * * *", color="#38bdf8", constraint=false];
-  Cron -> OJ [label="30 3 * * *", color="#38bdf8", constraint=false];
-  Cron -> W2 [label="0 4 * * 0", color="#38bdf8", constraint=false];
+  Cron -> S1 [label="OFF by default: 0 3 * * *", color="#38bdf8", constraint=false];
+  Cron -> OJ [label="OFF by default: 30 3 * * *", color="#38bdf8", constraint=false];
+  Cron -> W2 [label="OFF by default: 0 4 * * 0", color="#38bdf8", constraint=false];
   Cron -> MemGC [label="0 5 * * *", color="#38bdf8", constraint=false];
   OJ -> R1 [label="backfill", style=dashed, color="#a78bfa", constraint=false];
   OJ -> W3 [label="p(success)", style=dashed, color="#fbbf24", constraint=false];
 
   Ollama -> Loop [label="promoted vN+1\n(next session)", style=dashed, color="#fb7185", constraint=false, penwidth=2];
+
+  Checks [label="Host Verification\ncomplete pass / fail / unknown", fillcolor="#7dd3fc"];
+  Claims [label="Judge claim != verified completion\nfalse rate = refuted / checked claims", fillcolor="#fcd34d"];
+  Frozen [label="Explicit frozen PolicyEvaluation\npublic local held-out / two filesystem suites", fillcolor="#c4b5fd"];
+  Promotion [label="Fresh replay + per-task nonregression\noperator approval / stopped writers\nreceipt v1 + rollback refuses intervening writes", fillcolor="#6ee7b7"];
+  Loop -> Checks; Checks -> Claims; R1 -> Claims; Claims -> R5 [label="attributed eligible credit only"];
+  Fpol -> Frozen [label="snapshot, not live writes"]; Frozen -> Promotion;
+  Promotion -> Fpol [label="explicit target", style=dashed];
 }

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

@@ -42,11 +42,13 @@ digraph "PWN_Reports" {
   Fuzz  -> Rfuzz  [color="#f59e0b"];
   Uri   -> Ruri   [color="#f59e0b"];
   Phone -> Rphone [color="#f59e0b"];
-  Obs   -> Find   [label="handoff", color="#34d399"];
+  Obs   -> Find   [label="explicit structured record", color="#34d399"];
   Find  -> Gate   [label="verify transcript", color="#f59e0b"];
   Gate  -> HTML   [color="#a78bfa"];
   Rsast  -> HTML [color="#a78bfa"];
   Rfuzz  -> JSON [color="#a78bfa"];
-  Ruri   -> DD   [color="#a78bfa"];
-  Rphone -> Jira [color="#a78bfa"];
+  Ruri -> HTML [color="#a78bfa"];
+  JSON -> DD [label="explicit authenticated import", style=dashed];
+  Rphone -> HTML [color="#a78bfa"];
+  HTML -> Jira [label="operator delivery", style=dashed];
 }

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

@@ -1,6 +1,6 @@
 digraph "PWN_RE" {
   graph [
-    label=<<B>Reverse Engineering &amp; Binary Exploitation</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">pwn-asm · Assembly · XXD · FFI · Radare2 banners</FONT>>,
+    label=<<B>Reverse Engineering &amp; Binary Exploitation</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">pwn-asm · Assembly · XXD · REDB · Radare2 · GDBMI · ExploitDev</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
@@ -15,7 +15,7 @@ digraph "PWN_RE" {
   subgraph cluster_static {
     label="Static"; fontcolor="#a7f3d0"; style=rounded;
     color="#047857"; bgcolor="#022c22";
-    XXD  [label="Plugins::XXD\nhex dump / patch", fillcolor="#6ee7b7"];
+    XXD  [label="XXD · REDB · Radare2\nhex / binary analysis", fillcolor="#6ee7b7"];
     BDBA [label="BlackDuckBinaryAnalysis\nSBOM · CVE match", fillcolor="#6ee7b7"];
   }
   subgraph cluster_disasm {
@@ -27,7 +27,7 @@ digraph "PWN_RE" {
   subgraph cluster_dyn {
     label="Dynamic"; fontcolor="#fecaca"; style=rounded;
     color="#b91c1c"; bgcolor="#450a0a";
-    FFI  [label="PWN::FFI::Stdio\nnative calls",   fillcolor="#fda4af"];
+    FFI  [label="GDBMI · ProcessTube\ndebug / process I/O",   fillcolor="#fda4af"];
     Fuzz [label="Plugins::Fuzz\ntargeted crashes",  fillcolor="#fda4af"];
   }
   Xpl [label="Exploit PoC\nMetasploit module", fillcolor="#c4b5fd"];

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

@@ -1,6 +1,6 @@
 digraph "PWN_SDR" {
   graph [
-    label=<<B>PWN::SDR - Software-Defined Radio &amp; RF Hacking</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">GQRX · FlipperZero · RFIDler · FrequencyAllocation · Decoder::* (20+Base/DSP) · Base.run_iq (true-air) · FFI::{Volk,Liquid,FFTW,RTLSdr,HackRF,AdalmPluto,SoapySDR}</FONT>>,
+    label=<<B>PWN::SDR - Software-Defined Radio &amp; RF Hacking</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">GQRX · FlipperZero · RFIDler · FrequencyAllocation · Decoder::* (21+Base/DSP) · mode-specific input boundaries · FFI::{Volk,Liquid,FFTW,RTLSdr,HackRF,AdalmPluto,SoapySDR}</FONT>>,
     labelloc=t, fontsize=20, fontname="Helvetica",
     rankdir=LR, splines=spline, nodesep=0.45, ranksep=1.1,
     bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true
@@ -37,9 +37,9 @@ digraph "PWN_SDR" {
   subgraph cluster_dec {
     label="Decode · Sense · Record"; fontcolor="#ddd6fe"; style=rounded;
     color="#6d28d9"; bgcolor="#2e1065";
-    Base [label="Decoder::Base\nrun_iq (TRUE-AIR I/Q)\nrun_native (48 kHz UDP)\nrun_detector (energy)\nresolve_iq_source :auto", fillcolor="#c4b5fd", penwidth=2];
+    Base [label="Decoder::Base\nrun_iq (supported IQ modes)\nrun_native (48 kHz UDP)\nrun_detector (energy)\nresolve_iq_source :auto", fillcolor="#c4b5fd", penwidth=2];
     DSP  [label="Decoder::DSP\npure-Ruby + FFI accel\n(unpack · resample · FSK · FM)", fillcolor="#c4b5fd"];
-    Dec  [label="SDR::Decoder::*\nADSB · APT · BT · DECT · GPS\nGSM · Iridium · LoRa · LTE\nMorse · P25 · POCSAG/FLEX\nRDS · RFID · rtl_433 · RTTY\nWiFi · ZigBee", fillcolor="#c4b5fd"];
+    Dec  [label="SDR::Decoder::*\nADSB · APT · BT · DECT · GPS\nGSM · Iridium · LoRa · LTE\nMorse · P25 · POCSAG/FLEX\nRDS · RFID · rtl_433 · RTTY\nWiFi · ZigBee · Tempest", fillcolor="#c4b5fd"];
     Obs  [label="extro_observe\ncategory: :rf", fillcolor="#c4b5fd"];
     Xrf  [label="extro_snapshot :rf\nprobe_rf → hw inventory", fillcolor="#c4b5fd"];
     Tune [label="extro_rf_tune  📡\ntune · demod · strength\nRDS.sample → now_playing", fillcolor="#c4b5fd", penwidth=2];
@@ -63,8 +63,8 @@ digraph "PWN_SDR" {
   DSP  -> Dec  [color="#a78bfa"];
   Base -> Dec  [label="feed_iq / feed", color="#a78bfa", penwidth=2];
   Freq -> Dec  [color="#a78bfa"];
-  Flipper -> Freq [color="#f59e0b"];
-  RFID  -> Scan [color="#f59e0b"];
+  Flipper -> Obs [label="operator observation", color="#f59e0b"];
+  RFID -> Obs [label="operator observation", color="#f59e0b"];
   Freq  -> Scan [label="plan_bw/step", color="#f59e0b"];
   Scan  -> Obs  [color="#a78bfa"];
   Front -> Xrf  [style=dashed, color="#fbbf24", constraint=false];

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

@@ -30,7 +30,7 @@ digraph "PWN_SessionsCron" {
   }
   {rank=same; Reflect; Fire; Resume}
 
-  Next [label="Next pwn-ai session\ncontext restored", fillcolor="#7dd3fc"];
+  Next [label="Next pwn-ai session\nselected context / new prompt jobs", fillcolor="#7dd3fc"];
 
   Now -> Sess  [label="append", color="#f59e0b"];
   Now -> Cron  [label="cron_create", color="#f59e0b"];

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

@@ -23,16 +23,16 @@ digraph "PWN_Swarm" {
     Ask       [label="agent_ask\n1 turn → 1 persona",         fillcolor="#c4b5fd"];
     Debate    [label="agent_debate\nround-robin critique",    fillcolor="#c4b5fd"];
     Broadcast [label="agent_broadcast\nfan-out ensemble",     fillcolor="#c4b5fd"];
-    Escalate  [label="Loop.escalate\n(local stuck ≥N fails)\n→ frontier hint", fillcolor="#c4b5fd", penwidth=2];
+    Escalate  [label="Loop escalation (private)\n(local stuck ≥N fails)\n→ frontier hint", fillcolor="#c4b5fd", penwidth=2];
   }
   {rank=same; Spawn; Ask; Debate; Broadcast; Escalate}
 
   /* L2 ─ personas */
   subgraph cluster_personas {
-    label="Personas  (each = full PWN::AI::Agent::Loop)"; fontcolor="#a7f3d0";
+    label="Illustrative personas (each = nested Loop; not completion proof)"; fontcolor="#a7f3d0";
     style=rounded; color="#047857"; bgcolor="#022c22"; penwidth=2;
     Red   [label="🔴  red_team\nengine: grok\ntoolsets: terminal,pwn",     fillcolor="#6ee7b7"];
-    Blue  [label="🔵  blue_team\nengine: anthropic\ntoolsets: pwn,extro",  fillcolor="#6ee7b7"];
+    Blue  [label="🔵  blue_team\nengine: anthropic\ntoolsets: pwn,extrospection",  fillcolor="#6ee7b7"];
     Recon [label="🛰  recon\nengine: ollama\ntoolsets: terminal,memory",  fillcolor="#6ee7b7"];
     Xpl   [label="💥  exploit_dev\nengine: openai\ntoolsets: pwn,skills",  fillcolor="#6ee7b7"];
   }

data/documentation/diagrams/dot/task-summarizer.dot

@@ -1,6 +1,6 @@
 digraph "PWN_TaskSummarizer" {
   graph [
-    label=<<B>PWN::AI::Agent::TaskSummarizer - executive briefs</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">every request is a goal: emit_plan! then about_to then tools (no request type)</FONT>>,
+    label=<<B>PWN::AI::Agent::TaskSummarizer - executive briefs</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Task compass and UI only; request evidence governs completion</FONT>>,
     labelloc=t, fontsize=20, fontname="Helvetica",
     rankdir=TB, splines=spline, nodesep=0.55, ranksep=0.9,
     bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.6, newrank=true, compound=true
@@ -47,7 +47,7 @@ digraph "PWN_TaskSummarizer" {
     label="Execution (not on task row)"; fontcolor="#fde68a";
     style=rounded; color="#a16207"; bgcolor="#422006"; penwidth=2;
     Tools  [label="Dispatch tools\nshell · pwn_eval · CORE_TOOLS\nown REPL lines", fillcolor="#fcd34d"];
-    Rec    [label="record!\nadvance plan_idx\n(silent unless verbose)", fillcolor="#fcd34d"];
+    Rec    [label="record!\nevidence/phase-guided plan_idx\n(silent unless verbose)", fillcolor="#fcd34d"];
     Flush  [label="flush! / emit!\noptional closing brief", fillcolor="#fcd34d"];
   }
   {rank=same; Tools; Rec; Flush}

data/documentation/diagrams/dot/web-application-testing.dot

@@ -1,6 +1,6 @@
 digraph "PWN_Web" {
   graph [
-    label=<<B>Web Application Testing</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">TransparentBrowser → BurpSuite (preferred) → SAST → Reports</FONT>>,
+    label=<<B>Web Application Testing</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">Operator workflow: proxy evidence and separate source scans → reports</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
@@ -28,7 +28,7 @@ digraph "PWN_Web" {
   subgraph cluster_deep {
     label="Deep Analysis"; fontcolor="#ddd6fe"; style=rounded;
     color="#6d28d9"; bgcolor="#2e1065";
-    SAST [label="PWN::SAST\n48 rules on source",     fillcolor="#c4b5fd"];
+    SAST [label="PWN::SAST\n48 modules; source tree input",     fillcolor="#c4b5fd"];
     XSS  [label="pwn_xss_dom_vectors\nweb_cache_deception", fillcolor="#c4b5fd"];
     API  [label="Plugins::OpenAPI\nGraphQL introspection",  fillcolor="#c4b5fd"];
   }
@@ -40,7 +40,8 @@ digraph "PWN_Web" {
   TB     -> Burp   [label="proxy 127.0.0.1:8080", color="#f59e0b", penwidth=2];
   Spider -> Burp   [color="#f59e0b"];
   WWW    -> Zap    [color="#f59e0b"];
-  Burp   -> SAST   [color="#a78bfa"];
+  Source [label="Separately supplied source tree", fillcolor="#7dd3fc"];
+  Source -> SAST [color="#a78bfa"];
   Burp   -> XSS    [color="#a78bfa"];
   Zap    -> API    [color="#a78bfa"];
   SAST   -> Report [color="#38bdf8"];

data/documentation/diagrams/dot/zero-day-research-flow.dot

@@ -43,9 +43,10 @@ digraph "PWN_ZeroDay" {
   Surface -> AI   [color="#38bdf8"];
   SAST -> Obs [color="#f59e0b"];
   AI   -> Obs [color="#f59e0b"];
-  Obs  -> Ver [label="lead, not a finding", color="#f59e0b"];
-  Ver  -> Fuzz [color="#f59e0b"];
-  Ver  -> TB   [color="#f59e0b"];
+  Obs -> Fuzz [label="lead, not a finding", color="#f59e0b"];
+  Obs -> TB [label="lead", color="#f59e0b"];
+  Fuzz -> Ver [label="stored PoC", color="#f59e0b"];
+  TB -> Ver [label="reproduction", color="#f59e0b"];
   Fuzz -> Asm  [color="#fb7185"];
   TB   -> MSF  [color="#fb7185"];
   Asm  -> H1   [color="#a78bfa"];

data/documentation/diagrams/driver-framework.svg

@@ -10,7 +10,7 @@
 <title>PWN_Driver</title>
 <polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-397.2 684.45,-397.2 684.45,43.2 -43.2,43.2"/>
 <text xml:space="preserve" text-anchor="start" x="191.62" y="-332" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">Driver Anatomy &#45; bin/pwn_*</text>
-<text xml:space="preserve" text-anchor="start" x="169.5" y="-320.55" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">54 executables (pwn + 53 pwn_*) · thin CLI over PWN::Plugins</text>
+<text xml:space="preserve" text-anchor="start" x="120.75" y="-320.55" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">56 executables (pwn / pwn&#45;ai / pwn&#45;capd + 53 pwn_*) · thin CLI over PWN::Plugins</text>
 <g id="clust1" class="cluster">
 <title>cluster_d</title>
 <path fill="#022c22" stroke="#047857" d="M276,-8C276,-8 419,-8 419,-8 425,-8 431,-14 431,-20 431,-20 431,-223 431,-223 431,-229 425,-235 419,-235 419,-235 276,-235 276,-235 270,-235 264,-229 264,-223 264,-223 264,-20 264,-20 264,-14 270,-8 276,-8"/>