pwn 0.5.635 → 0.5.637

data/documentation/Installation.md

@@ -59,9 +59,9 @@ Prints a per-capability report and **exits non-zero if anything is degraded**
 (so you can gate CI on it):
 
 ```text
-PWN v0.5.628 · ruby 4.0.5 · linux x86_64 · pkg-manager: apt
+PWN vCURRENT_VERSION · ruby 4.0.5 · linux x86_64 · pkg-manager: apt
 
-~/.pwn/                    ok   (11 entries)
+~/.pwn/                    ok   (13 entries · schema v1)
 ~/.pwn/pwn.yaml            ok   (encrypted, decryptor present)
 AI engine                  ok   anthropic (key set)
 
@@ -76,6 +76,12 @@ External toolchain                              used by
   gqrx           MISSING                        PWN::SDR, extro_rf_tune
   ...
 
+~/.pwn state files                              owner
+  pwn.yaml       ok                             PWN::Config
+  memory.json    ok                             PWN::Memory
+  skills/        drift  1 legacy flat file(s)   PWN::Config     → run --migrate --fix
+  ...
+
 31 / 36 capabilities usable · 5 degraded
 
 Run `pwn setup --deps` to install missing OS headers/tools, or
@@ -113,7 +119,7 @@ pwn setup --list-profiles
 | `ai` | verify at least one AI engine key/oauth in `~/.pwn/pwn.yaml` |
 | `web` | `TransparentBrowser` · `BurpSuite` · `Zaproxy` · `extro_verify` · `extro_watch` · `sqlmap` · `tor` |
 | `net` | `NmapIt` · `Packet` · `extro_packet` · `extro_osint` · `tshark`/`tcpdump` |
-| `db` | `DAOPostgres` · `DAOSqlite3` · `DAOMongo` |
+| `db` | `DAOPostgres` · `DAOSQLite3` · `DAOMongo` |
 | `sdr` | `PWN::SDR` · GQRX · `PWN::FFI` DSP backends · `extro_rf_tune` · rtl-sdr / hackrf / SoapySDR |
 | `vision` | `OCR` · `ScannableCodes` · `Reports` · `extro_vision` · tesseract / zbar / graphviz |
 | `voice` | `PWN::Plugins::Voice` · `extro_voice` · espeak-ng / sox |
@@ -125,7 +131,7 @@ pwn setup --list-profiles
 
 ```text
 pwn setup [--check] [--deps] [--profile NAME] [--list-profiles]
