Adom Wiki Skill Pack

@@ -1,3 +1,179 @@ # Adom Wiki Skill Pack -How to use the Adom Wiki without breaking pages — five tools in one, three repo archetypes (Page, Skillpack, Family), 13 skills in one install.+**One install, 13 skills that teach the AI to use the Adom Wiki without breaking+pages — plus a write-up of the wiki repo archetypes that have emerged from real+use.**++![Adom Wiki Skill Pack](/blob/skill/adom-wiki-skillpack/screenshots/hero.png)++Publishing to [wiki.adom.inc](https://wiki.adom.inc) is powerful but fraught: the+AI re-breaks pages (unlinks heroes, base64-mangles READMEs, writes only one of+the two storage layers, forgets to verify what it shipped). And as the wiki has+been used heavily, a set of **repo archetypes** has quietly emerged — patterns+nobody had named or written down. This pack fixes both: it bundles the publishing+know-how as installable skills, and it names the archetypes so they can be used+deliberately.++> **📌 Note for Colby (and anyone building the wiki):** the section+> [**The repo archetypes**](#the-repo-archetypes-emerging-from-real-use) is for+> you. It documents the page structures that have emerged from heavy real-world+> use of the wiki — Page, Skillpack, and Family — and a few features they lean on+> (private source + public releases, the private readme, breadcrumbs, scoring).+> Some of it is built, some is partial, some is still a spec; each skill labels+> its status honestly. This is meant as a design mirror: here's how your heaviest+> user is actually structuring repos, so the platform can meet those patterns.++## Install++```bash+adompkg install adom-wiki-skillpack+```++This drops the main `adom-wiki-skillpack` skill plus 12 sub-skills onto your+container, and pulls in **`adom-wiki-hero-image`** (a dependency) for hero+generation.++## The wiki is five tools in one++It feels like a wiki, but it's a fusion of five tools you already know, all keyed+off one slug per page:++| # | Tool | Like | What it powers |+|---|---|---|---|+| 1 | **Git host** | GitHub repo | Files tab, README, commits, contributors |+| 2 | **adompkg** | npm | `install` / `publish` / `update`, dependency maps |+| 3 | **Release database** | GitHub Releases | versioned downloadable binaries |+| 4 | **Discussions** | GitHub Issues | a forum thread per page |+| 5 | **Pull requests** | GitHub PRs | community edits, owner reviews/merges |++Plus a **scoring/trending** layer (stars / high-fives / installs) and a+**presentation** layer (`README.md` or a custom `readme.html`, and a separate+**private readme** for proprietary pages).++The single most important consequence: **the git repo and the package registry are+two independent storage layers.** `adompkg publish` does *not* push your source to+git, and pushing files does *not* make a tarball. A correct publish writes both.+Doing one leaves the page half-broken — the root of most incidents.++## The repo archetypes (emerging from real use)++Three repo shapes have emerged. Naming them turns "how should I structure this?"+into a deliberate choice.++![The three Adom Wiki repo archetypes](/blob/skill/adom-wiki-skillpack/screenshots/archetypes.png)++### 1. Page — one page = one thing++A single page for a single app/tool/skill/doc. Two sub-variants by **source+visibility**:++- **Open-source Page** — source public + installable. _e.g._ `chip-fetcher`,+  `adom-usb`. MIT, contributions welcome.+- **Closed-source Page** — source **private**, releases/adompkg **public**, so+  people install the compiled app but can't read the code. _e.g._+  `hydrogen-desktop`, `adom-desktop`. Uses the **private readme** so the page+  still has public docs.++> The wiki lets the git source, the release/package, and the readme each be public+> or private independently — that's what makes a proprietary app and an+> open-source library both first-class on the same platform.++### 2. Skillpack — one repo, one main skill + N sub-skills++One repo / one installable package carrying a whole set of skills, deployed+together by a single `adompkg install`. Sub-skills are files under `skills/`, not+separate pages. **Convention: the slug ends in `-skillpack`** so the class is+recognizable.++- _e.g._ `adom-ui-design` (grandfathered, predates the suffix), and **this pack**.+- **This very repo is a Skillpack** — it dogfoods its own archetype.++### 3. Family — an anchor page + separately-published children++An anchor page plus children published as **their own pages**, joined by+convention rather than living in one repo:++- **Slug** `<parent>-<descriptor>`; **Title** leads with the parent+  (`Adom USB - CDC serial sniffer`); a **family tag** (`<parent>-plugin`); and+  **breadcrumbs** linking children back to the anchor.+- _e.g._ `adom-desktop` (+ bridges), `adom-usb` (+ sniffer/firmware plugins).++### Skillpack vs Family — the decision rule++Both are "a main thing + many smaller things." The divider is **ownership and+update cadence**:++- **Skillpack** when one author owns all the parts and they version *together*.+- **Family** when children have *independent owners or release cadences* — each is+  its own page, and third parties can add their own without touching the anchor.++**Worked example — `chip-fetcher`:** it's open source AND has many per-vendor+scraper skills (DigiKey, Mouser, TI, Analog Devices) that **change daily** and+that **third parties** want to own. As a Skillpack, every vendor tweak would force+the single owner to re-publish the whole pack. So it's better as a **Family**: an+anchor plus `chip-fetcher-digikey`, `chip-fetcher-mouser`, … each independently+publishable, discovered via the family tag + breadcrumbs. Rule of thumb: _does+each part need its own lifecycle and maybe its own author?_ Yes → Family.++## The hard rules (page-breakers)++The pack encodes these; they're worth stating here too:++1. **Write both storage layers** every publish (git + registry).+2. **`adompkg publish` clobbers the hero** — it overwrites the repo's `page.json`+   (no `hero`), so the hero gets *unlinked* (not deleted) on every publish. Fix:+   **publish first, push a complete `page.json` LAST.** (This is the recurring+   "hero disappeared" bug.)+3. **Never base64 a text file** — only real binaries are base64.+4. **Versions are immutable** — bump; never delete-and-recreate (soft-delete trips+   a UNIQUE constraint).+5. **Verify with your eyes** — open the live page in pup and screenshot it before+   calling any wiki edit done.++## Skills in this pack++| Skill | What it's for |+|---|---|+| **adom-wiki-skillpack** | Entry point: the five-tools model, the archetypes, the hard rules, the map. |+| **wiki-anatomy** | The mental model — five tools in one, and the two storage layers. |+| **wiki-api** | The REST API + `adompkg` CLI and the publish workflow. |+| **wiki-publish-safely** | Operational pitfalls as hard rules + the verify-in-pup gate. |+| **wiki-readme** | Make a great README — `README.md` vs `readme.html`, sections, embeds. |+| **wiki-visibility** | Public vs private source, public releases, the private readme. |+| **wiki-repo-styles** | The archetype taxonomy and how to choose. |+| **wiki-family** | Build a Family: naming, family tag, anchor registry, breadcrumbs. |+| **wiki-skillpack** | Build a Skillpack: layout, install.sh, files[], the `-skillpack` suffix. |+| **wiki-hero** | Generate a hero, and never let it get unlinked. |+| **wiki-breadcrumbs** | Third-party "I built an add-on for X" links _(implemented, basic)_. |+| **wiki-forking** | Fork + community-PR contribution _(PRs live; fork-button planned)_. |+| **wiki-scoring** | Stars / high-fives / installs / trending _(stars live; rest partial)_. |++## Talk to the AI++- "Publish this tool to the wiki" → wiki-api + wiki-publish-safely+- "What kind of wiki repo should this be?" → wiki-repo-styles+- "Make a hero for this page" / "the hero disappeared" → wiki-hero+- "Write a README for this page" → wiki-readme+- "Keep the source private but let people install it" → wiki-visibility+- "Bundle these skills into one package" → wiki-skillpack+- "Add a child plugin to adom-usb / a bridge to adom-desktop" → wiki-family++## Dependencies++| Dependency | Required? | Why |+|---|---|---|+| **adom-wiki-hero-image** | Yes | Generates the 16:10 hero billboard every page needs; self-contained (bundles brand fonts + wordmark + render pipeline). Pulled automatically by `adompkg install`. |++Companion tools (not hard dependencies): `adompkg` itself (the package manager),+and `adom-desktop` / pup for the verify-in-pup step.++## Relationship to gallia++Gallia's `adom-wiki-v2` and `adom-wiki-hero-image` skills remain the+employee-internal source of truth. This pack is the **public, installable digest**+of that knowledge plus the archetype taxonomy — same model as `adom-ui-design`.+Update gallia first, then refresh this page.++## License++MIT.

