---
name: adom-wiki
user-invocable: true
description: "How the Adom Wiki (wiki.adom.inc) actually works, and how to drive it end to end with the adom-wiki CLI. READ THIS FIRST before publishing, hosting source, sharing a tool, or installing from the wiki. Covers the two storage layers (git page repo vs package registry, which are NOT synced), how to host source (push files, never a tarball), how to make a package and cut per-platform releases, the three-tier skill layout (user skills ship; dev-skills/ and publish-skills/ stay source-only), and a decision table. adom-wiki is the current tool; adompkg and any wiki-v1/v2 or *.adom.cloud slug host are DEPRECATED and dead. Triggers: publish to wiki, host source, share/distribute a tool or CLI or skill, make a package, cut a release, Files tab, clone a wiki page, how does the wiki work, wiki.adom.inc, adompkg, dev skills, publish skills, user skills, dev-skills, publish-skills, keep skills out of the tarball, how to structure skills, why won't my skill publish, dev skill blocked on publish, confirmed_user_skills, skill in the wrong folder, make a skill for my app, standalone skill package, skill in app repo vs separate package."
---

# How the Adom Wiki works

The Adom Wiki (wiki.adom.inc) is a package registry plus a git-backed page per
project. You drive ALL of it with one tool: the `adom-wiki` CLI.

- `adom-wiki` is the current, canonical CLI. Install it once, then `adom-wiki --help`.
- `adompkg` is DEPRECATED. So are "wiki v1", "wiki v2", and any `*.adom.cloud`
  slug host (e.g. `wiki-ufypy5dpx93o.adom.cloud`). If a skill or doc tells you to
  use those, it is stale. The only host is `https://wiki.adom.inc`.

## Bootstrap: adom-wiki is missing or outdated

This skill assumes you HAVE the current `adom-wiki`. If commands fail, check
that first -- an old binary strands you with confusing errors:

- `adom-wiki pkg install ...` fails with **"unrecognized subcommand"**: the old
  binary predates the `pkg` / `repo` / `release` verbs.
- `adom-wiki url` prints a `*.adom.cloud` host: that host is dead.
- The version LOOKS newer but is not: the old CLI reached v1.12.x before the
  rewrite restarted versioning at 1.0.x, so **v1.12.2 is OLDER than v1.0.22**.
  Do not trust a bigger number; trust the host `adom-wiki url` prints.
- `adom-wiki app install ...` is an old-binary verb; it does not exist anymore.

The fix is one command, which installs the current CLI and the core workspace
from the live registry (also the fix when `adom-wiki` is missing entirely):

```bash
bash <(curl -fsSL https://wiki.adom.inc/static/bootstrap.sh) adom/core
```

Verify with `adom-wiki --version` and `adom-wiki url` (must print
wiki.adom.inc). From then on the CLI keeps itself current via
`adom-wiki self-update`, and `adom-wiki pkg update` refreshes it in bulk.

## The two storage layers (they are NOT synced)

Every page has two independent layers. Writing one does not change the other.

1. **The git page repo** = the Files tab, the rendered README, commit history.
   You write it by **pushing files** (`adom-wiki repo push`). This is where your
   SOURCE lives. Readers browse it in the Files tab or `adom-wiki repo clone`.
2. **The package registry** = versions, dist-tags, the installable tarball.
   You write it by **publishing** (`adom-wiki pkg publish`). This is what
   `adom-wiki pkg install` consumes.

A file you push does not appear as a package version, and a version you publish
does not change the Files tab. Keep both in mind.

## Host source the right way: push files, never a tarball

The page IS a git repo, so host source by pushing the actual files into it. They
render in the Files tab in place and readers can clone them.

- DO: `adom-wiki repo push <owner>/<slug>` (or commit + push) so the source files
  land in the repo. Point people at `adom-wiki repo clone <owner>/<slug>` and the
  Files-tab URL `https://wiki.adom.inc/<owner>/<slug>`.
- DO NOT: attach a `source.tar.gz` / `.bundle` and tell people to `tar xzf` or
  clone the bundle. A tarball of source on a git-backed page is an anti-pattern.

## Package vs release: install payload vs downloadable binaries

These are different things; do not conflate them.

- **Package** (`pkg publish` / `pkg install`): the install payload. It is the
  manifest + install scripts + bundled skills, and it is resolved **per platform**
  on install. `adom-wiki pkg install <ref>` fetches only the current version's
  tarball for the consumer's platform, then runs its install script. It does NOT
  pull every asset on the page.
- **Release asset** (`release upload` / `release download`): a downloadable
  binary, tagged with a coarse platform (`any` / `linux` / `windows` / `macos`).
  It is anonymously downloadable but is NOT auto-installed. This is how you host,
  say, a Windows installer that a laptop fetches directly while a Linux
  `pkg install` ignores it.

