packet-tracer-skill 0.2.2 → 0.3.0

package/docs/packet-tracer-feature-gap-atlas.md

@@ -7,27 +7,39 @@ It is intentionally conservative:
 - `inventory_known` means a Packet Tracer sample or path proves the feature exists.
 - `report_supported` means the skill can recognize and report the feature without claiming mutation support.
 - `edit_proven` requires a roundtrip editor test.
-- `donor_backed_ready` requires selected-donor evidence.
+- `donor_backed_ready` requires selected-donor evidence or a validated proof-linked explicit edit gate with sample, decode, and roundtrip evidence.
 - `generate_ready` requires acceptance-backed generate behavior.
 
-The atlas does not claim that every Packet Tracer feature is generate-ready. It turns missing or under-modelled Packet Tracer features into an auditable backlog before any broad config mutation is opened.
+The atlas does not claim that every Packet Tracer feature is `generate_ready`. It turns missing or under-modelled Packet Tracer features into an auditable backlog before any broad config mutation is opened.
 
-## First Generate Enablement Wave
+## Remote Sample Evidence
 
-The first promotion wave is `ipv6_routing`. The following subset can move beyond report-only only when explicit router/interface targets and an IPv6/routing donor are selected:
+GitHub `.pkt` repositories can add discovery evidence, but they do not automatically change feature maturity.
 
-- IPv6 interface/SLAAC config
-- DHCPv6 stateful pool binding
-- OSPFv3 interface routing
-- EIGRP IPv6 interface routing
-- RIPng interface routing
-- IPv6 HSRP virtual address
+Remote sample evidence is treated in three layers:
+
+- sample-path evidence: a public repo path suggests a Packet Tracer feature exists, but the file may still fail decode or validation
+- decode/inventory evidence: a locally cached sample opens through the decoder and produces feature tags
+- proof evidence: an explicit editor roundtrip or acceptance fixture proves a safe operation shape
+
+`output/remote-import-cache/remote-sample-audit.json` records repo URL, license metadata, imported file counts, decode success/failure counts, detected feature tags, license-based candidate promotion status, and decode-gated validation status. Unknown-license repositories remain `reference_only`. Permissive-license repositories only become curated candidates after local decode and inventory validation. Raw remote `.pkt` files are never a checked-in truth source.
+
+## First Donor-Backed Edit Readiness Wave
+
+The first promotion wave is `ipv6_routing`. The following subset can move beyond report-only when explicit router/interface targets or proof-linked IPv6/routing edit evidence exists:
+
+- IPv6 interface/SLAAC config remains edit-proven.
+- DHCPv6 stateful pool binding remains edit-proven until decode-verified sample evidence is available.
+- OSPFv3 interface routing is donor-backed ready for explicit edit paths.
+- EIGRP IPv6 interface routing is donor-backed ready for explicit edit paths.
+- RIPng interface routing is donor-backed ready for explicit edit paths.
+- IPv6 HSRP virtual address is donor-backed ready for explicit edit paths.
 
 IPv6 tunneling, ISATAP, prefix delegation, and AAAA DNS remain report-first until separate donor-backed editor proof exists.
 
 ## Second Edit-Proven Wave
 
-The second promotion wave is `l2_security_monitoring`. The following subset is edit-proven for explicit commands, but still not broad generate-ready:
+The second promotion wave is `l2_security_monitoring`. The following subset is edit-proven for explicit commands, but still not broad `generate_ready`:
 
 - DHCP snooping
 - Dynamic ARP Inspection
@@ -56,23 +68,168 @@ SSID. They still report `generate_supported=false` and
 WLC/controller workflows, Meraki, cellular/5G, Bluetooth, beamforming, and
 guest Wi-Fi remain report-only until separate donor-backed editor proof exists.
 
