# adom-tsci/export-wiki — publishing a tscircuit molecule to the Adom Wiki **Read this before running `adom-tsci export-wiki` on any project.** The CLI is deliberately opinionated: it ships the interactive 3D viewer, the source bundle, the plan.md, AND a comprehensive body markdown to the wiki page in one shot. Skipping any of those pieces makes the page useless to a future viewer (human or AI) — the goal is "another agent can pick up exactly where this one left off" with nothing missing. ## What the CLI does, in order ``` adom-tsci export-wiki [] --slug \ --page-type molecules \ --label "Live 3D viewer" \ [--rebuild] [--texture-resolution N] [--no-upload] ``` 1. **Confirms `dist/lib/index/circuit.json` exists.** Skip-rebuild is the default — `bunx tsci build` can take 10 minutes on dense boards. Pass `--rebuild` to force. **Fallback-dist search** (1.3.91+): if the in-place dist is missing, the CLI looks for an existing dist at known parallel locations before erroring out. Order: `~/project/adom-tsci-projects//dist`, `~/project/adom-tsci/examples//dist`, `~/project/tscircuit-projects//dist`. Picks the freshest by `circuit.json` mtime. Many canonical molecules live in two places (the example-library copy and the local scratch-build copy); only one has a fresh dist at any given moment, and there's no reason to spend 10 minutes rebuilding when the other copy is already there. **The reflex when a build seems missing:** `ls ~/project/adom-tsci-projects//dist/lib/index/circuit.json` FIRST. Only rebuild if neither copy has a fresh dist. The CLI does this automatically now, but the same rule applies to any AI helper debugging "why doesn't this project have a dist?" — search before rebuilding. 2. **Resolves the GLB.** Default = `dist/lib/index/3d.glb` (1024-px texture). Pass `--texture-resolution N` to rebake at higher res (4096 typical for 100–200 mm boards; first bake ~75 s, cache hit ~190 ms). 3. **Stages the viewer bundle** at `/tmp/adom-tsci-export-/`: - `index.html` — `shell.html` rewritten for static hosting (fetch monkeypatch, walkthrough autoplay, all `glb`-style URLs remapped to relative paths). - `js/adom-3d-viewer.min.js`, `js/tscircuit-alphabet.js`, `js/environmentSpecular.env`, `adom.css`, `favicon.svg` — embedded into the binary, copied out at staging time. - `3d.glb`, `circuit.json`, `walkthrough.json`, `pcb.svg`, `schematic.svg` — the project's build artifacts. 4. **Tarballs the viewer bundle** as `-tsci-viewer.tar.gz`. Uploads via `adom-wiki asset upload --asset-type tsci-viewer`. The wiki extracts to `/static///tsci-viewer//` and auto-renders an iframe section on the page. 5. **Builds a separate source bundle** at `/tmp/-source.tar.gz` containing every file an agent would need to recreate the molecule: - `lib/` (recursive) - `package.json` - `tscircuit.config.json` - `tsconfig.json` - `walkthrough.json` - `.npmrc` - **`plan.md`** (or `PLAN.md`) — the design brief. Required by convention; see "plan.md" below. - `README.md` (if present) Excluded: `dist/` (build output) and `node_modules/` (deps). Uploaded as a `file` asset. 6. **Uploads `plan.md` standalone** as a separate `file` asset so the wiki can render a one-click link to it without untar. Failures on steps 5 / 6 are non-fatal — the viewer publish in step 4 is the load-bearing one and lands first. If a transient wiki failure blocks the source-bundle upload, the CLI emits a hint with the retry command. ## Walkthrough autoplay The static export of `shell.html` registers a small bootstrapper that **fires `walkthroughStart()` ~2 s after the page loads**. This is on by default for the wiki context — the walkthrough is the canonical "tour the board" experience for an external viewer who isn't going to know to click anything. It can be opted out with `?autoplay=off` on the iframe URL if a future wiki template wants to defer firing it. The walkthrough is loaded from `walkthrough.json` in the bundle. If the project has no `walkthrough.json`, the autoplay no-ops gracefully (no walkthroughStart call until the array is populated). Generate one with: ```bash adom-tsci walkthrough-gen # auto-generate from circuit.json ``` …or hand-edit `walkthrough.json` directly. The `_meta` block has a `do_not_edit_by_hand` field — set it to a plausible-looking string (e.g. "Hand-edited intentionally") to keep `walkthrough-gen` from overwriting your edits. ## plan.md — the design brief **Every molecule publish should include `plan.md` at the project root.** plan.md is the original prompt the project was authored from, plus the refinements that came out during build. It carries forward to the wiki so a future agent skimming the page can answer: - What was the user actually asking for? - What design decisions were made and why? - What's intentionally out of scope? If the project doesn't have a plan.md when you run `export-wiki`, **create one before publishing**. Reconstruct it from the original prompt + the design conversation; check it into the project root. Skeleton: ```markdown # Plan — ## Original prompt > ## Refinements during the build - ## Hardware decisions - ## Out of scope (deliberate) - ## Build → publish workflow ``` (See `adom-tsci-projects/Brianna-LED-Nameplate/plan.md` for a full example.) The CLI uploads `plan.md` standalone (one-click link on the page) AND inside the source bundle (preserved alongside the rest of the project source). ## The body markdown — comprehensive, AI-readable The wiki page's `content` field — the markdown body — must give a downstream agent everything they'd need to continue work without reading external docs. **The CLI does not write the body for you; you produce it via `adom-wiki page edit --field content` (or as part of `page publish`).** Required sections: | Section | What it captures | |---|---| | **Brief** (above the fold) | One-line elevator pitch. Same as the page brief. | | **Live 3D viewer** | Pointer to the iframe, mention `?autoplay=off` opt-out. | | **How it works** | The circuit story: what each block does, key constants, font/layout source. | | **Hardware summary** table | Block / Part / JLCPCB / Notes for every refdes family. | | **Mechanical** | Board dims, USB-C edge, workcell-pin info, silkscreen choices. | | **Source layout** | The project's directory tree with one-line per file. | | **Build commands** | The exact bash to clone → install → build → preview → publish. | | **Color options / variants** (if applicable) | What's parameterised and how to retune. | | **Known issues / lessons learned** | Things that bit during the build, in case they come up again. | | **Build provenance** | Author, tooling versions, walkthrough authorship. | | **Files attached** | Two sub-lists: **Source — recreate the molecule** (plan.md, source bundle) and **Build outputs** (GLB, SVGs, demo video). | **Rule:** if a future agent has to ask the human user any factual question about the project that they could have answered by reading this page, the body is incomplete. Treat it as a writeup, not a README stub. ## Hero image `adom-wiki page publish` requires `--hero-image ` (the wiki enforces it for non-app pages). The hero image is **the thumbnail** that shows up on the molecule index page — heavy interactive viewers can't be embedded in index lists, so a static iso render is the right artifact for that role. For an adom-tsci-published molecule: - The **index/listing page** uses the `--hero-image` PNG as the thumbnail. - The **full molecule page** has the interactive `tsci-viewer` iframe as its hero (rendered automatically by the wiki when a `tsci_viewer` asset is present). Take the hero image with `adom-cli hydrogen screenshot panel --tab-id ` after setting the camera to `iso` view and hiding the components HUD. ~1500 px wide is plenty. ## Verifying the publish After `export-wiki` returns `OK: published …`, open the molecule URL in a browser: ``` https://wiki-ufypy5dpx93o.adom.cloud/molecules/ ``` Confirm visually: 1. **Walkthrough auto-plays** within ~2 s of page load. Step text appears at the bottom of the iframe with Back/Next controls. 2. **3D scene is rendered** — the board (not the loading screen) is visible. 3. **Source bundle download works** — click the `*-source.tar.gz` link in the body, untar, confirm `lib/index.tsx` and `plan.md` are present. 4. **plan.md link works** — opens directly without untar. If the walkthrough doesn't fire, check the iframe URL has no `?autoplay=off`, and that `walkthrough.json` was non-empty in the bundle (`tar -tzf .tar.gz | grep walkthrough`). ## Troubleshooting | Symptom | Cause | Fix | |---|---|---| | `dist/lib/index/circuit.json not found` | No build artifacts | Pass `--rebuild` or run `bunx tsci build` first | | `--texture-resolution N` warns "no rebake-glb.mjs in cache" | First-time use without prior `adom-tsci start` | Run `adom-tsci start .` once to populate the cache, then re-export | | `bundle is over 95 MB` warning | Big GLB (very high texture res) or many extra files | Drop `--texture-resolution` to 4096 or 2048 | | `adom-wiki upload failed: page-type mismatch` | Slug exists at a different page-type | Either pass the matching `--page-type`, OR delete the existing page first (`adom-wiki page delete /`) | | Source-bundle upload fails but viewer publish succeeds | Transient wiki error | Re-run `adom-wiki asset upload / --asset-type file --file /tmp/-source.tar.gz` manually — the CLI prints this hint | | Walkthrough doesn't auto-play on the wiki page | walkthrough.json missing or empty | Run `adom-tsci walkthrough-gen` in the project, hand-edit if needed, re-export | ## See also - `adom-tsci/guides/demo-recording.md` — making a 30-second narrated demo video to attach to the page (separate workflow; the live viewer is now the primary artifact, demo video is supplementary). - `adom-tsci/guides/adom-usbc.md` — USB-C placement rules for the molecule before you publish. - `adom-wiki` skill — the underlying CLI for asset uploads and page edits.