-          [--yes] [--dry-run]
+          [--migrate [--fix]] [--yes] [--dry-run]
 ```
 
 | Flag | Meaning |
@@ -134,11 +140,63 @@ pwn setup [--check] [--deps] [--profile NAME] [--list-profiles]
 | `-d`, `--deps` | Install OS packages + rebuild native gems for `--profile` (default `full`). |
 | `-p`, `--profile NAME` | One of the profiles above. Implies `--deps`. |
 | `-l`, `--list-profiles` | Print profile table and exit. |
-| `-y`, `--yes` | Assume yes; non-interactive (CI / Docker / Packer). |
+| **`-m`, `--migrate`** | **Verify every `~/.pwn` state file against this pwn version; apply schema migrations. See below.** |
+| **`-f`, `--fix`** | **With `--migrate`: also autofix incompatible files (timestamped backup taken first).** |
+| `-y`, `--yes` | Assume yes; non-interactive (CI / Docker / Packer). Also implies `--fix` when combined with `--migrate`. |
 | `-n`, `--dry-run` | Print the commands that *would* run, do nothing. |
 
 ---
 
+## Upgrading — `~/.pwn` state migration (`PWN::Migrate`)
+
+PWN persists a growing set of files under `~/.pwn` (encrypted config,
+memory, learning, metrics, mistakes, extrospection, cron, agents, skills,
+sessions, swarm, curriculum, finetune, …). Each file is owned by a different
+module and each release can add keys or change shape. `PWN::Migrate` closes
+that gap so `gem update pwn` never leaves you with a `KeyError` or a silent
+empty-fallback.
+
+```bash
+gem update pwn
+pwn setup --migrate            # verify + apply schema migrations (backup taken)
+pwn setup --migrate --fix      # also autofix incompatible files
+pwn setup --migrate --dry-run  # report only, write nothing
+```
+
+What `--migrate` does:
+
+1. **Stamp** `~/.pwn/.schema` with `{ schema:, pwn_version:, at: }`. Any
+   release that changes the on-disk shape of a `~/.pwn` file bumps
+   `PWN::Migrate::SCHEMA_VERSION` and appends an idempotent lambda to
+   `PWN::Migrate::MIGRATIONS`.
+2. **Verify** every state file against its owning module's *own* loader
+   (`PWN::Migrate::STATE_FILES` - no re-implemented parsers). If the raw
+   file has bytes but the owner returned its empty-fallback, the file is
+   flagged incompatible.
+3. **Autofix** (with `--fix`): timestamped backup under `~/.pwn/backup/<ts>/`
+   → ordered schema migrations → per-file repair (quarantine corrupt to
+   `~/.pwn/quarantine/`, re-seed missing dirs, strip unparsable JSONL lines,
+   convert legacy flat skills to the [agentskills.io](https://agentskills.io)
+   directory layout) → **deep-merge** any keys the current
+   `PWN::Config.env_template` added into your encrypted `~/.pwn/pwn.yaml`
+   **without overwriting your values** (re-encrypted with the same key/IV).
+
+Everything is idempotent and dry-run capable. The plain `pwn` launcher also
+prints a one-line drift warning on startup whenever `~/.pwn/.schema`
+predates the running gem (`PWN::Migrate.needed?`).
+
+Schema `v1` also seeds `PWN::Cron.install_defaults` — the nightly
+`curriculum_practice` and weekly `curriculum_train` self-improvement jobs
+(see [Reinforcement Learning](Reinforcement-Learning.md)).
+
+From a checkout:
+
+```bash
+cd /opt/pwn && git pull && rake install && pwn setup --migrate --fix
+```
+
+---
+
 ## From a git checkout (contributors)
 
 ```bash
@@ -178,21 +236,6 @@ pwn setup --profile ${PWN_PROFILE:-full} --yes
 
 ---
 
-## Upgrading
-
-```bash
-gem update pwn         # or: gem uninstall --all --executables pwn && gem install pwn
-pwn setup              # re-doctor - new versions may add capabilities
-```
-
-From a checkout:
-
-```bash
-cd /opt/pwn && git pull && rake install && pwn setup
-```
-
----
-
 ## First-run configuration
 
 The first `pwn` launch creates `~/.pwn/` and an **encrypted**
@@ -203,25 +246,38 @@ row as `MISSING` until a key is set.
 
 ---
 
-## Programmatic API - `PWN::Setup`
+## Programmatic API - `PWN::Setup` / `PWN::Migrate`
 
-Everything above is a thin CLI over one autoloaded module:
+Everything above is a thin CLI over two autoloaded modules:
 
 ```ruby
-PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, pkg_manager:, os:, arch: }
+PWN::Setup.check                          # → { ok:, native_gems_missing:, toolchain_missing:, state:, pkg_manager:, os:, arch: }
 PWN::Setup.deps(profile: :web, yes: true) # install, then re-check
 PWN::Setup.list_profiles
+PWN::Setup.migrate(fix: true)             # thin wrapper → PWN::Migrate.run
 PWN::Setup.pkg_manager                    # → { key: :apt, install: 'sudo apt-get install -y', sudo: true }
 
 # The data tables - single source of truth, versioned with the gem:
 PWN::Setup::NATIVE_GEMS   # native ext  → { apt:, dnf:, pacman:, brew:, port:, plugins: }
 PWN::Setup::TOOLCHAIN     # external bin → { apt:, dnf:, pacman:, brew:, port:, plugins: }
 PWN::Setup::PROFILES      # profile      → { desc:, gems:, bins: }
+
+# ~/.pwn state doctor / auto-migrator (lib/pwn/migrate.rb)
+PWN::Migrate.needed?                      # cheap: schema stamp < SCHEMA_VERSION ?
+PWN::Migrate.status                       # per-file compatibility rows (never writes)
+PWN::Migrate.check                        # human report + { compatible:[], incompatible:[], missing:[] }
+PWN::Migrate.run(fix: true, dry_run:false)# backup → ordered migrations → per-file repair → vault backfill
+PWN::Migrate.vault_drift                  # keys env_template has that your pwn.yaml is missing
+PWN::Migrate.backfill_vault               # deep-merge those keys under your values, re-encrypt
+PWN::Migrate::STATE_FILES                 # declarative registry of every ~/.pwn artefact
+PWN::Migrate::SCHEMA_VERSION              # bump when a state file changes shape
 ```
 
 Adding a new native dependency or wrapped binary? Add **one row** to the