So a tool that ships a Linux CLI + skills + a Windows installer:
push the source to the repo; publish the package (manifest + scripts + skills);
`release upload --platform linux <cli>` and `release upload --platform windows
<installer>`. A Linux consumer installs the package (CLI + skills) and never pulls
the Windows installer; the laptop downloads the Windows asset directly by URL.

## Dependencies on the page come from the PUBLISHED package (not repo push)

The Dependencies tab/graph and the "Used by" list are fed ONLY by the
`dependencies` in the last PUBLISHED package version. Declaring dependencies in
package.json and `repo push`-ing it does NOT populate the graph ("Depends on
0") -- the repo layer is your source, the registry layer is what the graph
reads. To make an edge appear you must `pkg publish`.

Worked recipe -- link one component page as a dependency of another (a board
depending on a part):

```bash
# 1. the TARGET part page must be published (a page that exists only as a repo
#    is not a package the resolver can see)
cd part/ && adom-wiki pkg publish --org adom

# 2. declare the dep in the DEPENDENT board's package.json, owner-qualified:
#    "dependencies": { "adom/<part-slug>": "^1.0.0" }

# 3. publish the board -- THIS is what draws the edge
cd board/ && adom-wiki pkg publish --org adom
```

After step 3 the board's Dependencies graph shows the part, and the part's
page lists the board under Dependents. Re-publish after any dependency change;
repo-pushing the edited package.json alone changes nothing on the graph.

## Make a package and cut a release (exact verbs)

```bash
# 1. scaffold or edit a package dir (package.json + README + SKILL.md + scripts)
adom-wiki pkg init <slug> --type app        # app | skill | component | bootstrap

# 2. publish a version (metadata comes from package.json; no flags to re-supply)
adom-wiki pkg publish [--org <org>]          # bump package.json "version" to re-publish

# 3. upload per-platform downloadable binaries to that version
adom-wiki release upload <owner>/<slug> <version> <file> --platform linux

# 4. set who can see what (three axes)
adom-wiki page visibility <owner>/<slug> --preset open|licensed|preview|private

# 5. install / clone
adom-wiki pkg install <owner>/<slug>         # platform-aware install payload
adom-wiki repo clone <owner>/<slug>          # browse / get the source
```

Add `--json` to any command for a `{ status, data, hints[] }` envelope. **Read the
hints**: each carries a ready-to-run `cmd` for the next step.

## Skill types: the three-tier layout (user, dev, publish)

### First: a skill in an app, or a standalone skill package?

Before the three tiers, one decision people get wrong constantly. When you make
"a skill for my app", it belongs **inside that app's repo** as
`skills/<name>/SKILL.md` — it ships with the app and shows on the app's Skills
tab. **Do NOT create a separate wiki package/page for it.** A standalone skill
package (its own page, its own `pkg publish`) is only for a **reusable skill that
many apps or agents share** (e.g. `adom/google`, or this `adom/wiki` skill).

- Skill belongs to one app → a file in that app's repo (`skills/<name>/SKILL.md`).
- Skill is general / reused across apps → its own standalone skill package.

`pkg init --type skill` and the first `pkg publish` of a standalone skill both
emit an `APP_SKILL_LOCATION` hint reminding you of this, because the default AI
move — spinning up a separate skill repo for an app — is almost always wrong.

### The three tiers (within an app)

Every app should ship a skill, but not every skill you write should reach the
people who install the app. Skills come in **three types**, sorted by a top-level
directory. The directory IS the type — nothing about the type goes in the
SKILL.md frontmatter.

| Directory | Type | For | Examples | In install tarball? | On the page? |
|---|---|---|---|---|---|
| `skills/` | **User** | everyone who installs the app; user-invocable | "deploy my app", "connect to a device", "run a scan" | YES | YES |
| `dev-skills/` | **Dev** | whoever checks out the SOURCE: build, debug, test | "run the test suite", "cross-compile", "debug the daemon", "regenerate fixtures" | NO | YES |
| `publish-skills/` | **Publish** | the app→wiki glue: how to release/publish THIS app | "cut a release", "bump the version and republish", "update the hero/screenshots" | NO | YES |

A root-level `SKILL.md` (no directory) counts as a **User** skill.

### How each type reaches the wiki (the whole point)

There are two storage layers (see above), and the types map onto them:

- **User skills ride the package layer.** `pkg publish` bundles `skills/` + the
  root `SKILL.md` into the install tarball, so every `pkg install` gets them.
- **Dev + Publish skills are source.** `pkg publish` / `pkg pack` **auto-exclude**
  `dev-skills/` and `publish-skills/` from the tarball — you never have to
  remember to strip them. They reach the wiki the way ALL your source does: a
  **`repo push`** into the git page repo (the Files tab). Publish does NOT push
  them for you.

So the normal flow is two commands: `pkg publish` (ships the user skills to
installers) and `repo push` (puts your source — including the dev/publish skills
— on the page). On every pack/publish the CLI prints a `SKILL_LAYOUT` hint with
the split and, when dev/publish tiers exist, the exact command to run:

```bash
adom-wiki repo push <owner>/<slug> --files dev-skills publish-skills -m "add dev/publish skills"
```

### Where they show up

The page's **Skills tab** splits into three sub-tabs — **User | Dev | Publish** —
read from the git repo (with a `?` tooltip explaining the types). A visitor
browsing the page sees all three tiers; a consumer who `pkg install`s the app
gets only the User tier. That is the point of the split: teach/collaborate with
the full set, ship only what users invoke.

### Which type is it?

If a skill is only useful with the source in front of you (running the build,
wiring a release), it is a **dev** or **publish** skill → `dev-skills/` or
`publish-skills/`. If a user of the *installed* app would invoke it, it is a
**user** skill → `skills/`.

### Publish enforces it (so a dev skill can't leak)

Putting a skill in the wrong folder is the easy mistake — a build/test/release
skill dropped into `skills/` would ship to every install. So `pkg publish`
**reads each `skills/<slug>` SKILL.md and blocks the publish** when one reads like
dev or publish work (its description mentions e.g. "test suite", "cross-compile",
"cut a release", "bump the version"). It names the skill and the fix. The message
is the only thing that catches this — the folder exclusion can't, because the
skill is in the wrong folder.

If it is a false positive — a genuine user skill for a tool that legitimately
talks about tests or releases (e.g. this CLI's own user skill) — confirm it in
package.json. This is the one override, kept in the manifest (never in the
SKILL.md), per-skill:

```json
{ "confirmed_user_skills": ["my-user-skill-slug"] }
```

(or `pkg publish --skip-lint` to bypass all soft checks at once).

### Writing a good skill (any type)

- YAML frontmatter with `name` and a rich, **trigger-laden `description`** — the
  real phrases someone would say. Discovery search and the agent match on this;
  a vague description makes the skill unfindable.
- User skills add `user-invocable: true`.
- Body teaches the **fastest path to the one job**, not an exhaustive reference.
  One skill = one clear job; split a second job into a second skill.
- Keep dev/publish descriptions concrete about the source task ("run `cargo test`
  and read the failures", not "testing").

## Component pages: publish gates and the type is forever

- `pkg publish` of a `component` is HARD-GATED server-side (not bypassable
  with `--skip-lint`): the tarball must include a hero screenshot image AND at
  least one 3D source file (`.step`, `.stp`, or `.glb`). A schematic-only
  board with no layout still needs a placeholder 3D file to publish at all.
- A page's `type` is IMMUTABLE after creation. There is no convert; a page
  created as the wrong type must be hard-deleted and recreated. Tools that
  filter by type (e.g. the board browser lists only `type=component`) will
  never see a mis-typed page, so create it as `component` from the start:
  `adom-wiki pkg init <slug> --type component`.

## Decision table

| You want to | Do this |
|---|---|
| Read the docs | open the README on the page |
| Browse / share source | push files to the repo, link the Files tab; do NOT attach a tarball |
| Get a local copy of source | `adom-wiki repo clone <owner>/<slug>` |
| Distribute an installable (CLI + skills) | `adom-wiki pkg publish`, consumers `adom-wiki pkg install` |
| Make a skill for your app | put it in the app's repo as `skills/<name>/SKILL.md`; do NOT create a separate skill package (that's only for reusable, cross-app skills) |
| Keep a build/debug/test or publish skill out of installs | put it in `dev-skills/` or `publish-skills/`; it stays in source, never in the tarball |
| Host a downloadable binary (e.g. Windows installer) | `adom-wiki release upload <ref> <ver> <file> --platform <os>` |
| Re-ship a new version | bump `version` in package.json, `adom-wiki pkg publish` |
| Remove a superseded asset | `adom-wiki release delete-asset <ref> <ver> <file>` |

## Anti-patterns (these are why agents get lost)

- Reaching for `adompkg` (deprecated). Use `adom-wiki`.
- Pointing at a `*.adom.cloud` slug host or "wiki v1/v2". The host is wiki.adom.inc.
- Shipping source as a `source.tar.gz` / `.bundle`. Push files instead.
- Assuming `pkg install` drags down every page asset. It fetches one per-platform
  tarball.
- Re-supplying title/hero/body to bump a version. Metadata lives in package.json.
- Dumping build/debug/publish skills into `skills/` so they ship to every install.
  Put them in `dev-skills/` or `publish-skills/` — publish auto-keeps them out.