cd <staging-dir>          # holds package.json, bin/, src/, skills/, SKILL.md, README.md, LICENSE, screenshots/
adompkg publish --org adom --public --version <next> --yes

---
name: adom-shotlog-publishing
description: "How to publish adom-shotlog (and apps like it) to wiki.adom.inc with adompkg - org ownership, OSS source, MIT license, hero, and the wiki traps that waste hours (visibility re-privatization, hero caching, binary overwrite, title vs slug). Use when: publishing/republishing adom-shotlog, cutting a release, fixing an unlisted/privatized page, a stale hero, or bundling sub-skills. Trigger words: publish shotlog, adompkg publish, republish, wiki release, hero not updating, page went private, visibility trap, bundle sub-skills, org owned, publish rules."
---

# Publishing adom-shotlog to wiki.adom.inc

The whole app - CLI binary, source, README, main skill, AND sub-skills - ships as
**one package**: `adom/adom-shotlog`. Do NOT create separate wiki pages/repos for
the skills; they live in THIS repo and ride along.

## The publish command

```bash
cd <staging-dir>          # holds package.json, bin/, src/, skills/, SKILL.md, README.md, LICENSE, screenshots/
adompkg publish --org adom --public --version <next> --yes
```

- **`--org adom`** → the page is **org-owned** (`/adom/adom-shotlog`), not
  user-owned. (The `author_name` sidebar shows the publishing employee and is
  **immutable via the API** - that's attribution, not ownership.)
- **`--public`** → anyone can install/view.
- **Version must bump every publish** - you cannot republish the same version.
  Keep `Cargo.toml`, `VERSION`, and `package.json` version in lockstep, and rebuild
  so the binary's `--version` matches what the page advertises.

## package.json essentials

- `slug: "adom-shotlog"` (install name) vs `title: "Adom Shotlog"` (display heading).
  They're different on purpose - slug stays kebab, title is human.
- `license: "MIT"` + ship a real **`LICENSE`** file (© Adom Industries) + set
  `license`/`authors` in `Cargo.toml`. Metadata alone isn't enough for OSS.
- `hero: { path: "screenshots/hero.png" }` - REQUIRED; publish refuses without it.
- `bundled: true`, a `tags` array, and `files` **must whitelist everything that
  should be browseable/installed**, including source + sub-skills:
  `["SKILL.md","skills/**","README.md","package.json","install.sh","uninstall.sh","bin/**","screenshots/**","src/**","Cargo.toml","Cargo.lock","build.sh","VERSION","LICENSE"]`
  (Only what's in `files` reaches the git repo / Files tab - omit `src/**` and the
  source is NOT browseable.)
- `install.sh` deploys the binary AND loops `skills/*/` to install every sub-skill.

## The traps (learned the hard way)

1. **Visibility re-privatization.** A `POST /files` or a metadata `PUT` on a public
   org page silently flips `visibility` back to private. **Fix: don't poke files
   piecemeal - do a bumped `adompkg publish --org adom --public`,** which
   re-publicizes. After publishing, **verify anonymously**:
   ```bash
   curl -s -o /dev/null -w "%{http_code}\n" https://wiki.adom.inc/adom/adom-shotlog
   curl -s -o /dev/null -w "%{http_code}\n" https://wiki.adom.inc/api/packages/adom/adom-shotlog/<ver>/manifest
   ```
   Both must be `200`.
2. **Hero caching by URL.** The hero blob URL (`/blob/app/adom-shotlog/screenshots/hero.png`)
   is cached by browser + CDN; overwriting the SAME path serves the stale image.
   You should NOT have to rename the file - the platform should cache-bust by
   content hash. Until it does, if a hero looks stale, confirm the served bytes
   (`curl … | md5sum`) match your new file; it's a cache, not a regression.
   (Logged for Colby - don't normalize the rename-the-file workaround.)
3. **Binary overwrite.** Overwriting a binary at the same repo path can no-op
   (`commit:null`). A version bump + republish sidesteps it.
4. **Overview vs Files lag.** The Overview tab renders a `readme` DB field set from
   the **tarball** README at publish time - a bare `git push` of README updates the
   Files tab but not the Overview. Republish to refresh Overview.

## After EVERY publish

- Verify anon `200` (above).
- **Show it in pup** (public page → pup): open/refresh the page, screenshot, look.
  A `200` proves nothing about what the human sees.
- Retiring an old slug (e.g. the pre-rename `adom/shotlog`)? `adompkg delete
  <owner>/<slug> --confirm` is a **soft, reversible** delete (`adompkg undelete`).
  It breaks `adompkg install <old>`, so mention the migration.