packet-tracer-skill 0.1.0 → 0.2.0

package/docs/discovery-keywords.md

@@ -0,0 +1,55 @@
+# Discovery Keywords
+
+## Must-Keep Clusters
+
+### Packet Tracer Core
+
+- `packet-tracer`
+- `pkt`
+- `cisco`
+- `packet-tracer-generator`
+- `packet-tracer-editor`
+- `network-topology-generator`
+
+### Networking Labs
+
+- `vlan`
+- `dhcp`
+- `dns`
+- `acl`
+- `nat`
+- `router-on-a-stick`
+- `telnet`
+- `wireless`
+- `ccna`
+- `ccnp`
+
+### AI / Natural Language
+
+- `ai-skill`
+- `llm-skill`
+- `natural-language`
+- `prompt-to-topology`
+- `network-automation`
+- `network-lab-generator`
+
+### Host Ecosystem
+
+- `codex`
+- `cursor`
+- `claude`
+- `gemini`
+- `github-copilot-skill`
+- `npx`
+
+## Candidate-To-Prune-Later
+
+Do not remove these yet, but review them after real publish and search feedback:
+
+- broad generic terms that add little host or networking intent
+- duplicate phrases that do not add new discovery surface
+
+Current policy:
+
+- keep the wider keyword set through publish-preview
+- use README headings, GitHub Topics, example titles, and article titles to reinforce the same vocabulary

package/docs/github-discussions-setup.md

@@ -0,0 +1,34 @@
+# GitHub Discussions Setup
+
+Recommended categories:
+
+- `Show and Tell`
+- `Q&A`
+- `Donor Requests`
+- `Capability Roadmap`
+
+Recommended purpose:
+
+- `Show and Tell`
+  Real example screenshots, labs, and outcomes.
+- `Q&A`
+  Usage help, runtime doctor interpretation, install guidance.
+- `Donor Requests`
+  Requests for new donor families or curated donor promotion.
+- `Capability Roadmap`
+  Discussion of scenario families, parity gaps, and future coverage.
+
+Recommended repository About topics:
+
+- `packet-tracer`
+- `cisco`
+- `networking`
+- `network-lab`
+- `natural-language`
+- `ai-skill`
+- `codex`
+- `cursor`
+- `claude`
+- `gemini`
+
+Keep repository Topics, README headings, and npm keywords aligned to the same vocabulary clusters.

package/docs/github-metadata.md

@@ -0,0 +1,33 @@
+# GitHub Metadata
+
+## Final About Text
+
+Donor-backed Cisco Packet Tracer 9.x skill for natural-language planning, safe-open `.pkt` generation, editing, parity reporting, and runtime diagnostics.
+
+## Final Topics
+
+- `packet-tracer`
+- `cisco`
+- `networking`
+- `network-lab`
+- `natural-language`
+- `ai-skill`
+- `codex`
+- `cursor`
+- `claude`
+- `gemini`
+
+## Final Pinned Visual
+
+Use the complex campus Packet Tracer screenshot as the first public visual until a dedicated hero demo GIF is ready.
+
+Pinned screenshot:
+
+- `examples/screenshots/complex_campus_master_edit_v4.png`
+
+## Public Message Guardrails
+
+- say `donor-backed`, `open-first`, `scenario-aware`, and `Windows-first runtime`
+- say `validated with external bridge override` when referring to strict runtime validation
+- do not say the repo is self-contained runtime-ready unless doctor semantics change
+- keep README, release notes, and GitHub About text aligned with the same wording

package/docs/hero-demo-plan.md