+## Fourth Edit-Proven Wave
+
+The fourth promotion wave is `wan_security_edge`. This wave promotes only
+explicit, deterministic router edit commands:
+
+- GRE tunnel basics
+- PPP serial encapsulation
+- IPSec transform-set lines
+- site-to-site VPN crypto-map skeleton binding
+
+These capabilities can report `edit_supported=true` only when the prompt names
+the router, interface or tunnel, peer/source/destination, and required crypto
+objects. They still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+ASA ACL/NAT, service policies, clientless VPN, CBAC, ZFW, security-edge device
+mutation, and multilayer switching remain report-only in this wave until separate
+donor-backed editor proof exists.
+
+## Fifth Donor-Backed Edit Readiness Wave
+
+The fifth promotion wave is `industrial_iot` programming. This wave promotes
+only existing script-file replacement for Real HTTP and Real WebSocket samples:
+
+- Real HTTP Python script file replacement
+- Real WebSocket Python/JavaScript script file replacement
+- programming inventory with hashes and lengths instead of source dumps
+
+These capabilities can report `edit_supported=true` and
+`donor_backed_ready=true` only when the prompt quotes the device name, app name,
+and existing file name. They still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+MQTT protocol mutation, visual scripting generation, PTP, Profinet, L2NAT,
+CyberObserver, and industrial firewall workflows remain report-only until
+separate donor-backed editor proof exists.
+
+## Sixth Donor-Backed Edit Readiness Wave
+
+The sixth promotion wave is `voice_collaboration`. This wave promotes only
+explicit IOS voice configuration lines on an existing router config surface:
+
+- `telephony-service` source address, SCCP port, max ephones, and max DNs
+- `ephone-dn` extension number lines
+- `ephone` MAC and button assignment lines
+- `dial-peer voice` destination-pattern and session-target lines
+
+These capabilities can report `edit_supported=true` and
+`donor_backed_ready=true` only when the prompt names the router and the voice
+object identifiers or values. They still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+IP phone GUI internals, Linksys voice GUI mutation, Call Manager synthesis, and
+broad VoIP topology generation remain report-only until separate donor-backed
+editor proof exists.
+
+## Seventh Donor-Backed Edit Readiness Wave
+
+The seventh promotion wave is `automation_controller`. This wave promotes only
+existing script-file replacement on Packet Tracer programming samples:
+
+- Python app file replacement
+- JavaScript app file replacement
+- TCP/UDP test app JavaScript file replacement
+- programming inventory with hashes and lengths instead of source dumps
+
+These capabilities can report `edit_supported=true` and
+`donor_backed_ready=true` only when the prompt quotes the device name, app name,
+and existing file name. They still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+Network Controller GUI workflows, Blockly visual graph mutation, VM/IOx runtime
+creation, and broad controller/application generation remain report-only until
+separate donor-backed editor proof exists.
+
+## Eighth Donor-Backed Edit Readiness Wave
+
+The eighth promotion wave is the `0.2.3` candidate L2/security proof hardening.
+This wave promotes only deterministic IOS line edits:
+
+- 802.1X/NAC switch config using `aaa new-model`, `dot1x system-auth-control`,
+  `authentication port-control`, and optional `radius-server host`
+- QoS switch config using explicit `class-map`, `policy-map`, and
+  `service-policy input/output`
+- router CBAC using `ip inspect name` plus interface-level `ip inspect`
+- router ZFW using `zone security`, `zone-pair security`, and
+  `policy-map type inspect`
+
+These capabilities can report `edit_supported=true` only for explicit commands
+with deterministic device/interface/object names. Dot1x and ZFW can also report
+`donor_backed_ready=true` because they have decode-verified sample evidence.
+QoS and CBAC remain `edit_proven` until decode-verified sample evidence is added.
+All four still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+ASA ACL/NAT, ASA service-policy, clientless VPN, sniffer workflows, broad NAC,
+and broad QoS design remain report-only until separate donor-backed editor proof
+exists.
+
+## Ninth Edit-Proven Wave
+
+The ninth promotion wave is `l2_resiliency_routing`. This wave uses the local
+user-supplied `pkt_examples` corpus as evidence input and promotes only explicit
+IOS line edits:
+
+- BGP `router bgp`, `neighbor remote-as`, and optional `network mask` lines
+- STP/RSTP `spanning-tree mode` and VLAN root lines
+- EtherChannel `channel-group` and `Port-channel` lines
+- LACP/PAgP mode derivation from explicit EtherChannel modes
+- VTP domain/mode/version lines
+- DTP dynamic switchport mode lines
+
+These capabilities can report `edit_supported=true` only for explicit commands
+with deterministic router/switch/interface names. They do not report
+`donor_backed_ready=true` yet, because this wave does not add selected-donor
+acceptance proof. They still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+`spanning-tree` evidence is intentionally separated from SPAN/RSPAN. STP/RSTP
+must not create the `span` capability; SPAN remains tied to monitor-session style
+config or explicit SPAN/RSPAN prompts.
+
+## Tenth Edit-Proven Wave
+
+The tenth promotion wave is `ipv4_routing_management`. This wave also uses the
+local user-supplied `pkt_examples` corpus as evidence input and promotes only
+explicit IOS line edits:
+
+- OSPFv2, EIGRP IPv4, and RIPv2 router process/network lines
+- static and default IPv4 routes
+- DHCP relay `ip helper-address`
+- NAT inside/outside markers, static NAT, and PAT overload skeletons
+- IOS SSH, NTP client, and syslog client lines
+
+These capabilities can report `edit_supported=true` only for explicit commands
+with deterministic router and interface names. They remain
+`donor_backed_ready=false` and `generate_supported=false`; the local sample corpus
+is evidence input, not a public curated donor registry.
+
 ## Current Feature Families
 