-appropriate constant in `lib/pwn/setup.rb` - every install path (gem, git,
-Docker, Packer, Vagrant, CI) picks it up automatically.
+appropriate constant in `lib/pwn/setup.rb`. Adding a new persisted state
+file under `~/.pwn`? Add **one entry** to `PWN::Migrate::STATE_FILES` in
+`lib/pwn/migrate.rb` - every install path (gem, git, Docker, Packer,
+Vagrant, CI) picks it up automatically.
 
 ---
 
@@ -229,11 +285,12 @@ Docker, Packer, Vagrant, CI) picks it up automatically.
 
 ```ruby
 pwn[CURRENT_VERSION]:001 >>> PWN::Setup.check[:ok]          # => true
-pwn[CURRENT_VERSION]:002 >>> PWN::Plugins.constants.count   # => 66
-pwn[CURRENT_VERSION]:003 >>> PWN::SAST.constants.count      # => 48
-pwn[CURRENT_VERSION]:004 >>> pwn-ai                         # launches agent TUI
+pwn[CURRENT_VERSION]:002 >>> PWN::Migrate.needed?           # => false
+pwn[CURRENT_VERSION]:003 >>> PWN::Plugins.constants.count   # => 66
+pwn[CURRENT_VERSION]:004 >>> PWN::SAST.constants.count      # => 48
+pwn[CURRENT_VERSION]:005 >>> pwn-ai                         # launches agent TUI
 ```
 
-**Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md)
+**Next:** [Configuration](Configuration.md) · [General Usage](General-PWN-Usage.md) · [Persistence](Persistence.md)
 
 [← Home](Home.md)

data/documentation/Persistence.md

@@ -8,29 +8,55 @@ Every byte PWN remembers between processes lives here.
 |---|---|---|---|---|
 | `pwn.yaml` | `PWN::Config` · `PWN::Plugins::Vault` | AES-encrypted YAML | `pwn-vault` | engines, keys, agent options |
 | `pwn.yaml.decryptor` | `PWN::Plugins::Vault` | key/IV | - | decrypts `pwn.yaml` (or set `PWN_DECRYPTOR_KEY`/`_IV`) |
+| **`.schema`** | **`PWN::Migrate`** | JSON `{schema:,pwn_version:,at:}` | `pwn setup --migrate` | **schema stamp - drives the one-line drift warning on launch** |
 | `memory.json` | `PWN::Memory` | JSON array | `memory_clear` | facts · prefs · lessons · env - injected into every prompt |
 | `memory.idx` | `PWN::MemoryIndex` | JSON `{key → {sha,vec}}` | `PWN::MemoryIndex.reset` | local embedding index over `memory.json` - powers **relevance-ranked** MEMORY injection (incremental; only re-embeds changed entries) |
