DEPRECATED: Bridge SDK (moved into Adom Bridge)

@@ -1,6 +1,6 @@ --- name: adom-desktop-bridge-sdk-description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files, manifest + runtime-asset placement) and which skills stay private if your bridge is closed-source; the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; the publish/dev/user SKILL set you must ship; and the auto-discover → install-check → use flow.+description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files [server deps in the zip; the pkg declares dependencies:{adom/adom-desktop}], manifest + runtime-asset placement); the pkg carries ONLY user skills while dev + publish skills live in your source repo (not the pkg); the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; and the auto-discover → install-check → use flow. ---  # Bridge SDK — build, publish, and surface a bridge for Adom Desktop@@ -28,10 +28,10 @@ A **bridge** is a small local program (Python, Node, Rust, anything) that AD spa | **Published as** | a versioned **Release** (`release create` + `release upload --platform any`) | an **`adom-wiki pkg`** (`pkg publish --org adom`) | | **Installed by** | `bridge_install {manifestUrl}` → AD streams, unzips, spawns | `pkg install adom/<slug>` / `sync_skills` → `~/.claude/skills` + `~/.codex/skills` | | **Contains** | server code + `bridge.json` at the zip **ROOT** + assets. **Node: SOURCE ONLY, no `node_modules`.** | ROOT `SKILL.md` + `skills/<name>/SKILL.md` + `package.json` + `install.sh`/`uninstall.sh`. **Docs only.** |-| **NEVER contains** | the skills pkg | **ANY binary, the Release zip, `src/`, `node_modules`, hero PNGs, or a `dependencies:` block** |-| **its `package.json`** | (node) the **RUNTIME deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **skillpack manifest**: `files[]`, `discovery_triggers`, install/uninstall scripts — **NO `dependencies`** |+| **NEVER contains** | the skills pkg | **ANY binary, the Release zip, `src/`, `node_modules`, hero PNGs, or the bridge SERVER's npm/runtime deps** |+| **its `package.json`** | (node) the **bridge SERVER's runtime deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **pkg manifest**: `files[]` (user skills), `discovery_triggers`, scripts, **AND `dependencies:{"adom/adom-desktop":"^1.9.x"}`** (the container needs the AD CLI + core skills to drive you) — but NOT the server's npm deps | -**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the deps AD installs on the *desktop*; the other is the skillpack manifest in the pkg tarball and lists *skill files*, never deps. Put runtime `dependencies` in the **pkg's** package.json and you bloat every container install — the pkg lands in a container that *never runs your bridge*. Put skill metadata in the **zip's** package.json and it does nothing.+**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the **bridge server's** runtime deps (puppeteer, sharp, ...) that AD installs on the *desktop* at spawn. The other is the **pkg manifest** in the skills tarball: it lists your user-skill `files[]` + `discovery_triggers` AND declares **`dependencies:{"adom/adom-desktop":"^1.9.x"}`** — `pkg install` resolves that npm-style, so installing your bridge's skill pkg also pulls the adom-desktop CLI + core skills the container needs to drive you. What the pkg manifest must NOT list is the **server's** npm deps (those are desktop-side, in the zip) — put them there and you bloat every container install, since the container never runs your server.  **Where each file physically lives (this is the map that ends the inconsistency):** - **`bridge.json`** → the **root of the Release zip** (AD reads it post-unzip). Carries `version` + `updateManifestUrl`.@@ -39,9 +39,10 @@ A **bridge** is a small local program (Python, Node, Rust, anything) that AD spa - **The manifest** (`adom-bridge-<name>-manifest.json`, this naming is the consistent one — keep it) → POSTed to your page **`/files`**. Its `url` points at the **Release download** (`https://wiki.adom.inc/download/adom/<slug>/<ver>/<file>.zip`), base-relative + extension-agnostic. `updateManifestUrl` (in the manifest AND in bridge.json) points back at this manifest. - **A big RUNTIME ASSET** (a headless-GL pack like Mesa, a browser download) → declare it in **`prewarm.assets`** so AD downloads + manages it, or bundle it in your seed. **NOT a loose `/files` blob** — kicad's `mesa-llvmpipe-x64.zip` on `/files` is the anti-pattern. -**Which skills go PUBLIC depends on whether your bridge is open source:**-- **USER skills ALWAYS ship** in your pkg (public) — the container can't drive your verbs without them.-- **DEV + PUBLISH skills:** ship them in your pkg (scoped `user-invocable:false`, see "The SKILL SET") **only if your bridge is OPEN SOURCE** / you're fine with your release-and-publish process being publicly readable. **If your bridge is CLOSED SOURCE, keep dev + publish skills in your PRIVATE repo and ship ONLY user skills to the wiki** — exactly what **adom-desktop core** does: its `RELEASE` / `WIKI_PUBLISH` / `SIGNING` / `AD_RELAUNCH` skills live only in the private GitHub source and are NEVER in the public pkg (verified: the published adom-desktop pkg carries 9 user/integration skills, zero dev/publish). Don't publish your release dance if your source isn't public.+**Which skills go where — the pkg is USER-only; DEV + PUBLISH skills live in your source REPO:**+- **The pkg ships ONLY your USER skill(s)** — how a general adom user drives your verbs. That IS the pkg's whole job: a container `pkg install`s it to USE your bridge. A big surface can be a core USER skill + USER sub-skills, but every one is a *user* skill.+- **DEV + PUBLISH skills live in your source REPO, NEVER in the pkg.** A developer who clones/checks out your source to EDIT the bridge gets them as repo files — that is their entire delivery mechanism. The normal user never needs them, so shipping them in the pkg is pure bloat. Do NOT list them in the pkg's `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them).+- **Open-source vs closed-source does NOT change this** — it only affects whether your repo's dev/publish files are publicly readable (public repo) or private (private repo). Either way they are in the repo, never the pkg. adom-desktop core does exactly this: user/integration skills in the pkg; `RELEASE`/`WIKI_PUBLISH`/`SIGNING`/`AD_RELAUNCH` live only in the source repo.  --- @@ -118,7 +119,7 @@ When a maintainer says *"audit your code, skills, README, and wiki page against  **Artifacts & deps** (the two-artifact split — the #1 inconsistency) *(→ Where every file lives)*: - [ ] Your Release `.zip` is a **Release asset** (`release upload`), NOT a loose `/files` blob — and old version zips are NOT piling up on `/files` (audit for stray `*-v*.zip`).-- [ ] Runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python); the **skillpack** `package.json` in your pkg has **NO `dependencies`** (it installs into a container that never runs you).+- [ ] The **server's** runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python). The **pkg's** `package.json` declares `dependencies:{"adom/adom-desktop":"^1.9.x"}` (so `pkg install` pulls the AD CLI + core skills) and does NOT list the server's npm deps. - [ ] A big runtime asset (Mesa, a browser) is a **`prewarm.asset`** or seed-bundled — NOT a loose `/files` blob. - [ ] Your **manifest** (`adom-bridge-<name>-manifest.json`) is on `/files`; its `url` points at the **Release download**, not at a `/files` blob. @@ -139,8 +140,9 @@ When a maintainer says *"audit your code, skills, README, and wiki page against - [ ] Triggers stay in YOUR niche — you don't poach a sibling's (login/forms → native-browser, not pup). `discovery_pitch` is an INSTRUCTION.  **Skills & docs** (what the container + humans read):-- [ ] You ship the **USER skill(s)** in the SKILLPACK layout: a real `skills/<name>/SKILL.md` with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*-- [ ] **DEV + PUBLISH skills:** in the pkg (scoped `user-invocable:false` + DEVELOPER-only description, NOT hidden as `dev-skills/*.md` — that convention is dead) **only if your bridge is OPEN SOURCE**; if CLOSED source, they stay in your PRIVATE repo and only user skills ship (the adom-desktop-core model). *(→ Where every file lives)*+- [ ] Your pkg ships **ONLY your USER skill(s)** — a real `skills/<name>/SKILL.md` (core user skill + user sub-skills) with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*+- [ ] **DEV + PUBLISH skills are in your source REPO, NOT the pkg** — not in `files[]`, not scoped in via `user-invocable:false`. A developer gets them by cloning the source; the normal user never needs them. Open-vs-closed source is irrelevant (it only sets repo visibility). *(→ Where every file lives)*+- [ ] Your pkg's `package.json` declares `dependencies:{"adom/adom-desktop":"^1.9.x"}` so `pkg install` pulls the AD CLI + core skills the container needs. *(→ Where every file lives)* - [ ] Your USER skill leads with the cold-start "read before you panic" section + the 8 conventions, and points the AI at `bridge_readiness`. *(→ USER-skill conventions)* - [ ] README + wiki page + skills all AGREE with the above (no stale github links, no wrong schema, triggers vetted). @@ -228,17 +230,19 @@ This is the code AD streams onto the user's machine. Two files on your page:  Your runtime runs on the user's DESKTOP; the AI driving it runs in a cloud/WSL2 CONTAINER. That container needs your **consumer SKILL.md** locally to know your verbs. Ship it as its own **`adom-wiki pkg`** (skills only, NO binaries): -**Layout = the wiki SKILLPACK convention** (reference: `adom/adom-wiki-skillpack`; supersedes the old "hide dev docs in `dev-skills/*.md`" guidance — pup migrated 2026-07-03):+**Layout** (reference: `adom/adom-wiki-skillpack`): -- **EVERY skill — user, dev, AND publish — is a real `skills/<name>/SKILL.md`.** Nothing is scoped by hiding files. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words.+- **The pkg carries ONLY your USER skill(s).** Each is a real `skills/<name>/SKILL.md`. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words. Large surface → a core user skill + user sub-skills, but **every skill in the pkg is a *user* skill.**+- **DEV + PUBLISH skills do NOT go in the pkg — they live in your source repo** (a developer gets them by cloning to edit the bridge). Do NOT list them in `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them and bloats every container install).+- **Declare `dependencies:{"adom/adom-desktop":"^1.9.x"}`** in `package.json` — `pkg install` resolves it npm-style, so installing your bridge's skill pkg also pulls the AD CLI + core skills the container needs to drive you. - **Each sub-skill's body opens with a `Parent skill:` line** (first line after the frontmatter): `Parent skill: **adom-desktop-<bridge>-bridge**`.-- **Dev/publish skills are scoped by AUDIENCE, not by filename:** frontmatter `user-invocable: false` + a description that opens DEVELOPER-only (e.g. "DEVELOPER skill for maintainers of this bridge — not for driving it"). Everyday users never get them offered; maintainers still install them.-- **List every skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing; the skillpack's own install.sh says so. (The old "use `skills/**`" advice is dead.)+- **List every user-skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing. (The old "use `skills/**`" advice is dead.)  ```bash-# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per skill (user + dev + publish),+# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per USER skill (dev/publish stay in the repo), # package.json {name:"adom-desktop-<bridge>-bridge", version, discovery_triggers,-#               files:[ every path, explicitly ], scripts:{install,uninstall}}.+#               dependencies:{"adom/adom-desktop":"^1.9.x"},+#               files:[ every USER-skill path, explicitly ], scripts:{install,uninstall}}. # TWO traps that still bite — verify each with `tar tzf` before publishing: #  1. ⚠ pkg pack/publish HONORS the stage dir's .gitignore — a gitignored skills/ ships #     a 3 MB tarball with ZERO skills. Set .gitignore aside across pack+publish, restore after.@@ -249,7 +253,7 @@ adom-wiki pkg pack                       # then: tar tzf <tgz> → every skills/ adom-wiki pkg publish --org adom         # publishes adom/adom-desktop-<bridge>-bridge ``` -**What `skill_count` on your page actually shows** (measured 2026-07-03): pup — a `type:app` page whose PKG ships 3 `SKILL.md`s — shows `skill_count: 3` (correct by design: it counts the skills your published PKG carries). But the reference `adom-wiki-skillpack` — `type:skill`, 15 `SKILL.md`s in its repo — shows `skill_count: 0`, so the metric is NOT "SKILL.md files in the repo" and looks inconsistent across page types. Treat your own pkg's count as the meaningful one; don't chase parity with skill-type pages (wiki-side question, flagged).+**`skill_count` on your page counts the USER skills your published PKG carries** — so it should be SMALL (1 for a single-skill bridge, a handful for a core + sub-skills). If it looks inflated, you probably shipped dev/publish skills that belong in the repo instead. The metric is NOT "SKILL.md files in the repo," so a `type:skill` page can read `skill_count: 0` while its repo holds many — don't chase parity across page types (wiki-side quirk).  A container gets it **without anyone asking**: - `bridge_install` returns `skillPkg` + `installSkill` (AD derives `adom/<slug>` from your `docs`) and the `_hint` tells the AI to run it.@@ -367,13 +371,13 @@ Your two own cold-start verbs (above) still apply: `<prefix>_readiness` (read-on  ## The SKILL SET you should ship (not one SKILL.md — a small library) -Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader:+Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader **and a different home** — the USER skill goes in the pkg; the DEV and PUBLISH skills stay in your source repo: -1. **A PUBLISH skill** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong.-2. **A DEV skill** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.-3. **USER skill(s)** (shipped in your pkg → the container): how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + sub-skills.)+1. **A PUBLISH skill — lives in your source REPO** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong.+2. **A DEV skill — lives in your source REPO** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.+3. **USER skill(s) — shipped in your pkg** → the container: how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + user sub-skills.) -Ship ALL of them — user + dev + publish — in your **pkg**, each as a real `skills/<name>/SKILL.md` (the SKILLPACK layout, Artifact 2). **Scoping is by AUDIENCE, not filename:** dev/publish skills carry `user-invocable: false` + a description that opens DEVELOPER-only, so everyday users are never offered them while your maintainer thread still installs the full set. (The old "name dev docs `dev-skills/*.md` so they don't ship" rule is DEAD — pup migrated to the skillpack layout 2026-07-03 and its `skill_count: 3` is by design.)+**Only the USER skill(s) go in your pkg** (Artifact 2), each a real `skills/<name>/SKILL.md`. **The DEV + PUBLISH skills stay in your source repo** — a developer gets them by cloning to edit the bridge; they are NOT in the pkg's `files[]`, and you do NOT "scope" them into the pkg with `user-invocable:false` (that still ships them and bloats every container install). Open-vs-closed source doesn't change this — it only sets whether your repo's dev/publish files are publicly readable.  **Start from the templates — don't write these from scratch.** `skills/bridge-templates/` in the AD repo has a fill-in-the-blanks file for each of the three skill kinds, generalized from pup's battle-tested set: **`bridge-dev-template.md`** (architecture + the rich-hints rule), **`bridge-publish-template.md`** (the whole release/pkg/discovery dance + every trap), **`bridge-user-skill-template.md`** (the consumer skill, already encoding all eight conventions below). Copy the one you need, swap `<bridge>`/`<prefix>` for your names, delete what doesn't apply. 

