Altium - the Altium Bridge

@@ -0,0 +1,94 @@+---+name: altium-licensing+description: >-+  Altium's On-Demand licence seat, and the ONE mistake that costs an hour: killing Altium strands+  the seat, after which the licence page reports it FREE (Seats 0/1) while refusing every claim+  with "License maximum usage reached". Covers the one-seat-per-machine rule (Altium Designer and+  Altium Designer Develop share it), how to swap the seat between apps, how to recover a stranded+  one, and why Develop's window title does not say it is licensed. Read when a verb returns+  not_licensed, when the title says "No License" or "Viewer", when a claim fails, or BEFORE closing+  or killing any Altium. Trigger words — altium licence, altium license, no license, viewer mode,+  license maximum usage reached, license renewal failed, seat, on-demand, use license, release+  license, stranded seat, altium_close force, two altiums one seat.+---++# altium-licensing++Parent skill: [altium-bridge](../altium-bridge/SKILL.md).++## The rule that explains almost everything++**One On-Demand seat serves EVERY Altium app on the machine.** Altium Designer and Altium Designer+Develop draw from the *same* seat — on John's box the trial licence is literally named+`Altium Designer Develop` (On-Demand, Single Site, 1 seat) and both apps use it. So:++* Two Altiums can RUN at once. Only ONE can be LICENSED at once.+* The unlicensed one falls back to **Viewer**, where Altium refuses scripting — so the bridge's+  agent cannot start there, and every verb gated by `_need_licensed` returns `not_licensed`.+* You do NOT need a second trial to use Develop. You need the seat.++## NEVER kill an Altium that holds the seat++`taskkill` / `process_kill` / a crash all end the process WITHOUT releasing the lease. The result is+the worst kind of failure — one that lies to you:++```+licence page:  Seats 0/1        <- looks free+every claim:   "License maximum usage reached. Please contact your Administrator+                to add or release seats for this license."+```++Waiting does not clear it. `Refresh` on that page is a hyperlink the UIA layer cannot invoke.++**Recovery, measured 2026-09-01:** `altium_close` (polite WM_CLOSE) on the instance that held it+releases the lease immediately; then `altium_license {action:"use_license"}` claims it. That is the+whole fix, and nothing else worked.++`altium_close {force:true}` now refuses unless you also pass `acceptSeatLoss:true`, precisely so this+cannot be reached for casually.++## Swapping the seat between Designer and Develop++```bash+altium_agent_stop                                  # nothing mid-flight+altium_close                                       # polite: releases the seat+#   an Unsaved Changes prompt NAMES the documents — READ IT. On a shared machine one may belong to+#   ANOTHER AI thread. Save preserves their work; Don't Save destroys it. Never default this.+#   launch the other app; it claims the free seat SILENTLY at startup, no clicking:+shell_execute 'Start-Process "C:\Program Files\Altium\ADDevelop\X2.EXE"'+altium_agent_start '{"instance":"develop"}'+```++## Develop does not admit it is licensed++Altium Designer writes the licence into its title (`… - Trial`, `… - No License`).+**Altium Designer Develop writes NOTHING when it HOLDS a seat** — only `- Viewer` when it does not.++So a blank `licenceState` on Develop does **not** mean unlicensed. On 2026-09-01 `altium_instances`+reported ADD unlicensed for an entire test while its agent bootstrapped and imported five parts+without complaint. The bridge now treats an absent tail on a Develop edition as *licensed, kind+unknown* — but if you are reading a raw title, remember it.++## Reclaiming without an agent++The licence page is a WebView2 whose DOM IS in the UIA tree, so the quiet lane works even with no+agent running (no cursor, no foreground):++```bash+desktop_ui_click '{"hwnd":<main>,"automationId":"UseLicenseButton"}'   # claim+desktop_ui_click '{"hwnd":<main>,"automationId":"ReleaseButton"}'      # release+```++Both were verified live. `Refresh` and `Sign Out` are links, not buttons — UIA cannot invoke them.++In **Develop** the account menu is NOT UIA-addressable at all (no `Manage Seats`, no account button,+`desktop_ui_from_point` returns nothing), so there is no in-app quiet lane to its licence page. Do+not burn time hunting for one: free the seat elsewhere and let Develop take it at startup.++## Dialogs this produces++| dialog | meaning | do |+|---|---|---|+| `License maximum usage reached` | seat stranded by a killed instance | close other Altiums politely, then claim |+| `License Renewal Failed` | same cause; **re-fires on a timer** | clearing it is not the fix |+| `You are not currently using an Altium Designer license` | seat free, nobody claimed it | `Choose a license` → `Use License` |

