packet-tracer-skill 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -4,6 +4,122 @@ All notable changes to this project should be recorded in this file.
 
 The format is intentionally simple and release-oriented.
 
+## [0.3.2] - 2026-09-12
+
+### Picking up a half-finished edit session
+
+Almost nothing here needs remembering between turns: `--doctor`,
+`--explain-plan` and `--parity-report` all recompute from the install, the
+donor registry and the bridge, so an agent that has lost its earlier context
+re-runs one and is exactly as certain as before. One question had no such
+source -- part-way through `--explain-plan` -> `--edit` -> `--parity-report`,
+*which lab am I working on and what comes next*.
+
+### Added
+
+- `output/session-log.jsonl`, one line per run, and two flags that read it
+  back: `--session-state` lists the labs in flight, `--resume <lab.pkt>` says
+  where one was left.
+- `--resume` re-hashes the lab and compares it with what the last step
+  recorded, and claims a position **only when the two agree**. When they do
+  not it says the lab has changed and to re-derive instead -- the same
+  refusal-first stance the rest of the skill takes. Verified first that a
+  digest can carry that weight: decoding a lab and re-encoding it reproduces
+  the file byte for byte.
+- Three constraints, each with a test. No secrets: facts are allow-listed
+  rather than filtered, because an edit prompt holds a passphrase in a field
+  called `passphrase` and a deny-list would leak whatever secret field is added
+  next; the prompt survives only as a non-reversible shape fingerprint. No
+  weight: a test regenerates a lab with and without the log and compares the
+  decoded content. Ships nowhere: `output/` is gitignored and in no
+  `package.json` file list, checked rather than assumed.
+
+### Fixed
+
+- `PKT_USAGE_LEDGER=on`, the obvious way to switch learning on, made the path
+  resolver treat `"on"` as a filename and write the ledger to a file called
+  `on` in the working directory. One variable carrying two meanings with only
+  one of its two readers knowing the switch words. Found by doing it.
+- `--session-state` and `--resume` were recorded as steps by the same wrapper
+  as the work they report on, so each recovery pushed itself in front of the
+  real chain. In a bounded log a reader that writes eventually evicts the steps
+  it exists to report.
+
+### Changed
+
+- `main()` is split into `_build_parser`, `_dispatch` and a wrapper that
+  records once around the whole dispatch. Fourteen branches with twelve return
+  points is not somewhere to repeat a hook.
+
+847 passed, 1 skipped. Corpus: 32 of 33 generated, 31 opened, 0 unexpected.
+
+## [0.3.1] - 2026-09-06
+
+### Wireless labs that actually carry traffic
+
+`0.3.0` shipped wireless topologies that opened and passed every static check
+while no client could reach anything. Measured on a generated lab after this
+release: a laptop takes its lease from the home router and pings the gateway
+and the other laptop 4/4, over Wi-Fi, on an open network and on WPA2.
+
+Six facts about one wireless lab were each decided in two places with nothing
+comparing them, and every one of them had to be fixed before a packet moved.
+
+### Fixed
+
+- **The access point's key was written where Packet Tracer does not read it.**
+  A working WPA2 home router keeps `WIRELESS_COMMON/WEP_PROCESS/KEY` with
+  `WEP_PROCESS/ENCRYPTION`, and carries no `WPA_PASSPHRASE` at all -- the field
+  names are legacy and WPA2 uses them. Choosing the field by authentication
+  type left the access point running WPA2 with no key while its clients had
+  one. Both sides looked right in every field anyone was reading.
+- **A home router's DHCP lease records were deleted when its LAN moved.** That
+  is how a client gets its address back when the file opens; they are
+  renumbered into the new pool now, and a lease naming a client the prune
+  removed is dropped.
+- **The client's security, network name and addressing mode never followed the
+  access point.** `set_wireless_ssid` wrote the access point;
+  `associate_wireless_client` wrote only the SSID. A repair pass now carries
+  authentication, encryption, key and network type across, and only into the
+  live profile -- every working client leaves its saved `PROFILES` list as the
+  donor's boilerplate.
+- **A home router served whatever network its donor had.** The laptops were
+  addressed on the planned network and the router on the donor's; the router
+  now moves onto the one its own clients point at, and its pool with it.
+- **The layout placed wireless clients out of radio range.** Hosts were laid
+  out in rows under the switch they hang off, and a wireless client hangs off
+  nothing -- one landed 420 units from a router whose radio reaches 250.
+- **`port_exists` accepted interface names a home router does not have.** It
+  checked only the port index, so `FastEthernet0/1` passed on a device whose
+  sockets are `Ethernet 1` .. `4`, and with no interfaces in its configuration
+  `Ethernet 99` passed too. Both models were read off the live devices; the
+  repair pass reads the same list, so a wrong name is renamed rather than the
+  cable dropped.
+- **The coherence checker could not see a home router's LAN address.** It walks
+  running configs, and that address is a setting, so it reported
+  `gateway_answers_for_nobody` against a router holding exactly that address.
+
+### Changed
+
+- The committed sample catalogue is limited to the labs it may publish.
+  Rebuilding it on a machine with saved labs had staged 350 entries naming
+  their owner, with absolute paths under their home directory, into a file
+  bound for a public repository. Local labs go to a git-ignored file beside it
+  and donor ranking reads both, so nothing about donor choice changed.
+- Comments, docs and fixtures no longer identify their evidence by the filename
+  of someone's saved lab.
+
+### Notes on measurement
+
+`pt_inspect_ports` immediately after a lab opens shows a wireless client as
+`up`, `linked`, `ip 0.0.0.0`. That is a first reading and means nothing -- a lab
+Packet Tracer saved itself, seconds after it pinged 4/4, reads the same way on
+reopen. Several hypotheses were rejected against that control rather than
+argued: radio bandwidth matching, channel matching, `NETWORK_TYPE`, and the
+belief that only a runtime nudge could make association work.
+
+833 passed, 1 skipped. Corpus: 32 of 33 generated, 31 opened, 0 unexpected.
+
 ## [0.3.0] - 2026-08-06
 
 ### First verified generation

