skill
Adom Wiki Skill Pack
Public Made by Adomby adom
The Adom Wiki Skill Pack : one main skill plus the focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, name the wiki repo archetypes (Page, Skillpack, Family), and publish rich component pages (chips, molecules, boards). The wiki is six tools in one: git, package manager, releases, discussions, pull requests, and discovery. One package manager install drops the whole set onto your container. Includes reviewed Z-up component artwork, surface-selected MPN marki
← Commit history
Publish 0.8.56
7 files changed
+87−109
README.md+6−5@@ -124,11 +124,12 @@ each part need its own lifecycle and maybe its own author?_ Yes → Family. The pack encodes these; they're worth stating here too: -1. **Every file the page shows must reach the repo.** Since adom-wiki 1.8.2 publish commits the tarball's files to the repo itself (media only with `--include-media`); before it, write both storage layers every publish (git + registry).-2. **Hero and `page.json` on publish.** Since 1.8.2 publish merges `page.json` and keeps the hero. Before it, `adom-wiki pkg publish` clobbered the hero: it overwrote 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.)+1. **One publish writes both layers.** `adom-wiki pkg publish` stores the package and+ commits its files into the page repo; push only what it leaves out (screenshots,+ videos, `.pkgignore`d source) with `adom-wiki repo push`.+2. **The hero belongs to the page.** A first publish carries the declared hero+ (adom-wiki 1.8.3+ adds it itself); after that, change it with `adom-wiki page hero`.+ A republish merges `page.json` and never replaces the hero. 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).
package.json+1−1@@ -1,7 +1,7 @@ { "slug": "adom-wiki-skillpack", "title": "Adom Wiki Skill Pack",- "version": "0.8.55",+ "version": "0.8.56", "changelog": "0.8.55: wiki-publish-safely matches adom-wiki 1.8.2 (tested 2026-10-30, #5): publish writes both layers (commits the tarball files + a merged page.json to the repo), a first publish creates the page with no ghost row, and page.json is merged (manifest keys win, the hero and hand-added keys survive); the old rules are kept for older CLIs/servers. 0.8.54: publish checklist: page.json must carry the same discovery_triggers as package.json; a page.json push without them silently wipes the page's triggers (adom/wiki#240).", "type": "skill", "hero": {
page.json+1−1@@ -201,7 +201,7 @@ "prompt": "Before I create this wiki page, check whether the thing already has a home." } ],- "version": "0.8.55",+ "version": "0.8.56", "changelog": "0.8.55: wiki-publish-safely matches adom-wiki 1.8.2 (tested 2026-10-30, #5): publish writes both layers (commits the tarball files + a merged page.json to the repo), a first publish creates the page with no ghost row, and page.json is merged (manifest keys win, the hero and hand-added keys survive); the old rules are kept for older CLIs/servers. 0.8.54: publish checklist: page.json must carry the same discovery_triggers as package.json; a page.json push without them silently wipes the page's triggers (adom/wiki#240).", "description": "The Adom Wiki Skill Pack : one main skill plus the focused sub-skills that teach the AI to publish to wiki.adom.inc without breaking pages, name the wiki repo archetypes (Page, Skillpack, Family), and publish rich component pages (chips, molecules, boards). The wiki is six tools in one: git, package manager, releases, discussions, pull requests, and discovery. One package manager install drops the whole set onto your container. Includes reviewed Z-up component artwork, surface-selected MPN marking, reusable thumbnail caches and component-page widgets. Includes canonical video widgets, synchronized captions and chapters, and voiceover pacing checks.", "dependencies": {
skills/wiki-api/SKILL.md+22−25@@ -39,39 +39,36 @@ adom-wiki whoami 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 -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). adom-wiki 1.8.2+ (tested 2026-10-30): publish commits the tarball files and a MERGED page.json to the repo and keeps the hero; see **wiki-publish-safely** rules 1-2. On an older CLI/server the following still applies.+The page repo and the package registry are two layers (see **wiki-anatomy**), and+one `adom-wiki pkg publish` writes both: it stores the package and commits its files+into the page repo with a merged `page.json`. Rules and edge cases:+**wiki-publish-safely** rules 1-2. -**Step 1, `package.json` first.** Set `slug`, `version`, `type`, `description`,-`dependencies`, `files[]` (list every shipped file), and `scripts.install/uninstall`.+**Step 1, `package.json`.** Set `slug`, `version`, `type`, `title`, `description`,+`dependencies`, `files[]` (list every shipped file), `scripts.install/uninstall`,+and the discovery fields. -**Step 2, create the page (first publish only).** Inits the git repo.--```bash-WIKI="https://wiki.adom.inc"-curl -s -X POST "$WIKI/api/v1/pages" \- -H "Authorization: Bearer $(cat /var/run/adom/api-key)" \- -H "Content-Type: application/json" \- -d '{"type":"skill","slug":"my-tool","title":"my-tool","brief":"One line","version":"0.1.0"}'-```--**Step 3, `adom-wiki pkg publish`.** Builds the tarball and uploads it to the registry.-(Do this before the final file push, see step 4.)+**Step 2, `adom-wiki pkg publish`.** The first publish creates the page and its repo+(nothing to create beforehand) and carries the declared hero (adom-wiki 1.8.3+ adds+it itself). Every publish commits `Publish X.Y.Z` to the repo and keeps the page's+hero. ```bash 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:** `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**.+**Step 3, push what the package leaves out.** Screenshots, videos, README images,+`.pkgignore`d source: `adom-wiki repo push <ref> --files <paths>`. Files pushed only+to the repo survive later publishes. To change the hero, push the PNG and run+`adom-wiki page hero`. Without the CLI, `POST /api/v1/pages/<owner>/<slug>/files`+takes the same files (text plain, binaries base64): ```python import requests, base64, os+WIKI, owner, slug, project_dir = "https://wiki.adom.inc", "<owner>", "<slug>", "."+token = open("/var/run/adom/api-key").read().strip() BINARY_EXTS = {'.png','.jpg','.jpeg','.webp','.gif','.ico','.woff','.woff2', '.tgz','.gz','.zip','.bin','.exe','.glb','.step','.stl','.wasm','.so','.dll'} files, skip = [], {'.git','target','node_modules'}@@ -85,12 +82,12 @@ for root, dirs, fnames in os.walk(project_dir): else: files.append({"path": rel, "content": open(full).read()}) # TEXT = plain, never base64 for i in range(0, len(files), 50): # batch by 50 (payload limit)- requests.post(f"{WIKI}/api/v1/pages/{slug}/files",+ requests.post(f"{WIKI}/api/v1/pages/{owner}/{slug}/files", 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"})+ json={"files": files[i:i+50], "message": "Push what the package leaves out"}) ``` -**Step 5, verify in pup** (non-negotiable; see **wiki-publish-safely**).+**Step 4, verify in pup** (non-negotiable; see **wiki-publish-safely**). ## Encoding rule (memorize)
skills/wiki-family/SKILL.md+3−3@@ -93,9 +93,9 @@ with the family conventions applied: adom-wiki pkg publish --org adom -y # if the child ships a binary, attach it as a release asset: 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 before adom-wiki 1.8.2;-# since 1.8.2 publish merges page.json and keeps the hero, see wiki-publish-safely).+# publish commits the package files and a merged page.json to the repo; push what+# the package leaves out with `adom-wiki repo push`. The title leads with the parent+# (set it in package.json), and the family tag goes in the page metadata. ``` After any title/hero change, confirm `GET /api/v1/pages/<child-slug>` shows the
skills/wiki-hero/SKILL.md+22−34@@ -63,42 +63,30 @@ of the page for you. **Do NOT also embed it in the README** (`: publish commits the tarball files and a MERGED page.json to the repo and keeps the hero; see **wiki-publish-safely** rules 1-2. On an older CLI/server the following still applies.--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"}`,- 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 ,-just re-push a complete `page.json` with the `hero` block and verify `hero_path`.+## The hero through a publish++The page-header hero renders from the DB `hero_type` / `hero_path`, which the+indexer reads from the repo's **`page.json` → `hero:{type,path}`**. Publish keeps it:++- **A first publish** carries the declared `hero.path` into the page repo.+ adom-wiki 1.8.3+ adds that file to a first publish itself; on an older CLI list+ it in `files[]` or pass `--include-media`. That one publish does not warn+ `MEDIA_IN_TARBALL` about the hero.+- **Every later publish** merges `page.json` and keeps the page's hero, whatever+ `package.json` says. Leave the hero out of the tarball from then on: a hero still+ packed into a republish warns `MEDIA_IN_TARBALL` (every installer downloads it).+- **To change the hero**, push the new PNG with `adom-wiki repo push`, then point+ the page at it with `adom-wiki page hero`. A publish never replaces it.++If an older page lost its hero (servers before the merge overwrote `page.json`+on publish), the PNG is usually still in the repo: run `adom-wiki page hero` on it,+then confirm `GET /api/v1/pages/<owner>/<slug>` shows `hero_path` and open the+page in pup (see **wiki-publish-safely**). ## 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 `adom-wiki pkg publish`+- [ ] The hero PNG is in the repo: it rode the first publish, or was pushed with `adom-wiki repo push`+- [ ] `page.json` has the `hero` block (the first publish or `adom-wiki page hero` wrote it)+- [ ] Republishes leave the hero out of the tarball (no `MEDIA_IN_TARBALL`) - [ ] `GET /pages/<slug>` → `hero_path` set - [ ] Hero visually confirmed in pup
skills/wiki-publish-safely/SKILL.md+32−40@@ -17,40 +17,37 @@ companion. ## The five rules that prevent broken pages -**What publish does today** (tested 2026-10-30 on adom-wiki 1.8.2, wiki issue-adom/adom-wiki-skillpack#5): `adom-wiki pkg publish` writes BOTH layers. On every-publish, first or later, it commits a `Publish X.Y.Z` to the page repo holding every-file in the tarball, plus `package.json` and a `page.json`. A first publish with no-page created beforehand creates the page with its repo, as one row. The CLI's-`PUBLISH_LAYERS` hint ("the page git repo is a SEPARATE layer and is not synced by-publish") is wrong on this version. Rules 1 and 2 below say what still applies.+**What publish does** (checked against the server, adom/adom-wiki-skillpack#5):+`adom-wiki pkg publish` stores the package AND commits its files into the page+repo, on every publish, first or later, as one `Publish X.Y.Z` commit (added or+updated, never removed) with a merged `page.json`. A first publish creates the+page and its repo in that same step: there is nothing to create beforehand. -1. **Every file the page shows must reach the repo.** Publish commits the tarball's- files, so anything in `files[]` lands on the Files tab. What is NOT in the tarball- is not committed: media is left out unless you pass `--include-media` (hero,- `screenshots/`, videos are page assets, not install payload). So either publish- with `--include-media`, or push the media yourself with `adom-wiki repo push`.- Files pushed only to the repo survive later publishes (publish adds and updates- files, it does not delete). Before 1.8.2 publish wrote only the registry: on an- older CLI or server, push all source to the repo as well. See **wiki-anatomy**.+1. **One publish writes both layers; push only what the package leaves out.**+ Everything in the tarball lands on the Files tab. What the tarball leaves out+ still needs `adom-wiki repo push`: screenshots, videos, `.pkgignore`d source,+ `dev-skills/` and `publish-skills/`. Media stays out of the tarball by default+ (it is page decor, not install payload), and files pushed only to the repo+ survive later publishes. See **wiki-anatomy**. -2. **Publish merges `page.json`: keys from `package.json` win.** Publish writes the- manifest's keys (version, title, description, hero, discovery_triggers, tags,- files...) into the repo's `page.json` and keeps every other key you added by hand- (`kind`, for example). Consequences:- - The **hero survives** publish, whether or not `package.json` declares one. (Before- 1.8.2 publish replaced `page.json` with a manifest that had no hero, which is why- this rule used to say "re-push page.json last". On an older server, still do that,- and confirm `GET /api/v1/pages/<slug>` shows `hero_path`.) Full detail → **wiki-hero**.- - A **title or brief edited only in `page.json` is reset** to the `package.json` value- on the next publish. Keep them in `package.json`. Two title traps: (a) put a- `title` in **package.json**, or publish 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 `adom-wiki-hero-image`). Cards, search, the homepage, and- the screensaver all show the title; nobody reads slugs. → **wiki-repo-styles** /- **wiki-family**.- - A `page.json` you push by hand still needs the same `discovery_triggers` as- `package.json` (a push without them zeroes the indexed triggers, adom/wiki#240).+2. **The hero belongs to the page.** A first publish carries the declared+ `hero.path` into the page repo: adom-wiki 1.8.3+ adds it to a first publish+ itself (on an older CLI, list it in `files[]` or pass `--include-media`). After+ that, change it with `adom-wiki page hero` (push the PNG first). A republish+ never replaces it, and a hero still packed into a republish warns+ `MEDIA_IN_TARBALL`. Full detail: **wiki-hero**. The rest of `page.json` merges:+ - Keys `package.json` sets win (version, title, brief, tags, discovery_triggers,+ files...); keys it omits keep the page's value, and keys you added by hand+ (`kind`, for example) stay.+ - **Set a `title` in `package.json`.** A first publish without one titles the+ page with its slug. The title must be a **human, descriptive name, NEVER the+ slug echo** (`Wiki Hero Image Skill`, not `adom-wiki-hero-image`): cards,+ search, the homepage and the screensaver show it; nobody reads slugs. A title+ edited only in `page.json` is replaced by the next publish that sets one.+ → **wiki-repo-styles** / **wiki-family**.+ - Keep `discovery_triggers` in `package.json` so every publish restates them. A+ `page.json` you push by hand without them keeps the indexed triggers+ (adom/wiki#240 is fixed), it does not clear them. 3. **Text is plain; only binaries are base64.** Base64-encoding a `.md`/`.json`/ `.sh` makes the wiki store the base64 string as the file content → README@@ -97,11 +94,6 @@ README for the hero filename and delete any line that references it. → **wiki- - **Cloudflare WAF blocks Python urllib/requests without a `User-Agent`** → send `User-Agent: `adom-wiki pkg`/2.1.0`. curl sends its own UA and is fine.-- **No need to create the page first (1.8.2).** A first `adom-wiki pkg publish`- creates the page and its repo as one row, and a later `repo push` goes to that same- row. Before 1.8.2, publish-only pages made a tarball but no repo, and a later- `POST /files` inserted a *second* page row (a ghost duplicate): on an older CLI or- server, create the page first. - **Rate limits** are per account when signed in (per IP when anonymous), over a sliding minute. Going over returns HTTP 429 with `{"error":"Rate limit exceeded","retry_after":N,"code":"RATE_LIMITED"}`:@@ -130,9 +122,9 @@ README for the hero filename and delete any line that references it. → **wiki- - [ ] `package.json`: version bumped, `files[]` complete, `dependencies` set - [ ] **Findable**: app/skill pages carry 3+ `discovery_triggers` in the user's own words (in `package.json`, or `adom-wiki discover triggers <ref> --add ...` for a page-only page). A page with none never appears in `discover find`. Check: `adom-wiki discover find "<how a user would ask>"` lists it-- [ ] `adom-wiki pkg publish` succeeded: it creates the page on the first publish and commits `Publish X.Y.Z` to the repo (check `adom-wiki repo log <ref>`; before 1.8.2, create the page first and push all source yourself)-- [ ] Media on the page (hero, README images) is in the repo: published with `--include-media`, or pushed with `adom-wiki repo push`-- [ ] Title, brief, hero and `discovery_triggers` live in `package.json` (publish writes them into `page.json`); check after: `adom-wiki page stats <ref>` shows `hero_path`, and `adom-wiki discover triggers <ref>` lists the triggers+- [ ] `adom-wiki pkg publish` succeeded: the first one creates the page, and every one commits `Publish X.Y.Z` to the repo (check `adom-wiki repo log <ref>`)+- [ ] Anything the package leaves out (screenshots, videos, README images, `.pkgignore`d source) pushed with `adom-wiki repo push`+- [ ] Title, brief and `discovery_triggers` live in `package.json`; the hero rode the first publish or was set with `adom-wiki page hero`. Check: `adom-wiki page stats <ref>` shows `hero_path`, and `adom-wiki discover triggers <ref>` lists the triggers - [ ] **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