@@ -0,0 +1,100 @@+---+name: adom-wiki-skillpack+user-invocable: true+description: >-+  The Adom Wiki Skill Pack — the entry point for working with the Adom Wiki+  (wiki.adom.inc). Read this BEFORE creating, publishing, or restructuring any+  wiki page. The wiki is five tools in one (git host + adompkg package manager ++  release database + discussion forum + pull requests), and three repo+  archetypes have emerged from real use: Page, Skillpack, and Family. This pack+  routes to 12 focused sub-skills and carries the hard rules that keep pages from+  breaking. Trigger words: the wiki, adom wiki, wiki.adom.inc, publish to the+  wiki, wiki repo, wiki page, what kind of wiki repo, repo archetype, skillpack,+  super-skill, wiki family, parent child repo, wiki readme, hero unlinked,+  proprietary wiki page, private source public app, wiki breadcrumb, fork a wiki+  page, wiki scoring, trending, high five, adompkg publish.+---++# Adom Wiki Skill Pack++The Adom Wiki at **https://wiki.adom.inc** is the single canonical wiki. This+pack is the map for working with it. Gallia's `adom-wiki-v2` and+`adom-wiki-hero-image` skills remain the employee-internal source of truth; this+pack is the **public, installable digest** of that knowledge plus the repo+archetypes that have emerged from heavy real-world use — update gallia first,+then refresh this page.++## The wiki is five tools in one++It feels like a wiki, but it's a fusion of five tools you already know, all+keyed off one slug per page:++1. **Git host** — every page is a real git repo (Files tab, commits, contributors).+2. **adompkg** — an npm-style package manager: dependency maps, `adompkg update`.+3. **Release database** — versioned binary/tarball releases (like GitHub Releases).+4. **Discussion forum** — a thread per page (like GitHub Issues).+5. **Pull requests** — community edits proposed to a repo, the owner reviews/merges.++Cross-cutting: a **scoring/trending** system (stars / high-fives / install counts)+and a **presentation layer** (a plain `README.md`, or a custom `readme.html`, plus+a separate **private readme** for proprietary-source pages). Full model →+**wiki-anatomy**.++## Three repo archetypes (pick one before you publish)++| Archetype | One line | Examples | Build skill |+|---|---|---|---|+| **Page** | One page = one thing. Open-source (public source) or Closed-source (private source, public compiled app). | chip-fetcher, adom-usb / hydrogen-desktop, adom-desktop | wiki-visibility |+| **Skillpack** | One repo, one main skill + N sub-skills, installed together. Suffix `-skillpack`. | adom-ui-design, **this pack** | wiki-skillpack |+| **Family** | An anchor page + children published as separate pages, joined by naming + a family tag + breadcrumbs. | adom-desktop, adom-usb | wiki-family |++Decision: **Skillpack** when one author owns all the skills and they version+together; **Family** when children have independent owners or update cadences+(e.g. per-vendor scrapers that change daily). Full taxonomy → **wiki-repo-styles**.++## The hard rules (the page-breakers)++These are the mistakes that recur. They each have a dedicated skill, but they're+important enough to state up front:++1. **Write BOTH storage layers, every publish.** The git repo (Files/README) and+   the package registry (tarball/`adompkg install`) are independent. Do only one+   and the page is broken. → **wiki-api**, **wiki-publish-safely**.+2. **`adompkg publish` clobbers the hero.** It overwrites the repo's `page.json`+   with the package manifest (which has no `hero`), so the page-header hero gets+   unlinked on every publish. The image isn't deleted — its reference is. **Fix:+   publish FIRST, then push a complete `page.json` (with `hero`) to git LAST.** →+   **wiki-hero**, **wiki-publish-safely**.+3. **Never base64 a text file.** Text (`.md`, `.json`, `.sh`) goes as plain+   `content`; only real binaries (images) go base64. → **wiki-api**.+4. **Versions are immutable.** Bump before republishing; never delete-and-recreate+   (soft-delete trips a UNIQUE constraint). → **wiki-publish-safely**.+5. **Verify with your eyes.** After ANY wiki edit, open the live page in pup and+   screenshot-confirm it rendered before calling it done. → **wiki-publish-safely**.++## Skill map++| Skill | Use it for |+|---|---|+| **wiki-anatomy** | The mental model: the five tools in one, and how the layers relate. |+| **wiki-api** | The REST API + `adompkg` CLI, the two storage layers, the publish workflow. |+| **wiki-publish-safely** | The operational pitfalls as hard rules; the verify-in-pup gate. |+| **wiki-readme** | How to make a great README — `README.md` vs `readme.html`, sections, embeds, images. |+| **wiki-visibility** | Public vs private source, public releases, the private readme, open vs closed pages. |+| **wiki-repo-styles** | The archetype taxonomy (Page / Skillpack / Family) and how to choose. |+| **wiki-family** | Build a Family: naming convention, family tag, anchor registry, breadcrumbs. |+| **wiki-skillpack** | Build a Skillpack: layout, install.sh, files[], skill map, the `-skillpack` suffix. |+| **wiki-hero** | The hero image: generate it (adom-wiki-hero-image), and never let it get unlinked. |+| **wiki-breadcrumbs** | Third-party "I built an add-on for X" links — the breadcrumb system. |+| **wiki-forking** | Fork + community-PR contribution flow (PRs live; fork-button planned). |+| **wiki-scoring** | Stars / high-fives / installs / trending — what's tracked and how to earn it. |++## Talk to the AI++- "Publish this tool to the wiki" → wiki-api + wiki-publish-safely+- "What kind of wiki repo should this be?" → wiki-repo-styles+- "Make a hero for this page" / "the hero disappeared" → wiki-hero+- "Write a README for this page" → wiki-readme+- "Keep the source private but let people install it" → wiki-visibility+- "Bundle these skills into one package" → wiki-skillpack+- "Add a child plugin to adom-usb" → wiki-family