package/README.md

@@ -10,7 +10,7 @@ This repository is built for one job: take a natural-language network request, b
 
 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.
 
-## What `0.3.0` does
+## What `0.3.2` does
 
 In this release a prompt produces a lab Packet Tracer opens.
 
@@ -24,11 +24,12 @@ inspecting the file.
 
 | measurement | result |
 | --- | --- |
-| corpus scenarios generated | 32 of 33 |
-| of those, opened by Packet Tracer | 32 of 32 |
-| tests | 657 passed, 1 skipped |
+| corpus scenarios generated | 32 of 33 (the 33rd asks for no devices and is refused) |
+| of those, opened by Packet Tracer | 31 of 32 |
+| tests | 833 passed, 1 skipped |
 | generated DHCP lab | four PCs took leases from the router pool and pinged their gateway and each other 4/4 |
 | generated leased line | traffic crossed `Serial0/1/1 <-> Serial0/1/0` 4/4 |
+| generated home-router lab | both hosts pinged the gateway and each other 4/4, cabled and over Wi-Fi, open and WPA2 |
 
 Three defects had made every generated WAN lab unopenable, each hiding the next.
 A donor the selector had *rejected* still rewrote the request, so a planned
@@ -43,6 +44,14 @@ donor-prune generation: a real lab is pruned and rewired to match the request.
 The atlas `generate_ready` count further down is a stricter per-feature
 acceptance gate, still `0` by design.
 
+**One thing to know when you check a Wi-Fi lab.** Read a wireless client once,
+straight after the file opens, and it will look broken: port `up` and `linked`,
+`ip 0.0.0.0`, the radio at its un-negotiated rate. That is a first reading and
+means nothing -- the client has not finished taking its lease. Read it again and
+it holds its address and pings. A lab Packet Tracer saved itself, seconds after
+it pinged 4/4, reads the same way on reopen, which is how we know the reading
+rather than the lab is at fault.
+
 The previous line, the `0.2.3` capability release, was focused on:
 
 - donor-backed and scenario-aware public messaging
@@ -220,6 +229,34 @@ Launch references:
 - [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)
 
+## Picking Up A Half-Finished Edit Session
+
+Almost nothing in this skill needs remembering between turns. `--doctor`,
+`--explain-plan` and `--parity-report` recompute from the install, the donor
+registry and the bridge, so an agent that has lost its earlier context re-runs
+one and is exactly as certain as before.
+
+One question has no such source: part-way through
+`--explain-plan` -> `--edit` -> `--parity-report`, *which lab am I working on
+and what comes next*. Each run now appends a line to
+`output/session-log.jsonl`, and two flags read it back:
+
+```powershell
+python scripts\generate_pkt.py --session-state
+python scripts\generate_pkt.py --resume output\lab.pkt
+```
+
+`--resume` re-hashes the lab and compares it with what the last step recorded.
+A position is reported **only when the two agree**; otherwise it says the lab
+has changed and to re-derive instead. That refusal is the useful answer, and it
+is the same stance the rest of the skill takes when it cannot prove something.
+
+The log carries no secrets (facts are allow-listed, and the prompt survives
+only as a non-reversible shape fingerprint), carries no weight (a test
+regenerates a lab with and without it and compares the decoded content), and
+ships nowhere (`output/` is gitignored and in no `package.json` file list).
+`PKT_SESSION_LOG=off` disables it.
+
 ## Runtime Doctor Contract
 
 `--doctor` is a product surface, not a debug afterthought. It reports:
