---
name: kicad-bridge-publish
description: PUBLISH skill — the exact recipe to ship a new version of the Adom Desktop KiCad bridge to wiki.adom.inc. NOT shipped to users (source-only). Covers version lockstep, the zip build, adom-wiki repo push + release create, the skills pkg, pushing to a target AD, and verify steps. Trigger words — publish kicad bridge, release kicad bridge, ship kicad bridge, bump kicad bridge, kicad bridge manifest, kicad bridge pkg.
---

# kicad-bridge-publish

How to cut and publish a KiCad-bridge release. **Use the `adom-wiki` CLI for ALL wiki interactions — never raw curl.** Two independent artifacts: the RUNTIME (zip + manifest, on the page `/files`) and the SKILLS PKG (`adom/adom-desktop-kicad-bridge`, container-side docs).

## 1. Version lockstep (bump ALL three together)

- `bridge.json` → `"version"`
- `BRIDGE_VERSION` (plain text)
- the manifest JSON → `"version"`

They must match. `bridge.json` also carries `updateManifestUrl` (durable auto-update), `docs` (your page), `homepage` (a **wiki.adom.inc** URL, NEVER github), `detect` (host-app paths incl. `%LocalAppData%\Programs\KiCad`), `verbPrefixes`, complete `verbs[]`, `statusVerb`.

## 2. Build the zip

Zip the repo dir CONTENTS (bridge.json at the zip root). Exclude: `__pycache__`, `*.pyc`, `.git`, `.github`, `node_modules`, `.DS_Store`, and the generated `adom-bridge-kicad-manifest.json`. Include `certs/cacert.pem`. Compute `sha256` + byte `size` for the manifest.

Manifest fields: `manifest_version:1, name:"kicad", version, url` (the `/blob/app/.../adom-bridge-kicad-v<ver>.zip`), `sha256, size, verbPrefixes:["kicad_"], healthEndpoint:"/status", released_at, hero, languages`.

## 3. Publish the runtime (CLI)

```bash
adom-wiki repo push adom/adom-desktop-kicad-bridge \
  --files adom-bridge-kicad-v<ver>.zip adom-bridge-kicad-manifest.json bridge.json \
  -m "v<ver>: <what changed>"
adom-wiki release create adom/adom-desktop-kicad-bridge <ver> \
  --title "KiCad bridge v<ver>" --changelog "..." \
  --binary-path adom-bridge-kicad-v<ver>.zip
```

`repo push` writes the files to the page `/files` (same place AD's bridge_cache fetches from). `release create` also registers a proper Release (SDK Artifact 1). For a field with no dedicated verb use `adom-wiki api -X PUT /api/v1/pages/... --body ...`, not curl.

## 4. Publish the skills pkg (container docs)

Stage a dir with `package.json` (name/version/`files[]`), a ROOT `SKILL.md`, and `skills/<name>/SKILL.md` per user skill. **DEV + PUBLISH skills go in `dev-skills/`/`publish-skills/` in the REPO only — they are auto-excluded from the pkg tarball; never ship them to users.** Then:

```bash
cd <staging> && adom-wiki pkg pack --out /tmp/v.tgz   # verify: tar lists every skills/<x>/SKILL.md, 0 binaries
adom-wiki pkg publish --org adom --skip-lint --yes     # moves dist-tag latest
```

The runtime SKILL.md (`adom-desktop-kicad`, ships in the zip) and the pkg's root SKILL.md are DIFFERENT docs — update both when a change affects users.

## 5. Push to a running desktop + verify

```bash
adom-desktop --target <name> refresh_bridges '{"name":"kicad"}'   # pulls new cache
adom-desktop --target <name> bridge_kill '{"name":"kicad"}'       # force fresh spawn (old instance keeps old code)
adom-desktop --target <name> bridge_check_updates '{}'            # current == latest?
adom-wiki repo show adom/adom-desktop-kicad-bridge adom-bridge-kicad-manifest.json  # served version matches?
```

Verify the served bridge.json (`repo show ... bridge.json`) has the fields you expect and the zip's sha matches. A fresh verb call after a kill returns `bridge_starting` — retry.

## 6. Standing rules

- Commit source to `main` in lockstep with each publish (drift = the bug that once dropped `updateManifestUrl`).
- After ANY wiki change, refresh the wiki pup window showing the page.
- The changelog must be real (≥2 words, no placeholders) — the server enforces it.