Marketplace Scaffold

# Architecture Decision Guide

## Client-Side vs Full-Stack

| Factor | Client-Side Only | Full-Stack (Auth0) |
|--------|------------------|--------------------|
| **Scaffold URL** | `app-client.json` | `app-auth0.json` |
| **Auth** | Built-in (automatic) | Auth0 (requires tenant) |
| **Server-side SDK** | No | Yes (`experimental_createXMCClient`, `experimental_createAIClient`) |
| **API Routes** | Not needed | Yes (Next.js API routes / Server Actions) |
| **External APIs** | Direct from client only | Can proxy through server |
| **Complexity** | Lower | Higher |
| **Use when** | Simple UI extensions, read-only data, client-side mutations | Need server-side processing, Auth0, external service integration |

## Package Selection

| Package | Registry URL | Provides |
|---------|-------------|----------|
| **Client** (required) | `app-client.json` | `ClientSDK.init()`, queries, mutations, subscriptions, types |
| **XM Cloud** | `xmc.json` | Sites, Pages, Authoring (GraphQL), Content Transfer, Search, Agent APIs |
| **AI Skills** | `ai.json` | Brand Review API for AI-powered content analysis |
| **Blok Theme** | `blok-theme.json` | Sitecore-branded shadcn components (always install) |

## What the Scaffold Creates

### Client-side (`app-client.json`)
- `lib/sitecore/client.ts` — Client initialization with `ClientSDK.init()`
- `lib/sitecore/providers.tsx` — React context providers (`<SitecoreProvider>`)
- `hooks/use-sitecore.ts` — React hooks for SDK access
- `app/layout.tsx` updates — Wraps app in providers

### Full-stack (`app-auth0.json`)
- Everything from client-side, plus:
- `lib/sitecore/server.ts` — Server-side client factories
- `app/api/auth/[...auth0]/route.ts` — Auth0 route handlers
- `middleware.ts` — Auth0 middleware

### XMC (`xmc.json`)
- `lib/sitecore/xmc.ts` — XMC module registration
- Types for all XM Cloud APIs

### AI (`ai.json`)
- `lib/sitecore/ai.ts` — AI module registration
- Types for Brand Review API


# Environment Variable Templates

## Client-Side Only (.env.local)

```env
# Sitecore Marketplace SDK
NEXT_PUBLIC_SITECORE_APP_ID=your-app-id-from-portal
```

## Full-Stack with Auth0 (.env.local)

```env
# Sitecore Marketplace SDK
NEXT_PUBLIC_SITECORE_APP_ID=your-app-id-from-portal

# Auth0 Configuration
AUTH0_SECRET=use-openssl-rand-hex-32-to-generate
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://your-tenant.auth0.com
AUTH0_CLIENT_ID=your-auth0-client-id
AUTH0_CLIENT_SECRET=your-auth0-client-secret

# Auth0 Sitecore Connection
AUTH0_AUDIENCE=https://api.sitecorecloud.io
AUTH0_SCOPE=openid profile email
```

## How to Get Values

| Variable | Where to find it |
|----------|-----------------|
| `NEXT_PUBLIC_SITECORE_APP_ID` | Sitecore Developer Portal → Your App → Settings |
| `AUTH0_SECRET` | Generate: `openssl rand -hex 32` |
| `AUTH0_BASE_URL` | Your app URL (localhost for dev) |
| `AUTH0_ISSUER_BASE_URL` | Auth0 Dashboard → Applications → Your App → Domain |
| `AUTH0_CLIENT_ID` | Auth0 Dashboard → Applications → Your App → Client ID |
| `AUTH0_CLIENT_SECRET` | Auth0 Dashboard → Applications → Your App → Client Secret |
| `AUTH0_AUDIENCE` | Always `https://api.sitecorecloud.io` for Sitecore |


---
name: marketplace-scaffold
description: Scaffolds a new Sitecore Marketplace app using the official SDK. Use when the user wants to create a new marketplace app, start a new Sitecore project, or initialize a marketplace integration.
argument-hint: "[app-name]"
---

# Scaffold a New Sitecore Marketplace App

You are helping the user scaffold a new Sitecore Marketplace app using the official Sitecore Marketplace SDK (v0.4).

## Step 1: Gather Requirements

Ask the user the following questions (skip any they've already answered):

1. **App name** — What should the app be called? (default: from $ARGUMENTS if provided)
2. **Architecture** — Client-side only or full-stack?
   - **Client-side**: UI runs entirely in the iframe, communicates via SDK client. Simpler, no server needed.
   - **Full-s