@@ -589,7 +626,7 @@ See also:
 
 ## Release and Launch State
 
-The current line is `packet-tracer-skill@0.3.0`, and it is the first release
+The current line is `packet-tracer-skill@0.3.2`, and it is the first release
 where generation is the headline rather than a deferred promise. `0.2.3`, the
 previous published line, was a capability proof and readiness release that
 deliberately refused broad generation.
@@ -643,21 +680,30 @@ qurur, mövcud faylı redaktə edir və hər iddiasını ölçü ilə əsasland
 fayl Packet Tracer-də açılır və cihazları bir-birini ping edir; alınmayanda
 səbəbini açıq deyir.
 
-### `0.3.0` nə dəyişdi
+### `0.3.2` nə dəyişdi
 
 Bu, promptun Packet Tracer-in açdığı fayla çevrildiyi ilk buraxılışdır.
 
 | Ölçü | Nəticə |
 | --- | --- |
-| korpusda qurulan ssenari | 33-dən 32 |
-| onlardan Packet Tracer-in açdığı | 32-dən 32 |
-| testlər | 657 keçdi, 1 ötürüldü |
+| korpusda qurulan ssenari | 33-dən 32 (33-cü heç bir cihaz istəmir, rədd edilir) |
+| onlardan Packet Tracer-in açdığı | 32-dən 31 |
+| testlər | 833 keçdi, 1 ötürüldü |
 | DHCP laboratoriyası | 4 kompüter routerin hovuzundan ünvan aldı, şlüzə və bir-birinə 4/4 ping |
 | icarə xətti (leased line) | trafik `Serial0/1/1 <-> Serial0/1/0` üzərindən 4/4 keçdi |
+| ev routeri laboratoriyası | hər iki host şlüzə və bir-birinə 4/4 ping etdi -- kabel və Wi-Fi, açıq və WPA2 |
 
 Ping rəqəmləri cihazların özündə `ping` işlədilməklə alınıb. Bu layihədə bütün
 statik yoxlamaları keçən, amma heç nəyin ping etmədiyi laboratoriyalar olub.
 
+**Wi-Fi laboratoriyasını yoxlayarkən bilməli olduğunuz bir şey.** Fayl açılan
+kimi simsiz klienti bir dəfə oxusanız, xarab görünəcək: port `up` və `linked`,
+`ip 0.0.0.0`, radio danışılmamış sürətdə. Bu **ilk oxunuşdur** və heç nə demir --
+klient hələ icarəsini almayıb. İkinci dəfə oxuyun: ünvanı olur və ping edir.
+Packet Tracer-in özünün yaddaşa verdiyi, saniyələr əvvəl 4/4 ping edən fayl da
+yenidən açılanda eyni cür oxunur -- səhv olanın lab yox, oxunuş olduğunu bundan
+bilirik.
+
 ### Nə düzəldildi
 
 Generasiya edilən hər WAN laboratoriyası açılmırdı və bunun arxasında bir-birini

package/SKILL.md

@@ -37,6 +37,210 @@ Useful ideas from `MCP-Packet-Tracer` were adopted only at the architecture
 level. PTBuilder live deploy and external donor usage were intentionally not
 adopted.
 