-- `ipv6_routing`: SLAAC, DHCPv6, prefix delegation, AAAA DNS, IPv6 tunneling, ISATAP, OSPFv3, EIGRP IPv6, RIPng, HSRP.
-- `l2_security_monitoring`: DHCP snooping, DAI, 802.1X/NAC, LLDP, REP, SNMP, NetFlow, SPAN/RSPAN, QoS, port security.
-- `wan_security_edge`: ASA ACL/NAT, ASA service policy, clientless VPN, CBAC, ZFW, sniffer, IPSec variants.
+- `ipv6_routing`: SLAAC, DHCPv6, prefix delegation, AAAA DNS, IPv6 tunneling, ISATAP, OSPFv3, EIGRP IPv6, RIPng, HSRP; OSPFv3, EIGRP IPv6, RIPng, and HSRP are donor-backed ready for explicit edit paths.
+- `ipv4_routing_management`: OSPFv2, EIGRP IPv4, RIPv2, static/default routes, DHCP relay, static/dynamic NAT, PAT, SSH, NTP, and syslog; explicit IOS text edits are edit-proven, but not donor-backed ready or `generate_ready`.
+- `l2_resiliency_routing`: BGP, STP/RSTP, EtherChannel, LACP/PAgP, VTP, and DTP; explicit IOS text edits are edit-proven, but not donor-backed ready or `generate_ready`.
+- `l2_security_monitoring`: DHCP snooping, DAI, 802.1X/NAC, LLDP, REP, SNMP, NetFlow, SPAN/RSPAN, QoS, port security; dot1x is donor-backed ready for explicit IOS line edits, while QoS is edit-proven.
+- `wan_security_edge`: VPN crypto-map skeleton, IPSec transform-set, GRE tunnel basics, PPP serial encapsulation, CBAC/ZFW router IOS edits, security-edge evidence, multilayer evidence.
+- `security_edge_deepening`: ASA ACL/NAT, ASA service policy, clientless VPN, CBAC, ZFW, sniffer, IPSec variants; router ZFW is donor-backed ready, while CBAC is edit-proven.
 - `wireless_advanced`: WLC, WPA Enterprise/RADIUS, WEP/WPA modes, guest Wi-Fi, beamforming, Meraki, 5G/cellular, Bluetooth.
-- `automation_controller`: Network Controller, Python, JavaScript, Blockly, TCP/UDP test apps, VM/IOx samples.
-- `voice_collaboration`: VoIP, IP phones, Call Manager-style telephony, Linksys voice.
-- `industrial_iot`: MQTT, Real HTTP, Real WebSocket, visual scripting, PTP, Profinet, L2NAT, CyberObserver, industrial firewall.
+- `automation_controller`: Network Controller, Python, JavaScript, Blockly, TCP/UDP test apps, VM/IOx samples; existing Python, JavaScript, and TCP/UDP script-file edits are donor-backed ready.
+- `voice_collaboration`: VoIP, IP phones, Call Manager-style IOS telephony, Linksys voice; explicit IOS voice edits are donor-backed ready.
+- `industrial_iot`: MQTT, Real HTTP, Real WebSocket, visual scripting, PTP, Profinet, L2NAT, CyberObserver, industrial firewall; only Real HTTP/WebSocket existing script-file edits are donor-backed ready.
 - `physical_media_device`: coaxial, cable/DSL, central office, cell tower, power distribution, hot-swappable modules, IOS/license workflows.
 
 ## CLI
 
 ```powershell
 python .\scripts\generate_pkt.py --feature-gap-report
+python .\scripts\generate_pkt.py --local-sample-audit-root "C:\path\to\pkt_examples"
 ```
 
