Setup Weaverse Project

---
name: setup-weaverse-project
description: "Set up a new Weaverse Hydrogen storefront locally from a Weaverse theme. Boot a live demo-store preview before asking for any credentials, then make it the merchant's own: install the Hydrogen app, link the store, pull the Storefront credentials, push the repo to GitHub, configure the Weaverse MCP for live page edits, and install the full shopify-hydrogen-skills pack."
---

# Set Up a Weaverse Project — Agent Skill

> Take a user from **nothing** to a **running, connected** Weaverse Hydrogen storefront.
> This is the front door. Every other Weaverse skill assumes the project already exists — this one creates it.

## The One Rule That Fixes Onboarding

**Boot a live preview on the demo store BEFORE asking for any credentials.**

Most users quit onboarding because they hit a wall (GitHub, Shopify tokens, CLI) before they ever see anything work. Weaverse themes ship with working demo store tokens in `.env.example`, so you can show a real, running storefront in ~2 minutes with **zero** credentials. Do that first. Get the "wow." *Then* make it theirs.

Do not make the user create a GitHub repo, link a Shopify store, or paste tokens before they have seen the storefront running. If you do, you have failed the onboarding even if every command succeeds.

## You Drive the CLI — The User Only Clicks Browser Flows

The user (merchant or developer) should never have to type a CLI command. **You** run `shopify hydrogen` and `@weaverse/cli` under the hood. The Shopify CLI does real work (env pull, dev server, codegen, deploy) — drive it, do not reimplement it. `npm run dev` itself shells out to `shopify hydrogen dev`, so the CLI is always involved; just keep it invisible to the user.

The human's job is limited to: approving browser flows, selecting the store in the shop picker, copying credentials, and supplying secrets. Never make them paste commands.

## Inputs You Need

Ask for as little as possible. Most setup values are generated or discovered.

Required from the setup prompt or user:

- `WEAVERSE_PROJECT_ID` — from Weaverse Builder
- Theme handle — default to `pilot` only when omitted
- Project folder name — default to `my-hydrogen-storefront`

Required later for the real store:

- `PUBLIC_STORE_DOMAIN`
- `PUBLIC_STOREFRONT_API_TOKEN`

Generated by you:

- `SESSION_SECRET` — never ask the user for this; generate a random value

Optional later:

- `PRIVATE_STOREFRONT_API_TOKEN`
- `SHOP_ID`
- customer account vars
- checkout domain
- analytics/reviews vars

---

## Phase 0 — Detect the Environment

Before doing anything, detect and record (do not assume):

```bash
node --version            # need >= 18
git --version
gh --version 2>/dev/null && gh auth status 2>/dev/null   # is GitHub CLI present AND authed?
npx shopify version 2>/dev/null                          # Shopify CLI availability
npx @weaverse/cli@latest create --help 2>/dev/null        # CLI availability + template choices
ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager
```

Branch all later steps off this. If `gh` is missing or not authed, use the manual repo fallback in Phase 6. If Node < 18, stop and tell the user to upgrade.

---

## Phase 1 — Scaffold the Theme with Weaverse CLI

Prefer the Weaverse CLI over `git clone`. It knows the supported templates, downloads the correct source, and writes the initial env file.

```bash
npx @weaverse/cli@latest create \
  --template=<theme-handle> \
  --project-id=<WEAVERSE_PROJECT_ID> \
  --project-name=<project-folder> \
  --no-install \
  -y

cd <project-folder>
git init
```

Rules:

- If the theme handle is missing, default to `pilot`.
- If the CLI rejects a theme (for example an old/nonexistent `blank` handle), show the supported template list and ask the user for the replacement. Do not silently switch themes.
- If `--no-install` is not supported by the installed CLI, let the CLI install dependencies, then continue from the created folder.
- Do not hand-roll a GitHub downloader. Use the CLI first; use clone/degit only if the CLI is unavailable and the theme repo exists.

---

## Phase 2 — THE WOW MOMENT (boot on the demo store)

This is the centerpiece. Get a live preview running with the demo Shopify credentials before asking for Shopify credentials.

