shopify-agentic-dev-workflow 0.1.0

package/.cursor/rules/shopify-agentic-dev.mdc

@@ -0,0 +1,290 @@
+---
+description: Shopify agentic development guardrails
+alwaysApply: true
+---
+
+# Shopify Agentic Dev Workflow — Agent Guardrails
+
+This project is managed by `shopify-agentic-dev-workflow`.
+All store operations run through the `shopify-agent` CLI. Never call Shopify Admin GraphQL directly — always use the commands below.
+
+---
+
+## Hard Rules — Never Bypass These
+
+1. **Never push to a live/published theme without explicit user confirmation.**
+   - Before any `theme:push` or `shopify theme push`, check if the active theme is live (role: live).
+   - If it is live: STOP, explain the consequences below, and ask the user to choose:
+     a. Push to a NEW staging theme (`--unpublished`) — RECOMMENDED
+     b. Push to live (CLI requires typing the store domain to confirm)
+   - If the user chooses staging: run `shopify-agent theme:push` and tell them to preview before publishing.
+   - Never silently push to a live theme.
+
+2. **Never publish a theme without explicit user confirmation.**
+   - `shopify-agent theme:publish` prompts before going live — never skip or auto-approve on the user's behalf.
+   - Use `--yes` only when the user has already previewed and explicitly approved the theme for publication.
+
+3. **Never run any mutation command without explicit user confirmation.**
+   - Every write command (`inventory:set`, `inventory:adjust`, `products:create`, `products:delete`,
+     `variants:update`, `orders:cancel`, `orders:close`, `customers:create`, `customers:tags`,
+     `discounts:create`, `discounts:delete`, `discounts:enable`, `discounts:disable`,
+     `gift-cards:create`, `pages:create`, `redirects:create`, `metafields:set`,
+     `collections:create`, `admin:mutate`) prompts for confirmation before executing.
+   - Always show what will change and which store before asking.
+   - Use `--yes` only when the user has already reviewed and explicitly approved the operation.
+
+4. **Never commit or print secrets.**
+   - Do not read, log, or include `.env`, access tokens, client secrets, or session tokens in any output.
+   - `.env` and `.shopify-agent/` are git-ignored — never stage them.
+
+5. **Never mix files between themes or pull into the project root.**
+   - Theme code lives under `themes/<theme-name>-<theme-id>/`, never directly in the package root.
+   - Before `theme:pull`, `theme:push`, or `theme:publish`, verify the active store, theme ID, theme role, and local theme folder metadata.
+   - If the Git worktree is dirty, stop and ask the user to commit or stash first. Pulling Theme A into Theme B's folder or branch is a release blocker.
+
+---
+
+## Live Theme Consequences (always explain before any live push)
+
+- The storefront updates IMMEDIATELY — customers browsing right now see the new code
+- Liquid errors, broken CSS, or JS issues go live instantly
+- Shopify does NOT auto-revert — rollback requires manually republishing the previous theme
+- A single typo in a section template can render pages blank for real customers
+
+---
+
+## Setup & Diagnostics
+
+```bash
+shopify-agent init              # Full interactive setup wizard (connect store, auth, pick theme)
+shopify-agent doctor            # Check tools, show active config + install hints
+shopify-agent capabilities      # Detect which Shopify CLI 4.x commands are available
+shopify-agent auth              # shopify auth login (opens browser)
+shopify-agent agents:install    # Write/update these guardrail files
+shopify-agent mcp:install       # Add Shopify Dev MCP to ~/.codex/config.toml
+shopify-agent profile:list      # List saved profiles
+shopify-agent profile:use       # Switch active profile
+shopify-agent store:list        # Show Shopify orgs linked to your account
+shopify-agent store:auth        # Create Admin API token with selected scopes
+```
+
+---
+
+## Theme Development (Developers)
+
+```bash
+shopify-agent theme:list        # List themes with roles (live vs unpublished)
+shopify-agent theme:select      # Pick active theme (live ⚠ warning included)
+shopify-agent theme:pull        # Download theme files locally
+shopify-agent theme:dev         # Hot-reload dev server — opens browser automatically
+shopify-agent theme:check       # Liquid linting via Theme Check
+shopify-agent theme:push        # Push to staging (3-option guard if theme is live)
+shopify-agent theme:publish     # Prompts for confirmation before going live
+```
+
+Recommended theme dev workflow:
+1. `shopify-agent init` → select an UNPUBLISHED staging theme
+2. `shopify-agent theme:pull` → download theme files into `themes/<theme-name>-<theme-id>/`
+3. `shopify-agent theme:dev` → hot-reload dev server
+4. Edit Liquid / CSS / JS files locally
+5. `shopify-agent theme:check` → lint after edits
+6. `shopify-agent theme:push` → push to staging theme
+7. Preview in Shopify Admin → Themes → Preview
+8. `shopify-agent theme:publish` → go live after review
+
+If the user asks to push to a live theme, respond:
+> "The configured theme is LIVE. I recommend `shopify-agent theme:push` which will offer a safe staging option. Push directly only after you confirm the store domain."
+
+### Theme Folder and Git Discipline
+
+- Treat each Shopify theme as its own versioned artifact: `themes/dawn-169809707321/`, `themes/brand-refresh-123456789/`, etc.
+- A pull must write only into the folder for the selected `SHOPIFY_THEME_ID`. If files appear in the repo root, stop and fix the command/path before continuing.
+- Commit after every successful pull and before every push. This gives the team a rollback point and prevents accidental Theme A/Theme B overwrites.
+- Do not switch themes by editing files in place. Run `shopify-agent theme:select`, then `shopify-agent theme:pull`, and let the CLI create or reuse the matching theme folder.
+- Never remove, rewrite, or bypass `.shopify-theme.json` metadata in a theme folder; it is the local proof that the folder belongs to the selected store and theme.
+
+### Figma-to-Dawn Build Rules
+
+- Read the Figma file before coding, then map frames to Dawn sections/templates: home, collection/PLP, product/PDP, cart, header, and footer.
+- Build real Shopify Liquid sections with schema settings instead of static HTML where merchants may need control later.
+- Keep design-preview data and live Shopify data separate. Demo store products can break the visual match; add explicit settings such as "Use live collection products" or "Use live product data" before letting catalog data override Figma assets.
+- Make header, menu, product-card, CTA, social, and footer links real and clickable. Fallback links should go to search, collection, product, account, cart, or policy URLs, not dead placeholders.
+- After frontend work, run `shopify-agent theme:check` and visually inspect desktop and mobile previews for home, collection, product, header, footer, and horizontal overflow.
+
+---
+
+## App Development (Developers)
+
+```bash
+shopify-agent app:dev           # shopify app dev
+shopify-agent app:deploy        # shopify app deploy
+```
+
+---
+
+## Raw GraphQL (Developers / Power Users)
+
+```bash
+shopify-agent admin:query  <file.graphql>   # Read-only Admin GraphQL
+shopify-agent admin:mutate <file.graphql>   # Mutation (always prompts for confirmation)
+```
+
+Pre-built templates in `templates/graphql/`:
+- `shop-query.graphql`, `inventory-audit.graphql`, `discounts-list.graphql`, `products-seo-audit.graphql`
+- `products/list.graphql`, `products/low-inventory.graphql`
+- `orders/list-open.graphql`, `orders/revenue-summary.graphql`
+- `customers/top-spenders.graphql`, `customers/new-customers.graphql`
+- `discounts/active-discounts.graphql`
+- `store/full-info.graphql`, `store/webhooks.graphql`
+- `content/pages-list.graphql`, `content/redirects-list.graphql`
+- `metafields/product-metafields.graphql`
+
+Schema hygiene:
+- Shopify Admin GraphQL is versioned and fields move or disappear. If a query fails with `undefinedField`, treat the template as stale and update it against the configured `SHOPIFY_API_VERSION`.
+- Do not assume dashboard, discount, inventory, or product payload shapes from memory. Run the smallest read-only query first, then expand.
+- Keep mutations behind `admin:mutate` so the CLI confirmation and store context are visible before anything changes.
+
+---
+
+## Products & Catalog (Catalogers)
+
+```bash
+shopify-agent products:list [--status active|draft|archived] [--limit N]
+shopify-agent products:get              # Interactive full product detail viewer
+shopify-agent products:create           # Wizard: title, type, vendor, price, SKU, inventory, status
+shopify-agent products:publish          # Set product to Active (visible in store) — prompts
+shopify-agent products:archive          # Set product to Archived — prompts
+shopify-agent products:draft            # Set product back to Draft — prompts
+shopify-agent products:delete           # Delete a product — prompts with confirmation
+
+shopify-agent variants:list             # Pick a product → see all variants with price/SKU/qty
+shopify-agent variants:update           # Update price, SKU, barcode for a variant — prompts
+
+shopify-agent collections:list          # List all collections (manual + smart)
+shopify-agent collections:create        # Wizard: manual or smart (with rule builder) — prompts
+```
+
+---
+
+## Inventory (Catalogers / Operations)
+
+```bash
+shopify-agent inventory:list            # List all inventory levels across locations
+shopify-agent inventory:set <qty>       # Set ALL variants to <qty> in bulk — prompts
+shopify-agent inventory:adjust          # Adjust one variant: +5, -3, or =10 — prompts
+```
+
+---
+
+## Orders (Business Admins)
+
+```bash
+shopify-agent orders:list [--status open|closed|cancelled|any] [--limit N]
+shopify-agent orders:get                # Full order detail: line items, tracking, totals
+shopify-agent orders:cancel             # Cancel an open order (choose reason, refund, restock) — prompts
+shopify-agent orders:close              # Mark an order as closed — prompts
+```
+
+---
+
+## Customers (Business Admins / Marketing)
+
+```bash
+shopify-agent customers:list [--limit N]
+shopify-agent customers:search          # Search by name, email, phone, or tag
+shopify-agent customers:get             # Full customer profile + recent order history
+shopify-agent customers:create          # Wizard: name, email, phone, tags, marketing opt-in — prompts
+shopify-agent customers:tags            # Add or remove tags on a customer — prompts
+```
+
+---
+
+## Discounts & Gift Cards (Marketing)
+
+```bash
+shopify-agent discounts:list            # List all discount codes with usage stats
+shopify-agent discounts:create          # Wizard: % off, fixed amount, per-customer limit, expiry — prompts
+shopify-agent discounts:delete          # Delete a discount code — prompts
+shopify-agent discounts:enable          # Re-activate a disabled discount — prompts
+shopify-agent discounts:disable         # Deactivate without deleting — prompts
+
+shopify-agent gift-cards:list           # List all gift cards with balance
+shopify-agent gift-cards:create         # Create a gift card (with optional customer assignment) — prompts
+```
+
+---
+
+## Store Info (Business Admins)
+
+```bash
+shopify-agent store:info                # Name, plan, currency, timezone, multi-currency
+shopify-agent store:locations           # List locations with fulfillment status
+shopify-agent store:dashboard           # Snapshot: open orders + low-stock + active discounts
+shopify-agent dashboard                 # Alias for store:dashboard
+```
+
+---
+
+## Content (Marketing)
+
+```bash
+shopify-agent pages:list                # List all pages
+shopify-agent pages:create              # Wizard: title, body HTML, publish immediately — prompts
+shopify-agent blogs:list                # List blogs with 5 recent articles each
+shopify-agent articles:list             # Pick a blog → list articles with author + status
+shopify-agent redirects:list            # List all URL redirects
+shopify-agent redirects:create          # Create a URL redirect (from → to) — prompts
+```
+
+---
+
+## Metafields (Developers / Catalogers)
+
+```bash
+shopify-agent metafields:list           # List metafields for any resource
+shopify-agent metafields:set            # Create or update a metafield on any resource — prompts
+# Works with: Product, Collection, Customer, Order, Shop
+```
+
+---
+
+## Flags
+
+```bash
+--yes, -y       Auto-confirm all prompts (scripting / CI — only use after reviewing the operation)
+--status <s>    Filter by status where supported (products:list, orders:list)
+--limit <n>     Limit result count where supported
+```
+
+---
+
+## Role-Based Workflow Examples
+
+**Cataloger — bulk inventory reset before a sale:**
+```bash
+shopify-agent inventory:list            # review current levels
+shopify-agent inventory:set 50          # bulk-set all variants to 50 (prompts)
+shopify-agent products:list --status active --limit 50  # verify
+```
+
+**Marketing — launch a discount campaign:**
+```bash
+shopify-agent discounts:list            # check existing codes
+shopify-agent discounts:create          # wizard → 10% off, first order, 7-day expiry (prompts)
+shopify-agent pages:create              # create a landing page for the campaign (prompts)
+```
+
+**Business admin — morning dashboard:**
+```bash
+shopify-agent dashboard                 # open orders + low-stock + active discounts
+shopify-agent orders:list --status open
+shopify-agent customers:list --limit 10
+```
+
+**Developer — theme deploy pipeline:**
+```bash
+shopify-agent theme:check               # lint
+shopify-agent theme:push                # push to staging
+# preview in Admin
+shopify-agent theme:publish             # go live (prompts)
+```