@@ -0,0 +1,42 @@
+# Hero Demo Plan
+
+## Goal
+
+Prepare one conservative hero demo flow for the `0.2.0` public preview surface without implying self-contained runtime readiness.
+
+## Prompt
+
+Use this prompt:
+
+```text
+6 department campus with router-on-a-stick, VLAN, DHCP, management VLAN, Telnet, ACL
+```
+
+## CLI Flow
+
+Run in this order:
+
+```powershell
+python .\scripts\generate_pkt.py --explain-plan "6 department campus with router-on-a-stick, VLAN, DHCP, management VLAN, Telnet, ACL"
+python .\scripts\generate_pkt.py --parity-report "6 department campus with router-on-a-stick, VLAN, DHCP, management VLAN, Telnet, ACL"
+python .\scripts\runtime_doctor.py
+```
+
+## Visual
+
+- pinned image: `examples/screenshots/complex_campus_master_edit_v4.png`
+- reuse the complex campus topology screenshot as the hero visual until a dedicated GIF is produced
+
+## Claims To Make
+
+- donor-backed
+- open-first
+- scenario-aware
+- Windows-first runtime
+- validated with external bridge override
+
+## Claims Not To Make
+
+- do not say the repo is self-contained runtime-ready
+- do not claim full synthetic generate for WAN/security coverage
+- do not imply unsupported or acceptance-gated mutations are generated anyway

package/docs/publish-preview-roadmap.md

@@ -0,0 +1,31 @@
+# Publish-Preview Roadmap
+
+## Step A: Internal Freeze
+
+- completed
+- release surface is commit-ready
+- checklist dry run passes
+- changelog reflects the current batch
+- 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.0`
+- release notes draft is ready: `docs/release-notes-0.2.0.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 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

package/docs/release-checklist.md

