Adom Wiki Skill Pack

@@ -1,13 +1,13 @@ # Adom Wiki Skill Pack  **One install, 15 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+pages, plus a write-up of the wiki repo archetypes that have emerged from real use.**  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+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.@@ -15,16 +15,16 @@ 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+> 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.+> user is structuring repos, so the platform can meet those patterns.  ## Install  ```bash-adompkg install adom-wiki-skillpack+adom-wiki pkg install adom-wiki-skillpack ```  This drops the main `adom-wiki-skillpack` skill plus 14 sub-skills onto your@@ -39,11 +39,11 @@ 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 |+| 2 | **`adom-wiki pkg`** | 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 |-| 6 | **Discovery** | npm search / app-store surfacing | how a page/skill gets found — search, `/discover` triggers, local skill matching |+| 6 | **Discovery** | npm search / app-store surfacing | how a page/skill gets found: search, `/discover` triggers, local skill matching |  Plus a **presentation** layer (`README.md` or a custom `readme.html`, and a separate **private readme** for proprietary pages). The **scoring/trending** signals (stars /@@ -52,13 +52,13 @@ high-fives / installs) feed Discovery's ranking. > **Discovery is a first-class pillar, and it's the least-finished one.** Layer 1 > (local installed-skill matching) works; Layer 2 (the registry `/discover` > endpoint) does not yet match declared `discovery_triggers`. The `wiki-discovery`-> skill carries the current state + a TODO list of what discovery still needs —+> skill carries the current state + a TODO list of what discovery still needs , > see it (and finding #3 in our Colby feedback).  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+two independent storage layers.** `adom-wiki pkg 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.+Doing one leaves the page half-broken, the root of most incidents.  ## The repo archetypes (emerging from real use) @@ -67,33 +67,33 @@ into a deliberate choice.  ![The three Adom Wiki repo archetypes](/blob/skill/adom-wiki-skillpack/screenshots/archetypes.png) -### 1. Page — one page = one thing+### 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`,+- **Open-source Page**, source public + installable. _e.g._ `chip-fetcher`,   `adom-usb`. MIT, contributions welcome.-- **Closed-source Page** — source **private**, releases/adompkg **public**, so+- **Closed-source Page**, source **private**, releases/`adom-wiki pkg` **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+> 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+### 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+together by a single `adom-wiki pkg 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.+- **This very repo is a Skillpack**, it dogfoods its own archetype. -### 3. Family — an anchor page + separately-published children+### 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:@@ -103,16 +103,16 @@ convention rather than living in one repo:   **breadcrumbs** linking children back to the anchor. - _e.g._ `adom-desktop` (+ bridges), `adom-usb` (+ sniffer/firmware plugins). -### Skillpack vs Family — the decision rule+### 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+- **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+**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@@ -125,14 +125,14 @@ each part need its own lifecycle and maybe its own author?_ Yes → Family. 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`+2. **`adom-wiki pkg 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+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+5. **Verify with your eyes**, open the live page in pup and screenshot it before    calling any wiki edit done.  ## Skills in this pack@@ -140,19 +140,19 @@ The pack encodes these; they're worth stating here too: | 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 — six tools in one, and the two storage layers. |-| **wiki-api** | The REST API + `adompkg` CLI and the publish workflow. |+| **wiki-anatomy** | The mental model: six tools in one, and the two storage layers. |+| **wiki-api** | The REST API + ``adom-wiki pkg`` 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-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-component** | Publish a component — chip / molecule / board; the tabbed chip CAD-hub README (symbol, footprint, 3D, pins, specs, sourcing, tape & reel). |+| **wiki-component** | Publish a component: chip / molecule / board; the tabbed chip CAD-hub README (symbol, footprint, 3D, pins, specs, sourcing, tape & reel). | | **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-discovery** | How pages get found — the two layers, current state, and the TODO list _(Layer 1 live; `/discover` partial)_. |+| **wiki-discovery** | How pages get found: the two layers, current state, and the TODO list _(Layer 1 live; `/discover` partial)_. | | **wiki-scoring** | Stars / high-fives / installs / trending _(stars live; rest partial)_. |  ## Talk to the AI@@ -169,16 +169,16 @@ The pack encodes these; they're worth stating here too:  | 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`. |+| **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 `adom-wiki pkg install`. | -Companion tools (not hard dependencies): `adompkg` itself (the package manager),+Companion tools (not hard dependencies): ``adom-wiki pkg`` 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`.+of that knowledge plus the archetype taxonomy, same model as `adom-ui-design`. Update gallia first, then refresh this page.  ## License