package/AGENTS.md

@@ -0,0 +1,285 @@
+# Shopify Agentic Dev Workflow — Agent Guardrails
+
+This project is managed by `shopify-agentic-dev-workflow`.
+All store operations run through the `shopify-agent` CLI. Never call Shopify Admin GraphQL directly — always use the commands below.
+
+---
+
+## Hard Rules — Never Bypass These
+
+1. **Never push to a live/published theme without explicit user confirmation.**
+   - Before any `theme:push` or `shopify theme push`, check if the active theme is live (role: live).
+   - If it is live: STOP, explain the consequences below, and ask the user to choose:
+     a. Push to a NEW staging theme (`--unpublished`) — RECOMMENDED
+     b. Push to live (CLI requires typing the store domain to confirm)
+   - If the user chooses staging: run `shopify-agent theme:push` and tell them to preview before publishing.
+   - Never silently push to a live theme.
+
+2. **Never publish a theme without explicit user confirmation.**
+   - `shopify-agent theme:publish` prompts before going live — never skip or auto-approve on the user's behalf.
+   - Use `--yes` only when the user has already previewed and explicitly approved the theme for publication.
+
+3. **Never run any mutation command without explicit user confirmation.**
+   - Every write command (`inventory:set`, `inventory:adjust`, `products:create`, `products:delete`,
+     `variants:update`, `orders:cancel`, `orders:close`, `customers:create`, `customers:tags`,
+     `discounts:create`, `discounts:delete`, `discounts:enable`, `discounts:disable`,
+     `gift-cards:create`, `pages:create`, `redirects:create`, `metafields:set`,
+     `collections:create`, `admin:mutate`) prompts for confirmation before executing.
+   - Always show what will change and which store before asking.
+   - Use `--yes` only when the user has already reviewed and explicitly approved the operation.
+
+4. **Never commit or print secrets.**
+   - Do not read, log, or include `.env`, access tokens, client secrets, or session tokens in any output.
+   - `.env` and `.shopify-agent/` are git-ignored — never stage them.
+
+5. **Never mix files between themes or pull into the project root.**
+   - Theme code lives under `themes/<theme-name>-<theme-id>/`, never directly in the package root.
+   - Before `theme:pull`, `theme:push`, or `theme:publish`, verify the active store, theme ID, theme role, and local theme folder metadata.
+   - If the Git worktree is dirty, stop and ask the user to commit or stash first. Pulling Theme A into Theme B's folder or branch is a release blocker.
+
+---
+
+## Live Theme Consequences (always explain before any live push)
+
+- The storefront updates IMMEDIATELY — customers browsing right now see the new code
+- Liquid errors, broken CSS, or JS issues go live instantly
+- Shopify does NOT auto-revert — rollback requires manually republishing the previous theme
+- A single typo in a section template can render pages blank for real customers
+
+---
+
+## Setup & Diagnostics
+
+```bash
+shopify-agent init              # Full interactive setup wizard (connect store, auth, pick theme)
+shopify-agent doctor            # Check tools, show active config + install hints
+shopify-agent capabilities      # Detect which Shopify CLI 4.x commands are available
+shopify-agent auth              # shopify auth login (opens browser)
+shopify-agent agents:install    # Write/update these guardrail files
+shopify-agent mcp:install       # Add Shopify Dev MCP to ~/.codex/config.toml
+shopify-agent profile:list      # List saved profiles
+shopify-agent profile:use       # Switch active profile
+shopify-agent store:list        # Show Shopify orgs linked to your account
+shopify-agent store:auth        # Create Admin API token with selected scopes
+```
+
+---
+
+## Theme Development (Developers)
+
+```bash
+shopify-agent theme:list        # List themes with roles (live vs unpublished)
+shopify-agent theme:select      # Pick active theme (live ⚠ warning included)
+shopify-agent theme:pull        # Download theme files locally
+shopify-agent theme:dev         # Hot-reload dev server — opens browser automatically
+shopify-agent theme:check       # Liquid linting via Theme Check
+shopify-agent theme:push        # Push to staging (3-option guard if theme is live)
+shopify-agent theme:publish     # Prompts for confirmation before going live
+```
+
+Recommended theme dev workflow:
+1. `shopify-agent init` → select an UNPUBLISHED staging theme
+2. `shopify-agent theme:pull` → download theme files into `themes/<theme-name>-<theme-id>/`
+3. `shopify-agent theme:dev` → hot-reload dev server
+4. Edit Liquid / CSS / JS files locally
+5. `shopify-agent theme:check` → lint after edits
+6. `shopify-agent theme:push` → push to staging theme
+7. Preview in Shopify Admin → Themes → Preview
+8. `shopify-agent theme:publish` → go live after review
+
+If the user asks to push to a live theme, respond:
+> "The configured theme is LIVE. I recommend `shopify-agent theme:push` which will offer a safe staging option. Push directly only after you confirm the store domain."
+
+### Theme Folder and Git Discipline
+
+- Treat each Shopify theme as its own versioned artifact: `themes/dawn-169809707321/`, `themes/brand-refresh-123456789/`, etc.
+- A pull must write only into the folder for the selected `SHOPIFY_THEME_ID`. If files appear in the repo root, stop and fix the command/path before continuing.
+- Commit after every successful pull and before every push. This gives the team a rollback point and prevents accidental Theme A/Theme B overwrites.
+- Do not switch themes by editing files in place. Run `shopify-agent theme:select`, then `shopify-agent theme:pull`, and let the CLI create or reuse the matching theme folder.
+- Never remove, rewrite, or bypass `.shopify-theme.json` metadata in a theme folder; it is the local proof that the folder belongs to the selected store and theme.
+
+### Figma-to-Dawn Build Rules
+
+- Read the Figma file before coding, then map frames to Dawn sections/templates: home, collection/PLP, product/PDP, cart, header, and footer.
+- Build real Shopify Liquid sections with schema settings instead of static HTML where merchants may need control later.
+- Keep design-preview data and live Shopify data separate. Demo store products can break the visual match; add explicit settings such as "Use live collection products" or "Use live product data" before letting catalog data override Figma assets.
+- Make header, menu, product-card, CTA, social, and footer links real and clickable. Fallback links should go to search, collection, product, account, cart, or policy URLs, not dead placeholders.
+- After frontend work, run `shopify-agent theme:check` and visually inspect desktop and mobile previews for home, collection, product, header, footer, and horizontal overflow.
+
+---
+
+## App Development (Developers)
+
+```bash
+shopify-agent app:dev           # shopify app dev
+shopify-agent app:deploy        # shopify app deploy
+```
+
+---
+
+## Raw GraphQL (Developers / Power Users)
+
+```bash
+shopify-agent admin:query  <file.graphql>   # Read-only Admin GraphQL
+shopify-agent admin:mutate <file.graphql>   # Mutation (always prompts for confirmation)
+```
+
+Pre-built templates in `templates/graphql/`:
+- `shop-query.graphql`, `inventory-audit.graphql`, `discounts-list.graphql`, `products-seo-audit.graphql`
+- `products/list.graphql`, `products/low-inventory.graphql`
+- `orders/list-open.graphql`, `orders/revenue-summary.graphql`
+- `customers/top-spenders.graphql`, `customers/new-customers.graphql`
+- `discounts/active-discounts.graphql`
+- `store/full-info.graphql`, `store/webhooks.graphql`
+- `content/pages-list.graphql`, `content/redirects-list.graphql`
+- `metafields/product-metafields.graphql`
+
+Schema hygiene:
+- Shopify Admin GraphQL is versioned and fields move or disappear. If a query fails with `undefinedField`, treat the template as stale and update it against the configured `SHOPIFY_API_VERSION`.
+- Do not assume dashboard, discount, inventory, or product payload shapes from memory. Run the smallest read-only query first, then expand.
+- Keep mutations behind `admin:mutate` so the CLI confirmation and store context are visible before anything changes.
+
+---
+
+## Products & Catalog (Catalogers)
+
+```bash
+shopify-agent products:list [--status active|draft|archived] [--limit N]
+shopify-agent products:get              # Interactive full product detail viewer
+shopify-agent products:create           # Wizard: title, type, vendor, price, SKU, inventory, status
+shopify-agent products:publish          # Set product to Active (visible in store) — prompts
+shopify-agent products:archive          # Set product to Archived — prompts
+shopify-agent products:draft            # Set product back to Draft — prompts
+shopify-agent products:delete           # Delete a product — prompts with confirmation
+
+shopify-agent variants:list             # Pick a product → see all variants with price/SKU/qty
+shopify-agent variants:update           # Update price, SKU, barcode for a variant — prompts
+
+shopify-agent collections:list          # List all collections (manual + smart)
+shopify-agent collections:create        # Wizard: manual or smart (with rule builder) — prompts
+```
+
+---
+
+## Inventory (Catalogers / Operations)
+
+```bash
+shopify-agent inventory:list            # List all inventory levels across locations
+shopify-agent inventory:set <qty>       # Set ALL variants to <qty> in bulk — prompts
+shopify-agent inventory:adjust          # Adjust one variant: +5, -3, or =10 — prompts
+```
+
+---
+
+## Orders (Business Admins)
+
+```bash
+shopify-agent orders:list [--status open|closed|cancelled|any] [--limit N]
+shopify-agent orders:get                # Full order detail: line items, tracking, totals
+shopify-agent orders:cancel             # Cancel an open order (choose reason, refund, restock) — prompts
+shopify-agent orders:close              # Mark an order as closed — prompts
+```
+
+---
+
+## Customers (Business Admins / Marketing)
+
+```bash
+shopify-agent customers:list [--limit N]
+shopify-agent customers:search          # Search by name, email, phone, or tag
+shopify-agent customers:get             # Full customer profile + recent order history
+shopify-agent customers:create          # Wizard: name, email, phone, tags, marketing opt-in — prompts
+shopify-agent customers:tags            # Add or remove tags on a customer — prompts
+```
+
+---
+
+## Discounts & Gift Cards (Marketing)
+
+```bash
+shopify-agent discounts:list            # List all discount codes with usage stats
+shopify-agent discounts:create          # Wizard: % off, fixed amount, per-customer limit, expiry — prompts
+shopify-agent discounts:delete          # Delete a discount code — prompts
+shopify-agent discounts:enable          # Re-activate a disabled discount — prompts
+shopify-agent discounts:disable         # Deactivate without deleting — prompts
+
+shopify-agent gift-cards:list           # List all gift cards with balance
+shopify-agent gift-cards:create         # Create a gift card (with optional customer assignment) — prompts
+```
+
+---
+
+## Store Info (Business Admins)
+
+```bash
+shopify-agent store:info                # Name, plan, currency, timezone, multi-currency
+shopify-agent store:locations           # List locations with fulfillment status
+shopify-agent store:dashboard           # Snapshot: open orders + low-stock + active discounts
+shopify-agent dashboard                 # Alias for store:dashboard
+```
+
+---
+
+## Content (Marketing)
+
+```bash
+shopify-agent pages:list                # List all pages
+shopify-agent pages:create              # Wizard: title, body HTML, publish immediately — prompts
+shopify-agent blogs:list                # List blogs with 5 recent articles each
+shopify-agent articles:list             # Pick a blog → list articles with author + status
+shopify-agent redirects:list            # List all URL redirects
+shopify-agent redirects:create          # Create a URL redirect (from → to) — prompts
+```
+
+---
+
+## Metafields (Developers / Catalogers)
+
+```bash
+shopify-agent metafields:list           # List metafields for any resource
+shopify-agent metafields:set            # Create or update a metafield on any resource — prompts
+# Works with: Product, Collection, Customer, Order, Shop
+```
+
+---
+
+## Flags
+
+```bash
+--yes, -y       Auto-confirm all prompts (scripting / CI — only use after reviewing the operation)
+--status <s>    Filter by status where supported (products:list, orders:list)
+--limit <n>     Limit result count where supported
+```
+
+---
+
+## Role-Based Workflow Examples
+
+**Cataloger — bulk inventory reset before a sale:**
+```bash
+shopify-agent inventory:list            # review current levels
+shopify-agent inventory:set 50          # bulk-set all variants to 50 (prompts)
+shopify-agent products:list --status active --limit 50  # verify
+```
+
+**Marketing — launch a discount campaign:**
+```bash
+shopify-agent discounts:list            # check existing codes
+shopify-agent discounts:create          # wizard → 10% off, first order, 7-day expiry (prompts)
+shopify-agent pages:create              # create a landing page for the campaign (prompts)
+```
+
+**Business admin — morning dashboard:**
+```bash
+shopify-agent dashboard                 # open orders + low-stock + active discounts
+shopify-agent orders:list --status open
+shopify-agent customers:list --limit 10
+```
+
+**Developer — theme deploy pipeline:**
+```bash
+shopify-agent theme:check               # lint
+shopify-agent theme:push                # push to staging
+# preview in Admin
+shopify-agent theme:publish             # go live (prompts)
+```

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0
+
+Initial public package candidate.
+
+- Adds the `shopify-agent` CLI for Shopify setup, theme development, Admin GraphQL operations, and agent guardrail installation.
+- Wraps Shopify CLI 4.x for auth, theme, app, and store operations.
+- Adds guarded commands for products, variants, collections, inventory, orders, customers, discounts, gift cards, pages, redirects, metafields, and store dashboards.
+- Adds live theme safety prompts and mutation confirmations.
+- Pulls each Shopify theme into `themes/<theme-name>-<theme-id>/` with metadata to avoid cross-theme overwrites.
+- Requires a clean Git worktree before theme pull, push, and publish operations.
+- Installs default guardrails for Codex, Claude, Cursor, and Gemini.
+- Includes GraphQL templates, onboarding docs, Figma-to-Dawn workflow notes, and field learnings.