packet-tracer-skill 0.2.2 → 0.2.3

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to this project should be recorded in this file.
 
 The format is intentionally simple and release-oriented.
 
+## [0.2.3] - 2026-05-03
+
+### Added
+
+- voice/collaboration edit-proven proof for IOS `telephony-service`, `ephone-dn`, `ephone`, and `dial-peer voice` command shapes
+- automation/controller edit-proven proof for existing Python, JavaScript, and TCP/UDP script-file replacement
+- L2 security/QoS edit-proven proof for explicit dot1x and QoS IOS switch commands
+- security-edge deepening proof for explicit router CBAC and ZFW IOS commands
+- L2 resiliency + BGP edit-proven proof for explicit BGP, STP/RSTP, EtherChannel/LACP/PAgP, VTP, and DTP IOS commands
+- IPv4 routing/NAT/IOS-management edit-proven proof for explicit OSPFv2, EIGRP IPv4, RIPv2, static/default route, DHCP relay, NAT/PAT, SSH, NTP, and syslog IOS commands
+- local user-supplied Packet Tracer corpus audit via `--local-sample-audit-root` and ignored `output/local-sample-audit.json`
+- donor-backed readiness expansion for dot1x, ZFW, voice/collaboration IOS edits, and automation/controller script-file edits
+- donor-backed readiness expansion for explicit OSPFv3, EIGRP IPv6, RIPng, and IPv6 HSRP edit paths
+- generate-ready pilot design doc that defines the future acceptance gate without enabling broad generate
+- local/cache-only GitHub sample ingestion audit for `.pkt`/`.pka` repositories, license status, decode evidence, and promotion status
+
+### Changed
+
+- feature atlas candidate status now promotes `ospfv3`, `eigrp_ipv6`, `ripng`, `hsrp`, `dot1x`, `qos`, `cbac`, and `zfw` only when editor roundtrip and decode-backed evidence exists
+- donor-backed readiness now requires proof-linked sample, decode, parser, and editor roundtrip evidence
+- remote samples with unknown license metadata now stay `reference_only`; permissive-license samples still require decode and inventory validation before curated donor eligibility
+- local `pkt_examples` evidence is now separated from public curated truth; raw `.pkt/.pka` files remain excluded from git and npm
+- README and proof docs now describe `0.2.3` as a capability release, not an unpublished candidate
+- ASA service-policy, clientless VPN, Linksys voice, Network Controller GUI, Blockly, VM/IOx, and broad physical/media workflows remain report-only
+
+### Notes
+
+- `0.2.3` is a capability proof/readiness release, not a broad generation release
+- `generate_ready=0` remains intentional until donor-backed acceptance evidence exists
+- broad NAC, QoS, ASA, and security topology generation remains blocked
+
 ## [0.2.2]
 
 ### Added
@@ -15,7 +46,7 @@ The format is intentionally simple and release-oriented.
 ### Changed
 
 - package version advanced to `0.2.2` for the README/runtime cleanup and advanced wireless feature wave
-- README runtime setup no longer presents a user-specific `.codex` path as the default bridge location
+- README runtime setup no longer presents a user-specific local path as the default bridge location
 - advanced wireless prompts now classify into the `wireless_advanced` family without drifting into `service_heavy`
 - WEP and WPA Enterprise/RADIUS are represented as edit-proven where explicit deterministic edit targets exist, while broader WLC/cellular/Bluetooth/Meraki scope remains report-only
 

package/README.md

