Adom Wiki

@@ -0,0 +1,605 @@+---+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.+---++# adom-wiki — one skill, one CLI++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.++Every CLI invocation prints JSON to stdout. Pipe through `jq` for extraction.++## ⚠ Author identity on publish++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.++**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:++```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:++```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+```++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):++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.++### Browse index consumer contract++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.++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.