+The default local audit artifact is `output/local-sample-audit.json`. It is ignored by git and excluded from npm packaging. Local `pkt_examples` evidence does not promote a sample into curated public truth by itself.
+
 The report includes:
 
 - total Packet Tracer feature groups tracked

package/docs/post-launch-follow-up.md

@@ -2,10 +2,13 @@
 
 ## Immediate Follow-Up Items
 
-- complete GitHub launch ops from `docs/github-launch-ops-0.2.2.md`
-- publish one canonical donor proof artifact: `docs/campus-donor-proof.md`
-- publish one Home IoT donor proof artifact: `docs/home-iot-donor-proof.md`
-- publish one WAN/security donor proof artifact: `docs/wan-security-donor-proof.md`
+- keep the published `0.2.3` surface aligned across README, npm, changelog, release notes, proof docs, and examples
+- freeze the `Examples Truth 2.0` proof-card/gallery surface as the first `0.2.4` candidate batch
+- use `docs/proof-readiness-dashboard.md` and `references/proof-readiness-candidates.json` as the next engineering queue
+- keep canonical proof artifacts discoverable from README and examples:
+  - `docs/campus-donor-proof.md`
+  - `docs/home-iot-donor-proof.md`
+  - `docs/wan-security-donor-proof.md`
 - keep README, release notes, launch announcement, and GitHub metadata in sync
 
 ## Next Technical Proof Batch
@@ -24,13 +27,14 @@
 - treat runtime clarity as a product surface, not a debug detail
 - keep `what_currently_works`, `what_is_blocked`, and `best_next_fix` aligned with `doctor_summary`
 
-## Trigger Conditions for `0.2.2` or the Next Minor
+## Trigger Conditions for `0.2.4`
 
 - README / npm / GitHub wording drift
 - donor proof uncovers a concrete selector mismatch worth productizing
 - runtime doctor wording becomes ambiguous again
 - examples and public proof artifacts stop matching current behavior
 - selected donor refusal becomes too generic to explain the closest rejected donor class
+- proof-readiness candidates gain enough selected-donor evidence to justify promotion
 
 ## Next Integration Wave
 

package/docs/proof-readiness-dashboard.md