+## Using This Skill Correctly
+
+Read this before generating anything. Every rule below was learned by measuring
+a lab that looked finished and was not.
+
+### A lab that opens is not a lab that works
+
+This is the single most expensive mistake available here. Generated labs have
+passed every structural check, opened cleanly in Packet Tracer, read correctly
+line by line, and been unable to pass a single packet. "It opened" tells you
+the container is valid. It tells you nothing about the network.
+
+Two things separate a finished lab from a plausible one:
+
+```bash
+python scripts/generate_pkt.py --coherence-report output/lab.pkt
+```
+
+and a live ping. Do both. `--coherence-report` exits non-zero when the lab
+contradicts itself, and generation prints the same summary as a `WARNING:` line
+when it hands the file over — never ignore that line.
+
+### What the coherence report is telling you
+
+Every defect this project has paid for has one shape: **a fact derived twice,
+in two passes, with nothing comparing the derivations.** Each half reads
+correctly on its own. The report is that comparison:
+
+| Finding | What it means |
+|---|---|
+| `interface_declared_twice` | IOS keeps the last block; readers scan the first |
+| `port_not_on_device` | Packet Tracer refuses to open the file |
+| `port_double_booked` | two cables on one socket |
+| `duplicate_address` | two interfaces claim one address |
+| `real_address_is_also_virtual` | a router holds an address that is someone's HSRP virtual |
+| `native_vlan_mismatch` | spanning tree blocks a cabled, configured port |
+| `etherchannel_peer_does_not_bundle` | the switch behind it drops off the network |
+| `gateway_answers_for_nobody` | a static host points at an address nothing holds |
+| `pool_without_interface` | DHCP hands out addresses nothing can route |
+
+The report never repairs. A checker that fixes what it finds stops being able
+to tell you whether the thing it checks is working.
+
+### Measuring in a live Packet Tracer
+
+Three steps, in order, every time:
+
+1. **Confirm which document is open.** With two windows open the bridge answers
+   for the other one. A pass rate measured against the wrong lab is worse than
+   no measurement, because it is believed. Check the device list first.
+2. **Throw the first reading away.** Spanning tree has not converged; the first
+   ping after opening a large lab reports 0/4 on a path that works. It is not a
+   measurement, it is the lab starting up.
+3. **Then measure.** A *failing* ping takes far longer than a passing one --
+   each packet waits out its own timeout, about 13 seconds for four -- so
+   budget 45-60s per call rather than reading a timeout as a failure.
+
+Ping from a host. Routers and switches answer through a different bridge path
+that is not reliable here.
+
+### When two repairs in a row do not change the measurement
+
+Stop repairing. The symptom is not where the defect is. Find the pass that
+wrote the state, and fix it there. The fastest way in: **diff the broken device
+against a working sibling.** One switch unreachable while identical ones work
+has one extra line, and reading configuration top to bottom will not find it as
+quickly as `diff` will.
+
+### Facts about Packet Tracer that cost a lab each
+
+- a copper cable in a fibre socket is **dropped in silence** -- the file opens,
+  the cable is simply not there
+- a duplicate `interface` block is applied last-wins, while readers scan the first
+- a subinterface `ip address` before its `encapsulation dot1Q` is refused
+  silently
+- `PORT_DHCP_ENABLE=true` makes Packet Tracer ignore the static address in the
+  file; a host with both is a DHCP client, and judging it on its stale address
+  is a false reading
+- DHCP snooping with no trusted uplink eats every offer the router sends
+- port security on a trunk isolates the whole switch behind it
+- a `channel-group` whose peer does not bundle takes that switch off the network
+- an interface name the device does not own blocks the file from opening at all;
+  a double-booked port does not
+- a `vlan N` line in a switch's configuration does **not** create the VLAN --
+  Packet Tracer keeps the database separately, and a port assigned to a VLAN
+  that is not in it forwards nothing
+- a top-level command written straight after an indented sub-block line is
+  swallowed; the `!` between them is load-bearing
+- a home router's sockets are named, not slotted, and the spelling is the
+  model's: `Ethernet 1` .. `4` on `WirelessRouter`, `GigabitEthernet 1` .. `4`
+  on `WirelessRouterNewGeneration`, and `Internet` for the uplink on both. It
+  writes no interfaces into its configuration, so nothing else can tell you
+- a home router's LAN address is a **setting**, not a config line, and lives in
+  `ENGINE/LAN_IP_ADDRESS` with its pool under `ENGINE/DHCP_SERVER/POOLS/POOL`;
+  a reader that only walks running configs cannot see it
+- a wireless client's addressing comes from its `WIRELESS_PROFILE`, not from
+  its port -- both record it, and Packet Tracer obeys the profile
+- a radio link is made by **distance**. A client outside the access point's
+  `COVERAGERANGE` reports its port `up` and `linked` and passes nothing
+- an access point's WPA key lives in `WIRELESS_COMMON/WEP_PROCESS/KEY` with
+  `WEP_PROCESS/ENCRYPTION`, never in `WPA_PASSPHRASE`. The names are legacy and
+  WPA2 uses them; the client side is the same shape. Put it in the wrong field
+  and the access point runs WPA2 with no key while its clients have one
+- a wireless client reads `ip 0.0.0.0` at its un-negotiated rate for the first
+  moments after a lab opens, even in a lab Packet Tracer saved itself while it
+  was pinging 4/4. `pt_inspect_ports` right after opening is a **first reading**
+  and has to be discarded exactly like a first ping
+- a home router's DHCP **lease records** are how a client gets its address back
+  when the file opens; move its LAN and they have to be renumbered, not dropped
+- the builder MCP's device table is not authoritative about port names; it
+  gives the AC home router `Ethernet 1` .. `4`, and the device itself says
+  `GigabitEthernet 1` .. `4`. `pt_inspect_ports` answers at the IOS layer,
+  where those sockets are bridged into `Vlan1` and do not appear at all --
+  `pt_query_topology` is the one that lists them
+
+### Drawing the topology yourself
+
+The generator packs switch blocks into a roughly square grid, which is fine for
+a lab nobody planned. When you have already decided the shape -- which
+department sits where, which switch faces which, where the core belongs -- say
+so in the blueprint and set `PACKET_TRACER_LAYOUT=keep`. Every `x`/`y` in the
+blueprint is then left exactly as given, and the frames are drawn around the
+devices where they land.
+
+Sketch first, build second, is the better order for anything a person will
+look at: you can see the whole diagram before a single cable exists, and the
+skill's job narrows to making the file match the drawing.
+
+Without the knob the packing applies, and it is deterministic: the same
+blueprint gives the same coordinates every time, so a regenerated lab does not
+drift.
+
+### Scale
+
+There is no artificial device limit. The only ceiling is physical: a switch has
+the ports it has, and the generator says so plainly when it runs out. Ask for
+more switches, not fewer hosts.
+
+### If you lost the thread part-way through an edit chain
+
+Almost nothing here needs remembering. `--doctor`, `--explain-plan` and
+`--parity-report` all recompute from the install, the donor registry and the
+bridge, so re-running one costs time and nothing else. Losing the conversation
+does not make the skill less certain about anything it reports.
+
+One question has no such source. Part-way through
+`--explain-plan` -> `--edit` -> `--parity-report`, *which lab am I working on
+and what comes next* lived only in the conversation. So each run appends a line
+to `output/session-log.jsonl`, and two flags read it back:
+
+```bash
+python scripts/generate_pkt.py --session-state          # which labs are in flight
+python scripts/generate_pkt.py --resume output/lab.pkt  # where this one was left
+```
+
+`--resume` re-hashes the lab and compares it to what the last step recorded. It
+reports a position **only when the two agree**; when they do not, it says the
+lab has changed and tells you to re-derive instead. Treat "position not
+claimed" as the correct answer, not a failure -- it is the same refusal-first
+stance as everything else here.
+
+Three things the log deliberately is not:
+
+- **not a secret store.** Facts are allow-listed, never filtered. An edit
+  prompt carries a passphrase in an ordinary field, so nothing is written but
+  the named, known-safe keys, and the prompt survives only as the same
+  non-reversible shape fingerprint the usage ledger uses.
+- **not load-bearing.** Delete it and every result is identical; there is a
+  test that regenerates a lab with and without it and compares the content.
+- **not shipped.** It lives under `output/`, which is gitignored and in no
+  `package.json` file list.
+
+`PKT_SESSION_LOG=off` turns it off; `PKT_SESSION_LOG=<path>` moves it.
+
+### A generated lab becomes the next build's donor
+
+Donor selection can pick a lab this skill produced, so every repair pass
+eventually runs over its own output. Write interface configuration with
+`_set_config_block`, never by appending, and check a new pass by running it
+three times and asserting the document stops changing after the first.
+
+### The palette is not the vocabulary
+
+Packet Tracer's device palette lists more kinds than a saved lab distinguishes:
+`SMARTPHONE-PT` saves as `Pda`, `Fiber Patch Panel` saves as `Patch Panel`.
+Adding an askable kind with no donor behind it produces a request that can only
+come back as an undelivered device. `tests/test_askable_kinds_have_donors.py`
+holds the vocabulary to what real labs actually contain, in both directions.
+
+### When generation refuses
+
+A refusal returns `blocking_gaps` together with a `blueprint_plan`. That is not
+a failure to work around by loosening a policy -- it is the skill saying no
+donor can serve the request. Read the gaps, adjust the request or supply a
+donor, and try again.
+
+### What works without Packet Tracer installed
+
+Decode, inventory, edit, generate and structural verification all work from the
+donor cache with no install and no environment variables -- the Twofish engine
+is vendored pure Python. Only `--validate-open` and live pings need the
+application itself. Tests that build a lab are marked `requires_donors` and skip
+where there is nothing to build from.
+
 ## How `.pkt` Files Work
 
 For the modern format targeted by this skill, the pipeline is:
