packet-tracer-skill 0.2.1 → 0.2.3

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

@@ -0,0 +1,244 @@
+# Packet Tracer Feature Gap Atlas
+
+This atlas is the public truth source for Packet Tracer 9.0 features that exist in local Cisco samples but are not yet fully productized by this skill.
+
+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 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.
+
+## Remote Sample Evidence
+
+GitHub `.pkt` repositories can add discovery evidence, but they do not automatically change feature maturity.
+
+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:
+
+- DHCP snooping
+- Dynamic ARP Inspection
+- LLDP
+- REP
+- SNMP community
+- NetFlow export
+- SPAN/RSPAN
+- Port security
+
+802.1X/NAC and QoS remain report-first in this wave. Decode-fail Packet Tracer samples can prove that a feature exists by path/catalog evidence, but they do not create edit or generate readiness by themselves.
+
+## Third Edit-Proven Wave
+
+The third promotion wave is `wireless_advanced`. This wave deliberately promotes
+only the safest explicit wireless edit subset:
+
+- WEP SSID/security mutation
+- WPA Enterprise/RADIUS SSID/security intent
+
+These capabilities can report `edit_supported=true` only when the prompt is an
+explicit wireless edit command with a deterministic AP/router/WLC target and
+SSID. They still report `generate_supported=false` and
+`generate_mismatch_reason=supported_in_edit_only`.
+
+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; 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; 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
+- mapped and unmapped feature counts
+- status counts by support level
+- sample-backed feature counts
+- top missing feature families
+- per-feature evidence from parser, catalog, coverage, editor tests, and Packet Tracer sample paths
+
+## Product Rule
+
+Feature atlas support is not the same as generation support. A feature can be visible in `--feature-gap-report` and still remain blocked in `--explain-plan`, `--compare-scenarios`, or `--parity-report` until donor-backed proof exists.

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

@@ -0,0 +1,39 @@
+# Post-Launch Follow-Up
+
+## 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 README, release notes, launch announcement, and GitHub metadata in sync
+
+## Next Technical Proof Batch
+
+- use the canonical `campus` donor proof path first
+- close shorthand campus family fidelity before broadening scenario scope
+- improve selected donor reasoning visibility before adding new capability scope
+- preserve the difference between donor-limited refusal and runtime-blocked refusal
+- make the closest rejected donor class and primary rejection code visible in the public decision surface
+- lift Home IoT only through donor-backed deterministic targets, not broad smart-home synthesis
+
+## Runtime Clarity Improvements
+
+- keep `validated with external bridge override` wording consistent
+- make `validate_open ready but strict generate blocked` easier to read in both docs and doctor output
+- 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
+
+- 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
+
+## Next Integration Wave
+
+- after the Home IoT and wireless internal gate closes, keep `wan_security_edge` scoped to report/selection plus donor-backed readiness
+- next constrained edit candidates remain `vpn`, `ipsec`, `gre`, `ppp`, `security_edge`, and `multilayer_switching`
+- do not open that wave until the Home IoT proof and readiness wording are stable

package/docs/publish-preview-roadmap.md

@@ -9,23 +9,26 @@
 - docs and runtime wording match actual behavior
 - template fallback assets are checked in and release-surface tests protect them
 