@@ -0,0 +1,69 @@
+# Proof Readiness Dashboard
+
+This dashboard is the `0.2.4` candidate planning surface for moving features from `edit_proven` toward `donor_backed_ready`.
+
+It combines three sources:
+
+- proof cards in `examples/proof-cards.json`
+- feature support ceilings in `references/packettracer-feature-atlas.json`
+- local sample evidence summarized in `examples/local-sample-evidence.json`
+
+It does not enable broad generation. The current product truth remains `generate_ready=0`.
+
+## Status Contract
+
+- `report_supported`: the feature is recognized and can be reported, but no edit claim is made.
+- `edit_proven`: explicit command or script-file roundtrip has evidence.
+- `donor_backed_ready`: selected donor or proof-linked explicit edit path is safe for a narrow prompt-scoped workflow.
+- `blocked_by_missing_decode_evidence`: sample-path evidence exists, but decode-backed evidence is not sufficient.
+- `blocked_by_missing_roundtrip`: inventory or parser truth exists, but editor roundtrip proof is missing.
+- `blocked_by_no_deterministic_target`: edit proof exists, but selected donor / device / interface / object resolution is not yet locked.
+
+## Primary Queue
+
+Primary candidates are the highest-value next promotion targets because local evidence is strong and the edit surface is IOS text only:
+
+- `ospfv2`
+- `eigrp_ipv4`
+- `ripv2`
+- `static_route`
+- `default_route`
+- `dhcp_relay`
+- `ssh_ios`
+- `ntp_ios`
+- `syslog_ios`
+
+These remain `edit_proven` until selected-donor evidence and deterministic target resolution are proof-linked. Broad routing, NAT, and management design generation stays blocked.
+
+## Secondary Queue
+
+Secondary candidates are L2 resiliency and BGP features with strong local sample evidence but more topology-sensitive safety requirements:
+
+- `stp`
+- `rstp`
+- `etherchannel`
+- `lacp`
+- `pagp`
+- `vtp`
+- `dtp`
+- `bgp`
+
+These features should not inherit donor readiness from generic sample counts. Promotion requires explicit command shape, decode-backed sample evidence, editor roundtrip, deterministic target resolution, and clean refusal on ambiguous targets.
+
+## Promotion Rule
+
+A candidate can be promoted only when all of these are true:
+
+- an explicit command shape exists
+- parser and parity recognize the capability without family drift
+- sample evidence exists
+- decode evidence exists
+- editor roundtrip test exists
+- device/interface/object targets are deterministic
+- ambiguity produces a clean refusal
+
+If any item is missing, the feature stays `edit_proven` or `report_supported`.
+
+## Next Safe Action
+
+Use `references/proof-readiness-candidates.json` as the implementation queue. Do not add new random capability names until the primary queue either promotes or records a concrete blocker.

package/docs/publish-preview-roadmap.md

@@ -11,16 +11,17 @@
 
 ## Step B: Public `0.2.x` Publish-Preview
 
-- `package.json` is versioned at `0.2.2`
-- npm publish target is `packet-tracer-skill@0.2.2`
-- release notes source is ready: `docs/release-notes-0.2.2.md`
+- `packet-tracer-skill@0.2.3` is the current published capability release
+- next candidate line is `0.2.4`, with notes drafted in `docs/release-notes-0.2.4.md`
+- package version remains `0.2.3` until a `0.2.4` publish decision is made
 - hero visual is locked to `examples/screenshots/complex_campus_master_edit_v4.png`
 - hero demo execution plan is ready: `docs/hero-demo-plan.md`
 - GitHub About/Topics text is finalized in `docs/github-metadata.md`
-- launch ops runbook is ready: `docs/github-launch-ops-0.2.2.md`
+- active launch ops source is `docs/github-launch-ops-0.2.3.md`
+- historical `0.2.1` and `0.2.2` launch ops runbooks remain archived
 - npm publish checklist is complete and conservative runtime wording is preserved
 - remaining public launch ops are:
-  - GitHub release creation
+  - GitHub release object verification for the current published tag
   - About/Topics update in GitHub UI
   - Discussions opening
   - release announcement application

package/docs/release-checklist.md

@@ -1,6 +1,6 @@
 # Release Checklist
 
-Target release surface: `0.2.2` conservative public preview.
+Target release surface: `0.2.4` candidate product-hardening patch on top of the published `0.2.3` capability release.
 
 ## Product Contract
 
@@ -17,25 +17,38 @@ python .\scripts\build_examples_index.py
 python -m pytest tests -q
 node --check .\bin\packet-tracer-skill.js
 python .\scripts\generate_pkt.py --parity-report "campus with VLAN DHCP ACL"
-python .\scripts\runtime_doctor.py
-```
-
-## Package Audit
+python .\scripts\runtime_doctor.py
+```
+
+Runtime profile:
+
+- default `python -m pytest tests -q` may skip `requires_twofish` tests when no local bridge is resolved
+- strict release runtime gate must set `PKT_REQUIRE_TWOFISH_TESTS=1` and resolve `PKT_TWOFISH_LIBRARY` or `PKT_TWOFISH_SEARCH_ROOTS`
+- `PKT_REQUIRE_TWOFISH_TESTS=1 python -m pytest tests -q` must pass before publishing any release that claims strict `.pkt` runtime proof
+
+## Package Audit
 
 - `package.json` description matches current product scope
 - keyword clusters cover Packet Tracer, networking labs, AI/natural language, and host ecosystems
 - `files` includes docs and runtime assets needed by consumers
 - version bump matches semver intent
 