@@ -0,0 +1,99 @@+---+name: altium-wiki-import+description: >-+  Import a component from the Adom wiki into Altium — one part page, or a whole Cloud Library+  (Colby's component cart) — with symbol, footprint, 3D body and Mouser/DigiKey/LCSC identity, in+  seconds, without foregrounding Altium. Covers the Cloud Library's Altium gap (export --format+  altium is phase 3; KiCad + Fusion ship today) and the working pipeline that closes it, plus the+  background proof captures the wiki front-end needs. Read when asked to "add this wiki part to+  Altium", "install my cloud library into Altium", or to prove an import worked. Trigger words —+  wiki part to altium, cloud library, adom-wiki library, import component altium, kicad_sym to+  altium, kicad_mod to altium, import_part, library export, prove the import.+---++# altium-wiki-import++Parent skill: [altium-bridge](../altium-bridge/SKILL.md).++## What ships today++`adom-wiki library` (Cloud Libraries — component carts) exports **KiCad and Fusion**. Altium is+**phase 3**:++```+$ adom-wiki library availability <ref>      -> {"kicad":5,"fusion":5,"altium":0}+                                               per item: "no Altium assets declared"+$ adom-wiki library export <ref> --format altium+  LIB_FORMAT_UNAVAILABLE: format "altium" is not exportable yet+  "KiCad and Fusion ship today; the Altium lane (verified vendor assets, clone-based merge) is phase 3."+```++Wiki component pages carry `.kicad_sym`, `.kicad_mod`, `.step`, `.glb`, `.lbr` — no Altium-native+assets, which is exactly what the exporter is telling you. **The bridge closes that gap today.**++## The pipeline (verified end to end, 2026-09-01)++Ray's `stm32f303cbt6` and a 5-part Cloud Library, into both Altium Designer and Altium Designer+Develop: **5/5 parts, 2.4–7.3 s each, zero dialogs, foreground never disturbed.**++```bash+# 1. get the parts.  ONE page:            /api/v1/pages/<slug>/files/<slug>.kicad_sym|.kicad_mod|.step+#    a whole cart:+adom-wiki library export <ref> --format kicad -o lib.zip     # merged .kicad_sym + .pretty/ + 3dmodels/++# 2. a Cloud Library ships ONE merged .kicad_sym — split it per part before converting, or+#    symbol_modes.py will fuse every part's pins into a single symbol.+#    Each part's (property "Footprint" "Lib:FP") names its .pretty/<FP>.kicad_mod.++# 3. convert (container side; both tools ship in the bridge repo's tools/)+python3 tools/kicad2altium.py <part>.kicad_mod fp.spec "<FootprintName>" "<desc>"+python3 tools/symbol_modes.py <part>.kicad_sym sym.spec "<SymbolName>"    "<desc>"++# 4. vendor identity — ONE parts-search call, never a loop (shared daily quota)+adom-parts-search search "<MPN>"        # -> Mouser / DigiKey / LCSC part numbers++# 5. stage on the box and import (agent lane: in-process, no cursor, no foreground)+send_files '{"filePaths":["fp.spec","sym.spec","part.step"]}'+altium_import_part '{"schLib":"…\\Lib.SchLib","pcbLib":"…\\Lib.PcbLib",+                     "footprintSpec":"…\\fp.spec","symbolSpec":"…\\sym.spec","step":"…\\part.step",+                     "params":{"Mouser Part #":"…","DigiKey Part #":"…","LCSC Part #":"…",+                               "MPN":"…","Manufacturer":"…","Package":"…","Value":"…"},+                     "comment":"…","description":"…"}'+```++`import_part` returns its step counts — **check them**. `{"add_models": true, "models": 1, "params": 7}`+is a complete import; `models: 0` means the symbol has NO footprint and would place on a schematic+with nothing attached. The verb now fails on a zero-model attach rather than reporting success.++## Gotchas paid for in real imports++* **The first part into a NEW library can silently skip models+params** if the bridge process is+  mid-reload. Verify with `altium_read_symbol` (params) and the step counts; repair with+  `altium_remove_symbol` + re-import.+* **`add_models` is not idempotent** — each call appends another implementation. Calling it twice+  leaves duplicate footprint models on one symbol. Repair = `remove_symbol` + re-import.+* **Fresh libraries carry factory strays** (`Component_1`, `PCBComponent_1`) — `altium_cleanup_libs`.+* **`read_symbol` does not report models.** `models: null` is a REPORTING GAP, not proof the+  footprint link is missing. Do not conclude from it.+* Wiki parts can carry real data faults — a live example: `93LC56BT-I` has **8 symbol pins against a+  6-pad SOT-23-6 footprint**. Report it to the page owner; do not silently "fix" someone else's page.++## Proving it to the front-end++The wiki needs evidence, and the user must not be disturbed:++```bash+altium_show_symbol    '{"libraryPath":"…SchLib","symbolName":"…"}'+altium_show_footprint '{"libraryPath":"…PcbLib","footprintName":"…"}'+altium_show_3d_chip   '{"libraryPath":"…PcbLib","footprintName":"…"}'+altium_show_library   '{"libraryPath":"…"}'      # the whole library, with componentCount+```++Each returns `shot.image` (base64 PNG) and `windowEtiquette: "background"`. If Altium is MINIMIZED+the bridge restores it into the background, captures, and hands the user's foreground straight back+— it never moves the window off-screen, because a user reaching for Altium must find it where they+left it. A capture under 400 px wide is refused as `proof_unavailable` rather than returned: a+title-bar sliver is not evidence.++There is no single "ganged" symbol+footprint+3D view in Altium's library editors, so three captures+are the proof set.

@@ -77,6 +77,44 @@ def h_readiness(args):     return out  ++# ---- licence-seat hints (John, 2026-09-01: "ai hints are way more valuable ... the AI is bad at+# reading skills") ------------------------------------------------------------------------------+#+# One On-Demand seat serves ALL Altium apps on the machine — Designer and Designer Develop draw+# from the SAME seat. Everything below exists because two hours were lost to a stranded seat that+# the licence page reported as free.++SEAT_RULE = ("One On-Demand seat serves EVERY Altium app on this machine — Altium Designer and "+             "Altium Designer Develop share it. Only one can be licensed at a time.")++SEAT_STRANDED_FIX = (+    "If a claim fails while the licence page shows Seats 0/1 (looks free, is not), the seat is "+    "STRANDED by an Altium that was KILLED instead of closed. Fix: altium_close on every other "+    "instance (polite WM_CLOSE releases the lease), then altium_license {action:'use_license'}. "+    "Waiting does not clear it, and Refresh is a link the UIA layer cannot invoke."+)++SEAT_SWAP_HOWTO = (+    "To move the seat between apps: altium_close the one holding it (answer any Unsaved Changes "+    "prompt deliberately — on a shared machine the document may belong to another AI thread), then "+    "LAUNCH the other app; it claims the free seat silently at startup. No clicking required."+)+++def _seat_hints(out: dict, licence_state, instance_count: int = 1) -> dict:+    """Attach the seat guidance to any reply where the licence is the thing about to bite."""+    unlicensed = str(licence_state or "").lower() in ("no license", "no licence", "viewer")+    if unlicensed:+        out["_licenceHint"] = f"{SEAT_RULE} {SEAT_STRANDED_FIX}"+    if instance_count > 1:+        out["_seatHint"] = (f"{SEAT_RULE} {SEAT_SWAP_HOWTO} "+                            "NOTE: Altium Designer Develop writes NO licence tail in its title when it "+                            "HOLDS the seat (only '- Viewer' when it does not), so a blank licenceState "+                            "on Develop does not mean unlicensed — try the verb.")+    return out++ def h_status(args):     r = h_readiness(args)     r["uptimeSec"] = int(time.time() - _boot_at)@@ -208,8 +246,24 @@ def h_close(args):         dl = dialogs.scan(main_pid_only=True)         if dl:             if args.get("force"):+                # A forced kill STRANDS the On-Demand licence seat: the lease is never released, and+                # the licence page then shows Seats 0/1 (free) while every claim fails with "License+                # maximum usage reached". Two hours were lost to this on 2026-09-01. Make the caller+                # say it out loud.+                if not args.get("acceptSeatLoss"):+                    return _seat_hints({"success": False, "errorCode": "would_strand_licence_seat",+                        "dialogs": dl,+                        "error": "force:true KILLS Altium, which strands the On-Demand licence seat — "+                                 "no other Altium will be able to claim it, and the licence page will "+                                 "report it as free while refusing every claim.",+                        "_hint": "Answer the dialog instead (it is usually an Unsaved Changes prompt that "+                                 "names the document — on a shared machine it may belong to another AI "+                                 "thread). If you truly must kill, repeat with acceptSeatLoss:true and "+                                 "expect to reclaim the seat afterwards."},+                        altium_detect.licence_state().get("state"), len(altium_detect.instances()))                 subprocess.run(["taskkill", "/F", "/IM", altium_detect.EXE_NAME], capture_output=True)                 return {"success": True, "forced": True, "dismissedDialogs": [d.get("title") for d in dl],+                        "_seatWarning": "The licence seat is now STRANDED. " + SEAT_STRANDED_FIX,                         "_hint": "force:true kills even when a dialog blocks the polite close (e.g. the "                                  "'script stopped on a breakpoint' Error that refuses WM_CLOSE)."}             return {"success": False, "errorCode": "close_blocked_by_dialog", "dialogs": dl,@@ -228,8 +282,11 @@ def _need_licensed():     if not lic.get("running"):         return {"success": False, "errorCode": "altium_not_running", "_hint": "altium_launch first."}     if lic.get("licensed") is False:-        return {"success": False, "errorCode": "not_licensed", "licenceState": lic.get("state"),-                "_hint": "Altium refuses scripts without a licence. altium_license '{}'."}+        n = len(altium_detect.instances())+        return _seat_hints({"success": False, "errorCode": "not_licensed", "licenceState": lic.get("state"),+                            "_hint": "Altium refuses scripts without a licence. altium_license "+                                     "{\"action\":\"use_license\"} claims a free seat."},+                           lic.get("state"), n)     dl = dialogs.scan(main_pid_only=True)     if dl:         _attach_dialog_shots(dl)@@ -1437,10 +1494,11 @@ def h_instances(args):         i["agentAlive"] = agent.is_alive()         i["agentWorkspace"] = str(agent.workspace_dir())     agent.use_instance(None)-    return {"success": True, "count": len(found), "instances": found,-            "_hint": ("Pass instance:<pid|key|word> to any verb to target one. "-                      "With several running, verbs without it fail with errorCode ambiguous_instance.")-            if len(found) > 1 else "One Altium running — `instance` is optional."}+    out = {"success": True, "count": len(found), "instances": found,+           "_hint": ("Pass instance:<pid|key|word> to any verb to target one. "+                     "With several running, verbs without it fail with errorCode ambiguous_instance.")+           if len(found) > 1 else "One Altium running — `instance` is optional."}+    return _seat_hints(out, None, len(found))