--- name: bridge-publish-template user-invocable: false description: "TEMPLATE — the canonical, battle-tested recipe for publishing a new version of ANY Adom Desktop bridge to wiki.adom.inc, plus every gotcha hit live. Copy into your own bridge's dev-skills/, replace the / placeholders, and follow it. NOT for general users. Read before cutting a release: which artifact goes where (pkg=skills, release=bridge zip, repo=manifest+source), version-lockstep (kept above the AD bundled seed), the `files` allowlist + `skills/**` glob trap, keeping the tarball lean (NO zip / NO src / NO heroes), keeping dev/publish skills SOURCE-ONLY (not SKILL.md), deploying skills to .claude AND .codex, scrubbing retired-wiki host URLs, user-first discovery triggers, sha matching, and verify steps. Trigger words: publish bridge, ship bridge, release bridge, pkg publish, repo push, adom-wiki release, bridge manifest, bridge version bump, no zip in tarball, dev skill source only, scrub old wiki url, codex skills, discovery triggers, adom-desktop bridge publish template." --- # bridge-publish-template — shipping a new `` bridge version > **Template — copy into your bridge's own `dev-skills/`, replace the ``/`` placeholders, follow the steps.** This is the step-by-step ship recipe for a cloud-owned Adom Desktop bridge living at `wiki.adom.inc/adom/adom-desktop--bridge`, plus the traps that cost real time. Companion docs in your repo: a `*-dev.md` dev skill (architecture / ownership), a terse `PUBLISHING.md`, and `CLAUDE.md` (ownership boundary). Placeholder legend — replace consistently throughout before you ship: | Placeholder | Meaning | Example (Puppeteer bridge) | |---|---|---| | `` | lowercase bridge id | `puppeteer` | | `` | display name | `Puppeteer` | | `_` | verb prefix | `browser_` | | `adom-desktop--bridge` | wiki slug | `adom-desktop-puppeteer-bridge` | | `adom-bridge--manifest.json` | streaming manifest filename | `adom-bridge-puppeteer-manifest.json` | | `adom-bridge--v.zip` | release zip filename | `adom-bridge-puppeteer-v1.1.1.zip` | | `` | the runtime source files | `server.js`, `chrome.js`, `bridge.json` | | `` | the language/runtime AD reconstructs | `node` + `node_modules` | ## What goes WHERE — three artifacts, three homes (memorize this) | Artifact | Home | Command | Carries | |---|---|---|---| | **bridge runtime `.zip`** | a **Release** asset | `adom-wiki release upload` | `src/` at zip-root (`` — the thing AD runs). | | **streaming manifest JSON** | the **git repo** | `adom-wiki repo push` | points at the release zip URL + its sha256/size | | **container skills tarball** | a **Package** | `adom-wiki pkg publish` | `SKILL.md` + `skills/*` (the Claude/Codex skills). NO runtime. | > The `.zip` is a RELEASE, never a git file: `*.zip` is gitignored and `repo push --files X.zip` > reports `ok` but silently skips it (the URL then 404s). Binaries → `release upload`. ## Auth (once per container) ```bash export ADOM_WIKI_TOKEN=$(cat /var/run/adom/api-key 2>/dev/null) # container default; or session.json's login session_token adom-wiki whoami # MUST show a real user (e.g. john@adom.inc). Strict-auth rejects the shared "Developer" token. ``` `ADOM_WIKI_TOKEN` is the user's **login `session_token`** — the container default lives at `/var/run/adom/api-key`; otherwise pull it from `~/.adom/session.json`. Every mutation needs a real `--changelog` / `-m` (≥10 chars, ≥2 words) or the server 400s. ## The recipe ### 1. Bump version IN LOCKSTEP, and keep it > the AD bundled seed ```bash printf '1.1.1' > src/BRIDGE_VERSION sed -i 's/"version": "1.1.0"/"version": "1.1.1"/' src/bridge.json # bridge runtime sed -i 's/"version": "1.1.0"/"version": "1.1.1"/' package.json # adompkg descriptor (the pkg) ``` `src/BRIDGE_VERSION` and `src/bridge.json` MUST match (AD uses `BRIDGE_VERSION` to detect a stale running process). Keep the number **above** the seed in `adom-desktop/plugins/` so cache-over-bundled wins. ### 2. Build the bridge zip (source-only, `src/` at zip ROOT — no top-level dir) `zip` may be absent → Python. Your `` deps (e.g. `node_modules`) are NEVER included (AD reconstructs them on spawn; the seed ships them; a fat zip would blow wiki limits): ```python import zipfile, os, hashlib root, out = "src", "adom-bridge--v1.1.1.zip" with zipfile.ZipFile(out, "w", zipfile.ZIP_DEFLATED) as z: for dp, dirs, files in os.walk(root): for skip in ("node_modules","screenshots","profiles"): # your runtime's heavy/generated dirs if skip in dirs: dirs.remove(skip) for f in files: z.write(os.path.join(dp,f), os.path.relpath(os.path.join(dp,f), root)) print("sha256:", hashlib.sha256(open(out,"rb").read()).hexdigest(), "size:", os.path.getsize(out)) # SANITY: assert your changed file(s) are inside before shipping. ``` > **Concrete pup example (so the commands aren't abstract):** the Puppeteer bridge skips > `node_modules`/`screenshots`/`profiles`, and its sanity check asserts `chrome.js` + the change are > inside the zip before upload. `node_modules` is excluded because AD `npm install`s it on spawn (an > 88 MB zip would exceed wiki limits). ### 3. Publish the zip as a Release (releases PRESERVE your sha) ```bash adom-wiki release create adom/adom-desktop--bridge 1.1.1 --title "..." --changelog "<≥2 words>" adom-wiki release upload adom/adom-desktop--bridge 1.1.1 adom-bridge--v1.1.1.zip --json # the response's assets[].sha256/size are what the manifest MUST carry. Then VERIFY the PUBLIC url: curl -sL https://wiki.adom.inc/download/adom/adom-desktop--bridge/1.1.1/adom-bridge--v1.1.1.zip | sha256sum ``` ### 4. Point the manifest at the release + push it (git repo) Edit `adom-bridge--manifest.json` → `version`, `url` (the release download URL), `sha256`, `size` (from step 3 — **must match the served asset or `bridge_install` rejects it**): ```json { "manifest_version": 1, "name": "", "version": "1.1.1", "url": "https://wiki.adom.inc/download/adom/adom-desktop--bridge/1.1.1/adom-bridge--v1.1.1.zip", "sha256": "", "size": , "verbPrefixes": ["_"], "healthEndpoint": "/status", "statusVerb": "_readiness", "updateManifestUrl": "https://wiki.adom.inc/api/v1/pages/adom-desktop--bridge/files/adom-bridge--manifest.json", "released_at": "" } ``` > Declare `updateManifestUrl` (the full URL of THIS manifest on your own page) in both the manifest and > `src/bridge.json` so `refresh_bridges` / the auto-poll reach YOUR page instead of the legacy > AD-owned convention. Then push: ```bash adom-wiki repo push adom/adom-desktop--bridge \ --files adom-bridge--manifest.json src/bridge.json src/BRIDGE_VERSION SKILL.md \ -m "v1.1.1: " ``` > `sha256`/`size` MUST match the served asset or `bridge_install` rejects it. Re-download to confirm: > `curl -sL | sha256sum`. ### 5. Publish the container skills as a pkg — keep it LEAN, and MIND THE TRAPS ```bash adom-wiki pkg pack # ALWAYS pack + inspect BEFORE publish tar tzf *.tgz # confirm: SKILL.md + skills/*/SKILL.md + install.sh, and NOTHING heavy adom-wiki pkg publish --org adom --version 1.1.1 adom-wiki pkg notes adom/adom-desktop--bridge@1.1.1 -m "Container skills: " ``` The pkg description lives in the root **`package.json`** `description` — keep it explicit that this is **container-side skills only; the bridge runtime is the Release zip + bundled in Adom Desktop.** ## Traps hit live (don't relearn these) - **`pkg pack` includes EVERYTHING by default** → a fat tarball (all the hero PNGs + `src/` runtime). Fix: the heroes are gitignored (`*.png`) since they're already page assets, AND `package.json` has a **`files` allowlist**. With both, the tarball drops to ~12 KB. (Pup's was 16 MB before the guards.) - **`files` directory entries need a GLOB.** Listing `"skills"` (bare dir) silently includes ZERO skill files. Use **`"skills/**"`** (and/or the explicit `"skills//SKILL.md"`). Always `tar tzf` to confirm your skills actually made it in — a missing skill = an empty Skills tab. - **`pkg pack` honors `.gitignore`, not a separate npmignore.** So you can't gitignore something you need in git (e.g. `src/`) to drop it from the pkg — use the `files` allowlist for that. - **A RELEASE shows up in `adom-wiki pkg info` as a row with `type:null`** (wiki UI conflation). The real pkg rows are `type:"app"`. Use `adom-wiki release list` for true releases; don't think your pkg shipped just because a version appears in `pkg info`. - **sha/size mismatch → `bridge_install` rejects the manifest.** Releases preserve the uploaded sha, so use the `release upload` response values verbatim and re-download to confirm. - **The Skills tab + `skill_count` + `adom-wiki skills install` come from the GIT REPO, not the pkg.** The wiki indexes **every `SKILL.md`** in the page repo (root = main skill; `/SKILL.md` = sub-skills) — `page.skills` is null; it's a repo scan. So a file named `SKILL.md` ANYWHERE in the repo becomes an indexed, tab-listed, `skills install`-able skill. (This is *separate* from `pkg install`, which installs the pkg tarball governed by the `files` allowlist.) Corollary → see "Keep dev/publish skills source-only". ## Verify (every ship) ```bash # manifest serves at the updateManifestUrl path: curl -s https://wiki.adom.inc/api/v1/pages/adom-desktop--bridge/files/adom-bridge--manifest.json | jq .sha256 # anon-fetch the PUBLIC release zip URL and confirm the sha matches the manifest (curl 200 is NOT enough): curl -sL https://wiki.adom.inc/download/adom/adom-desktop--bridge/1.1.1/adom-bridge--v1.1.1.zip | sha256sum # live install + new verbs on a real desktop (multi-desktop → --target; `adom-desktop targets` lists them): adom-desktop --target bridge_install '{"manifestUrl":".../files/adom-bridge--manifest.json","force":true}' adom-desktop --target _readiness '{}' # bridge_list shows the new version + skillPkg; bridge_check_updates reaches your page; sync_skills pulls the user skill: adom-desktop --target bridge_list '{}' # confirm version + skillPkg (adom/adom-desktop--bridge) adom-desktop --target bridge_check_updates '{}' # wikiHosted:true, latest = your new version adom-desktop --target sync_skills '{}' # installs the user skill pkg into the container # render the page in pup + READ the screenshot. Confirm version + Skills tab. ``` > Server-only change → AD reaps + respawns the bridge from the new cache on the next `_*` call. ## Keep dev/publish skills SOURCE-ONLY (not on the Skills tab, not installed) Everyday users should get ONLY the `` user skill — not the dev/publish skills. But the wiki indexes every `SKILL.md` in the repo (above), so a dev skill named `SKILL.md` would show on the Skills tab AND install via `skills install`. The fix: keep dev/publish skills as **source-only docs that are NOT named `SKILL.md`** — they live in `dev-skills/` as `-bridge-dev.md` / `-bridge-publish.md`. Then they are: - **not indexed** (`skill_count` stays 1), **not on the Skills tab**, **not `skills install`-able**; - still in git → available via `adom-wiki repo clone` (and the Files tab); - excluded from the pkg too (the `files` allowlist lists only `SKILL.md` + `skills/**`). `dev-skills/README.md` tells a developer how to load one as a live skill (copy it to `~/.claude/skills//SKILL.md`). **Verify after publish:** `skill_count` should be **1** — `curl -s https://wiki.adom.inc/api/pages/adom/adom-desktop--bridge | jq '.page.skill_count'`. ## Keep the pkg tarball LEAN — NO zip, NO src/, NO heroes The pkg tarball must be the `` user skill ONLY — never the bridge runtime zip, `src/`, or hero PNGs. Guards: the `package.json` `files` allowlist (`SKILL.md`, `skills/**`, `install.sh`, `uninstall.sh`, `README.md`, `package.json`) **plus** `.gitignore` (`*.zip`, `*.png`, `*.bundle`, `*.tgz`, the old `*-source.tar.gz`). **ALWAYS** `adom-wiki pkg pack` then `tar tzf *.tgz` and confirm there is **no `*.zip`, no `src/`, no `*.png`**. A lean tarball is ~10 KB; if it's megabytes, something heavy leaked in (it was 16 MB before the guards). `rm -f *.tgz` after inspecting. ## Skills install to BOTH .claude AND .codex `install.sh` deploys the user skill into **both `~/.claude/skills/` and `~/.codex/skills/`** (Codex only if `~/.codex` exists); `uninstall.sh` removes from both. Codex is a real second agent skills home now — don't ship an install.sh that only does `.claude`. ## Scrub retired-wiki URLs (the #1 fork/extract gotcha) **The only wiki host is `wiki.adom.inc`.** Any `wiki-*.adom.cloud` host is RETIRED — as are the `/static/apps/...` and `/wiki/apps/...` path formats. When you fork/extract a page, the inherited `README.md` and the `page.json` `readme` body carry OLD URLs (this bit pup live — a dead `static/apps` zip link). Before every publish: ```bash grep -rnI 'adom\.cloud\|/static/apps\|/wiki/apps' . --exclude-dir=node_modules ``` Fix every hit (README + the `page.json` `readme` body are the usual culprits), then VERIFY the **live** entity (not just local): ```bash curl -s https://wiki.adom.inc/api/pages/adom/adom-desktop--bridge | grep -c '\.adom\.cloud' # want 0 ``` Also `repo rm` any stale source-mirror artifacts left on the page (old `*-source.tar.gz` / `*.bundle`). (`https://adom.inc/fonts/...` is fine — that's the brand font CDN, not a wiki host.) ## Canonical wiki.adom.inc URL formats - **Page:** `https://wiki.adom.inc/adom/` - **File (served, anon):** `https://wiki.adom.inc/api/v1/pages//files/` - **Release download:** `https://wiki.adom.inc/download/adom///` - **Sibling pages:** `/adom/adom-desktop-bridges`, `/adom/adom-desktop-kicad-bridge`, `/adom/adom-desktop-fusion-bridge`, `/adom/adom-desktop` ## Discovery triggers — lead with everyday USER phrases Lead `discovery_triggers` with everyday phrases, not dev jargon — the single most important is the bare bridge name users actually say. The wiki **auto-generates** the discover snippet from `discovery_triggers` + `discovery_pitch` (there is no separate "upload a snippet" — those two fields ARE the snippet). Set them via `adom-wiki discover triggers --add ...` OR `page.json` `discovery_triggers`/`discovery_pitch` + push. **Verify:** `adom-wiki discover preview ""` should rank this page #1. > **Concrete pup example:** the most important trigger is the bare word **`pup`**, plus `open in pup`, > `open my app in pup`, `screenshot the page`, `record a browser window`. `adom-wiki discover preview > "open my app in pup"` must rank the Puppeteer page #1.