@@ -0,0 +1,118 @@+---+name: wiki-api+description: >-+  How to drive the Adom Wiki (wiki.adom.inc) programmatically: the adompkg CLI,+  the REST API (/api/v1/...), authentication, and the publish workflow that+  writes BOTH storage layers (git repo + package registry). Read this before any+  create-page, push-files, or publish call. Trigger words: wiki api, adompkg,+  adompkg publish, adompkg install, POST pages, push files to wiki, wiki rest+  api, publish to the wiki, create wiki page, commit to wiki repo, wiki bearer+  token, adompkg login, two storage layers, wiki tarball.+---++Parent skill: **adom-wiki-skillpack**++# Driving the Adom Wiki: adompkg + the REST API++Canonical host: **https://wiki.adom.inc**. Read **wiki-anatomy** first if you+don't yet know why the wiki has two independent storage layers — this skill is+the how. Read **wiki-publish-safely** for the pitfalls.++## Auth++```bash+bash <(curl -fsSL https://wiki.adom.inc/static/bootstrap.sh)   # if adompkg missing+export PATH="$HOME/.local/bin:$PATH"+adompkg login --token "$(cat /var/run/adom/api-key)"+adompkg whoami+# For curl: -H "Authorization: Bearer $(cat /var/run/adom/api-key)"+```++## adompkg CLI (the bits you use most)++| Command | Purpose |+|---|---|+| `adompkg install <slug>[@ver]` | Install a package (+ its dependencies) |+| `adompkg info <slug>` / `view` | Manifest / full metadata + versions |+| `adompkg search <query>` | Search the registry |+| `adompkg list` / `outdated` / `update` | Manage installed packages |+| `adompkg version <patch\|minor\|major>` | Bump version in package.json |+| `adompkg publish [--org adom] [-y]` | Build + upload the tarball to the registry |+| `adompkg release upload <slug>@<ver> <file> --platform <os>` | Attach a downloadable binary |++Namespace: `adompkg publish` goes to your personal namespace (`john/<slug>`).+Add `--org adom -y` to publish a canonical org package (`adom/<slug>`).++## The publish workflow — both layers, in this order++The git repo and the package registry are written separately (see wiki-anatomy).+Write both, and order matters because of the hero-clobber gotcha (see step 4).++**Step 1 — `package.json` first.** Set `slug`, `version`, `type`, `description`,+`dependencies`, `files[]` (list every shipped file), and `scripts.install/uninstall`.++**Step 2 — create the page (first publish only).** Inits the git repo.++```bash+WIKI="https://wiki.adom.inc"+curl -s -X POST "$WIKI/api/v1/pages" \+  -H "Authorization: Bearer $(cat /var/run/adom/api-key)" \+  -H "Content-Type: application/json" \+  -d '{"type":"skill","slug":"my-tool","title":"my-tool","brief":"One line","version":"0.1.0"}'+```++**Step 3 — `adompkg publish`.** Builds the tarball and uploads it to the registry.+(Do this before the final file push — see step 4.)++```bash+cd /path/to/my-tool && adompkg publish+```++**Step 4 — push ALL source files to the git repo, with a complete `page.json` LAST.**+This is the equivalent of `git push`. **Critical:** `adompkg publish` overwrote+the repo's `page.json` with the package manifest, which has no `hero` — so you+re-push a *complete* `page.json` (including `hero:{type,path}`, title, brief,+tags) as the final step to re-index and re-link the hero. See **wiki-hero**.++```python+import requests, base64, os+BINARY_EXTS = {'.png','.jpg','.jpeg','.webp','.gif','.ico','.woff','.woff2',+               '.tgz','.gz','.zip','.bin','.exe','.glb','.step','.stl','.wasm','.so','.dll'}+files, skip = [], {'.git','target','node_modules'}+for root, dirs, fnames in os.walk(project_dir):+    dirs[:] = [d for d in dirs if d not in skip]+    for f in fnames:+        full = os.path.join(root, f); rel = os.path.relpath(full, project_dir)+        if os.path.getsize(full) > 10_000_000: continue+        if os.path.splitext(f)[1].lower() in BINARY_EXTS:+            files.append({"path": rel, "content": base64.b64encode(open(full,'rb').read()).decode(), "encoding": "base64"})+        else:+            files.append({"path": rel, "content": open(full).read()})  # TEXT = plain, never base64+for i in range(0, len(files), 50):  # batch by 50 (payload limit)+    requests.post(f"{WIKI}/api/v1/pages/{slug}/files",+        headers={"Authorization": f"Bearer {token}", "User-Agent": "adompkg/2.1.0"},  # UA dodges Cloudflare WAF+        json={"files": files[i:i+50], "message": "Publish source"})+```++**Step 5 — verify in pup** (non-negotiable; see **wiki-publish-safely**).++## Encoding rule (memorize)++Text files (`.md`, `.rs`, `.toml`, `.js`, `.json`, `.sh`) → plain `{"content": "..."}`.+Binary files (images, fonts, archives) → `{"content": "<base64>", "encoding": "base64"}`.+Base64-encode a text file and the README renders as gibberish.++## REST API quick reference++- Pages: `POST /pages`, `GET/PUT/DELETE /pages/:slug`, `GET /pages` (`?type=&limit=&offset=`)+- Files (git): `GET/POST /pages/:slug/files`, `GET /pages/:slug/files/:path`, `GET /pages/:slug/log`+- Packages: `POST /packages/:slug/publish`, `GET /packages/:slug/manifest|versions`, `POST /packages/resolve`, `PUT .../deprecate`+- Social: `POST/DELETE /pages/:slug/star`, `GET /pages/:slug/stars`, discussions under `/pages/:slug/discussions`+- PRs: `GET/POST /pages/:slug/prs`, `POST /prs/:id/merge|close`+- Breadcrumbs: `GET /pages/:slug/breadcrumbs` (see **wiki-breadcrumbs**)+- Search/discover: `GET /search?q=`, `GET /discover?triggers=<csv>`++Two gotchas worth pinning here: **Cloudflare WAF blocks Python urllib without a+`User-Agent`** (use `adompkg/2.1.0`; curl is fine), and **FTS search chokes on+hyphens** (`chip-fetcher` → "no such column: fetcher"). Full pitfall list →+**wiki-publish-safely**.

