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 [<project>] --slug <wiki-slug> \
    --page-type molecules \
    --label "Live 3D viewer" \
    [--rebuild] [--texture-resolution N] [--no-upload]

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/<basename>/dist,
~/project/adom-tsci/examples/<basename>/dist,
~/project/tscircuit-projects/<basename>/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/<name>/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.
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).
Stages the viewer bundle at /tmp/adom-tsci-export-<slug>/:
- 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.
Tarballs the viewer bundle as
<slug>-tsci-viewer.tar.gz. Uploads via adom-wiki asset upload --asset-type tsci-viewer. The wiki extracts to
/static/<page-type-plural>/<slug>/tsci-viewer/<label-slug>/ and
auto-renders an iframe section on the page.
Builds a separate source bundle at
/tmp/<slug>-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.
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:

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:

# Plan — <Project Name>

## Original prompt

> <copy the user's first ask verbatim>

## Refinements during the build

- <each meaningful refinement, one bullet per>

## Hardware decisions

- <each component choice with rationale>

## Out of scope (deliberate)

- <what was explicitly NOT built and why>

## 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 <path> (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 <brianna-tab> 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/<slug>

Confirm visually:

Walkthrough auto-plays within ~2 s of page load. Step text
appears at the bottom of the iframe with Back/Next controls.
3D scene is rendered — the board (not the loading screen) is
visible.
Source bundle download works — click the *-source.tar.gz
link in the body, untar, confirm lib/index.tsx and plan.md
are present.
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 <bundle>.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 <type>/<slug>`)
Source-bundle upload fails but viewer publish succeeds	Transient wiki error	Re-run `adom-wiki asset upload <page>/<slug> --asset-type file --file /tmp/<slug>-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

adom-tsci — Tscircuit Board Viewer