packet-tracer-skill 0.2.2 → 0.3.0

package/bin/packet-tracer-skill.js

@@ -1036,12 +1036,39 @@ function main() {
         }
       }
       printEnvExamples(runtimeDoctor);
-      const failed = checks.some(([, ok]) => !ok);
+      // The verdict follows the checks that decide whether anything is
+      // actually blocked, not "did any line print MISSING". A fresh install
+      // reported `RUNTIME_GRADE ready`, `BLOCKED_OPERATIONS none` and every
+      // capability ready, and then closed with "Runtime is not fully ready"
+      // and exit 1 -- because `TWOFISH_SHA256` is a checksum of the optional
+      // compiled bridge, which is absent by design when the vendored
+      // pure-Python engine is in use. A first-time user reads that as a failed
+      // install.
+      const status = checkMap(checks);
+      const isClear = (name) => {
+        const entry = status.get(name);
+        if (!entry) return true;
+        const detail = (entry.detail || "").trim().toLowerCase();
+        return entry.ok || detail === "" || detail === "none";
+      };
+      const gradeEntry = status.get("RUNTIME_GRADE");
+      const grade = (gradeEntry && gradeEntry.detail ? gradeEntry.detail : "").trim();
+      const failed =
+        (grade !== "" && grade !== "ready") ||
+        !isClear("RUNTIME_BLOCKERS") ||
+        !isClear("BLOCKED_OPERATIONS");
       if (failed) {
         console.error("\nRuntime is not fully ready. Install copies are fine, but Packet Tracer generation still needs the missing items above.");
         process.exit(1);
       }
-      console.log("\nRuntime looks ready.");
+      const informational = checks.filter(([, ok]) => !ok).map(([name]) => name);
+      if (informational.length > 0) {
+        console.log(
+          `\nRuntime looks ready. Optional items not present: ${informational.join(", ")}.`
+        );
+      } else {
+        console.log("\nRuntime looks ready.");
+      }
       process.exit(0);
     }
 

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/github-launch-ops-0.2.3.md

@@ -0,0 +1,37 @@
+# GitHub Launch Ops for `v0.2.3`
+
+`packet-tracer-skill@0.2.3` is the current published capability release. This runbook is the active launch-ops source for the published line.
+
+## Release Object
+
+1. Ensure tag `v0.2.3` points to the publish commit.
+2. Create or verify the GitHub Release title `v0.2.3`.
+3. Use `docs/release-notes-0.2.3.md` as the release body source.
+4. Keep the hero visual as `examples/screenshots/complex_campus_master_edit_v4.png`.
+
+## About And Topics
+
+Use `docs/github-metadata.md` as the current source of truth.
+
+The public wording should say:
+
+- donor-backed
+- open-first
+- scenario-aware
+- Windows-first runtime
+- validated with external bridge override
+
+Do not claim repo-local self-contained runtime readiness unless `runtime_doctor` semantics change.
+
+## Discussions
+
+Recommended categories:
+
+- `Showcase`
+- `Q&A`
+- `Donor Requests`
+- `Capability Roadmap`
+
+## Next Candidate
+
+`0.2.4` is a candidate product-hardening patch for Examples Truth 2.0, proof-card discoverability, local sample evidence, and proof-readiness promotion planning. It should not be presented as published until version, tag, npm, and release notes are finalized.

package/docs/github-metadata.md

@@ -27,13 +27,15 @@ Pinned screenshot:
 
 Pinned caption:
 
-- `donor-backed complex campus proof artifact for the 0.2.2 public preview`
+- `donor-backed complex campus proof artifact for the 0.2.3 capability release`
 
 ## Release Source
 
-- release title: `v0.2.2`
-- release body source: `docs/release-notes-0.2.2.md`
-- launch wording source: `docs/launch-announcement-0.2.2.md`
+- current published release title: `v0.2.3`
+- current release body source: `docs/release-notes-0.2.3.md`
+- current launch ops source: `docs/github-launch-ops-0.2.3.md`
+- next candidate release notes draft: `docs/release-notes-0.2.4.md`
+- historical `0.2.2` launch wording remains archived in `docs/launch-announcement-0.2.2.md`
 
 ## Discussions Categories
 