@@ -0,0 +1,91 @@+---+name: wiki-publish-safely+description: >-+  The hard rules and operational pitfalls for editing Adom Wiki pages+  (wiki.adom.inc) without breaking them — write both storage layers, never+  base64 a text file, versions are immutable, soft-delete blocks re-creation, the+  hero gets clobbered on publish, rate limits, and the non-negotiable verify-in-pup+  step. Read this before AND after any publish, file push, README change, or+  metadata edit. Trigger words: wiki publish broke the page, page shows+  placeholder, readme is gibberish, files tab empty, hero disappeared, hero+  unlinked, UNIQUE constraint pages, immutable version, adompkg 429, ghost page,+  verify wiki in pup, wiki publish checklist, don't break the wiki page.+---++Parent skill: **adom-wiki-skillpack**++# Publishing to the wiki without breaking the page++Every item here is a real incident that recurs. Treat them as hard rules. The+mechanics live in **wiki-api**; this is the "don't shoot yourself in the foot"+companion.++## The five rules that prevent broken pages++1. **Write BOTH layers, every publish.** Git repo (`POST /files`) *and* package+   registry (`adompkg publish`). Only one → the page is broken (placeholder Files+   tab, or a README that won't `adompkg install`). See **wiki-anatomy**.++2. **The hero gets clobbered — re-push `page.json` LAST.** `adompkg publish`+   overwrites the repo's `page.json` with the package manifest, which has **no+   `hero`** — so the page-header hero is unlinked on every publish. The PNG is NOT+   deleted; only its reference is dropped. **Fix:** publish first, then push a+   *complete* `page.json` (with `hero:{type:"image",path:"screenshots/hero.png"}`,+   title, brief, tags) as the final commit, and confirm+   `GET /api/v1/pages/<slug>` shows `hero_path` set. Full detail → **wiki-hero**.+   The same clobber resets the page **title and brief** to the package values —+   the complete `page.json` re-push restores those too.++3. **Text is plain; only binaries are base64.** Base64-encoding a `.md`/`.json`/+   `.sh` makes the wiki store the base64 string as the file content → README+   renders as gibberish. Images/fonts/archives go base64; everything else plain.++4. **Versions are immutable; never delete-and-recreate.** Once `0.1.0` is+   published it can't be overwritten — `adompkg version patch` before republishing+   changed source. And `DELETE /pages/:slug` only *soft*-deletes (sets+   `deleted_at`), after which republishing the same slug fails with+   `UNIQUE constraint failed: pages.owner, pages.slug`. Bump the version instead+   of deleting. (Hard purge exists — `DELETE /pages/<slug>?hard=true` — but it's+   irreversible and rarely the right move.)++5. **Verify with your eyes — open the live page in pup.** After ANY wiki edit+   (publish, file push, metadata/README/hero change, even a one-file fix), open+   the page in a pup window on the user's laptop and screenshot-confirm it+   rendered. Do not report a wiki edit as done from API JSON alone.++   ```bash+   OWNER=john; SLUG=my-page; LAP=AdomLapper   # `adom-desktop status` shows the laptop host+   adom-desktop browser_open_window \+     "{\"sessionId\":\"wiki\",\"profile\":\"wiki\",\"url\":\"https://wiki.adom.inc/$OWNER/$SLUG\"}" \+     --target "$LAP"+   sleep 3+   adom-desktop browser_screenshot '{"sessionId":"wiki","maxWidth":1500}' --target "$LAP"+   # Read the screenshot; confirm it rendered before telling the user it's done.+   ```++   Reuse `sessionId:"wiki"` / `profile:"wiki"` every time so the login persists;+   `browser_navigate` an already-open window rather than spawning new ones.++## Other gotchas++- **Cloudflare WAF blocks Python urllib/requests without a `User-Agent`** →+  send `User-Agent: adompkg/2.1.0`. curl sends its own UA and is fine.+- **Publish-only pages create ghost rows.** `adompkg publish` without first+  `POST /pages` makes a tarball but no git repo; a later `POST /files` then+  inserts a *second* page row (a duplicate on the listing). Always create the+  page first.+- **Rate limit: ~10 publishes/minute** → HTTP 429. Space them or retry.+- **Search hyphen bug:** FTS reads `-` as a column operator (`chip-fetcher` →+  "no such column: fetcher"). Most slugs have hyphens; expect this until fixed.+- **Inline images need HEAD support** on `/blob/` routes — a known wiki bug means+  `<img>` can 404 on preflight even though the tag is correct. Verify visually.++## The publish checklist++- [ ] `package.json`: version bumped, `files[]` complete, `dependencies` set+- [ ] Page created (first time only) via `POST /pages`+- [ ] `adompkg publish` succeeded (tarball in registry)+- [ ] ALL source pushed to git (text plain, binaries base64, UA header)+- [ ] **Complete `page.json` pushed LAST** → `hero_path`, title, brief restored+- [ ] Opened in pup + screenshot read: README renders, Files tab full, hero shows+- [ ] `adompkg info <slug>` shows the right version + dependencies

@@ -0,0 +1,88 @@+---+name: wiki-readme+description: >-+  How to make a great Adom Wiki page presentation — the README is the page. Covers+  the choice between a plain README.md and a fully custom readme.html, the+  mandatory sections every page needs, embedding live demos / videos / iframes,+  and referencing inline images from the repo. Read this when writing or fixing+  the Overview tab of a wiki page. Trigger words: how to make a readme, wiki+  readme, readme.html, custom readme, write a readme for the wiki, wiki page+  overview, embed iframe wiki, embed demo, inline images readme, wiki page+  presentation, mandatory readme sections, readme renders blank.+---++Parent skill: **adom-wiki-skillpack**++# How to make a README (the presentation layer)++On the Adom Wiki the **README is the page** — the Overview tab is the first thing+a human sees, and it's what sells the page in search and on cards. The renderer+(`marked`) passes HTML through, so you can go from a plain doc to a fully+designed page.++## Two modes++- **`README.md`** — plain Markdown. The default; right for most pages. You can+  still embed raw HTML (iframes, video, styled divs) inline.+- **`readme.html`** — a fully custom HTML document, when you want complete control+  over layout, embeds, and styling (landing-page-grade pages). Use when Markdown+  can't express the design you want; otherwise prefer `README.md` for+  maintainability.++There is also a **private readme** for pages whose git source is private but whose+releases are public — so the public still gets docs without seeing the source.+That's a visibility concern → see **wiki-visibility**.++## The README is for humans, and humans need images++**Never publish a text-only README.** Every page needs a hero and at least two+inline screenshots; any page with a UI also needs an embedded live demo. A skill+`description` is for the AI — the README is for the person deciding whether to+install.++## Mandatory sections (in this order)++1. **Title + one-line description**+2. **Hero image** — right after the description. Generate it with the+   `adom-wiki-hero-image` skill (see **wiki-hero**).+3. **Live demo** (if there's any UI) — an `<iframe>` of a self-contained+   `demo/index.html` with baked-in sample data (no server dependency).+4. **Install** — `adompkg install <slug>`+5. **Quick start** — 3–5 lines showing the most common workflow+6. **Screenshots** — 2–4 inline images, each with a caption heading+7. **Dependencies** — a table: Dependency / Required? / Why (explain the *why*)+8. **Features** — bullet list+9. **Talk to the AI** — paste-ready prompts grouped by action, using the exact+   trigger words so routing works (this teaches humans the vocabulary)+10. **Skills** — table of the main skill + sub-skills with a purpose column+11. **CLI reference** — command table (if there's a CLI)++## Embeds++Inline image from the repo (blob endpoint):++```markdown+![Dashboard](/blob/<type>/<slug>/screenshots/hero.png)+```++Self-contained demo (bake sample data into the HTML, no fetch/WebSocket):++```html+<iframe src="/blob/app/<slug>/demo/index.html" width="100%" height="500"+  frameborder="0" style="border-radius:8px;border:1px solid #333;"></iframe>+```++Video — local file from the repo (the blob endpoint supports Range, so seeking+works), or YouTube via `youtube-nocookie.com`, or Vimeo:++```html+<video width="100%" controls poster="/blob/app/<slug>/screenshots/hero.png">+  <source src="/blob/app/<slug>/demo/walkthrough.webm" type="video/webm"></video>+```++## Known rendering pitfalls++- Inline images can 404 on `<img>` HEAD preflight (a wiki bug) even though the+  tag is correct — always verify visually in pup.+- After `adompkg publish`, the page title/brief reset to the package values;+  re-push a complete `page.json` to restore them (see **wiki-publish-safely**).

@@ -0,0 +1,99 @@+---+name: wiki-repo-styles+description: >-+  The taxonomy of Adom Wiki repo archetypes that have emerged from real use, and+  how to choose between them BEFORE you publish: Page (open- or closed-source),+  Skillpack (one repo, many bundled sub-skills, suffix -skillpack), and Family (an+  anchor page plus separately-published children). Read this when starting any new+  wiki repo or deciding how to structure related pages. Trigger words: what kind+  of wiki repo, wiki repo archetype, wiki repo style, page vs skillpack vs family,+  parent child wiki, super skill repo, bundle skills or separate, how to structure+  a wiki repo, skillpack vs family, one repo or many, chip-fetcher structure.+---++Parent skill: **adom-wiki-skillpack**++# Wiki repo archetypes — pick one before you publish++Three repo shapes have emerged from heavy real-world use of the Adom Wiki. Naming+them makes the choice deliberate instead of accidental. Decide which one a new+thing is **before** you create the page, because the layout, naming, and publish+flow differ.++## 1. Page — one page = one thing++A single wiki page for a single app, tool, skill, or doc. Two sub-variants by+**source visibility** (see **wiki-visibility**):++- **Open-source Page** — source public + installable. e.g. `chip-fetcher`,+  `adom-usb`. MIT, contributions welcome.+- **Closed-source Page** — source **private**, releases/adompkg **public** →+  install the compiled app, can't read the code. e.g. `hydrogen-desktop`,+  `adom-desktop`. Uses the private readme.++## 2. Skillpack — one repo, one main skill + N sub-skills++One repo, one installable package, that carries a whole set of skills installed+together by a single `adompkg install`. The sub-skills are files under `skills/`,+**not** separately published pages. Convention: the slug ends in **`-skillpack`**+so the class is recognizable in the grid and in `~/.claude/skills/`.++- Examples: **adom-ui-design** (grandfathered — predates the suffix), and **this+  pack, adom-wiki-skillpack**.+- Build it → **wiki-skillpack**.++## 3. Family — an anchor page + separately-published children++A parent ("anchor") page plus multiple **children published as their own pages**,+joined not by living in one repo but by convention:++- **Slug**: `<parent>-<descriptor>` (e.g. `adom-usb-sniffer-cdc`).+- **Title**: leads with the parent — `Adom USB - CDC serial sniffer` (plain ASCII+  hyphen, never em-dash) — because cards/search/screensaver show the title, and+  nobody reads slugs.+- **Family tag**: `<parent>-plugin` so the anchor's discovery finds children.+- **Breadcrumbs**: third parties attach a link back to the anchor (see+  **wiki-breadcrumbs**).++- Examples: **adom-desktop**, **adom-usb**.+- Build it → **wiki-family**.++## Skillpack vs Family — the decision rule++Both involve "a main thing plus many smaller things." The dividing question is+**ownership and update cadence**:++- **Skillpack** when **one author owns all the parts and they version together.**+  Shipping a new sub-skill means re-publishing the one pack. (The Adom UI design+  guidelines: one author, one coherent release.)+- **Family** when **children have independent owners or change on their own+  cadence.** Each child is its own page with its own version, and third parties+  can publish their own children without touching the anchor.++### Worked example: chip-fetcher++`chip-fetcher` is the instructive edge case. It's open source AND has many+per-vendor scraper skills (DigiKey, Mouser, TI, Analog Devices) that **change+daily** as those sites change, and **third parties** want to own and update the+ones they care about.++- If it were a **Skillpack**, every vendor tweak would force a re-publish of the+  whole pack by its single owner — a bottleneck, and third parties couldn't+  contribute their own scraper without a PR to the core repo.+- So `chip-fetcher` is better as a **Family**: an anchor (`chip-fetcher`) plus+  children like `chip-fetcher-digikey`, `chip-fetcher-mouser`, each separately+  publishable and independently owned, discovered via the `chip-fetcher-plugin`+  family tag and breadcrumbs. The anchor keeps a registry table of known children.++Rule of thumb: **does each part need its own lifecycle and possibly its own+author?** Yes → Family. No → Skillpack.++## Quick chooser++```+New wiki thing?+├─ One self-contained app/tool/doc?            → Page  (open or closed source)+├─ A set of skills, one owner, ship together?  → Skillpack  (-skillpack suffix)+└─ A hub with parts that have their own        → Family  (anchor + children+   owners / release cadences?                            + family tag + breadcrumbs)+```

@@ -0,0 +1,99 @@+---+name: wiki-skillpack+description: >-+  How to build a Skillpack — one Adom Wiki repo that bundles a main skill plus+  many sub-skills, installed together by a single adompkg install, with the slug+  suffix -skillpack so the class is recognizable. Covers the bundle layout (root+  SKILL.md + skills/<sub>/SKILL.md), an install.sh that lists every skill, the+  package.json files[] whitelist, frontmatter conventions, and the skill-map+  table. Read BEFORE creating a new skill set so you never make a repo per skill.+  Trigger words: make a skillpack, super skill, bundle skills, one repo many+  skills, skill bundle, do not make a repo per skill, skillpack suffix, author a+  skill set, SKILL.md bundle, install.sh skills, wiki skill package.+---++Parent skill: **adom-wiki-skillpack**++# Building a Skillpack (super-skill bundle)++A **Skillpack** is one wiki repo / one installable package that carries a main+skill plus many sub-skills, all deployed by a single `adompkg install`. Use it+when one author owns all the skills and they version together — see+**wiki-repo-styles** for Skillpack-vs-Family.++> **The mistake to never make:** do **not** create one wiki page per small skill.+> A skill as small as a tooltip spec is a *file in a bundle*, not its own repo. A+> page per skill clutters the namespace, fragments install, and duplicates+> metadata. If you catch yourself looping `POST /pages` for many small skills,+> stop — you want one Skillpack with many files under `skills/`.++## The `-skillpack` suffix convention++A Skillpack's slug ends in **`-skillpack`** (e.g. `adom-wiki-skillpack`) so the+class is instantly recognizable in the wiki grid and in `~/.claude/skills/`. The+prior example `adom-ui-design` predates the convention and is grandfathered; new+super-skill bundles should adopt the suffix.++## The bundle layout++```+my-thing-skillpack/            (one wiki repo, one adompkg package)+  SKILL.md                     # the main skill — REQUIRED at repo root by the registry+  README.md                    # rendered on the Overview tab; includes the skill-map table+  page.json                    # title, brief, hero, visibility+  package.json                 # version, files[] lists EVERY skill file, scripts.install/uninstall+  install.sh                   # copies the main skill AND every sub-skill to ~/.claude/skills/<name>/+  uninstall.sh                 # removes them all+  screenshots/hero.png+  skills/+    sub-a/SKILL.md             # each sub-skill: its own folder + SKILL.md+    sub-b/SKILL.md+```++`adompkg install my-thing-skillpack` then drops the main skill plus every+sub-skill onto the container as separate, independently-loadable skill files.++## install.sh lists every skill explicitly++The publish linter rejects an `install.sh` that misses any bundled sub-skill, so+**list each one — do not rely on a glob.**++```bash+#!/usr/bin/env bash+set -e+DEST="$HOME/.claude/skills"+install_skill() { mkdir -p "$DEST/$1"; cp "$2" "$DEST/$1/SKILL.md"; }+install_skill my-thing-skillpack SKILL.md+install_skill sub-a              skills/sub-a/SKILL.md+install_skill sub-b              skills/sub-b/SKILL.md+echo "OK: Installed my-thing-skillpack plus 2 bundled skills to $DEST/."+```++`uninstall.sh` removes the same set. `package.json` `files[]` must list `SKILL.md`,+`README.md`, `page.json`, `install.sh`, `uninstall.sh`, every `skills/<sub>/SKILL.md`,+and any `screenshots/*`, plus `scripts.install`/`scripts.uninstall`.++## Sub-skill naming & frontmatter++- Name sub-skills to avoid clobbering generic names in the shared+  `~/.claude/skills/` dir — prefix them with the pack's domain (this pack uses+  `wiki-*`: `wiki-api`, `wiki-hero`). The folder name = the `name:` frontmatter.+- First body line of each sub-skill: `Parent skill: **<pack-slug>**`.+- Only `name` + `description` are pre-loaded, so the description must carry enough+  signal to be picked, ending with a generous list of quoted trigger phrases. Keep+  each body to one job; if a skill grows past one purpose, split it into another+  file in the same bundle.++## The skill-map table++The main `SKILL.md` and the `README.md` should each carry a **skill-map table**+(Skill | what it's for) so both the AI and humans can see the whole set and route+to the right sub-skill. This is the navigational backbone of a Skillpack.++## Publishing++Publish the whole package via the standard workflow (**wiki-api** /+**wiki-publish-safely**): create the page once, `adompkg publish` the tarball,+push all files to git with a complete `page.json` LAST, then verify in pup that+`adompkg install` deploys every skill. The live reference for this whole pattern+is **adom-ui-design** (and this pack itself).