@@ -2,18 +2,18 @@ name: adom-wiki-skillpack user-invocable: true description: >--  The Adom Wiki Skill Pack — the entry point for working with the Adom Wiki+  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 six tools in one (git host + adompkg package manager ++  wiki page. The wiki is six tools in one (git host + wiki package manager (`adom-wiki pkg`) +   release database + discussion forum + pull requests + discovery), and three repo   archetypes have emerged from real use: Page, Skillpack, and Family. This pack   routes to 16 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+  breaking. Trigger words: adompkg (deprecated old name), 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 discovery, page not surfacing, wiki scoring, trending, high five,-  adompkg publish, publish a chip, component page, chip page, molecule page,+  adom-wiki pkg publish, publish a chip, component page, chip page, molecule page,   tape and reel, pin 1 orientation. --- @@ -23,21 +23,23 @@ 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,+archetypes that have emerged from heavy real-world use, update gallia first, then refresh this page. +> **`adompkg` is the deprecated old name of the package manager.** It is dead; do not run it. Every old `adompkg <verb>` maps to `adom-wiki pkg|page|repo|release <verb>` (e.g. `adompkg publish` -> `adom-wiki pkg publish`, `adompkg install` -> `adom-wiki pkg install`). If a doc or a user says adompkg, translate and continue.+ ## The wiki is six tools in one  It feels like a wiki, but it's a fusion of six 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.-6. **Discovery** — how a page/skill gets found (search, `/discover` triggers, local-   skill matching); a first-class pillar — fed by the scoring/trending signals.+1. **Git host**, every page is a real git repo (Files tab, commits, contributors).+2. **`adom-wiki pkg`**, an npm-style package manager: dependency maps, `adom-wiki pkg 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.+6. **Discovery**, how a page/skill gets found (search, `/discover` triggers, local+   skill matching); a first-class pillar, fed by the scoring/trending signals.  Plus a **presentation layer** (a plain `README.md`, or a custom `readme.html`, plus a separate **private readme** for proprietary-source pages). Full model →@@ -60,21 +62,21 @@ together; **Family** when children have independent owners or update cadences These are the mistakes that recur. They each have a dedicated skill, but they're important enough to state up front: -> ⛔ **NEVER use em-dashes (—) in ANY wiki content** (John, 2026-06-26): page titles, briefs,+> ⛔ **NEVER use em-dashes (,) in ANY wiki content** (John, 2026-06-26): page titles, briefs, > descriptions, README bodies, hero text, sample prompts, changelogs, even commit messages. Use a > comma, a regular hyphen `-`, or a colon `:`. The en-dash `–` is banned too. ASCII punctuation only.  1. **Write BOTH storage layers, every publish.** The git repo (Files/README) and-   the package registry (tarball/`adompkg install`) are independent. Do only one+   the package registry (tarball/`adom-wiki pkg 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`+2. **`adom-wiki pkg 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:+   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 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+   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**.@@ -88,21 +90,21 @@ important enough to state up front: | Skill | Use it for | |---|---| | **wiki-anatomy** | The mental model: the six tools in one, and how the layers relate. |-| **wiki-api** | The REST API + `adompkg` CLI, the two storage layers, the publish workflow. |+| **wiki-api** | The REST API + ``adom-wiki pkg`` 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-readme-html** | Build a custom `readme.html` — sandbox limits, shadowing, self-containment, theming, verify loop. |+| **wiki-readme** | How to make a great README: `README.md` vs `readme.html`, sections, embeds, images. |+| **wiki-readme-html** | Build a custom `readme.html`: sandbox limits, shadowing, self-containment, theming, verify loop. | | **wiki-sub-readme** | Make a sub-readme: a 2nd doc in the page repo, linked from the README. The repo-push / relative-link / image-path gotchas. | | **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-component** | Publish a component page — chip / molecule / board; the tabbed chip CAD-hub README. |+| **wiki-component** | Publish a component page: chip / molecule / board; the tabbed chip CAD-hub README. | | **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-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-discovery** | How pages get found — the two layers, current state, and the TODO list. |-| **wiki-scoring** | Stars / high-fives / installs / trending — what's tracked and how to earn it. |+| **wiki-discovery** | How pages get found: the two layers, current state, and the TODO list. |+| **wiki-scoring** | Stars / high-fives / installs / trending: what's tracked and how to earn it. |  ## Talk to the AI 

@@ -2,9 +2,9 @@ name: wiki-anatomy description: >-   The mental model of the Adom Wiki (wiki.adom.inc): it is five familiar tools-  fused into one product keyed off a single slug per page — a git host, the-  adompkg package manager, a release database, a discussion forum, pull requests,-  and discovery — plus a presentation layer. Read this to understand WHAT the wiki+  fused into one product keyed off a single slug per page, a git host, the+  wiki package manager (`adom-wiki pkg`), a release database, a discussion forum, pull requests,+  and discovery, plus a presentation layer. Read this to understand WHAT the wiki   is before learning HOW to drive it. Trigger words: what is the adom wiki, how   does the wiki work, wiki architecture, wiki mental model, git plus npm plus   releases, wiki page is a repo, two storage layers, why both git and registry,@@ -13,36 +13,36 @@ description: >-  Parent skill: **adom-wiki-skillpack** -# What the Adom Wiki actually is+# What the Adom Wiki is  The Adom Wiki looks like a wiki, but it is **six tools you already know, fused into one**, all addressed by a single `slug` per page. Understanding this is the-prerequisite for everything else — most publishing mistakes come from treating-it as one tool when it is really several stacked together.+prerequisite for everything else, most publishing mistakes come from treating+it as one tool when it is several stacked together.  ## The six tools  1. **A git host (per page).** Every page owns a real git repo. The Files tab,    README rendering, commit log, and contributors all read from it. You push to-   it via `POST /api/v1/pages/:slug/files` — that call *is* a `git commit`.+   it via `POST /api/v1/pages/:slug/files`, that call *is* a `git commit`. -2. **adompkg — an npm-style package manager.** Alongside the git repo, each page+2. **`adom-wiki pkg`, an npm-style package manager.** Alongside the git repo, each page    can carry a package: versioned tarballs, a `package.json` manifest, a-   `dependencies` map, and dist-tags. `adompkg install <slug>` resolves and-   installs dependencies transitively, just like `npm i`. `adompkg update`+   `dependencies` map, and dist-tags. `adom-wiki pkg install <slug>` resolves and+   installs dependencies transitively, just like `npm i`. `adom-wiki pkg update`    upgrades everything installed.  3. **A release database.** Like GitHub Releases: a page can attach versioned,-   downloadable assets (per-platform binaries) via `adompkg release upload`. This+   downloadable assets (per-platform binaries) via `adom-wiki release upload`. This    is how closed-source apps ship a compiled binary without shipping source.  4. **A discussion forum.** Each page has discussions + threaded replies, the-   GitHub-Issues equivalent — for questions, bug reports, and feature requests.+   GitHub-Issues equivalent, for questions, bug reports, and feature requests.  5. **Pull requests.** Community members propose edits to a page's repo; the owner    reviews and merges. The contribution path for a wiki you don't own. -6. **Discovery.** How a page/skill gets FOUND — search, the `/discover` endpoint's+6. **Discovery.** How a page/skill gets FOUND, search, the `/discover` endpoint's    trigger matching, and local installed-skill matching. A first-class pillar: a    page that can't be discovered may as well not exist. The **scoring/trending**    signals (stars, high-fives, installs) feed discovery's ranking. See@@ -64,15 +64,31 @@ it as one tool when it is really several stacked together.   │  Files tab, README,  │        │  tarballs, versions,      │   │  commits, page.json  │        │  dependencies, dist-tags  │   └─────────────────────┘        └──────────────────────────┘-   written by POST /files          written by `adompkg publish`+   written by POST /files          written by `adom-wiki pkg publish` ``` -They are **not** synchronized. `adompkg publish` does **not** push your source to+They are **not** synchronized. `adom-wiki pkg publish` does **not** push your source to the git repo, and pushing files does **not** create a tarball. A correct publish writes **both**. Doing only one leaves the page half-broken (placeholder Files-tab, or a README that won't install). This is the single most common failure —+tab, or a README that won't install). This is the single most common failure , the **wiki-api** and **wiki-publish-safely** skills exist to make you do both, in the right order.  Same split as the rest of the world: GitHub (repo) + npm (registry). The wiki just puts both behind one slug.++## ⛔ Two storage layers: the files blob store vs the git page repo++A page has TWO stores, and they are NOT synced:++- the **files blob API** (`POST /api/v1/pages/<slug>/files`), and+- the **git page repo**, which is what the **Files tab renders** and what `adom-wiki repo *` reads+  and writes.++A raw `curl POST .../files` can return **200 while the Files tab keeps serving the OLD content**,+because the git repo was never updated. This burned a real session: nine docs "published" with 200s,+all stale on the page.++**Rule: page content (README, docs, images) goes through `adom-wiki repo push --files ...`,** then+verify with `adom-wiki repo show <ref> <path>`. Use the raw files API only for things a tool+explicitly reads from it (e.g. a bridge manifest an installer fetches by URL).

@@ -1,57 +1,57 @@ --- name: wiki-api description: >--  How to drive the Adom Wiki (wiki.adom.inc) programmatically: the adompkg CLI,+  How to drive the Adom Wiki (wiki.adom.inc) programmatically: the `adom-wiki pkg` 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+  create-page, push-files, or publish call. Trigger words: wiki api, `adom-wiki pkg`,+  adom-wiki pkg publish, adom-wiki pkg 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.+  token, adom-wiki auth, two storage layers, wiki tarball. ---  Parent skill: **adom-wiki-skillpack** -# Driving the Adom Wiki: adompkg + the REST API+# Driving the Adom Wiki: `adom-wiki pkg` + 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+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+bash <(curl -fsSL https://wiki.adom.inc/static/bootstrap.sh)   # if `adom-wiki pkg` missing export PATH="$HOME/.local/bin:$PATH"-adompkg login --token "$(cat /var/run/adom/api-key)"-adompkg whoami+adom-wiki auth "$(cat /var/run/adom/api-key)"+adom-wiki whoami # For curl: -H "Authorization: Bearer $(cat /var/run/adom/api-key)" ``` -## adompkg CLI (the bits you use most)+## `adom-wiki pkg` 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>`).+| `adom-wiki pkg install <slug>[@ver]` | Install a package (+ its dependencies) |+| `adom-wiki pkg info <slug>` / `view` | Manifest / full metadata + versions |+| `adom-wiki pkg search <query>` | Search the registry |+| `adom-wiki pkg list` / `outdated` / `update` | Manage installed packages |+| `adom-wiki pkg version <patch\|minor\|major>` | Bump version in package.json |+| `adom-wiki pkg publish [--org adom] [-y]` | Build + upload the tarball to the registry |+| `adom-wiki release upload <slug>@<ver> <file> --platform <os>` | Attach a downloadable binary |++Namespace: `adom-wiki pkg 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 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`,+**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.+**Step 2, create the page (first publish only).** Inits the git repo.  ```bash WIKI="https://wiki.adom.inc"@@ -61,16 +61,16 @@ curl -s -X POST "$WIKI/api/v1/pages" \   -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.)+**Step 3, `adom-wiki pkg 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+cd /path/to/my-tool && adom-wiki pkg 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+**Step 4, push ALL source files to the git repo, with a complete `page.json` LAST.**+This is the equivalent of `git push`. **Critical:** `adom-wiki pkg 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**. @@ -90,11 +90,11 @@ for root, dirs, fnames in os.walk(project_dir):             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+        headers={"Authorization": f"Bearer {token}", "User-Agent": "`adom-wiki pkg`/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**).+**Step 5, verify in pup** (non-negotiable; see **wiki-publish-safely**).  ## Encoding rule (memorize) @@ -113,6 +113,17 @@ Base64-encode a text file and the README renders as gibberish. - 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+`User-Agent`** (use ``adom-wiki pkg`/2.1.0`; curl is fine), and **FTS search chokes on hyphens** (`chip-fetcher` → "no such column: fetcher"). Full pitfall list → **wiki-publish-safely**.++## Which manifest a publish reads (PAGE_JSON_IGNORED)++`adom-wiki pkg publish` reads **`package.json` ONLY**. Discovery fields placed in `page.json`+(`discovery_triggers`, `discovery_pitch`, `sample_prompts`, `description`) do NOTHING at publish+time; the linter says so: `PAGE_JSON_IGNORED ... Only the package.json manifest counts.`+`page.json` is read on **page-repo pushes**, not package publishes. Keep the discovery fields in+`package.json`; keep them mirrored in `page.json` only if the page layer also uses them.++And for page files themselves: `adom-wiki repo push` is the canonical write path (see wiki-anatomy,+"Two storage layers") - a 200 from the raw files POST does not mean the Files tab updated.

@@ -1,7 +1,7 @@ --- name: wiki-component description: >--  How to publish a "component" page to the Adom Wiki — a single chip, a molecule,+  How to publish a "component" page to the Adom Wiki, a single chip, a molecule,   or a PCB that isn't a molecule. `component` is a real wiki page TYPE (peer to   app/skill) with NATIVE rendering: set a `component` block in page.json + push the   CAD files and the wiki auto-renders interactive symbol + footprint + 3D viewers,@@ -21,33 +21,33 @@ Parent skill: **adom-wiki-skillpack**  # Publishing a component (chip / molecule / PCB) -`component` is a first-class **wiki page type** (alongside `app` and `skill` — see+`component` is a first-class **wiki page type** (alongside `app` and `skill`, see **wiki-api**). Structurally a component is usually the **Page** archetype; chip families use the **Family** archetype (see **wiki-repo-styles**), e.g. an `stm32f4` anchor with `stm32f405` / `stm32f407` children.  Three kinds, by what they are: -1. **Chip** — a single part / IC (MCU, MOSFET, sensor, passive, connector). The+1. **Chip**, a single part / IC (MCU, MOSFET, sensor, passive, connector). The    rich case; most of this skill.-2. **Molecule** — a reusable sub-circuit / breakout published via `adom-molecule`.-3. **PCB (non-molecule)** — a finished board not meant to be reused as a part.+2. **Molecule**, a reusable sub-circuit / breakout published via `adom-molecule`.+3. **PCB (non-molecule)**, a finished board not meant to be reused as a part.  > **Read [adom-ui-design](https://wiki.adom.inc/john/adom-ui-design) BEFORE you build > the page UI.** A component page is a real Adom interface and must obey it: > canonical color tokens, brand fonts (Familjen Grotesk / Satoshi / JetBrains Mono,-> never the system stack), **monochrome line-icon SVGs — NO emoji, anywhere**, **no+> never the system stack), **monochrome line-icon SVGs, NO emoji, anywhere**, **no > em-dashes or en-dashes**, a 44px three-zone header, body-appended tooltips, 8/12/999 > radii. Lint with `adom-ui-linter`. This was learned the hard way: an emoji- and > em-dash-ridden page reads as AI slop and engineers stop trusting it.  --- -# How the page actually renders: two layers+# How the page renders: two layers  There are two very different rendering paths. Know which you're using. -## Layer A — the wiki's NATIVE component rendering (the working path today)+## Layer A: the wiki's NATIVE component rendering (the working path today)  This is what you get for free, and it is good. Set a **`component` block in page.json** and push the CAD files; the wiki auto-renders:@@ -66,7 +66,7 @@ The `component` block:  ```json "component": {-  "mpn": "nRF52840-CKAA",            // REQUIRED — POST /pages rejects a component without it+  "mpn": "nRF52840-CKAA",            // REQUIRED, POST /pages rejects a component without it   "manufacturer": "Nordic Semiconductor",   "package": "aQFN-73 (7x7x0.85 mm, 0.5 mm pitch)",   "pin_count": 73,@@ -83,23 +83,23 @@ Parts auto-detect by extension if you omit `parts` (first `.kicad_sym`/`.kicad_m `.glb`/`.step`/`.pdf` in the tree), but **declare them** so the right datasheet PDF wins over the RoHS cert, etc. -## Layer B — the README / custom HTML (heavily constrained)+## Layer B: the README / custom HTML (heavily constrained)  The Overview README is rendered through `marked` + **`sanitize-html` with a strict allowlist**. It **strips `<style>`, `<script>`, `<details>`, `<iframe>`, and even `style=` attributes.** So you **cannot** build a tabbed/accordion/toolbar custom-layout in the README — inline styles vanish, accordions collapse to nothing, scripts+layout in the README, inline styles vanish, accordions collapse to nothing, scripts never run. (Confirmed live: a hand-built toolbar rendered as plain text links.) README HTML that survives: `h1-6, p, a, ul/ol/li, blockquote, pre, code, em, strong, table/tr/th/td, span, div, img`, with `class` on a few. Use the README for prose +-images + tables that complement the native viewers — not for a custom app shell.+images + tables that complement the native viewers, not for a custom app shell.  **To get the full custom layout** (tabs, accordions, panels, the Open-in toolbar, provenance lightbox) you have two options:-1. **Ship a `readme.html`** (LIVE — verified 2026-07-15): put a self-contained+1. **Ship a `readme.html`** (LIVE, verified 2026-07-15): put a self-contained    `readme.html` in the publish tree and `pkg publish`. The wiki renders it as the    page body in a sandboxed iframe (`sandbox="allow-scripts allow-downloads"`,-   served unsanitized from `/readme/<owner>/<type>/<slug>?variant=public`) —+   served unsanitized from `/readme/<owner>/<type>/<slug>?variant=public`) ,    inline CSS AND `<script>` both work, so the full tabbed/accordion/toolbar/    lightbox layout is the real page now. It fully shadows README.md on the page.    No `allow-same-origin`: self-contain everything (base64-inline fonts/images or@@ -142,7 +142,7 @@ and **embed the live interactive viewers**.  | Artifact / capability | Tool | Command → output (verified) | |---|---|---|-| STEP + KiCad sym/mod + Altium IntLib + Fusion .lbr + datasheet + stock | **chip-fetcher** | `chip-fetcher fetch <MPN>` → `library/<MPN>/` (⚠ may save a *product brief*, not the full datasheet — verify it has the pinout, see Provenance) |+| STEP + KiCad sym/mod + Altium IntLib + Fusion .lbr + datasheet + stock | **chip-fetcher** | `chip-fetcher fetch <MPN>` → `library/<MPN>/` (⚠ may save a *product brief*, not the full datasheet: verify it has the pinout, see Provenance) | | Pin descriptions + symbol/footprint extraction + **per-pin datasheet page citations** | **ds2sf** | `ds2sf extract <chip-dir> --pdf <full-datasheet.pdf>` → `*-symbol.extracted.json`, `*-footprint.extracted.json`, `*-provenance.json`. **Refuses a PDF with no pinout** (won't fabricate). | | Interactive **SymView** | **adom-symbol** (service :8781 / wiki) | wiki route `/viewer/symbol/component/<slug>` (embed). CLI `adom-symbol render --file x.kicad_sym --out x.svg` for a static SVG. | | Interactive **FpView** (layer toggles + solder blobs) | **adom-footprint** (service :8782 / wiki) | wiki route `/viewer/footprint/component/<slug>` (embed). CLI `render` for SVG. |@@ -151,11 +151,11 @@ and **embed the live interactive viewers**. | pin-1 + seat-plane validation + pin-1-baked GLB | **adom-chipfit** | `adom-chipfit check --footprint x.kicad_mod --glb x.glb` | | symbol/footprint SVGs + 3D iso PNGs + manifest | **chip-thumbnailer** | `chip-thumbnailer once <MPN>` | -### Generate the embeddable viewers FROM the apps — use `embed`+### Generate the embeddable viewers FROM the apps: use `embed`  adom-symbol and adom-footprint ship a first-class **`embed`** command that exports a **self-contained, interactive HTML package** (pan/zoom + pin info panel; pads +-courtyard + layer toggles) built for an iframe — no server, no external assets, one+courtyard + layer toggles) built for an iframe, no server, no external assets, one portable `.html`. **This is the canonical way to get the symbol/footprint viewers.**  ```bash@@ -166,10 +166,10 @@ adom-footprint embed --file <mpn>.kicad_mod --out fpview.html   # interactive Fp Then embed each same-origin: `<iframe src="symview.html">` / `<iframe src="fpview.html">`. The footprint export includes a layers panel with an **"InstaPCB paste dots" toggle** (the 300µm jetted-paste positions, off by default) plus Copper / Assembly /-Courtyard / Paste apertures — so the solder-paste view is built in. Pin 1 is marked.+Courtyard / Paste apertures, so the solder-paste view is built in. Pin 1 is marked.  > Use the freshly **built** binaries (`<app>/target/release/adom-symbol|adom-footprint`)-> — a stale `~/.local/bin` copy may predate `embed` (or be a stub). `embed` renders+>, a stale `~/.local/bin` copy may predate `embed` (or be a stub). `embed` renders > via service-kicad, which must be reachable.  Two fallbacks, only if `embed` isn't available:@@ -177,7 +177,7 @@ Two fallbacks, only if `embed` isn't available:   (pass a pre-rendered `svgContent` to skip service-kicad), or - once the page is **published**, the wiki hosts the same viewer at   `/viewer/{symbol,footprint,3d}/component/<slug>?embed=1` (the wiki runs these-  generators server-side) — fine for the live page.+  generators server-side), fine for the live page.  The shipped `component-page-generator/` does this: `mkviewers.sh` runs `adom-symbol embed` / `adom-footprint embed`; the page embeds `symview.html` /@@ -185,41 +185,41 @@ The shipped `component-page-generator/` does this: `mkviewers.sh` runs  ## 1. What goes in each section -- **Overview** — MPN, manufacturer, one-liner, lifecycle badge (Active / NRND /+- **Overview**, MPN, manufacturer, one-liner, lifecycle badge (Active / NRND /   Obsolete), package, pin count, voltage, datasheet link. (Hero shows in the page-  header — never re-embed it, **wiki-hero**.)-- **Symbol** — embed the live SymView iframe. (Static SVG fallback below it.)-- **Footprint** — embed the live FpView iframe; the solder/paste layer is a real+  header, never re-embed it, **wiki-hero**.)+- **Symbol**, embed the live SymView iframe. (Static SVG fallback below it.)+- **Footprint**, embed the live FpView iframe; the solder/paste layer is a real   toggle there. Note pin-1 = square pad, top-left. Leaded vs lead-free + bridging   feedback via Discussions.-- **3D** — embed the live Babylon viewer; show the chipfit verdict (pin-1, seat Δz).-- **Pin map** — pin list with descriptions (ds2sf per-pin, grouped POWER/IO/…) and+- **3D**, embed the live Babylon viewer; show the chipfit verdict (pin-1, seat Δz).+- **Pin map**, pin list with descriptions (ds2sf per-pin, grouped POWER/IO/…) and   symbol-pin ↔ pad map. **Cite the datasheet page per pin** (Provenance).-- **Specifications** — **class-aware** (render the block that fits): MCU (core,+- **Specifications**, **class-aware** (render the block that fits): MCU (core,   clock, flash, RAM, GPIO, peripherals, V, temp); MOSFET (channel, Vds, Id, Rds(on),   Vgs(th), Qg, Ciss, Pd); passive (value, tol, V, dielectric/temp-co, EIA size);   op-amp (channels, GBW, slew, Vos, Ib, V±).-- **Sourcing** — price-break table, stock, lifecycle, RoHS, MSL (1–6 + floor life),+- **Sourcing**, price-break table, stock, lifecycle, RoHS, MSL (1–6 + floor life),   Mouser + DigiKey buy links. Date every snapshot.-- **Tape & reel** — packaging (CT/T&R/tube/tray), reel qty, MSL, EIA-481 pin-1+- **Tape & reel**, packaging (CT/T&R/tube/tray), reel qty, MSL, EIA-481 pin-1   quadrant. Authoritative orientation = the manufacturer's tape-and-reel drawing.-- **Manufacturer & resources** — the mfr product page + **every** supplemental doc+- **Manufacturer & resources**, the mfr product page + **every** supplemental doc   (datasheet, errata, PCN, RoHS cert, app notes, reference designs, SDK, dev kits,   CAD source). Don't just link the datasheet.-- **Variants** — symbol/footprint/3D/package variants, each with downloads.-- **Related** — molecules using this chip, family siblings (Family anchor), alternates.-- **CAD downloads** — per-tool: KiCad (`.kicad_sym`+`.kicad_mod`+STEP+WRL), Fusion/+- **Variants**, symbol/footprint/3D/package variants, each with downloads.+- **Related**, molecules using this chip, family siblings (Family anchor), alternates.+- **CAD downloads**, per-tool: KiCad (`.kicad_sym`+`.kicad_mod`+STEP+WRL), Fusion/   EAGLE (`.lbr`), Altium (`.IntLib`), OrCAD (`.olb`+`.dra`/`.psm`/`.pad`), universal   STEP + GLB. (The native grid renders this automatically.)-- **Provenance** — see its own section below. Mandatory.-- **Open in** — see its own section below.+- **Provenance**, see its own section below. Mandatory.+- **Open in**, see its own section below.  ## 2. Pin-1 / pick-and-place orientation  The footprint pin-1, the 3D pin-1 corner, and the placement **zero orientation** must agree or the part lands rotated 90/180°. IPC-7351: ICs pin-1 **top-left**; polarized two-terminal pin-1 (+) **left**; positive rotation CCW. ⚠ IEC 61188-7 uses-**bottom-left** — call out which a library follows. Markers: SOIC dot/notch, QFP/QFN+**bottom-left**, call out which a library follows. Markers: SOIC dot/notch, QFP/QFN chamfer, BGA A1 corner, footprint pin-1 = square pad. Polarity gotcha: SMD tantalum stripe = +, SMD aluminum electrolytic stripe = −. Validate with **adom-chipfit**. @@ -231,7 +231,7 @@ Quadrant 1), MSL 1→6. Defer to the mfr tape-and-reel drawing for orientation.  --- -# Provenance — prove every datapoint+# Provenance: prove every datapoint  **Engineers don't trust AI yet, so prove the backing data.** Every datapoint on the page must trace to a source, and the strongest claims must show the evidence.@@ -249,7 +249,7 @@ page must trace to a source, and the strongest claims must show the evidence.   Specs and Pin-map sections. - **ds2sf refusing a brief is the feature, not a bug.** It will not invent pin data   from a PDF that lacks the pinout. ⚠ **chip-fetcher sometimes saves a 2-page product-  brief instead of the full Product Specification** (seen on nRF52840-CKAA — both+  brief instead of the full Product Specification** (seen on nRF52840-CKAA, both   "datasheet" files were the same 2-page brief). Always verify the datasheet has the   pinout before relying on it; if ds2sf refuses, fetch the full datasheet (mfr site /   desktop browser) and re-run.@@ -267,9 +267,9 @@ Let the user *act* on the part, not just read it. | Buy (Mouser / DigiKey) | `distributor_links` | ✅ | | adom-symbol / footprint / lbr / step / chipfit / chipsmith / chip-fetcher / service-kicad | container CLI / services | ❌ no page→container bridge → **paste-to-Claude prompt** | | KiCad / Fusion on desktop | `adom-desktop kicad_open_* / fusion_open_*` | ❌ no page→desktop bridge → **paste-to-Claude prompt** |-| Altium / OrCAD on desktop | — | ❌ no adom-desktop verb → download + open manually |+| Altium / OrCAD on desktop |: | ❌ no adom-desktop verb → download + open manually | | Send library → Downloads + open folder | `adom-desktop send_files` + reveal | ❌ paste-to-Claude prompt |-| "Component Ocean" | — | not an Adom tool (a distributor); no open verb |+| "Component Ocean" |: | not an Adom tool (a distributor); no open verb |  Why prompts: a wiki page can't run JS (README sanitized) and there's no page→desktop bridge. So the live `/viewer/...` routes are real link/embed buttons; everything else@@ -298,17 +298,17 @@ downloads + BOM + assembly notes. Page archetype. 2. Create the page: `POST /api/v1/pages` with `type:"component"` **and `component.mpn`    in the body** (it's rejected otherwise). 3. Push all files (text plain, binaries base64, `User-Agent` header) in **<4MB-   batches** — GLB/STEP/PDF are big and a too-large batch returns **413**. Push a+   batches**, GLB/STEP/PDF are big and a too-large batch returns **413**. Push a    **complete `page.json` LAST** so the hero/title stay linked (**wiki-hero**,-   **wiki-publish-safely**). (No `adompkg publish` tarball is needed for a component.)+   **wiki-publish-safely**). (No `adom-wiki pkg publish` tarball is needed for a component.) 4. **Verify in pup**, and check `/viewer/...` routes return interactive content. 5. For chip families, apply the Family naming/title rules (**wiki-family**). -## 📋 Platform TODO (for Colby / adom-desktop) — fold these into build asks+## 📋 Platform TODO (for Colby / adom-desktop): fold these into build asks  - ~~**Custom-HTML page mode**~~ **SHIPPED** (verified 2026-07-15): a repo   `readme.html` renders as the page body in a sandboxed iframe-  (`allow-scripts allow-downloads`, unsanitized) — see **wiki-readme**. Remaining+  (`allow-scripts allow-downloads`, unsanitized), see **wiki-readme**. Remaining   gap: no `allow-same-origin`, so embedded viewers can't fetch the wiki API from   inside the readme (next item). - **Editable embedded viewers**: let the embedded SymView/FpView tweak + regenerate@@ -320,9 +320,9 @@ downloads + BOM + assembly notes. Page archetype. - **Live price/stock** widgets (vs dated `stock.json`); **leaded/lead-free paste   switch + bridging heatmap** in FpView; **auto "molecules using this chip" backlink   index**; a **per-class spec schema** the page fills structurally.-- **chip-fetcher**: don't save a product brief as the datasheet — verify the PDF has+- **chip-fetcher**: don't save a product brief as the datasheet, verify the PDF has   the pinout (so ds2sf can extract).  > ⏳ This skill records the live constraints as of its writing (README.md is-> sanitized, but `readme.html` custom pages SHIPPED — verified 2026-07-15; still+> sanitized, but `readme.html` custom pages SHIPPED, verified 2026-07-15; still > no page→desktop bridge). Re-verify and update when the bridge ships.

@@ -1,8 +1,8 @@ --- name: wiki-discovery description: >--  Discovery on the Adom Wiki — a FIRST-CLASS component of the wiki, peer to git,-  adompkg, releases, discussions, and pull requests. How pages/skills get FOUND:+  Discovery on the Adom Wiki, a FIRST-CLASS component of the wiki, peer to git,+  `adom-wiki pkg`, releases, discussions, and pull requests. How pages/skills get FOUND:   the two layers (local installed-skill matching vs the registry /discover + search   endpoints), how to make a page discoverable (manifest + page discovery_triggers),   the current real state of what works and what doesn't, and the TODO list of what@@ -16,10 +16,10 @@ description: >-  Parent skill: **adom-wiki-skillpack** -# Discovery — a first-class component of the wiki+# Discovery: a first-class component of the wiki -Discovery is **not a nice-to-have bolted onto the wiki — it is one of its core-pillars**, on the same footing as the git host, the adompkg package manager, the+Discovery is **not a nice-to-have bolted onto the wiki, it is one of its core+pillars**, on the same footing as the git host, the wiki package manager (`adom-wiki pkg`), the release database, the discussions forum, and pull requests (see **wiki-anatomy**). A page that can't be discovered may as well not exist: discovery is how an AI (or a human) finds the right skill/app/doc *for what they're doing right now*, ideally@@ -28,12 +28,12 @@ a human) finds the right skill/app/doc *for what they're doing right now*, ideal ## The two layers of discovery  Discovery happens at two distinct layers. They are wired differently and fail-differently — know which one you're reasoning about.+differently, know which one you're reasoning about. -### Layer 1 — Local installed-skill discovery (works today)+### Layer 1: Local installed-skill discovery (works today)  Once a skill is installed (`~/.claude/skills/<name>/SKILL.md`), the AI picks it by-matching the user's intent against the skill's **frontmatter `description`** —+matching the user's intent against the skill's **frontmatter `description`** , specifically its trigger phrases. This is why every skill's description must end with a generous, specific list of trigger words. This layer is reliable: if the phrase is in the description and the skill is installed, the AI surfaces it.@@ -42,21 +42,21 @@ phrase is in the description and the skill is installed, the AI surfaces it. `description` (e.g. wiki-readme carries "hero shows twice", "duplicate hero" so it fires the moment someone is about to embed a hero). -### Layer 2 — Registry discovery (search + /discover) — partially working+### Layer 2: Registry discovery (search + /discover): partially working  For pages a user has **not** installed yet, the wiki exposes:-- `GET /api/v1/search?q=<query>` — full-text search. **Works** (finds pages by+- `GET /api/v1/search?q=<query>`, full-text search. **Works** (finds pages by   slug/title/brief). Caveat: the FTS hyphen bug (`chip-fetcher` →   "no such column: fetcher").-- `GET /api/v1/discover?triggers=<csv>` — intended to surface pages whose+- `GET /api/v1/discover?triggers=<csv>`, intended to surface pages whose   declared `discovery_triggers` match what the user is doing. **This is where-  discovery is currently weak — see the state + TODO below.**+  discovery is currently weak, see the state + TODO below.**  You declare a page's triggers in the **package manifest** (`package.json` `discovery_triggers: [...]`) and they ARE stored (verify: `GET /api/v1/packages/<slug>/manifest`). -## ⚠️ Current real state (verified 2026-06-21 — re-verify, this WILL change)+## ⚠️ Current real state (verified 2026-06-21: re-verify, this WILL change)  - ✅ Local installed-skill discovery (Layer 1) works. - ✅ `/search?q=` finds pages.@@ -65,7 +65,7 @@ You declare a page's triggers in the **package manifest** (`package.json`   returns roughly the same fixed ~70-page set regardless of the triggers passed,   so it appears to rank a popular set (stars/installs/recency) rather than match   the requested phrases. A brand-new, correct, zero-engagement page is effectively-  invisible to trigger discovery until it organically accrues engagement — which+  invisible to trigger discovery until it organically accrues engagement, which   is backwards (you discover something in order to *start* using it). - ❌ Page-level `metadata.discovery_triggers` pushed via `page.json` to `/files`   does not persist (reads back as `metadata: []` on `GET /pages/:slug`).@@ -74,17 +74,17 @@ You declare a page's triggers in the **package manifest** (`package.json` then local discovery is solid) and on `/search` for pages. Don't assume `/discover` will surface a fresh page by its triggers yet. -## 📋 TODO — what we need from discovery (for Colby)+## 📋 TODO: what we need from discovery (for Colby)  Discovery deserves to be as solid as the wiki's other pillars. The asks, roughly in priority order: -1. **Make `/discover?triggers=` actually match `discovery_triggers`.** Text-relevance+1. **Make `/discover?triggers=` match `discovery_triggers`.** Text-relevance    match the requested phrases against each page's manifest (and persisted page)-   triggers — not just return a popular set. This is the core bug.+   triggers, not just return a popular set. This is the core bug. 2. **Index triggers at publish time** so a page is discoverable the instant it's    published, with no engagement required.-3. **Persist `page.json` `metadata.discovery_triggers`** (today it's dropped) — or+3. **Persist `page.json` `metadata.discovery_triggers`** (today it's dropped), or    document the manifest as the single source of truth and say so. 4. **Relevance + quality blend in ranking**, not quality alone: a highly-relevant    new page should outrank a barely-relevant popular one.@@ -101,7 +101,7 @@ in priority order: 10. **Exclude deprecated/soft-deleted/private pages** from public discovery. 11. **Fix the FTS hyphen bug** in `/search` (most Adom slugs contain hyphens). 12. **Discovery analytics**: which trigger surfaced a page, and install-    attribution, so authors can see discovery actually working (feeds **wiki-scoring**).+    attribution, so authors can see discovery working (feeds **wiki-scoring**).  > ⏳ **UPDATE THIS SKILL when discovery is upgraded.** The "current real state" > section above is a snapshot and is expected to go stale fast. After any wiki@@ -114,6 +114,6 @@ in priority order:  Discovery answers "can this be found?"; **wiki-scoring** covers the engagement signals (stars / high-fives / installs / trending) that *rank* what's found. They-are linked — ranking is part of discovery — but distinct: a page can be perfectly+are linked, ranking is part of discovery, but distinct: a page can be perfectly discoverable with zero stars, and discovery should surface it on relevance, with scoring breaking ties among relevant results.

@@ -1,7 +1,7 @@ --- name: wiki-family description: >--  How to build a Family-style wiki repo on the Adom Wiki — an anchor page plus+  How to build a Family-style wiki repo on the Adom Wiki, an anchor page plus   children published as their own pages, joined by a naming convention, a family   tag, and breadcrumbs (e.g. adom-usb + adom-usb-sniffer-cdc, adom-desktop +   bridges). Use this when a hub has parts that need their own owners or release@@ -18,19 +18,19 @@ Parent skill: **adom-wiki-skillpack** A **Family** is an anchor page plus children published as **separate** wiki pages (not files in one repo), joined by convention so the relationship survives even when a child is seen out of context. Use it when children need independent owners-or update cadences — see **wiki-repo-styles** for Family-vs-Skillpack. Examples:+or update cadences, see **wiki-repo-styles** for Family-vs-Skillpack. Examples: `adom-usb` (+ sniffer/firmware plugins), `adom-desktop` (+ bridges). -## 1. Naming — every member announces its family+## 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. There are TWO-names, with DIFFERENT separators — don't mix them up:+names, with DIFFERENT separators, don't mix them up: -### The title — the canonical format (this is the one people see)+### 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+screensaver. **Nobody reads slugs, the title is what carries the family.** Use exactly this format, every time, identically across siblings:  ```@@ -40,27 +40,27 @@ exactly this format, every time, identically across siblings: - 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+- **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 - 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 - 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 - 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,+(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+### The slug: dashes, no spaces -- **Slug**: `<parent>-<descriptor>` — `adom-usb-sniffer-cdc`,+- **Slug**: `<parent>-<descriptor>`, `adom-usb-sniffer-cdc`,   `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+  (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@@ -71,7 +71,7 @@ em-dashes, slug-as-title, and orphan titles all exist today. Match the ✅ colum   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,+`title`, it must read `<Parent> - <descriptor>` with the spaced ASCII hyphen, identical in style to its siblings.  ## 2. The anchor page is a registry@@ -96,15 +96,15 @@ with the family conventions applied:  ```bash # canonical org children publish into the org namespace, not personal:-adompkg publish --org adom -y+adom-wiki pkg publish --org adom -y # if the child ships a binary, attach it as a release asset:-adompkg release upload adom/<child-slug>@<ver> ./bin/<bin> --platform linux+adom-wiki release upload adom/<child-slug>@<ver> ./bin/<bin> --platform linux # then push source + a COMPLETE page.json (title leads with the parent, hero set, # family tag in metadata) to the git layer LAST (the hero-clobber rule applies). ```  After any title/hero change, confirm `GET /api/v1/pages/<child-slug>` shows the-`title` leading with the parent and `hero_path` set — cards, search, and the+`title` leading with the parent and `hero_path` set, cards, search, and the screensaver read those fields.  ## 5. Discovery

@@ -1,12 +1,12 @@ --- name: wiki-hero description: >--  The hero image for an Adom Wiki page — how to generate one (via the+  The hero image for an Adom Wiki page, how to generate one (via the   adom-wiki-hero-image package, a dependency of this pack) and, critically, how to-  stop it from getting unlinked. adompkg publish overwrites the repo's page.json+  stop it from getting unlinked. adom-wiki pkg publish overwrites the repo's page.json   (which has no hero), so the page-header hero is dropped on every publish unless   you re-push a complete page.json LAST. Read this when adding a hero, or when a-  hero that used to show is suddenly gone. The hero lives in page.json ONLY —+  hero that used to show is suddenly gone. The hero lives in page.json ONLY ,   never embed it in the README body (that shows the human the same image twice).   Trigger words: wiki hero, hero image, hero disappeared, hero unlinked, hero gone   after publish, page shows placeholder icon, generate a hero, billboard image,@@ -16,7 +16,7 @@ description: >-  Parent skill: **adom-wiki-skillpack** -# The hero image — generating it, and keeping it linked+# The hero image: generating it, and keeping it linked  Every wiki page needs a hero: the 16:10 dark-mode billboard the page header, the landing-grid card, the Hydrogen Desktop installer, the homepage, and the@@ -25,8 +25,8 @@ as unfinished.  ## Generating it -Use the **adom-wiki-hero-image** package — it's a declared **dependency of this-pack**, so `adompkg install adom-wiki-skillpack` pulls it automatically. It+Use the **adom-wiki-hero-image** package, it's a declared **dependency of this+pack**, so `adom-wiki pkg install adom-wiki-skillpack` pulls it automatically. It bundles the brand fonts + ADOM wordmark + the render pipeline, so it works standalone with no gallia dependency. Invoke it (the `adom-wiki-hero` / `adom-wiki-hero-image` skill) to render `screenshots/hero.png`: the app NAME as@@ -38,7 +38,7 @@ dots.) For Family children, also carry the family chip (e.g. `ADOM-USB · SNIFFE ### The hero shot: laptop width, full toolbars OPEN (show the sophistication)  The single most important choice is the screenshot. For an app, capture the-**laptop-browser view with every toolbar / studio / HUD / layers panel OPEN** —+**laptop-browser view with every toolbar / studio / HUD / layers panel OPEN** , the busy, sophisticated state, not the default empty one. A loaded part with the control panel deployed tells the viewer "this tool is capable" at a glance; a bare canvas reads as a toy. Capture at ~1440px wide (deviceScaleFactor 2 for crispness)@@ -49,29 +49,29 @@ so users "understand how sophisticated the apps have gotten.") ### The subhead carries the VALUE PROP, not a restatement of the name  The headline can be a punchy phrase; the **subhead must be the value proposition**-— one line on what the app is *for* and its differentiator (e.g. "preview the+, one line on what the app is *for* and its differentiator (e.g. "preview the InstaPCB 300µm solder-paste dots no other tool shows"). Don't waste the subhead paraphrasing the title. Keep it to ~1 line so the composer doesn't truncate it.  > 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 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*+, 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+This is the #1 hero problem and it looks like the image was deleted, **it wasn't**. The mechanism:  - The page-header hero renders from the DB `hero_type` / `hero_path`, which the   wiki indexer derives from the repo's **`page.json` → `hero:{type,path}`**.-- **`adompkg publish` OVERWRITES `page.json` in the repo with the package+- **`adom-wiki pkg publish` OVERWRITES `page.json` in the repo with the package   manifest, which has no `hero` field.** So every publish silently drops the hero   reference. The PNG file is still in the repo at `screenshots/hero.png`; only the   pointer in `page.json` is gone.@@ -82,22 +82,22 @@ The same overwrite also resets the page **title and brief** to the package value  Order every publish so the complete `page.json` is the final commit: -1. `adompkg publish` (registry/tarball) — this clobbers `page.json` in the repo.+1. `adom-wiki pkg publish` (registry/tarball), this clobbers `page.json` in the repo. 2. **THEN** push a **complete** `page.json` to `POST /api/v1/pages/<slug>/files`-   as the last step — including `hero:{type:"image",path:"screenshots/hero.png"}`,+   as the last step, including `hero:{type:"image",path:"screenshots/hero.png"}`,    plus title, brief, visibility, tags. This re-indexes and re-links the hero    (and restores title/brief). 3. Confirm: `GET /api/v1/pages/<slug>` shows    `hero_type:"image", hero_path:"screenshots/hero.png"`. 4. Open the page in pup and confirm the hero renders (see **wiki-publish-safely**). -If a hero "disappeared" on an existing page, you don't need to regenerate it —+If a hero "disappeared" on an existing page, you don't need to regenerate it , just re-push a complete `page.json` with the `hero` block and verify `hero_path`.  ## Checklist  - [ ] `screenshots/hero.png` exists in the repo and is listed in `package.json` `files[]` - [ ] `page.json` has the `hero` block-- [ ] Complete `page.json` pushed AFTER `adompkg publish`+- [ ] Complete `page.json` pushed AFTER `adom-wiki pkg publish` - [ ] `GET /pages/<slug>` → `hero_path` set - [ ] Hero visually confirmed in pup

@@ -2,13 +2,13 @@ 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+  (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,+  unlinked, UNIQUE constraint pages, immutable version, `adom-wiki pkg` 429, ghost page,   verify wiki in pup, wiki publish checklist, don't break the wiki page. --- @@ -23,21 +23,21 @@ 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**.+   registry (`adom-wiki pkg publish`). Only one → the page is broken (placeholder Files+   tab, or a README that won't `adom-wiki pkg install`). See **wiki-anatomy**. -2. **The hero gets clobbered — re-push `page.json` LAST.** `adompkg publish`+2. **The hero gets clobbered, re-push `page.json` LAST.** `adom-wiki pkg 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+   `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 same clobber resets the page **title and brief** to the package values ,    the complete `page.json` re-push restores those too. Two title traps: (a) put a-   `title` in **package.json** as well — the manifest has none by default, so the+   `title` in **package.json** as well, the manifest has none by default, so the    clobber resets the title to the bare **slug**; (b) the title must be a-   **human, descriptive name — NEVER the slug echo** (`Wiki Hero Image Skill`, not+   **human, descriptive name, NEVER the slug echo** (`Wiki Hero Image Skill`, not    `adom-wiki-hero-image`). Cards, search, the homepage, and the screensaver all    show the title; nobody reads slugs. → **wiki-repo-styles** / **wiki-family**. @@ -46,14 +46,14 @@ companion.    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+   published it can't be overwritten, `adom-wiki pkg 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+   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+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.@@ -74,7 +74,7 @@ companion. ## 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+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**.@@ -82,25 +82,25 @@ README for the hero filename and delete any line that references it. → **wiki- ## 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+  send `User-Agent: `adom-wiki pkg`/2.1.0`. curl sends its own UA and is fine.+- **Publish-only pages create ghost rows.** `adom-wiki pkg 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+- **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)+- [ ] `adom-wiki pkg 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 - [ ] **Title is descriptive, NOT the slug** (and `title` is set in `package.json` too, so publish won't reset it to the slug) - [ ] 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+- [ ] `adom-wiki pkg info <slug>` shows the right version + dependencies

@@ -1,7 +1,7 @@ --- name: wiki-readme-html description: >--  How to build a custom HTML readme (readme.html) for an Adom Wiki page — the+  How to build a custom HTML readme (readme.html) for an Adom Wiki page, the   fully designed, unsanitized alternative to README.md. Covers when to choose   html over markdown, the shadowing rule (readme.html makes README.md invisible   on the page), the sandboxed-iframe render pipeline and its exact limits@@ -48,8 +48,8 @@ and the Overview tab switches to HTML mode.  `readme.html` **fully shadows README.md on the page**. The publish linter warns: `README_SHADOWED: readme.html is what renders on the page, so edits to README.md-will not be visible.` Keep a README.md anyway — the Files tab, `repo clone`-readers, and git tooling still use it — but every page-visible edit goes in the+will not be visible.` Keep a README.md anyway, the Files tab, `repo clone`+readers, and git tooling still use it, but every page-visible edit goes in the HTML file. If "my readme edit isn't showing up," check which file you edited.  ## How it renders (and what the sandbox forbids)@@ -62,7 +62,7 @@ https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public ```  in `<iframe sandbox="allow-scripts allow-downloads">`. The endpoint serves your-file **byte-for-byte — no sanitizer**. Consequences:+file **byte-for-byte, no sanitizer**. Consequences:  - `<style>`, `style=`, and `<script>` all work. Scripts run inside the sandbox. - **No `allow-same-origin`**: the iframe runs as an opaque origin. No cookies,@@ -71,7 +71,7 @@ file **byte-for-byte — no sanitizer**. Consequences: - **No `allow-popups` / `allow-top-navigation`**: `target="_blank"` links and   `window.open` are blocked by the sandbox. Plain same-frame links navigate the   iframe itself, not the wiki page. Design navigation accordingly (prefer-  in-page JS interactions; verify any external link actually opens before+  in-page JS interactions; verify any external link opens before   relying on it). - It is a full document of its own: include your own base styles; nothing   cascades in from the wiki.@@ -82,9 +82,9 @@ Treat the file like an email template: everything inline.  - Inline all CSS and JS. Base64-inline fonts and small images. - Repo files are reachable at absolute `/blob/<type>/<slug>/...` URLs for-  `<img>`/`<video>` — but note the known content-type bug (SVGs served as+  `<img>`/`<video>`, but note the known content-type bug (SVGs served as   `application/octet-stream`, adom/wiki issue #38); PNG/JPG are safe.-- Never reference the hero image — the page header already renders it+- Never reference the hero image, the page header already renders it   (**wiki-readme**'s #1 rule applies in both modes).  ## Theme: the wiki is dark@@ -101,19 +101,19 @@ The page tracks six slots in `readme_variants_json`: `bareHtml`/`bareMd`, `publicHtml`/`publicMd`, `privateHtml`/`privateMd`. A plain `readme.html` registers as `bareHtml`. The html-vs-md choice composes with the private-readme system for private-source/public-releases pages-(**wiki-visibility**) — the `?variant=` query selects which one renders.+(**wiki-visibility**), the `?variant=` query selects which one renders.  ## Verify loop (do all three) -1. **curl the endpoint** — confirm your exact bytes are live:+1. **curl the endpoint**, confirm your exact bytes are live:    `curl -s "https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public"`-2. **Open the page in pup** (cache-bust `?v=<ver>`) and screenshot — confirm the+2. **Open the page in pup** (cache-bust `?v=<ver>`) and screenshot, confirm the    iframe shows your layout, styles applied, at a sane height with no clipping-   or double scrollbars. Iframe sizing is controlled by the page, not you —+   or double scrollbars. Iframe sizing is controlled by the page, not you ,    if your content clips, restructure toward a natural document flow and    re-verify. (Sizing behavior is not yet fully characterized; report surprises    on adom/wiki.)-3. **Check any JS actually ran** — bake a visible self-test into the page while+3. **Check any JS ran**, bake a visible self-test into the page while    iterating (an element whose text a script rewrites), remove it when done.  ## Pitfalls recap@@ -125,3 +125,62 @@ with the private-readme system for private-source/public-releases pages - SVG `<img>` broken → content-type bug (issue #38); use PNG or inline the SVG markup. - Works locally, stale on the wiki → you pushed the repo but didn't `pkg publish`   (or vice versa); the readme the page renders comes from the published layer.++## Roll your own Adom Babylon9 3D viewer inside readme.html++The 3D tab on every Components page is the **Adom 3D Viewer** (Babylon 9.5). You can embed and+CUSTOMIZE that same engine inside a `readme.html`, custom layers panels, exploded-view animation,+scrub bars, your own toolbars, because readme.html runs scripts. This is proven live (the+BQ25792 charger page ran a full animated exploded PCB stackup this way). The facts below are the+difference between it working and hours of silent failure.++### Where the viewer lives++- **Runtime bundle (load this in readme.html):**+  `https://wiki.adom.inc/static/vendor/adom-3d-viewer-babylon9/adom-3d-viewer-babylon9.esm.js`+  It sets `window.Adom3DViewerBabylon9` and `window.BABYLON`, so your script can use the shipped+  viewer (view cube, layers toolbar, ground shadows, Z-up CAD framing) or raw Babylon on top.+- **Source code:** the [`adom-3d-viewer`](https://wiki.adom.inc/adom/adom-3d-viewer) page (adom-owned),+  full `src/`, `standalone.ts`, vite configs in its Files tab. Read it there before customizing;+  never fork blind.+- **NEVER roll your own engine.** Extend this one. A hand-rolled viewer was rejected hard in review.++### ⛔ NEVER pin the bundle URL with `?v=`++The bundle is a tiny **code-split stub** (~30 bytes: `import "./chunk-<hash>.js"`). The chunk hash+changes on every rebuild of the wiki. If you pin `?v=...`, a cached stub keeps importing a chunk+that no longer exists and the viewer 404s AFTER a wiki deploy, weeks later, on a page you already+shipped. Load it unpinned.++### The sandbox will kill the viewer unless you shim three things++readme.html runs in `sandbox="allow-scripts allow-downloads"`, no same-origin. Consequences,+each found the hard way:++1. **`localStorage` THROWS** (SecurityError) in a sandboxed document, and the viewer touches it on+   init, which aborts the whole rig. Shim it in `<head>` BEFORE the bundle loads:+   ```html+   <script>try{localStorage}catch(e){var _m={};Object.defineProperty(window,'localStorage',+     {value:{getItem:k=>_m[k]??null,setItem:(k,v)=>{_m[k]=String(v)},removeItem:k=>{delete _m[k]},clear:()=>{_m={}}}});}</script>+   ```+2. **`blob:` images are blocked** (img-src has no blob:). Anything doing+   `URL.createObjectURL` for textures needs a shim that converts to `data:` URIs instead.+3. **`connect-src 'none'`: NO fetch/XHR at all.** You cannot download a GLB at runtime. Ship model+   bytes INSIDE the page instead: base64 `data:` URIs, or (the proven trick for multi-MB models)+   pack the GLB bytes into a lossless PNG's RGB channels (4-byte little-endian length header),+   reference the PNG as a normal repo image, and decode via canvas at runtime. Images load fine;+   fetch does not.++### Size budget++A readme.html has roughly a **4-5 MB practical cap**. Optimize models before embedding:+service-step2glb / gltf-transform (join, weld, prune, Draco) turns a raw ~16 MB board GLB into+~465 KB. Budget models first, code second.++### The default vs your own++If you just need "a 3D model on the page", you do NOT need any of this: give the page a+`component` block / GLB and the wiki renders the standard viewer on the 3D tab (see+wiki-component). Roll your own INSIDE readme.html only when you need custom behavior the standard+viewer lacks (exploded animation, custom panels, scripted tours), and even then, build ON+`window.Adom3DViewerBabylon9`, not beside it.

@@ -1,11 +1,11 @@ --- name: wiki-readme description: >--  How to make a great Adom Wiki page presentation — the README is the page. Covers+  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, and BEFORE adding any image to a README —+  the Overview tab of a wiki page, and BEFORE adding any image to a README ,   NEVER embed the page hero in the README body (the page header already shows it,   so embedding it makes the human see the same image twice). Trigger words: how to   make a readme, wiki readme, readme.html, custom readme, write a readme for the@@ -20,13 +20,13 @@ 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+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. There are TWO presentation modes: -1. **`README.md`** (the default) — rendered through `marked` **then sanitized**,+1. **`README.md`** (the default), rendered through `marked` **then sanitized**,    so what you can build is limited (below).-2. **`readme.html`** (custom HTML mode, LIVE — verified end to end 2026-07-15) —+2. **`readme.html`** (custom HTML mode, LIVE, verified end to end 2026-07-15) ,    your HTML renders as the page body in a **sandboxed iframe**, completely    unsanitized: inline `<style>` AND `<script>` both work. The nuances (sandbox    limits, self-containment, theming, variants, verify loop) have their own@@ -43,16 +43,16 @@ Ship a `readme.html` in the publish tree and `pkg publish`. That's it. - **How it renders:** the Overview tab embeds   `https://wiki.adom.inc/readme/<owner>/<type>/<slug>?variant=public` in an   iframe with `sandbox="allow-scripts allow-downloads"` (no `allow-same-origin`).-  The endpoint serves your HTML byte-for-byte — no sanitizer. Styles apply,+  The endpoint serves your HTML byte-for-byte, no sanitizer. Styles apply,   scripts run (verified live: styled tabs rendered, a `<script>` mutated the DOM). - **Sandbox limits:** no same-origin access (no cookies, no wiki API calls from   the readme), no top-navigation. Self-contain everything: inline CSS/JS,   base64-inline fonts and images or use absolute `/blob/...` URLs.-- **Variants:** the page tracks six readme slots in `readme_variants_json` —-  `bareHtml`/`bareMd`, `publicHtml`/`publicMd`, `privateHtml`/`privateMd` — so+- **Variants:** the page tracks six readme slots in `readme_variants_json` ,+  `bareHtml`/`bareMd`, `publicHtml`/`publicMd`, `privateHtml`/`privateMd`, so   the html-vs-md choice composes with the public/private readme split   (see **wiki-visibility**). A plain `readme.html` registers as `bareHtml`.-- Tabs, accordions, toolbars, provenance lightboxes — all buildable here. This+- Tabs, accordions, toolbars, provenance lightboxes, all buildable here. This   is the mode the old "standalone prototype in the container" workaround was   waiting for; prototype straight in `readme.html` now. @@ -64,16 +64,16 @@ It **strips `<style>`, `<script>`, `<details>`/`<summary>`, `<iframe>`, and even code, em, strong, del, ins, sub, sup, kbd, hr, br, img, table/thead/tbody/tr/th/td, span, div, input` (task lists), with `class` on a few and `href/src/alt/width/ height/align`. **Consequence: you cannot build a tabbed / accordion / toolbar-"custom HTML layout" in README.md** — inline styles vanish, `<details>` collapse,+"custom HTML layout" in README.md**, inline styles vanish, `<details>` collapse, scripts never run. (Confirmed live: a hand-styled toolbar rendered as plain links.)  So README.md is for **prose + images + tables**. For anything richer: - **Switch to `readme.html`** (above) for a fully designed layout. - **Component pages** get rich interactive UI from the wiki's **native rendering**-  (symbol/footprint/3D viewers, downloads grid) — see **wiki-component**, not the README.+  (symbol/footprint/3D viewers, downloads grid), see **wiki-component**, not the README.  There is also a **private readme** for pages whose git source is private but whose-releases are public — see **wiki-visibility**.+releases are public, see **wiki-visibility**.  ## Provenance: cite your sources (engineers don't trust AI yet) @@ -81,22 +81,22 @@ Every non-obvious claim on a page should name where it came from: a datasheet pa a distributor + date, a manufacturer URL, the tool + input hash that produced an artifact. For datasheet-derived data, show the **page number and a cropped image of that page**. This is mandatory on component/chip pages (full pattern + tooling in-**wiki-component**), and good practice everywhere — provenance is what turns "the AI+**wiki-component**), and good practice everywhere, provenance is what turns "the AI said so" into "here's the page it's on."  ## ⛔ 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,+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.+- 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. @@ -104,61 +104,61 @@ goes first.  **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+`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.+for the AI, the README is for the person deciding whether to install.  ## Mandatory sections (in this order) -1. **Title + one-line description** — the title is a **human, descriptive name,+1. **Title + one-line description**, the title is a **human, descriptive name,    NEVER the slug echo** (`Wiki Hero Image Skill`, not `adom-wiki-hero-image`).    Set it in `page.json` AND `package.json` (publish resets a missing manifest    title to the slug). → **wiki-repo-styles**.-2. **(The page header already shows the hero — do NOT embed it here.)** Go+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+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. **Feature images** — for an app, show **exactly 3 inline images of the major+4. **Install**, `adom-wiki pkg install <slug>`+5. **Quick start**, 3–5 lines showing the most common workflow+6. **Feature images**, for an app, show **exactly 3 inline images of the major    elements of the app**, each under its own `##` heading and each **described in    detail**: a full paragraph on *what's in the shot and why it matters*, not a    one-line caption. Make the three DIFFERENT elements (e.g. the control panel,-   the rendered output, the signature feature) — and never the hero. A close-up+   the rendered output, the signature feature), and never the hero. A close-up    crop of a region is a fine "different" image; an identical copy of the hero is    not. (Pattern proven on adom-symbol / adom-footprint / adom-lbr, 2026-06-21.)-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+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)+10. **Skills**, table of the main skill + sub-skills with a purpose column+11. **CLI reference**, command table (if there's a CLI)  ## Open-source pages need a "check it out, vibe-code it, send it back" section  If the page's source is public (open source), the README MUST teach the-contribution loop — otherwise "open source" is a hollow claim. The proven section+contribution loop, otherwise "open source" is a hollow claim. The proven section (used across the Adom EDA apps, 2026-06-21) is a `## Open source` heading with a short intro ("the complete source is in this page's **Files** tab") plus four numbered steps: -1. **Build it** — the one-command build (`cargo build --release`, etc.).-2. **Point your install at your checkout** — `adompkg link <owner>/<slug> ./<dir>`+1. **Build it**, the one-command build (`cargo build --release`, etc.).+2. **Point your install at your checkout**, `adom-wiki pkg link <owner>/<slug> ./<dir>`    so the installed command runs the local copy.-3. **Vibe-code a change** — open the folder in Claude Code and describe the change;+3. **Vibe-code a change**, open the folder in Claude Code and describe the change;    name a couple of concrete, small extension points so it feels approachable.-4. **Send it back** — open a **pull request** on the page (the wiki merges per-repo+4. **Send it back**, open a **pull request** on the page (the wiki merges per-repo    PRs) or start a discussion thread. -For this to be TRUE, you must actually push the source (`src/` + build manifest)-into the page repo so the Files tab really shows it — don't write the section+For this to be TRUE, you must push the source (`src/` + build manifest)+into the page repo so the Files tab shows it, don't write the section against source that isn't there. Don't invent a `git clone` URL you haven't-verified; lean on the **Files** tab, `adompkg link`, and PRs, which exist.+verified; lean on the **Files** tab, `adom-wiki pkg link`, and PRs, which exist.  ## Embeds -Inline image from the repo (blob endpoint) — point at a NON-hero screenshot+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@@ -172,7 +172,7 @@ Self-contained demo (bake sample data into the HTML, no fetch/WebSocket):   frameborder="0" style="border-radius:8px;border:1px solid #333;"></iframe> ``` -Video — local file from the repo (the blob endpoint supports Range, so seeking+Video, local file from the repo (the blob endpoint supports Range, so seeking works), or YouTube via `youtube-nocookie.com`, or Vimeo:  ```html@@ -183,6 +183,6 @@ works), or YouTube via `youtube-nocookie.com`, or Vimeo: ## 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;+  tag is correct, always verify visually in pup.+- After `adom-wiki pkg publish`, the page title/brief reset to the package values;   re-push a complete `page.json` to restore them (see **wiki-publish-safely**).

@@ -1,7 +1,7 @@ --- name: wiki-scoring description: >--  The scoring / trending system on the Adom Wiki — the signals tracked to know+  The scoring / trending system on the Adom Wiki, the signals tracked to know   whether a page is doing well (stars / high-fives, install counts, and a   trending surface) and how an author legitimately earns them (great hero, strong   README, working demo). Stars are live; install counts, high-fives, and a@@ -15,14 +15,14 @@ Parent skill: **adom-wiki-skillpack**  # Scoring & trending -The wiki tracks engagement signals so good pages surface — the equivalent of+The wiki tracks engagement signals so good pages surface, the equivalent of stars + download counts driving a "trending" view. The intent is to capture everything that indicates a page is valued; the surfacing is partly built. -These signals are the **ranking input to discovery** (a first-class wiki pillar —+These signals are the **ranking input to discovery** (a first-class wiki pillar , see **wiki-discovery**). Scoring answers "how valued is this page?"; discovery answers "can it be found at all?" Relevance should surface a page; scoring should-break ties among relevant results — a great new page shouldn't be invisible just+break ties among relevant results, a great new page shouldn't be invisible just because it has zero stars yet.  ## Status@@ -31,7 +31,7 @@ because it has zero stars yet.   `GET /api/v1/pages/:slug/stars` work (`→ {"count":N,"starred_by_me":bool}`). - **High-fives / install counts / a dedicated trending endpoint: Partial /   Planned.** These signals are intended but not yet exposed through the public API-  — page metadata doesn't surface install/high-five/score fields today, and+ , page metadata doesn't surface install/high-five/score fields today, and   `GET /api/v1/trending` returns 404. Treat trending rank as not-yet-queryable.  Don't report a numeric "score" or "trending rank" you can't read from the API.@@ -40,26 +40,26 @@ claiming numbers.  ## The signals (the model) -- **High-fives** — lightweight positive user feedback on a page.-- **Stars** — a user bookmarking/endorsing a page (live).-- **Install counts** — how many times the package was installed (the strongest+- **High-fives**, lightweight positive user feedback on a page.+- **Stars**, a user bookmarking/endorsing a page (live).+- **Install counts**, how many times the package was installed (the strongest   signal of real use).-- **Activity** — commits, releases, discussions, recency.+- **Activity**, commits, releases, discussions, recency.  These roll up into a **trending** surface so the wiki homepage and the adom-screensaver billboards can promote what's hot. -## How to earn it (what actually moves the needle)+## How to earn it (what moves the needle) -Scoring rewards the same things that make a page genuinely good — there's no trick+Scoring rewards the same things that make a page genuinely good, there's no trick substitute: -- **A great hero** (see **wiki-hero**) — it's what cards, the homepage, and the+- **A great hero** (see **wiki-hero**), it's what cards, the homepage, and the   screensaver display; readable in one second.-- **A strong README with a working demo** (see **wiki-readme**) — humans install+- **A strong README with a working demo** (see **wiki-readme**), humans install   what they can see working; install count is the heaviest signal. - **Clear value + correct discovery triggers** so the right people find it.-- **Keep it alive** — releases, answered discussions, merged PRs.+- **Keep it alive**, releases, answered discussions, merged PRs.  So "how do I make this trend?" reduces to: make the page legitimately excellent and easy to discover. The scoring system is designed to surface exactly that.@@ -67,9 +67,9 @@ and easy to discover. The scoring system is designed to surface exactly that. ## Reading what's available now  ```bash-curl -s -H "User-Agent: adompkg/2.1.0" \+curl -s -H "User-Agent: `adom-wiki pkg`/2.1.0" \   "https://wiki.adom.inc/api/v1/pages/<slug>/stars"   # {"count":N,"starred_by_me":bool} ``` -Update this skill as install-count / high-five / trending endpoints come online —+Update this skill as install-count / high-five / trending endpoints come online , re-probe and label them honestly.