Reference guide

Commands and setup

How to run, build and package both apps, with the settings that change their behaviour.

Ad Shots

Command	What it does
`npm run dev`	Runs the editor in the browser at http://127.0.0.1:3002
`npm run desktop`	Runs the Electron app
`npm run build`	Type-checks and builds the editor
`npm run build:server`	Bundles the local API for the packaged app
`npm run dist:mac:install`	Builds the Mac app and installs it to Applications
`npm run dist:win`	Builds the Windows app
`npm run test`	Runs the tests

Packaging Review

Command	What it does
`npm run review`	Runs it in the browser at http://127.0.0.1:3004
`npm run review:desktop`	Runs the desktop app
`npm run review:dist:mac:install`	Builds and installs the Mac app
`npm run review:dist:win`	Builds the Windows app

Packaging models

Command	What it does
`packaging/build.sh all --variants`	Builds every model
`packaging/build.sh coverage`	Shows what is done, missing, failing or stale

Working without API keys

These settings make the app use stand-ins, so no keys are needed and nothing is spent.

Setting	Effect
`AD_SHOTS_AI_MOCK=1`	A scripted agent, with mock vectors and images
`AD_SHOTS_QUIVER_MOCK=1`	Mock vectors only
`AD_SHOTS_IMAGE_MOCK=1`	Mock reference images only
`AD_SHOTS_PHOTOROOM_MOCK=echo`	Returns the product render unchanged as the "background"

Folders you can redirect

Setting	Default
`AD_SHOTS_LIBRARY`	`/Volumes/MAKER_DEVELOPMENT/LIBRARY`
`AD_SHOTS_PACKAGING`	`packaging/out`
`FREECADCMD`	Found per platform
`REVIEW_HDRIS`	`LIBRARY/HDRIS`

Branches

main holds the shipped app. Feature work happens on a small branch and is merged when approved. Packaging work is on packaging, packaging-claude and packaging-codex.

This wiki

Pages are Markdown files in wiki/content/. node wiki/build.mjs builds the site into wiki/site/.

Updated 2026-11-14. Built 2026-11-15.