pwn 0.5.636 → 0.5.637

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41a8a5c5d750508d4f3904d7a05151719e2c86fa4cf20001a3aab0985910963d
-  data.tar.gz: 7af0757b53bdfa6c97d86a9415a2cbf41ca9447b3f9e438b95b2424f5d835cbf
+  metadata.gz: 0201dea34ecdcd8a8a04debd2beea9f8faf296806dda78067873a023e3dd311e
+  data.tar.gz: f82990f46e0b6bccc2bf1020c41d19e681fa48e1ff6b96904b762e8d7a206716
 SHA512:
-  metadata.gz: 8053f31ef3138368e50c1b6920fa7804945f508daabc31191ba2a9578f3c31f7e6629e1ca901a409ec82e4cefdf3a824fa48bcfe4fdcd8ab4a1a9da0f168e1da
-  data.tar.gz: 592bfb24c2c2a610813fcd5b8431478d4774ef312405f446393db9cbb305c2c223b129a0714b9b464adc9976e682b1754a4e5d760d0ca28b00ba99778df21d7a
+  metadata.gz: '036668a7388b08f9aed7fe00d92b3034c3b47c9e29a0dccf92f3a2eb5149f9948d7283420a679547737763f2934a2df959f367ae33d08c1c785be6ff3db8dbe1'
+  data.tar.gz: d89b96e1dc380a4f87d0d82249c64213caa4c7f06a7ba8d20efe4a284ca1017b12de1f4bafaec66946d14efb31d4d9281dfc69c11fb840e3d74bc32c58f12415

data/bin/pwn_setup

@@ -44,6 +44,12 @@ pwn_driver = PWN::Driver::Parser.new do |options|
     opts[:yes] = o
   end
 
+  options.on('-t', '--terminal',
+             '<Optional - Opt-in SHIFT+ENTER multi-line support: prints ~/.tmux.conf lines and, ' \
+             'under Terminator, installs the PWNShiftEnter GTK plugin (with confirmation)>') do |o|
+    opts[:terminal] = o
+  end
+
   options.on('-n', '--dry-run',
              '<Optional - Print the commands that would run, do not execute>') do |o|
     opts[:dry_run] = o
@@ -61,6 +67,11 @@ begin
       dry_run: opts[:dry_run]
     )
     exit 1 unless r && r[:after] && r[:after][:incompatible].empty?