-| `finetune/*.jsonl` | `PWN::AI::Agent::Learning.export_finetune` | ShareGPT / OpenAI JSONL | `rm` | supervised dataset cut from every successful session - feed to a LoRA over the local model |
-| `skills/*.md` | `PWN::Config.load_skills` | Markdown + YAML front-matter | `skill_delete` | reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST) |
+| `skills/<name>/SKILL.md` | `PWN::Config.load_skills` | **[agentskills.io](https://agentskills.io) spec** - `name`+`description` YAML front-matter | `skill_delete` | reusable procedures + `metadata.references:` (CWE/CVE/ATT&CK/NIST). Legacy flat `skills/*.md` auto-migrated by `skill_migrate_legacy` / `pwn setup --migrate --fix`. |
 | `learning.jsonl` | `PWN::AI::Agent::Learning` | JSON-per-line | `learning_reset` | task outcome log → success_rate |
+| **`preferences.jsonl`** | **`PWN::AI::Agent::Reward`** | JSON-per-line `{prompt,rejected,chosen,source}` | `rm` | **DPO/KTO/ORPO preference-pair ledger - user_correction · mistakes_resolve · counterfactual · critic · curriculum** |
 | **`mistakes.json`** | **`PWN::AI::Agent::Mistakes`** | **JSON `{sig → entry}`** | **`mistakes_reset`** | **failure fingerprints · cross-session count · fix · `[REPEATING]` · `[REGRESSED]`** |
-| `metrics.json` | `PWN::AI::Agent::Metrics` | JSON | `metrics_reset` | per-tool calls · success · avg_duration · last_error · **per-engine** sub-buckets |
-| `extrospection.json` | `PWN::AI::Agent::Extrospection` | JSON | `extro_reset` | host/net/toolchain/repo/env/**rf**/**web** snapshot + previous baseline + observations[] |
-| `extrospection/web/*.png` | `PWN::AI::Agent::Extrospection` | PNG | `rm -rf` | headless-browser screenshots from `probe_web` / `extro_watch` (opt-in) |
-| `sessions/*.jsonl` | `PWN::Sessions` | JSON-per-line | `sessions_delete` | full transcript per pwn-ai run |
-| `cron/jobs.yml` | `PWN::Cron` | YAML | `cron_remove` | scheduled prompt/ruby/script jobs |
+| `metrics.json` | `PWN::AI::Agent::Metrics` | JSON | `metrics_reset` | per-tool calls · success · avg_duration · last_error · **per-engine** sub-buckets · calibration |
+| `reward_sentinel.json` | `PWN::AI::Agent::Reward` | JSON | `rm` | R3 - proxy vs judge vs user-correction gap history |
+| `extrospection.json` | `PWN::AI::Agent::Extrospection` | JSON | `extro_reset` | host/net/toolchain/repo/env/**rf**/**web**/osint/serial/telecomm/packet/vision/voice snapshot + previous baseline + observations[] |
+| `extrospection/web/*.png` | `Extrospection` | PNG | `rm -rf` | headless-browser screenshots from `probe_web` / `extro_watch` (opt-in) |
+| `extrospection/packet/*.pcap` | `Extrospection` | pcap | `rm -rf` | bounded captures from `extro_packet(action: :capture)` |
+| `extrospection/voice/*` | `Extrospection` | wav / txt | `rm -rf` | TTS/STT artifacts from `extro_voice` |
+| `sessions/*.jsonl` | `PWN::Sessions` | JSON-per-line | `sessions_delete` | full transcript per pwn-ai run (with per-step `step_reward` from `Reward.prm`) |
+| `cron/jobs.yml` | `PWN::Cron` | YAML | `cron_remove` | scheduled prompt/ruby/script jobs (**seeded** with `curriculum_practice_nightly` + `curriculum_train_weekly`) |
 | `cron/log/*.log` | `PWN::Cron` | text | rm | last_run output |
 | `agents.yml` | `PWN::AI::Agent::Swarm` | YAML | edit / `agent_spawn` | persona registry |
 | `swarm/<id>/bus.jsonl` | `Swarm` | JSON-per-line | rm -rf | append-only multi-agent chat |
 | `swarm/<id>/personas.json` | `Swarm` | JSON | rm | persona → session_id map |
+| `curriculum/` | `PWN::AI::Agent::Curriculum` | JSONL | rm -rf | S1 self-play reproducers · W2 A/B eval sets |
+| `finetune/*.jsonl` | `Learning.export_finetune` · `Reward.export_dpo` | ShareGPT / OpenAI / DPO JSONL | `rm` | supervised + preference datasets - feed to a LoRA over the local model |
+| `backup/<ts>/` | `PWN::Migrate` | tree copy | rm -rf | timestamped snapshot taken before every `--migrate --fix` |
+| `quarantine/` | `PWN::Migrate` | quarantined originals | rm -rf | corrupt/incompatible state files moved aside so the owner re-seeds |
 | `~/.pwn_history` | Pry | text | rm | REPL input history |
 
+## Verify / repair the whole tree
+
+```bash
+pwn setup --migrate            # per-file compatibility report + apply schema migrations
+pwn setup --migrate --fix      # + autofix (backup → quarantine/repair → vault backfill)
+```
+
+```ruby
+PWN::Migrate.status            # machine-readable rows
+PWN::Migrate.needed?           # ~/.pwn/.schema older than PWN::Migrate::SCHEMA_VERSION ?
+```
+
+See [Installation § Upgrading](Installation.md#upgrading--pwn-state-migration-pwnmigrate)
+for the full `PWN::Migrate` API.
+
 ## Back it up
 
 ```bash
 tar czf pwn-state-$(date +%F).tgz -C "$HOME" .pwn
 ```
 
+`pwn setup --migrate --fix` also writes one automatically to
+`~/.pwn/backup/<timestamp>/` before touching anything.
+
 ## Start fresh for a new engagement
 
 ```ruby
@@ -41,4 +67,4 @@ learning_reset(confirm: true)  # task outcomes (optional)
 metrics_reset(confirm: true)   # tool telemetry (optional)
 ```
 
-[← Home](Home.md) · [Configuration](Configuration.md)
+[← Home](Home.md) · [Configuration](Configuration.md) · [Installation](Installation.md)

data/documentation/Plugins.md

@@ -54,7 +54,7 @@ show-source PWN::Plugins::Fuzz.generate
 ### Data Access / Parsing
 | Module | Purpose |
 |---|---|
-| `DAOLdap` · `DAOMongo` · `DAOPostgres` · `DAOSqlite3` | DB clients |
+| `DAOLDAP` · `DAOMongo` · `DAOPostgres` · `DAOSQLite3` | DB clients |
 | `JSONPathify` | JSONPath query |
 | `PDFParse` · `OCR` | document extraction |
 | `ScannableCodes` | QR/barcode gen/read |
@@ -92,17 +92,17 @@ show-source PWN::Plugins::Fuzz.generate
 | `RabbitMQ` | AMQP |
 
 ### Utility
-`FileFu` · `ThreadPool` · `Log` · `PwnLogger` · `Char` · `XXD` · `DetectOS` ·
+`FileFu` · `ThreadPool` · `Log` · `PWNLogger` · `Char` · `XXD` · `DetectOS` ·
 `CreditCard` · `SSN` · `EIN` · `VIN` · `PS` · `MonkeyPatch` · `REPL`
 
 ## Full alphabetical list
 
 `Android Assembly AuthenticationHelper BareSIP BasicAuth BeEF
-BlackDuckBinaryAnalysis BurpSuite BusPirate Char CreditCard DAOLdap DAOMongo
-DAOPostgres DAOSqlite3 DefectDojo DetectOS EIN FileFu Fuzz Git Github
+BlackDuckBinaryAnalysis BurpSuite BusPirate Char CreditCard DAOLDAP DAOMongo
+DAOPostgres DAOSQLite3 DefectDojo DetectOS EIN FileFu Fuzz Git Github
 HackerOne Hunter IPInfo IRC Jenkins JiraDataCenter JSONPathify Log MailAgent
 Metasploit MonkeyPatch MSR206 NessusCloud NexposeVulnScan NmapIt OAuth2 OCR
-OpenAPI OpenVAS Packet PDFParse Pony PS PwnLogger RabbitMQ REPL ScannableCodes
+OpenAPI OpenVAS Packet PDFParse Pony PS PWNLogger RabbitMQ REPL ScannableCodes
 Serial Shodan SlackClient Sock Spider SSN ThreadPool Tor TransparentBrowser
 TwitterAPI URIScheme Vault VIN Voice Vsphere XXD Zaproxy`
 

data/documentation/Reinforcement-Learning.md

@@ -6,6 +6,8 @@ LATS, Generative Agents, PRM, RLAIF, DPO, Self-Refine, Toolformer, DSPy)
 on at least one axis, and on **five axes simultaneously** for the full
 `Curriculum.practice → Reward.export_dpo → Curriculum.train_and_gate` path.
 
+![Reinforcement-learning loop](diagrams/reinforcement-learning.svg)
+
 ```
                        ┌────────────────────────────────────────────────┐
         request ──────►│ Loop.run                                       │
@@ -121,3 +123,8 @@ PWN::Cron.create(name: 'mem_gc',      schedule: '0 5 * * *',
 3. **Reward-hacking self-detection** (R3)
 4. **Mistake-driven curriculum with regression-gated LoRA promotion** (S1+W2)
 5. **Five naturally-generated DPO sources** with zero human labelling (W1)
+
+**See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·
+[Mistakes](Mistakes.md) · [Cron](Cron.md) · [pwn-ai Agent](pwn-ai-Agent.md)
+
+[← Home](Home.md)

data/documentation/Sessions.md

@@ -9,7 +9,11 @@ appended as JSON-per-line to `~/.pwn/sessions/<id>.jsonl`.
 
 - `learning_reflect(session_id:)` mines them for durable lessons → Memory.
 - `learning_distill_skill(name:, session_id:)` turns a winning run into a
-  reusable Skill.
+  reusable Skill (only steps with `step_reward > 0` are kept — the minimal
+  sufficient trace).
+- `Reward.prm(request:, session_id:)` back-labels every tool step in the
+  transcript with `step_reward: +1/0/−1` for credit assignment.
+- `Reward.judge(request:, final:, session_id:)` grades the whole run.
 - `sessions_view` lets you (or a later agent) re-read exactly what happened.
 - Swarm maps each persona to its own session so its private context survives
   across `agent_ask` calls.
@@ -30,7 +34,7 @@ appended as JSON-per-line to `~/.pwn/sessions/<id>.jsonl`.
 {"role":"system","ts":"2026-07-07T22:08:02Z","content":"..."}
 {"role":"user","ts":"...","content":"..."}
 {"role":"assistant","ts":"...","content":"...","tool_calls":[...]}
-{"role":"tool","ts":"...","name":"shell","content":"..."}
+{"role":"tool","ts":"...","name":"shell","content":"...","step_reward":1}
 ```
 
 **See also:** [Skills, Memory & Learning](Skills-Memory-Learning.md) ·

data/documentation/Skills-Memory-Learning.md

@@ -11,7 +11,7 @@ its own performance, turns wins into permanent capability, and - critically -
 | Store | File | Write tool | Read tool | Injected as |
 |---|---|---|---|---|
 | **Memory** | `memory.json` (+ `memory.idx`) | `memory_remember` | `memory_recall` · `PWN::MemoryIndex.recall_semantic` | `MEMORY` block - durable facts / prefs / lessons / env. **Relevance-ranked** for the current request via a local embedding index when `ai.ollama.embed_model` is available; falls back to newest-first otherwise. |
-| **Skills** | `skills/*.md` | `skill_create` · `learning_distill_skill` | `skill_list` · `skill_view` | `SKILLS` list - reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST/URL) |
+| **Skills** | `skills/<name>/SKILL.md` | `skill_create` · `skill_migrate_legacy` · `learning_distill_skill` | `skill_list` · `skill_view` | `SKILLS` list - reusable procedures + `references:` (CWE/CVE/ATT&CK/NIST/URL) |
 | **Learning** | `learning.jsonl` | `learning_note_outcome` · `learning_reflect` | `learning_outcomes` · `learning_stats` · `Learning.exemplars_for` | `LEARNING` block - recent outcomes + success_rate. Prior *successful* traces are also spliced in as **few-shot exemplars** for local models. |
 | **Mistakes** | `mistakes.json` | `mistakes_record` · `mistakes_resolve` · *auto on failure* | `mistakes_list` | `KNOWN MISTAKES` + `KNOWN FIXES` blocks - do-NOT-repeat + do-THIS-instead |
 | **Metrics** | `metrics.json` | *automatic* (every Dispatch) | `metrics_summary` | `TOOL EFFECTIVENESS` block - steer tool choice. **Segmented per engine** (`engine=...`) so a local model's telemetry never blends with a frontier model's. |