-## Public Artifacts
-
-- raw `.pkt` binaries are not committed
-- examples index and gallery were rebuilt
-- screenshots are intentional and non-sensitive
-- changelog entry is updated for `0.2.2`
-- release notes source exists: `docs/release-notes-0.2.2.md`
+## Public Artifacts
+
+- raw `.pkt` binaries are not committed
+- remote GitHub imports, if used, stay under `output/remote-import-cache`
+- `output/remote-import-cache/remote-sample-audit.json` is reviewed for license, decode, and promotion status before any claim changes
+- user-supplied local audits, if used, stay under `output/local-sample-audit.json` or another ignored `output/` path
+- local `pkt_examples` files remain local evidence only; no raw `.pkt`, `.pka`, local audit cache, or user-supplied corpus files are packaged
+- examples index and gallery were rebuilt
+- screenshots are intentional and non-sensitive
+- changelog entry is updated for the candidate release
+- release notes source exists: `docs/release-notes-0.2.4.md`
+- proof-readiness dashboard exists: `docs/proof-readiness-dashboard.md`
+- proof-readiness candidates exist: `references/proof-readiness-candidates.json`
 - hero demo plan exists: `docs/hero-demo-plan.md`
-- GitHub launch ops runbook exists: `docs/github-launch-ops-0.2.2.md`
+- current GitHub launch ops runbook exists: `docs/github-launch-ops-0.2.3.md`
+- historical GitHub launch ops runbooks remain archived and current metadata points at the published release
 - canonical donor proof exists: `docs/campus-donor-proof.md`
 - hero visual is selected: `examples/screenshots/complex_campus_master_edit_v4.png`
 - runtime truth docs match current `runtime_grade` and `bridge_resolution` semantics
@@ -60,6 +73,7 @@ Only publish when:
 - `package.json` version is final for the publish-preview batch
 - doctor wording matches current runtime reality
 - no accidental local paths leaked into tracked files
+- no raw `.pkt`, `.pka`, or remote cache files appear in `npm pack --dry-run --json`
 - GitHub metadata doc is final and matches README wording
 - hero visual and release notes are ready for direct reuse
 

package/docs/release-notes-0.2.2.md

@@ -6,7 +6,7 @@
 
 ## Highlights
 
-- README runtime instructions now use generic Twofish bridge examples instead of a user-specific `.codex` path as the default
+- README runtime instructions now use generic Twofish bridge examples instead of a user-specific local path as the default
 - `PKT_TWOFISH_LIBRARY` and `PKT_TWOFISH_SEARCH_ROOTS` setup paths are documented separately
 - advanced wireless prompts classify into the `wireless_advanced` family
 - WEP and WPA Enterprise/RADIUS are represented as edit-proven only for explicit deterministic edit targets

package/docs/release-notes-0.2.3.md

