@payloadcms/figma 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/db-content-api/utilities/data/stringifyNumericIds.js

@@ -0,0 +1,19 @@
+// The Content API stores every document id as a string, but Payload keeps a
+// collection's custom numeric id as a `number`. Stringify numbers so an id filter
+// matches the stored value.
+// Has two shapes it accepts:
+// - Scalar values (most operators)
+// - Arrays of values (for `in`/`not_in` operators)
+// Non-numeric entries (already-string ids) pass through untouched.
+export function stringifyNumericIds(value) {
+    if (typeof value === 'number') {
+        return stringifyNumericId(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry)=>stringifyNumericId(entry));
+    }
+    return value;
+}
+function stringifyNumericId(value) {
+    return typeof value === 'number' ? String(value) : value;
+}

package/dist/db-content-api/utilities/isRecord.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A plain, string-keyed object — the shape that can safely be spread and have
+ * properties read off it without tripping over arrays, `null`, or exotic objects.
+ *
+ * Objects carrying symbol-keyed own properties are rejected: symbol keys are how
+ * libraries tag a value as something more than data, and a spread copies only the
+ * string keys, so treating such a value as a record silently strips the tag.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/db-content-api/utilities/isRecord.js

@@ -0,0 +1,19 @@
+/**
+ * A plain, string-keyed object — the shape that can safely be spread and have
+ * properties read off it without tripping over arrays, `null`, or exotic objects.
+ *
+ * Objects carrying symbol-keyed own properties are rejected: symbol keys are how
+ * libraries tag a value as something more than data, and a spread copies only the
+ * string keys, so treating such a value as a record silently strips the tag.
+ */ export function isRecord(value) {
+    if (value == null) {
+        return false;
+    }
+    if (typeof value !== 'object') {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        return false;
+    }
+    return Object.getOwnPropertySymbols(value).length === 0;
+}

package/dist/db-content-api/utilities/where.js