@@ -0,0 +1,60 @@
+# Release Checklist
+
+Target release surface: `0.2.0` conservative public preview prep.
+
+## Product Contract
+
+- `scenario_generate_decision`, `scenario_acceptance_summary`, `scenario_matrix_row`, `capability_parity`, and runtime doctor wording are internally consistent
+- curated donor registry and scenario fixture corpus reflect current behavior
+- README claims do not exceed tested behavior
+
+## Validation
+
+Run:
+
+```powershell
+python .\scripts\build_examples_index.py
+python -m pytest tests -q
+node --check .\bin\packet-tracer-skill.js
+python .\scripts\generate_pkt.py --parity-report "campus with VLAN DHCP ACL"
+python .\scripts\runtime_doctor.py
+```
+
+## Package Audit
+
+- `package.json` description matches current product scope
+- keyword clusters cover Packet Tracer, networking labs, AI/natural language, and host ecosystems
+- `files` includes docs and runtime assets needed by consumers
+- version bump matches semver intent
+
+## Public Artifacts
+
+- raw `.pkt` binaries are not committed
+- examples index and gallery were rebuilt
+- screenshots are intentional and non-sensitive
+- changelog entry is updated for `0.2.0`
+- release notes draft exists: `docs/release-notes-0.2.0.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
+
+## 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
+
+## Publish Gate
+
+Only publish when:
+
+- CI is green
+- 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

package/docs/release-notes-0.2.0.md

@@ -0,0 +1,25 @@
+# `packet-tracer-skill` `0.2.0` Release Notes Draft
+
+## Summary
+
+`0.2.0` is a conservative public preview prep release for `packet-tracer-skill`. It stabilizes the public release surface around donor-backed planning, open-first generation rules, scenario-aware reporting, and Windows-first runtime truth.
+
+## Highlights
+
+- donor-backed and scenario-aware Packet Tracer 9.x workflow
+- explicit product surfaces: `--explain-plan`, `--compare-scenarios`, `--parity-report`, `--doctor`
+- curated donor registry and scenario fixture corpus are checked-in truth sources
+- known working scenario set examples are positioned as public proof artifacts
+- release/readme/docs wording is aligned to runtime and donor reality
+
+## Runtime Notes
+
+- real `.pkt` runtime remains Windows-first
+- 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

package/docs/runtime-truth.md

@@ -0,0 +1,49 @@
+# Runtime Truth
+
+## Why This Exists
+
+This repo makes a strict distinction between:
+
+- passing tests with an external bridge override
+- being self-contained and repo-local runtime ready
+
+That distinction is part of the public product contract.
+
+## Runtime Grades
+
+- `ready`
+  Repo-local runtime pieces are available and the doctor sees a complete decode/edit/generate path.
+- `partially_ready`
+  Some operations work, but strict `.pkt` generation is still blocked.
+- `blocked`
+  Required donor, bridge, or Packet Tracer runtime pieces are missing.
+
+## Bridge Resolution
+
+- `repo_local`
+  A repo-local vendor bridge is resolved.
+- `external_env`
+  A bridge is only available through an external environment path.
+- `missing`
+  No usable bridge is resolved.
+
+## Publish-Preview Policy
+
+For `0.2.x` publish-preview:
+
+- external bridge assisted testing is acceptable
+- docs must say this explicitly
+- README must not imply the repo is self-contained if it is not
+
+For `1.0.0`:
+
+- either repo-local readiness improves
+- or the Windows-first external-bridge-assisted contract remains explicit and stable
+
+## Required Messaging
+
+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

package/docs/screenshots/.gitkeep

@@ -0,0 +1 @@
+

package/examples/README.md

@@ -0,0 +1,72 @@
+## Known Working Scenario Set
+
+This repo keeps text-based example artifacts under `examples/` and treats them as a known working scenario set, not just a screenshot folder.
+
+For the `0.2.0` launch-prep surface, the canonical public set is:
+
+- `complex_campus_master_edit_v4`
+- `home_iot_cli_edit_v1`
+- `service_heavy_cli_edit_v1`
+
+Hero visual:
+
+- `screenshots/complex_campus_master_edit_v4.png`
+
+Policy:
+- generated `.pkt` and `.xml` files stay gitignored
+- public examples should be sanitized JSON or markdown summaries
+- if you want to publish a lab sample, prefer `--inventory --inventory-out` and commit the resulting JSON
+- real Packet Tracer screenshots can be committed under `examples/screenshots/`
+- examples may have one primary screenshot plus additional detail screenshots
+
+Example command:
+
+```powershell
+python .\scripts\generate_pkt.py --inventory .\output\complex_campus_master_edit_v4.pkt --inventory-capabilities --inventory-out .\examples\complex_campus_master_edit_v4.inventory.json
+```
+
+Current curated example:
+- `complex_campus_master_edit_v4.inventory.json`
+  Donor-backed complex campus edit showing management VLAN, Telnet, ACL, server services, and wireless updates without publishing the binary `.pkt` itself.
+- `screenshots/complex_campus_master_edit_v4.png`
+  Visual snapshot of the same lab opened inside Cisco Packet Tracer.
+
+Additional curated examples:
+- `home_iot_cli_edit_v1.inventory.json`
+  Home gateway and IoT registration example focused on gateway-backed device onboarding.
+- `screenshots/home_iot_cli_edit_v1.png`
+  Topology snapshot for the Home IoT example.
+- `service_heavy_cli_edit_v1.inventory.json`
+  Service-heavy server example focused on DNS, DHCP, FTP, email, syslog, AAA, and related service metadata.
+- `screenshots/service_heavy_cli_edit_v1.png`
+  Topology snapshot for the Service Heavy example.
+- `screenshots/service_heavy_cli_edit_v1_*.png`
+  Additional service detail screenshots for DHCP, DNS, and FTP views.
+- `index.json`
+  Lightweight gallery index for curated example artifacts.
+
+Rebuild the gallery index:
+
+```powershell
+python .\scripts\build_examples_index.py
+```
+
+Generated outputs:
+- `index.json`
+  Machine-readable curated example index.
+- `gallery.md`
+  Human-readable markdown gallery generated from the same source, positioned as the known working scenario set.
+- `previews/*.svg`
+  Generated fallback preview images for examples that do not yet have real Packet Tracer screenshots.
+
+Gallery families:
+- `campus`
+  VLAN, management, ACL, server services, and wireless edits.
+- `home_iot`
+  Home gateway, IoT things, and registration-focused examples.
+- `service_heavy`
+  Server-centric service labs with richer metadata.
+
+Launch-prep references:
+- `..\docs\hero-demo-plan.md`
+- `..\docs\release-notes-0.2.0.md`

package/examples/complex_campus_master_edit_v4.inventory.json

@@ -0,0 +1,94 @@
+{
+  "example_name": "complex_campus_master_edit_v4",
+  "source_mode": "donor-backed edit",
+  "scenario_family": "campus",
+  "public_repo_policy": {
+    "commit_pkt_binary": false,
+    "commit_inventory_json": true
+  },
+  "artifact_paths": {
+    "screenshot": "examples/screenshots/complex_campus_master_edit_v4.png",
+    "screenshots": [
+      "examples/screenshots/complex_campus_master_edit_v4.png"
+    ],
+    "inventory_json": "examples/complex_campus_master_edit_v4.inventory.json"
+  },
+  "topology_summary": {
+    "network_style": "campus",
+    "core_router": "Router0",
+    "switches_with_management": [
+      "Switch Management",
+      "Switch Emeliyyat",
+      "Switch IT",
+      "Switch Maliyye",
+      "Switch Muhendislik",
+      "Switch Security"
+    ],
+    "wireless_routers": [
+      "Wireless Router0",
+      "Wireless Router1",
+      "Wireless Router2",
+      "Wireless Router3",
+      "Wireless Router4"
+    ]
+  },
+  "management_summary": {
+    "management_vlan": 99,
+    "default_gateway": "192.168.99.1",
+    "telnet_enabled_switches": [
+      "Switch Management",
+      "Switch Emeliyyat",
+      "Switch IT",
+      "Switch Maliyye",
+      "Switch Muhendislik",
+      "Switch Security"
+    ],
+    "username": "admin"
+  },
+  "routing_security_summary": {
+    "acl_names": {
+      "Router0": [
+        "MGMT_ONLY"
+      ]
+    }
+  },
+  "server_service_summary": {
+    "Server0": {
+      "services": [
+        "dns_server",
+        "email_server",
+        "ftp_server",
+        "http_server",
+        "https_server",
+        "ntp_server",
+        "syslog_server",
+        "tftp_server"
+      ],
+      "email_domain": "campus.local"
+    },
+    "Server1": {
+      "services": [
+        "acs_server",
+        "email_server",
+        "ftp_server",
+        "http_server",
+        "https_server",
+        "ntp_server",
+        "syslog_server",
+        "tftp_server"
+      ],
+      "aaa_auth_port": "1812"
+    }
+  },
+  "wireless_summary": {
+    "Wireless Router0": "OPS_WIFI",
+    "Wireless Router1": "IT_WIFI",
+    "Wireless Router2": "FIN_WIFI",
+    "Wireless Router3": "ENG_WIFI",
+    "Wireless Router4": "SEC_WIFI"
+  },
+  "verification_status": {
+    "inventory_roundtrip_verified": true,
+    "full_pytest_passed": true
+  }
+}

package/examples/gallery.md

@@ -0,0 +1,39 @@
+## Known Working Scenario Set
+
+These examples are public, text-first proof artifacts derived from donor-backed workflows and aligned with the scenario fixture corpus.
+
+`0.2.0` canonical public set:
+
+- `campus`
+- `home_iot`
+- `service_heavy`
+
+Hero visual:
+
+- [complex campus screenshot](screenshots/complex_campus_master_edit_v4.png)
+
+| Title | Family | Capabilities | Image | Inventory |
+| --- | --- | --- | --- | --- |
+| Complex Campus | `campus` | management_vlan, telnet, acl, server_dns, server_email, server_aaa, wireless_mutation | [screenshot](screenshots/complex_campus_master_edit_v4.png) | [manifest](complex_campus_master_edit_v4.inventory.json) |
+|  |  | Management VLAN, Telnet, ACL, DNS, email, AAA, and multi-SSID wireless campus edit. |  |  |
+|  |  | `known_working_example | donor=donor-backed | capabilities=management_vlan, telnet, acl` |  |  |
+|  |  | `campus_core_complex | known_working_example | family=campus` |  |  |
+|  |  | `management_vlan=generate-ready, telnet=generate-ready, acl=generate-ready` |  |  |
+|  |  | `decision=known_working_example | donor_origin=donor-backed` |  |  |
+|  |  | `runtime=donor-backed example artifact` |  |  |
+| Home IoT | `home_iot` | iot, iot_registration, wireless_ap | [screenshot](screenshots/home_iot_cli_edit_v1.png) | [manifest](home_iot_cli_edit_v1.inventory.json) |
+|  |  | Home gateway and IoT device onboarding with gateway-backed registration state. |  |  |
+|  |  | `known_working_example | donor=donor-backed | capabilities=iot, iot_registration, wireless_ap` |  |  |
+|  |  | `home_iot_complex | known_working_example | family=home_iot` |  |  |
+|  |  | `iot=generate-ready, iot_registration=generate-ready, wireless_ap=generate-ready` |  |  |
+|  |  | `decision=known_working_example | donor_origin=donor-backed` |  |  |
+|  |  | `runtime=donor-backed example artifact` |  |  |
+| Service Heavy | `service_heavy` | server_dns, server_dhcp, server_ftp, server_email, server_syslog, server_aaa | [screenshot](screenshots/service_heavy_cli_edit_v1.png) | [manifest](service_heavy_cli_edit_v1.inventory.json) |
+|  |  | Service-rich server lab with DNS, DHCP, FTP, email, syslog, AAA, and detailed service metadata. |  |  |
+|  |  | `known_working_example | donor=donor-backed | capabilities=server_dns, server_dhcp, server_ftp` |  |  |
+|  |  | `service_heavy_complex | known_working_example | family=service_heavy` |  |  |
+|  |  | `server_dns=generate-ready, server_dhcp=generate-ready, server_ftp=generate-ready` |  |  |
+|  |  | `decision=known_working_example | donor_origin=donor-backed` |  |  |
+|  |  | `runtime=donor-backed example artifact` |  |  |
+|  |  | extra visuals: [detail 1](screenshots/service_heavy_cli_edit_v1_dhcp.png); [detail 2](screenshots/service_heavy_cli_edit_v1_dns.png); [detail 3](screenshots/service_heavy_cli_edit_v1_ftp.png) |  |  |
+

package/examples/home_iot_cli_edit_v1.inventory.json

@@ -0,0 +1,58 @@
+{
+  "example_name": "home_iot_cli_edit_v1",
+  "source_mode": "donor-backed edit",
+  "scenario_family": "home_iot",
+  "public_repo_policy": {
+    "commit_pkt_binary": false,
+    "commit_inventory_json": true,
+    "commit_screenshot": false
+  },
+  "artifact_paths": {
+    "inventory_json": "examples/home_iot_cli_edit_v1.inventory.json",
+    "screenshot": "examples/screenshots/home_iot_cli_edit_v1.png",
+    "screenshots": [
+      "examples/screenshots/home_iot_cli_edit_v1.png"
+    ]
+  },
+  "topology_summary": {
+    "gateway": "Home Gateway0",
+    "iot_things": [
+      "door0",
+      "door1"
+    ]
+  },
+  "wireless_summary": {
+    "Home Gateway0": "HomeGateway",
+    "door0": "HomeGateway",
+    "door1": "HomeGateway"
+  },
+  "iot_summary": {
+    "Home Gateway0": {
+      "role": "gateway",
+      "type": "HomeGateway",
+      "http_enabled": true
+    },
+    "door0": {
+      "role": "thing",
+      "type": "MCUComponent",
+      "client_mode": "LAN_SERVER",
+      "server_address": "192.168.25.1",
+      "username": "admin"
+    },
+    "door1": {
+      "role": "thing",
+      "type": "MCUComponent",
+      "client_mode": "LAN_SERVER"
+    }
+  },
+  "service_summary": {
+    "Home Gateway0": [
+      "http_server",
+      "dhcp_server"
+    ]
+  },
+  "verification_status": {
+    "inventory_roundtrip_verified": true,
+    "full_pytest_passed": true
+  }
+}