Your command reference.

Start with a store you can see

Prefer a guided learning path? Start the ten-lesson field guide. The maintained chapters are also in this folder’s lessons/ directory. This page is the compact command reference for the current local sample.

This guide accompanies the local delivery prototype of AI Commerce Starter. You can browse sample products, create a test order, edit product wording in Admin and rehearse a database recovery. The $299 Standard package is still in development. Real payments and a public launch are not available in this prototype.

You need Docker Desktop (or Docker Engine with Compose v2), Node.js 22.14 or later in the 22 series, and this example folder. The first build downloads dependencies. Start Docker before you begin. We recommend at least 4 GB available to Docker for this development build; this is not a tested minimum or a capacity promise.

In your AI coding tool, open the examples/commerce-starter folder. Then use this prompt:

I am a seller without a development background. Read this folder’s README.md and AGENTS.md. Check that Docker Compose and Node 22 are available, and that local port 9421 is free. Explain where to open the terminal. Run only the documented local setup. Do not read secret values into your answer, delete volumes, change an existing project, or open a cloud account. Show me the shop URL and whether the three demo services are healthy.

Run these commands from the example folder, one at a time:

npm run setup
npm start
npm run status

Success looks like three healthy services. Open your local sample store only after startup completes. This link opens the store on your computer; it is not a public hosted demo. If you chose a different port in your private settings, use that port instead.

The setup creates random local passwords once. Existing settings and data are preserved. The Admin login email is owner@mint-demo.test; find DEMO_ADMIN_PASSWORD in your local .env yourself. Do not paste the password, the full file, payment keys or customer data into an AI conversation.

Make your first test order

1. Choose Everyday pouch, select a color and add one to your bag.
2. Choose Review test checkout. It uses Demo Buyer at a synthetic US address.
3. Check the amount: $24 for the pouch, $5 test delivery, $0 test tax, $29 total.
4. Choose Place test order. Save the order number shown on the confirmation.
5. Open Store Admin and find that order in Orders. Test payment may appear as authorized in Admin; no card was charged and nothing will be shipped.

The native commerce backend calculates prices and checks inventory. Your browser only remembers a cart ID and the latest test order ID. Reloading the page does not erase the database. If a checkout times out, keep the same bag and recover its saved result; do not create a fresh bag just to repeat payment.

To run the repeatable engineering check:

npm run verify

This creates another synthetic order, tests invalid quantities and price changes, retries the same checkout, reads the order through authenticated Admin and restarts this example’s services. Run it when you are not manually editing the store. It saves a local verification receipt and proves no real payment.

Bring your product facts to AI

Prepare a title, materials, size, available colors, care instructions you have verified, and your own product pictures. Leave unknown facts blank. The current sample image path supports the included SVG files; customer uploads and remote image hosting are not implemented yet.

Open AI draft desk from the shop footer. It uses your existing AI tool, without requesting an API key:

1. Enter verified facts and choose Make my AI prompt.
2. Copy the prompt into the AI tool you already use.
3. Paste its JSON response back into the desk and choose Preview draft.
4. Check every claim. Remove unsupported certifications, care, health, shipping and quality claims.
5. Mark the review checkbox and copy the wording you approved.
6. In Admin, open the product, edit its title or description, paste only the appropriate wording into each field, and save. Refresh its page in the shop to verify the result.

The desk accepts only title, description and FAQ fields. It rejects extra fields such as prices, stock or order operations. Its validator checks format and size; you still check factual accuracy. Changing the source facts or pasted draft clears the previous review. The desk cannot publish or write to your catalog.

Make one small change with AI

Start with your brand name or a heading. Keep your product facts separate from design changes.

In this standalone example, change the shop’s visible brand name to [MY BRAND] and the homepage heading to [MY HEADING]. Keep the cart, prices, inventory, test payment mode and backend APIs unchanged. Read AGENTS.md first. Show the files changed, rebuild using npm start, and check the homepage and a product page on a narrow screen. Do not commit unrelated files. Tell me exactly how to undo just this change.