+  elsif opts[:terminal]
+    PWN::Setup.terminal(
+      yes: opts[:yes],
+      dry_run: opts[:dry_run]
+    )
   elsif opts[:deps] || opts[:profile]
     PWN::Setup.deps(
       profile: opts[:profile],

data/documentation/Agent-Tool-Registry.md

@@ -6,21 +6,25 @@ toolsets; the JSON-Schema for each tool is what the model actually sees.
 
 ![Tool registry](diagrams/agent-tool-registry.svg)
 
-## Toolsets → Tools  (10 toolsets · 61 tools)
+## Toolsets → Tools  (10 toolsets · 71 tools)
 
 | Toolset | Tools | Backed by |
 |---|---|---|
 | `terminal` | `shell` | `Open3.capture3` on the host |
 | `pwn` | `pwn_eval` | `TOPLEVEL_BINDING.eval` in the live REPL process |
 | `memory` | `memory_remember` · `memory_recall` · `memory_forget` · `memory_clear` | `PWN::Memory` → `~/.pwn/memory.json` |
-| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (agentskills.io; legacy flat `*.md` still read) |
+| `skills` | `skill_list` · `skill_view` · `skill_create` · `skill_add_reference` · `skill_delete` · `skill_migrate_legacy` | `~/.pwn/skills/<name>/SKILL.md` (**[agentskills.io](https://agentskills.io) spec**; legacy flat `*.md` auto-migrated) |
 | `sessions` | `sessions_list` · `sessions_view` · `sessions_current` · `sessions_delete` · `sessions_stats` | `PWN::Sessions` → `~/.pwn/sessions/` |
-| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · `learning_purge_noise` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` |
+| `learning` | `learning_note_outcome` · `learning_reflect` · `learning_distill_skill` · `learning_stats` · `learning_outcomes` · `learning_consolidate` · `learning_reset` · `learning_auto_introspect_toggle` · **`mistakes_list`** · **`mistakes_record`** · **`mistakes_resolve`** · **`mistakes_reset`** · **`reward_judge`** · **`reward_prm`** · **`reward_sentinel`** · **`reward_preferences`** · **`reward_export_dpo`** · **`curriculum_practice`** · **`curriculum_train`** · **`curriculum_hindsight`** · **`learning_purge_noise`** | `PWN::AI::Agent::Learning` + `Mistakes` + `Reward` + `Curriculum` → `~/.pwn/learning.jsonl` + `~/.pwn/mistakes.json` + `~/.pwn/preferences.jsonl` + `~/.pwn/curriculum/` + `~/.pwn/finetune/` |
 | `metrics` | `metrics_summary` · `metrics_reset` | `PWN::AI::Agent::Metrics` → `~/.pwn/metrics.json` |
-| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/TransparentBrowser) → `~/.pwn/extrospection.json` |
+| `extrospection` | `extro_snapshot` · `extro_drift` · `extro_observe` · `extro_observations` · `extro_intel` · **`extro_watch`** · **`extro_verify`** · **`extro_rf_tune`** · **`extro_osint`** · **`extro_serial`** · **`extro_telecomm`** · **`extro_packet`** · **`extro_vision`** · **`extro_voice`** · `extro_correlate` · `extro_stats` · `extro_reset` · `extro_auto_toggle` | `PWN::AI::Agent::Extrospection` (+ Serial/Packet/OCR/Voice/BareSIP/TransparentBrowser/GQRX) → `~/.pwn/extrospection.json` |
 | `cron` | `cron_list` · `cron_create` · `cron_run` · `cron_enable` · `cron_disable` · `cron_remove` | `PWN::Cron` → `~/.pwn/cron/jobs.yml` |
 | `swarm` | `agent_list` · `agent_spawn` · `agent_ask` · `agent_debate` · `agent_broadcast` · `swarm_bus` · `swarm_list` | `PWN::AI::Agent::Swarm` → `~/.pwn/agents.yml` + `~/.pwn/swarm/` |
 
+The `learning` toolset is deliberately fat: **Mistakes** (negative feedback),
+**Reward** (ORM/PRM/sentinel/DPO ledger) and **Curriculum** (self-play, HER,
+regression-gated LoRA) are all facets of the same self-improvement loop -
+see [Reinforcement Learning](Reinforcement-Learning.md).
 
 ## Dynamic tool-set slimming (`ai.agent.tool_router`)
 
@@ -41,6 +45,8 @@ CORE_TOOLS  = shell · pwn_eval · memory_remember · memory_recall
 ```ruby
 PWN::AI::Agent::Registry.definitions(relevance: 'nmap sweep 10.0.0.0/8', top_k: 10)
 PWN::AI::Agent::Registry.rank(query: 'run a shell command')   # inspect ranking
+PWN::AI::Agent::Registry.toolsets                              # → the 10 names above
+PWN::AI::Agent::Registry.all.count                             # → 71
 ```
 
 Frontier engines leave `tool_router` off and receive the full set.
@@ -75,6 +81,7 @@ recon:
   engine: ollama
 ```
 
-**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Mistakes](Mistakes.md) · [Swarm](Swarm.md)
+**See also:** [pwn-ai Agent](pwn-ai-Agent.md) · [Mistakes](Mistakes.md) ·
+[Reinforcement Learning](Reinforcement-Learning.md) · [Swarm](Swarm.md)
 
 [← Home](Home.md)

data/documentation/CLI-Drivers.md

@@ -1,47 +1,52 @@
 # CLI Drivers - `bin/pwn_*`
 
-53 headless executables, each a thin `OptionParser` wrapper over one plugin
-(or one workflow). They exist so CI/CD can call PWN without a REPL or an LLM.
+53 headless executables (52 `pwn_*` + `pwn`), each a thin `OptionParser`
+wrapper over one plugin (or one workflow). They exist so CI/CD can call PWN
+without a REPL or an LLM.
 
 ![Driver anatomy](diagrams/driver-framework.svg)
 
 ## Full list
 
 ```text
-pwn                              pwn_jenkins_thinBackup_aws_s3
-pwn_android_war_dialer           pwn_jenkins_update_plugins
-pwn_autoinc_version              pwn_jenkins_useradd
-pwn_aws_describe_resources       pwn_mail_agent
-pwn_bdba_groups                  pwn_msf_postgres_login
-pwn_bdba_scan                    pwn_nessus_cloud_scan_crud
-pwn_burp_suite_pro_active_rest_api_scan   pwn_nessus_cloud_vulnscan
-pwn_burp_suite_pro_active_scan   pwn_nexpose
-pwn_char_base64_encoding         pwn_nmap_discover_tcp_udp
-pwn_char_dec_encoding            pwn_openvas_vulnscan
-pwn_char_hex_escaped_encoding    pwn_pastebin_sample_filter
-pwn_char_html_entity_encoding    pwn_phone
-pwn_char_unicode_escaped_encoding  pwn_rdoc_to_jsonl
-pwn_char_url_encoding            pwn_sast
-pwn_crt_sh                       pwn_serial_check_voicemail
-pwn_defectdojo_engagement_create pwn_serial_msr206
-pwn_defectdojo_importscan        pwn_serial_qualcomm_commands
-pwn_defectdojo_reimportscan      pwn_serial_son_micro_sm132_rfid
-pwn_diff_csv_files_w_column_exclude  pwn_setup
-pwn_domain_reversewhois          pwn_shodan_graphql_introspection
-pwn_fuzz_net_app_proto           pwn_shodan_search
-pwn_gqrx_scanner                 pwn_simple_http_server
-pwn_jenkins_create_job           pwn_web_cache_deception
-pwn_jenkins_create_view          pwn_www_checkip
-pwn_jenkins_install_plugin       pwn_www_uri_buster
+pwn                                pwn_mail_agent
+pwn_android_war_dialer             pwn_msf_postgres_login
+pwn_autoinc_version                pwn_nessus_cloud_scan_crud
+pwn_aws_describe_resources         pwn_nessus_cloud_vulnscan
+pwn_bdba_groups                    pwn_nexpose
+pwn_bdba_scan                      pwn_nmap_discover_tcp_udp
+pwn_burp_suite_pro_active_rest_api_scan   pwn_openvas_vulnscan
+pwn_burp_suite_pro_active_scan     pwn_pastebin_sample_filter
+pwn_char_base64_encoding           pwn_phone
+pwn_char_dec_encoding              pwn_rdoc_to_jsonl
+pwn_char_hex_escaped_encoding      pwn_sast
+pwn_char_html_entity_encoding      pwn_serial_check_voicemail
+pwn_char_unicode_escaped_encoding  pwn_serial_msr206
+pwn_char_url_encoding              pwn_serial_qualcomm_commands
+pwn_crt_sh                         pwn_serial_son_micro_sm132_rfid
+pwn_defectdojo_engagement_create   pwn_setup
+pwn_defectdojo_importscan          pwn_shodan_graphql_introspection
+pwn_defectdojo_reimportscan        pwn_shodan_search
+pwn_diff_csv_files_w_column_exclude  pwn_simple_http_server
+pwn_domain_reversewhois            pwn_web_cache_deception
+pwn_fuzz_net_app_proto             pwn_www_checkip
+pwn_gqrx_scanner                   pwn_www_uri_buster
+pwn_jenkins_create_job             pwn_xss_dom_vectors
+pwn_jenkins_create_view            pwn_zaproxy_active_rest_api_scan
+pwn_jenkins_install_plugin         pwn_zaproxy_active_scan
+pwn_jenkins_thinBackup_aws_s3
+pwn_jenkins_update_plugins
+pwn_jenkins_useradd
 ```
 
 Run any with `--help` for its flags.
 
-## `pwn_setup` - post-install doctor & capability provisioner
+## `pwn_setup` - post-install doctor / provisioner / state migrator
 
 The one driver that isn't a plugin wrapper. It grows a bare `gem install pwn`
 into a fully-armed host by installing OS headers / external tools for whatever
-capability profile you ask for. Also reachable as `pwn setup` and
+capability profile you ask for, **and** verifies/repairs every persisted
+`~/.pwn` state file after an upgrade. Also reachable as `pwn setup` and
 `pwn --setup[=PROFILE]`.
 
 ```bash
@@ -49,10 +54,11 @@ pwn_setup                        # read-only doctor; exit 1 if degraded
 pwn_setup --list-profiles
 pwn_setup --profile web --yes    # CI-friendly, non-interactive
 pwn_setup --deps --dry-run       # print the apt/dnf/pacman/brew/port commands only
+pwn_setup --migrate --fix        # ~/.pwn state doctor + autofix (PWN::Migrate)
 ```
 
-See [Installation](Installation.md) for the full profile table and
-`PWN::Setup` API.
+See [Installation](Installation.md) for the full profile table, the
+`PWN::Setup` API and the `PWN::Migrate` state-file registry.
 
 ## Typical CI usage
 

data/documentation/Configuration.md

@@ -20,6 +20,9 @@ generates the decryptor.
 > [doctor](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
 > reports whether `~/.pwn/`, `pwn.yaml`, its decryptor, and an AI-engine key
 > are present, and exits non-zero for CI if any are missing.
+> After `gem update pwn`, run `pwn setup --migrate --fix` — `PWN::Migrate`
+> deep-merges any keys the new `PWN::Config.env_template` added into your
+> encrypted `pwn.yaml` **without overwriting your values**.
 
 ---
 
@@ -263,6 +266,11 @@ PWN::Config.refresh_env
 | `ai.agent.plan_first` | Boolean \| `nil` | `nil` (auto: `true` when `ai.active == ollama`) | `PWN::AI::Agent::Loop.plan_first` | Plan-then-act pre-pass: the model must emit a numbered tool plan (as an assistant message) *before* it may dispatch anything. Cheap chain-of-thought scaffolding for local models. |
 | `ai.agent.tool_router` | Boolean | `false` | `PWN::AI::Agent::Registry.definitions` | Dynamic tool-set slimming: expose only `Registry::CORE_TOOLS` + the top-K keyword-relevant schemas for *this* request. Ties break on historical `Metrics` success rate so the router itself is a learned component. |
 | `ai.agent.escalation_persona` | String \| `nil` | `nil` | `PWN::AI::Agent::Loop.escalate` → `Swarm.ask` | Circuit-breaker: once a local model accumulates ≥ `Loop::ESCALATE_AFTER_FAILS` in-turn failures, ask this Swarm persona for a 3-line corrective hint (injected as a synthetic tool result). The local model still authors the final answer so Learning/Metrics stay attributed. |
+| `ai.agent.critic` | Boolean | `false` | `PWN::AI::Agent::Curriculum.critic` (S3) | Tool-armed constitutional self-critic reviews (and may `shell`/`extro_verify`) every final answer before it is returned. |
+| `ai.agent.red_team_plan` | Boolean | `false` | `PWN::AI::Agent::Curriculum.red_team_plan` (S4) | Adversarial review of the `plan_first` numbered plan, grounded in Metrics/Mistakes/`extro_drift` telemetry, before the first dispatch. |
+| `ai.agent.counterfactual` | Boolean | `false` | `PWN::AI::Agent::Curriculum.counterfactual` (S2) | On `[REPEATING]`, fork an alt-persona branch, judge both, and record the `(loser, winner)` DPO preference pair. |
+| `ai.agent.hindsight` | Boolean | `true` | `PWN::AI::Agent::Curriculum.hindsight` (C3) | Hindsight Experience Replay — relabel a failed trajectory as `success:true` for whatever it *did* accomplish. Free positive samples from failures. |
+| `ai.agent.verify_as_reward` | Boolean | `false` | `PWN::AI::Agent::Reward.verify_as_reward` (E3) | Ground the LLM judge score by browser-verifying any checkable claim in the final via `extro_verify`; verdict caps/floors `Reward.judge`. |
 | `ai.agent.extrospection.web.anchors` | Array\<String\> | `DEFAULT_WEB_ANCHORS` | `PWN::AI::Agent::Extrospection.probe_web` | URLs the headless browser fingerprints on `extro_snapshot(sections:[:web])`. Alias: `web_anchors`. |
 | `ai.agent.extrospection.web.proxy` | String | - | `Extrospection.probe_web` / `.verify` / `.watch` | Upstream proxy for `PWN::Plugins::TransparentBrowser` (e.g. `tor`, `http://127.0.0.1:8080`). |
 | `ai.agent.extrospection.web.max_anchors` | Integer | `8` | `Extrospection.probe_web` | Cap on anchors rendered per snapshot. |
@@ -371,9 +379,14 @@ agent system prompt.
 
 `pwn.yaml` is the only file you edit; everything else is machine-written
 state. See **[Persistence](Persistence.md)** for the full map
-(`memory.json`, `memory.idx`, `learning.jsonl`, `mistakes.json`,
-`metrics.json`, `extrospection.json`, `sessions/`, `skills/`,
-`finetune/`, `cron/`, `agents.yml`, `swarm/`).
+(`.schema`, `memory.json`, `memory.idx`, `learning.jsonl`,
+`preferences.jsonl`, `mistakes.json`, `metrics.json`,
+`reward_sentinel.json`, `extrospection.json`, `sessions/`,
+`skills/<name>/SKILL.md`, `curriculum/`, `finetune/`, `cron/`,
+`agents.yml`, `swarm/`, `backup/`, `quarantine/`).
+
+`pwn setup --migrate` verifies (and `--fix` autorepairs) every
+one of them against the running gem version.
 
 Multi-agent personas are **not** configured here - they live in
 `~/.pwn/agents.yml` and are managed with `agent_spawn` / `agent_list`

data/documentation/Contributing.md

@@ -5,10 +5,11 @@
 ```text
 lib/pwn/                # all namespaces
 lib/pwn/setup.rb        # PWN::Setup - doctor/provisioner data tables
+lib/pwn/migrate.rb      # PWN::Migrate - ~/.pwn state doctor / auto-migrator
 lib/pwn/plugins/        # 66 plugin modules
 lib/pwn/ai/agent/       # agent core
 lib/pwn/ai/agent/tools/ # LLM tool registrations
-bin/                    # 53 pwn_* drivers (incl. pwn_setup)
+bin/                    # 52 pwn_* drivers + pwn (incl. pwn_setup)
 spec/                   # RSpec (incl. conventions_spec)
 documentation/          # this wiki + diagrams
 ```
@@ -44,7 +45,13 @@ rake            # rubocop + rspec - must be zero offenses
    set, reference it from `PWN::Setup::PROFILES`. That single edit makes
    `pwn setup` install it on every OS and every install path (gem, git,
    Docker, Packer, Vagrant, CI). **Do not** add a new bash provisioner.
-7. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
+7. **If it persists a new file under `~/.pwn/`**, add **one entry** to
+   `PWN::Migrate::STATE_FILES` in `lib/pwn/migrate.rb` (owner, kind,
+   `:fix` strategy, shallow verifier). If the change breaks *existing*
+   files, bump `PWN::Migrate::SCHEMA_VERSION` and append an idempotent
+   lambda to `PWN::Migrate::MIGRATIONS`. `pwn setup --migrate --fix`
+   then heals every user's `~/.pwn` on upgrade.
+8. Update [Plugins.md](Plugins.md) and, if it changes a data flow, the
    relevant `.dot` in `documentation/diagrams/dot/` → `./build.sh`.
 
 ## Commit / release

data/documentation/Cron.md

@@ -24,6 +24,26 @@ invokes `PWN::Cron.run(<id>)` on schedule.
 | `cron_enable` / `cron_disable` | Toggle without deleting |
 | `cron_remove` | Delete from `jobs.yml` (does **not** scrub crontab - `crontab -e` yourself) |
 
+## Seeded self-improvement jobs (`PWN::Cron.install_defaults`)
+
+`pwn setup --migrate` (schema `v1`) seeds two jobs into every fresh
+`~/.pwn/cron/jobs.yml`:
+
+| Name | Schedule | Ruby |
+|---|---|---|
+| `curriculum_practice_nightly` | `0 3 * * *` | `PWN::AI::Agent::Curriculum.practice(limit: 3)` |
+| `curriculum_train_weekly` | `0 4 * * 0` | `PWN::AI::Agent::Curriculum.train_and_gate(dry_run: true)` |
+
+The first practises the top unresolved `Mistakes` under `Reward.judge` and
+auto-`resolve`s any it now solves; the second exports SFT + DPO datasets to
+`~/.pwn/finetune/`, LoRA-trains a `pwn-vN+1` local model, replays the
+`Mistakes.top` set on both, and only promotes the new adapter when it wins.
+Set `dry_run: false` (via `pwn-ai-cron` or `cron_create`) once a local
+trainer is installed. See [Reinforcement Learning](Reinforcement-Learning.md).
+
+`cron_disable(id:)` turns either off; `install_defaults` is idempotent and
+never overwrites a job you already have with the same name.
+
 ## Example
 
 ```ruby
@@ -57,6 +77,6 @@ yyyy-mm-dd]` so the injected MEMORY block stops calcifying into
 confidently-wrong priors - see [Extrospection § revalidate_memory](Extrospection.md).
 
 **See also:** [Sessions](Sessions.md) · [Extrospection](Extrospection.md) ·
-[CLI Drivers](CLI-Drivers.md)
+[Reinforcement Learning](Reinforcement-Learning.md) · [CLI Drivers](CLI-Drivers.md)
 
 [← Home](Home.md)

data/documentation/Diagrams.md

@@ -1,6 +1,6 @@
 # PWN Data-Flow Diagrams
 
-27 SVG diagrams, all rendered from Graphviz sources in
+28 SVG diagrams, all rendered from Graphviz sources in
 [`diagrams/dot/`](diagrams/dot/) with a single shared visual theme
 (see [`_THEME.md`](diagrams/dot/_THEME.md)). Rebuild everything with:
 
@@ -55,11 +55,15 @@ groups) so lines never criss-cross.
 [source](diagrams/dot/mistakes-negative-feedback.dot) · doc: [Mistakes](Mistakes.md)
 ![mistakes-negative-feedback](diagrams/mistakes-negative-feedback.svg)
 
+### Reinforcement Learning - Reward + Curriculum
+[source](diagrams/dot/reinforcement-learning.dot) · doc: [Reinforcement Learning](Reinforcement-Learning.md)
+![reinforcement-learning](diagrams/reinforcement-learning.svg)
+
 ### Multi-Provider LLM Integration
 [source](diagrams/dot/ai-integration-tool-calling.dot) · doc: [AI Integration](AI-Integration.md)
 ![ai-integration-tool-calling](diagrams/ai-integration-tool-calling.svg)
 
-### Agent Tool Registry (10 toolsets · 61 tools)
+### Agent Tool Registry (10 toolsets · 71 tools)
 [source](diagrams/dot/agent-tool-registry.dot) · doc: [Agent Tool Registry](Agent-Tool-Registry.md)
 ![agent-tool-registry](diagrams/agent-tool-registry.svg)
 

data/documentation/Drivers.md

@@ -43,7 +43,7 @@ puts result
 | Artifact | Made with | Consumed by |
 |---|---|---|
 | `bin/pwn_<name>` | template above | shell / CI |
-| `~/.pwn/skills/<name>.md` | `learning_distill_skill` | every future pwn-ai prompt |
+| `~/.pwn/skills/<name>/SKILL.md` | `learning_distill_skill` | every future pwn-ai prompt |
 | `cron` job | `cron_create(ruby: '...')` | system crontab → unattended |
 
 **See also:** [CLI Drivers](CLI-Drivers.md) · [Cron](Cron.md) ·

data/documentation/General-PWN-Usage.md

@@ -14,9 +14,11 @@ $ pwn_nmap_discover_tcp_udp -t 10.0.0.0/24 -o out/   # headless driver
 $ pwn setup                   # doctor: which PWN:: capabilities are usable here?
 $ pwn setup --profile web     # install what TransparentBrowser / Burp / ZAP need
 $ pwn setup --list-profiles   # core · ai · web · net · db · sdr · vision · voice · exploit · hardware · full
+$ pwn setup --migrate --fix   # after `gem update pwn`: verify + autofix ~/.pwn state
 ```
 
-See [Installation](Installation.md) for every flag and the `PWN::Setup` API.
+See [Installation](Installation.md) for every flag and the
+`PWN::Setup` / `PWN::Migrate` API.
 
 ## Inside the REPL
 
@@ -25,6 +27,7 @@ PWN.help                            # top-level help
 PWN::Plugins.constants.sort         # list all 66 plugins
 PWN::Plugins::NmapIt.help           # per-plugin usage
 PWN::Setup.check                    # capability doctor from inside the REPL
+PWN::Migrate.status                 # ~/.pwn state-file compatibility rows
 ls PWN::Plugins::BurpSuite          # Pry: list methods
 show-source PWN::SAST::SQL.scan     # Pry: read the code
 history                             # what you've typed → copy into a driver
@@ -36,11 +39,14 @@ history                             # what you've typed → copy into a driver
 |---|---|
 | `pwn-ai` | Enter the agent TUI (SHIFT+ENTER = newline, ENTER = submit) |
 | `pwn-asm` | Multi-line assembly ↔ opcode workbench |
+| `pwn-mesh` | Meshtastic serial / MQTT client (Ruby ≥ 4.0) |
 | `pwn-vault` | Decrypt → edit `~/.pwn/pwn.yaml` in `$EDITOR` → re-encrypt |
 | `pwn-ai-memory` | Inspect / edit `~/.pwn/memory.json` |
 | `pwn-ai-sessions` | List / view / delete transcripts |
 | `pwn-ai-cron` | List / run scheduled jobs |
 | `pwn-ai-delegate` | Hand a task to a Swarm persona |
+| `toggle-pwn-ai-debug` | Show/hide raw tool_calls JSON |
+| `toggle-pwn-ai-speaks` | TTS every final answer on/off |
 | `welcome-banner` | Redraw a random `PWN::Banner` |
 | `toggle-pager` | Pry pager on/off |
 

data/documentation/Home.md

@@ -20,7 +20,7 @@
 | [Installation](Installation.md) | `gem install pwn` → `pwn setup` doctor/provisioner · capability profiles · `--migrate` state doctor |
 | [General Usage](General-PWN-Usage.md) | Day-one cheat sheet |
 | [Configuration](Configuration.md) | `~/.pwn/pwn.yaml` (encrypted) - engines, keys, agent options · `pwn-vault` |
-| **[All Data-Flow Diagrams](Diagrams.md)** | **27 SVGs** in one scrollable page |
+| **[All Data-Flow Diagrams](Diagrams.md)** | **28 SVGs** in one scrollable page |
 
 ## 🚪 Entry Points
 

data/documentation/How-PWN-Works.md

@@ -19,52 +19,66 @@ hardware).
 | `pwn` REPL | `lib/pwn/plugins/repl.rb` | Pry with `PWN::` pre-loaded + custom commands |
 | `pwn-ai` | `lib/pwn/ai/agent/loop.rb` | Agent TUI inside the REPL |
 | `pwn --ai PROMPT` | `bin/pwn` | Headless one-shot agent (CI-friendly) |
-| `pwn setup` | `lib/pwn/setup.rb` · `bin/pwn_setup` | Post-install doctor + capability provisioner (also `pwn --setup[=PROFILE]`) |
-| `bin/pwn_*` | 53 files | Thin OptionParser wrappers over one plugin each |
-| `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs → any of the above |
+| `pwn setup` | `lib/pwn/setup.rb` · `bin/pwn_setup` | Post-install doctor + capability provisioner + `--migrate` state doctor (also `pwn --setup[=PROFILE]`) |
+| `bin/pwn_*` | 52 files | Thin OptionParser wrappers over one plugin each |
+| `PWN::Cron` | `lib/pwn/cron.rb` | Scheduled jobs → any of the above (nightly self-play + weekly weight-loop seeded by default) |
 
 ## L2 - AI agent core  (`lib/pwn/ai/agent/`)
 
 | Module | Role |
 |---|---|
 | `Loop` | plan → dispatch tool_calls → observe → repeat until final answer |
-| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · 61 tools |
+| `Registry` | JSON-Schema function definitions grouped into 10 **toolsets** · **71 tools** |
 | `Dispatch` / `Result` | execute a tool, capture stdout/value/error/duration |
 | `PromptBuilder` | inject MEMORY / SKILLS / LEARNING / **KNOWN MISTAKES + FIXES** / METRICS / EXTROSPECTION blocks |
-| `Metrics` · `Learning` | **introspection** - how well am I doing? |
+| `Metrics` · `Learning` · `Reflect` | **introspection** - how well am I doing? |
 | `Mistakes` | **negative feedback** - fingerprint failures, do NOT repeat, `[REPEATING]`/`[REGRESSED]`, inline `correction_hint` |
-| `Extrospection` | **extrospection** - on-demand world sensing (`intel` · **`verify`** · **`watch`** · **`rf_tune`**) + ambient baseline (host · net · toolchain · repo · env · **rf** · **web**) joined to introspection via `correlate` |
+| **`Reward`** | **R1** ORM `judge` · **R2** PRM per-step credit · **R3** `sentinel` reward-hacking detector · **R4** `semantic_ok` · **W1** DPO `preferences.jsonl` |
+| **`Curriculum`** | **S1** mistake-driven self-play `practice` · **S2** `counterfactual` A/B · **S3** tool-armed `critic` · **S4** `red_team_plan` · **C3** `hindsight` (HER) · **W2** `train_and_gate` regression-gated LoRA |
+| `Extrospection` | **extrospection** - on-demand world sensing (`intel` · **`verify`** · **`watch`** · **`rf_tune`** · **`osint`** · `serial` · `telecomm` · `packet` · `vision` · `voice`) + ambient baseline (host · net · toolchain · repo · env · **rf** · **web**) joined to introspection via `correlate` |
 | `Swarm` | multi-agent personas over a shared JSONL bus |
 
-See [Agent Tool Registry](Agent-Tool-Registry.md) for every tool the LLM can call.
+See [Agent Tool Registry](Agent-Tool-Registry.md) for every tool the LLM can
+call, and [Reinforcement Learning](Reinforcement-Learning.md) for how
+`Reward` + `Curriculum` close the weight-level loop.
 
 ## L3 - Capability namespaces  (`lib/pwn/*`)
 
 `Plugins` (66) · `SAST` (48) · `WWW` (21) · `AWS` (90) · `SDR` · `Blockchain` ·
-`Bounty` · `Reports` · `FFI` · `Banner`. Each is a plain module of
-`public_class_method def self.x(opts = {})` methods - callable identically from
-the REPL, from `pwn_eval`, or from a driver.
+`Bounty` · `Reports` · `FFI` · `Banner` · **`Setup`** · **`Migrate`**. Each is
+a plain module of `public_class_method def self.x(opts = {})` methods -
+callable identically from the REPL, from `pwn_eval`, or from a driver.
 
 ## L4 - Persistence  (`~/.pwn/`)
 
-Everything the framework remembers between processes lives in one directory:
+Everything the framework remembers between processes lives in one directory.
+`PWN::Migrate` (schema-stamped, idempotent, dry-run capable) verifies and
+autofixes every file in it after a `gem update pwn`:
 
 ![~/.pwn map](diagrams/persistence-filesystem.svg)
 
-See [Persistence](Persistence.md) for the byte-level layout of each file.
+See [Persistence](Persistence.md) for the byte-level layout of each file and
+[Installation § Upgrading](Installation.md#upgrading--pwn-state-migration-pwnmigrate)
+for the migrator.
 
 ## The feedback loop
 
 The reason L2 exists is to close this loop on every turn - successes
 become skills/lessons, **failures become fingerprinted mistakes with fixes**,
 **world-state is sensed on demand** (`extro_verify` / `extro_watch` /
-`extro_rf_tune` / `extro_osint` / `extro_serial` / `extro_telecomm` / `extro_packet` / `extro_vision` / `extro_voice` / `extro_intel`) and correlated against those failures, and
-**all six prompt blocks** (MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES ·
-TOOL EFFECTIVENESS · EXTROSPECTION) are re-injected into the very next system
-prompt:
+`extro_rf_tune` / `extro_osint` / `extro_serial` / `extro_telecomm` /
+`extro_packet` / `extro_vision` / `extro_voice` / `extro_intel`) and
+correlated against those failures, an **LLM judge scores the final** and a
+**process reward model tags each tool step**, and **all six prompt blocks**
+(MEMORY · SKILLS · LEARNING · KNOWN MISTAKES/FIXES · TOOL EFFECTIVENESS ·
+EXTROSPECTION) are re-injected into the very next system prompt.
+Nightly cron practises the top unresolved Mistakes; weekly cron cuts a
+LoRA and only promotes it if it beats the previous adapter on that same
+mistake set:
 
 ![Self-improvement loop](diagrams/pwn-ai-feedback-learning-loop.svg)
 
-**Next:** [pwn REPL](pwn-REPL.md) · [pwn-ai Agent](pwn-ai-Agent.md)
+**Next:** [pwn REPL](pwn-REPL.md) · [pwn-ai Agent](pwn-ai-Agent.md) ·
+[Reinforcement Learning](Reinforcement-Learning.md)
 
 [← Home](Home.md)