@@ -0,0 +1,59 @@
+# packet-tracer-skill v0.2.3
+
+`0.2.3` is a capability proof and readiness release. It expands the set of Packet Tracer features that the skill can recognize, inventory, edit with explicit deterministic commands, and report through the feature atlas without claiming broad synthetic generation.
+
+## Highlights
+
+- Added voice/collaboration edit proof for IOS `telephony-service`, `ephone-dn`, `ephone`, and `dial-peer voice` command shapes.
+- Added automation/controller script-file edit proof for existing Python, JavaScript, and TCP/UDP app files.
+- Added L2 security/QoS proof for explicit dot1x and QoS IOS switch commands.
+- Added router security-edge proof for explicit CBAC and ZFW IOS command shapes.
+- Added BGP + L2 resiliency proof for BGP, STP/RSTP, EtherChannel/LACP/PAgP, VTP, and DTP IOS commands.
+- Added IPv4 routing/NAT/IOS-management proof for OSPFv2, EIGRP IPv4, RIPv2, static/default routes, DHCP relay, NAT/PAT, SSH, NTP, and syslog.
+- Added local user-supplied Packet Tracer corpus audit with `--local-sample-audit-root`, storing audit output under ignored `output/` paths.
+- Hardened donor-backed readiness gates so proof-linked decode, sample, parser, and editor evidence are required before readiness promotion.
+
+## Runtime Truth
+
+Windows-first runtime remains the supported validation posture. This release was validated with an external Twofish bridge override, but it does not claim repo-local self-contained runtime readiness.
+
+Use:
+
+```powershell
+npx packet-tracer-skill --doctor
+python .\scripts\runtime_doctor.py
+```
+
+The doctor output remains the authority for Packet Tracer install state, donor path, bridge resolution, ready operations, blocked operations, and the recommended next fix.
+
+## Feature Atlas Truth
+
+`generate_ready=0` remains intentional. The release improves report, edit, and donor-backed edit readiness coverage, but broad generation stays blocked until a future single-donor acceptance-backed pilot proves deterministic target inventory and acceptance JSON.
+
+Support levels should be read in this order:
+
+- `report_supported`: the feature is recognized and can be explained in reports.
+- `edit_proven`: explicit command shapes have editor roundtrip evidence.
+- `donor_backed_ready`: a proof-linked donor or selected-donor path can safely carry a narrow explicit workflow.
+- `generate_ready`: strict scenario generation is acceptance-backed. This remains closed in `0.2.3`.
+
+## Safety Boundaries
+
+- No raw `.pkt` or `.pka` labs are added to the repo or npm tarball.
+- Local `pkt_examples` evidence and remote GitHub sample imports remain evidence-only workflows.
+- Unknown-license remote samples stay `reference_only`.
+- ASA GUI/internal mutation, WLC/controller synthesis, broad physical/media workflows, and broad topology generation remain blocked.
+
+## Verification
+
+Release verification includes:
+
+```powershell
+python .\scripts\build_examples_index.py
+python -m pytest tests -q
+node --check .\bin\packet-tracer-skill.js
+python .\scripts\generate_pkt.py --feature-gap-report
+python .\scripts\generate_pkt.py --parity-report "campus with VLAN DHCP ACL"
+python .\scripts\generate_pkt.py --parity-report "ospf eigrp rip static default route dhcp relay nat pat ssh ntp syslog"
+npm pack --dry-run --json
+```

package/docs/release-notes-0.2.4.md

@@ -0,0 +1,20 @@
+# `packet-tracer-skill` `0.2.4` Release Notes Draft
+
+`0.2.4` is planned as a product hardening patch for the post-`0.2.3` capability surface.
+
+The intended focus is examples truth, proof-card discoverability, local sample evidence presentation, and a proof-readiness promotion queue. It is not a broad generate-ready release.
+
+## Planned Highlights
+
+- Examples Truth 2.0 model with `showcase_example` and `proof_card` artifacts.
+- Local sample evidence board summarized without committing raw `.pkt/.pka` files.
+- Proof-readiness dashboard for the next donor-backed promotion wave.
+- Promotion queue for IPv4 routing/management and L2 resiliency/BGP candidates.
+- Guided user summaries for doctor, parity, and explain-plan workflows.
+- Current docs wording aligned around `0.2.3` as the published release and `0.2.4` as the next candidate.
+
+## Safety Posture
+
+- `generate_ready=0` remains intentional.
+- Raw `.pkt/.pka`, `pkt_examples`, and `output/` artifacts stay out of git and npm.
+- Proof cards and promotion queues are planning and evidence surfaces, not broad topology generation claims.

package/docs/runtime-truth.md

@@ -47,14 +47,39 @@ Another mixed case:
 - that still means the checkout is only partially ready as a packaged repo surface
 - docs should continue saying `validated with external bridge override` rather than implying repo-local readiness
 