First, make sure `.env` is complete **before** the server boots (dev servers read the environment at startup — fixing it later means a restart):

- The CLI-generated `.env` should already contain demo Shopify values plus the user's `WEAVERSE_PROJECT_ID`. If `.env` is missing, copy `.env.example` to `.env`, then set `WEAVERSE_PROJECT_ID` from the setup prompt.
- Never ask the user for `SESSION_SECRET`. If it is missing or still the demo placeholder (e.g. `foobar`), generate one and write it to `.env` now:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```

Then boot:

```bash
npm install                   # or pnpm/yarn per lockfile
npm run dev                   # boots http://localhost:3456
```

Then **verify it actually came up** before saying anything succeeded:

```bash
curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200
```

Tell the user, in plain language:
> "Your storefront is running locally at http://localhost:3456 — this is the Weaverse demo store. Next we'll make it *yours*."

Do not proceed to credentials until the preview is up and verified.

---

## Phase 3 — Make It Theirs (Shopify credentials)

Now swap the demo store for the user's store. The **minimum vars needed to render a Weaverse preview** are:

- `PUBLIC_STORE_DOMAIN` — `their-store.myshopify.com`
- `PUBLIC_STOREFRONT_API_TOKEN` — Storefront API access token
- `WEAVERSE_PROJECT_ID` — see Phase 4 (this is the only var that can't come from Shopify)

`SESSION_SECRET` is still required by Hydrogen, but it is agent-generated. Everything else (`SHOP_ID`, `PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID`, `PUBLIC_CHECKOUT_DOMAIN`, `PUBLIC_STOREFRONT_ID`, analytics, reviews) is **feature-complete extra** — set it *after* first success, never block on it.

### One path: install the Hydrogen app and link the storefront

Hydrogen works on Shopify development stores. There is no Headless-app fallback: local linking and credential setup go through the **Hydrogen app** regardless of plan.

1. Have the user install the **Hydrogen app**: [https://apps.shopify.com/hydrogen](https://apps.shopify.com/hydrogen). They may need to pick the store, approve the install, and create a Hydrogen storefront project in the app.
2. **Link the storefront** (you run this):
   ```bash
   npx shopify hydrogen link
   ```
   If a shop picker appears, ask the user for the exact `.myshopify.com` domain to select — do not guess from a list of shops.
3. **Pull the environment** (you run this):
   ```bash
   npx shopify hydrogen env pull
   ```
   This populates `.env` with the store's real variables. Preserve `WEAVERSE_PROJECT_ID` and the generated `SESSION_SECRET` if the pull overwrites them.
4. **Verify before swapping** — never replace demo credentials with unverified ones. Check that `.env` now contains real values, not placeholders:
   ```bash
   grep -E "^(PUBLIC_STORE_DOMAIN|PUBLIC_STOREFRONT_API_TOKEN)=" .env
   ```
   `PUBLIC_STORE_DOMAIN` must be the store's actual `<store>.myshopify.com` domain and `PUBLIC_STOREFRONT_API_TOKEN` a non-empty Storefront API token. Only then swap (the pull already did); re-run the Phase 2 verify:
   ```bash
   curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # expect 200
   ```

> **Real limitation, stated once:** public Oxygen / shareable *production* environments still depend on the store's Shopify plan. Local linking and credential setup do **not** — they work on development stores through the Hydrogen app.
> Environment docs: [https://shopify.dev/docs/storefronts/headless/hydrogen/environments](https://shopify.dev/docs/storefronts/headless/hydrogen/environments)
> Getting started: [https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started](https://shopify.dev/docs/storefronts/headless/hydrogen/getting-started)

If `env pull` is unavailable or fails, have the user copy variables from **Shopify Admin → Hydrogen app → Storefront settings → Environments and variables**; you write the minimum render vars into `.env` and verify as above.

---

## Phase 4 — Project Identity (`WEAVERSE_PROJECT_ID`)

`WEAVERSE_PROJECT_ID` is the one value that lives only in Weaverse Builder and cannot be derived from Shopify.

The setup prompt generated by Weaverse Builder embeds the project's `WEAVERSE_PROJECT_ID` (and theme name). Read it from the prompt you were given and write it into `.env`. If you were not given one, ask the user to copy it from [Weaverse Studio](https://studio.weaverse.io) → Project Settings.

---

## Phase 5 — Weaverse API token + MCP (chat-driven live editing)

The Weaverse MCP lets the agent read and edit *this* project (and other projects on the same shop) directly from chat — including live page/content writes through the mounted Content API.

1. **Create the token (human action).** The user creates a **Weaverse API token** in Weaverse Studio → Dashboard → Account/Settings → API Keys ([https://studio.weaverse.io](https://studio.weaverse.io)). Copy it into your environment as `WEAVERSE_API_KEY` — never into a tracked file, never into the prompt.
2. **Configure the MCP server.** Add `@weaverse/mcp@latest` to the agent's MCP config with the bearer env var exactly:
   ```env
   WEAVERSE_API_KEY=<token>
   ```
   The config shape differs per client (Cursor, Claude Code, Codex, opencode, VS Code, pi, …); exact per-client snippets are in the docs: [https://weaverse.io/docs/developer-tools/weaverse-mcp](https://weaverse.io/docs/developer-tools/weaverse-mcp)
3. **Verify reads.** Use the real read tools: `list_projects`, `get_project`, `list_pages`, `get_page`, `get_theme_settings`, `list_languages`, `get_openapi_spec`. There is no `whoami` tool.
4. **Live writes are default-off — turn them on only with consent.** All six write tools require the env var exactly:
   ```env
   WEAVERSE_ENABLE_LIVE_WRITES=true
   ```
   With it: `update_project`, `create_page`, `delete_pages`, `update_page`, `assign_template_resources`, `update_theme_settings`.
   **Before enabling, disclose in plain language:** with live writes enabled, these tools change **live storefront content** — `update_page` edits real page items, `create_page`/`delete_pages` create/delete real pages, `assign_template_resources` adds Shopify resources to ONE existing shared template page (it never repoints an assignment away from another page; if any handle already belongs to a different live page the whole batch is rejected with 409 and nothing is written), `update_theme_settings` changes theme settings, `update_project` renames the project. Writes go live **immediately** through the same cache-invalidation path as a Studio save — there is no separate publish step. After any write, read back the affected resource to confirm.

This is a convenience for *future* work — not required to finish setup. Skip it if the user isn't on an MCP-capable agent.

---

## Phase 6 — Create the User's Repo and Push (ask first)

Pushing creates a repository under the user's GitHub account and publishes their code — an external effect they must approve. Never block local setup on it: if approval doesn't come, the storefront is already working locally and setup can still be reported complete.

**Always ask before any `gh repo create`, `git commit`, or `git push`** — including when `gh` is already authenticated. Detected `gh` state only decides *how* to execute after approval; it is never itself the approval. Ask for and echo back:

- the exact repository name (default `<project-folder>`),
- the visibility (**private** unless the user says otherwise),
- confirmation to make the first push.

**After approval, if `gh` is present and authed (Phase 0):**

```bash
git add -A
git commit -m "Initial commit: Weaverse Hydrogen storefront"
gh repo create <approved-name> --private --source=. --remote=origin --push
```

If the repo name already exists, inspect it before acting:

```bash
gh repo view <owner>/<approved-name> --json isEmpty,sshUrl,url
```

- **Empty repo** → add it as `origin` and push.
- **Not empty** → do not overwrite or force-push. Propose a distinct name such as `<project-folder>-pilot` or `<project-folder>-weaverse` and get approval for that name before continuing.

**After approval, if `gh` is missing / not authed:** give the user a clickable path and ask them to enable the push:
1. Authenticate the GitHub CLI ([https://github.com/login](https://github.com/login)) or create a new empty repo at [https://github.com/new](https://github.com/new) (no README).
2. Then run (you fill in their URL):
   ```bash
   git add -A && git commit -m "Initial commit: Weaverse Hydrogen storefront"
   git remote add origin https://github.com/<user>/<repo>.git
   git branch -M main && git push -u origin main
   ```

**If the user declines or doesn't answer:** say so plainly, leave the work committed only locally (or uncommitted), and continue. Do not retry the push unprompted.

**Never commit `.env` or secrets.** Confirm `.gitignore` covers `.env*` (the scaffold ships one) and that no token ends up in the commit. If a secret was staged, unstage it and add it to `.gitignore` before committing.

Never present "agent does it" and "user does it" as the same step — after approval, pick the path from Phase 0 detection and state which one you're taking.

---

## Phase 7 — Connect the Preview to Weaverse Builder

Guide the user: in Builder, click the URL in the preview address bar and choose **Manage previews** (or Builder → **Project Settings** → **Manage URLs**, Preview URLs section) → add `http://localhost:3456` → save.

