pwn 0.5.781 → 0.5.782

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be1437ab0b3260ca673ef36aa2c5d062008637493f6c0a02c0863e514fc3b199
-  data.tar.gz: 2c10c59ab8501a88b0e788034d8319e04a58d4322c2ed345f6cb88bf11e9e452
+  metadata.gz: 15a843d292cc4872961ee750110b60f259e14c1f50185522ee9a219f8dabf75d
+  data.tar.gz: 00c12b64346f6e35d8f6d44b638c1e9e0edb856390db76834fb72a65471d0ac7
 SHA512:
-  metadata.gz: 51827bef402328c9bfe195fac4a7542733b485651e4cfd6eb87203abf5ee0a7c83c1dd5837da133d1fdcb21e1582cc9f6867087f427293b6a4719de2efe0a857
-  data.tar.gz: a19aaf87f51bfaa1101918cd9c1526791d6953249ba992a51ebfe86db5a4eec8da79e348dc29263161f17d9754f108f53b5044d53c98a92719900668883a886f
+  metadata.gz: cb8ac9969959a5403b761a906497337852619dcbeef1c9f5a12956eb062963409426feaba0a188c3d10a278a422364c602fb30947ea28ef63b8f49d477e49b63
+  data.tar.gz: 0c79e7ce4c8f77974f25574bf309ce72e5b46ad40e562de334d653765b66f130959a65a157d567242f1756ed493a5e7c8d6febf435579ef1243ea969d8a57f9e

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