-## Step B: Public `0.2.x` Publish-Preview
-
-- `package.json` is versioned at `0.2.1`
-- release notes draft is ready: `docs/release-notes-0.2.1.md`
-- 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`
-- npm publish checklist is complete and conservative runtime wording is preserved
-- final publish batch should only do:
-  - npm publish
-  - GitHub release creation
-  - About/Topics update in GitHub UI
-  - Discussions opening and release announcement
+## 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`
+- 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`
+- npm publish checklist is complete and conservative runtime wording is preserved
+- remaining public launch ops are:
+  - GitHub release creation
+  - About/Topics update in GitHub UI
+  - Discussions opening
+  - release announcement application
 
 ## Step C: `1.0.0` Preparation
 
-- at least one populated curated donor path is actively used in practice
-- runtime messaging remains conservative and stable
-- one richer example family or improved `wan_security_edge` reporting is added
-- publish-preview feedback is folded back into docs and trust surface
+- at least one populated curated donor path is publicly proven in practice
+- runtime messaging remains conservative and stable
+- one richer example family or improved `wan_security_edge` reporting/proof is added
+- publish-preview feedback is folded back into docs and trust surface
+- post-launch follow-up is tracked in `docs/post-launch-follow-up.md`

package/docs/release-checklist.md

@@ -1,6 +1,6 @@
 # Release Checklist
 
-Target release surface: `0.2.1` conservative public preview.
+Target release surface: `0.2.3` capability proof/readiness release.
 
 ## Product Contract
 
@@ -27,25 +27,33 @@ python .\scripts\runtime_doctor.py
 - `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.1`
-- release notes draft exists: `docs/release-notes-0.2.1.md`
-- hero demo plan exists: `docs/hero-demo-plan.md`
-- hero visual is selected: `examples/screenshots/complex_campus_master_edit_v4.png`
-- runtime truth docs match current `runtime_grade` and `bridge_resolution` semantics
-- curated donor registry entries are reviewed for promotion status and provenance
+## 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 `0.2.3`
+- release notes source exists: `docs/release-notes-0.2.3.md`
+- hero demo plan exists: `docs/hero-demo-plan.md`
+- GitHub launch ops runbook exists: `docs/github-launch-ops-0.2.2.md`
+- 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
+- curated donor registry entries are reviewed for promotion status and provenance
 
 ## GitHub Surface
 
 - CI workflow is green
 - issue templates are present
 - contributing and security docs exist
-- citation metadata exists
-- About/Topics are ready to be updated in GitHub UI
+- citation metadata exists
+- About/Topics are ready to be updated in GitHub UI
+- release body source is ready for direct paste into GitHub Releases
+- Discussions categories are decision-complete in docs
 
 ## Publish Gate
 
@@ -55,6 +63,13 @@ Only publish when:
 - README renders cleanly
 - `package.json` version is final for the publish-preview batch
 - doctor wording matches current runtime reality
-- no accidental local paths leaked into tracked files
-- GitHub metadata doc is final and matches README wording
-- hero visual and release notes are ready for direct reuse
+- 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
+
+## Post-Publish Follow-Up
+
+- apply GitHub launch ops if they were not automated
+- publish one canonical donor proof note
+- use `docs/post-launch-follow-up.md` as the source for the next patch trigger conditions

package/docs/release-notes-0.2.1.md

@@ -1,8 +1,8 @@
-# `packet-tracer-skill` `0.2.1` Release Notes Draft
+# `packet-tracer-skill` `0.2.1` Release Notes Source
 
 ## Summary
 
-`0.2.1` is a conservative public preview patch release for `packet-tracer-skill`. It hardens the npm package surface around donor-backed planning, open-first generation rules, scenario-aware reporting, and Windows-first runtime truth.
+`0.2.1` is a conservative public preview patch release for `packet-tracer-skill`. The npm package is already live, and this file is the source text for the GitHub release body.
 
 ## Highlights
 
@@ -14,12 +14,13 @@
 
 ## Runtime Notes
 
-- real `.pkt` runtime remains Windows-first
+- real `.pkt` runtime remains Windows-first runtime
 - strict validation is currently performed with an external bridge override when repo-local bridge assets are not bundled
 - public docs intentionally preserve the distinction between repo-local readiness and external bridge fallback
 
 ## Public Preview Intent
 
-- this release prepares the repo for npm publish and GitHub release
-- it does not change the product contract to imply `1.0.0` stability
-- publish should happen only after the short follow-up batch that applies the prepared metadata and release steps
+- `packet-tracer-skill@0.2.1` is already published on npm
+- GitHub release, About/Topics application, and Discussions setup still follow the prepared manual launch ops flow
+- it does not change the product contract to imply `1.0.0` stability
+- the next public-facing technical step is a canonical campus donor proof artifact, not broader synthetic scope

package/docs/release-notes-0.2.2.md

@@ -0,0 +1,26 @@
+# `packet-tracer-skill` `0.2.2` Release Notes Source
+
+## Summary
+
+`0.2.2` is a conservative patch release for the public preview line. It publishes the README runtime cleanup and the advanced wireless feature wave without changing the core safety posture.
+
+## Highlights
+
+- 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
+- WLC, Meraki, cellular, Bluetooth, beamforming, and guest Wi-Fi remain report-only unless future donor-backed edit proof is added
+- feature atlas and release-surface tests protect the conservative support claims
+
+## Runtime Notes
+
+- real `.pkt` runtime remains Windows-first runtime
+- strict validation is currently performed with an external bridge override when repo-local bridge assets are not bundled
+- public docs intentionally preserve the distinction between repo-local readiness and external bridge fallback
+
+## Public Preview Intent
+
+- `packet-tracer-skill@0.2.2` is the patch release for README cleanup and advanced wireless report/edit truth
+- this release does not claim `generate_ready` support for broad advanced wireless controller, cellular, Bluetooth, or Meraki scenarios
+- unsupported and acceptance-gated mutations still refuse instead of guessing

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/runtime-truth.md

@@ -18,6 +18,35 @@ That distinction is part of the public product contract.
 - `blocked`
   Required donor, bridge, or Packet Tracer runtime pieces are missing.
 
+## How To Read `--doctor`
+
+- if `runtime_grade=ready`, strict decode/edit/generate and `validate_open` are available from the current checkout
+- if `runtime_grade=partially_ready`, at least one operation still works, but the product contract is not fully satisfied
+- if `runtime_grade=blocked`, no critical runtime path is ready enough to claim strict `.pkt` support
+
+High-signal fields:
+
+- `what_currently_works`
+  Short sentence for the operations that are usable right now.
+- `what_is_blocked`
+  Short sentence for the operations that are still blocked.
+- `why_it_is_blocked`
+  Product-facing reason for the current blocker set.
+- `best_next_fix`
+  The single next fix that should be done first.
+
+High-signal mixed case:
+
+- `validate_open` can be `ready` while `inventory`, `decode`, `edit`, and `generate` are blocked
+- this means Packet Tracer is installed, but the donor and/or bridge path is still not sufficient for strict `.pkt` work
+- in that state, `best_next_fix` should point at donor or bridge remediation before anything else
+
+Another mixed case:
+
+- all listed operations can be operationally ready while `bridge_resolution=external_env`
+- 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`
@@ -47,3 +76,5 @@ If tests pass only with an external bridge:
 - do not say "runtime ready" without qualification
 - do say "validated with external bridge override"
 - do preserve the difference between repo-local readiness and external fallback
+- do say when `validate_open` is ready but strict decode/edit/generate are still blocked
+- do keep `what_currently_works`, `what_is_blocked`, and `best_next_fix` aligned with `doctor_summary`

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

@@ -0,0 +1,65 @@
+# Security Edge Deepening Proof
+
+This proof records the `0.2.3` candidate router-based security edge edit-proven subset. 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.