Adom Wiki

@@ -1,38 +1,105 @@ --- name: adom-wiki-description: Browse, search, and use the Adom wiki and package registry at wiki.adom.inc (a git-backed wiki with an npm-style package manager, adompkg). Use when the user mentions the wiki, finding or sharing a skill, molecule, symbol, footprint, library, or datasheet, or asks where something lives. For publishing and installing packages, see the adompkg skill.+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, 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." --- -# The Adom Wiki+# How the Adom Wiki works -The Adom wiki lives at **`https://wiki.adom.inc`**. It is a git-backed wiki with an npm-style package registry on top: every page is a git repo, and packages (skills, apps, components, bootstraps) have versions, tarballs, and dependency resolution.+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. -This is the one and only Adom wiki. Any older wiki host or `adom-wiki` CLI you see referenced elsewhere is retired; do not use it.+- `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`. -## What is on it+## The two storage layers (they are NOT synced) -- **skills** and **apps** that agents install (`adompkg install <owner>/<slug>`)-- **components** (symbols, footprints, 3D models) for hardware work-- **bootstraps** (curated dependency bundles, e.g. `adom/core`)-- pages are owned `owner/slug` (a person like `kyle/foo` or an org like `adom/foo`)+Every page has two independent layers. Writing one does not change the other. -## Doing things on the wiki+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. -Almost everything goes through the **`adompkg`** CLI (see the `adompkg` skill for the full guide):+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.++## Make a package and cut a release (exact verbs)  ```bash-adompkg search <query>            # find a package-adompkg info <owner>/<slug>       # description, versions, deps-adompkg install <owner>/<slug>    # install a skill/app (with deps)-adompkg publish --org <org>       # publish the current directory+# 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 ``` -Browse a page in a webview at `https://wiki.adom.inc/<owner>/<slug>`.+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. -## Before you create something new+## Decision table -Search the wiki first (`adompkg search`) before authoring a new skill, symbol, or footprint, so you do not duplicate work that already exists.+| 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` |+| 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>` | -## Authentication+## Anti-patterns (these are why agents get lost) -Write operations use a bearer token (a Carbon API key); the CLI reads it from `/var/run/adom/api-key` automatically on an Adom box, or from `ADOMPKG_TOKEN`.+- 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.