Adom Wiki Skill Pack

@@ -4,8 +4,6 @@ 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

@@ -65,11 +65,15 @@ important enough to state up front:    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+3. **NEVER embed the hero image in the README body.** The wiki renders the hero+   at the top of the page automatically (from `page.json`). Repeating it inline+   shows the human the same image twice — redundant and rude. README images must+   be OTHER screenshots, never the hero. → **wiki-readme**.+4. **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+5. **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+6. **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

@@ -1,6 +1,6 @@ {   "slug": "adom-wiki-skillpack",-  "version": "0.1.0",+  "version": "0.1.1",   "type": "skill",   "description": "The Adom Wiki Skill Pack — one main skill plus 12 focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, and that name and document the wiki repo archetypes (Page, Skillpack, Family) that have emerged from real use. One adompkg install drops the whole set onto your container.",   "dependencies": {

@@ -24,19 +24,56 @@ or update cadences — see **wiki-repo-styles** for Family-vs-Skillpack. Example ## 1. Naming — every member announces its family  Users meet children out of context (a card, a search hit, a screensaver-billboard), so the family must be obvious without reading the slug:+billboard), so the family must be obvious without reading the slug. There are TWO+names, with DIFFERENT separators — don't mix them up:++### The title — the canonical format (this is the one people see)++The page **title** is what shows on cards, search, the homepage slideshow, and the+screensaver. **Nobody reads slugs — the title is what carries the family.** Use+exactly this format, every time, identically across siblings:++```+<Parent Title> - <Child descriptor>+```++- Separator is a **space, a plain ASCII hyphen `-`, and a space** (`" - "`).+- The parent is its **proper Title Case** product name (`Adom USB`, `Adom Desktop`),+  NOT the slug.+- **NEVER** a colon (`:`), an em-dash (`—`) or en-dash (`–`), a slug-style hyphen+  with no spaces, or the bare descriptor on its own.++| ✅ Correct | ❌ Wrong | Why it's wrong |+|---|---|---|+| `Adom USB - CDC serial sniffer` | `CDC serial sniffer` | bare descriptor — hides the family |+| `Adom USB - RP2040 persona pack` | `adom-usb-stub-rp2040` | slug used as the title |+| `Adom Desktop - KiCad Bridge` | `Adom Desktop: KiCad Bridge` | colon, not `" - "` |+| `Adom Desktop - Bridge SDK` | `Adom Desktop — Bridge SDK` | em-dash, not ASCII hyphen |+| `Adom Desktop - Altium Bridge` | `adom-desktop-altium-bridge` | slug as title (a real offender) |+| `Adom Desktop - Demo` | `Demo` | orphan — doesn't announce the family at all |+| `Adom Desktop - Bridges Registry` | `Adom Desktop Bridges Registry` | no `" - "` separator |++(The ❌ column is drawn from real inconsistencies already on the wiki — colons,+em-dashes, slug-as-title, and orphan titles all exist today. Match the ✅ column.)++### The slug — dashes, no spaces  - **Slug**: `<parent>-<descriptor>` — `adom-usb-sniffer-cdc`,-  `adom-usb-stub-rp2040`. Dash separators; **never a colon** (illegal in slugs).-- **Title** (the human name shown on cards/search/screensaver — the one that-  matters): **MUST lead with the parent name**, plain ASCII hyphen with spaces —-  `Adom USB - CDC serial sniffer`. **Never an em-dash (—)**; keep it identical to-  siblings. A bare title like "CDC serial sniffer" hides the family.+  `adom-desktop-kicad-bridge`. Dash separators, lowercase, **never a colon**+  (illegal in slugs) and never spaces. The slug is NOT the title — convert it to+  the spaced, Title-Cased form above for the `title` field.++### The other family markers+ - **Family tag/keyword**: include `<parent>-plugin` (e.g. `adom-usb-plugin`) so   the anchor's discovery and `<parent> plugins search` find the child. - **Hero billboard**: carry a small family chip (e.g. `ADOM-USB · SNIFFER`) so the   relationship survives even when only the image shows. Build it per **wiki-hero**. +After publishing a child, `GET /api/v1/pages/<child-slug>` and eyeball the+`title` — it must read `<Parent> - <descriptor>` with the spaced ASCII hyphen,+identical in style to its siblings.+ ## 2. The anchor page is a registry  The anchor (e.g. `adom-usb`) documents the family and keeps a **table of known

@@ -36,6 +36,14 @@ dots.) For Family children, also carry the family chip (e.g. `ADOM-USB · SNIFFE > TODO (pack maintainers): we depend on `adom-wiki-hero-image` rather than folding > its content in. Revisit whether to inline it here later. +## The hero goes in page.json ONLY — never in the README body++The hero is set via `page.json` → `hero.path` and the wiki renders it at the top+of the page for you. **Do NOT also embed it in the README** (`![...](.../hero.png)`)+— that shows the human the same image twice. README images are *other*+screenshots. This pairs with the unlink bug below: the hero's home is `page.json`,+full stop. → **wiki-readme**.+ ## ⚠️ The recurring bug: the hero gets UNLINKED on publish  This is the #1 hero problem and it looks like the image was deleted — **it

@@ -66,6 +66,14 @@ companion.    Reuse `sessionId:"wiki"` / `profile:"wiki"` every time so the login persists;    `browser_navigate` an already-open window rather than spawning new ones. +## Never show the hero twice++The page header renders the hero from `page.json` automatically. **Do NOT also+embed the hero image in the README body** — the human would see the same image+twice, back to back. It's the most common README mistake on the wiki. Inline+README images must be *other* screenshots/diagrams. Before publishing, grep the+README for the hero filename and delete any line that references it. → **wiki-readme**.+ ## Other gotchas  - **Cloudflare WAF blocks Python urllib/requests without a `User-Agent`** →@@ -87,5 +95,6 @@ companion. - [ ] `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+- [ ] README does NOT embed the hero image (page header shows it already) - [ ] Opened in pup + screenshot read: README renders, Files tab full, hero shows - [ ] `adompkg info <slug>` shows the right version + dependencies

@@ -33,23 +33,42 @@ There is also a **private readme** for pages whose git source is private but who releases are public — so the public still gets docs without seeing the source. That's a visibility concern → see **wiki-visibility**. +## ⛔ THE #1 README RULE: NEVER embed the hero image in the README body++**The wiki renders the hero at the top of the page automatically** (from+`page.json` → `hero.path`). If you ALSO drop the hero image into the README body,+the human sees the **same image twice**, back to back — which is redundant,+annoying, and reads as careless. **Do not `![...](.../screenshots/hero.png)` in the+README. Ever.** This is the single most common README mistake on the wiki, so it+goes first.++- The hero lives in **`page.json` only** (see **wiki-hero**). The README never+  references it.+- Inline images in the README must be **OTHER** images — different screenshots,+  states, diagrams — never the hero, and never a near-duplicate of it.+- Before publishing, grep the README: if it points at `hero.png` (or whatever the+  `page.json` hero path is), delete that line.+ ## 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.+**Never publish a text-only README.** Any page with a UI needs inline+screenshots and an embedded live demo. But the **hero** is supplied via+`page.json` and shown at the top of the page for you — the README's images are+the *additional* ones (different views/states/diagrams). 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**).+2. **(The page header already shows the hero — do NOT embed it here.)** Go+   straight from the description into content. Set the hero in `page.json`, not+   the README (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+6. **Screenshots** — 2–4 inline images, each with a caption heading. These are+   **other** images, NOT the hero (see the #1 rule above). 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@@ -59,10 +78,11 @@ install.  ## Embeds -Inline image from the repo (blob endpoint):+Inline image from the repo (blob endpoint) — point at a NON-hero screenshot+(`feature-1.png`, a diagram, a different state), never `hero.png`:  ```markdown-![Dashboard](/blob/<type>/<slug>/screenshots/hero.png)+![Results view](/blob/<type>/<slug>/screenshots/feature-1.png) ```  Self-contained demo (bake sample data into the HTML, no fetch/WebSocket):