@@ -1,105 +1,50 @@
 digraph "PWN_Extrospection" {
   graph [
-    label=<<B>PWN::AI::Agent::Extrospection - On-demand sensing + ambient baseline</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">PRIMARY: intel · verify · watch · rf_tune · osint · serial · telecomm · packet · vision · voice · observe  ·  SECONDARY: snapshot/drift (AUTO_SECTIONS=host/repo/env)</FONT>>,
+    label=<<B>PWN::AI::Agent::Extrospection - On-demand sensing + ambient baseline</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">automatic host / repo / env only · other probes and actions are on demand · observations are not completion proof</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
+    rankdir=TB, splines=polyline, nodesep=0.45, ranksep=0.5,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.4, 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",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a",
+        fillcolor="#fcd34d", margin="0.22,0.16", width=3.8];
+  edge [fontname="Helvetica", fontsize=10, 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 (presence)\nnmap/git (safe --ver)\nburp/msf/gqrx PATH only", fillcolor="#fda4af"];
-    Repo  [label="repo · env\nHEAD · dirty · ruby/gem", fillcolor="#fda4af"];
-    RFhw  [label="rf  📡\nrtl-sdr · hackrf · flipper\ngqrx sock · serial devs", fillcolor="#fda4af"];
-    Web   [label="web  🌐\nanchors · targets\nrendered DOM · TLS cert", fillcolor="#fda4af"];
-    Feeds [label="intel feeds\nNVD · CIRCL · Exploit-DB", fillcolor="#fda4af"];
-    OSINT [label="osint  🕵️\nphone · FCC · patent\nIP/ASN · CT · person", fillcolor="#fda4af"];
-    Serial[label="serial  🔌\nttyUSB/ACM · by-id\nUART / AT modem", fillcolor="#fda4af"];
-    Telco [label="telecomm  ☎️\nBareSIP · SIP ports\nPSTN / VoIP", fillcolor="#fda4af"];
-    Pkt   [label="packet  📦\ntshark · tcpdump\npcap summarise", fillcolor="#fda4af"];
-    Vis   [label="vision  👁\ntesseract OCR\nzbar QR/barcode", fillcolor="#fda4af"];
-    Voice [label="voice  🔊\nespeak TTS · whisper STT\nsox / festival", fillcolor="#fda4af"];
+  subgraph cluster_auto {
+    label="AMBIENT BASELINE  ·  automatic scope"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Baseline [fillcolor="#7dd3fc", label="AUTO_SECTIONS = host / repo / env\nHost: OS / distribution / architecture\nRepository: HEAD / dirty state\nEnvironment: Ruby / gem information\nNo automatic network / RF / browser sensing"];
+    Snapshot [label="SNAPSHOT + DRIFT\nextro_snapshot: selected probes\nextro_drift: delta against prior baseline\nExplicit snapshots can request other sections\nToolchain inventory uses safe version checks\nor PATH presence; not general tool execution"];
+    Baseline -> Snapshot [label="auto_extrospect", color="#38bdf8"];
   }
-  {rank=same; Host; Net; Tool; Repo; RFhw; Web; Feeds; OSINT; Serial; Telco; Pkt; Vis; Voice}
 
-  /* col 0.5 ─ transport */
-  TB [label="PWN::Plugins::\nTransparentBrowser\n:headless (→ :rest fallback)",
-      fillcolor="#7dd3fc", penwidth=2];
-
-  /* col 1 ─ engine */
-  subgraph cluster_eng {
-    label="Extrospection Engine"; fontcolor="#fde68a"; style=rounded;
-    color="#a16207"; bgcolor="#422006"; penwidth=2;
-    Snap  [label="extro_snapshot\nprobe_host/net/toolchain/repo/env\nrf/web/osint/serial/telecomm\npacket/vision/voice\n(auto = host/repo/env only)", fillcolor="#fcd34d"];
-    Drift [label="extro_drift\ndelta vs baseline",     fillcolor="#fcd34d"];
-    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\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];
-    TelT  [label="extro_telecomm  ☎️\nBareSIP status/dial\ninventory SIP", fillcolor="#fcd34d", penwidth=2];
-    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\ncandidate correlations\nLearning + Mistakes + Memory", fillcolor="#fcd34d", penwidth=2];
+  subgraph cluster_web {
+    label="ON DEMAND  ·  web / public intelligence"; fontsize=12;
+    style="rounded,dashed,filled"; color="#94a3b8"; fillcolor="#1e293b";
+    Web [fillcolor="#6ee7b7", label="INDEPENDENT LOOKUPS / WATCHES\nextro_intel: NVD / CIRCL / Exploit-DB\nextro_osint: phone / FCC / patent / IP / person\nextro_watch: DOM hash / screenshot / TLS\nextro_verify: CVE / version / doc / generic\nWeb: TransparentBrowser headless → REST fallback"];
+    Verdict [label="RECORDING / HEURISTIC VERDICTS\nIntel records when record:true; watch stores web data\nVerify: confirmed / refuted / unknown\nWith commit: confirmed → intel; refuted → Mistakes\nrevalidate_memory: confident refutation marks\n:fact [UNVERIFIED date] + stale web observation"];
+    Web -> Verdict [label="selected operation"];
   }
-  {rank=same; Snap; Drift; Obs; Intel; Watch; Verify; RFTune; OsintT; SerT; TelT; PktT; VisT; VoxT; Corr}
-
-  /* col 2 ─ store + prompt + feedback sinks */
-  Store  [label="~/.pwn/\nextrospection.json", shape=cylinder, fillcolor="#fcd34d"];
-  Shots  [label="~/.pwn/extrospection/\nweb/*.png", shape=cylinder, fillcolor="#fcd34d"];
-  Prompt [label="EXTROSPECTION\nblock in system prompt", fillcolor="#c4b5fd"];
-  Mist   [label="Mistakes.record\n(tool:'assumption')\n→ KNOWN MISTAKES", fillcolor="#fca5a5", penwidth=2];
-  Mem    [label="PWN::Memory :fact\n[UNVERIFIED yyyy-mm-dd]\n(revalidate_memory)", fillcolor="#c4b5fd"];
-  {rank=same; Store; Shots; Prompt; Mist; Mem}
-
-  Host  -> Snap  [color="#fb7185"];
-  Net   -> Snap  [color="#fb7185"];
-  Tool  -> Drift [color="#fb7185"];
-  Repo  -> Drift [color="#fb7185"];
-  RFhw  -> Obs   [label="probe_rf", color="#fb7185"];
-  RFhw  -> RFTune[label="tune · RDS", color="#fb7185", penwidth=2];
-  Feeds -> Intel [color="#fb7185"];
 
-  Web   -> TB    [color="#fb7185"];
-  TB    -> Snap  [label="probe_web\n(opt-in)", color="#38bdf8"];
-  TB    -> Watch [label="goto · text\nscreenshot", color="#38bdf8"];
-  TB    -> Verify[label="render\ncanonical source", color="#38bdf8", penwidth=2];
+  subgraph cluster_sense {
+    label="ON DEMAND  ·  devices / media / observations"; fontsize=12;
+    style="rounded,dashed,filled"; color="#94a3b8"; fillcolor="#1e293b";
+    Sense [fillcolor="#6ee7b7", label="INDEPENDENT TOOLS / ACTIONS\nextro_rf_tune: GQRX / strength / RDS\nextro_serial: UART open / payload / drain\nextro_telecomm: BareSIP status / dial\nextro_packet: capture / pcap summary\nextro_vision: OCR / QR; extro_voice: TTS / STT"];
+    Observe [label="OBSERVATION BOUNDARY\nOn-demand calls use available plugins / hardware\nActions may affect devices or external services\nextro_observe records supplied observations\nCategories: recon / vuln / intel / target / network\nenv / RF / web / OSINT / serial / telecomm\npacket / vision / voice"];
+    Sense -> Observe [label="record operation results"];
+  }
+  {rank=same; Baseline; Web; Sense}
+  {rank=same; Snapshot; Verdict; Observe}
 
-  Snap  -> Store [color="#f59e0b"];
-  Drift -> Store [color="#f59e0b"];
-  Obs   -> Store [color="#f59e0b"];
-  Intel -> Store [label="record:true", color="#f59e0b"];
-  Watch -> Store [label="category::web", color="#f59e0b"];
-  Watch -> Shots [color="#f59e0b"];
-  RFTune-> Store [label="category::rf\nnow_playing", color="#f59e0b", penwidth=2];
-  OSINT -> OsintT[label="public APIs", color="#fb7185", penwidth=2];
-  Serial-> SerT  [label="UART I/O", color="#fb7185", penwidth=2];
-  Telco -> TelT  [label="SIP/HTTP", color="#fb7185", penwidth=2];
-  Pkt   -> PktT  [label="capture", color="#fb7185", penwidth=2];
-  Vis   -> VisT  [label="OCR", color="#fb7185", penwidth=2];
-  Voice -> VoxT  [label="TTS/STT", color="#fb7185", penwidth=2];
-  OsintT-> Store [label="category::osint", color="#f59e0b", penwidth=2];
-  SerT  -> Store [label="category::serial", color="#f59e0b"];
-  TelT  -> Store [label="category::telecomm", color="#f59e0b"];
-  PktT  -> Store [label="category::packet", color="#f59e0b"];
-  VisT  -> Store [label="category::vision", color="#f59e0b"];
-  VoxT  -> Store [label="category::voice", color="#f59e0b"];
-  Verify-> Mist  [label=":refuted", color="#fb7185", penwidth=2];
-  Verify-> Store [label=":confirmed\n:intel obs (ttl 30d)", color="#f59e0b"];
-  Verify-> Mem   [label="revalidate_memory\nmark stale :fact", color="#a78bfa", style=dashed];
-  Corr  -> Prompt[label="findings", color="#a78bfa", penwidth=2];
-  Store -> Prompt[label="inject", style=dashed, color="#fbbf24"];
-  Store -> Corr  [style=dashed, color="#fbbf24", constraint=false];
-  Mem   -> Corr  [label="rule (f)\nstale :fact", style=dashed, color="#a78bfa", constraint=false];
+  subgraph cluster_retention {
+    label="RETAINED WORLD MODEL  ·  not ground truth"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Store [label="~/.pwn/extrospection.json\nSnapshot + baseline / categorized observations\nWatch screenshots: ~/.pwn/extrospection/web/*.png\nPersistence depends on operation / options", width=5.2];
+    Context [fillcolor="#c4b5fd", label="extro_correlate: candidate correlations, not causal proof\nJoin world state with Metrics / Learning / Mistakes / Memory\nPromptBuilder: EXTROSPECTION when context is expanded\nBudgeted advisory context; recheck before relying on stale data", width=5.2];
+    Store -> Context [label="read retained state", style=dashed];
+  }
+  Snapshot -> Store [ltail=cluster_auto, lhead=cluster_retention, label="snapshot / delta", color="#f59e0b"];
+  Verdict -> Store [ltail=cluster_web, lhead=cluster_retention, label="recorded observations", color="#f59e0b"];
+  Observe -> Store [ltail=cluster_sense, lhead=cluster_retention, label="categorized results", color="#f59e0b"];
 }

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

@@ -1,108 +1,43 @@
 digraph "PWN_MemorySkills" {
   graph [
-    label=<<B>Persistent Knowledge - Memory · Skills · Learning · Mistakes · Policy · Sessions</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">everything under ~/.pwn/ that shapes future prompts</FONT>>,
+    label=<<B>Persistent Knowledge - Memory · Skills · Learning · Mistakes · Policy · Sessions</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">durable context · explicit maintenance / export · storage is not verified success</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
+    rankdir=TB, splines=polyline, nodesep=0.5, ranksep=0.48,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.4, 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",
+  node [fontname="Helvetica", fontsize=11, style="filled,rounded",
+        shape=box, penwidth=1.3, color="#334155", fontcolor="#0f172a",
+        fillcolor="#c4b5fd", margin="0.22,0.16", width=5.0];
+  edge [fontname="Helvetica", fontsize=10, 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 · 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(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_episode / observe_step / finish\neligible attributed credit only", fillcolor="#6ee7b7"];
+  // Store families replace one arrow per read/write API. Maintenance cards
+  // are independent operations, not a chain invoked for every memory write.
+  subgraph cluster_context {
+    label="CONTEXT LIFECYCLE  ·  read top to bottom"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Write [fillcolor="#6ee7b7", label="1  RECORD THROUGH THE OWNING API\nMemory: memory_remember / lean\nSkills: skill_create / skill_add_reference\nLearning: note_outcome / reflect; Mistakes: record / resolve\nSessions: transcript append; Policy: episode accounting"];
+    Stores [fillcolor="#fcd34d", label="2  RETAIN UNDER ~/.pwn/\nmemory.json: facts / preferences / lessons / environment\nmemory.idx: embedding index (incremental re-embed)\nskills/<n>/SKILL.md + references; default skill seeds\nlearning.jsonl + mistakes.json + sessions/*.jsonl\npolicy.json + policy_traj.jsonl; extrospection.json"];
+    Read [label="3  SELECT RELEVANT CONTEXT\nMemory.recall / MemoryIndex.recall_semantic\nSkills list / view; Learning outcomes / stats\nSessions view / current; Mistakes list / correction_hint\nPolicy stats / evaluate / recommend: advisory only"];
+    Prompt [fillcolor="#7dd3fc", label="4  PromptBuilder.build(request:)\nEngine-aware budget; relevance-ranked memory\nRecent turns + skills + learning + known mistakes / fixes\nExpanded / stuck context: metrics + policy + extrospection\nThin mode omits full memory / harness blocks"];
+    Reuse [fillcolor="#7dd3fc", label="5  INFORM THE NEXT TURN\nSelected context, not a dump of every stored file\nLearning.exemplars_for: local-only few-shot traces\nStored lessons / judge claims are not host verification\nPositive policy credit needs independent action attribution"];
+    Write -> Stores [color="#f59e0b"];
+    Stores -> Read -> Prompt -> Reuse;
   }
-  {rank=same; Rem; Skc; Note; Dist; Mrec; Xft; Rdpo; PolW}
 
-  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"];
-    Fidx [label="memory.idx\nembedding index\n(sha → vec)", shape=cylinder, fillcolor="#fcd34d"];
-    Fskl [label="skills/<n>/SKILL.md\nYAML front-matter + refs\n(+ etc/default_skills seed)", shape=cylinder, fillcolor="#fcd34d"];
-    Flrn [label="learning.jsonl\noutcome log",               shape=cylinder, fillcolor="#fcd34d"];
-    Fses [label="sessions/*.jsonl\ntranscripts (+ lean)",      shape=cylinder, fillcolor="#fcd34d"];
-    Fmis [label="mistakes.json\nsig → count · fix · regressed", shape=cylinder, fillcolor="#fcd34d"];
-    Fext [label="extrospection.json\nsnapshot · rf · web · obs", shape=cylinder, fillcolor="#fcd34d"];
-    Fftn [label="finetune/*.jsonl\nShareGPT / OpenAI / DPO", shape=cylinder, fillcolor="#fcd34d"];
-    Fprf [label="preferences.jsonl\nDPO (prompt,rejected,chosen)", shape=cylinder, fillcolor="#fcd34d"];
-    Fpol [label="policy.json + policy_traj.jsonl\nQ table · REINFORCE · MDP log", shape=cylinder, fillcolor="#fcd34d"];
+  subgraph cluster_operations {
+    label="MAINTENANCE / EXPORT  ·  independently invoked"; fontsize=12;
+    style="rounded,dashed,filled"; color="#94a3b8"; fillcolor="#1e293b";
+    Skill [fillcolor="#6ee7b7", label="SKILL MAINTENANCE\nlearning_distill_skill: explicit reviewed session distillation\nSkillReview: recommend by default\nauto-safe: small proven append to existing non-pwn/ SOP\nNot automatic skill creation after routine success"];
+    Reflect [label="REFLECTION + CORRECTIONS\nReflect.on: teacher reads transcript → memory :lesson\nMistakes.resolve: correction → memory lesson\nResolution can also record a preference pair\nRetain source provenance; do not treat prose as proof"];
+    Revalidate [label="WORLD-FACT REVALIDATION\nExtrospection.revalidate_memory (cron / explicit)\nSelect :fact entries containing CVE / version / URL\nRefuted with confidence ≥ 0.6 → [UNVERIFIED date]\nRecord stale web observation in extrospection.json"];
+    Export [fillcolor="#fcd34d", label="DATASET EXPORT\nLearning.export_finetune: eligible verified outcomes\n+ session traces → ShareGPT / OpenAI datasets\nReward.record_preference → preferences.jsonl\nReward.export_dpo → finetune/*.jsonl\nExport does not train or promote a model"];
+    Context [fillcolor="#1e293b", fontcolor="#cbd5e1", style="rounded,dashed,filled",
+      label="READ / WRITE BOUNDARY\nThese operations read selected retained sources\nand write only their corresponding stores / artifacts.\nThey are not prerequisites for PromptBuilder.\nFrozen policy evaluation / promotion is a separate workflow."];
   }
-  {rank=same; Fmem; Fidx; Fskl; Flrn; Fses; Fmis; Fext; Fftn; Fprf; Fpol}
-
-  subgraph cluster_read {
-    label="Read-Side / Injection"; fontcolor="#ddd6fe"; style=rounded;
-    color="#6d28d9"; bgcolor="#2e1065";
-    Rec  [label="memory_recall",       fillcolor="#c4b5fd"];
-    Midx [label="MemoryIndex\nrecall_semantic\n(cosine top-K)",   fillcolor="#c4b5fd", penwidth=2];
-    Skv  [label="skill_list · view",   fillcolor="#c4b5fd"];
-    Out  [label="learning_outcomes\nlearning_stats", fillcolor="#c4b5fd"];
-    Sesv [label="sessions_view\nsessions_current",   fillcolor="#c4b5fd"];
-    Mlst [label="mistakes_list\ncorrection_hint",    fillcolor="#c4b5fd"];
-    Exem [label="Learning.exemplars_for\n(few-shot trace)",   fillcolor="#c4b5fd"];
-    PolR [label="policy_stats · evaluate\npolicy_recommend",   fillcolor="#c4b5fd"];
-  }
-  {rank=same; Rec; Midx; Skv; Out; Sesv; Mlst; Exem; PolR}
-
-  Prompt [label="PromptBuilder.build(request:)\nengine-aware .budget\nMEMORY (relevance-ranked) + SKILLS\n+ LEARNING + KNOWN MISTAKES/FIXES\n+ METRICS (per-engine) + POLICY + EXTRO", 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"];
-  Mrec -> Fmis [color="#f59e0b"];
-  Mrec -> Fmem [label="resolve→lesson", style=dashed, color="#fbbf24"];
-
-  Fmem -> Rec  [color="#a78bfa"];
-  Fskl -> Skv  [color="#a78bfa"];
-  Flrn -> Out  [color="#a78bfa"];
-  Fses -> Sesv [color="#a78bfa"];
-  Fmis -> Mlst [color="#a78bfa"];
-
-  Rec  -> Prompt [color="#38bdf8"];
-  Skv  -> Prompt [color="#38bdf8"];
-  Out  -> Prompt [color="#38bdf8"];
-  Sesv -> Prompt [color="#38bdf8"];
-  Mlst -> Prompt [label="do NOT repeat", color="#fb7185", penwidth=2];
-
-  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="eligible verified outcomes"];
-  
-  Fidx -> Midx [color="#a78bfa"];
-  Fmem -> Midx [style=dashed, color="#a78bfa"];
-  Flrn -> Exem [color="#a78bfa"];
-  Fses -> Exem [style=dashed, color="#a78bfa"];
-  
-  Midx -> Prompt [label="MEMORY block\n(top-K by cosine)", color="#38bdf8", penwidth=2];
-  Exem -> Prompt [label="few-shot msgs\n(local only)", color="#38bdf8"];
-
-  ReVal [label="Extrospection.verify\nrevalidate_memory (cron)\nbrowser-backed GC", fillcolor="#fcd34d"];
-  ReVal -> Fmem [label="[UNVERIFIED yyyy-mm-dd]\nprefix stale :fact", color="#fb7185", style=dashed, penwidth=2];
-  ReVal -> Fext [label=":confirmed → :intel obs\n:refuted → observe stale", color="#f59e0b", style=dashed];
-  Fmem  -> ReVal [label=":fact w/ CVE|ver|URL", style=dashed, color="#94a3b8", constraint=false];
-  
-  Teach [label="Reflect.on\n(engine: reflect_engine)\nteacher-student", fillcolor="#fda4af", penwidth=2];
-  Fses  -> Teach [label="transcript", style=dashed, color="#94a3b8", constraint=false];
-  Teach -> Fmem  [label="frontier-authored\n:lesson", color="#fb7185", penwidth=2];
-
-  PolW -> Fpol [color="#f59e0b"];
-  Fpol -> PolR [color="#a78bfa"];
-  PolR -> Prompt [label="POLICY block\nadvisory only", color="#38bdf8"];
-  Rdpo -> Fprf [color="#f59e0b"];
-  Mrec -> Fprf [label="resolve → pair", style=dashed, color="#fbbf24"];
-  Fprf -> Fftn [label="export_dpo", style=dashed, color="#fbbf24", constraint=false];
-
+  {rank=same; Write; Skill}
+  {rank=same; Stores; Reflect}
+  {rank=same; Read; Revalidate}
+  {rank=same; Prompt; Export}
+  {rank=same; Reuse; Context}
 }

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

@@ -1,34 +1,56 @@
 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];
+  graph [
+    label=<<B>PWN - Overall Architecture</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">runtime ownership · evidence flow · verified outcomes</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=polyline, nodesep=0.5, ranksep=0.48,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.4, newrank=true, compound=true
+  ];
+  node [fontname="Helvetica", fontsize=11, shape=box, style="filled,rounded",
+        fillcolor="#c4b5fd", penwidth=1.3, color="#334155", fontcolor="#0f172a", margin="0.22,0.16"];
+  edge [fontname="Helvetica", fontsize=10, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  // Ownership map, not a complete call graph. Internal repetition is summarized
+  // inside Runtime; shared state and asynchronous work are not return arrows.
+  subgraph cluster_entry {
+    label="01  ACCESS  ·  operator / CI"; labelloc=t; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Entry [fillcolor="#7dd3fc", width=5.1,
+      label="pwn / pwn-ai  ·  REPL, curses and headless CLI\npwn-mesh: received @ai + private channel + whitelist\nCron: asynchronous prompt jobs; curriculum opt-in"];
+  }
+  subgraph cluster_control {
+    label="02  CONTROL  ·  request-owned agent runtime"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Runtime [width=5.1,
+      label="RequestRuntime + Loop\nOwn objective, additive steering and checkpoints\nPromptBuilder + Registry: context and available tools\nRepeat tool / observation turns; optional Swarm / Solve"];
+  }
+  subgraph cluster_execution {
+    label="03  EXECUTION  ·  host-owned tools"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Execute [fillcolor="#6ee7b7", width=5.1,
+      label="Dispatch + ToolGuard + confirmation + sandbox\nPlugins / SAST / AWS / WWW / SDR / Blockchain / Reports\nShell, Ruby and MCP integrations\nDirect REPL / driver calls can also use these capabilities"];
+  }
+  subgraph cluster_evidence {
+    label="04  ACCEPTANCE  ·  evidence, not model prose"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Accept [width=5.1,
+      label="Host observations + exact-target artifact receipts\nFinalization arbiter + Verification: all obligations\nParent rechecks child artifacts; authored checks / current bytes\nRelease verified, failed, or unknown / incomplete result"];
+  }
+  subgraph cluster_state {
+    label="05  RETENTION  ·  durable evidence and advisory context"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    State [fillcolor="#fcd34d", width=5.1,
+      label="Sessions / Learning / Mistakes / Metrics / Policy\nDefault ~/.pwn stores; explicit artifacts may live elsewhere\nLater PromptBuilder reads memory, skills, lessons and policy\nCron hygiene is asynchronous; improvement is not automatic"];
+  }
+  Provider [fillcolor="#fda4af", label="MODEL BOUNDARY\nConfigured provider adapter\nRequest-local routing and retries\nModel output is not host evidence"];
+  Target [fillcolor="#fda4af", label="WORLD BOUNDARY\nExternal services / targets / hardware\nLive behavior needs separate validation\nRadio submission is not RF delivery"];
+
+  {rank=same; Runtime; Provider}
+  {rank=same; Execute; Target}
+  Entry -> Runtime [ltail=cluster_entry, lhead=cluster_control, label="agent requests", color="#38bdf8", weight=10];
+  Runtime -> Execute [ltail=cluster_control, lhead=cluster_execution, label="selected tool calls", color="#38bdf8", weight=10];
+  Execute -> Accept [ltail=cluster_execution, lhead=cluster_evidence, label="observed results / receipts", color="#38bdf8", weight=10];
+  Accept -> State [ltail=cluster_evidence, lhead=cluster_state, label="record outcomes and evidence", weight=10];
+  Runtime -> Provider [dir=both, label="context / proposals", constraint=false];
+  Execute -> Target [dir=both, label="as required", style=dashed, constraint=false];
 }

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

@@ -1,32 +1,55 @@
 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];
+  graph [
+    label=<<B>PWN::AI::Agent - Feedback + Learning Loop</B><BR/><FONT POINT-SIZE="11" COLOR="#94a3b8">evidence-backed feedback · not automatic improvement</FONT>>,
+    labelloc=t, fontsize=20, fontname="Helvetica",
+    rankdir=TB, splines=polyline, nodesep=0.55, ranksep=0.42,
+    bgcolor="#0f172a", fontcolor="#e2e8f0", pad=0.4, newrank=true
+  ];
+  node [fontname="Helvetica", fontsize=11, shape=box, style="filled,rounded",
+        fillcolor="#c4b5fd", penwidth=1.3, color="#334155", fontcolor="#0f172a", margin="0.22,0.16", width=4.6];
+  edge [fontname="Helvetica", fontsize=10, color="#94a3b8",
+        fontcolor="#cbd5e1", penwidth=1.3, arrowsize=0.8];
+
+  // Two independently initiated lifecycles. The evaluation lane reads explicitly
+  // selected frozen state, not a live automatic handoff from every request.
+  subgraph cluster_turn {
+    label="REQUEST LIFECYCLE  ·  read top to bottom"; fontsize=12;
+    style="rounded,filled"; color="#334155"; fillcolor="#1e293b";
+    Prepare [fillcolor="#7dd3fc", label="1  PREPARE\nOriginal request + additive amendments\nPromptBuilder: recalled memory / skills / lessons / policy\nHOST: DetectOS summary + PreflightChecker"];
+    Execute [label="2  ACT + OBSERVE\nLoop + Registry + Dispatch: repeat tool / observation turns\nPermissions, confirmation and sandbox\nExtrospection on demand; auto baseline: host / repo / env"];
+    Verify [fillcolor="#fcd34d", label="3  CHECK THE EVIDENCE\nHost receipts + exact-target bytes / digests\nAuthored checks + complete original obligation coverage\nCompletion arbiter: verified / failed / unknown"];
+    Account [fillcolor="#6ee7b7", label="4  RECORD FEEDBACK\nReward + Learning: judge claim != verified completion\nFalse-completion rate uses checked claims\nMistakes / Metrics / Reflect: diagnostic lessons"];
+    Retain [fillcolor="#fcd34d", label="5  RETAIN ADVISORY CONTEXT\nPolicy accounting + ranking: positive training credit\nrequires independent action attribution\nSkillReview: recommend by default; limited auto-safe SOP edits"];
+    Reuse [fillcolor="#7dd3fc", label="6  INFORM A LATER TURN\nPromptBuilder recalls retained context as budget permits\nThis closes the context loop, not a proof of improvement\nTaskSummarizer compass is UX, never acceptance"];
+    Prepare -> Execute [color="#38bdf8"];
+    Execute -> Verify [label="host evidence boundary", color="#38bdf8"];
+    Verify -> Account [label="preserve failed / unknown", color="#38bdf8"];
+    Account -> Retain;
+    Retain -> Reuse [label="later context read", style=dashed];
+  }
+
+  subgraph cluster_evaluation {
+    label="EVALUATION / PROMOTION  ·  explicit operator workflow"; fontsize=12;
+    style="rounded,dashed,filled"; color="#94a3b8"; fillcolor="#1e293b";
+    Select [label="A  SELECT FROZEN INPUTS\nExplicit baseline + candidate policy snapshots\nRead recorded policy state, not live online writers\nNo automatic handoff from the request lifecycle"];
+    Regression [label="B  KEEP EVALUATION SPLITS SEPARATE\nOptional Learning.regression_task: persisted verifier failure\nExact request digest + operator-authored file / JSON gold\nInert regression recipe; never relabel as held-out"];
+    Evaluate [label="C  EVALUATE LOCALLY\nPolicyEvaluation: disposable HOME + frozen bytes\nOff / baseline / candidate; public fixed held-out tasks\nRegression replay stays separate from held-out evidence"];
+    Promote [fillcolor="#6ee7b7", label="D  GATE + EXPLICITLY PROMOTE\nFresh replay; per-task + aggregate nonregression\nHeld-out gain; both filesystem environments\nApproval + stopped writers + explicit live policy target"];
+    Receipt [fillcolor="#fcd34d", label="E  VERSION + RETAIN ROLLBACK EVIDENCE\nRouting-policy replacement only; versioned receipt\nDigest-bound rollback refuses intervening live writes\nNo claim of general live LLM improvement"];
+    Select -> Regression;
+    Regression -> Evaluate [label="reviewed inputs; distinct splits"];
+    Evaluate -> Promote [label="acceptance gates", style=dashed];
+    Promote -> Receipt [label="only after approval and passing gates"];
+  }
+
+  // Alignment only: no fabricated flow between independently initiated lanes.
+  {rank=same; Prepare; Select}
+  {rank=same; Execute; Regression}
+  {rank=same; Verify; Evaluate}
+  {rank=same; Account; Promote}
+  {rank=same; Retain; Receipt}
+
+  Trainer [fillcolor="#1e293b", fontcolor="#cbd5e1", style="rounded,dashed,filled",
+    label="SEPARATE OPTIONAL WEIGHT PATH\nCurriculum export / configured trainer is opt-in\nNot routing-policy promotion or proof of adapter gains\nScheduled curriculum jobs are disabled by default"];
+  {rank=same; Reuse; Trainer}
 }