@@ -1,6 +1,6 @@ --- name: adom-desktop-bridge-sdk-description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files, manifest + runtime-asset placement) and which skills stay private if your bridge is closed-source; the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; the publish/dev/user SKILL set you must ship; and the auto-discover → install-check → use flow.+description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files [server deps in the zip; the pkg declares dependencies:{adom/adom-desktop}], manifest + runtime-asset placement); the pkg carries ONLY user skills while dev + publish skills live in your source repo (not the pkg); the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; and the auto-discover → install-check → use flow. ---  # Bridge SDK — build, publish, and surface a bridge for Adom Desktop@@ -28,10 +28,10 @@ A **bridge** is a small local program (Python, Node, Rust, anything) that AD spa | **Published as** | a versioned **Release** (`release create` + `release upload --platform any`) | an **`adom-wiki pkg`** (`pkg publish --org adom`) | | **Installed by** | `bridge_install {manifestUrl}` → AD streams, unzips, spawns | `pkg install adom/<slug>` / `sync_skills` → `~/.claude/skills` + `~/.codex/skills` | | **Contains** | server code + `bridge.json` at the zip **ROOT** + assets. **Node: SOURCE ONLY, no `node_modules`.** | ROOT `SKILL.md` + `skills/<name>/SKILL.md` + `package.json` + `install.sh`/`uninstall.sh`. **Docs only.** |-| **NEVER contains** | the skills pkg | **ANY binary, the Release zip, `src/`, `node_modules`, hero PNGs, or a `dependencies:` block** |-| **its `package.json`** | (node) the **RUNTIME deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **skillpack manifest**: `files[]`, `discovery_triggers`, install/uninstall scripts — **NO `dependencies`** |+| **NEVER contains** | the skills pkg | **ANY binary, the Release zip, `src/`, `node_modules`, hero PNGs, or the bridge SERVER's npm/runtime deps** |+| **its `package.json`** | (node) the **bridge SERVER's runtime deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **pkg manifest**: `files[]` (user skills), `discovery_triggers`, scripts, **AND `dependencies:{"adom/adom-desktop":"^1.9.x"}`** (the container needs the AD CLI + core skills to drive you) — but NOT the server's npm deps | -**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the deps AD installs on the *desktop*; the other is the skillpack manifest in the pkg tarball and lists *skill files*, never deps. Put runtime `dependencies` in the **pkg's** package.json and you bloat every container install — the pkg lands in a container that *never runs your bridge*. Put skill metadata in the **zip's** package.json and it does nothing.+**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the **bridge server's** runtime deps (puppeteer, sharp, ...) that AD installs on the *desktop* at spawn. The other is the **pkg manifest** in the skills tarball: it lists your user-skill `files[]` + `discovery_triggers` AND declares **`dependencies:{"adom/adom-desktop":"^1.9.x"}`** — `pkg install` resolves that npm-style, so installing your bridge's skill pkg also pulls the adom-desktop CLI + core skills the container needs to drive you. What the pkg manifest must NOT list is the **server's** npm deps (those are desktop-side, in the zip) — put them there and you bloat every container install, since the container never runs your server.  **Where each file physically lives (this is the map that ends the inconsistency):** - **`bridge.json`** → the **root of the Release zip** (AD reads it post-unzip). Carries `version` + `updateManifestUrl`.@@ -39,9 +39,10 @@ A **bridge** is a small local program (Python, Node, Rust, anything) that AD spa - **The manifest** (`adom-bridge-<name>-manifest.json`, this naming is the consistent one — keep it) → POSTed to your page **`/files`**. Its `url` points at the **Release download** (`https://wiki.adom.inc/download/adom/<slug>/<ver>/<file>.zip`), base-relative + extension-agnostic. `updateManifestUrl` (in the manifest AND in bridge.json) points back at this manifest. - **A big RUNTIME ASSET** (a headless-GL pack like Mesa, a browser download) → declare it in **`prewarm.assets`** so AD downloads + manages it, or bundle it in your seed. **NOT a loose `/files` blob** — kicad's `mesa-llvmpipe-x64.zip` on `/files` is the anti-pattern. -**Which skills go PUBLIC depends on whether your bridge is open source:**-- **USER skills ALWAYS ship** in your pkg (public) — the container can't drive your verbs without them.-- **DEV + PUBLISH skills:** ship them in your pkg (scoped `user-invocable:false`, see "The SKILL SET") **only if your bridge is OPEN SOURCE** / you're fine with your release-and-publish process being publicly readable. **If your bridge is CLOSED SOURCE, keep dev + publish skills in your PRIVATE repo and ship ONLY user skills to the wiki** — exactly what **adom-desktop core** does: its `RELEASE` / `WIKI_PUBLISH` / `SIGNING` / `AD_RELAUNCH` skills live only in the private GitHub source and are NEVER in the public pkg (verified: the published adom-desktop pkg carries 9 user/integration skills, zero dev/publish). Don't publish your release dance if your source isn't public.+**Which skills go where — the pkg is USER-only; DEV + PUBLISH skills live in your source REPO:**+- **The pkg ships ONLY your USER skill(s)** — how a general adom user drives your verbs. That IS the pkg's whole job: a container `pkg install`s it to USE your bridge. A big surface can be a core USER skill + USER sub-skills, but every one is a *user* skill.+- **DEV + PUBLISH skills live in your source REPO, NEVER in the pkg.** A developer who clones/checks out your source to EDIT the bridge gets them as repo files — that is their entire delivery mechanism. The normal user never needs them, so shipping them in the pkg is pure bloat. Do NOT list them in the pkg's `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them).+- **Open-source vs closed-source does NOT change this** — it only affects whether your repo's dev/publish files are publicly readable (public repo) or private (private repo). Either way they are in the repo, never the pkg. adom-desktop core does exactly this: user/integration skills in the pkg; `RELEASE`/`WIKI_PUBLISH`/`SIGNING`/`AD_RELAUNCH` live only in the source repo.  --- @@ -118,7 +119,7 @@ When a maintainer says *"audit your code, skills, README, and wiki page against  **Artifacts & deps** (the two-artifact split — the #1 inconsistency) *(→ Where every file lives)*: - [ ] Your Release `.zip` is a **Release asset** (`release upload`), NOT a loose `/files` blob — and old version zips are NOT piling up on `/files` (audit for stray `*-v*.zip`).-- [ ] Runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python); the **skillpack** `package.json` in your pkg has **NO `dependencies`** (it installs into a container that never runs you).+- [ ] The **server's** runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python). The **pkg's** `package.json` declares `dependencies:{"adom/adom-desktop":"^1.9.x"}` (so `pkg install` pulls the AD CLI + core skills) and does NOT list the server's npm deps. - [ ] A big runtime asset (Mesa, a browser) is a **`prewarm.asset`** or seed-bundled — NOT a loose `/files` blob. - [ ] Your **manifest** (`adom-bridge-<name>-manifest.json`) is on `/files`; its `url` points at the **Release download**, not at a `/files` blob. @@ -139,8 +140,9 @@ When a maintainer says *"audit your code, skills, README, and wiki page against - [ ] Triggers stay in YOUR niche — you don't poach a sibling's (login/forms → native-browser, not pup). `discovery_pitch` is an INSTRUCTION.  **Skills & docs** (what the container + humans read):-- [ ] You ship the **USER skill(s)** in the SKILLPACK layout: a real `skills/<name>/SKILL.md` with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*-- [ ] **DEV + PUBLISH skills:** in the pkg (scoped `user-invocable:false` + DEVELOPER-only description, NOT hidden as `dev-skills/*.md` — that convention is dead) **only if your bridge is OPEN SOURCE**; if CLOSED source, they stay in your PRIVATE repo and only user skills ship (the adom-desktop-core model). *(→ Where every file lives)*+- [ ] Your pkg ships **ONLY your USER skill(s)** — a real `skills/<name>/SKILL.md` (core user skill + user sub-skills) with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*+- [ ] **DEV + PUBLISH skills are in your source REPO, NOT the pkg** — not in `files[]`, not scoped in via `user-invocable:false`. A developer gets them by cloning the source; the normal user never needs them. Open-vs-closed source is irrelevant (it only sets repo visibility). *(→ Where every file lives)*+- [ ] Your pkg's `package.json` declares `dependencies:{"adom/adom-desktop":"^1.9.x"}` so `pkg install` pulls the AD CLI + core skills the container needs. *(→ Where every file lives)* - [ ] Your USER skill leads with the cold-start "read before you panic" section + the 8 conventions, and points the AI at `bridge_readiness`. *(→ USER-skill conventions)* - [ ] README + wiki page + skills all AGREE with the above (no stale github links, no wrong schema, triggers vetted). @@ -228,17 +230,19 @@ This is the code AD streams onto the user's machine. Two files on your page:  Your runtime runs on the user's DESKTOP; the AI driving it runs in a cloud/WSL2 CONTAINER. That container needs your **consumer SKILL.md** locally to know your verbs. Ship it as its own **`adom-wiki pkg`** (skills only, NO binaries): -**Layout = the wiki SKILLPACK convention** (reference: `adom/adom-wiki-skillpack`; supersedes the old "hide dev docs in `dev-skills/*.md`" guidance — pup migrated 2026-07-03):+**Layout** (reference: `adom/adom-wiki-skillpack`): -- **EVERY skill — user, dev, AND publish — is a real `skills/<name>/SKILL.md`.** Nothing is scoped by hiding files. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words.+- **The pkg carries ONLY your USER skill(s).** Each is a real `skills/<name>/SKILL.md`. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words. Large surface → a core user skill + user sub-skills, but **every skill in the pkg is a *user* skill.**+- **DEV + PUBLISH skills do NOT go in the pkg — they live in your source repo** (a developer gets them by cloning to edit the bridge). Do NOT list them in `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them and bloats every container install).+- **Declare `dependencies:{"adom/adom-desktop":"^1.9.x"}`** in `package.json` — `pkg install` resolves it npm-style, so installing your bridge's skill pkg also pulls the AD CLI + core skills the container needs to drive you. - **Each sub-skill's body opens with a `Parent skill:` line** (first line after the frontmatter): `Parent skill: **adom-desktop-<bridge>-bridge**`.-- **Dev/publish skills are scoped by AUDIENCE, not by filename:** frontmatter `user-invocable: false` + a description that opens DEVELOPER-only (e.g. "DEVELOPER skill for maintainers of this bridge — not for driving it"). Everyday users never get them offered; maintainers still install them.-- **List every skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing; the skillpack's own install.sh says so. (The old "use `skills/**`" advice is dead.)+- **List every user-skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing. (The old "use `skills/**`" advice is dead.)  ```bash-# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per skill (user + dev + publish),+# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per USER skill (dev/publish stay in the repo), # package.json {name:"adom-desktop-<bridge>-bridge", version, discovery_triggers,-#               files:[ every path, explicitly ], scripts:{install,uninstall}}.+#               dependencies:{"adom/adom-desktop":"^1.9.x"},+#               files:[ every USER-skill path, explicitly ], scripts:{install,uninstall}}. # TWO traps that still bite — verify each with `tar tzf` before publishing: #  1. ⚠ pkg pack/publish HONORS the stage dir's .gitignore — a gitignored skills/ ships #     a 3 MB tarball with ZERO skills. Set .gitignore aside across pack+publish, restore after.@@ -249,7 +253,7 @@ adom-wiki pkg pack                       # then: tar tzf <tgz> → every skills/ adom-wiki pkg publish --org adom         # publishes adom/adom-desktop-<bridge>-bridge ``` -**What `skill_count` on your page actually shows** (measured 2026-07-03): pup — a `type:app` page whose PKG ships 3 `SKILL.md`s — shows `skill_count: 3` (correct by design: it counts the skills your published PKG carries). But the reference `adom-wiki-skillpack` — `type:skill`, 15 `SKILL.md`s in its repo — shows `skill_count: 0`, so the metric is NOT "SKILL.md files in the repo" and looks inconsistent across page types. Treat your own pkg's count as the meaningful one; don't chase parity with skill-type pages (wiki-side question, flagged).+**`skill_count` on your page counts the USER skills your published PKG carries** — so it should be SMALL (1 for a single-skill bridge, a handful for a core + sub-skills). If it looks inflated, you probably shipped dev/publish skills that belong in the repo instead. The metric is NOT "SKILL.md files in the repo," so a `type:skill` page can read `skill_count: 0` while its repo holds many — don't chase parity across page types (wiki-side quirk).  A container gets it **without anyone asking**: - `bridge_install` returns `skillPkg` + `installSkill` (AD derives `adom/<slug>` from your `docs`) and the `_hint` tells the AI to run it.@@ -367,13 +371,13 @@ Your two own cold-start verbs (above) still apply: `<prefix>_readiness` (read-on  ## The SKILL SET you should ship (not one SKILL.md — a small library) -Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader:+Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader **and a different home** — the USER skill goes in the pkg; the DEV and PUBLISH skills stay in your source repo: -1. **A PUBLISH skill** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong.-2. **A DEV skill** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.-3. **USER skill(s)** (shipped in your pkg → the container): how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + sub-skills.)+1. **A PUBLISH skill — lives in your source REPO** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong.+2. **A DEV skill — lives in your source REPO** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.+3. **USER skill(s) — shipped in your pkg** → the container: how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + user sub-skills.) -Ship ALL of them — user + dev + publish — in your **pkg**, each as a real `skills/<name>/SKILL.md` (the SKILLPACK layout, Artifact 2). **Scoping is by AUDIENCE, not filename:** dev/publish skills carry `user-invocable: false` + a description that opens DEVELOPER-only, so everyday users are never offered them while your maintainer thread still installs the full set. (The old "name dev docs `dev-skills/*.md` so they don't ship" rule is DEAD — pup migrated to the skillpack layout 2026-07-03 and its `skill_count: 3` is by design.)+**Only the USER skill(s) go in your pkg** (Artifact 2), each a real `skills/<name>/SKILL.md`. **The DEV + PUBLISH skills stay in your source repo** — a developer gets them by cloning to edit the bridge; they are NOT in the pkg's `files[]`, and you do NOT "scope" them into the pkg with `user-invocable:false` (that still ships them and bloats every container install). Open-vs-closed source doesn't change this — it only sets whether your repo's dev/publish files are publicly readable.  **Start from the templates — don't write these from scratch.** `skills/bridge-templates/` in the AD repo has a fill-in-the-blanks file for each of the three skill kinds, generalized from pup's battle-tested set: **`bridge-dev-template.md`** (architecture + the rich-hints rule), **`bridge-publish-template.md`** (the whole release/pkg/discovery dance + every trap), **`bridge-user-skill-template.md`** (the consumer skill, already encoding all eight conventions below). Copy the one you need, swap `<bridge>`/`<prefix>` for your names, delete what doesn't apply. 