The theme lives in storefront/index.html and storefront/shop.css. Edit these source files rather than generated build output. Product wording saved in Admin lives in the database, not in the HTML. Running setup again is not a way to change the catalog.

Back up, then prove you can restore

After creating a test order, run:

npm run backup
npm run restore:check

The backup command creates a PostgreSQL dump and checksum inside .local/backups. The restore check creates a new temporary database, restores the dump, checks the three sample products and the verified order ID, then drops only that temporary database. It does not overwrite the running store.

Read the documented backup commands. Create a database backup and run the isolated restore check. Show only the filename, checksum, whether the saved order was found, and whether the temporary database was cleaned up. Do not print database rows, passwords or customer data. Keep the original store untouched.

This is a database recovery rehearsal, not full disaster recovery. The included static pictures are in source. Redis jobs, future uploaded files, cloud settings and provider data are not part of this dump. Keep an encrypted copy of source, private settings and backups somewhere you control before any real launch. A file that exists is not enough: verify a restore.

Stop and come back later

npm run stop
npm start
node scripts/verify.mjs --readback

Stopping preserves volumes. The final command reads the order from your most recent verification through authenticated Admin; it creates no new order. Never use a volume deletion command as a routine restart. Do not regenerate database passwords while keeping the old database volume.

Updates and rollback

Keep the source version, dependency lockfile and a verified backup together. Do not ask AI to “upgrade everything.” The example pins its commerce backend and dependencies to reviewed versions; both compatibility and licensing need a fresh review before changing them.

Review [THE SPECIFIC CHANGE] against this example’s documented version. First show the affected files, migrations, license changes and rollback steps. Test it in a separate copy with its own Compose project, port and volumes. Never reuse the current database for an upgrade rehearsal. Run typecheck, tests, build, checkout verification and restore check on that copy before suggesting a switch.

For a wording or CSS change, revert only its source diff and rebuild. For an Admin content change, copy the previous wording back into that product. Database migrations may not be reversible by rolling back source; keep the earlier source and a matching database backup. The supplied restore helper is a rehearsal, not a live database replacement command. Get help before replacing a live database or replaying uncertain provider operations.

Run privately in an account you control

The same Docker bundle can be copied to your own Linux server with Docker Compose. Generate new settings there, run the same three startup commands and keep its shop port on loopback. Open an SSH tunnel from your computer:

ssh -N -L 9421:127.0.0.1:9421 YOUR_USER@YOUR_SERVER

Then open http://127.0.0.1:9421/shop/ on your computer. Stop your local copy first if it is already using that port. You pay the cloud provider directly. The current evidence is from local Docker; a specific cloud account or server has not been validated.

This private preview is the supported deployment path today. A public store still needs a supported real payment provider, webhooks, refund checks, TLS/domain configuration, persistent uploads, transactional email, backup monitoring and merchant-specific shipping/tax policies. These are remaining product work, not settings you can enable by changing “test” to “live.”

Get unstuck without losing your store

Use this prompt when something fails:

Diagnose my local AI Commerce Starter setup. First read README.md. Use npm run status and a short, redacted tail of the commerce logs. Report the failing step, exact non-sensitive error, and whether data is still present. Do not print .env, run docker compose config, delete volumes, reseed a nonempty database, expose ports publicly, or make changes to another Docker project. Propose the smallest reversible fix and recheck the same step.

If port 9421 is busy, change SHOP_PORT in the private settings to an unused local port, then start again. If Docker is unavailable, start it before retrying. If initialization says the database is nonempty without a completed seed, preserve it and ask for a repair; do not delete it as a shortcut. If a download or build fails, retain the error and rerun the same build after fixing the cause.

Choose Launch Assist if you prefer someone to do the initial configuration. Custom features and ongoing operations are separately scoped services. The planned $299 Standard price covers the kit and guides; cloud, domain, AI usage, payment, email, tax and shipping costs are separate. Review the planned packages.