package/docs/hero-demo-plan.md

@@ -2,7 +2,7 @@
 
 ## Goal
 
-Prepare one conservative hero demo flow for the `0.2.1` public preview surface without implying self-contained runtime readiness.
+Prepare one conservative hero demo flow for the current `0.2.3` capability release and the next `0.2.4` candidate surface without implying self-contained runtime readiness.
 
 ## Prompt
 

package/docs/home-iot-donor-proof.md

@@ -25,15 +25,15 @@ Observed Home IoT proof facts:
   - IoT rule enable/disable state
   - donor-backed wireless association
 
-## Donor-Backed Generate Interpretation
+## Donor-Backed Readiness Interpretation
 
 The current product contract for Home IoT is intentionally narrow:
 
-- `iot_registration`, `iot_control`, and `wireless_client_association` are only considered generate-ready when a selected donor exists
+- `iot_registration`, `iot_control`, and `wireless_client_association` are only considered donor-backed ready when a selected donor exists
 - the selected donor must match `IoT/home gateway` or a compatible `wireless-heavy` shape
 - the prompt must name deterministic targets such as the thing, gateway/server, client, AP/router, and SSID
 
-This is why the public wording uses `donor-backed constrained-generate` rather than broad `smart home generate-ready`.
+This is why the public wording uses `donor-backed constrained edit/readiness` rather than broad smart-home generation.
 
 ## What This Proves
 
@@ -45,7 +45,7 @@ This is why the public wording uses `donor-backed constrained-generate` rather t
 ## What This Does Not Prove
 
 - it does not prove free-form smart-home topology generation is solved
-- it does not prove every prompt mentioning IoT registration is generate-ready
+- it does not prove every prompt mentioning IoT registration is donor-backed ready or generation ready
 - it does not remove the need for a selected donor and deterministic target resolution
 - it does not promote WAN/security features ahead of the next wave
 

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.

package/docs/l2-resiliency-bgp-proof.md

@@ -0,0 +1,60 @@
+# L2 Resiliency + BGP Proof Wave
+
+This proof wave uses the local user-supplied `pkt_examples` corpus as evidence input only. Raw `.pkt` files, imported caches, and `output/pkt_examples_audit.json` are not package or repository artifacts.
+
+## What Is Covered
+
+The wave adds parser, inventory, catalog, atlas, and parity truth for:
+
+- `bgp`
+- `stp`
+- `rstp`
+- `etherchannel`
+- `lacp`
+- `pagp`
+- `vtp`
+- `dtp`
+
+These capabilities are constrained to IOS text configuration surfaces. They are not broad topology generation features.
+
+## Explicit Edit Commands
+
+Supported edit-proof command shapes:
+
+```powershell
+python scripts/generate_pkt.py --parity-report "set R1 bgp 65001 neighbor 10.0.0.2 remote-as 65002 network 192.168.1.0 mask 255.255.255.0"
+python scripts/generate_pkt.py --parity-report "set SW1 stp mode rapid-pvst vlan 10 root primary"
+python scripts/generate_pkt.py --parity-report "set SW1 etherchannel 1 mode active interfaces FastEthernet0/1 FastEthernet0/2"
+python scripts/generate_pkt.py --parity-report "set SW1 etherchannel 2 mode desirable interfaces FastEthernet0/3 FastEthernet0/4"
+python scripts/generate_pkt.py --parity-report "set SW1 vtp domain CAMPUS mode server version 2"
+python scripts/generate_pkt.py --parity-report "set SW1 dtp interface FastEthernet0/1 mode dynamic desirable"
+```
+
+## Target Rules
+
+- The target device name must be explicit.
+- Interface names must be explicit where an interface command is used.
+- Only existing device configuration text is mutated.
+- No GUI/internal Packet Tracer state is guessed.
+- No links, modules, devices, or topology shape are synthesized in this wave.
+
+## What This Proves
+
+- BGP neighbor/network IOS text can be parsed and written deterministically.
+- The editor writes a `router bgp` block with explicit `neighbor ... remote-as` and optional `network ... mask` lines.
+- STP/RSTP can be detected separately from SPAN/RSPAN through explicit `spanning-tree` lines.
+- EtherChannel can be represented through explicit `channel-group` and `Port-channel` text.
+- LACP/PAgP are derived from explicit EtherChannel modes.
+- VTP and DTP line shapes can be parsed, inventoried, and roundtripped as IOS text.
+
+## What This Does Not Prove
+
+- It does not prove full BGP peering convergence.
+- It does not prove STP state simulation correctness.
+- It does not create or validate physical redundant links.
+- It does not make these capabilities `donor_backed_ready`.
+- It does not make any of these capabilities `generate_ready`.
+
+## Current Product Status
+
+The atlas status for this wave is `edit_proven` when roundtrip tests exist. `generate_ready=0` remains intentional until a single-donor acceptance fixture proves a strict safe-open generate path.

