pwn 0.5.617 → 0.5.620

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

@@ -0,0 +1,166 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: PWN_SDR Pages: 1 -->
+<svg width="917pt" height="599pt"
+ viewBox="0.00 0.00 917.00 599.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(43.2 556.2)">
+<title>PWN_SDR</title>
+<polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-556.2 873.45,-556.2 873.45,43.2 -43.2,43.2"/>
+<text xml:space="preserve" text-anchor="start" x="169.88" y="-491" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">PWN::SDR — Software&#45;Defined Radio &amp; RF Hacking</text>
+<text xml:space="preserve" text-anchor="start" x="197.62" y="-479.55" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">GQRX · FlipperZero · RFIDler · SonMicro · FrequencyAllocation · Decoder::* (20 protocols)</text>
+<g id="clust1" class="cluster">
+<title>cluster_hw</title>
+<path fill="#022c22" stroke="#047857" d="M228.5,-239C228.5,-239 346,-239 346,-239 352,-239 358,-245 358,-251 358,-251 358,-446 358,-446 358,-452 352,-458 346,-458 346,-458 228.5,-458 228.5,-458 222.5,-458 216.5,-452 216.5,-446 216.5,-446 216.5,-251 216.5,-251 216.5,-245 222.5,-239 228.5,-239"/>
+<text xml:space="preserve" text-anchor="middle" x="287.25" y="-435" font-family="sans-Serif" font-size="20.00" fill="#a7f3d0">Hardware</text>
+</g>
+<g id="clust2" class="cluster">
+<title>cluster_ctrl</title>
+<path fill="#422006" stroke="#a16207" d="M440,-219C440,-219 564.25,-219 564.25,-219 570.25,-219 576.25,-225 576.25,-231 576.25,-231 576.25,-454 576.25,-454 576.25,-460 570.25,-466 564.25,-466 564.25,-466 440,-466 440,-466 434,-466 428,-460 428,-454 428,-454 428,-231 428,-231 428,-225 434,-219 440,-219"/>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-443" font-family="sans-Serif" font-size="20.00" fill="#fde68a">Control · Scan</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster_dec</title>
+<path fill="#2e1065" stroke="#6d28d9" d="M20,-8C20,-8 810.25,-8 810.25,-8 816.25,-8 822.25,-14 822.25,-20 822.25,-20 822.25,-199 822.25,-199 822.25,-205 816.25,-211 810.25,-211 810.25,-211 20,-211 20,-211 14,-211 8,-205 8,-199 8,-199 8,-20 8,-20 8,-14 14,-8 20,-8"/>
+<text xml:space="preserve" text-anchor="middle" x="415.12" y="-188" font-family="sans-Serif" font-size="20.00" fill="#ddd6fe">Decode · Record</text>
+</g>
+<!-- RF -->
+<g id="node1" class="node">
+<title>RF</title>
+<path fill="#fda4af" stroke="#334155" stroke-width="1.3" d="M111.88,-351C111.88,-351 42.62,-351 42.62,-351 36.62,-351 30.62,-345 30.62,-339 30.62,-339 30.62,-327 30.62,-327 30.62,-321 36.62,-315 42.62,-315 42.62,-315 111.88,-315 111.88,-315 117.88,-315 123.88,-321 123.88,-327 123.88,-327 123.88,-339 123.88,-339 123.88,-345 117.88,-351 111.88,-351"/>
+<text xml:space="preserve" text-anchor="middle" x="77.25" y="-329.88" font-family="sans-Serif" font-size="10.00" fill="#0f172a">📡 &#160;RF Spectrum</text>
+</g>
+<!-- SDRhw -->
+<g id="node2" class="node">
+<title>SDRhw</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.3" d="M338,-283C338,-283 236.5,-283 236.5,-283 230.5,-283 224.5,-277 224.5,-271 224.5,-271 224.5,-259 224.5,-259 224.5,-253 230.5,-247 236.5,-247 236.5,-247 338,-247 338,-247 344,-247 350,-253 350,-259 350,-259 350,-271 350,-271 350,-277 344,-283 338,-283"/>
+<text xml:space="preserve" text-anchor="middle" x="287.25" y="-267.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">RTL&#45;SDR / HackRF</text>
+<text xml:space="preserve" text-anchor="middle" x="287.25" y="-255.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">(via GQRX / SoapySDR)</text>
+</g>
+<!-- RF&#45;&gt;SDRhw -->
+<g id="edge1" class="edge">
+<title>RF&#45;&gt;SDRhw</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M124.41,-317.91C152.63,-308.69 189.17,-296.74 220.38,-286.53"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="220.86,-289.32 227.59,-284.18 219.12,-284 220.86,-289.32"/>
+</g>
+<!-- Flipper -->
+<g id="node3" class="node">
+<title>Flipper</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.3" d="M321.5,-351C321.5,-351 253,-351 253,-351 247,-351 241,-345 241,-339 241,-339 241,-327 241,-327 241,-321 247,-315 253,-315 253,-315 321.5,-315 321.5,-315 327.5,-315 333.5,-321 333.5,-327 333.5,-327 333.5,-339 333.5,-339 333.5,-345 327.5,-351 321.5,-351"/>
+<text xml:space="preserve" text-anchor="middle" x="287.25" y="-329.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SDR::FlipperZero</text>
+</g>
+<!-- RF&#45;&gt;Flipper -->
+<g id="edge2" class="edge">
+<title>RF&#45;&gt;Flipper</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M124.41,-333C155.89,-333 197.74,-333 231,-333"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="230.61,-335.8 238.61,-333 230.61,-330.2 230.61,-335.8"/>
+</g>
+<!-- RFID -->
+<g id="node4" class="node">
+<title>RFID</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.3" d="M315.88,-419C315.88,-419 258.62,-419 258.62,-419 252.62,-419 246.62,-413 246.62,-407 246.62,-407 246.62,-395 246.62,-395 246.62,-389 252.62,-383 258.62,-383 258.62,-383 315.88,-383 315.88,-383 321.88,-383 327.88,-389 327.88,-395 327.88,-395 327.88,-407 327.88,-407 327.88,-413 321.88,-419 315.88,-419"/>
+<text xml:space="preserve" text-anchor="middle" x="287.25" y="-403.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SDR::RFIDler</text>
+<text xml:space="preserve" text-anchor="middle" x="287.25" y="-391.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SonMicroRFID</text>
+</g>
+<!-- RF&#45;&gt;RFID -->
+<g id="edge3" class="edge">
+<title>RF&#45;&gt;RFID</title>
+<path fill="none" stroke="#fb7185" stroke-width="1.3" d="M124.27,-348.51C151.14,-357.52 185.7,-369.02 216.5,-379 223.06,-381.13 229.98,-383.34 236.8,-385.51"/>
+<polygon fill="#fb7185" stroke="#fb7185" stroke-width="1.3" points="235.66,-388.09 244.14,-387.83 237.36,-382.75 235.66,-388.09"/>
+</g>
+<!-- GQRX -->
+<g id="node5" class="node">
+<title>GQRX</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M548.75,-283C548.75,-283 455.5,-283 455.5,-283 449.5,-283 443.5,-277 443.5,-271 443.5,-271 443.5,-239 443.5,-239 443.5,-233 449.5,-227 455.5,-227 455.5,-227 548.75,-227 548.75,-227 554.75,-227 560.75,-233 560.75,-239 560.75,-239 560.75,-271 560.75,-271 560.75,-277 554.75,-283 548.75,-283"/>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-269.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SDR::GQRX</text>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-257.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">remote control</text>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-245.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">spectrum snapshot</text>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-233.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">(median floor · DC null)</text>
+</g>
+<!-- SDRhw&#45;&gt;GQRX -->
+<g id="edge4" class="edge">
+<title>SDRhw&#45;&gt;GQRX</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M350.39,-262.08C376.41,-260.86 406.72,-259.43 433.31,-258.19"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="433.09,-261 440.95,-257.83 432.83,-255.41 433.09,-261"/>
+</g>
+<!-- Xrf -->
+<g id="node10" class="node">
+<title>Xrf</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M126.5,-112C126.5,-112 28,-112 28,-112 22,-112 16,-106 16,-100 16,-100 16,-88 16,-88 16,-82 22,-76 28,-76 28,-76 126.5,-76 126.5,-76 132.5,-76 138.5,-82 138.5,-88 138.5,-88 138.5,-100 138.5,-100 138.5,-106 132.5,-112 126.5,-112"/>
+<text xml:space="preserve" text-anchor="middle" x="77.25" y="-96.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">extro_snapshot :rf</text>
+<text xml:space="preserve" text-anchor="middle" x="77.25" y="-84.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">probe_rf → hw inventory</text>
+</g>
+<!-- SDRhw&#45;&gt;Xrf -->
+<g id="edge10" class="edge">
+<title>SDRhw&#45;&gt;Xrf</title>
+<path fill="none" stroke="#fbbf24" stroke-width="1.3" stroke-dasharray="5,2" d="M223.87,-247.2C221.33,-245.89 218.86,-244.49 216.5,-243 164.82,-210.3 119.75,-153.58 96.03,-120.36"/>
+<polygon fill="#fbbf24" stroke="#fbbf24" stroke-width="1.3" points="98.49,-118.99 91.6,-114.05 93.91,-122.21 98.49,-118.99"/>
+</g>
+<!-- Freq -->
+<g id="node6" class="node">
+<title>Freq</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M556.25,-351C556.25,-351 448,-351 448,-351 442,-351 436,-345 436,-339 436,-339 436,-327 436,-327 436,-321 442,-315 448,-315 448,-315 556.25,-315 556.25,-315 562.25,-315 568.25,-321 568.25,-327 568.25,-327 568.25,-339 568.25,-339 568.25,-345 562.25,-351 556.25,-351"/>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-335.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SDR::FrequencyAllocation</text>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-323.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">band lookup</text>
+</g>
+<!-- Flipper&#45;&gt;Freq -->
+<g id="edge5" class="edge">
+<title>Flipper&#45;&gt;Freq</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M333.92,-333C360.7,-333 395.22,-333 425.92,-333"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="425.77,-335.8 433.77,-333 425.77,-330.2 425.77,-335.8"/>
+</g>
+<!-- Scan -->
+<g id="node7" class="node">
+<title>Scan</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.3" d="M546.88,-427C546.88,-427 457.38,-427 457.38,-427 451.38,-427 445.38,-421 445.38,-415 445.38,-415 445.38,-395 445.38,-395 445.38,-389 451.38,-383 457.38,-383 457.38,-383 546.88,-383 546.88,-383 552.88,-383 558.88,-389 558.88,-395 558.88,-395 558.88,-415 558.88,-415 558.88,-421 552.88,-427 546.88,-427"/>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-413.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">bin/pwn_gqrx_scanner</text>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-401.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">&#45;&#45;fft&#45;scan · iterative</text>
+<text xml:space="preserve" text-anchor="middle" x="502.12" y="-389.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">&#45;&#45;min&#45;snr&#45;db · &#45;&#45;avg</text>
+</g>
+<!-- RFID&#45;&gt;Scan -->
+<g id="edge6" class="edge">
+<title>RFID&#45;&gt;Scan</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M328.29,-401.75C358.34,-402.32 400.16,-403.1 435.13,-403.76"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="434.78,-406.55 442.83,-403.9 434.88,-400.95 434.78,-406.55"/>
+</g>
+<!-- Dec -->
+<g id="node8" class="node">
+<title>Dec</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M802.25,-96C802.25,-96 666.25,-96 666.25,-96 660.25,-96 654.25,-90 654.25,-84 654.25,-84 654.25,-28 654.25,-28 654.25,-22 660.25,-16 666.25,-16 666.25,-16 802.25,-16 802.25,-16 808.25,-16 814.25,-22 814.25,-28 814.25,-28 814.25,-84 814.25,-84 814.25,-90 808.25,-96 802.25,-96"/>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-82.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">SDR::Decoder::*</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-70.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">ADSB · APT · BT · DECT · GPS</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-58.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">GSM · Iridium · LoRa · LTE</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-46.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">Morse · P25 · POCSAG/FLEX</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-34.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">RDS · RFID · rtl_433 · RTTY</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-22.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">WiFi · ZigBee</text>
+</g>
+<!-- GQRX&#45;&gt;Dec -->
+<g id="edge7" class="edge">
+<title>GQRX&#45;&gt;Dec</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M561.17,-233.24C566.51,-230.18 571.64,-226.77 576.25,-223 622.93,-184.83 611.7,-154.72 654.25,-112 657.34,-108.9 660.61,-105.85 664,-102.88"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="665.77,-105.05 670.09,-97.76 662.16,-100.77 665.77,-105.05"/>
+</g>
+<!-- Freq&#45;&gt;Dec -->
+<g id="edge8" class="edge">
+<title>Freq&#45;&gt;Dec</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M568.68,-316.86C571.37,-315.1 573.91,-313.16 576.25,-311 646.1,-246.61 595.72,-186.82 654.25,-112 656.7,-108.87 659.37,-105.84 662.19,-102.92"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="663.82,-105.25 667.64,-97.68 659.93,-101.22 663.82,-105.25"/>
+</g>
+<!-- Obs -->
+<g id="node9" class="node">
+<title>Obs</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.3" d="M768.5,-172C768.5,-172 700,-172 700,-172 694,-172 688,-166 688,-160 688,-160 688,-140 688,-140 688,-134 694,-128 700,-128 700,-128 768.5,-128 768.5,-128 774.5,-128 780.5,-134 780.5,-140 780.5,-140 780.5,-160 780.5,-160 780.5,-166 774.5,-172 768.5,-172"/>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-158.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">extro_observe</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-146.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">category: :rf</text>
+<text xml:space="preserve" text-anchor="middle" x="734.25" y="-134.5" font-family="sans-Serif" font-size="10.00" fill="#0f172a">record signal intel</text>
+</g>
+<!-- Scan&#45;&gt;Obs -->
+<g id="edge9" class="edge">
+<title>Scan&#45;&gt;Obs</title>
+<path fill="none" stroke="#a78bfa" stroke-width="1.3" d="M559.35,-389.21C565.35,-386.32 571.12,-382.94 576.25,-379 646.6,-324.88 696.97,-230.14 719.71,-181.21"/>
+<polygon fill="#a78bfa" stroke="#a78bfa" stroke-width="1.3" points="722.17,-182.58 722.94,-174.14 717.07,-180.25 722.17,-182.58"/>
+</g>
+</g>
+</svg>

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

