Pup - the AI's own browser

@@ -1,7 +1,7 @@ --- name: pup-bridge-publish user-invocable: false-description: "DEVELOPER skill — the exact, battle-tested recipe for publishing a new version of the Adom Desktop Puppeteer (pup) bridge to wiki.adom.inc, plus every gotcha hit live. NOT for general users. Read before cutting a release: which artifact goes where (pkg=skills, release=bridge zip), version-lockstep, the `files` allowlist + `skills/**` glob trap, keeping the tarball lean (NO zip / NO src / NO heroes), bundling dev/publish skills the wiki skillpack way (skills/<name>/SKILL.md + explicit install.sh list), deploying skills to .claude AND .codex, scrubbing stale retired-wiki (wiki-ufypy5dpx93o.adom.cloud) URLs, user-first discovery triggers, sha matching, and verify steps. Trigger words: publish pup bridge, ship pup bridge, release pup, pkg publish, repo push, adom-wiki release, bridge manifest, pup version bump, no zip in tarball, dev skill source only, scrub old wiki url, codex skills, discovery triggers, adom-desktop-puppeteer-bridge publish."+description: "DEVELOPER skill — the exact, battle-tested recipe for publishing a new version of the Adom Desktop Puppeteer (pup) bridge to wiki.adom.inc, plus every gotcha hit live. NOT for general users. Read before cutting a release: which artifact goes where (pkg=skills, release=bridge zip), version-lockstep, the `files` allowlist, keeping the tarball lean (NO zip / NO src / NO heroes / NO maintainer skills), the three-tier skill layout (user skill ships from root SKILL.md; dev/publish skills live in dev-skills/ + publish-skills/ and are auto-excluded from the tarball — never shipped to user containers), deploying skills to .claude AND .codex, scrubbing stale retired-wiki (wiki-ufypy5dpx93o.adom.cloud) URLs, user-first discovery triggers, sha matching, and verify steps. Trigger words: publish pup bridge, ship pup bridge, release pup, pkg publish, repo push, adom-wiki release, bridge manifest, pup version bump, no zip in tarball, dev skill source only, scrub old wiki url, codex skills, discovery triggers, adom-desktop-puppeteer-bridge publish." ---  Parent skill: **adom-desktop-puppeteer-bridge**@@ -97,9 +97,10 @@ The pkg description lives in the root **`package.json`** `description` — keep - **`pkg pack` includes EVERYTHING by default** → a 16 MB 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.-- **`files` directory entries need a GLOB.** Listing `"skills"` (bare dir) silently includes ZERO skill-  files. Use **`"skills/**"`** (and/or the explicit `"skills/<name>/SKILL.md"`). Always `tar tzf` to-  confirm your skills actually made it in — a missing skill = an empty Skills tab.+- **`files` directory entries need a GLOB** — if you ever ship an extra USER skill under `skills/`, list+  `"skills/**"` (a bare `"skills"` dir entry silently includes ZERO files). But maintainer skills do NOT+  go in `files[]` at all — they live in `dev-skills/`/`publish-skills/` (auto-excluded). Always `tar tzf`+  to confirm exactly what shipped. - **`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@@ -124,33 +125,49 @@ adom-desktop --target <name> browser_readiness '{}' # render the page in pup + READ the screenshot (curl 200 is NOT verification). Confirm version + Skills tab. ``` -## Bundle dev/publish skills the wiki SKILLPACK way (superseded the old source-only hack)+## The three-tier skill layout — DON'T ship maintainer skills to users -Everyday users should get ONLY the `pup` user skill by *triggering*, but the wiki's blessed structure-(see the `wiki-skillpack` skill / the `adom-wiki-skillpack` reference repo) is: **every skill is a real-`skills/<name>/SKILL.md`**, listed EXPLICITLY (no globs) in `install.sh`, `uninstall.sh`, and-`package.json files[]`, with a `Parent skill: **adom-desktop-puppeteer-bridge**` first body line and a-skill-map table in the root SKILL.md + README.+The wiki packer recognizes THREE tiers by DIRECTORY, and its own `pkg pack` hint spells it out:+*"build/debug/test skills go in `dev-skills/`, app→wiki publish skills in `publish-skills/` — both are+**auto-excluded** from the tarball and belong in the source repo, so you don't ship them to every+install."* -History: we originally kept dev skills as loose `dev-skills/*.md` files to dodge the Skills-tab indexer.-That was based on a wrong assumption — the reference skillpack carries 14 SKILL.md files with-`skill_count: 0`, so the indexer does NOT blindly count SKILL.md files. The loose-file hack broke the-convention (no folder, no Parent line, no explicit install list) and made the dev skills invisible to-tooling. Superseded 2026-07-03.--Keeping everyday users out of dev skills is done the skillpack way instead:-- `user-invocable: false` in the sub-skill frontmatter;-- descriptions that lead with "DEVELOPER skill … NOT needed by general users" so they never trigger;-- the `pup` skill map tells the AI which skill is for whom.+| Tier | Location | Ships in pkg tarball? | For |+|---|---|---|---|+| **user** | root `SKILL.md` (+ `skills/<name>/SKILL.md` for extra *user* skills) | YES | everyday users — here, just `pup` |+| **dev** | `dev-skills/<name>/SKILL.md` | **NO (auto-excluded)** | maintainers building the bridge |+| **publish** | `publish-skills/<name>/SKILL.md` | **NO (auto-excluded)** | maintainers cutting a release (this skill) |++So for pup: `pup` is the only USER skill (root `SKILL.md`); `pup-bridge-dev` lives in+`dev-skills/pup-bridge-dev/SKILL.md` and `pup-bridge-publish` in+`publish-skills/pup-bridge-publish/SKILL.md`. They stay in the git repo (maintainers read them via+`repo clone` / the Files tab) but NEVER land on a user's container.++Consequences for the publish machinery — get these right or you re-ship ~37 KB of recipes to every user:+- **`package.json files[]` lists ONLY the user files** — `SKILL.md`, `install.sh`, `uninstall.sh`,+  `README.md`, `package.json`. Do NOT list `dev-skills/**` or `publish-skills/**` (and don't put maintainer+  skills under `skills/**` either — anything shipped there counts as a USER skill).+- **`install.sh` installs ONLY the `pup` user skill.** (uninstall.sh may still `rm -rf` the old+  `pup-bridge-*` dirs so upgrades from the pre-1.8.21 layout clean up.)+- **Verify:** `adom-wiki pkg pack` prints `shipped N user skill(s)` — for pup that must be **1**. Then+  `tar tzf *.tgz | grep -c 'dev-skills\|publish-skills\|pup-bridge'` must be **0**.++History (so you don't "fix" it backwards): through 1.8.20 the dev/publish skills were wrongly placed under+`skills/<name>/` + listed in `files[]`, so the packer shipped them as user skills (28 KB tarball). Moved+to `dev-skills/`/`publish-skills/` on 2026-07-05 → 12 KB, 1 user skill. The `user-invocable: false`+frontmatter still matters (belt-and-suspenders so they never *trigger*), but the DIRECTORY is what keeps+them out of the tarball.  ## Keep the pkg tarball LEAN — NO zip, NO src/, NO heroes -The pkg tarball must be the `pup` 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.+The pkg tarball must be the `pup` user skill ONLY — never the bridge runtime zip, `src/`, hero PNGs, or+the dev/publish maintainer skills. Guards: the `package.json` `files` allowlist (`SKILL.md`, `install.sh`,+`uninstall.sh`, `README.md`, `package.json` — NO `skills/**` for pup, since its only extra skills are+maintainer-tier and live in the auto-excluded `dev-skills/`/`publish-skills/`) **plus** `.gitignore`+(`*.zip`, `*.png`, `*.bundle`, `*.tgz`, the old `*-source.tar.gz`). **ALWAYS** `adom-wiki pkg pack` then+`tar tzf *.tgz` and confirm: **no `*.zip`, no `src/`, no `*.png`, no `dev-skills/`/`publish-skills/`, and+`shipped 1 user skill(s)`**. A lean tarball is ~12 KB; if it's megabytes, something heavy leaked in (it+was 16 MB before the guards, 28 KB when the maintainer skills wrongly shipped). `rm -f *.tgz` after.  ## Skills install to BOTH .claude AND .codex