package/docs/l2-security-qos-proof.md

@@ -0,0 +1,59 @@
+# L2 Security and QoS Proof
+
+This proof records the published `0.2.3` L2 security/QoS edit-proven subset and the `0.2.4` candidate proof-readiness context. It is intentionally narrow: the skill can append deterministic IOS-style switch configuration lines for explicitly named targets, but it does not synthesize a full NAC or QoS design from a broad prompt.
+
+## Explicit Commands
+
+Supported explicit edit shapes:
+
+```text
+set SW1 dot1x interface FastEthernet0/1 mode auto radius 192.168.1.10 key radius123
+set SW1 qos class-map VOICE match dscp ef policy-map QOS_POLICY class VOICE priority service-policy output FastEthernet0/1
+```
+
+The dot1x command writes:
+
+```text
+aaa new-model
+dot1x system-auth-control
+radius-server host 192.168.1.10 key radius123
+interface FastEthernet0/1
+ authentication port-control auto
+ dot1x pae authenticator
+```
+
+The QoS command writes:
+
+```text
+mls qos
+class-map match-any VOICE
+ match dscp ef
+policy-map QOS_POLICY
+ class VOICE
+  priority
+interface FastEthernet0/1
+ service-policy output QOS_POLICY
+```
+
+## Donor-Backed Readiness
+
+- `dot1x` is `donor_backed_ready` because it has parser, catalog, decode-verified sample, and editor roundtrip evidence.
+- `qos` remains `edit_proven` rather than `donor_backed_ready` because the current QoS sample evidence is path-backed but not decode-verified in the atlas gate.
+
+## What This Proves
+
+- `dot1x` and `qos` are parser-recognized as `l2_security_monitoring`.
+- Explicit dot1x and QoS commands roundtrip through Packet Tracer XML config text.
+- Parity reports mark these capabilities as `edit_supported=true`, `generate_supported=false`, and `generate_mismatch_reason=supported_in_edit_only`.
+- The feature atlas can classify dot1x as `donor_backed_ready` and QoS as `edit_proven` when the proof gate is evaluated.
+
+## What This Does Not Prove
+
+- This does not make dot1x or QoS `generate_ready`.
+- This does not create RADIUS server users, certificates, supplicant profiles, policy discovery, or end-to-end NAC validation.
+- This does not generate QoS classes from traffic intent; class-map, policy-map, direction, and interface must be explicit.
+- This does not prove every Packet Tracer switch model accepts every IOS line.
+
+## Safe Next Step
+
+The next promotion would require selected-donor proof with a reusable L2 security/monitoring skeleton and acceptance fixtures. Until then, broad prompts such as `dot1x qos policy class-map policy-map` remain report/plan evidence, while explicit commands use the edit-only path.