git:20260624.5363ac9 to git:20260703.ae55958

---

name: setup-weaverse-project

---

# 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.**

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 Never Types It

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.

---

## 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

ls package-lock.json pnpm-lock.yaml yarn.lock 2>/dev/null # infer package manager

```

---

```bash

git init

```

---

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

```bash

```

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)

```bash

npx shopify hydrogen env pull # works ONLY if the storefront is already linked

```

---

## Phase 4 — Project Identity (`WEAVERSE_PROJECT_ID` + API key)

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

**Path A — available today (default):**

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 Builder → Project Settings.

**Path B — local auth handshake (milestone, may not be live yet):**

When available, you can run a local authentication handshake that returns the user's `WEAVERSE_PROJECT_ID`, `WEAVERSE_API_KEY`, and the ability to register a preview URL and use the Content API directly. If the handshake tooling is present, prefer it. If not, fall back to Path A. **Do not assume `WEAVERSE_API_KEY` exists** unless the handshake provided it. Once you have the key, you can also give the agent the Weaverse MCP (Phase 8).

---

## Phase 5 — Create the User's Repo and Push

**Default (if `gh` present and authed from Phase 0):**

```bash

git add -A

```

**Fallback (no `gh`):** give numbered manual steps —

1. Create a new empty repo at https://github.com/new (no README).

2. Then run (you fill in their URL):

```bash

git remote add origin https://github.com/<user>/<repo>.git

git branch -M main && git push -u origin main

```

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

---

## Phase 6 — Connect the Preview to Weaverse Builder

- **Today:** guide the user — Builder → **Project Settings** → **Manage URLs** (Preview URLs section) → add `http://localhost:3456` → save.

- **Milestone (Path B auth):** when the handshake/API is live, register the preview URL automatically via the authenticated endpoint so the user never leaves the agent. Prefer this when available.

---

## Phase 7 — Verify (the success oracle)

```bash

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

npm run typecheck # passes

```

---

## Phase 8 — (Optional) Give the agent the Weaverse MCP

Once the project has a `WEAVERSE_API_KEY` (the Phase 4 Path B handshake, or a Content API

key from Builder → Settings → API Keys), offer to add the **Weaverse MCP server** so the

- Ships as `npx -y @weaverse/mcp` over stdio. **Account tools need v2.2.0+**; docs search

works with no key.

- Put `WEAVERSE_API_KEY` in the MCP client's `env` block — never in a tracked file.

- 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**

This is a convenience for *future* work — not required to finish setup. Skip it if the user

isn't on an MCP-capable agent.

---

## Full Sequence (cheat sheet)

1. Detect env (node, gh+auth, shopify CLI, package manager).

6. Create repo + push (`gh repo create` default, manual fallback).

7. Connect preview URL (manual paste today / auto-register later).

9. *(Optional)* Wire up the Weaverse MCP for the user's agent (`npx -y @weaverse/mcp` + `WEAVERSE_API_KEY`) — see Phase 8.

## Required vars quick reference

| Var | Needed to render? | Source |

|-----|-------------------|--------|

| `WEAVERSE_PROJECT_ID` | yes | Weaverse Builder (prompt / handshake) |

| `SHOP_ID`, customer-account, checkout, storefront-id, analytics | no (feature-complete) | Shopify / later |