@@ -1,3 +1,4 @@
+import { stringifyNumericIds } from './data/stringifyNumericIds.js';
 export function convertPayloadWhereToContentAPI(where, options = {}) {
     // Empty where {} should be { and: [] } not undefined
     // Content API requires a where clause structure even for "no filter"
@@ -42,7 +43,7 @@ export function convertPayloadWhereToContentAPI(where, options = {}) {
                 conditions.push({
                     operator: 'equals',
                     path: fieldPath,
-                    value: fieldPath === 'id' && typeof value === 'number' ? String(value) : value
+                    value: fieldPath === 'id' ? stringifyNumericIds(value) : value
                 });
                 continue;
             }
@@ -69,9 +70,10 @@ export function convertPayloadWhereToContentAPI(where, options = {}) {
                 }
                 // Content API stores all document IDs as strings.
                 // Payload sends numeric values for collections with custom numeric ID fields,
-                // so we must stringify to match.
-                if (fieldPath === 'id' && typeof finalValue === 'number') {
-                    finalValue = String(finalValue);
+                // so we must stringify to match. This includes the `in`/`not_in` arrays that
+                // Payload's relationship-population dataloader always uses ({ id: { in: [...] } }).
+                if (fieldPath === 'id') {
+                    finalValue = stringifyNumericIds(finalValue);
                 }
                 conditions.push({
                     operator: op,

package/dist/lib/write-agent-config.d.ts

@@ -0,0 +1,12 @@
+export type WriteAgentConfigResult = {
+    agentsMd: 'appended' | 'created' | 'unchanged';
+    claudeMd: 'appended' | 'created' | 'unchanged';
+};
+/**
+ * Write the root AI-agent pointer files so assistants can find the Payload
+ * skill bundled in node_modules. Idempotent: creates when absent, appends the
+ * pointer when a file exists without it, and no-ops when already present.
+ */
+export declare function writeAgentConfigFiles(args: {
+    projectDir: string;
+}): Promise<WriteAgentConfigResult>;

package/dist/lib/write-agent-config.js

@@ -0,0 +1,52 @@
+import fs from 'fs/promises';
+import path from 'path';
+const SKILL_POINTER_PATH = 'node_modules/payload/skills/payload/SKILL.md';
+const AGENTS_BLOCK = `# AI Agent
+
+For any Payload-related work, reference the skill at
+\`${SKILL_POINTER_PATH}\`.
+`;
+const CLAUDE_IMPORT = '@AGENTS.md';
+/**
+ * Write the root AI-agent pointer files so assistants can find the Payload
+ * skill bundled in node_modules. Idempotent: creates when absent, appends the
+ * pointer when a file exists without it, and no-ops when already present.
+ */ export async function writeAgentConfigFiles(args) {
+    const agentsMd = await ensureFileContains({
+        content: AGENTS_BLOCK,
+        filePath: path.join(args.projectDir, 'AGENTS.md'),
+        marker: SKILL_POINTER_PATH
+    });
+    const claudeMd = await ensureFileContains({
+        content: `${CLAUDE_IMPORT}\n`,
+        filePath: path.join(args.projectDir, 'CLAUDE.md'),
+        marker: CLAUDE_IMPORT
+    });
+    return {
+        agentsMd,
+        claudeMd
+    };
+}
+async function ensureFileContains(args) {
+    const existing = await readFileOrNull(args.filePath);
+    if (existing === null) {
+        await fs.writeFile(args.filePath, args.content, 'utf8');
+        return 'created';
+    }
+    if (existing.includes(args.marker)) {
+        return 'unchanged';
+    }
+    const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+    await fs.writeFile(args.filePath, `${existing}${separator}${args.content}`, 'utf8');
+    return 'appended';
+}
+async function readFileOrNull(filePath) {
+    try {
+        return await fs.readFile(filePath, 'utf8');
+    } catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            return null;
+        }
+        throw err;
+    }
+}

package/dist/skills/deploy-to-figma/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: deploy-to-figma
+description: This skill should be used when the user asks to "deploy to Figma", "publish to Figma", "ship to Figma", "deploy my app to Figma Cloud", "put this Payload site on Figma", or otherwise wants to deploy the current project to Figma Cloud. You (the agent) inspect, classify, and build the target project; the @payloadcms/figma CLI only authenticates and deploys the verified artifact you hand it.
+version: 0.2.0
+allowed-tools: Read, Bash, AskUserQuestion
+---
+
+# Deploy to Figma Cloud
+
+Deploy a project to Figma Cloud with the `@payloadcms/figma` CLI. **You** (the
+agent) determine the deploy shape — you inspect the project, run the build, and
+verify the real build artifacts, then hand the CLI an explicit adapter and
+output root you have confirmed on disk. The CLI no longer inspects the project;
+it only authenticates and ships the artifact you point it at.
+
+**Golden rule:** detection is your job. Read files and inspect real artifacts —
+do not ask `@payloadcms/figma` what framework this is, and do not guess. When the
+evidence conflicts or the shape isn't one Figma Cloud supports, **stop** before
+touching auth or deploy.
+
+Run the CLI with `npx @payloadcms/figma@alpha <...>` **from the target folder**.
+If a different invocation is already established in the repo (e.g.
+`pnpm start --`), use that instead — but `npx @payloadcms/figma@alpha` is the
+default.
+
+If the user's request contains **“Figma staging”** (case-insensitive), append
+`--infra-env staging` to every CLI invocation in this flow, including login,
+login completion, deploy, and deploy retries. Otherwise omit the flag.
+
+## Flow overview
+
+1. **Resolve** the target project directory.
+2. **Inspect & classify** the deploy shape from evidence — or stop if unsupported/ambiguous.
+3. **Build & verify** the real artifact (buildable projects); static folders skip the build.
+4. **Detect initialization** from `target/.env`; gather creation inputs if uninitialized.
+5. **Preflight auth** with the resumable headless flow.
+6. **Deploy** the verified artifact with an explicit `--adapter` and `--output`.
+7. **Report** the deployed URL.
+
+Exact CLI contracts (flags, JSON shapes, artifact signatures) live in
+`references/cli-reference.md` — consult it when a flag or field is unclear.
+
+## Step 1 — Resolve the target directory
+
+- If the prompt names a directory, that is the target.
+- Otherwise use the current folder.
+- In a **monorepo**, operate from the target **package** folder — not the repo
+  root. If several plausible apps exist and none is clearly the target, **ask**
+  via `AskUserQuestion` rather than guessing.
+
+Every command and the build run **from the target folder**.
+
+## Step 2 — Inspect and classify the deploy shape
+
+Gather evidence yourself with `Read`/`Bash`. Do **not** rely on
+`@payloadcms/figma` for detection. Look at:
+
+- `package.json` — `dependencies`/`devDependencies`, `scripts.build`, and
+  `packageManager`.
+- Lockfiles — `pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`.
+- Framework config — `next.config.*`, `vite.config.*`, `nitro.config.*`,
+  `nuxt.config.*`, `app.config.*`.
+- Source layout and any build artifacts already on disk.
+
+Map the evidence to one **supported deploy shape**:
+
+| Evidence | Shape | `--adapter` |
+| --- | --- | --- |
+| `next` dependency / `next.config.*` / a `next build` script | Next.js | `nextjs` |
+| Nitro, Nuxt, TanStack Start, or any other evidenced Nitro output | Nitro | `nitro` |
+| A built (or buildable) Vite single-page app | Vite | `vite` |
+| A simple static folder — `index.html` plus CSS/JS/assets, no build needed (even with **no** `package.json`) | Static | `vite`, output = that folder |
+
+If the evidence fits **none** of these, or points at **more than one** framework
+with no clear winner, or you otherwise can't land confidently on one supported
+shape → **go to Step 8 and stop**. Do not build, authenticate, or deploy.
+
+## Step 3 — Build and verify the artifact
+
+**Buildable projects** (Next.js / Nitro / Vite): run the build **from the target
+folder, before** any auth or project creation, with `FIGMA_EXTRACT_SCHEDULES=true`.
+
+Pick the package manager by searching the **target folder and its ancestors**
+(up to the repo/monorepo root) — in a monorepo the `packageManager` field and
+the lockfile usually live at the workspace root, not in the target package.
+Precedence: nearest `packageManager` field → nearest lockfile
+(`pnpm-lock.yaml`→pnpm, `package-lock.json`→npm, `yarn.lock`→yarn,
+`bun.lockb`→bun) → available tooling. Run the build itself **from the target
+package folder** with whichever manager you resolved, e.g.:
+
+```bash
+FIGMA_EXTRACT_SCHEDULES=true npm run build
+```
+
+Then **inspect the actual artifacts** to confirm the adapter and the output
+**root**:
+
+- **Next.js** — the root contains `BUILD_ID` and standalone server output. Pass
+  the root (e.g. `.next`) — **never** `.next/standalone`.
+- **Nitro** — the root contains `server/index.mjs` (typically `.output`).
+- **Vite** — the root contains `index.html` (typically `dist`).
+
+**Static folders** skip the build entirely. The output is the exact folder that
+contains `index.html` (often `.`).
+
+If the build fails, or the artifacts don't match the shape you classified (the
+evidence now conflicts), **stop** — go to Step 8. Never pass an `--output` root
+you have not confirmed exists on disk.
+
+## Step 4 — Detect initialization; gather creation inputs
+
+Detect initialization **only** by testing whether `target/.env` contains a
+nonempty `FIGMA_PROJECT_ID`, e.g.:
+
+```bash
+test -f .env && grep -Eq '^FIGMA_PROJECT_ID=.+' .env && echo initialized || echo uninitialized
+```
+
+Do **not** print the value or dump `.env`.
+
+**Initialized** (`FIGMA_PROJECT_ID` present) → skip this step; pass no creation flags.
+
+**Uninitialized** → gather the five project-creation fields across **two** grouped
+`AskUserQuestion` interactions (a single call accepts at most four questions),
+each field offering the CLI default so the user can accept as-is:
+
+**Interaction 1 — naming** (three questions):
+
+| Field | CLI default | Deploy flag |
+| --- | --- | --- |
+| Project name | derived from the directory name | `--name` |
+| Description | `"<name> project"` | `--description` |
+| Subdomain | slugified from the project name | `--subdomain` |
+
+**Interaction 2 — placement** (two questions):
+
+| Field | CLI default | Deploy flag |
+| --- | --- | --- |
+| Workspace | the account's default Figma workspace | `--workspace` |
+| Region | `us-east-1` | `--region` |
+
+Present the defaults as the recommended option. For any field left at its
+default, **omit** the corresponding flag and let the CLI apply the default — only
+pass a flag when the user supplied a non-default value.
+
+## Step 5 — Preflight authentication
+
+The deploy command needs a valid credential and cannot open a browser in a
+headless/agent context, so authenticate first with the resumable headless flow.
+
+```bash
+npx @payloadcms/figma@alpha login --headless --json
+```
+
+Parse `status`:
+
+- `authenticated` — already logged in. Proceed to deploy.
+- `authorization_required` — the JSON includes `authorizationUrl` and
+  `sessionId`. Give the user the `authorizationUrl`, ask them to open it,
+  approve, and paste back **the full redirected URL** (the
+  `http://localhost:.../callback?...` address the browser lands on). Then:
+
+```bash
+npx @payloadcms/figma@alpha login --complete <sessionId> --callback-url '<redirect-url>' --json
+```
+
+Quote the callback URL in single quotes. Expect `{"status":"authenticated",...}`.
+
+**Handle the callback URL as a one-time secret:** pass it directly to the
+`--complete` command and nothing else. Do not echo it back, summarize it, store
+it in a file, or repeat it in later messages.
+
+If completion fails, report the CLI's error and let the user retry the login
+step; do not loop silently.
+
+## Step 6 — Deploy
+
+Run **from the target folder**, non-interactively with `-y`. Always pass
+`--skip-build` (you already built, or a static folder needs no build) and the
+explicit `--adapter` / `--output` you verified in Steps 2–3:
+
+```bash
+npx @payloadcms/figma@alpha deploy -y --skip-build --adapter <nextjs|nitro|vite> --output <verified-root>
+```
+
+Add the project-creation flags from Step 4 only for an uninitialized project.
+
+Examples:
+
+```bash
+# Next.js app in a monorepo package (already initialized), built to .next
+npx @payloadcms/figma@alpha deploy -y --skip-build --adapter nextjs --output .next
+
+# Vite single-page app, built to dist
+npx @payloadcms/figma@alpha deploy -y --skip-build --adapter vite --output dist
+
+# Simple static folder (index.html at the folder root), no build
+npx @payloadcms/figma@alpha deploy -y --skip-build --adapter vite --output .
+```
+
+### Deterministic retry — workspace selection
+
+If deploy fails with a message like:
+
+> Multiple eligible Figma workspaces. Pass --workspace `<plan-key>`. Available: Acme (plan_abc), Beta (plan_xyz)
+
+re-run the exact same command with `--workspace <plan-key>` added, choosing the
+plan key the user selected (ask via `AskUserQuestion` if not already known,
+listing the workspaces from the error's `Available:` list). This is the only
+retry to perform automatically. For other errors, surface the CLI message and stop.
+
+## Step 7 — Report the result
+
+On success the CLI prints a line like `URL: https://<subdomain>.<domain>`.
+Extract that URL and report it to the user as the deployed address, noting the
+CLI's own message that a deploy usually takes 2–3 minutes to finish.
+
+## Step 8 — Unsupported or ambiguous → stop
+
+If Steps 2–3 can't land confidently on one supported shape, **stop before auth
+or deploy**. Tell the user what you found and quote the supported set:
+
+> Figma Cloud supports Next.js, Vite single-page apps, and any Nitro-based app
+> (including Nuxt and TanStack Start).
+
+Never run `login` or `deploy` for an unsupported or ambiguous project. Decide
+this **before** asking an uninitialized project's creation questions — never make
+the user answer prompts only to fail on an unsupported framework.
+
+## Additional resources
+
+- **`references/cli-reference.md`** — the deploy/login flags this skill uses, the
+  `login ... --json` JSON shapes, and the on-disk artifact signatures that
+  confirm each adapter and output root.

package/dist/skills/deploy-to-figma/references/cli-reference.md

@@ -0,0 +1,146 @@
+# @payloadcms/figma CLI reference (deploy-to-figma)
+
+Exact contracts the orchestration depends on. Source of truth is the CLI itself
+(`payload/payload-plugin` in figma/figma); this file mirrors the flags and shapes
+the skill reads. If something is unclear, run the command and inspect the raw
+output rather than guessing.
+
+The CLI does **not** inspect the project — there is no `deploy --inspect` and no
+project-inspection JSON API. The agent classifies the deploy shape from evidence
+(see `SKILL.md` Steps 2–3) and hands the CLI an explicit `--adapter` and
+`--output`.
+
+## Classifying the deploy shape (agent-driven)
+
+Detect the shape yourself from files on disk. Do **not** call `@payloadcms/figma`
+to detect it.
+
+| Evidence | adapter | typical output root |
+| --- | --- | --- |
+| Next.js — `next` dep, `next.config.*`, or a `next build` script | `nextjs` | `.next` |
+| Nitro / Nuxt / TanStack Start / other evidenced Nitro output | `nitro` | `.output` |
+| Built Vite single-page app | `vite` | `dist` |
+| Simple static folder — `index.html` + CSS/JS/assets, no build (no `package.json` OK) | `vite` | the folder itself (often `.`) |
+
+Framework config hints: Next.js `distDir` (`next.config.*`), Vite `build.outDir`
+(`vite.config.*`), Nitro/Nuxt `output.dir` (`nitro.config.*` / `nuxt.config.*`).
+Custom output dirs mean you must confirm the real root against artifacts below.
+
+### On-disk artifact signatures (confirm before deploy)
+
+After building (or for a static folder, as-is), confirm the output **root** by
+what it contains:
+
+- **Next.js** — root contains `BUILD_ID` **and** standalone server output. Pass
+  the root such as `.next`; **never** `.next/standalone`.
+- **Nitro** — root contains `server/index.mjs` (typically `.output`).
+- **Vite / static** — root contains `index.html` (typically `dist`; a static
+  folder may be `.`).
+
+If the build fails or the artifacts don't match the classified shape, **stop** —
+do not pass an unverified `--output`.
+
+## Building
+
+Run the target package's build **from the target folder**, before auth, with
+`FIGMA_EXTRACT_SCHEDULES=true`. Choose the package manager by searching the
+target folder **and its ancestors** (up to the repo/monorepo root) — the
+`packageManager` field and the lockfile often live at the workspace root, not
+the target package. Precedence: nearest `packageManager` field → nearest
+lockfile (`pnpm-lock.yaml`→pnpm, `package-lock.json`→npm, `yarn.lock`→yarn,
+`bun.lockb`→bun) → available tooling. Even so, run the build itself from the
+target package folder. Static folders skip the build.
+
+```bash
+FIGMA_EXTRACT_SCHEDULES=true npm run build
+```
+
+## `login --headless --json`
+
+Starts (or short-circuits) a resumable login without a live terminal.
+
+Already authenticated:
+
+```json
+{ "status": "authenticated", "userId": "..." }
+```
+
+Authorization required:
+
+```json
+{
+  "status": "authorization_required",
+  "authorizationUrl": "https://www.figma.com/oauth?...",
+  "sessionId": "sess_...",
+  "expiresAt": 1730000000000
+}
+```
+
+## `login --complete <sessionId> --callback-url '<url>' --json`
+
+Completes a pending headless login using the full redirect URL the browser
+landed on (`http://localhost:<port>/callback?code=...&state=...`). Returns:
+
+```json
+{ "status": "authenticated", "userId": "..." }
+```
+
+Treat the callback URL as a one-time secret: pass it once, never echo or persist it.
+
+## Infrastructure environment
+
+When the user's request contains “Figma staging” (case-insensitive), append
+`--infra-env staging` to every CLI command, including login, login completion,
+deploy, and deploy retries. Otherwise omit the flag.
+
+## `deploy` flags used by this skill
+
+The deploy command is always explicit — the agent supplies the verified adapter
+and output root and skips the build (it already ran, or the folder is static):
+
+```bash
+npx @payloadcms/figma@alpha deploy -y --skip-build --adapter <nextjs|nitro|vite> --output <root>
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `-y`, `--yes` | Non-interactive; safe project-creation defaults |
+| `--infra-env staging` | Target Figma staging when explicitly requested |
+| `--skip-build` | Always passed — deploy the artifact as-is, never rebuild |
+| `--adapter <name>` | `nextjs` \| `vite` \| `nitro` — the shape you classified |
+| `--output <path>` | The exact, verified build output root |
+| `--name <name>` | Project name (uninitialized project creation) |
+| `--description <text>` | Project description (uninitialized) |
+| `--subdomain <sub>` | Requested subdomain (uninitialized) |
+| `--workspace <planKey>` | Workspace plan key (uninitialized; also the retry flag) |
+| `--region <region>` | Region, e.g. `us-east-1` (uninitialized) |
+
+Initialization is detected only by a nonempty `FIGMA_PROJECT_ID` in `target/.env`
+(never printed). Initialized projects pass no creation flags.
+
+## Deterministic deploy retry
+
+When multiple eligible workspaces exist and none is a default, non-interactive
+deploy fails with:
+
+```text
+Multiple eligible Figma workspaces. Pass --workspace <plan-key>. Available: <Name> (<plan-key>), ...
+```
+
+Re-run the identical command with `--workspace <plan-key>` for the chosen
+workspace. An invalid `--workspace` value fails with:
+
+```text
+Workspace plan key "<key>" is not eligible. Available: <Name> (<plan-key>), ...
+```
+
+## Success output
+
+On success the CLI prints:
+
+```text
+URL: https://<subdomain>.<domain>
+This usually takes 2-3 minutes to complete.
+```
+
+Extract the `URL:` line as the deployed address.

package/dist/types.d.ts

@@ -1,11 +1,16 @@
 import type arg from 'arg';
 export interface Args extends arg.Spec {
     '--adapter': StringConstructor;
+    '--callback-url': StringConstructor;
+    '--complete': StringConstructor;
     '--debug': BooleanConstructor;
+    '--description': StringConstructor;
     '--dry-run': BooleanConstructor;
     '--env': StringConstructor;
     '--environment': string;
     '--force': BooleanConstructor;
+    '--global': BooleanConstructor;
+    '--headless': BooleanConstructor;
     '--help': BooleanConstructor;
     '--id': StringConstructor;
     '--infra-env': StringConstructor;
@@ -13,7 +18,11 @@ export interface Args extends arg.Spec {
     '--logout': BooleanConstructor;
     '--name': StringConstructor;
     '--output': StringConstructor;
+    '--project': BooleanConstructor;
+    '--region': StringConstructor;
+    '--subdomain': StringConstructor;
     '--template': StringConstructor;
+    '--workspace': StringConstructor;
     '--yes': BooleanConstructor;
     '-e': string;
     '-f': string;

package/dist/utils/lambda-config.js

@@ -1,6 +1,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { IndentationText, Node, Project, SyntaxKind } from 'ts-morph';
+import { ensurePnpmWorkspace } from './pnpm-builds.js';
 const RUN_SH_CONTENT = `#!/bin/bash -x
 
 [ ! -d '/tmp/cache' ] && mkdir -p /tmp/cache
@@ -19,21 +20,10 @@ NODE_ENV=production exec node server.js
     await fs.chmod(runShPath, 0o755);
     // 2. Modify next config to add standalone output
     await addNextConfigProperties(projectPath);
-    // 3. Create/update .npmrc
-    const npmrcPath = path.join(projectPath, '.npmrc');
-    let npmrcContent = '';
-    try {
-        npmrcContent = await fs.readFile(npmrcPath, 'utf-8');
-    } catch  {
-    // File doesn't exist, start fresh
-    }
-    if (!npmrcContent.includes('node-linker=hoisted')) {
-        npmrcContent += npmrcContent && !npmrcContent.endsWith('\n') ? '\n' : '';
-        npmrcContent += 'node-linker=hoisted\n';
-        await fs.writeFile(npmrcPath, npmrcContent, 'utf-8');
-    }
-    // 4. Add lambda:buildzip script to package.json
+    // 3. Add lambda:buildzip script to package.json
     await addLambdaBuildScript(projectPath, packageManager);
+    // 4. Write pnpm-workspace.yaml (hoisted linker + build approvals)
+    await ensurePnpmWorkspace(projectPath);
 }
 /**
  * Find the Next.js config file, checking TS extensions first

package/dist/utils/messages.js

@@ -14,6 +14,7 @@ export function helpMessage() {
       ${pc.cyan('logout')}           Clear all stored tokens
       ${pc.cyan('list-tokens')}      Show stored token information
       ${pc.cyan('init')}             Initialize a Figma CMS project
+      ${pc.cyan('setup-agent')}      Install or update the Figma deploy skill
       ${pc.cyan('bootstrap')}        Print bootstrap info (tenant IDs, OAuth creds) for a project
       ${pc.cyan('debug')}            Show debug info for troubleshooting
       ${pc.cyan('env')}              Switch active environment
@@ -31,16 +32,20 @@ export function helpMessage() {
   ${pc.bold('AUTHENTICATION')}
 
       ${pc.cyan('@payloadcms/figma login')}                Authenticate with Figma
+      ${pc.cyan('@payloadcms/figma login --headless --json')} Start resumable login for agents
+      ${pc.cyan('@payloadcms/figma login --complete <id> --callback-url <url>')} Complete resumable login
+      ${pc.dim('--json')}                                  Emit machine-readable login status
       ${pc.cyan('@payloadcms/figma logout')}               Clear tokens for current environment
       ${pc.cyan('@payloadcms/figma list-tokens')}          Display stored OAuth and project tokens
 
   ${pc.bold('INIT COMMAND')}
 
-      ${pc.cyan('@payloadcms/figma init --id <cms-resource-id>')}     Initialize project
+      ${pc.cyan('@payloadcms/figma init')}                            Create and initialize project
+      ${pc.cyan('@payloadcms/figma init --id <cms-resource-id>')}     Connect existing project
       ${pc.cyan('@payloadcms/figma init --id <id> --env staging')}    Initialize for specific environment
       ${pc.dim('--name, -n <name>')}                     Set project directory name (skips prompt)
       ${pc.dim('--force')}                               Force reconfiguration of existing project
-      ${pc.dim('--no-skill')}                            Skip installing the Payload skill into .claude/skills/payload/
+      ${pc.dim('--no-agent')}                            Skip writing AI agent config files (AGENTS.md, CLAUDE.md)
       ${pc.dim('--template, -t <spec>')}                  Override scaffold template (e.g. main:website, owner/repo#ref:path)
       ${pc.dim('--payload-version <tag|version>')}        Core Payload npm dist-tag or version (default canary; e.g. latest, 4.0.0-canary.16)
 
@@ -58,14 +63,28 @@ export function helpMessage() {
   ${pc.bold('DEPLOY COMMAND')}
 
       ${pc.cyan('@payloadcms/figma deploy')}             Deploy your project to Figma
+      ${pc.dim('                                            Creates a project when not initialized')}
       ${pc.dim('--id <project-id>')}                     Override FIGMA_PROJECT_ID
       ${pc.dim('--env <environment>')}                   Override FIGMA_ENVIRONMENT_NAME
-      ${pc.dim('--yes, -y')}                             Skip confirmation prompts
+      ${pc.dim('--yes, -y')}                             Skip prompts; use safe defaults for project creation
+      ${pc.dim('--name <name>')}                         New project name (default: package/directory name)
+      ${pc.dim('--description <description>')}           New project description (default: <name> project)
+      ${pc.dim('--subdomain <subdomain>')}               New project subdomain (default: generated from name)
+      ${pc.dim('--workspace <plan-key>')}                Workspace plan key (default workspace if omitted)
+      ${pc.dim('--region <region>')}                     New project region (default: us-east-1 non-interactively)
       ${pc.dim('--skip-build')}                          Skip building and use existing build
       ${pc.dim('--skip-size-check')}                     Skip the client-side bundle size check
       ${pc.dim('--adapter <nextjs|nitro|vite>')}          Override framework detection
       ${pc.dim('--output <path>')}                        Exact framework build output root
 
+  ${pc.bold('SETUP AGENT COMMAND')}
+
+      ${pc.cyan('@payloadcms/figma setup-agent')}                    Prompt for global or project installation
+      ${pc.cyan('@payloadcms/figma setup-agent --global')}           Install/update globally
+      ${pc.cyan('@payloadcms/figma setup-agent --project')}          Install/update in the current project
+      ${pc.dim('--yes, -y')}                             Skip skills installer prompts
+      ${pc.dim('Non-interactive use requires --global or --project.')}
+
   ${pc.bold('UPGRADE COMMAND')}
 
       ${pc.cyan('@payloadcms/figma upgrade')}              Run all upgrade migrations

package/dist/utils/payload-generate.d.ts

@@ -0,0 +1,10 @@
+export type PayloadGenerateResult = {
+    error: string;
+    ok: false;
+} | {
+    ok: true;
+};
+/** Never throws. */
+export declare function generateImportMap(projectPath: string): Promise<PayloadGenerateResult>;
+/** Never throws. */
+export declare function generateTypes(projectPath: string): Promise<PayloadGenerateResult>;