@@ -226,8 +430,10 @@ If the user does not specify details:
 
 ## Constraints
 
-- The builder depends on a local Packet Tracer installation with the bundled
-  sample saves present, on any of Windows, macOS or Linux
+- The builder needs Packet Tracer's bundled sample saves as prototype sources,
+  from a local installation on Windows, macOS or Linux **or** from the donor
+  cache under `~/.pkt/saves`, which a single generate run on an installed
+  machine populates and which can then be copied anywhere
 - Donor devices the plan does not need are deleted. `PACKET_TRACER_SPARE_STRATEGY=park`
   restores the older behaviour of renaming them `UNUSED-*` / `*-SPARE-*` and
   moving them offscreen, if a donor turns out to depend on one staying present
@@ -252,6 +458,12 @@ Generate from a blueprint file:
 python scripts/generate_pkt.py --blueprint examples/blueprint_minimal.json --output output\minimal.pkt
 ```
 
+Check what a finished lab contradicts about itself, and exit non-zero if it does:
+
+```powershell
+python scripts/generate_pkt.py --coherence-report output\campus.pkt
+```
+
 Generate from a hybrid prompt:
 
 ```powershell

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "packet-tracer-skill",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "private": false,
   "description": "Donor-backed Cisco Packet Tracer 9.x skill for natural-language planning, safe-open generation, editing, parity reporting, and runtime diagnostics across coding hosts.",
   "keywords": [
@@ -75,6 +75,7 @@
     "scripts/vendor/twofish_pure.py",
     "templates",
     "references/*.json",
+    "!references/local-donor-catalog.json",
     "references/*.md",
     "examples/README.md",
     "examples/gallery.md",

package/scripts/build_sample_catalog.py

@@ -11,19 +11,61 @@ now calls it rather than keeping a second, weaker copy.
 
 from __future__ import annotations
 
+from pathlib import Path
+
 from packet_tracer_env import require_packet_tracer_saves_root
 from sample_catalog import _summarize_pkt, write_catalog_outputs
 
 
+def _local_donor_items(catalogued: set[str]) -> list[dict]:
+    """Labs the user saved outside the Packet Tracer installation.
+
+    Donor selection ranks candidates from this catalogue, and the catalogue
+    only ever held the installed samples. So a lab saved specifically to serve
+    as a donor was discovered by `discover_local_donors`, reported as present,
+    and never ranked -- generation for a five-switch topology stayed blocked
+    with "no ranked donor candidate passed validation" while a donor that fit
+    sat on disk.
+
+    These entries carry an absolute `path` rather than one relative to the
+    saves root, which is why `_catalog_item_path` has to keep it.
+    """
+    try:
+        from local_donors import discover_local_donors
+    except ImportError:  # pragma: no cover - discovery is optional
+        return []
+
+    items: list[dict] = []
+    for donor in discover_local_donors():
+        path = Path(donor.path)
+        if str(path) in catalogued or not path.is_file():
+            continue
+        try:
+            item = _summarize_pkt(path, path.name, "user-local", True)
+        except Exception as exc:
+            items.append(
+                {"relative_path": path.name, "source_path": str(path), "error": f"{type(exc).__name__}: {exc}"}
+            )
+            continue
+        # `source_path`, not `path`: the writer drops `path` so the committed
+        # catalogue does not depend on whose machine built it.
+        item["source_path"] = str(path)
+        items.append(item)
+    return items
+
+
 def build_catalog() -> list[dict]:
     saves_root = require_packet_tracer_saves_root()
     items: list[dict] = []
+    catalogued: set[str] = set()
     for path in sorted(saves_root.rglob("*.pkt")):
         relative_path = str(path.relative_to(saves_root))
+        catalogued.add(str(path))
         try:
             items.append(_summarize_pkt(path, relative_path, "cisco-local", True))
         except Exception as exc:
             items.append({"relative_path": relative_path, "error": f"{type(exc).__name__}: {exc}"})
+    items.extend(_local_donor_items(catalogued))
     return items