@@ -51,16 +51,26 @@ dongle unplugged, target DOM moved). See **[Mistakes](Mistakes.md)** for the
 negative-feedback mechanics and **[Extrospection](Extrospection.md)** for the
 outward half.
 
-## Skill file format
+## Skill file format ([agentskills.io](https://agentskills.io) spec)
+
+Each skill lives in its own directory as `~/.pwn/skills/<name>/SKILL.md`.
+The name is sanitised to `[a-z0-9-]{1,64}`. Front-matter **must** carry
+`name` + `description`; `metadata.references` and `allowed-tools` are
+optional.
 
 ```markdown
 ---
-references:
-  - CWE-89
-  - T1190
-  - https://portswigger.net/web-security/sql-injection
+name: sqli-union-enum
+description: Manual UNION-based SQLi column enumeration and data extraction.
+license: MIT
+allowed-tools: [terminal, pwn, extrospection]
+metadata:
+  references:
+    - CWE-89
+    - T1190
+    - https://portswigger.net/web-security/sql-injection
 ---
-# sqli_union_enum
+# sqli-union-enum
 
 1. Confirm injection with `' AND 1=1 --`.
 2. Find column count with `ORDER BY n`.
@@ -71,10 +81,16 @@ references:
 - T1190
 ```
 
-`PWN::Config.parse_skill_references` reads both the YAML front-matter **and**
-the `## References` section, deduplicates, and exposes them via
+`PWN::Config.parse_skill_references` reads both the YAML `metadata.references`
+**and** the `## References` section, deduplicates, and exposes them via
 `skill_view(name)[:references]`.
 