---

## Phase 8 — Verify (the success oracle)

**Do not claim setup success without these green checks:**

```bash
curl -sf -o /dev/null -w "%{http_code}" http://localhost:3456   # 200
npm run typecheck                                               # passes
```

Recommended full check before handoff or production prep:

```bash
npm run build
```

Plus confirm the Weaverse preview shows **connected** in Builder when the user can check it. If any required check fails, fix it before reporting done — and report exactly which check failed if you cannot.

---

## Phase 9 — Install the full skills pack (finish line)

End by installing the complete `shopify-hydrogen-skills` pack — all skills, all agents, noninteractive — **inside the generated storefront project** (not anywhere else). The setup request explicitly asks for this, so the install itself is expected:

```bash
npx skills@latest add Weaverse/shopify-hydrogen-skills --all
```

Then inspect what it generated:

```bash
git status --short          # review what the pack install generated
```

**Publishing those changes is a separate external effect — ask again.** Show the user the file list from `git status` and what the commit message would be, then wait for approval before running anything below:

```bash
git add -A && git commit -m "Add shopify-hydrogen-skills pack"
git push
```

If the user declines, leave the installed pack in the working tree and say it is uncommitted. Never run this commit/push block unconditionally.

---

## Full Sequence (cheat sheet)

1. Detect env (node, gh+auth, shopify CLI, package manager).
2. Scaffold with `npx @weaverse/cli@latest create` (default `pilot`) → `git init`.
3. Generate `SESSION_SECRET` if needed.
4. **Boot on demo Shopify store** (install, `npm run dev`, verify 200). ← wow moment.
5. Swap to user's store: install the Hydrogen app → `npx shopify hydrogen link` → `npx shopify hydrogen env pull` → verify `PUBLIC_STORE_DOMAIN` + `PUBLIC_STOREFRONT_API_TOKEN` are real before trusting them.
6. **Ask approval** for repo name/visibility/first push, then create repo + push (`gh repo create` after approval, manual fallback). Never commit `.env`/secrets.
7. Configure the Weaverse MCP (`WEAVERSE_API_KEY`; live writes only with consent via `WEAVERSE_ENABLE_LIVE_WRITES=true`).
8. Connect preview URL in Builder (Manage previews).
9. Verify required checks (200 + typecheck); run build when preparing handoff/production.
10. Install the full pack: `npx skills@latest add Weaverse/shopify-hydrogen-skills --all`; review `git status`, then **ask approval** before committing/pushing it.

## Required vars quick reference

| Var | Needed to render? | Source |
|-----|-------------------|--------|
| `SESSION_SECRET` | yes | agent-generated random string |
| `PUBLIC_STORE_DOMAIN` | yes | Shopify Hydrogen app (`env pull`) |
| `PUBLIC_STOREFRONT_API_TOKEN` | yes | Shopify Hydrogen app (`env pull`) |
| `WEAVERSE_PROJECT_ID` | yes | Weaverse Builder (setup prompt) |
| `WEAVERSE_API_KEY` | MCP only | Weaverse Studio → Dashboard → Account/Settings → API Keys |
| `SHOP_ID`, customer-account, checkout, storefront-id, analytics | no (feature-complete) | Shopify / later |