@@ -1,6 +1,6 @@ --- name: adom-desktop-bridge-sdk-description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files, manifest + runtime-asset placement) and which skills stay private if your bridge is closed-source; the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; the publish/dev/user SKILL set you must ship; and the auto-discover → install-check → use flow.+description: Author, PUBLISH, and make-discoverable an adom-desktop bridge — a small local server that adds a namespace of verbs (kicad_, fusion_, browser_, your_prefix_) to adom-desktop. Use when building, publishing, updating, prewarming, or debugging a bridge, or deciding what skills to ship. Covers the AD-core-vs-author boundary; the #1 rule (rich hints in EVERY verb's OUTPUT, because the AI reads CLI output, never your on-disk skill); bridge.json; where every file lives (the Release-zip-vs-skills-pkg split, the TWO package.json files [server deps in the zip; the pkg declares dependencies:{adom/adom-desktop}], manifest + runtime-asset placement); the pkg carries ONLY user skills while dev + publish skills live in your source repo (not the pkg); the THREE things you publish (runtime Release zip + manifest, container skills pkg, wiki discovery_triggers); prewarm; and the auto-discover → install-check → use flow. ---  # Bridge SDK — build, publish, and surface a bridge for Adom Desktop@@ -28,10 +28,10 @@ A **bridge** is a small local program (Python, Node, Rust, anything) that AD spa | **Published as** | a versioned **Release** (`release create` + `release upload --platform any`) | an **`adom-wiki pkg`** (`pkg publish --org adom`) | | **Installed by** | `bridge_install {manifestUrl}` → AD streams, unzips, spawns | `pkg install adom/<slug>` / `sync_skills` → `~/.claude/skills` + `~/.codex/skills` | | **Contains** | server code + `bridge.json` at the zip **ROOT** + assets. **Node: SOURCE ONLY, no `node_modules`.** | ROOT `SKILL.md` + `skills/<name>/SKILL.md` + `package.json` + `install.sh`/`uninstall.sh`. **Docs only.** |-| **NEVER contains** | the skills pkg | **ANY binary, the Release zip, `src/`, `node_modules`, hero PNGs, or a `dependencies:` block** |-| **its `package.json`** | (node) the **RUNTIME deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **skillpack manifest**: `files[]`, `discovery_triggers`, install/uninstall scripts — **NO `dependencies`** |+| **NEVER contains** | the skills pkg | **ANY binary, the Release zip, `src/`, `node_modules`, hero PNGs, or the bridge SERVER's npm/runtime deps** |+| **its `package.json`** | (node) the **bridge SERVER's runtime deps** AD installs at spawn: `dependencies:{ puppeteer, … }` | the **pkg manifest**: `files[]` (user skills), `discovery_triggers`, scripts, **AND `dependencies:{"adom/adom-desktop":"^1.9.x"}`** (the container needs the AD CLI + core skills to drive you) — but NOT the server's npm deps | -**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the deps AD installs on the *desktop*; the other is the skillpack manifest in the pkg tarball and lists *skill files*, never deps. Put runtime `dependencies` in the **pkg's** package.json and you bloat every container install — the pkg lands in a container that *never runs your bridge*. Put skill metadata in the **zip's** package.json and it does nothing.+**Yes, a node bridge has TWO `package.json` files and they are NOT interchangeable.** One rides inside the Release zip and lists the **bridge server's** runtime deps (puppeteer, sharp, ...) that AD installs on the *desktop* at spawn. The other is the **pkg manifest** in the skills tarball: it lists your user-skill `files[]` + `discovery_triggers` AND declares **`dependencies:{"adom/adom-desktop":"^1.9.x"}`** — `pkg install` resolves that npm-style, so installing your bridge's skill pkg also pulls the adom-desktop CLI + core skills the container needs to drive you. What the pkg manifest must NOT list is the **server's** npm deps (those are desktop-side, in the zip) — put them there and you bloat every container install, since the container never runs your server.  **Where each file physically lives (this is the map that ends the inconsistency):** - **`bridge.json`** → the **root of the Release zip** (AD reads it post-unzip). Carries `version` + `updateManifestUrl`.@@ -39,9 +39,10 @@ A **bridge** is a small local program (Python, Node, Rust, anything) that AD spa - **The manifest** (`adom-bridge-<name>-manifest.json`, this naming is the consistent one — keep it) → POSTed to your page **`/files`**. Its `url` points at the **Release download** (`https://wiki.adom.inc/download/adom/<slug>/<ver>/<file>.zip`), base-relative + extension-agnostic. `updateManifestUrl` (in the manifest AND in bridge.json) points back at this manifest. - **A big RUNTIME ASSET** (a headless-GL pack like Mesa, a browser download) → declare it in **`prewarm.assets`** so AD downloads + manages it, or bundle it in your seed. **NOT a loose `/files` blob** — kicad's `mesa-llvmpipe-x64.zip` on `/files` is the anti-pattern. -**Which skills go PUBLIC depends on whether your bridge is open source:**-- **USER skills ALWAYS ship** in your pkg (public) — the container can't drive your verbs without them.-- **DEV + PUBLISH skills:** ship them in your pkg (scoped `user-invocable:false`, see "The SKILL SET") **only if your bridge is OPEN SOURCE** / you're fine with your release-and-publish process being publicly readable. **If your bridge is CLOSED SOURCE, keep dev + publish skills in your PRIVATE repo and ship ONLY user skills to the wiki** — exactly what **adom-desktop core** does: its `RELEASE` / `WIKI_PUBLISH` / `SIGNING` / `AD_RELAUNCH` skills live only in the private GitHub source and are NEVER in the public pkg (verified: the published adom-desktop pkg carries 9 user/integration skills, zero dev/publish). Don't publish your release dance if your source isn't public.+**Which skills go where — the pkg is USER-only; DEV + PUBLISH skills live in your source REPO:**+- **The pkg ships ONLY your USER skill(s)** — how a general adom user drives your verbs. That IS the pkg's whole job: a container `pkg install`s it to USE your bridge. A big surface can be a core USER skill + USER sub-skills, but every one is a *user* skill.+- **DEV + PUBLISH skills live in your source REPO, NEVER in the pkg.** A developer who clones/checks out your source to EDIT the bridge gets them as repo files — that is their entire delivery mechanism. The normal user never needs them, so shipping them in the pkg is pure bloat. Do NOT list them in the pkg's `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them).+- **Open-source vs closed-source does NOT change this** — it only affects whether your repo's dev/publish files are publicly readable (public repo) or private (private repo). Either way they are in the repo, never the pkg. adom-desktop core does exactly this: user/integration skills in the pkg; `RELEASE`/`WIKI_PUBLISH`/`SIGNING`/`AD_RELAUNCH` live only in the source repo.  --- @@ -118,7 +119,7 @@ When a maintainer says *"audit your code, skills, README, and wiki page against  **Artifacts & deps** (the two-artifact split — the #1 inconsistency) *(→ Where every file lives)*: - [ ] Your Release `.zip` is a **Release asset** (`release upload`), NOT a loose `/files` blob — and old version zips are NOT piling up on `/files` (audit for stray `*-v*.zip`).-- [ ] Runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python); the **skillpack** `package.json` in your pkg has **NO `dependencies`** (it installs into a container that never runs you).+- [ ] The **server's** runtime deps live in the **ZIP's** `package.json` (node) / `requirements.txt` (python). The **pkg's** `package.json` declares `dependencies:{"adom/adom-desktop":"^1.9.x"}` (so `pkg install` pulls the AD CLI + core skills) and does NOT list the server's npm deps. - [ ] A big runtime asset (Mesa, a browser) is a **`prewarm.asset`** or seed-bundled — NOT a loose `/files` blob. - [ ] Your **manifest** (`adom-bridge-<name>-manifest.json`) is on `/files`; its `url` points at the **Release download**, not at a `/files` blob. @@ -139,8 +140,9 @@ When a maintainer says *"audit your code, skills, README, and wiki page against - [ ] Triggers stay in YOUR niche — you don't poach a sibling's (login/forms → native-browser, not pup). `discovery_pitch` is an INSTRUCTION.  **Skills & docs** (what the container + humans read):-- [ ] You ship the **USER skill(s)** in the SKILLPACK layout: a real `skills/<name>/SKILL.md` with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*-- [ ] **DEV + PUBLISH skills:** in the pkg (scoped `user-invocable:false` + DEVELOPER-only description, NOT hidden as `dev-skills/*.md` — that convention is dead) **only if your bridge is OPEN SOURCE**; if CLOSED source, they stay in your PRIVATE repo and only user skills ship (the adom-desktop-core model). *(→ Where every file lives)*+- [ ] Your pkg ships **ONLY your USER skill(s)** — a real `skills/<name>/SKILL.md` (core user skill + user sub-skills) with a `Parent skill:` first body line; every path listed EXPLICITLY (no globs) in `files[]` + install.sh/uninstall.sh. *(→ Artifact 2 + The SKILL SET)*+- [ ] **DEV + PUBLISH skills are in your source REPO, NOT the pkg** — not in `files[]`, not scoped in via `user-invocable:false`. A developer gets them by cloning the source; the normal user never needs them. Open-vs-closed source is irrelevant (it only sets repo visibility). *(→ Where every file lives)*+- [ ] Your pkg's `package.json` declares `dependencies:{"adom/adom-desktop":"^1.9.x"}` so `pkg install` pulls the AD CLI + core skills the container needs. *(→ Where every file lives)* - [ ] Your USER skill leads with the cold-start "read before you panic" section + the 8 conventions, and points the AI at `bridge_readiness`. *(→ USER-skill conventions)* - [ ] README + wiki page + skills all AGREE with the above (no stale github links, no wrong schema, triggers vetted). @@ -228,17 +230,19 @@ This is the code AD streams onto the user's machine. Two files on your page:  Your runtime runs on the user's DESKTOP; the AI driving it runs in a cloud/WSL2 CONTAINER. That container needs your **consumer SKILL.md** locally to know your verbs. Ship it as its own **`adom-wiki pkg`** (skills only, NO binaries): -**Layout = the wiki SKILLPACK convention** (reference: `adom/adom-wiki-skillpack`; supersedes the old "hide dev docs in `dev-skills/*.md`" guidance — pup migrated 2026-07-03):+**Layout** (reference: `adom/adom-wiki-skillpack`): -- **EVERY skill — user, dev, AND publish — is a real `skills/<name>/SKILL.md`.** Nothing is scoped by hiding files. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words.+- **The pkg carries ONLY your USER skill(s).** Each is a real `skills/<name>/SKILL.md`. A ROOT `SKILL.md` (required by the registry) is the pack entry point: `user-invocable: true`, a `description` full of trigger words. Large surface → a core user skill + user sub-skills, but **every skill in the pkg is a *user* skill.**+- **DEV + PUBLISH skills do NOT go in the pkg — they live in your source repo** (a developer gets them by cloning to edit the bridge). Do NOT list them in `files[]`, and do NOT "scope" them in with `user-invocable:false` (that still ships them and bloats every container install).+- **Declare `dependencies:{"adom/adom-desktop":"^1.9.x"}`** in `package.json` — `pkg install` resolves it npm-style, so installing your bridge's skill pkg also pulls the AD CLI + core skills the container needs to drive you. - **Each sub-skill's body opens with a `Parent skill:` line** (first line after the frontmatter): `Parent skill: **adom-desktop-<bridge>-bridge**`.-- **Dev/publish skills are scoped by AUDIENCE, not by filename:** frontmatter `user-invocable: false` + a description that opens DEVELOPER-only (e.g. "DEVELOPER skill for maintainers of this bridge — not for driving it"). Everyday users never get them offered; maintainers still install them.-- **List every skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing; the skillpack's own install.sh says so. (The old "use `skills/**`" advice is dead.)+- **List every user-skill path EXPLICITLY — no globs — in `package.json` `files[]` AND `install.sh`/`uninstall.sh`** (one `install_skill <dest> <src>` line each, kept in sync). The publish linter REQUIRES explicit listing. (The old "use `skills/**`" advice is dead.)  ```bash-# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per skill (user + dev + publish),+# Stage dir: ROOT SKILL.md + skills/<name>/SKILL.md per USER skill (dev/publish stay in the repo), # package.json {name:"adom-desktop-<bridge>-bridge", version, discovery_triggers,-#               files:[ every path, explicitly ], scripts:{install,uninstall}}.+#               dependencies:{"adom/adom-desktop":"^1.9.x"},+#               files:[ every USER-skill path, explicitly ], scripts:{install,uninstall}}. # TWO traps that still bite — verify each with `tar tzf` before publishing: #  1. ⚠ pkg pack/publish HONORS the stage dir's .gitignore — a gitignored skills/ ships #     a 3 MB tarball with ZERO skills. Set .gitignore aside across pack+publish, restore after.@@ -249,7 +253,7 @@ adom-wiki pkg pack                       # then: tar tzf <tgz> → every skills/ adom-wiki pkg publish --org adom         # publishes adom/adom-desktop-<bridge>-bridge ``` -**What `skill_count` on your page actually shows** (measured 2026-07-03): pup — a `type:app` page whose PKG ships 3 `SKILL.md`s — shows `skill_count: 3` (correct by design: it counts the skills your published PKG carries). But the reference `adom-wiki-skillpack` — `type:skill`, 15 `SKILL.md`s in its repo — shows `skill_count: 0`, so the metric is NOT "SKILL.md files in the repo" and looks inconsistent across page types. Treat your own pkg's count as the meaningful one; don't chase parity with skill-type pages (wiki-side question, flagged).+**`skill_count` on your page counts the USER skills your published PKG carries** — so it should be SMALL (1 for a single-skill bridge, a handful for a core + sub-skills). If it looks inflated, you probably shipped dev/publish skills that belong in the repo instead. The metric is NOT "SKILL.md files in the repo," so a `type:skill` page can read `skill_count: 0` while its repo holds many — don't chase parity across page types (wiki-side quirk).  A container gets it **without anyone asking**: - `bridge_install` returns `skillPkg` + `installSkill` (AD derives `adom/<slug>` from your `docs`) and the `_hint` tells the AI to run it.@@ -367,13 +371,13 @@ Your two own cold-start verbs (above) still apply: `<prefix>_readiness` (read-on  ## The SKILL SET you should ship (not one SKILL.md — a small library) -Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader:+Don't cram everything into one file. Ship **three kinds** of skill, each with a different reader **and a different home** — the USER skill goes in the pkg; the DEV and PUBLISH skills stay in your source repo: -1. **A PUBLISH skill** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong.-2. **A DEV skill** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.-3. **USER skill(s)** (shipped in your pkg → the container): how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + sub-skills.)+1. **A PUBLISH skill — lives in your source REPO** (for the bridge's OWN cloud/dev thread): how to cut the Release zip, POST the manifest, bump versions, publish the skills pkg (with the `.gitignore` trap), set `discovery_triggers`, and re-seed AD's bundled copy. This keeps *your* future self from getting the publish dance wrong.+2. **A DEV skill — lives in your source REPO** (for whoever edits the bridge): architecture, the verb contract, how to test locally, the boundary with AD — and, front and center, **the rich-hints-in-output rule**: *the AI never reads this file; it reads your verb OUTPUT, so every verb must return `_hint`/`_next`/`related`/`pitfalls`.* Make that the loudest thing in the dev skill.+3. **USER skill(s) — shipped in your pkg** → the container: how a cloud AI drives your verbs to get real work done. **If the verb surface is large, split it:** a small **core USER skill** (the 80% workflow + a pointer to the sub-skills) plus **sub-skills** by area (e.g. `…-recording`, `…-electronics`, `…-aps-search`). A 2,000-line monolith won't get read; a tight core skill that names the sub-skills will. (Pup ships exactly this shape: a core bridge skill + user sub-skills.) -Ship ALL of them — user + dev + publish — in your **pkg**, each as a real `skills/<name>/SKILL.md` (the SKILLPACK layout, Artifact 2). **Scoping is by AUDIENCE, not filename:** dev/publish skills carry `user-invocable: false` + a description that opens DEVELOPER-only, so everyday users are never offered them while your maintainer thread still installs the full set. (The old "name dev docs `dev-skills/*.md` so they don't ship" rule is DEAD — pup migrated to the skillpack layout 2026-07-03 and its `skill_count: 3` is by design.)+**Only the USER skill(s) go in your pkg** (Artifact 2), each a real `skills/<name>/SKILL.md`. **The DEV + PUBLISH skills stay in your source repo** — a developer gets them by cloning to edit the bridge; they are NOT in the pkg's `files[]`, and you do NOT "scope" them into the pkg with `user-invocable:false` (that still ships them and bloats every container install). Open-vs-closed source doesn't change this — it only sets whether your repo's dev/publish files are publicly readable.  **Start from the templates — don't write these from scratch.** `skills/bridge-templates/` in the AD repo has a fill-in-the-blanks file for each of the three skill kinds, generalized from pup's battle-tested set: **`bridge-dev-template.md`** (architecture + the rich-hints rule), **`bridge-publish-template.md`** (the whole release/pkg/discovery dance + every trap), **`bridge-user-skill-template.md`** (the consumer skill, already encoding all eight conventions below). Copy the one you need, swap `<bridge>`/`<prefix>` for your names, delete what doesn't apply.