@@ -1,20 +1,54 @@
-# packet-tracer-skill
+# packet-tracer-skill
 
 [![CI](https://github.com/20hajiyev/packet-tracer-skill/actions/workflows/ci.yml/badge.svg)](https://github.com/20hajiyev/packet-tracer-skill/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Packet Tracer 9.0](https://img.shields.io/badge/Packet%20Tracer-9.0.0.0810-blue.svg)](https://github.com/20hajiyev/packet-tracer-skill)
 
-Cisco Packet Tracer 9.x `.pkt` generator and editor for skill-based coding hosts.
-
-This repository is built for one job: take a natural-language network request, build an explicit scenario-aware plan, adapt a compatible donor lab, and produce a Packet Tracer 9.x workflow that stays open-first and compatibility-first.
-
-`0.2.2` public preview baseline is focused on:
+Cisco Packet Tracer 9.x `.pkt` generator and editor for skill-based coding hosts.
+
+This repository is built for one job: take a natural-language network request, build an explicit scenario-aware plan, adapt a compatible donor lab, and produce a Packet Tracer 9.x workflow that stays open-first and compatibility-first.
+
+It is intended for networking labs where correctness matters more than producing a pretty but unverifiable diagram. The skill can plan, inspect, edit, compare, and explain Packet Tracer scenarios, but it deliberately separates "recognized by the parser", "visible in inventory", "edit-proven", "donor-backed ready", and "generate-ready" support.
+
+`0.2.3` capability release is focused on:
 
 - donor-backed and scenario-aware public messaging
 - conservative Windows-first runtime truth
 - known working scenario set examples with acceptance-backed artifacts
-- README runtime cleanup, advanced wireless feature atlas coverage, and GitHub-launch-ops-ready metadata
-
+- expanded edit-proven capability proof across voice, automation, L2 security, WAN/security, BGP/L2 resiliency, IPv4 routing/NAT, IOS management, and local sample audit workflows
+
+`0.2.3` freezes the voice/collaboration and automation/controller proof work, explicit L2 dot1x/QoS and router-based CBAC/ZFW proof, local-sample-driven BGP/L2 resiliency, IPv4 routing/NAT/IOS-management proof waves, and the first broader donor-backed edit readiness expansion. It remains conservative: `generate_ready=0` is intentional until a future single-donor acceptance-backed pilot is proven.
+
+## What It Does
+
+`packet-tracer-skill` turns network-lab requests into explicit Packet Tracer workflows. The core loop is:
+
+1. parse the prompt into a scenario family and requested capabilities
+2. compare those capabilities against the current support matrix
+3. look for a compatible donor lab when strict `.pkt` work is required
+4. refuse unsafe or unsupported changes instead of guessing
+5. return a decision payload that explains what passed, what failed, and what would make it pass
+
+The current public surface is strongest for these tasks:
+
+- scenario-aware planning for campus, service-heavy, Home IoT, WAN/security edge, IPv6/routing, IPv4 routing/management, L2 security/monitoring, L2 resiliency/BGP, and advanced wireless prompts
+- explicit `.pkt` edits for proven command shapes such as VLAN, DHCP, ACL, server services, IPv6/routing subsets, IPv4 routing/NAT/IOS-management subsets, L2 security/monitoring subsets, BGP/STP/EtherChannel/VTP/DTP IOS text edits, Home IoT constrained edits, and narrow advanced wireless edits
+- capability parity reports that explain whether a prompt is inventory-known, edit-supported, donor-limited, acceptance-gated, or unsupported
+- runtime diagnostics for Packet Tracer installation, donor path, Twofish bridge resolution, and blocked versus ready operations
+- public proof artifacts through examples, inventory manifests, acceptance excerpts, and donor proof docs
+
+## What It Does Not Claim
+
+The project is intentionally conservative. It does not claim universal Packet Tracer automation.
+
+- It does not claim every Packet Tracer feature is generate-ready.
+- It does not synthesize arbitrary `.pkt` internals when donor or acceptance evidence is weak.
+- It does not treat a successful skill install as proof that real `.pkt` decode/edit/generate is ready.
+- It does not commit raw `.pkt` donor labs or local bridge binaries into the public package.
+- It does not claim repo-local self-contained runtime readiness when validation depends on an external bridge override.
+
+The feature atlas exists so unsupported and under-modelled Packet Tracer areas are visible instead of hidden. The intended path is: map the feature, prove inventory visibility, prove edit roundtrip, add donor-backed readiness, and only then consider generate readiness.
+
 ## Why It Is Different
 
 `packet-tracer-skill` is not a generic topology sketcher. It is a donor-backed Packet Tracer workflow with strict refusal behavior:
@@ -41,8 +75,15 @@ Current product strengths:
 - known working examples with screenshots and acceptance excerpts
 
 ## Runtime Reality
-
-Use the same repository, then install it into the skill path your host expects.
+
+Use the same repository, then install it into the skill path your host expects.
+
+There are two separate installation stories:
+
+- installing the skill package into Codex, Cursor, Claude, Gemini, Kiro, AdaL, OpenCode, or a custom skill directory
+- making the local machine capable of opening, decoding, editing, and regenerating real Packet Tracer `.pkt` files
+
+The first story is handled by the npm installer. The second story depends on Packet Tracer 9.0, a compatible donor lab, and a local Twofish bridge. This is why the README keeps repeating the runtime distinction: a host can install the skill successfully while strict `.pkt` operations are still blocked.
 
 | Tool | Install | First Use |
 | --- | --- | --- |
@@ -119,6 +160,7 @@ powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1 -Dev
 
 Launch references:
 
+- [docs/release-notes-0.2.3.md](docs/release-notes-0.2.3.md)
 - [docs/release-notes-0.2.2.md](docs/release-notes-0.2.2.md)
 - [docs/hero-demo-plan.md](docs/hero-demo-plan.md)
 - [docs/github-metadata.md](docs/github-metadata.md)
@@ -128,6 +170,13 @@ Launch references:
 - [docs/home-iot-donor-proof.md](docs/home-iot-donor-proof.md)
 - [docs/wan-security-donor-proof.md](docs/wan-security-donor-proof.md)
 - [docs/wireless-advanced-proof.md](docs/wireless-advanced-proof.md)
+- [docs/industrial-programming-proof.md](docs/industrial-programming-proof.md)
+- [docs/automation-controller-proof.md](docs/automation-controller-proof.md)
+- [docs/voice-collaboration-proof.md](docs/voice-collaboration-proof.md)
+- [docs/l2-resiliency-bgp-proof.md](docs/l2-resiliency-bgp-proof.md)
+- [docs/ipv4-routing-management-proof.md](docs/ipv4-routing-management-proof.md)
+- [docs/l2-security-qos-proof.md](docs/l2-security-qos-proof.md)
+- [docs/security-edge-deepening-proof.md](docs/security-edge-deepening-proof.md)
 - [docs/packet-tracer-feature-gap-atlas.md](docs/packet-tracer-feature-gap-atlas.md)
 
 ## Runtime Doctor Contract
@@ -199,8 +248,7 @@ Important variables:
 - `PKT_TWOFISH_LIBRARY`
 - `PKT_TWOFISH_SEARCH_ROOTS`
 
-Twofish bridge setup is intentionally local-machine specific. Do not copy another
-user's `.codex` path as if it were universal.
+Twofish bridge setup is intentionally local-machine specific. Use a path that exists on your own machine.
 
 Generic explicit bridge path:
 
@@ -222,9 +270,7 @@ folder:
 $env:PKT_TWOFISH_SEARCH_ROOTS="C:\path\to\bridge-folder"
 ```
 
-Developer-local paths such as `$env:USERPROFILE\.codex\skills\...` are valid only
-for the person and host where that bridge exists. They are not the public setup
-contract.
+Developer-local bridge paths are valid only for the person and host where that bridge exists. They are not the public setup contract.
 
 Required policy:
 
@@ -239,9 +285,11 @@ Troubleshooting guide:
 - `bridge_resolution=missing` means strict decode/edit/generate is blocked until `PKT_TWOFISH_LIBRARY` or `PKT_TWOFISH_SEARCH_ROOTS` resolves a compatible bridge.
 - `validate_open` readiness only proves Packet Tracer can launch a file. Strict `.pkt` generation still depends on donor and bridge readiness.
 
-## Core Product Surfaces
-
-Use `--explain-plan` when you need the full decision payload:
+## Core Product Surfaces
+
+The CLI is not only a generator entrypoint. It is also the inspection surface for deciding whether a request is safe. In normal development, start with the reporting commands before expecting a final `.pkt` output.
+
+Use `--explain-plan` when you need the full decision payload:
 
 ```powershell
 python .\scripts\generate_pkt.py --explain-plan "6 department campus with router-on-a-stick, VLAN, DHCP, management VLAN, Telnet, ACL"
@@ -265,19 +313,88 @@ Use `--feature-gap-report` for the Packet Tracer 9.0 feature atlas:
 python .\scripts\generate_pkt.py --feature-gap-report
 ```
 
-The atlas now distinguishes report-only features from edit-proven features. IPv6/routing, a constrained L2 security/monitoring subset, and a narrow advanced-wireless edit subset can be edited with explicit commands, but none of these are claimed as broad generate-ready without donor-backed acceptance evidence.
+## GitHub Sample Ingestion Is Local/Cache-Only
+
+The skill can search GitHub for public Packet Tracer sample repositories when you explicitly opt in with `--search-remote`. This is a developer workflow for collecting evidence, not a promise that downloaded labs become trusted donors or package assets.
+
+Remote ingestion rules:
+
+- imported `.pkt` and `.pka` files stay under `output/remote-import-cache` by default
+- `output/remote-import-cache` is local-only and is not included in the npm package
+- unknown or missing license metadata is treated as `reference_only`
+- permissive-license repositories, such as MIT, only become curated donor candidates after decode and inventory validation
+- decode-fail samples can contribute sample-path evidence, but they never create edit, donor-backed, or generate-ready claims
+- final `.pkt` apply still uses the same `single-donor` safety rule
+
+Preview GitHub candidates without downloading archives:
+
+```powershell
+python .\scripts\generate_pkt.py --explain-plan "ipv6 ospf hsrp lab" --search-remote --remote-dry-run --max-remote-results 3
+```
+
+Import into the local cache and write the audit report:
+
+```powershell
+python .\scripts\generate_pkt.py --explain-plan "ipv6 ospf hsrp lab" --search-remote --max-remote-results 3 --remote-audit-out output\remote-import-cache\remote-sample-audit.json
+```
+
+## Local Sample Audit Is Evidence-Only
+
+If you have your own Packet Tracer lab folder, audit it locally instead of copying raw `.pkt` files into this repo:
+
+```powershell
+python .\scripts\generate_pkt.py --local-sample-audit-root "C:\path\to\pkt_examples"
+```
+
+By default this writes `output/local-sample-audit.json`. That file is local-only and ignored by git/npm packaging. The audit reports total `.pkt/.pka` files, decode success/fail counts, detected config capabilities, top device types, and local promotion candidates. It is evidence for future proof waves, not a curated donor registry entry by itself.
+
+Use an explicit output path when you want to compare audit snapshots:
+
+```powershell
+python .\scripts\generate_pkt.py --local-sample-audit-root "C:\path\to\pkt_examples" --local-sample-audit-out output\local-sample-audit.json
+```
+
+Local evidence still follows the same maturity ladder: sample path evidence, decode evidence, inventory proof, editor roundtrip proof, donor-backed readiness, then possible generate readiness. Raw user-supplied `.pkt/.pka` files are not committed or published.
+
+The generated audit is local by design:
+
+- `repo_url`, license, default branch, import status
+- imported `.pkt` / `.pka` / README / LICENSE counts
+- decode success and failure counts
+- detected feature tags when decode succeeds
+- license-based candidate promotion status and decode-gated validation status
+
+The atlas now distinguishes report-only features, edit-proven features, and donor-backed edit readiness. IPv6/routing, IPv4 routing/NAT/IOS management, a constrained L2 security/monitoring subset, BGP + L2 resiliency IOS text edits, router-based CBAC/ZFW, a narrow WAN/security subset, and a narrow advanced-wireless subset can be edited with explicit commands. Real HTTP/WebSocket, OSPFv3, EIGRP IPv6, RIPng, HSRP, dot1x, ZFW, voice IOS, and selected programming script-file edits are donor-backed-ready proof paths. None of these are claimed as broad generate-ready without acceptance evidence.
+
+Support levels used by the atlas:
+
+- `not_mapped`: the feature is known as a Packet Tracer area, but this repo does not yet model it.
+- `inventory_known`: the feature can be discovered or inferred from sample/catalog evidence.
+- `report_supported`: prompts and reports can talk about the feature without claiming edits.
+- `edit_proven`: explicit command shapes have editor roundtrip evidence.
+- `donor_backed_ready`: a selected donor or proof-linked explicit edit path can safely carry the capability for a prompt-scoped workflow.
+- `generate_ready`: strict generate support is acceptance-backed for that scenario.
 
 Current feature-support truth:
 
 | Area | Current status | Safe action |
 | --- | --- | --- |
 | Campus / service-heavy / Home IoT / WAN-security scenario families | Donor-aware planning and parity/report surfaces | Use `--explain-plan`, `--compare-scenarios`, and donor proof docs before strict generate claims |
-| IPv6/routing | Edit-proven subset | Use explicit router/interface commands; strict generate still needs selected-donor acceptance |
-| L2 security/monitoring | Edit-proven subset | Use explicit DHCP snooping, DAI, LLDP, REP, SNMP, NetFlow, SPAN/RSPAN, and port-security commands |
+| IPv6/routing | OSPFv3, EIGRP IPv6, RIPng, and HSRP are donor-backed ready for explicit edit paths; SLAAC and DHCPv6 stateful remain edit-proven; tunneling, ISATAP, prefix delegation, and AAAA DNS remain report-first | Use explicit router/interface commands; strict generate still needs selected-donor acceptance |
+| IPv4 routing/management | OSPFv2, EIGRP IPv4, RIPv2, static/default route, DHCP relay, NAT/PAT, SSH, NTP, and syslog are edit-proven only for explicit IOS text commands | Use named router/interface commands; do not claim route convergence, NAT policy synthesis, or topology generation |
+| L2 security/monitoring | Explicit dot1x is donor-backed ready; QoS and the rest of the explicit L2 subset remain edit-proven | Use explicit DHCP snooping, DAI, dot1x, QoS, LLDP, REP, SNMP, NetFlow, SPAN/RSPAN, and port-security commands |
+| L2 resiliency + BGP | BGP, STP/RSTP, EtherChannel, LACP/PAgP, VTP, and DTP are edit-proven only for explicit IOS text commands | Use named router/switch/interface commands; do not claim topology/link synthesis or protocol convergence |
+| WAN/security edge | Router ZFW is donor-backed ready; GRE, PPP, IPSec, VPN crypto-map, and CBAC are explicit-edit capable; ASA policies and multilayer switching remain report-only | Use explicit router edit commands; strict generate still needs selected-donor acceptance |
 | Advanced wireless | WEP and WPA Enterprise/RADIUS are explicit-edit capable; WLC, Meraki, cellular, Bluetooth, beamforming, and guest Wi-Fi remain report-only | Keep controller/cellular/Bluetooth claims in atlas/report mode until donor-backed proof exists |
-| Voice, automation/controller, industrial IoT, physical/media gaps | Report-supported atlas entries | Do not claim edit/generate support until a proof wave promotes them |
+| Industrial programming | Real HTTP and Real WebSocket existing script files are donor-backed-ready for explicit edits; MQTT, Profinet, PTP, L2NAT, CyberObserver, and industrial firewall remain report-only | Use quoted device/app/file script edit commands only |
+| Automation/controller | Python, JavaScript, and TCP/UDP app files are donor-backed ready through existing script-file replacement; Network Controller, Blockly, and VM/IOx remain report-only | Use quoted device/app/file script edit commands only |
+| Voice/collaboration | IOS `telephony-service`, `ephone-dn`, `ephone`, and `dial-peer voice` commands are donor-backed ready; Linksys voice remains report-only | Use explicit router voice commands; do not claim broad Call Manager or phone GUI generation |
+| Physical/media gaps | Report-supported atlas entries | Do not claim edit/generate support until a proof wave promotes them |
+
+The important number is still `generate_ready=0` for the atlas gap families. That is deliberate: visibility comes first, then edit proof, then donor-backed readiness, and only then generate readiness. `donor_backed_ready` is now used for narrow explicit edit paths, not broad topology generation.
 
-The important number is still `generate_ready=0` for the atlas gap families. That is deliberate: visibility comes first, then edit proof, then donor-backed readiness, and only then generate readiness.
+For `--parity-report`, prefer the critical parity counters when reading a scenario-level answer:
+`critical_parity_donor_backed_ready_count` shows proof-linked donor readiness, while `critical_parity_generate_ready_count` only counts capabilities that are critical for the detected scenario family and generate-ready. Treat these `critical_*` counts as the release truth. The older total `parity_generate_ready_count` remains for backward compatibility, but it can include non-critical helper capabilities and should not be read as scenario-level generate readiness.
 
 Stable CLI surfaces:
 
@@ -291,8 +408,8 @@ Stable CLI surfaces:
 - `--parity-report`
 - `--acceptance-json-out`
 
-## Curated Donor and Fixture Truth Sources
-
+## Curated Donor and Fixture Truth Sources
+
 This repository keeps explicit truth sources for donor evidence and scenario regression:
 
 - `references/curated-donor-registry.json`
@@ -303,6 +420,8 @@ Curated donor registry reference:
 
 - [docs/curated-donor-registry.md](docs/curated-donor-registry.md)
 
+The registry is not a marketing list. It is a control surface for deciding which donor classes can be trusted for which scenario families. A donor can be useful for inventory and proof while still being rejected for a larger prompt if the skeleton does not safely match the requested topology.
+
 Current selector truth:
 
 - a registry-backed donor can be inventory-proof without being prompt-selected
@@ -345,7 +464,7 @@ Primary screenshot:
 
 ![Packet Tracer topology](examples/screenshots/complex_campus_master_edit_v4.png)
 
-Hero visual for the `0.2.2` public preview surface:
+Hero visual for the `0.2.3` capability release surface:
 
 - `examples/screenshots/complex_campus_master_edit_v4.png`
 
@@ -356,15 +475,35 @@ Canonical public proof:
 - [docs/campus-donor-proof.md](docs/campus-donor-proof.md)
 - [docs/home-iot-donor-proof.md](docs/home-iot-donor-proof.md)
 - [docs/wan-security-donor-proof.md](docs/wan-security-donor-proof.md)
+- [docs/l2-resiliency-bgp-proof.md](docs/l2-resiliency-bgp-proof.md)
+- [docs/ipv4-routing-management-proof.md](docs/ipv4-routing-management-proof.md)
+- [docs/l2-security-qos-proof.md](docs/l2-security-qos-proof.md)
+- [docs/security-edge-deepening-proof.md](docs/security-edge-deepening-proof.md)
 
 The campus donor proof is intentionally more specific than the gallery cards. It shows that a real donor artifact inventories correctly, but it also shows that a generalized campus prompt can still be donor-limited. That is exactly the kind of nuance the public docs should preserve.
 
 The Home IoT donor proof is intentionally narrower than a generic smart-home claim. It shows that donor-backed registration, rule control, and wireless association are integrated only inside a constrained path with explicit targets and a selected donor.
 
-The WAN/security donor proof is also conservative. It shows family-correct report/selection behavior and donor-backed readiness semantics for VPN, IPSec, GRE, PPP, security-edge, and multilayer evidence, but it does not claim broad synthetic WAN/security configuration generation.
+The WAN/security donor proof is also conservative. It shows family-correct report/selection behavior, donor-backed readiness semantics, and a narrow explicit-edit subset for GRE, PPP, IPSec transform-set, and VPN crypto-map skeletons. It does not claim broad synthetic WAN/security configuration generation.
+
+The L2 resiliency + BGP proof is IOS text only. It can append explicit `router bgp`, `spanning-tree`, `channel-group`, `vtp`, and `switchport mode dynamic` lines when the router/switch and interfaces are named. It does not create redundant links, validate STP state, prove BGP convergence, or make these capabilities donor-backed/generate-ready.
+
+The IPv4 routing/management proof is IOS text only. It can append explicit `router ospf`, `router eigrp`, `router rip`, `ip route`, `ip helper-address`, `ip nat`, `ip ssh`, `ntp server`, and `logging host` lines when the router and interfaces are named. It does not synthesize routing designs, NAT pools, ACL policy, or convergence tests.
+
+The L2 security/QoS proof is explicit-command only. It can append IOS-style dot1x and QoS lines when the switch, interface, class-map, policy-map, direction, and optional RADIUS target are explicit. It does not create a full NAC design, supplicant profiles, RADIUS users, or broad QoS policy from intent alone.
+
+The security-edge deepening proof is router IOS only. It can append CBAC and ZFW line-based configuration for explicit targets. It does not mutate ASA GUI/internal state, clientless VPN, ASA service-policy, or broad security topology generation.
+
+Generate-ready pilot design is intentionally separate from implementation:
+
+- [docs/generate-ready-pilot-design.md](docs/generate-ready-pilot-design.md)
+
+That document exists to define the first possible acceptance-backed `generate_ready` pilot without opening it in the current batch.
 
 The advanced wireless proof is narrower again. It promotes only explicit WEP and WPA Enterprise/RADIUS edit semantics while keeping WLC, Meraki, cellular, Bluetooth, beamforming, and guest Wi-Fi in report-only atlas mode.
 
+The industrial programming proof is explicit-file-edit only. It can replace an existing Real HTTP or Real WebSocket script file when the device, app, and file names are quoted and uniquely resolved. It does not create apps, files, MQTT brokers, Profinet/PTP/L2NAT workflows, or broad Industrial IoT topologies.
+
 What the proof now tries to surface explicitly:
 
 - a real donor exists
@@ -403,16 +542,16 @@ See also:
 
 ## Release and Launch State
 
-The npm package release target for this batch is `packet-tracer-skill@0.2.2`. Remaining launch ops are GitHub release application, About/Topics updates, Discussions setup, and public proof follow-up.
+The npm package line is advancing to `packet-tracer-skill@0.2.3`. This release is a capability proof and readiness release, not a broad generate-ready release. The GitHub README, npm README, changelog, release notes, proof docs, and feature atlas should all say the same thing: the skill can recognize more Packet Tracer features, edit more explicit IOS/script surfaces, and report donor-backed readiness for more narrow paths, while still refusing broad unsupported generation.
 
-So the current state is no longer “preparing to publish.” The package line is public. The remaining work is about making the public surface honest and complete:
+So the current state is no longer "preparing an experiment." The package line is public and the `0.2.3` release freezes a real capability batch. The remaining launch ops are about making the public surface operationally complete:
 
 - GitHub release object should match the published npm state
 - About/Topics should match the README and launch wording
 - Discussions should exist as the feedback intake surface
 - donor proof should exist as the first post-launch technical evidence layer
 
-That is the difference between “published” and “productized.” The current repo is published; these follow-up documents are what make it operationally coherent.
+That is the difference between "published" and "productized." The release can be installed from npm, but GitHub release notes, About/Topics, Discussions, and follow-up proof artifacts are what make it operationally coherent.
 
 Recommended local validation before release:
 
@@ -433,25 +572,56 @@ Launch ops references:
 - [docs/github-launch-ops-0.2.2.md](docs/github-launch-ops-0.2.2.md)
 - [docs/post-launch-follow-up.md](docs/post-launch-follow-up.md)
 
-## Azerbaijani Summary
-
-Bu repo təbii dil ilə Packet Tracer `.pkt` generate və edit etmək üçündür, amma əsas fərqi ondadır ki, bunu donor-backed və open-first qayda ilə edir. Yəni donor, parity, acceptance və runtime hazır deyilsə, sistem guess etmir, refusal və remediation qaytarır.
-
-Əsas public səthlər:
-
-- `--explain-plan`
-- `--compare-scenarios`
-- `--parity-report`
-- `--doctor`
-- examples gallery və acceptance excerpt-lər
-
-Hazırkı prioritet:
-
-- `0.2.2` public preview hardening
-- release-ready və publish-ready surface
-- README / npm / GitHub discoverability hizalanması
-- scenario truth source, donor registry və runtime doctor contract consistency
-
-## License
+## Azerbaijani Summary
+
+Bu repo Cisco Packet Tracer 9.x `.pkt` faylları üçün təbii dilə əsaslanan planlama, analiz, edit, parity hesabatı və donor-backed workflow yaradır. Məqsəd sadəcə promptdan topologiya şəkli çıxarmaq deyil. Məqsəd Packet Tracer-in real fayl formatına uyğun, açılan, yoxlanıla bilən və səhv olanda səbəbini izah edən daha etibarlı skill təqdim etməkdir.
+
+Skill promptu əvvəl scenario family və capability-lərə ayırır, sonra həmin tələbi feature atlas, curated donor registry, runtime doctor, parity report və proof docs ilə yoxlayır. Uyğun donor, runtime bridge, deterministic target və ya acceptance sübutu zəifdirsə, sistem final `.pkt` yaratmaq əvəzinə səbəbli refusal verir. Bu davranış qəsdəndir: faylı korlamaqdansa, nə çatışmadığını və növbəti ən doğru addımı göstərmək daha təhlükəsizdir.
+
+Əsas public səthlər:
+
+- `--explain-plan`: promptun hansı scenario family və capability-lərə çevrildiyini, hansı donor və readiness qərarlarının verildiyini göstərir.
+- `--compare-scenarios`: bir neçə promptu eyni matrix üzərində müqayisə edir və hansı ailənin report-supported, edit-proven, donor-limited və ya unsupported olduğunu göstərir.
+- `--parity-report`: tələb olunan capability-lərin inventory, edit, donor-backed readiness, generate və acceptance səviyyəsində vəziyyətini izah edir.
+- `--feature-gap-report`: Packet Tracer 9.0-da mövcud olub skill-də hələ tam məhsullaşmamış sahələri atlas/backlog kimi göstərir.
+- `--local-sample-audit-root`: istifadəçinin lokal `.pkt/.pka` nümunə qovluğunu audit edir, decode nəticələrini və capability evidence-ni çıxarır, amma raw faylları repo-ya və npm paketinə daxil etmir.
+- `--doctor`: real `.pkt` runtime üçün Packet Tracer install, donor path, Twofish bridge və blocked/ready operations vəziyyətini yoxlayır.
+- examples gallery və proof docs: screenshot, inventory manifest, acceptance excerpt və donor proof ilə public iddiaları yoxlanıla bilən artefaktlara bağlayır.
+
+`0.2.3` release-in əsas dəyəri budur: skill Packet Tracer feature-lərini daha geniş tanıyır, daha çox explicit IOS/script edit path-i roundtrip proof ilə qoruyur və daha çox narrow path üçün donor-backed readiness göstərə bilir. Amma bu release hələ universal generate release deyil. `generate_ready=0` açıq saxlanılır, çünki geniş synthetic generation yalnız single-donor, deterministic inventory və acceptance JSON sübutu ilə açılmalıdır.
+
+Hazırda ən güclü sahələr:
+
+- campus və service-heavy lab planning, parity və reporting
+- donor-backed Home IoT constrained edits
+- WAN/security edge report və donor-backed readiness semantics
+- WAN/security edge üçün GRE, PPP, IPSec transform-set, VPN crypto-map, router CBAC və ZFW explicit edit semantics
+- IPv6/routing üçün OSPFv3, EIGRP IPv6, RIPng və HSRP donor-backed-ready subset
+- IPv4 routing/NAT/IOS management üçün OSPFv2, EIGRP IPv4, RIPv2, static/default route, DHCP relay, NAT/PAT, SSH, NTP və syslog explicit edit-proven subset
+- L2 security/monitoring üçün DHCP snooping, DAI, dot1x, QoS, SNMP, NetFlow və SPAN kimi explicit edit/report path-lər
+- BGP və L2 resiliency üçün STP/RSTP, EtherChannel/LACP/PAgP, VTP və DTP explicit IOS edit semantics
+- advanced wireless üçün WEP və WPA Enterprise/RADIUS explicit edit semantics
+- automation/controller və industrial programming üçün Python, JavaScript, TCP/UDP, Real HTTP və Real WebSocket existing script-file explicit edits
+- voice/collaboration üçün IOS telephony-service, ephone-dn/ephone və dial-peer voice explicit edit semantics
+
+Hələ konservativ saxlanan sahələr:
+
+- broad synthetic generate bütün Packet Tracer feature-ləri üçün açıq deyil
+- BGP/STP/EtherChannel/VTP/DTP üçün link/topology synthesis və protocol convergence iddiası edilmir
+- WLC, Meraki, cellular, Bluetooth, beamforming və guest Wi-Fi əsasən report-only qalır
+- Linksys voice, Network Controller GUI, Blockly visual graph, VM/IOx və physical/media feature-lər atlasda görünür, amma edit/generate iddiası almır
+- industrial MQTT, Profinet, PTP, L2NAT, CyberObserver və industrial firewall report-only qalır
+- repo-local self-contained runtime readiness iddia edilmir; external bridge-assisted validation ayrıca göstərilir
+- lokal `pkt_examples` və remote GitHub sample importları evidence source-dur, public curated truth və ya npm package content deyil
+
+Hazırkı release prioriteti:
+
+- `0.2.3` capability release-i dondurmaq və npm/GitHub ilə hizalamaq
+- README, npm package, changelog, release notes və proof docs arasında terminologiya drift-ni bağlamaq
+- scenario truth source, donor registry və runtime doctor contract consistency-ni qorumaq
+- feature atlas üzərindən Packet Tracer-də qalan bütün boşluqları görünən backlog kimi saxlamaq
+- yeni capability-ləri yalnız inventory proof, edit roundtrip proof, deterministic target resolution və donor-backed acceptance olduqda yüksəltmək
+
+## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License.

package/docs/automation-controller-proof.md

@@ -0,0 +1,35 @@
+# Automation Controller Proof
+
+This proof covers the narrow automation/controller wave for Packet Tracer programming surfaces. It is explicit script-file edit proof, not Network Controller GUI synthesis or broad automation topology generation.
+
+## What This Proves
+
+- Inventory can report existing Python, JavaScript, Blockly, and TCP/UDP app files without dumping full source code.
+- Existing Python and JavaScript script files can be replaced when the prompt quotes the device name, app name, and file name.
+- TCP/UDP test app JavaScript files can be edited through the same deterministic existing-file path.
+- `python_programming`, `javascript_programming`, and `tcp_udp_app` can be treated as `edit_proven` for explicit script-file edits.
+- `python_programming`, `javascript_programming`, and `tcp_udp_app` are `donor_backed_ready` for explicit existing-file edits because the proof gate has sample, decode, parser, and editor roundtrip evidence.
+
+## What This Does Not Prove
+
+- It does not create Network Controller projects, apps, or files.
+- It does not mutate Blockly visual graphs beyond inventory/report truth.
+- It does not create or run VM/IOx workloads.
+- It does not synthesize controller policies, REST workflows, or TCP/UDP applications from a broad prompt.
+- It does not make any automation/controller feature `generate_ready`.
+
+## Explicit Edit Shape
+
+```text
+set "python" script app "New Project (Python)" file "main.py" content "print(\"ok\")"
+set "javascript" script app "New Project (JavaScript)" file "main.js" content "console.log(\"ok\")"
+set "PC0" script app "tcpServer" file "tcpServer.js" content "console.log(\"tcp\")"
+```
+
+The editor refuses ambiguous or missing device/app/file targets. It replaces only existing file content and does not guess app names or create new programming surfaces.
+
+## Product Contract
+
+- `python_programming`, `javascript_programming`, and `tcp_udp_app` can report `edit_supported=true` and `donor_backed_ready=true` only for explicit existing-file edit commands.
+- `network_controller`, `blockly_programming`, and `vm_iox` remain report-only.
+- All automation/controller features keep `generate_supported=false` until separate donor-backed acceptance evidence exists.

package/docs/curated-donor-registry.md

@@ -59,6 +59,17 @@ Those are related, but they are not the same claim.
 - registry-backed metadata overrides inferred metadata where the registry is more explicit
 - validation can still demote a registry entry if the actual donor is blocked or incompatible
 
+## Remote Sample Promotion Rules
+
+GitHub sample ingestion is a local developer workflow, not a direct registry promotion path.
+
+- remote `.pkt` and `.pka` files are imported only into `output/remote-import-cache`
+- unknown, missing, or non-permissive license metadata stays `reference_only`
+- permissive-license metadata can only create a `validated_curated` candidate after decode and inventory validation
+- decode-fail samples can be recorded in `remote-sample-audit.json`, but they cannot create donor eligibility
+- no remote sample becomes `acceptance_verified_curated` without checked acceptance fixtures and proof notes
+- raw remote `.pkt` files are not committed and are not packed into npm artifacts
+
 ## Evidence Sources
 
 Selected donor summaries distinguish:

package/docs/generate-ready-pilot-design.md

@@ -0,0 +1,30 @@
+# Generate-Ready Pilot Design
+
+This is a design artifact only. It does not enable `generate_ready`.
+
+## Candidate
+
+The first safe pilot should use a narrow campus or service-heavy flow that already has fixture and donor evidence. The preferred pilot is `campus_core_complex` with a single `campus/core` donor class.
+
+## Required Gate
+
+The pilot can only move to implementation when all of these are true:
+
+- exactly one scenario family is in scope
+- exactly one donor class is allowed
+- exactly one fixture name is used as the regression truth source
+- target inventory is deterministic
+- final `.pkt` apply remains `single-donor`
+- acceptance JSON proves openability, inventory expectations, parity expectations, and decision status
+
+## Explicit Non-Goals
+
+- no L2/QoS generate-ready pilot
+- no ASA/security generate-ready pilot
+- no WLC/controller generate-ready pilot
+- no broad topology synthesis
+- no fallback guessed output when donor selection or acceptance is weak
+
+## Next Step
+
+Before implementation, add a short acceptance fixture proposal that names the donor path, expected inventory excerpt, expected parity excerpt, and the refusal condition when that donor is absent.

package/docs/industrial-programming-proof.md

@@ -0,0 +1,48 @@
+# Industrial Programming Proof
+
+This proof covers the narrow Packet Tracer programming surface promoted after the `0.2.2` baseline. It is intentionally donor-backed edit readiness, not generate-first support.
+
+## What This Proves
+
+- Real HTTP and Real WebSocket samples expose stable existing script files in Packet Tracer XML.
+- Inventory can report programming apps without dumping full source code.
+- Explicit quoted commands can replace an existing script file when device, app, and file names are unique.
+- Real HTTP and Real WebSocket can be treated as `edit_proven` for deterministic script-file edits.
+- Real HTTP and Real WebSocket are the first `donor_backed_ready` atlas entries because they pass a validated proof gate: sample-backed inventory, decode evidence, explicit target resolution, and editor roundtrip proof.
+
+## What This Does Not Prove
+
+- It does not claim broad Industrial IoT topology generation.
+- It does not create new apps, new files, MQTT brokers, WebSocket servers, or Real HTTP services.
+- It does not claim MQTT protocol mutation, Profinet, PTP, L2NAT, CyberObserver, or industrial firewall edit support.
+- It does not make any industrial programming feature `generate_ready`.
+- It does not create a new app or file when a donor lacks the named script target.
+
+## Explicit Edit Command Shape
+
+```text
+set "Py: real http server 2" script app "New Project (Python)" file "main.py" content "from realhttp import *\nprint(\"ok\")"
+set "WebSockets Client" script app "ws client (Python)" file "main.py" content "from realhttp import *\nclient = RealWSClient()\nprint(\"ok\")"
+```
+
+The command is quoted on purpose. Packet Tracer app and device names often contain spaces, punctuation, and parentheses. Unquoted script mutation is not supported.
+
+## Donor-Backed Readiness Boundary
+
+`donor_backed_ready` means the skill can safely apply an explicit existing-file script edit when the donor already contains the named device, app, and file. It does not mean broad prompt generation is ready.
+
+Readiness requires all of these to be true:
+
+- the feature is `real_http` or `real_websocket`
+- the command quotes a device name, app name, existing file name, and replacement content
+- inventory resolves exactly one matching target
+- the editor roundtrip test proves the file content can be replaced and decoded again
+- no new app, new file, MQTT broker, HTTP service, or WebSocket service is synthesized
+
+## Public Contract
+
+- `real_http`, `real_websocket`, `python_programming`, and `javascript_programming` can report `edit_supported=true` only for explicit existing-file edits.
+- `real_http` and `real_websocket` can report `donor_backed_ready=true` for explicit existing-file edits.
+- `generate_supported=false` remains the expected result.
+- `generate_mismatch_reason=supported_in_edit_only` is the intended parity wording.
+- `mqtt`, `visual_scripting`, `ptp`, `profinet`, `l2nat`, `cyberobserver`, and `industrial_firewall` remain report-only until separate roundtrip proof exists.

package/docs/ipv4-routing-management-proof.md

@@ -0,0 +1,37 @@
+# IPv4 Routing and IOS Management Proof
+
+This proof wave uses the local user-supplied `pkt_examples` corpus as evidence input, not as public package content. The corpus contains many decodeable Packet Tracer labs with IPv4 routing, NAT/PAT, SSH, NTP, syslog, DHCP relay, and classic CCNA management patterns.
+
+## What Is Edit-Proven
+
+The supported subset is explicit IOS `RUNNINGCONFIG` mutation only:
+
+- OSPFv2 via `router ospf <process>` with `network <network> <wildcard> area <area>`
+- `router eigrp <asn>` with IPv4 `network` and optional `no auto-summary`
+- `router rip` with `version 2`, IPv4 `network`, and optional `no auto-summary`
+- `ip route <network> <mask> <next-hop>` including default route
+- interface-level `ip helper-address`
+- interface-level `ip nat inside` and `ip nat outside`
+- `ip nat inside source static <inside-local> <inside-global>`
+- PAT overload with `ip nat inside source list <acl> interface <interface> overload`
+- IOS SSH setup with domain, username/password, RSA modulus, and `ip ssh version 2`
+- IOS `ntp server` and `logging host`
+
+## What This Proves
+
+- The parser can classify IPv4 routing and management prompts as `ipv4_routing_management`.
+- Explicit commands produce deterministic router operations.
+- Existing IOS text config surfaces can roundtrip these command shapes.
+- Parity can show these capabilities as `edit_supported=true`, `generate_supported=false`, and `generate_mismatch_reason=supported_in_edit_only`.
+- Local sample audit can summarize user-supplied `.pkt/.pka` evidence without committing raw Packet Tracer files.
+
+## What This Does Not Prove
+
+- It does not make any IPv4 routing, NAT, or IOS management capability `generate_ready`.
+- It does not synthesize topology, links, ACL objects, NAT pools, route convergence, or lab scoring.
+- It does not promote local `pkt_examples` files into curated public donors.
+- It does not mutate GUI/internal Packet Tracer state.
+
+## Safe Next Step
+
+The next promotion step is donor-backed readiness for a narrow single-donor IPv4 routing fixture, only after selected-donor evidence, deterministic targets, and acceptance JSON prove the resulting `.pkt` opens and matches expected inventory/parity.