@@ -0,0 +1,225 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
+ "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<!-- Generated by graphviz version 14.1.2 (0)
+ -->
+<!-- Title: PWN_Swarm Pages: 1 -->
+<svg width="933pt" height="582pt"
+ viewBox="0.00 0.00 933.00 582.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
+<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(43.2 538.58)">
+<title>PWN_Swarm</title>
+<polygon fill="#0f172a" stroke="none" points="-43.2,43.2 -43.2,-538.58 889.54,-538.58 889.54,43.2 -43.2,43.2"/>
+<text xml:space="preserve" text-anchor="start" x="138.54" y="-473.38" font-family="sans-Serif" font-weight="bold" font-size="20.00" fill="#e2e8f0">PWN::AI::Agent::Swarm — Native Multi&#45;Agent Orchestration</text>
+<text xml:space="preserve" text-anchor="start" x="275.79" y="-461.93" font-family="sans-Serif" font-size="11.00" fill="#94a3b8">personas · ask · debate · broadcast · shared bus (no daemon)</text>
+<g id="clust1" class="cluster">
+<title>cluster_verbs</title>
+<path fill="#2e1065" stroke="#6d28d9" stroke-width="2" d="M36,-292.12C36,-292.12 574,-292.12 574,-292.12 580,-292.12 586,-298.12 586,-304.12 586,-304.12 586,-363.38 586,-363.38 586,-369.38 580,-375.38 574,-375.38 574,-375.38 36,-375.38 36,-375.38 30,-375.38 24,-369.38 24,-363.38 24,-363.38 24,-304.12 24,-304.12 24,-298.12 30,-292.12 36,-292.12"/>
+<text xml:space="preserve" text-anchor="middle" x="305" y="-352.38" font-family="sans-Serif" font-size="20.00" fill="#ddd6fe">Swarm Verbs &#160;(toolset: swarm)</text>
+</g>
+<g id="clust3" class="cluster">
+<title>cluster_personas</title>
+<path fill="#022c22" stroke="#047857" stroke-width="2" d="M20,-149.88C20,-149.88 623,-149.88 623,-149.88 629,-149.88 635,-155.88 635,-161.88 635,-161.88 635,-233.62 635,-233.62 635,-239.62 629,-245.62 623,-245.62 623,-245.62 20,-245.62 20,-245.62 14,-245.62 8,-239.62 8,-233.62 8,-233.62 8,-161.88 8,-161.88 8,-155.88 14,-149.88 20,-149.88"/>
+<text xml:space="preserve" text-anchor="middle" x="321.5" y="-222.62" font-family="sans-Serif" font-size="20.00" fill="#a7f3d0">Personas &#160;(each = full PWN::AI::Agent::Loop)</text>
+</g>
+<g id="clust5" class="cluster">
+<title>cluster_state</title>
+<path fill="#422006" stroke="#a16207" stroke-width="2" d="M33,-8C33,-8 642,-8 642,-8 648,-8 654,-14 654,-20 654,-20 654,-91.38 654,-91.38 654,-97.38 648,-103.38 642,-103.38 642,-103.38 33,-103.38 33,-103.38 27,-103.38 21,-97.38 21,-91.38 21,-91.38 21,-20 21,-20 21,-14 27,-8 33,-8"/>
+<text xml:space="preserve" text-anchor="middle" x="337.5" y="-80.38" font-family="sans-Serif" font-size="20.00" fill="#fde68a">Shared State &#160;~/.pwn/</text>
+</g>
+<!-- Orchestrator -->
+<g id="node1" class="node">
+<title>Orchestrator</title>
+<path fill="#7dd3fc" stroke="#334155" stroke-width="1.4" d="M308.75,-456.38C308.75,-456.38 237.25,-456.38 237.25,-456.38 231.25,-456.38 225.25,-450.38 225.25,-444.38 225.25,-444.38 225.25,-432.38 225.25,-432.38 225.25,-426.38 231.25,-420.38 237.25,-420.38 237.25,-420.38 308.75,-420.38 308.75,-420.38 314.75,-420.38 320.75,-426.38 320.75,-432.38 320.75,-432.38 320.75,-444.38 320.75,-444.38 320.75,-450.38 314.75,-456.38 308.75,-456.38"/>
+<text xml:space="preserve" text-anchor="middle" x="273" y="-441.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">👤 &#160;Orchestrator</text>
+<text xml:space="preserve" text-anchor="middle" x="273" y="-427.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">(you, in pwn&#45;ai)</text>
+</g>
+<!-- Spawn -->
+<g id="node2" class="node">
+<title>Spawn</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.4" d="M107.62,-336.12C107.62,-336.12 44.38,-336.12 44.38,-336.12 38.38,-336.12 32.38,-330.12 32.38,-324.12 32.38,-324.12 32.38,-312.12 32.38,-312.12 32.38,-306.12 38.38,-300.12 44.38,-300.12 44.38,-300.12 107.62,-300.12 107.62,-300.12 113.62,-300.12 119.62,-306.12 119.62,-312.12 119.62,-312.12 119.62,-324.12 119.62,-324.12 119.62,-330.12 113.62,-336.12 107.62,-336.12"/>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-321.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">agent_spawn</text>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-307.68" font-family="sans-Serif" font-size="11.00" fill="#0f172a">define persona</text>
+</g>
+<!-- Orchestrator&#45;&gt;Spawn -->
+<g id="edge1" class="edge">
+<title>Orchestrator&#45;&gt;Spawn</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" d="M229.09,-419.75C203.18,-408.56 170.23,-392.9 143,-375.38 128.4,-365.98 113.49,-353.77 101.45,-343.12"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="103.63,-341.32 95.81,-338.05 99.88,-345.48 103.63,-341.32"/>
+</g>
+<!-- Ask -->
+<g id="node3" class="node">
+<title>Ask</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.4" d="M263.5,-336.12C263.5,-336.12 178.5,-336.12 178.5,-336.12 172.5,-336.12 166.5,-330.12 166.5,-324.12 166.5,-324.12 166.5,-312.12 166.5,-312.12 166.5,-306.12 172.5,-300.12 178.5,-300.12 178.5,-300.12 263.5,-300.12 263.5,-300.12 269.5,-300.12 275.5,-306.12 275.5,-312.12 275.5,-312.12 275.5,-324.12 275.5,-324.12 275.5,-330.12 269.5,-336.12 263.5,-336.12"/>
+<text xml:space="preserve" text-anchor="middle" x="221" y="-321.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">agent_ask</text>
+<text xml:space="preserve" text-anchor="middle" x="221" y="-307.68" font-family="sans-Serif" font-size="11.00" fill="#0f172a">1 turn → 1 persona</text>
+</g>
+<!-- Orchestrator&#45;&gt;Ask -->
+<g id="edge2" class="edge">
+<title>Orchestrator&#45;&gt;Ask</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" d="M265.33,-419.93C256.72,-400.36 242.68,-368.42 232.7,-345.74"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="235.28,-344.64 229.5,-338.45 230.15,-346.9 235.28,-344.64"/>
+</g>
+<!-- Debate -->
+<g id="node4" class="node">
+<title>Debate</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.4" d="M419.5,-336.12C419.5,-336.12 334.5,-336.12 334.5,-336.12 328.5,-336.12 322.5,-330.12 322.5,-324.12 322.5,-324.12 322.5,-312.12 322.5,-312.12 322.5,-306.12 328.5,-300.12 334.5,-300.12 334.5,-300.12 419.5,-300.12 419.5,-300.12 425.5,-300.12 431.5,-306.12 431.5,-312.12 431.5,-312.12 431.5,-324.12 431.5,-324.12 431.5,-330.12 425.5,-336.12 419.5,-336.12"/>
+<text xml:space="preserve" text-anchor="middle" x="377" y="-321.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">agent_debate</text>
+<text xml:space="preserve" text-anchor="middle" x="377" y="-307.68" font-family="sans-Serif" font-size="11.00" fill="#0f172a">round&#45;robin critique</text>
+</g>
+<!-- Orchestrator&#45;&gt;Debate -->
+<g id="edge3" class="edge">
+<title>Orchestrator&#45;&gt;Debate</title>
+<path fill="none" stroke="#38bdf8" stroke-width="2" d="M288.35,-419.93C305.78,-400.1 334.4,-367.56 354.39,-344.83"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="2" points="356.41,-346.77 359.59,-338.92 352.21,-343.08 356.41,-346.77"/>
+</g>
+<!-- Broadcast -->
+<g id="node5" class="node">
+<title>Broadcast</title>
+<path fill="#c4b5fd" stroke="#334155" stroke-width="1.4" d="M565.62,-336.12C565.62,-336.12 490.38,-336.12 490.38,-336.12 484.38,-336.12 478.38,-330.12 478.38,-324.12 478.38,-324.12 478.38,-312.12 478.38,-312.12 478.38,-306.12 484.38,-300.12 490.38,-300.12 490.38,-300.12 565.62,-300.12 565.62,-300.12 571.62,-300.12 577.62,-306.12 577.62,-312.12 577.62,-312.12 577.62,-324.12 577.62,-324.12 577.62,-330.12 571.62,-336.12 565.62,-336.12"/>
+<text xml:space="preserve" text-anchor="middle" x="528" y="-321.18" font-family="sans-Serif" font-size="11.00" fill="#0f172a">agent_broadcast</text>
+<text xml:space="preserve" text-anchor="middle" x="528" y="-307.68" font-family="sans-Serif" font-size="11.00" fill="#0f172a">fan&#45;out ensemble</text>
+</g>
+<!-- Orchestrator&#45;&gt;Broadcast -->
+<g id="edge4" class="edge">
+<title>Orchestrator&#45;&gt;Broadcast</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" d="M321.14,-425.63C358.9,-415.34 412.06,-398.42 455,-375.38 471.5,-366.52 488.17,-354.01 501.41,-343.03"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="502.98,-345.36 507.27,-338.06 499.36,-341.09 502.98,-345.36"/>
+</g>
+<!-- Red -->
+<g id="node6" class="node">
+<title>Red</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M124.12,-206.38C124.12,-206.38 27.88,-206.38 27.88,-206.38 21.88,-206.38 15.88,-200.38 15.88,-194.38 15.88,-194.38 15.88,-169.88 15.88,-169.88 15.88,-163.88 21.88,-157.88 27.88,-157.88 27.88,-157.88 124.12,-157.88 124.12,-157.88 130.12,-157.88 136.12,-163.88 136.12,-169.88 136.12,-169.88 136.12,-194.38 136.12,-194.38 136.12,-200.38 130.12,-206.38 124.12,-206.38"/>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-191.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">🔴 &#160;red_team</text>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-178.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">engine: grok</text>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-164.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">toolsets: terminal,pwn</text>
+</g>
+<!-- Spawn&#45;&gt;Red -->
+<!-- Agents -->
+<g id="node10" class="node">
+<title>Agents</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.4" d="M122.62,-59.75C122.62,-62.16 101.73,-64.12 76,-64.12 50.27,-64.12 29.38,-62.16 29.38,-59.75 29.38,-59.75 29.38,-20.38 29.38,-20.38 29.38,-17.96 50.27,-16 76,-16 101.73,-16 122.62,-17.96 122.62,-20.38 122.62,-20.38 122.62,-59.75 122.62,-59.75"/>
+<path fill="none" stroke="#334155" stroke-width="1.4" d="M122.62,-59.75C122.62,-57.34 101.73,-55.38 76,-55.38 50.27,-55.38 29.38,-57.34 29.38,-59.75"/>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-43.11" font-family="sans-Serif" font-size="11.00" fill="#0f172a">agents.yml</text>
+<text xml:space="preserve" text-anchor="middle" x="76" y="-29.61" font-family="sans-Serif" font-size="11.00" fill="#0f172a">persona registry</text>
+</g>
+<!-- Spawn&#45;&gt;Agents -->
+<g id="edge15" class="edge">
+<title>Spawn&#45;&gt;Agents</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M118.01,-299.52C126.18,-296.65 134.77,-294.01 143,-292.12 252.43,-267.12 570.37,-328.57 646,-245.62 674.67,-214.18 674.66,-181.33 646,-149.88 627.25,-129.29 172.57,-114.39 147,-103.38 130.38,-96.22 114.9,-83.65 102.66,-71.67"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="104.82,-69.88 97.22,-66.14 100.83,-73.81 104.82,-69.88"/>
+<text xml:space="preserve" text-anchor="middle" x="677.25" y="-178.82" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">write</text>
+</g>
+<!-- Ask&#45;&gt;Red -->
+<g id="edge6" class="edge">
+<title>Ask&#45;&gt;Red</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M202.04,-299.61C178.41,-277.76 137.62,-240.07 108.85,-213.48"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="111.03,-211.69 103.26,-208.32 107.23,-215.8 111.03,-211.69"/>
+</g>
+<!-- Blue -->
+<g id="node7" class="node">
+<title>Blue</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M277,-206.38C277,-206.38 195,-206.38 195,-206.38 189,-206.38 183,-200.38 183,-194.38 183,-194.38 183,-169.88 183,-169.88 183,-163.88 189,-157.88 195,-157.88 195,-157.88 277,-157.88 277,-157.88 283,-157.88 289,-163.88 289,-169.88 289,-169.88 289,-194.38 289,-194.38 289,-200.38 283,-206.38 277,-206.38"/>
+<text xml:space="preserve" text-anchor="middle" x="236" y="-191.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">🔵 &#160;blue_team</text>
+<text xml:space="preserve" text-anchor="middle" x="236" y="-178.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">engine: anthropic</text>
+<text xml:space="preserve" text-anchor="middle" x="236" y="-164.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">toolsets: pwn,extro</text>
+</g>
+<!-- Debate&#45;&gt;Blue -->
+<g id="edge7" class="edge">
+<title>Debate&#45;&gt;Blue</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M358.57,-299.61C335.68,-277.86 296.25,-240.39 268.3,-213.82"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="270.26,-211.82 262.53,-208.34 266.4,-215.88 270.26,-211.82"/>
+</g>
+<!-- Recon -->
+<g id="node8" class="node">
+<title>Recon</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M463.5,-206.38C463.5,-206.38 348.5,-206.38 348.5,-206.38 342.5,-206.38 336.5,-200.38 336.5,-194.38 336.5,-194.38 336.5,-169.88 336.5,-169.88 336.5,-163.88 342.5,-157.88 348.5,-157.88 348.5,-157.88 463.5,-157.88 463.5,-157.88 469.5,-157.88 475.5,-163.88 475.5,-169.88 475.5,-169.88 475.5,-194.38 475.5,-194.38 475.5,-200.38 469.5,-206.38 463.5,-206.38"/>
+<text xml:space="preserve" text-anchor="middle" x="406" y="-191.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">🛰 &#160;recon</text>
+<text xml:space="preserve" text-anchor="middle" x="406" y="-178.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">engine: ollama</text>
+<text xml:space="preserve" text-anchor="middle" x="406" y="-164.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">toolsets: terminal,memory</text>
+</g>
+<!-- Debate&#45;&gt;Recon -->
+<g id="edge8" class="edge">
+<title>Debate&#45;&gt;Recon</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M380.79,-299.61C385.34,-278.6 393.06,-242.92 398.76,-216.57"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="401.47,-217.31 400.42,-208.9 395.99,-216.13 401.47,-217.31"/>
+</g>
+<!-- Xpl -->
+<g id="node9" class="node">
+<title>Xpl</title>
+<path fill="#6ee7b7" stroke="#334155" stroke-width="1.4" d="M615.25,-206.38C615.25,-206.38 534.75,-206.38 534.75,-206.38 528.75,-206.38 522.75,-200.38 522.75,-194.38 522.75,-194.38 522.75,-169.88 522.75,-169.88 522.75,-163.88 528.75,-157.88 534.75,-157.88 534.75,-157.88 615.25,-157.88 615.25,-157.88 621.25,-157.88 627.25,-163.88 627.25,-169.88 627.25,-169.88 627.25,-194.38 627.25,-194.38 627.25,-200.38 621.25,-206.38 615.25,-206.38"/>
+<text xml:space="preserve" text-anchor="middle" x="575" y="-191.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">💥 &#160;exploit_dev</text>
+<text xml:space="preserve" text-anchor="middle" x="575" y="-178.43" font-family="sans-Serif" font-size="11.00" fill="#0f172a">engine: openai</text>
+<text xml:space="preserve" text-anchor="middle" x="575" y="-164.93" font-family="sans-Serif" font-size="11.00" fill="#0f172a">toolsets: pwn,skills</text>
+</g>
+<!-- Broadcast&#45;&gt;Xpl -->
+<g id="edge9" class="edge">
+<title>Broadcast&#45;&gt;Xpl</title>
+<path fill="none" stroke="#34d399" stroke-width="1.3" d="M534.14,-299.61C541.55,-278.5 554.14,-242.6 563.39,-216.22"/>
+<polygon fill="#34d399" stroke="#34d399" stroke-width="1.3" points="565.98,-217.31 565.98,-208.84 560.69,-215.46 565.98,-217.31"/>
+</g>
+<!-- Red&#45;&gt;Agents -->
+<!-- Bus -->
+<g id="node11" class="node">
+<title>Bus</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.4" d="M288,-59.75C288,-62.16 261.56,-64.12 229,-64.12 196.44,-64.12 170,-62.16 170,-59.75 170,-59.75 170,-20.38 170,-20.38 170,-17.96 196.44,-16 229,-16 261.56,-16 288,-17.96 288,-20.38 288,-20.38 288,-59.75 288,-59.75"/>
+<path fill="none" stroke="#334155" stroke-width="1.4" d="M288,-59.75C288,-57.34 261.56,-55.38 229,-55.38 196.44,-55.38 170,-57.34 170,-59.75"/>
+<text xml:space="preserve" text-anchor="middle" x="229" y="-43.11" font-family="sans-Serif" font-size="11.00" fill="#0f172a">swarm/&lt;id&gt;/bus.jsonl</text>
+<text xml:space="preserve" text-anchor="middle" x="229" y="-29.61" font-family="sans-Serif" font-size="11.00" fill="#0f172a">append&#45;only chat</text>
+</g>
+<!-- Red&#45;&gt;Bus -->
+<g id="edge11" class="edge">
+<title>Red&#45;&gt;Bus</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M101.95,-157.37C127.86,-133.65 167.76,-97.12 195.92,-71.34"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="197.71,-73.5 201.72,-66.03 193.93,-69.37 197.71,-73.5"/>
+<text xml:space="preserve" text-anchor="middle" x="174.91" y="-113.33" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">append reply</text>
+</g>
+<!-- Blue&#45;&gt;Bus -->
+<g id="edge12" class="edge">
+<title>Blue&#45;&gt;Bus</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M234.81,-157.37C233.67,-134.49 231.93,-99.69 230.65,-74.12"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="233.46,-74.29 230.27,-66.44 227.87,-74.57 233.46,-74.29"/>
+</g>
+<!-- Pmap -->
+<g id="node12" class="node">
+<title>Pmap</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.4" d="M477.38,-59.75C477.38,-62.16 445.38,-64.12 406,-64.12 366.62,-64.12 334.62,-62.16 334.62,-59.75 334.62,-59.75 334.62,-20.38 334.62,-20.38 334.62,-17.96 366.62,-16 406,-16 445.38,-16 477.38,-17.96 477.38,-20.38 477.38,-20.38 477.38,-59.75 477.38,-59.75"/>
+<path fill="none" stroke="#334155" stroke-width="1.4" d="M477.38,-59.75C477.38,-57.34 445.38,-55.38 406,-55.38 366.62,-55.38 334.62,-57.34 334.62,-59.75"/>
+<text xml:space="preserve" text-anchor="middle" x="406" y="-43.11" font-family="sans-Serif" font-size="11.00" fill="#0f172a">swarm/&lt;id&gt;/personas.json</text>
+<text xml:space="preserve" text-anchor="middle" x="406" y="-29.61" font-family="sans-Serif" font-size="11.00" fill="#0f172a">name → session_id</text>
+</g>
+<!-- Recon&#45;&gt;Pmap -->
+<g id="edge13" class="edge">
+<title>Recon&#45;&gt;Pmap</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M406,-157.37C406,-134.49 406,-99.69 406,-74.12"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="408.8,-74.44 406,-66.44 403.2,-74.44 408.8,-74.44"/>
+</g>
+<!-- Sess -->
+<g id="node13" class="node">
+<title>Sess</title>
+<path fill="#fcd34d" stroke="#334155" stroke-width="1.4" d="M645.88,-59.75C645.88,-62.16 618.59,-64.12 585,-64.12 551.41,-64.12 524.12,-62.16 524.12,-59.75 524.12,-59.75 524.12,-20.38 524.12,-20.38 524.12,-17.96 551.41,-16 585,-16 618.59,-16 645.88,-17.96 645.88,-20.38 645.88,-20.38 645.88,-59.75 645.88,-59.75"/>
+<path fill="none" stroke="#334155" stroke-width="1.4" d="M645.88,-59.75C645.88,-57.34 618.59,-55.38 585,-55.38 551.41,-55.38 524.12,-57.34 524.12,-59.75"/>
+<text xml:space="preserve" text-anchor="middle" x="585" y="-43.11" font-family="sans-Serif" font-size="11.00" fill="#0f172a">sessions/*.jsonl</text>
+<text xml:space="preserve" text-anchor="middle" x="585" y="-29.61" font-family="sans-Serif" font-size="11.00" fill="#0f172a">per&#45;persona transcript</text>
+</g>
+<!-- Xpl&#45;&gt;Sess -->
+<g id="edge14" class="edge">
+<title>Xpl&#45;&gt;Sess</title>
+<path fill="none" stroke="#f59e0b" stroke-width="1.3" d="M576.7,-157.37C578.33,-134.49 580.81,-99.69 582.64,-74.12"/>
+<polygon fill="#f59e0b" stroke="#f59e0b" stroke-width="1.3" points="585.41,-74.61 583.19,-66.43 579.83,-74.21 585.41,-74.61"/>
+</g>
+<!-- Bus&#45;&gt;Orchestrator -->
+<g id="edge17" class="edge">
+<title>Bus&#45;&gt;Orchestrator</title>
+<path fill="none" stroke="#38bdf8" stroke-width="1.3" stroke-dasharray="5,2" d="M251.75,-64.53C267.03,-78.61 288.44,-95.3 311,-103.38 333.3,-111.36 500.42,-109.2 524,-111.38 582.38,-116.76 746.69,-105.5 785,-149.88 870.27,-248.64 717.36,-324.97 597,-375.38 508.69,-412.36 397.56,-427.48 331.06,-433.52"/>
+<polygon fill="#38bdf8" stroke="#38bdf8" stroke-width="1.3" points="330.87,-430.72 323.15,-434.21 331.36,-436.3 330.87,-430.72"/>
+<text xml:space="preserve" text-anchor="middle" x="819.71" y="-255.57" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">swarm_bus()</text>
+</g>
+<!-- Bus&#45;&gt;Debate -->
+<g id="edge16" class="edge">
+<title>Bus&#45;&gt;Debate</title>
+<path fill="none" stroke="#fbbf24" stroke-width="1.3" stroke-dasharray="5,2" d="M252.68,-64.52C268.01,-78.23 289.12,-94.52 311,-103.38 391.29,-135.88 640.52,-85.08 698,-149.88 726.24,-181.71 725.12,-212.83 698,-245.62 627.93,-330.37 561.55,-264.96 455,-292.12 449.62,-293.5 444.06,-295.03 438.5,-296.65"/>
+<polygon fill="#fbbf24" stroke="#fbbf24" stroke-width="1.3" points="437.94,-293.9 431.08,-298.87 439.55,-299.26 437.94,-293.9"/>
+<text xml:space="preserve" text-anchor="middle" x="746.13" y="-178.82" font-family="sans-Serif" font-size="9.00" fill="#cbd5e1">tail → context</text>
+</g>
+</g>
+</svg>

data/documentation/pwn-REPL.md

@@ -1,33 +1,49 @@
-# The pwn REPL
+# The `pwn` REPL
 
-The `pwn` command launches a Pry-based interactive Ruby shell with the entire `PWN` namespace pre-loaded.
+`pwn` launches a **Pry** session with the entire `PWN::` namespace already
+`require`d, a themed prompt, a persistent history file, and a set of custom
+commands.
 
-## Starting
+![REPL prototyping](diagrams/pwn-repl-prototyping.svg)
 
-```bash
-pwn
-pwn[v0.5.613]:001 >>>
-```
+## Why Pry (not IRB)?
 
-## Key Features
+- `ls PWN::Plugins::BurpSuite` — instant method listing
+- `show-source` / `show-doc` — read any plugin without leaving the shell
+- `edit -m` — patch a method live and retry
+- `wtf?` — full backtrace of the last exception
+- `history --replay 5..12` — re-run a range of lines
 
-- Direct access to every `PWN::` constant and plugin.
-- Tab completion for classes and methods.
-- Multi-line support.
-- Easy prototyping of security workflows.
-- `PWN.help` and inspection of any object.
+## Custom commands
 
-## Useful REPL Commands
+| Command | Implemented in | Purpose |
+|---|---|---|
+| `pwn-ai` | `Agent::Loop` | Enter the AI agent TUI |
+| `pwn-asm` | `Plugins::Assembly` | Multiline asm ↔ opcodes workbench |
+| `pwn-ai-memory` | `PWN::Memory` | View/edit persistent memory |
+| `pwn-ai-sessions` | `PWN::Sessions` | List/view/delete transcripts |
+| `pwn-ai-cron` | `PWN::Cron` | List/run/toggle scheduled jobs |
+| `pwn-ai-delegate` | `Agent::Swarm` | Send one request to a persona |
+| `welcome-banner` | `PWN::Banner` | Redraw a random banner |
+| `toggle-pager` | Pry | Page long output on/off |
 
-```
-pwn[v0.5.613]:001 >>> PWN::Plugins.constants.sort
-pwn[v0.5.613]:001 >>> PWN::Plugins::BurpSuite.methods(false).sort
-pwn[v0.5.613]:001 >>> PWN::SAST.constants
-pwn[v0.5.613]:001 >>> pwn-ai
-```
+## Multi-line input
 
-See:
-- [pwn-ai Agent](pwn-ai-Agent.md) — the killer feature inside the REPL
-- [General Usage](General-PWN-Usage.md)
+`pwn-ai` and `pwn-asm` use a custom `PWNMultiLineInput` reader:
 
-[[Diagrams]]
+- **SHIFT + ENTER** → insert newline
+- **ENTER** → submit
+
+> **tmux users:** requires `set -s extended-keys on` **and**
+> `set -as terminal-features '<outerTERM>*:extkeys'` — see
+> [Troubleshooting](Troubleshooting.md#shiftenter-submits-instead-of-newline).
+
+## History → Driver
+
+`~/.pwn_history` captures every line you type. When a sequence works, turn it
+into a shipped `bin/pwn_*` driver — see
+[From REPL History to Driver](Drivers.md).
+
+**Next:** [pwn-ai Agent](pwn-ai-Agent.md) · [CLI Drivers](CLI-Drivers.md)
+
+[← Home](Home.md)

data/documentation/pwn-ai-Agent.md

@@ -1,43 +1,85 @@
-# pwn-ai Autonomous Agent
+# `pwn-ai` — The Autonomous Agent
 
-The most powerful way to use PWN is via the `pwn-ai` command inside the REPL.
+`pwn-ai` is a natural-language front end to everything in `PWN::`. You describe
+the goal; the agent plans a sequence of tool calls (`pwn_eval`, `shell`,
+`memory_*`, `skill_*`, `mistakes_*`, `extro_*`, `agent_*`, …), executes them
+against the live process, observes the results, and loops until it can give you
+a final answer — **learning from every failure so it doesn't repeat it**.
 
-## Activation
+## Two ways to run it
+
+```text
+# 1. Interactive TUI (inside the pwn REPL)
+pwn[v0.5.618]:001 >>> pwn-ai
+✨ pwn-ai · anthropic · session 20260707_225041_d7f2f3bb
+> Use NmapIt to sweep 10.0.0.0/24, then TransparentBrowser via Burp on any
+  host with 443 open, active-scan, and give me a Reports::SAST summary.
+```
 
 ```bash
-pwn[v0.5.613]:001 >>> pwn-ai
-[*] pwn-ai agent TUI activated...
->
+# 2. Headless one-shot (CI-friendly)
+$ pwn --ai "run bin/pwn_sast against ./src and push findings to DefectDojo"
 ```
 
-## Capabilities
+## Anatomy of a turn
 
-- Natural language instruction of complex multi-step security tasks.
-- Full tool calling access to:
-  - All `PWN::Plugins` (BurpSuite preferred, TransparentBrowser, NmapIt, Shodan, Metasploit, etc.)
-  - `PWN::SAST`
-  - `PWN::Reports`
-  - Shell execution
-  - Memory recall / remember
-  - Skill usage and distillation
-  - Learning / introspection loop
-- Persistent context across interactions via memory and skills.
+1. **PromptBuilder** assembles the system prompt: your request + MEMORY block +
+   SKILLS list + LEARNING stats + **KNOWN MISTAKES / KNOWN FIXES** +
+   TOOL EFFECTIVENESS + EXTROSPECTION block.
+2. **Loop** checks the incoming message against `Mistakes::CORRECTION_RX` — if
+   it reads like *"no, that's wrong"* the previous outcome is flipped to
+   `success:false` and fingerprinted.
+3. Loop sends the prompt to the active `PWN::AI::<Engine>` client.
+4. Provider replies with `tool_calls` → **Dispatch** executes each one via the
+   [Registry](Agent-Tool-Registry.md); **Metrics** records duration/success.
+   Any *failure* is fingerprinted into **Mistakes** (`count++`, cross-session)
+   and the tool result gets an inline `correction_hint` (`seen N×, sig=…,
+   KNOWN FIX: …`) so the very next iteration self-corrects. If the persistent
+   count ≥ 3, `guard_repeated_failure` interrupts with an explicit
+   *change-approach* instruction.
+5. Results are appended to the message list; go to 3.
+6. When the reply has *no* tool_calls it's the **final answer** →
+   `Learning.auto_reflect` and `Extrospection.auto_extrospect` fire (if
+   enabled), transcript is flushed to `~/.pwn/sessions/`.
 
-## Tips
+![Self-improvement loop](diagrams/pwn-ai-feedback-learning-loop.svg)
+
+## What the agent can call
+
+10 toolsets · 52 tools — full table at
+[Agent Tool Registry](Agent-Tool-Registry.md).
 
-- Use `SHIFT+ENTER` to insert newlines.
-- `ENTER` submits the prompt.
-- Type `back` or `exit` to return to normal REPL.
-- Example prompt:
-  ```
-  Scan https://target with NmapIt + TransparentBrowser (via BurpSuite), 
-  run relevant SAST if source present, exploit any findings, generate report.
-  ```
+The two that matter most:
 
-## Self-Improvement
+| Tool | Reach |
+|---|---|
+| `pwn_eval` | **Any** Ruby in-process — the whole `PWN::` namespace, `require`, monkey-patch, everything |
+| `shell` | **Any** OS command on the host |
+
+Everything else (memory, skills, learning, **mistakes**, extrospection, cron,
+swarm, sessions, metrics) is a convenience wrapper the model can discover from
+the schema alone.
+
+## Delegating to other agents
+
+`agent_ask`, `agent_debate`, `agent_broadcast` spin up **sub-agents** (each a
+full `Loop.run` under a persona overlay) that share a JSONL bus. See
+[Swarm](Swarm.md).
+
+## Tips
 
-Successful workflows can be distilled into reusable **Skills** (see [Skills-Memory-Learning](Skills-Memory-Learning.md)).
+- SHIFT+ENTER = newline, ENTER = submit.
+- `back` / `exit` returns to the plain REPL.
+- Set `ai.agent.max_iters` in `~/.pwn/config.yml` if long tasks get truncated.
+- Disable `auto_reflect` during noisy fuzz loops
+  (`learning_auto_reflect_toggle(enabled: false)`), re-enable for the summary
+  turn.
+- Run `mistakes_list` before retrying something that failed last session — the
+  fix may already be recorded.
 
-See also [AI Integration](AI-Integration.md).
+**See also:** [AI Integration](AI-Integration.md) ·
+[Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[Mistakes](Mistakes.md) · [Extrospection](Extrospection.md) ·
+[Swarm](Swarm.md) · [Cron](Cron.md)
 
-[[Diagrams]]
+[← Home](Home.md)