Build a Spark storefront theme with agents

git clone https://github.com/NextCommerceCo/skills.git
cd skills
git pull --ff-only
./skills.sh
./skills.sh status all next-theme-figma
./skills.sh status all next-theme-dev

I want to apply this design to a new unpublished Spark theme.

Design source:
- Figma: <figma-url>

Target store:
- https://<store-subdomain>.29next.store/

Stage 1 (design handoff):
- Load and follow the next-theme-figma skill against the Figma file.
- Use implementation-handoff mode with theme_family=spark and
  runtime_contract=web-components.
- Produce the complete 10-file package, including geometry.json and
  copy.json, and validate it in strict mode.
- Confirm every reference screenshot path exists inside the package.
- If the design source is incomplete, stop and give me the designer
  checklist instead of guessing.

Stage 2 (implementation):
- Clone a fresh copy of the public Spark theme (HTTPS).
- Record the Spark version and git commit before editing.
- Load and follow the next-theme-dev skill.
- Implement from the validated handoff package, not from memory of
  the Figma file.
- Install or use ntk from the Theme Kit docs.
- Create a new theme on the store with ntk init and upload the work there.
- Do not activate the new theme.
- Treat configs/settings_data.json as saved Theme Editor state. If this
  fresh preview build has a prepared copy as its source of truth, confirm
  that with me and push it from the first upload. Otherwise exclude it.
- Work from a clean local project folder.
- The store API key is available as THEME_API_KEY in an uncommitted
  .theme-build.env file. Never print or commit it.
- Run make verify-theme before uploading.
- Stop on any failed ntk push, then run the post-push readback gate.

Deliverables:
- The validated handoff package.
- A preview URL for the new theme.
- Spark, skill, and Theme Kit versions.
- The changed-file and pushed-file lists.
- The settings_data.json decision.
- Notes for any manual Dashboard setup still required, including
  Offers for any free-shipping or gift promises in the design.
- Geometry, copy, readback, and behavior reports.
- Desktop PNGs at 1440px and mobile PNGs at 390px, or a recorded
  accepted gap with an owner and reason.

# Store secrets outside committed files.
[ -f .theme-build.env ] && { echo ".theme-build.env already exists; edit it manually" >&2; exit 1; }
grep -qxF '.theme-build.env' .gitignore 2>/dev/null || printf '.theme-build.env\n' >> .gitignore
printf 'THEME_API_KEY=<paste-api-key-here>\n' > .theme-build.env

set -a
source .theme-build.env
set +a

[ "$THEME_API_KEY" = "<paste-api-key-here>" ] && { echo "Edit .theme-build.env with a real API key first" >&2; exit 1; }

export NTK_APIKEY="$THEME_API_KEY"
ntk init \
  --name="Merchant Storefront - Agent Build" \
  --store="https://<store-subdomain>.29next.store/"

ntk list

# Install Tailwind once, then run the full pre-upload check.
make install-tailwind
make verify-theme

# Rebuild assets/main.css, then stage it with its source changes.
make release
git add <changed-source-files> assets/main.css
git diff --cached -- assets/main.css
git commit -m "Build storefront theme"

# If this fresh preview owns a prepared settings_data.json, push it first.
# ntk push configs/settings_data.json || exit 1

# Initial Spark upload, excluding saved Theme Editor state.
for dir in assets configs layouts locales partials templates; do
  [ -d "$dir" ] && find "$dir" -type f
done \
  | grep -v '^configs/settings_data.json$' \
  | while IFS= read -r file; do ntk push "$file" || exit 1; done

ntk push templates/index.html partials/header.html assets/main.css configs/settings_schema.json

https://<store-subdomain>.29next.store/?preview_theme=THEME_ID

{
  "schema_version": "next-theme-dev/readback-expectations/v1",
  "theme_id": "THEME_ID",
  "routes": [{
    "route_id": "home",
    "url": "https://<store-subdomain>.29next.store/?preview_theme=THEME_ID",
    "expect_status": 200,
    "expect_section_count": 2,
    "section_markers": [
      {"section_id": "hero", "marker": "data-section=\"hero\""},
      {"section_id": "featured", "marker": "data-section=\"featured\""}
    ]
  }],
  "assets": [{
    "served_url": "https://<served-main-css-url>",
    "committed_path": "assets/main.css"
  }]
}

python3 <next-theme-dev-skill-dir>/scripts/readback-assert.py \
  --expect ./qa-output/readback-expectations.json \
  --repo-root . \
  --report ./qa-output/readback.json

node <next-theme-dev-skill-dir>/scripts/assert-geometry.mjs selectors \
  --manifest <handoff-package>/geometry.json \
  --route home --viewport desktop

node <next-theme-dev-skill-dir>/scripts/assert-geometry.mjs probe \
  --manifest <handoff-package>/geometry.json \
  --route home --viewport desktop \
  --out ./qa-output/geometry-probe.js

# Evaluate geometry-probe.js in the browser and save its JSON result.

node <next-theme-dev-skill-dir>/scripts/assert-geometry.mjs compare \
  --manifest <handoff-package>/geometry.json \
  --route home --viewport desktop \
  --boxes ./qa-output/geometry-boxes.json \
  --report ./qa-output/geometry-home-desktop.json

python3 <next-theme-figma-skill-dir>/scripts/copy-lint.py \
  --package <handoff-package> \
  --templates partials \
  --templates templates \
  --require-coverage \
  --report ./qa-output/copy-lint.json

New theme:
- Name: Merchant Storefront - Agent Build
- Theme ID: THEME_ID
- Store and environment: STORE / development
- Preview: https://<store-subdomain>.29next.store/?preview_theme=THEME_ID
- Status: Uploaded, not activated
- Active theme ID at handoff: ACTIVE_THEME_ID

Built from:
- Spark version and commit: VERSION / SHA
- Design source: <figma-url-or-brief>
- Handoff package: <path-or-link-to-validated-package>
- next-theme-figma version: VERSION
- next-theme-dev version: VERSION
- Theme Kit version: VERSION

Changed:
- <exact changed-file list>

Uploaded:
- <exact pushed-file list>

Settings:
- settings_data.json: excluded | pushed from first upload
- Reason: <reason>

Evidence:
- Strict handoff validation: PASS / report path
- Readback: PASS / report path
- Geometry: PASS / report paths
- Copy: PASS / report path
- Storefront behavior: PASS / report path
- Screenshots: desktop and mobile paths
- Accepted gaps: none | <route, viewport, owner, reason>

Dashboard work:
- <Offers, navigation, pages, products, or none>

export NTK_APIKEY="$THEME_API_KEY"
ntk checkout \
  --theme_id=THEME_ID \
  --store="https://<store-subdomain>.29next.store/"