-## Bridge Resolution
-
-- `repo_local`
-  A repo-local vendor bridge is resolved.
-- `external_env`
-  A bridge is only available through an external environment path.
-- `missing`
-  No usable bridge is resolved.
+## Twofish Engine
+
+The cipher is no longer a runtime blocker. `scripts/vendor/twofish_pure.py` is a
+vendored pure-Python Twofish, verified against the official test vectors at
+diagnostic time, so `decode`, `inventory`, `edit`, and `generate` are available
+on a clean checkout with no binaries and no environment variables.
+
+`twofish_backend` reports which engine is active:
+
+- `pure_python`
+  The vendored repo-local engine. Always available. This is the baseline.
+- `compiled`
+  A `_twofish` C bridge resolved from `PKT_TWOFISH_LIBRARY`,
+  `PKT_TWOFISH_SEARCH_ROOTS`, or `scripts/vendor/`. Optional, roughly 12x faster
+  on large labs, and bit-identical to the pure engine.
+
+`bridge_resolution` describes only where the *optional accelerator* came from.
+It no longer downgrades `runtime_grade`, and `external_env` is not a blocker.
+
+## Test Profiles
+
+There is one gate. The suite runs the same way with or without a compiled
+bridge, and nothing is skipped for lack of one:
+
+```
+python -m pytest tests -q
+```
+
+`PKT_REQUIRE_TWOFISH_TESTS=1` is still honoured for hosts that want to assert a
+compiled accelerator is present, but it is no longer needed to prove real
+`.pkt` decode/edit works.
+
+The doctor payload exposes this as `runtime_gate_status` and repeats the most useful user-facing answer in `user_summary`. Consumers should show `user_summary.status`, `user_summary.message`, and `user_summary.next_best_action` before dumping the full diagnostic JSON.
 
 ## Publish-Preview Policy
 

package/docs/security-edge-deepening-proof.md

@@ -0,0 +1,65 @@
+# Security Edge Deepening Proof
+
+This proof records the published `0.2.3` router-based security edge edit-proven subset and the `0.2.4` candidate proof-readiness context. The supported surface is IOS line-based CBAC/ZFW configuration on an explicitly named router. ASA GUI/internal mutation, clientless VPN, and broad security topology generation remain blocked.
+
+## Explicit Commands
+
+Supported CBAC shape:
+
+```text
+set R1 cbac inspect FIREWALL protocol tcp interface FastEthernet0/0 direction in
+```
+
+This writes:
+
+```text
+ip inspect name FIREWALL tcp
+interface FastEthernet0/0
+ ip inspect FIREWALL in
+```
+
+Supported ZFW shapes:
+
+```text
+set R1 zfw zone inside interface FastEthernet0/0
+set R1 zfw zone-pair INSIDE_OUT source inside destination outside policy POLICY1
+set R1 zfw class-map CM_WEB match protocol http policy-map POLICY1 action inspect
+```
+
+These write:
+
+```text
+zone security inside
+interface FastEthernet0/0
+ zone-member security inside
+zone-pair security INSIDE_OUT source inside destination outside
+ service-policy type inspect POLICY1
+class-map type inspect match-any CM_WEB
+ match protocol http
+policy-map type inspect POLICY1
+ class type inspect CM_WEB
+  inspect
+```
+
+## Donor-Backed Readiness
+
+- `zfw` is `donor_backed_ready` because it has parser, catalog, decode-verified sample, and editor roundtrip evidence.
+- `cbac` remains `edit_proven` rather than `donor_backed_ready` because the current CBAC sample evidence is path-backed but not decode-verified in the atlas gate.
+
+## What This Proves
+
+- `cbac` and `zfw` are parser-recognized under the WAN/security edge family.
+- Explicit router IOS commands roundtrip through Packet Tracer XML config text.
+- Parity reports mark CBAC/ZFW as `edit_supported=true`, `generate_supported=false`, and `generate_mismatch_reason=supported_in_edit_only` for explicit commands.
+- The feature atlas can classify ZFW as `donor_backed_ready` and CBAC as `edit_proven` when the proof gate is evaluated.
+
+## What This Does Not Prove
+
+- This does not make CBAC, ZFW, ASA ACL/NAT, ASA service policy, or clientless VPN `generate_ready`.
+- This does not mutate ASA GUI/internal security appliance state.
+- This does not synthesize zones, trust boundaries, NAT, VPN peers, or firewall policy from a broad prompt.
+- ASA service-policy and clientless VPN remain report-only until exact donor-backed XML surfaces are proven.
+
+## Safe Next Step
+
+The next promotion should prefer router IOS CBAC/ZFW donor-backed fixtures before touching ASA internals. ASA ACL/NAT, service policy, and clientless VPN should stay report-only until a decode-backed sample and deterministic roundtrip mutation exist.