Adom Wiki

@@ -1,605 +1,38 @@ --- name: adom-wiki-description: Search, read, publish, and upload assets to the Adom Wiki via the adom-wiki CLI. Use when the user mentions "wiki", "publish to wiki", "upload video/screenshot to wiki", "search wiki", "install skill from wiki", "install molecule", "find datasheet", or wants to share a skill/molecule/library/footprint/symbol/3dcomp with the team. Also use proactively before creating a new symbol, footprint, or skill — search the wiki first to avoid duplicating work.+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. --- -# adom-wiki — one skill, one CLI+# The Adom Wiki -The Adom Wiki lives at `https://wiki-ufypy5dpx93o.adom.cloud`. It holds **skills**, **molecules** (breakout boards), **libraries**, **footprints**, **symbols**, **3dcomps**, **apps**, and **datasheets**. Every interaction goes through the `adom-wiki` CLI at `/usr/local/bin/adom-wiki`. **Do not use the MCP `mcp__adom-wiki__*` tools** — they're deprecated and scheduled for removal.+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. -Every CLI invocation prints JSON to stdout. Pipe through `jq` for extraction.+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. -## ⚠ Author identity on publish+## What is on it -Every `page publish`, `page edit`, and `asset upload` gets stamped-with `pub_author_id` + `pub_author_name` on the server, derived from-the bearer token in use. The author stamp is **server-controlled** —-you cannot pass author fields in the body; whoever owns the token-wins. Good security property.+- **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`) -**The CLI hard-blocks shared-identity publishes** (v0.3.1+). If you-run `page publish` / `page edit` / `asset upload` with the shared-fallback token (`adom-wiki-dev-2025`), the CLI exits with:+## Doing things on the wiki -```text-ERROR: cannot publish as the shared "Developer" identity.-Your Adom profile: <name> <<email>>.-Run `adom-wiki set-author` to link it, or re-run with---force-shared if you truly want this page attributed to-"Developer (shared)" (e.g. automated CI without a user token).-```--You don't need to run `whoami` defensively — the CLI refuses the-shared case automatically. Just respond to the error by running-`adom-wiki set-author` (which SSOs the current Adom identity into the-wiki via `/auth/from-carbon` and writes a wiki token to-`~/.config/adom-wiki/token`).--### Flow on a fresh container--```bash-adom-wiki set-author      # one-time per container, links Adom identity-adom-wiki page publish ...   # stamps you as the author-```--### When to use `--force-shared`--Only automated CI / provisioning jobs where no human user is behind-the publish. Pages published with `--force-shared` show up as-`pub_author_name: "Developer (shared)"` — visually distinct on the-/discover listings so reviewers can tell at a glance that the page-was un-attributed.--### Other `set-author` forms--- `adom-wiki whoami` — print the identity your publishes will use.-- `adom-wiki set-author --unset` — delete the token file (revert to shared).-- `adom-wiki set-author --token <T>` — skip SSO, save a raw token (admin-provisioned use).--### If `adom-wiki whoami` is unknown on your CLI (pre-0.3.0)--Older CLIs (before v0.3.0) don't have `whoami` or `set-author`. Upgrade:+Almost everything goes through the **`adompkg`** CLI (see the `adompkg` skill for the full guide):  ```bash-curl -fL https://wiki-ufypy5dpx93o.adom.cloud/static/apps/adom-wiki/adom-wiki-0.3.0 \-  -o /tmp/adom-wiki && chmod +x /tmp/adom-wiki && sudo mv /tmp/adom-wiki /usr/local/bin/adom-wiki-adom-wiki --version   # should be ≥ 0.3.0+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 ``` -Then run `adom-wiki set-author` as above.--### If you need to surface the user's Adom identity yourself--The canonical source of "who is this Adom user?" is the Adom-platform profile, NOT git config (most containers don't have git-configured) and NOT gh (most users don't have a GitHub account-attached). Query it directly:--```bash-adom-cli carbon user get | jq '{id, name, display_name, email}'-# → {"id":"…","name":"john","display_name":"John Lauer","email":"[email protected]"}-```--This always works inside an Adom container because the container-itself is authenticated. When `adom-wiki whoami` doesn't exist or-the token is the fallback, use this to at least show the user the-identity that SHOULD have been attributed:--> "Your Adom profile says **John Lauer** (`[email protected]`). The wiki-> CLI can't attribute that today (shared token). Want me to publish-> under 'Developer' anyway, or wait until you have a wiki token?"--## ⚠ Strict-auth enforcement is ON (as of 2026-05-01)--The wiki container has `WIKI_STRICT_AUTH=1`, which means **every mutation endpoint enforces these on the server** (not just advisory in the CLI):--1. **Real author identity required.** The shared `Developer` / `Developer (shared)` fallback is rejected. Run `adom-wiki set-author` once per container to attach your Carbon identity.-2. **Real `--changelog` required** on every `page publish`, `page edit`, `asset upload`, `asset delete`, `video add`, `video delete`, `skill add`, `skill remove`. Min 10 chars, ≥2 words. Placeholder strings (`release v$VERSION`, `Initial publish from gallia`, `Add metadata`, `update`, `publish`, etc.) are rejected with a 400 + a hint pointing to the canonical changelog-generation pattern in the `tool-publisher` skill.-3. **Service-account flow** for genuine CI: tokens flagged `is_service_account=1` may pass `force_shared=true` plus an explicit `author_name="<bot label>"` to publish under a bot identity. Per-user tokens cannot use that escape hatch.--If your `publish.sh` still emits `release v$VERSION` as the changelog, your next release will fail with a 400. Migrate to the canonical fallback chain documented in `tool-publisher`.--## Workflow X — page log + contributors (mini-repo model)--Every wiki page is treated as a mini repo. Every mutation lands as a row in `page_activity` with kind, author, changelog, and timestamp. Two CLI commands surface that:--```bash-# Like `git log` for a page — every mutation, newest first-adom-wiki page log apps/adom-tsci --limit 20--# Distinct contributors with commit counts and last contribution timestamp-adom-wiki page contributors apps/adom-tsci-```--Use these to understand who touched a page and why. The same activity log renders as a "Recent activity" section on every page in the wiki UI.--## Page references--Pages are addressed as `<type>/<slug>`, for example:-- `apps/adom-desktop`-- `skills/symbol-creator`-- `molecules/drv8411a-breakout`-- `symbols/stm32f103c8t6`--Type is always singular in the ref. The CLI pluralizes where the server needs it.--### What each `<type>` means in Adom--Adom uses page types in a specific narrower sense than "any document". Pick the-right type — the wiki's browse indexes, install prompts, and `discovery_triggers`-matching all branch on it.--| Type | What goes here | What does NOT |-|---|---|---|-| **app** | A user-installable Adom tool with a binary you can run on your container/desktop (e.g. adom-tsci, adom-step, chipsmith). Has an Install prompt that copies the binary + drops SKILL.md. | Internal Rust crates, libraries that are only consumed via Cargo, Claude-only behaviours. |-| **library** | A complete EDA part bundle: symbol + footprint + 3D chip model + variants + the pad↔pin mapping that ties them together. Not a "code library". Example: a wiki page with the LM358D symbol, footprint, 3dcomp, and the connections between them, ready to drop into a schematic. | Rust/JS/Python source-code crates. Single-artifact pages like just a footprint or just a symbol on its own. |-| **symbol** | A single schematic symbol artifact (`.kicad_sym` + provenance). | Code. |-| **footprint** | A single PCB footprint artifact (`.kicad_mod` + provenance). | Code. |-| **3dcomp** | A single 3D component model (`.glb` / `.step` + materials). | Code. |-| **molecule** | A composable PCB module (Adom's hardware lego brick) — KiCad project + 3D + firmware glue. | Single chips. Single artifacts. |-| **skill** | A SKILL.md (Claude Code instructions) explaining when/how to use a thing. The thing itself can be private (private GitHub repo, internal tool) — the skill just teaches Claude/the team. | Tools that are user-installable as binaries (those go under `app`). EDA artifacts. |-| **datasheet** | Manufacturer datasheet PDF + parsed sym/fp/provenance. | |-| **video** | A demo recording. | |--**Common confusion — when a private Rust crate is "just a skill":** if you have-a private GitHub repo (e.g. a parser library that another Adom tool depends on-via Cargo), the wiki page is a **skill**, not a library or app. The skill-documents what the crate does, the public API, the private GH URL, and-`discovery_triggers` so Claude finds it; the source stays private. Library type-is reserved for the EDA-part-bundle meaning above.--## Workflow 1 — search before you build--Before creating any new symbol, footprint, skill, or molecule, check the wiki:--```bash-adom-wiki page search "STM32F103" --limit 10-```--If snippet search returns 0 or the match looks weak, escalate to deep search (enumerates all pages by type and scores matches against title/brief/slug/content):--```bash-adom-wiki page search "that obscure buck converter" --deep --limit 15-```--Deep search is essential for symbols, footprints, libraries, 3dcomps, molecules, and datasheets — their `discovery_triggers` are often sparse.--Inspect a hit:--```bash-adom-wiki page get skills/symbol-creator | jq '.page | {title, brief, version}'-```--## Workflow 2 — publish a page (the full checklist)--Every wiki page MUST have all of the following. The CLI rejects publish if required items are missing — don't try to work around it by editing the markdown, the structured fields are what make the page discoverable and installable.--| # | Item | CLI flag / how to set | Required? |-|---|---|---|---|-| 1 | Title | `--title "..."` | yes |-| 2 | Brief (1-line hook) | `--brief "..."` | yes |-| 3 | Body markdown | `--body-md file.md` | yes |-| 4 | **Sample prompts (3-8)** | `--sample-prompt "LABEL\|PROMPT"` × N | **yes — publish fails without these** |-| 5 | Discovery triggers | set via `page edit --field metadata` | yes |-| 6 | Discovery pitch | set via `page edit --field metadata` | yes |-| 7 | Version (semver) | `--version 1.0.0` (defaults to 1.0.0 on create) | yes on update |-| 8 | Changelog | `--changelog "..."` | yes on update |-| 9 | Thumbnail image | `asset upload --asset-type thumbnail --file ...` | yes for apps |-| 10 | Screenshots (≥2) | `asset upload --asset-type screenshot --file 01-X.png` | yes for apps with a visual surface |-| 11 | Install manifest | `metadata.install.bin` + `post_install` | yes for apps with a CLI binary |-| 12 | Skill source | `--skill-source file` | yes for skill pages |-| 13 | App files | `asset upload --asset-type file --file ...` | yes for installable apps |--### Step-by-step--Follow this order. Each step has a reason — don't skip.--**a. Draft the content** as markdown in `/tmp/page.md`.--**b. Draft 3-8 sample prompts WITH THE USER.** These are what users copy-paste into Claude Code to invoke the tool. Show your draft list, get explicit sign-off. Labels (before the `|`) are one-word summaries shown on the Copy button; the text after the pipe is the actual prompt.--**c. Draft discovery_triggers + discovery_pitch WITH THE USER.** Same rule — show the draft, get sign-off. Past failure: adom-desktop page shipped without "pup", "debug", "screenshot my pc" triggers — had to add them after.--**d. Draft the install prompt with the user.** Every page renders a type-aware "⚡ Install this..." prompt (auto-generated from page type). Confirm it covers everything a user would need.--**e. Publish:**--```bash-adom-wiki page publish apps/myapp \-  --title "My App" \-  --brief "One-line description" \-  --body-md /tmp/page.md \-  --sample-prompt "Open viewer|Open myapp for my project" \-  --sample-prompt "Start session|Start a myapp session for this task" \-  --sample-prompt "Do a ralph loop with myapp"-```--**f. Set metadata (triggers, pitch, install manifest for apps):**--```bash-cat > /tmp/meta.json << 'EOF'-{-  "discovery_triggers": ["myapp", "term1", "term2"],-  "discovery_pitch": "One-line hook for discovery.",-  "install": { "bin": ["myapp"], "post_install": ["myapp install"] }-}-EOF-adom-wiki page edit apps/myapp --field metadata --body-md /tmp/meta.json-```--**g. Upload a thumbnail** (the card image on /apps):--```bash-adom-wiki asset upload apps/myapp --asset-type thumbnail --file card.png-```--**h. Upload screenshots** (at least 2, prefix filenames 01-, 02- for ordering):--```bash-adom-wiki asset upload apps/myapp --asset-type screenshot --file 01-main.png --caption "Main view"-adom-wiki asset upload apps/myapp --asset-type screenshot --file 02-config.png --caption "Config"-```--**i. Upload app files** (for installable apps):--`--caption "<short description>"` is **REQUIRED** when `--asset-type` is-`file` or `docker_binary` — files surfaced in the page's Files section MUST-describe what they are so a reader knows what they're about to download.-Both the CLI and the server enforce this; there is no bypass. Aim for a-crisp one-liner: what the file is + (where useful) version or platform.--```bash-adom-wiki asset upload apps/myapp --asset-type file --file ./myapp \-  --caption "Linux CLI binary v0.4.0 (myapp client; replaces ~/apps/myapp/myapp on install)"-adom-wiki asset upload apps/myapp --asset-type file --file ./config.toml \-  --caption "Default config — drop into ~/apps/myapp/config.toml on first install"-```--If you forget `--caption`, the CLI fails fast with the message:--```-asset_type='file' requires --caption "<short description>" (≥3 chars).-Files in the wiki's Files section must describe what they are so readers-know what they're downloading.-```--The same is true for `--asset-type docker-binary`. Other asset types-(`hero-image`, `screenshot`, `video`, `viewer-html`, `kicad-sym`, etc.)-do NOT require `--caption` — they render with their own UX, not in the-Files section.--**j. Visually verify in pup.** Open the page in a browser, confirm: sample prompts card renders above the install prompt with Copy buttons; thumbnail + screenshots show; no broken markdown (code fences, tables); no console errors. `curl` returning 200 does NOT count as verification.--**k. Test `app install`** end to end if it's an app:--```bash-adom-wiki app install myapp-which myapp && myapp --version-adom-wiki app uninstall myapp-```--### Updating an existing page--Use `page edit` for field-level updates (no version bump):--```bash-adom-wiki page edit apps/myapp --field brief --body-md /tmp/new-brief.txt-adom-wiki page edit apps/myapp --field metadata --body-md /tmp/new-meta.json-adom-wiki page edit apps/myapp --field sample-prompts --body-md /tmp/new-prompts.json-```--For version-bumping changes use `page publish` again with `--version 1.1.0 --changelog "..."`.--### After every publish or edit — show the user the page AND surface the URL--Two things are mandatory after every successful `page publish` / `page edit` /-`asset upload`:--**1. Open the rendered page in a pup window on the user's desktop.** Don't-make them ask:--```bash-adom-desktop browser_open_window '{-  "sessionId":"wiki-<slug>",-  "profile":"wiki-<slug>",-  "url":"https://wiki-ufypy5dpx93o.adom.cloud/<type>/<slug>"-}'-```--Use a stable `sessionId` per page (`wiki-<slug>`) so re-publishes update the-same window instead of opening a new tab. `<type>` is `apps`, `library`,-`symbols`, etc. — match the page type.--**2. Print the page URL as a clickable link in the chat reply.** The user is-often on a different surface than the desktop pup window (mobile, separate-monitor, RC session) and wants a one-click way to open the page they just-shipped. Format:--```text-→ Live: https://wiki-ufypy5dpx93o.adom.cloud/<type>/<slug>-```--Always include this line whenever a wiki publish or asset upload completes-successfully. One short summary sentence + the link is enough — don't bury-the URL inside a paragraph. Past failure: shipped pages and never gave the-user the URL, leaving them to ask "where is it?" — fix is to make the link-the first or last visible artifact of the publish reply.--## Workflow 3 — upload assets (videos, images, files)--Assets attach to a page. Supported `--asset-type` values:--| type | use for |-|---|---|-| `file` | generic files (scripts, configs, docs, binaries) — shown in "Files" explorer on the page |-| `video` | uploaded video files (webm/mp4) from the Adom editor recorder |-| `hero_image` | top-of-page banner + index card — prefer a screenshot of the actual UI/product over a logo or brand asset (see below) |-| `thumbnail` | small index card image (overrides hero on index); also the Apps index card image — same preference as hero |-| `screenshot` | gallery images; prefix filename with `01-`, `02-` for ordering |-| `viewer_html` | interactive sample tab (iframed on the page) |-| `kicad_sym`, `kicad_mod`, `step`, `glb`, `lbr` | EDA files |--### Prefer a UI screenshot for the hero image--The hero image is what shows at the top of the wiki page and in the index card. It should communicate *what the app does* in one glance. A logo or brand favicon usually tells a visitor nothing — they can't tell a VS Code extension from a video editor from a BOM tool.--**Default to a screenshot of the actual running UI.** This is a strong preference, not a hard rule — there are cases where a branded asset or a diagram is the right call (e.g. a tool with no meaningful visual surface, or a repo/ref page where the brand mark *is* the identity). Use judgment, and when in doubt, ask the user.--Good defaults by page type:-- App → screenshot of the main screen (UI, panels, toolbars visible)-- VS Code extension → the extension detail page or it being used in VS Code-- CLI → terminal showing real output, or the companion UI if there is one-- Molecule / symbol / footprint → rendered view of the actual part-- Skill → screenshot of the skill being invoked, or the output it produces--Past failure: I uploaded `favicon-color.png` (the teal Adom logo) as the `adom-vscode` hero image. The user pushed back — the logo doesn't say anything about what the app does. The fix was a screenshot of the VS Code extension detail page showing the Adom VS Code entry with its icon, description, and sidebar. Lean toward UI shots unless there's a specific reason not to.--Upload a demo recording:--```bash-adom-wiki asset upload apps/adom-desktop \-  --asset-type video \-  --file /home/adom/project/recordings/adom-desktop-main-demo.webm \-  --caption "Main demo — screen recording, KiCad plugin, pup debugging"-```--Upload screenshots in order:--```bash-adom-wiki asset upload apps/adom-desktop --asset-type screenshot --file 01-setup.png --caption "Setup"-adom-wiki asset upload apps/adom-desktop --asset-type screenshot --file 02-kicad.png --caption "KiCad plugin"-```--Upload a viewer HTML sample tab (creates a sample tab automatically):--```bash-adom-wiki asset upload skills/symbol-creator \-  --asset-type viewer_html \-  --file preview.html \-  --label "SOT-23 Transistor" \-  --sort-order 1-```--List and delete:--```bash-adom-wiki asset list apps/adom-desktop | jq '.assets[] | {id, asset_type, filename}'-adom-wiki asset delete apps/adom-desktop --asset-id 42-```--After uploading `viewer_html`, verify the tabs render:--```bash-adom-wiki test-samples skills/symbol-creator-```--## Workflow 4 — publish an app to the wiki--End-to-end flow for making an app installable. See `adom-app-model` and-`tool-publisher` for the full lifecycle; this workflow is the wiki-side-steps only.--Two upload shapes depending on the app:--**Shape A — single compiled binary (canonical, used by Tier A + Tier B):**--1. Build the binary locally: `cargo build --release`-2. Publish the page (idempotent):-   `adom-wiki page publish apps/adom-mouser --title "..." --brief "..." --body-md /tmp/page.md`-3. Upload the binary as a `docker_binary` asset (replaces prior on update):-   `adom-wiki asset upload apps/adom-mouser --asset-type docker_binary --file target/release/adom-mouser`-4. Set metadata (see Workflow 10):-   - `metadata.version`: semver — must match `<tool> --version`-   - `metadata.releases.adom_docker.binary_url`: the `/static/apps/...` URL-   - `metadata.releases.adom_docker.install_hint`: one-liner curl that downloads + runs `<tool> install`-   - `metadata.discovery_triggers`: array of phrases for `adom-wiki-discover`-   - `metadata.discovery_pitch`: one-sentence elevator description-5. Verify via pup: the page renders the install prompt, the binary URL returns the expected `--version`.--**Shape B — multi-file app (older pattern, e.g. shotlog):**--1. Draft page content as markdown.-2. `adom-wiki page publish apps/myapp --title "..." --brief "..." --body-md /tmp/myapp.md`-3. Upload files as `file`-type assets: `adom-wiki asset upload apps/myapp --asset-type file --file ./myapp`-4. Set `install.bin` / `install.post_install` in metadata (Workflow 10).-5. Upload thumbnail + screenshots.-6. Test: `adom-wiki app install myapp && adom-wiki app uninstall myapp`--**For both shapes:** always verify rendering in pup before declaring victory.--**Tier A vs Tier B:** both use the SAME wiki assets. The difference is-where the install_hint gets called from:-- Tier A: `gallia/install.mjs` curls it at install time (runs for every user)-- Tier B: `adom-wiki-discover` auto-refreshed skill surfaces the app when-  Claude matches a trigger; Claude pastes the install_hint, user confirms,-  Claude runs it on demand--See `adom-app-model` for the full Tier A/B decision matrix and-`tool-publisher` for the release checklist.--## Workflow 5 — external video embed--For YouTube/Vimeo links (not uploaded files):--```bash-adom-wiki video add apps/adom-desktop \-  --url "https://youtube.com/watch?v=..." \-  --label "Community walkthrough" \-  --video-type youtube-```--Default path for demos is **uploaded webm** via `asset upload --asset-type video`. YouTube/Vimeo is the fallback for community-hosted content.--## Workflow 6 — add a sub-skill / related link--Every mutation now requires `--changelog` (CLI v1.9.0+):--```bash-adom-wiki skill add skills/symbol-creator \-  --url "https://wiki-ufypy5dpx93o.adom.cloud/wiki/skills/kicad-basics" \-  --description "Learn KiCad fundamentals before creating symbols" \-  --changelog "Add kicad-basics as a prerequisite — most symbol-creator users skip it and hit the same gotchas"-```--Remove a sub-skill link:--```bash-adom-wiki skill remove skills/symbol-creator --sub-skill-id 7 \-  --changelog "Drop the dead orcad-import link — that skill was archived"-```--## Workflow 7 — install an app from the wiki--```bash-adom-wiki app install shotlog      # downloads files to ~/apps/shotlog/, bins to /usr/local/bin/-adom-wiki app list                 # list installed apps-adom-wiki app uninstall shotlog    # removes ~/apps/shotlog/ + PATH binaries-```--## Workflow 8 — soft-delete a page--Pages are soft-deleted (recoverable by admin). Reason is required:--```bash-adom-wiki page delete apps/old-app --reason "Superseded by new-app"-```--Admins can view deleted pages at `/admin/pages?status=deleted` and restore them.--## Workflow 9 — edit metadata--Update a page's metadata JSON (e.g., `discovery_triggers`, `install` manifest):--```bash-# Write metadata as JSON to a file, then:-adom-wiki page edit apps/myapp --field metadata --body-md /tmp/metadata.json-```--The file must be valid JSON. This uses the v1 API endpoint which supports metadata.--## Workflow 10 — install content locally--Pull a skill into `~/.claude/skills/`:--```bash-# 1. Find it-adom-wiki page search "symbol creator" --limit 5--# 2. Fetch it-adom-wiki page get skills/symbol-creator | jq -r '.page.skill_source // .page.content' > ~/.claude/skills/symbol-creator/SKILL.md-```--Pull a molecule's KiCad files:--```bash-# List assets-adom-wiki asset list molecules/drv8411a-breakout | jq '.assets[] | select(.asset_type=="kicad_sym" or .asset_type=="kicad_mod" or .asset_type=="step")'--# Download via the page's file_path (served from the wiki's static dir)-```--## Listing--```bash-adom-wiki page list --type molecule --limit 50-adom-wiki page list --type skill --status validated-```--## Auth--The CLI resolves the bearer token in this order:-1. `$ADOM_WIKI_TOKEN`-2. `/var/run/adom/api-key` (container default)-3. `$ADOM_API_KEY`-4. `$X_API_KEY`-5. dev fallback (`adom-wiki-dev-2025`)--Read-only commands (search, get, list, asset list, test-samples) don't require auth.--## Gotchas--- **Every page needs 3-8 sample prompts.** The CLI rejects `page publish` without them, with a helpful hint. Draft them WITH THE USER — you can't guess how users will naturally phrase a request, and the prompts get indexed in FTS so `page search "ralph loop"` can find tools that support that workflow.-- **Never skip the discovery snippet OR install prompt user approval steps.** Both require showing the user the draft text and getting explicit sign-off before publishing. The discovery snippet tells Claude when to suggest the page; the install prompt tells users how to install it. Both are wrong on the first draft — the user always catches missing terms.-- **Visual verification is REQUIRED** after publishing — pup/hydrogen render check, not curl 200. Specifically check: (a) code fences render as monospace blocks (no huge headings inside), (b) markdown tables render as actual tables (not plain text with visible `|` characters), (c) no `<h1>` tags rendered from `# comment` lines inside code blocks. If any of these fail, it's a server-side `simpleMarkdown()` bug — file it, don't try to work around by rewriting the markdown.-- **Slug format** is lowercase-hyphenated (`adom-desktop`, `stm32f103c8t6`). No uppercase, no underscores.-- **viewer_html assets auto-create sample tabs** — use `--label` and `--sort-order` to name and order them.-- **Large video uploads** (>50 MB) work fine; the CLI has a 3-minute HTTP timeout.-- **Use `--deep` search liberally** for symbols/footprints/libraries/3dcomps/datasheets/molecules.-- **`app install` requires `file`-type assets** on the page. Upload files first with `asset upload --asset-type file`.-- **Apps install to `~/apps/<slug>/`** — not `/home/adom/project/`. Binaries go to `/usr/local/bin/` via the metadata manifest.-- **Delete is soft** — pages are hidden from public view but preserved in the database. Admins can restore.-- **Always verify wiki health from the PUBLIC URL, not localhost.** After any-  wiki restart or deploy, end the verification with a `curl` against the-  `https://...adom.cloud/health` URL, not `http://127.0.0.1:8785/health`.-  Localhost only proves the process is bound to a port; it does NOT prove-  the Adom edge / Cloudflare path is routing traffic to it. A prior-  outage had localhost reporting healthy while the public URL was 404-  from Cloudflare — "wiki is up" claims based on localhost were wrong-  from every user's perspective. Same principle applies to any service-  behind a reverse proxy / CDN: test the user's actual path, not the-  process's bind.--## Every artifact needs a provenance line--When publishing **any** wiki page that includes images, generated diagrams, rendered symbols/footprints, embedded iframes, or extracted data tables, each of those artifacts MUST be followed by a one-line **provenance** caption. Format:--```markdown-> **Provenance — <short artifact name>.** <Who or what produced this>. <What it is NOT — call out the source the reader might wrongly assume.> <Inputs / dependencies / fallbacks.>-```--Rendered as a Markdown blockquote so it's visually distinct from body prose. The reason: humans scanning a wiki page need to be able to trust evidence at a glance — if they have to ask "did you draw this or did the datasheet?", the caption is missing.--Categories that always need provenance:--| Artifact | Provenance must name |-|---|---|-| PDF-cropped figure | original page number + figure caption + the cropper that ran (`crop_figures.py`, manual `convert -crop`, etc.) |-| Generated symbol render | which tool (`sym_create`, hand-authored), input pin spec source |-| Generated footprint render | which tool (`generateFootprintViewer()`, custom script), KiCad service status (live render vs. local fallback) |-| Interactive iframe | which generator template, file path, key features wired by the template vs. by hand |-| Pinout / specs table | datasheet page + table number, OR community source URL |-| Photo / 3D render | manufacturer source URL OR the renderer + inputs |--Skipping provenance is a wiki-quality bug. The rule was added 2026-04-18 after a user call-out — *"you MUST tell how you created that example or evidence."* See [human-ui-patterns SKILL.md](../human-ui-patterns/SKILL.md) for the general UI principle.--## Hero images on every datasheet (and other browsable pages)--Every page type that can appear in a browse / index view — `datasheet`, `symbol`, `footprint`, `3dcomp`, `molecule`, `library`, `app`, `skill`, `video` — **must** carry a `hero-image` asset. This is the single image the wiki index uses to let a human visually identify the page at a glance.--### Rules for `publish`--When running `adom-wiki page publish` for a datasheet (or any of the above types):+Browse a page in a webview at `https://wiki.adom.inc/<owner>/<slug>`. -1. **Upload exactly one `--asset-type hero-image` in the same session as publish.** If the parse produced no suitable hero candidate, pick one from the cropped figures (prefer block diagram / architecture / product photo) and upload it as the hero. Do not leave the hero slot empty — datasheets without a hero image are nearly unusable in the index.-2. **For datasheets specifically**, the hero should be:-   - A product photo of the chip if the datasheet PDF contains one (rare for FPGAs / MCUs), **or**-   - The top-view block diagram / architecture figure (common on page 1-3 of most datasheets), **or**-   - A clean pinout diagram if neither of the above exists.-   - **Not** a schematic symbol (that's an interior detail), **not** a footprint drawing (same reason).-3. **Also emit the hero to any live visualizer.** The datasheet-parser / datasheet-parser-interactive skills must call `emit_hero <url> <caption>` on the visualizer so a human watching the parse can confirm "yes this is the right chip" before the page is published. This is part of the signoff gate.+## Before you create something new -### Browse index consumer contract+Search the wiki first (`adompkg search`) before authoring a new skill, symbol, or footprint, so you do not duplicate work that already exists. -The wiki datasheet index (`/datasheets/`) MUST render the `hero-image` asset as a 120–200 px thumbnail in every row. A row with a missing hero gets a deterministic slug-derived placeholder (first 2–3 letters + a colour), never a blank square — blank squares destroy scannability and make the index feel broken.+## Authentication -If you find that `hero-image` assets aren't surfacing on the index page, that's a bug in the wiki frontend, not a workaround-by-renaming problem. File it, don't work around it.+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`.