+Legacy flat `~/.pwn/skills/*.md` files are still read, but
+`skill_migrate_legacy` (also run by `pwn setup --migrate --fix`) converts
+them in-place to the spec-conformant `<name>/SKILL.md` layout with
+back-filled `name`/`description` front-matter. `skill_create` always writes
+the new format.
+
 ## Housekeeping
 
 | Tool | When |
@@ -135,7 +151,7 @@ when deciding which side of the loop to exercise.
 
 - "Which tools have the lowest success rate right now?"
 - "How often has `shell` been called, and what's its avg duration?"
-- "Is `extro_rf_tune` healtheir than the old GQRX helpers by metrics?"
+- "Is `extro_rf_tune` healthier than the old GQRX helpers by metrics?"
 - "Reset metrics after we fixed the broken tool so the 0 % doesn't steer us away." *(destructive)*
 
 ### Sessions / transcripts (`sessions_list`, `sessions_view`, `sessions_current`, `sessions_stats`, `sessions_delete`)

data/documentation/Troubleshooting.md

@@ -20,6 +20,29 @@ $ pwn setup --deps --dry-run     # show the apt/dnf/pacman/brew/port commands wi
 See [Installation](Installation.md#pwn-setup--the-post-install-doctor--provisioner)
 for the full profile table and `PWN::Setup` API.
 
+## `[pwn] ~/.pwn schema is stale — run pwn setup --migrate` on launch
+
+Your `~/.pwn` state files were written by an older PWN release than the one
+now running. The launcher checks `PWN::Migrate.needed?` on every start.
+
+```bash
+$ pwn setup --migrate            # verify each state file against its owning module
+$ pwn setup --migrate --fix      # + backup → schema migrations → repair → vault backfill
+$ pwn setup --migrate --dry-run  # report only
+```
+
+Corrupt / incompatible files are moved to `~/.pwn/quarantine/` (never
+deleted); a full timestamped backup is written to `~/.pwn/backup/<ts>/`
+first. Missing config keys added by the new release are deep-merged into
+your encrypted `~/.pwn/pwn.yaml` **under** your existing values. See
+[Installation § Upgrading](Installation.md#upgrading--pwn-state-migration-pwnmigrate).
+
+## `KeyError` / `NoMethodError for nil` reading memory / metrics / mistakes / cron / agents
+
+Same cause — the on-disk shape predates the current loader.
+`pwn setup --migrate --fix` will quarantine or repair the offending file
+and re-seed a valid one on next write.
+
 ## `LoadError` / `cannot load such file -- pg` (or rmagick, pcaprub, ...)
 
 A native extension failed to compile because its OS headers weren't present

data/documentation/What-is-PWN.md

@@ -18,10 +18,11 @@ tool-calling AI agent** on top of it.
 | `PWN::SAST::*` | **48** | Static-analysis rules across C/Java/Go/Python/Ruby/Scala/PHP/TS |
 | `PWN::AWS::*` | **90** | One module per AWS service for cloud enumeration |
 | `PWN::WWW::*` | **21** | Site-specific browser automations (HackerOne, BugCrowd, Google, LinkedIn, ...) |
-| `PWN::SDR::*` | **6** | GQRX, FlipperZero, RFIDler, SonMicro, decoders, band tables |
+| `PWN::SDR::*` | **6** (+ **20** decoders) | GQRX, FlipperZero, RFIDler, SonMicro, band tables, `Decoder::{ADSB,POCSAG,RDS,LoRa,...}` |
+| `PWN::FFI::*` | **8** | Native DSP/RF backends: Volk · Liquid · FFTW · RTLSdr · HackRF · AdalmPluto · SoapySDR · Stdio |
 | `PWN::AI::*` | **5** engines | OpenAI, Anthropic, Grok (OAuth device-flow), Gemini, Ollama |
 | `bin/pwn_*` | **53** | Headless CLI drivers for CI/CD |
-| Agent toolsets | **10** | terminal · pwn · memory · skills · sessions · learning · metrics · extrospection · cron · swarm |
+| Agent toolsets | **10** · **71 tools** | terminal · pwn · memory · skills · sessions · learning · metrics · extrospection · cron · swarm |
 
 ## The three ways to use it
 
@@ -37,13 +38,18 @@ tool-calling AI agent** on top of it.
 - **Everything is Ruby, everything is a method.** No YAML DSLs, no plugins-in-a-
   black-box. If you can call it in the REPL, the AI agent can call it, a driver
   can call it, and a cron job can call it.
-- **Closed self-improvement loop.** Metrics + Learning (introspection) and
-  Snapshot + Drift + Intel (extrospection) feed `extro_correlate`, which tells
-  the agent whether a failure was *its* fault or *the world* changed - and
-  writes the lesson back into the prompt for next time.
+- **Closed self-improvement loop.** Metrics + Learning + **Reward** (ORM/PRM
+  judge, sentinel) + **Curriculum** (mistake-driven self-play, HER,
+  regression-gated LoRA) on the introspection side; Snapshot + Drift + Intel
+  + Verify on the extrospection side; joined by `extro_correlate`, which
+  tells the agent whether a failure was *its* fault or *the world* changed -
+  and writes the lesson back into the prompt for next time.
 - **Native multi-agent.** `PWN::AI::Agent::Swarm` runs personas (each a full
   tool-calling agent, optionally on a *different* LLM engine) that debate,
   broadcast and share an append-only bus - no IRC daemon, no external service.
+- **Self-healing state.** `PWN::Setup` (doctor/provisioner) + `PWN::Migrate`
+  (schema-stamped `~/.pwn` verifier/auto-migrator) make `gem install pwn` →
+  `pwn setup` the entire install *and* upgrade story on every OS.
 
 ![Overall Architecture](diagrams/overall-pwn-architecture.svg)
 

data/documentation/Why-PWN.md

@@ -40,8 +40,9 @@ when the caller is an autonomous agent.
 A pentest framework that doesn't learn repeats the same dead-end scans forever.
 PWN records **per-tool success rate**, **per-task outcome**, **host drift**,
 and **external CVE intel**, then correlates them so tomorrow's run starts where
-today's finished. See [Skills, Memory & Learning](Skills-Memory-Learning.md)
-and [Extrospection](Extrospection.md).
+today's finished. See [Skills, Memory & Learning](Skills-Memory-Learning.md),
+[Reinforcement Learning](Reinforcement-Learning.md) and
+[Extrospection](Extrospection.md).
 
 **Next:** [How PWN Works](How-PWN-Works.md)