@dk/jolly 0.1.10 → 0.2.0

package/src/index.ts

@@ -1,2095 +1,2011 @@
-#!/usr/bin/env bun
-/**
- * Jolly CLI entry point.
- *
- * Every command emits the feature 020 output envelope. Side-effecting
- * commands accept --dry-run (show risk context, make no changes). All
- * commands accept --json (stdout = envelope only) and --quiet (reduced
- * human text).
- *
- * The entry is executable via `npx @saleor/jolly` (production) or
- * `npx @dk/jolly` (testing). Also runnable directly with `bun src/index.ts`.
- */
-import { existsSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { loadEnvValues, writeEnvValues } from "./lib/env-file.ts";
-import { normalizeSaleorUrl } from "./lib/saleor-url.ts";
+// Jolly — the thin, skill-driven CLI (decision 2026-06-13).
+//
+// Jolly does not replace the customer's agent. It does deterministic plumbing
+// (login/logout/auth status, create store/app-token/stripe, init, start,
+// doctor, upgrade, skills) and installs the Jolly skill plus the Saleor
+// agent-skills; the customer's agent runs the official CLIs (`npx vercel`,
+// `@saleor/configurator`, `git`, `pnpm`). Jolly never shells out to the Vercel
+// CLI or Configurator and holds no Vercel token.
+//
+// Every command emits exactly one output envelope (feature 020):
+//   { command, status, summary, data, checks, nextSteps, errors }
+// Field names are camelCase; checks[].status uses the doctor vocabulary;
+// errors[].code is a stable uppercase machine identifier; secrets are
+// referenced by name, never printed. Side-effecting actions carry a feature
+// 021 riskContext inside the envelope, identical for --dry-run and real runs.
+//
+// Runtime: ES module TypeScript, run directly by Bun in dev/test and by
+// Node >= 23 (native type stripping) in production via bin/jolly. Only Node
+// built-ins and the project's own src/lib/ helpers are used.
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { spawnSync } from "node:child_process";
+
 import {
-  CLOUD_API_BASE,
-  CloudApiError,
-  acquireAppToken,
-  createEnvironment,
-  createProject,
-  extractDomainUrl,
-  getEnvironment,
-  listEnvironments,
+  cloudApiBase,
   listOrganizations,
   listProjects,
+  createProject,
   listProjectServices,
   pickService,
+  listEnvironments,
+  createEnvironment,
   pollTaskStatus,
-  taskStatusUrl,
+  getEnvironment,
+  extractDomainUrl,
+  acquireAppToken,
+  CloudApiError,
+  type CloudOrganization,
 } from "./lib/cloud-api.ts";
+import { loadEnvValues, writeEnvValues } from "./lib/env-file.ts";
+import { normalizeSaleorUrl } from "./lib/saleor-url.ts";
 
-// ── Types ────────────────────────────────────────────────────────────────
+// ─── Envelope types (mirror features/support/envelope.ts) ─────────────────
 
-type Status = "success" | "warning" | "error";
+type EnvelopeStatus = "success" | "warning" | "error";
 type CheckStatus = "pass" | "warning" | "fail" | "skipped" | "unknown";
 type RiskLevel = "low" | "medium" | "high";
-type RiskCategory =
-  | "destructive operations"
-  | "billing"
-  | "payment setup"
-  | "credential handling"
-  | "live deployment"
-  | "production configuration changes";
 
 interface Check {
   id: string;
   status: CheckStatus;
+  description?: string;
+  command?: string;
+  remediation?: string;
   [key: string]: unknown;
 }
 
-interface Envelope {
-  command: string;
-  status: Status;
-  summary: string;
-  data: Record<string, unknown>;
-  checks: Check[];
-  nextSteps: Array<Record<string, unknown>>;
-  errors: Array<{ code: string; message: string; remediation?: string }>;
+interface NextStep {
+  description: string;
+  command?: string;
+  [key: string]: unknown;
+}
+
+interface ErrorEntry {
+  code: string;
+  message: string;
+  remediation?: string;
+  [key: string]: unknown;
 }
 
 interface RiskContext {
   action: string;
   target: unknown;
   riskLevel: RiskLevel;
-  categories: RiskCategory[];
+  categories: string[];
   reversible: boolean;
-  sideEffects: string[];
+  sideEffects: unknown[];
   dryRunAvailable: boolean;
 }
 
-// ── Load .env from working directory ─────────────────────────────────────
-// Load local .env values into process.env so they are available to the
-// CLI regardless of how it is invoked (bun, npx, test harness, etc).
-(() => {
-  const localEnv = loadEnvValues(process.cwd());
-  for (const [key, value] of Object.entries(localEnv)) {
-    if (!(key in process.env)) {
-      process.env[key] = value;
-    }
-  }
-})();
-
-// ── CLI flags ────────────────────────────────────────────────────────────
-
-const args = process.argv.slice(2);
-const FLAG_JSON = args.includes("--json");
-const FLAG_QUIET = args.includes("--quiet");
-const FLAG_DRY_RUN = args.includes("--dry-run");
-const FLAG_HELP = args.includes("--help") || args.includes("-h");
-
-// Strip flags for subcommand parsing
-function cleanArgs(argv: string[]): string[] {
-  return argv.filter((a) => !a.startsWith("--") && !a.startsWith("-"));
+interface Envelope {
+  command: string;
+  status: EnvelopeStatus;
+  summary: string;
+  data: Record<string, unknown>;
+  checks: Check[];
+  nextSteps: NextStep[];
+  errors: ErrorEntry[];
 }
 
-// ── Envelope builder ─────────────────────────────────────────────────────
-
-function buildEnvelope(command: string, overrides: Partial<Envelope>): Envelope {
-  return {
-    command,
-    status: "success",
-    summary: "",
-    data: {},
-    checks: [],
-    nextSteps: [],
-    errors: [],
-    ...overrides,
-  };
+// ─── Argv parsing ─────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+  positionals: string[];
+  json: boolean;
+  quiet: boolean;
+  yes: boolean;
+  dryRun: boolean;
+  help: boolean;
+  options: Record<string, string>;
+  flags: Set<string>;
 }
 
-function output(env: Envelope): void {
-  const json = JSON.stringify(env, null, 0);
-  if (FLAG_JSON) {
-    process.stdout.write(json + "\n");
-  } else if (FLAG_QUIET) {
-    process.stdout.write(json + "\n");
-  } else {
-    // Default: human readable + envelope
-    const emoji = env.status === "success" ? "✓" : env.status === "warning" ? "⚠" : "✗";
-    process.stdout.write(`${emoji} ${env.summary}\n`);
-    process.stdout.write(json + "\n");
+// Flags that take a value (so `--name foo` consumes `foo`).
+const VALUE_FLAGS = new Set([
+  "token",
+  "url",
+  "name",
+  "domain-label",
+  "region",
+  "organization",
+  "mock-organizations",
+  "publishable-key",
+  "secret-key",
+]);
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const positionals: string[] = [];
+  const options: Record<string, string> = {};
+  const flags = new Set<string>();
+  let json = false;
+  let quiet = false;
+  let yes = false;
+  let dryRun = false;
+  let help = false;
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--json") json = true;
+    else if (arg === "--quiet") quiet = true;
+    else if (arg === "--yes" || arg === "-y") yes = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--help" || arg === "-h") help = true;
+    else if (arg.startsWith("--")) {
+      const body = arg.slice(2);
+      const eq = body.indexOf("=");
+      if (eq >= 0) {
+        options[body.slice(0, eq)] = body.slice(eq + 1);
+      } else if (VALUE_FLAGS.has(body) && i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
+        options[body] = argv[++i];
+      } else {
+        flags.add(body);
+      }
+    } else {
+      positionals.push(arg);
+    }
   }
-}
 
-function errorExit(env: Envelope): never {
-  output(env);
-  process.exit(1);
+  return { positionals, json, quiet, yes, dryRun, help, options, flags };
 }
 
-// ── Risk context builder ─────────────────────────────────────────────────
+// ─── Envelope construction helpers ────────────────────────────────────────
 
-function riskContext(
-  action: string,
-  target: unknown,
-  riskLevel: RiskLevel,
-  categories: RiskCategory[],
-  reversible: boolean,
-  sideEffects: string[],
-): RiskContext {
+function envelope(
+  partial: Partial<Envelope> & { command: string; status: EnvelopeStatus; summary: string },
+): Envelope {
   return {
-    action,
-    target,
-    riskLevel,
-    categories: [...categories],
-    reversible,
-    sideEffects: [...sideEffects],
-    dryRunAvailable: true,
+    command: partial.command,
+    status: partial.status,
+    summary: partial.summary,
+    data: partial.data ?? {},
+    checks: partial.checks ?? [],
+    nextSteps: partial.nextSteps ?? [],
+    errors: partial.errors ?? [],
   };
 }
 
-// ── CWD resolution ───────────────────────────────────────────────────────
-
-const cwd = process.cwd();
-
-// ── Command: help ────────────────────────────────────────────────────────
-
-function cmdHelp(subcommand?: string): void {
-  if (subcommand === "create") {
-    output(
-      buildEnvelope("create --help", {
-        status: "success",
-        summary: "Available create subcommands: store, stripe, storefront, recipe, deployment, app-token",
-        data: {
-          subcommands: [
-            { name: "store", description: "Connect or create a Saleor Cloud store" },
-            { name: "stripe", description: "Configure Stripe test-mode credentials" },
-            { name: "storefront", description: "Clone and configure Saleor Paper storefront" },
-            { name: "recipe", description: "Prepare or apply the Jolly Configurator starter recipe" },
-            { name: "deployment", description: "Set up Vercel deployment (alias: deploy)" },
-            { name: "app-token", description: "Acquire a Saleor app token via GraphQL" },
-          ],
-        },
-        nextSteps: [{ description: "Run jolly create <subcommand> --help for details" }],
-      }),
-    );
-    return;
-  }
-
-  if (subcommand === "doctor") {
-    output(
-      buildEnvelope("doctor --help", {
-        status: "success",
-        summary: "Available doctor check groups: skills, saleor, storefront, deployment, stripe",
-        data: {
-          groups: [
-            { name: "skills", description: "Check skill installation status" },
-            { name: "saleor", description: "Check Saleor connectivity and configuration" },
-            { name: "storefront", description: "Check storefront readiness" },
-            { name: "deployment", description: "Check deployment and payment readiness" },
-            { name: "stripe", description: "Check Stripe test-mode setup" },
-          ],
-        },
-        nextSteps: [{ description: "Run jolly doctor <group> for targeted checks" }],
-      }),
-    );
-    return;
-  }
-
-  output(
-    buildEnvelope("--help", {
-      status: "success",
-      summary: "Jolly — Ahoy, agent. Go build a store.",
-      data: {
-        commands: [
-          "init  — Install Saleor agent skills and guidance",
-          "start — End-to-end setup orchestration",
-          "create — Create resources (store, stripe, storefront, recipe, deployment)",
-          "login — Authenticate with Saleor Cloud",
-          "logout — Remove Saleor Cloud auth state",
-          "auth status — Check authentication status",
-          "doctor — Run diagnostics",
-          "skills install — Install Saleor agent skills",
-          "skills update — Update installed skills",
-          "upgrade — Update Jolly-managed assets",
-          "deploy — Alias for create deployment",
-        ],
-      },
-      nextSteps: [{ description: "Run jolly <command> --help for details on a specific command" }],
-    }),
-  );
+function errorEnvelope(
+  command: string,
+  summary: string,
+  errors: ErrorEntry[],
+  extra: Partial<Envelope> = {},
+): Envelope {
+  return envelope({
+    command,
+    status: "error",
+    summary,
+    errors,
+    ...extra,
+  });
 }
 
-// ── Command: init ────────────────────────────────────────────────────────
-
-const JOLLY_AGENTS_BEGIN = "<!-- jolly:begin -->";
-const JOLLY_AGENTS_END = "<!-- jolly:end -->";
+// ─── Output rendering ─────────────────────────────────────────────────────
 
-const DEFAULT_SKILLS = [
-  "saleor-storefront",
-  "saleor-configurator",
-  "storefront-builder",
-  "saleor-core",
-  "saleor-app",
-] as const;
-
-function jollyAgentsSection(): string {
-  return `${JOLLY_AGENTS_BEGIN}
-## Jolly (Saleor agent setup)
-
-Jolly has initialized Saleor agent guidance in this project. Installed skills
-live under \`.jolly/skills/\`:
-
-${DEFAULT_SKILLS.map((s) => `- \`${s}\` — \`.jolly/skills/${s}/SKILL.md\``).join("\n")}
-
-- Run \`npx @saleor/jolly start\` for end-to-end store setup.
-- Live store data access: the read-only Saleor MCP server (https://mcp.saleor.app)
-  provides products, orders, and customers for a configured store.
-- \`.mcp.json\` configures an mcp-graphql server (\`saleor-graphql\`) against your
-  Saleor GraphQL endpoint; it reads \`NEXT_PUBLIC_SALEOR_API_URL\` and
-  \`SALEOR_APP_TOKEN\` from the environment — no secrets are stored in the file.
-${JOLLY_AGENTS_END}`;
+function statusGlyph(status: EnvelopeStatus): string {
+  if (status === "success") return "ok";
+  if (status === "warning") return "warn";
+  return "error";
 }
 
-/** Merge the Jolly section into AGENTS.md without touching user content. */
-function mergeAgentsMd(agentsPath: string): "created" | "updated" | "unchanged" {
-  const section = jollyAgentsSection();
-  if (!existsSync(agentsPath)) {
-    writeFileSync(agentsPath, `# Agent Guidance\n\n${section}\n`);
-    return "created";
-  }
-  const existing = readFileSync(agentsPath, "utf8");
-  const beginIdx = existing.indexOf(JOLLY_AGENTS_BEGIN);
-  const endIdx = existing.indexOf(JOLLY_AGENTS_END);
-  if (beginIdx >= 0 && endIdx > beginIdx) {
-    // Replace only the managed section; user-authored content survives.
-    const before = existing.slice(0, beginIdx);
-    const after = existing.slice(endIdx + JOLLY_AGENTS_END.length);
-    const updated = `${before}${section}${after}`;
-    if (updated === existing) return "unchanged";
-    writeFileSync(agentsPath, updated);
-    return "updated";
+function checkGlyph(status: CheckStatus): string {
+  switch (status) {
+    case "pass":
+      return "pass";
+    case "warning":
+      return "warn";
+    case "fail":
+      return "fail";
+    case "skipped":
+      return "skip";
+    default:
+      return "?";
   }
-  // No managed section yet: append it, preserving everything user-authored.
-  const prefix = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
-  writeFileSync(agentsPath, `${existing}${prefix}\n${section}\n`);
-  return "updated";
 }
 
 /**
- * Merge the Jolly mcp-graphql server entry into .mcp.json without replacing
- * user-authored entries. Never stores secrets: the entry references env var
- * names only. Returns the action taken; "skipped" means the existing file
- * could not be parsed and was left untouched (never silently overwrite).
+ * Render and emit one envelope, honoring --json / --quiet / default mode.
+ * Returns the process exit code (non-zero only for error status).
  */
-function mergeMcpJson(mcpPath: string): "created" | "merged" | "unchanged" | "skipped" {
-  const jollyEntry = {
-    command: "npx",
-    args: ["mcp-graphql"],
-    env: {
-      ENDPOINT: "${NEXT_PUBLIC_SALEOR_API_URL}",
-      HEADERS: '{"Authorization":"Bearer ${SALEOR_APP_TOKEN}"}',
-    },
-  };
-  if (!existsSync(mcpPath)) {
-    writeFileSync(
-      mcpPath,
-      JSON.stringify({ mcpServers: { "saleor-graphql": jollyEntry } }, null, 2) + "\n",
-    );
-    return "created";
-  }
-  let parsed: Record<string, unknown>;
-  try {
-    const raw = JSON.parse(readFileSync(mcpPath, "utf8")) as unknown;
-    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return "skipped";
-    parsed = raw as Record<string, unknown>;
-  } catch {
-    return "skipped";
-  }
-  const servers =
-    parsed.mcpServers !== null &&
-    typeof parsed.mcpServers === "object" &&
-    !Array.isArray(parsed.mcpServers)
-      ? (parsed.mcpServers as Record<string, unknown>)
-      : {};
-  if ("saleor-graphql" in servers) return "unchanged";
-  parsed.mcpServers = { ...servers, "saleor-graphql": jollyEntry };
-  writeFileSync(mcpPath, JSON.stringify(parsed, null, 2) + "\n");
-  return "merged";
-}
-
-function cmdInit(): void {
-  // Detect existing state before making any changes.
-  const jollyDir = join(cwd, ".jolly");
-  const skillsRoot = join(jollyDir, "skills");
-  const existingInit = existsSync(jollyDir) || existsSync(join(cwd, ".skills"));
-
-  // ── Install the default skill set on disk (idempotent) ───────────────
-  const checks: Check[] = [];
-  try {
-    for (const name of DEFAULT_SKILLS) {
-      const skillDir = join(skillsRoot, name);
-      mkdirSync(skillDir, { recursive: true });
-      const skillFile = join(skillDir, "SKILL.md");
-      if (!existsSync(skillFile)) {
-        writeFileSync(
-          skillFile,
-          `# ${name}\n\nSaleor agent skill \`${name}\`, installed by \`jolly init\`.\n`,
+function emit(env: Envelope, args: ParsedArgs): number {
+  if (args.json) {
+    process.stdout.write(JSON.stringify(env) + "\n");
+  } else {
+    const lines: string[] = [];
+    lines.push(`jolly ${env.command}: [${statusGlyph(env.status)}] ${env.summary}`);
+    if (!args.quiet) {
+      for (const check of env.checks) {
+        lines.push(
+          `  - [${checkGlyph(check.status)}] ${check.id}${check.description ? `: ${check.description}` : ""}`,
+        );
+      }
+      for (const step of env.nextSteps) {
+        lines.push(`  next: ${step.description}${step.command ? ` (\`${step.command}\`)` : ""}`);
+      }
+      for (const err of env.errors) {
+        lines.push(
+          `  error[${err.code}]: ${err.message}${err.remediation ? ` — ${err.remediation}` : ""}`,
         );
       }
     }
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    process.stderr.write(`jolly init: skill installation failed: ${message}\n`);
-    errorExit(
-      buildEnvelope("init", {
-        status: "error",
-        summary: `Skill installation failed: ${message}`,
-        data: { existing: existingInit, initialized: false },
-        errors: [{ code: "SKILL_INSTALL_FAILED", message }],
-      }),
-    );
-  }
-
-  // ── Verify on disk: report only what actually exists, never the
-  //    pre-computed name list (feature 007 Rule "Init boundaries") ───────
-  const skills: Array<{ name: string; path: string; verified: true }> = [];
-  const missing: string[] = [];
-  for (const name of DEFAULT_SKILLS) {
-    const relPath = join(".jolly", "skills", name, "SKILL.md");
-    if (existsSync(join(cwd, relPath))) {
-      skills.push({ name, path: relPath, verified: true });
-      checks.push({ id: `skills-${name}`, status: "pass" as CheckStatus, description: `Verified on disk at ${relPath}` });
-    } else {
-      missing.push(name);
-      checks.push({ id: `skills-${name}`, status: "fail" as CheckStatus, description: `Not found on disk at ${relPath}` });
-    }
+    // Human text first, then the machine-readable envelope on its own line.
+    process.stdout.write(lines.join("\n") + "\n");
+    process.stdout.write(JSON.stringify(env) + "\n");
   }
-  if (missing.length > 0) {
-    process.stderr.write(
-      `jolly init: skill verification failed for: ${missing.join(", ")}\n`,
-    );
-    errorExit(
-      buildEnvelope("init", {
-        status: "error",
-        summary: `Skill verification failed: ${missing.join(", ")} not found on disk after install.`,
-        data: { existing: existingInit, initialized: false, skills, missingSkills: missing },
-        checks,
-        errors: [{ code: "SKILL_VERIFY_FAILED", message: `Skills not found on disk after install: ${missing.join(", ")}` }],
-      }),
-    );
-  }
-  const installedSkills = skills.map((s) => s.name);
-
-  // Marker file recording what this run actually verified.
-  writeFileSync(
-    join(jollyDir, "init.json"),
-    JSON.stringify({ initialized: true, version: "0.1.0", installedSkills }, null, 2),
-  );
-
-  // ── Merge (never replace) .mcp.json: configure mcp-graphql ───────────
-  const mcpAction = mergeMcpJson(join(cwd, ".mcp.json"));
-  checks.push({
-    id: "init-mcp-json",
-    status: (mcpAction === "skipped" ? "warning" : "pass") as CheckStatus,
-    description:
-      mcpAction === "skipped"
-        ? ".mcp.json exists but could not be parsed as JSON; left untouched (never silently overwrite)"
-        : `.mcp.json ${mcpAction}: mcp-graphql server entry "saleor-graphql" (env var references only, no secrets)`,
-  });
-
-  // ── Merge (never replace) AGENTS.md: insert/update the Jolly section ─
-  const agentsAction = mergeAgentsMd(join(cwd, "AGENTS.md"));
-  checks.push({
-    id: "init-agents-md",
-    status: "pass" as CheckStatus,
-    description: `AGENTS.md ${agentsAction}: Jolly section merged, user-authored content preserved`,
-  });
+  return env.status === "error" ? 1 : 0;
+}
 
-  // ── Ensure .env is git-ignored ────────────────────────────────────────
-  const gitignorePath = join(cwd, ".gitignore");
-  const existingGi = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
-  if (!existingGi.split("\n").some((l) => l.trim() === ".env")) {
-    const prefix = existingGi.length > 0 && !existingGi.endsWith("\n") ? "\n" : "";
-    writeFileSync(gitignorePath, `${existingGi}${prefix}.env\n`);
-  }
+// ─── Project directory ────────────────────────────────────────────────────
 
-  checks.unshift({
-    id: "init-status",
-    status: "pass" as CheckStatus,
-    description: existingInit
-      ? "Existing Jolly init detected; managed guidance refreshed"
-      : "Skills installed and verified on disk",
-  });
+function projectDir(): string {
+  return process.cwd();
+}
 
-  output(
-    buildEnvelope("init", {
-      status: "success",
-      summary: existingInit
-        ? `Jolly already initialized. Verified ${skills.length} skills on disk; .mcp.json ${mcpAction}; AGENTS.md ${agentsAction}.`
-        : `Jolly initialized. Installed and verified ${skills.length} Saleor agent skills; .mcp.json ${mcpAction}; AGENTS.md ${agentsAction}.`,
-      data: {
-        existing: existingInit,
-        initialized: true,
-        installedSkills,
-        skills,
-        mcpJson: mcpAction,
-        agentsMd: agentsAction,
-        updated: !existingInit || mcpAction === "merged" || agentsAction !== "unchanged",
-      },
-      checks,
-      nextSteps: [
-        { description: "Run jolly start to begin end-to-end setup" },
-      ],
-    }),
-  );
+function envFilePath(): string {
+  return join(projectDir(), ".env");
 }
 
-// ── PKCE helpers ────────────────────────────────────────────────────────
+// ─── Shared skill set (features 007/001) ──────────────────────────────────
 
-function base64UrlEncode(buf: ArrayBuffer): string {
-  return btoa(String.fromCharCode(...new Uint8Array(buf)))
-    .replace(/\+/g, "-")
-    .replace(/\//g, "_")
-    .replace(/=+$/, "");
+interface SkillSpec {
+  id: string;
+  ref: string;
+  description: string;
 }
 
-async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
-  const verifierBytes = new Uint8Array(32);
-  globalThis.crypto.getRandomValues(verifierBytes);
-  const verifier = base64UrlEncode(verifierBytes.buffer);
-  const hash = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
-  const challenge = base64UrlEncode(hash);
-  return { verifier, challenge };
+const DEFAULT_SKILLS: SkillSpec[] = [
+  { id: "jolly", ref: "dmytri/jolly", description: "The Jolly end-to-end playbook" },
+  { id: "saleor-storefront", ref: "saleor/saleor-storefront", description: "Saleor storefront guidance" },
+  { id: "saleor-configurator", ref: "saleor/saleor-configurator", description: "Configuration-as-code guidance" },
+  { id: "storefront-builder", ref: "saleor/storefront-builder", description: "Storefront build guidance" },
+  { id: "saleor-core", ref: "saleor/saleor-core", description: "Saleor core concepts" },
+  { id: "saleor-app", ref: "saleor/saleor-app", description: "Saleor app development guidance" },
+];
+
+// Standard project-local skill location used by `npx skills add`.
+function skillsBaseDir(): string {
+  return join(projectDir(), ".claude", "skills");
 }
 
-function buildKeycloakAuthUrl(verifier: string, challenge: string): string {
-  const params: Record<string, string> = {
-    response_type: "code",
-    client_id: "saleor-cli",
-    code_challenge: challenge,
-    code_challenge_method: "S256",
-    state: base64UrlEncode(new Uint8Array(16).buffer),
-    redirect_uri: "http://127.0.0.1:5375/callback",
-    scope: "email openid profile",
-  };
-  const query = Object.entries(params)
-    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
-    .join("&");
-  return `https://auth.saleor.io/auth/realms/saleor/protocol/openid-connect/auth?${query}`;
+function skillInstalledOnDisk(skill: SkillSpec): boolean {
+  // A skill is present when its directory exists on disk.
+  const dir = join(skillsBaseDir(), skill.id);
+  return existsSync(join(dir, "SKILL.md")) || existsSync(dir);
 }
 
-// ── Command: login ───────────────────────────────────────────────────────
+// ─── login / token verification (feature 018) ─────────────────────────────
+
+const TOKEN_PAGE = "https://cloud.saleor.io/tokens";
 
-async function cmdLogin(token?: string): Promise<void> {
-  const hasBrowser = args.includes("--browser");
-  const exchangeCodeIdx = args.indexOf("--exchange-code");
-  const hasExchangeCode = exchangeCodeIdx >= 0;
-  const exchangeCodeValue = hasExchangeCode ? args[exchangeCodeIdx + 1] : undefined;
-  const tokenIdx = args.indexOf("--token");
-  const tokenValue = tokenIdx >= 0 ? args[tokenIdx + 1] : token;
+function loginRiskContext(dryRunAvailable = true): RiskContext {
+  return {
+    action: "login",
+    target: cloudApiBase(),
+    riskLevel: "medium",
+    categories: ["credential handling"],
+    reversible: true,
+    sideEffects: ["Writes JOLLY_SALEOR_CLOUD_TOKEN to .env when verification permits"],
+    dryRunAvailable,
+  };
+}
 
-  // ── Browser OAuth flow ──────────────────────────────────────────────
-  if (hasBrowser) {
-    const pkce = await generatePKCE();
-    const authUrl = buildKeycloakAuthUrl(pkce.verifier, pkce.challenge);
+async function commandLogin(args: ParsedArgs): Promise<Envelope> {
+  const command = "login";
+  const token = args.options["token"];
+  const browser = args.flags.has("browser");
 
-    output(
-      buildEnvelope("login", {
-        status: "success",
-        summary: "Browser OAuth login prepared. Open the authorization URL in a browser to continue.",
-        data: {
-          authUrl,
-          pkceChallenge: pkce.challenge,
-          pkceVerifier: pkce.verifier,
-          callbackPort: 5375,
-          authMethod: "browser_oauth",
-          envUpdated: false,
-          authenticated: false,
+  // --browser flows (PKCE preview, or honest unavailability) -------------
+  if (browser) {
+    if (args.dryRun) {
+      return loginBrowserDryRun(command);
+    }
+    // Real browser/Playwright callback flow is not implemented on this VM.
+    return errorEnvelope(
+      command,
+      "Browser-based login is not available in this environment.",
+      [
+        {
+          code: "BROWSER_LOGIN_UNAVAILABLE",
+          message:
+            "No native browser or Playwright callback flow is available to complete browser OAuth.",
+          remediation: `Create a token at ${TOKEN_PAGE} and run \`jolly login --token <value>\`.`,
         },
-        checks: [
-          { id: "login-pkce-generated", status: "pass" as CheckStatus, description: "PKCE challenge generated" },
-          { id: "login-auth-url", status: "pass" as CheckStatus, description: "Keycloak authorization URL constructed" },
-        ],
-        nextSteps: [
-          { description: "Open the authorization URL in a browser and complete the OAuth flow" },
-          { description: "After receiving the code, run jolly login --exchange-code <code> to complete authentication" },
-        ],
-      }),
+      ],
+      { data: { riskContext: loginRiskContext() } },
     );
-    return;
   }
 
-  // ── OAuth code exchange ─────────────────────────────────────────────
-  if (hasExchangeCode && exchangeCodeValue) {
-    const tokenExchangeBody = {
-      code: exchangeCodeValue,
-      code_verifier: "test-pkce-verifier",
-      client_id: "saleor-cli",
-      redirect_uri: "http://127.0.0.1:5375/callback",
-    };
-
-    // Simulate the Cloud API token exchange
-    const cloudTokenUrl = "https://api.saleor.cloud/platform/api/tokens";
-    const cloudTokenBody = { id_token: "oidc-id-token-mock" };
-    const verifyUrl = "https://id.saleor.online/verify";
-    const saleorCloudToken = "saleor-cloud-token-from-exchange";
-
-    writeEnvValues(cwd, {
-      "JOLLY_SALEOR_CLOUD_TOKEN": saleorCloudToken,
-      "JOLLY_SALEOR_ORGANIZATION": "Saleor Cloud user (authenticated)",
-    });
-
-    output(
-      buildEnvelope("login", {
-        status: "success",
-        summary: "OAuth code exchanged. Saleor Cloud token stored in .env.",
-        data: {
-          tokenExchangeBody,
-          cloudTokenUrl,
-          cloudTokenBody,
-          verifyUrl,
-          envUpdated: true,
-          authenticated: true,
-          tokenConfigured: true,
+  if (!token) {
+    return errorEnvelope(
+      command,
+      "No token provided and browser login is not available here.",
+      [
+        {
+          code: "NO_LOGIN_METHOD",
+          message:
+            "jolly login needs `--token <value>` in this environment (no browser/Playwright callback flow).",
+          remediation: `Create a token at ${TOKEN_PAGE} and run \`jolly login --token <value>\`.`,
         },
-        checks: [
-          { id: "login-code-exchanged", status: "pass" as CheckStatus, description: "OAuth code exchanged for Saleor Cloud token" },
-          { id: "login-token-verified", status: "pass" as CheckStatus, description: "Token verified via id.saleor.online/verify" },
-        ],
+      ],
+      {
         nextSteps: [
-          { description: "Verify authentication with jolly auth status" },
+          {
+            description: `Create a Saleor Cloud token at ${TOKEN_PAGE}, then run jolly login --token <value>.`,
+            command: "jolly login --token <value>",
+          },
         ],
-      }),
+        data: { riskContext: loginRiskContext() },
+      },
     );
-    return;
   }
 
-  // ── Dry-run ─────────────────────────────────────────────────────────
-  const rc = riskContext(
-    "login",
-    { type: "Saleor Cloud authentication", scope: "local .env" },
-    "medium",
-    ["credential handling"],
-    true,
-    ["Writes JOLLY_SALEOR_CLOUD_TOKEN to .env"],
-  );
-
-  if (FLAG_DRY_RUN) {
-    output(
-      buildEnvelope("login", {
-        status: "success",
-        summary: "Dry-run: would write Saleor Cloud token to .env",
-        data: {
-          dryRun: true,
-          riskContext: rc,
-          envUpdated: false,
-          authenticated: false,
+  // --token --dry-run: write nothing, show riskContext + nextSteps -------
+  if (args.dryRun) {
+    return envelope({
+      command,
+      status: "success",
+      summary: "Previewed token login; nothing was written.",
+      data: { riskContext: loginRiskContext(), dryRun: true },
+      nextSteps: [
+        {
+          description: "Run jolly login --token <value> to verify and store the token.",
+          command: "jolly login --token <value>",
         },
-        checks: [
-          { id: "login-dry-run", status: "pass" as CheckStatus, description: "Login preview — no changes made" },
-        ],
-        nextSteps: [
-          { description: "Run jolly login --token <token> (without --dry-run) to authenticate" },
-        ],
-      }),
-    );
-    return;
+      ],
+    });
   }
 
-  // ── Token login (headless) ──────────────────────────────────────────
-  if (!tokenValue) {
-    errorExit(
-      buildEnvelope("login", {
-        status: "error",
-        summary: "No token provided. Usage: jolly login --token <token> or jolly login --browser for browser OAuth",
-        data: {},
-        errors: [{ code: "MISSING_TOKEN", message: "A Saleor Cloud token is required. Provide it via --token <value>, or use --browser for browser OAuth." }],
-      }),
-    );
+  // Real --token login: verify via authenticated GET of organizations/ ----
+  let orgs: CloudOrganization[] | undefined;
+  let verificationFailure: unknown;
+  try {
+    orgs = await listOrganizations(token);
+  } catch (err) {
+    verificationFailure = err;
   }
 
-  // Validate token — for @logic testing, invalid/expired tokens are rejected
-  const verifyUrl = "https://id.saleor.online/configure";
-  const isInvalid = tokenValue!.startsWith("invalid-") || tokenValue!.startsWith("expired-");
-
-  const loginRc = riskContext(
-    "login",
-    { type: "Saleor Cloud authentication", scope: "local .env" },
-    "medium",
-    ["credential handling"],
-    true,
-    ["Writes JOLLY_SALEOR_CLOUD_TOKEN to .env"],
-  );
-
-  if (isInvalid) {
-    output(
-      buildEnvelope("login", {
-        status: "error",
-        summary: "Invalid token: the provided Saleor Cloud token could not be verified.",
-        data: {
-          verifyUrl,
-          valid: false,
+  if (
+    verificationFailure instanceof CloudApiError &&
+    (verificationFailure.httpStatus === 401 || verificationFailure.httpStatus === 403)
+  ) {
+    // Invalid token: write nothing, error honestly.
+    return errorEnvelope(
+      command,
+      "The token was rejected by the Cloud API. Nothing was written.",
+      [
+        {
+          code: "INVALID_TOKEN",
+          message: "Saleor Cloud rejected the token (HTTP 401/403). It was not stored.",
+          remediation: `Create a new token at ${TOKEN_PAGE} and try again.`,
         },
+      ],
+      {
         checks: [
-          { id: "login-token-validation", status: "fail" as CheckStatus, description: "Token verification failed" },
+          {
+            id: "cloud-token-verification",
+            status: "fail",
+            description: "Token rejected by the Cloud API.",
+          },
         ],
-        errors: [{
-          code: "INVALID_TOKEN",
-          message: "The provided token is invalid or expired. Create a new token at https://cloud.saleor.io/tokens",
-          remediation: "Create a new token at https://cloud.saleor.io/tokens",
-        }],
+        data: { riskContext: loginRiskContext() },
         nextSteps: [
-          { description: "Create a new token at https://cloud.saleor.io/tokens and run jolly login --token <token>" },
+          { description: `Create a new token at ${TOKEN_PAGE}.`, command: `open ${TOKEN_PAGE}` },
         ],
-      }),
+      },
     );
-    return;
   }
 
-  writeEnvValues(cwd, {
-    "JOLLY_SALEOR_CLOUD_TOKEN": tokenValue!,
-    "JOLLY_SALEOR_ORGANIZATION": "Saleor Cloud user (authenticated)",
-  });
-
-  output(
-    buildEnvelope("login", {
-      status: "success",
-      summary: "Logged in to Saleor Cloud. Token written to .env.",
+  if (verificationFailure) {
+    // Unreachable / 5xx / timeout: store token, warn "stored, not verified".
+    writeEnvValues(projectDir(), { JOLLY_SALEOR_CLOUD_TOKEN: token });
+    return envelope({
+      command,
+      status: "warning",
+      summary: "Token stored, not verified — the Cloud API was unreachable.",
       data: {
-        verifyUrl,
-        valid: true,
-        envUpdated: true,
-        authenticated: true,
-        tokenConfigured: true,
-        accountContext: "Saleor Cloud user (authenticated)",
-        riskContext: loginRc,
+        cloudTokenStored: true,
+        verified: false,
+        verification: "stored, not verified",
+        riskContext: loginRiskContext(),
       },
       checks: [
-        { id: "login-token-written", status: "pass" as CheckStatus, description: "JOLLY_SALEOR_CLOUD_TOKEN written to .env" },
-        { id: "login-gitignore", status: "pass" as CheckStatus, description: ".env is git-ignored" },
-        { id: "login-token-validation", status: "pass" as CheckStatus, description: "Token verified at id.saleor.online/configure" },
+        {
+          id: "cloud-token-verification",
+          status: "unknown",
+          description: "stored, not verified — the Cloud API was unreachable.",
+        },
       ],
       nextSteps: [
-        { description: "Verify authentication with jolly auth status" },
+        {
+          description: "Re-run jolly login when the Cloud API is reachable to verify the token.",
+          command: "jolly login --token <value>",
+        },
       ],
-    }),
-  );
-}
-
-// ── Command: logout ──────────────────────────────────────────────────────
-
-function cmdLogout(): void {
-  const existing = loadEnvValues(cwd);
-  const jollyKeys = Object.keys(existing).filter(
-    (k) => k.startsWith("JOLLY_SALEOR_"),
-  );
-
-  if (jollyKeys.length === 0) {
-    output(
-      buildEnvelope("logout", {
-        status: "success",
-        summary: "No Jolly-managed Saleor Cloud auth values found in .env. Nothing to remove.",
-        data: { removed: [], authenticated: false },
-      }),
-    );
-    return;
+    });
   }
 
-  // Preserve non-JOLLY_SALEOR keys
-  const preserved: Record<string, string> = {};
-  for (const [key, value] of Object.entries(existing)) {
-    if (!key.startsWith("JOLLY_SALEOR_")) {
-      preserved[key] = value;
-    }
-  }
+  // Verified: store token + the real organization name.
+  const orgName = resolveOrgName(orgs ?? []);
+  const values: Record<string, string> = { JOLLY_SALEOR_CLOUD_TOKEN: token };
+  if (orgName) values["JOLLY_SALEOR_ORGANIZATION"] = orgName;
+  writeEnvValues(projectDir(), values);
 
-  // Rewrite .env without the removed keys
-  const envPath = join(cwd, ".env");
-  const lines = Object.entries(preserved).map(([k, v]) => `${k}=${v}`);
-  writeFileSync(envPath, lines.join("\n") + "\n");
+  return envelope({
+    command,
+    status: "success",
+    summary: orgName
+      ? `Token verified and stored. Authenticated as "${orgName}".`
+      : "Token verified and stored.",
+    data: {
+      cloudTokenStored: true,
+      verified: true,
+      accountContext: orgName ?? "unknown",
+      riskContext: loginRiskContext(),
+    },
+    checks: [
+      {
+        id: "cloud-token-verification",
+        status: "pass",
+        description: "Token verified against the Cloud API organizations endpoint.",
+      },
+    ],
+    nextSteps: [
+      {
+        description: "Run jolly create store to provision a Saleor Cloud environment.",
+        command: "jolly create store --create-environment",
+      },
+    ],
+  });
+}
 
-  output(
-    buildEnvelope("logout", {
-      status: "success",
-      summary: `Logged out. Removed ${jollyKeys.length} Jolly-managed auth value(s) from .env.`,
-      data: { removed: jollyKeys, authenticated: false, envUpdated: true },
-      checks: [
-        { id: "logout-removed", status: "pass" as CheckStatus, description: `Removed: ${jollyKeys.join(", ")}` },
-      ],
-    }),
-  );
+function resolveOrgName(orgs: CloudOrganization[]): string | undefined {
+  const first = orgs[0];
+  if (!first) return undefined;
+  const name = first.name ?? first.slug;
+  return typeof name === "string" && name.length > 0 ? name : undefined;
 }
 
-// ── Command: auth status ─────────────────────────────────────────────────
+function base64url(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
 
-function cmdAuthStatus(): void {
-  const existing = loadEnvValues(cwd);
-  const hasCloudToken = "JOLLY_SALEOR_CLOUD_TOKEN" in existing;
-  const hasAppToken = "JOLLY_SALEOR_APP_TOKEN" in existing;
-  const organizationName = existing["JOLLY_SALEOR_ORGANIZATION"] ?? null;
-  const accountContext = organizationName ?? "unknown";
+function loginBrowserDryRun(command: string): Envelope {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash("sha256").update(verifier).digest());
+  const state = base64url(randomBytes(16));
+  const redirectUri = "http://127.0.0.1:5375/callback";
+  const authBase = "https://auth.saleor.io/realms/saleor-cloud/protocol/openid-connect/auth";
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: "saleor-cli",
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+    state,
+    redirect_uri: redirectUri,
+    scope: "email openid profile",
+  });
+  const authorizationUrl = `${authBase}?${params.toString()}`;
+
+  // The code-exchange preview: the two real POSTs the localhost callback would
+  // make, described without sending them or claiming any of them succeeded
+  // (feature 018, "previews the OAuth code exchange requests"). The token
+  // endpoint is Keycloak (auth.saleor.io); the resulting OIDC id_token is then
+  // exchanged for a Cloud API token at /platform/api/tokens.
+  const tokenEndpoint =
+    "https://auth.saleor.io/realms/saleor-cloud/protocol/openid-connect/token";
+  const tokensEndpoint = `${cloudApiBase()}/tokens`;
+  const exchangePreview = {
+    tokenExchange: {
+      method: "POST",
+      url: tokenEndpoint,
+      body: {
+        grant_type: "authorization_code",
+        code: "<authorization code from the localhost callback>",
+        code_verifier: "<the PKCE code_verifier>",
+        client_id: "saleor-cli",
+        redirect_uri: redirectUri,
+      },
+    },
+    cloudTokenExchange: {
+      method: "POST",
+      url: tokensEndpoint,
+      requestPath: "/platform/api/tokens",
+      body: { id_token: "<the OIDC id_token returned by Keycloak>" },
+    },
+  };
 
-  output(
-    buildEnvelope("auth status", {
-      status: "success",
-      summary: hasCloudToken
-        ? "Saleor Cloud authentication is configured."
-        : "Saleor Cloud authentication is not configured.",
-      data: {
-        authenticated: hasCloudToken,
-        hasCloudToken,
-        hasAppToken,
-        accountContext,
+  return envelope({
+    command,
+    status: "success",
+    summary:
+      "Prepared the browser OAuth authorization URL and code-exchange preview (PKCE). Nothing was written.",
+    data: {
+      dryRun: true,
+      authorizationUrl,
+      pkce: { codeChallengeMethod: "S256", codeChallenge: challenge },
+      state,
+      redirectUri,
+      scope: "email openid profile",
+      clientId: "saleor-cli",
+      responseType: "code",
+      exchangePreview,
+      riskContext: loginRiskContext(),
+    },
+    nextSteps: [
+      {
+        description:
+          "Open the authorization URL in a browser to complete OAuth, or use jolly login --token <value>.",
+        command: "jolly login --browser",
       },
-      checks: [
-        { id: "auth-cloud-token", status: (hasCloudToken ? "pass" : "fail") as CheckStatus, description: "JOLLY_SALEOR_CLOUD_TOKEN" },
-        { id: "auth-app-token", status: (hasAppToken ? "pass" : "skipped") as CheckStatus, description: "JOLLY_SALEOR_APP_TOKEN (optional)" },
-      ],
-      nextSteps: hasCloudToken
-        ? [{ description: "Authentication is configured. Run jolly start to proceed." }]
-        : [{ description: "Run jolly login --token <token> to authenticate with Saleor Cloud" }],
-    }),
-  );
+    ],
+  });
 }
 
-// ── Command: create environment (--create-environment) ───────────────────
-
-async function cmdCreateEnvironment(): Promise<void> {
-  const existing = loadEnvValues(cwd);
-  const cloudToken =
-    process.env["JOLLY_SALEOR_CLOUD_TOKEN"] ??
-    existing["JOLLY_SALEOR_CLOUD_TOKEN"];
-
-  if (!cloudToken) {
-    errorExit(
-      buildEnvelope("create store", {
-        status: "error",
-        summary: "Saleor Cloud token is required. Set JOLLY_SALEOR_CLOUD_TOKEN or run jolly login first.",
-        data: {},
-        errors: [{
-          code: "MISSING_CLOUD_TOKEN",
-          message: "No Saleor Cloud token found. Provide it via JOLLY_SALEOR_CLOUD_TOKEN environment variable or run jolly login --token <token>.",
-        }],
-      }),
-    );
-    return;
+// ─── logout (feature 018) ─────────────────────────────────────────────────
+
+const MANAGED_AUTH_VARS = [
+  "JOLLY_SALEOR_CLOUD_TOKEN",
+  "JOLLY_SALEOR_APP_TOKEN",
+  "JOLLY_SALEOR_ORGANIZATION",
+];
+
+function commandLogout(_args: ParsedArgs): Envelope {
+  const command = "logout";
+  const before = loadEnvValues(projectDir());
+  const path = envFilePath();
+  const removed: string[] = [];
+
+  if (existsSync(path)) {
+    const lineRe = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=/;
+    const kept = readFileSync(path, "utf8")
+      .split("\n")
+      .filter((line) => {
+        const m = lineRe.exec(line);
+        if (m && MANAGED_AUTH_VARS.includes(m[1])) {
+          removed.push(m[1]);
+          return false;
+        }
+        return true;
+      });
+    // Rewrite .env without the managed auth vars, preserving everything else
+    // (comments, blank lines, third-party credentials) verbatim.
+    let text = kept.join("\n").replace(/\n+$/, "");
+    text = text.length > 0 ? text + "\n" : "";
+    writeFileSync(path, text);
   }
 
-  // ── Flags (feature 012 Rule: environment creation against in-use
-  //    organizations) ─────────────────────────────────────────────────────
-  const flagValue = (flag: string): string | undefined => {
-    const idx = args.indexOf(flag);
-    return idx >= 0 ? args[idx + 1] : undefined;
-  };
-  const nameOverride = flagValue("--name");
-  const domainLabelOverride = flagValue("--domain-label");
-  const organizationOverride = flagValue("--organization");
-  const region = flagValue("--region") ?? "us-east-1";
-  // Test-injection flag: the organization list the token would see (the
-  // multi-org premise cannot be produced harmlessly in the sandbox).
-  const mockOrganizations = flagValue("--mock-organizations")
-    ?.split(",")
-    .map((s) => s.trim())
-    .filter((s) => s.length > 0);
-
-  // Environment name and domain label: overrides win; generated otherwise.
-  const suffix = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 6)}`;
-  const environmentName = nameOverride ?? `jolly-env-${suffix}`;
-  const domainLabel = domainLabelOverride ?? `jolly-${suffix}`;
-
-  const rc = riskContext(
-    "create store",
-    { type: "Saleor Cloud environment", organization: organizationOverride ?? "auto-discovered", name: environmentName },
-    "medium",
-    ["billing", "credential handling"],
-    true,
-    [
-      "Creates a Saleor Cloud environment (consumes a sandbox slot)",
-      "Writes NEXT_PUBLIC_SALEOR_API_URL and JOLLY_SALEOR_APP_TOKEN to .env",
+  return envelope({
+    command,
+    status: "success",
+    summary:
+      removed.length > 0
+        ? `Removed Jolly-managed Saleor auth values from .env (${[...new Set(removed)].join(", ")}).`
+        : "No Jolly-managed Saleor auth values were present in .env.",
+    data: {
+      removed: [...new Set(removed)],
+      preservedOthers: true,
+    },
+    checks: [
+      {
+        id: "auth-cleared",
+        status: "pass",
+        description: "Jolly-managed Saleor auth values are no longer in .env.",
+      },
     ],
-  );
+    nextSteps: [
+      {
+        description: "Run jolly login to authenticate again when needed.",
+        command: "jolly login --token <value>",
+      },
+    ],
+  });
+}
 
-  // ── Organization selection ──────────────────────────────────────────
-  // --organization wins without querying. Otherwise the token's
-  // organization list decides: exactly one → use it; several → select the
-  // first but warn with the available slugs so the agent can re-run with
-  // --organization <slug> (feature 012 Rule).
-  let status: Status = "success";
-  const advisorySteps: Array<Record<string, unknown>> = [];
-  const resolveOrganization = async (): Promise<{
-    slug: string;
-    available?: string[];
-  }> => {
-    if (organizationOverride) return { slug: organizationOverride };
-    const slugs =
-      mockOrganizations ??
-      (await listOrganizations(cloudToken)).map((o) => String(o.slug));
-    if (slugs.length === 0) {
-      throw new CloudApiError(
-        "No Saleor Cloud organizations are accessible with this token.",
-        "NO_ORGANIZATION",
-      );
-    }
-    return { slug: slugs[0], available: slugs.length > 1 ? slugs : undefined };
+// ─── auth status (feature 018) ────────────────────────────────────────────
+
+function commandAuthStatus(_args: ParsedArgs): Envelope {
+  const command = "auth status";
+  const values = loadEnvValues(projectDir());
+  const hasCloudToken = Boolean(values["JOLLY_SALEOR_CLOUD_TOKEN"]);
+  const hasAppToken = Boolean(values["JOLLY_SALEOR_APP_TOKEN"]);
+  const org = values["JOLLY_SALEOR_ORGANIZATION"];
+  const accountContext = org && org.length > 0 ? org : "unknown";
+
+  const checks: Check[] = [
+    {
+      id: "cloud-token-configured",
+      status: hasCloudToken ? "pass" : "warning",
+      description: hasCloudToken
+        ? "JOLLY_SALEOR_CLOUD_TOKEN is configured in .env."
+        : "JOLLY_SALEOR_CLOUD_TOKEN is not configured.",
+    },
+    {
+      id: "app-token-configured",
+      status: hasAppToken ? "pass" : "skipped",
+      description: hasAppToken
+        ? "JOLLY_SALEOR_APP_TOKEN is configured in .env."
+        : "JOLLY_SALEOR_APP_TOKEN is not configured.",
+    },
+  ];
+
+  return envelope({
+    command,
+    status: "success",
+    summary: hasCloudToken
+      ? `Saleor Cloud authentication is configured (account context: ${accountContext}).`
+      : "Saleor Cloud authentication is not configured.",
+    data: {
+      hasCloudToken,
+      hasAppToken,
+      accountContext,
+    },
+    checks,
+    nextSteps: hasCloudToken
+      ? []
+      : [
+          {
+            description: "Run jolly login to configure Saleor Cloud authentication.",
+            command: "jolly login --token <value>",
+          },
+        ],
+  });
+}
+
+// ─── create store (features 012/024) ──────────────────────────────────────
+
+function createStoreRiskContext(target: unknown, dryRunAvailable = true): RiskContext {
+  return {
+    action: "create store",
+    target,
+    riskLevel: "medium",
+    categories: ["billing", "production configuration changes"],
+    reversible: false,
+    sideEffects: [
+      "Creates a Saleor Cloud project and/or environment",
+      "Writes NEXT_PUBLIC_SALEOR_API_URL and JOLLY_SALEOR_APP_TOKEN to .env",
+    ],
+    dryRunAvailable,
   };
+}
 
-  // ── Dry-run: prepare the creation without any Cloud API write ───────
-  // Emits the prepared POST (requestUrl + requestBody); nothing is created
-  // and .env is not written. With --organization (or the mock-injected
-  // organization list) no Cloud API call is made at all, so this works
-  // with a dummy token.
-  if (FLAG_DRY_RUN) {
-    const dryData: Record<string, unknown> = {
-      dryRun: true,
-      riskContext: rc,
-      envUpdated: false,
-    };
-    let organization: { slug: string; available?: string[] };
-    try {
-      organization = await resolveOrganization();
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
-      errorExit(
-        buildEnvelope("create store", {
-          status: "error",
-          summary: `Could not resolve a Saleor Cloud organization: ${message}`,
-          data: dryData,
-          errors: [{
-            code: error instanceof CloudApiError ? error.code : "CLOUD_API_ERROR",
-            message,
-          }],
-        }),
+async function commandCreateStore(args: ParsedArgs): Promise<Envelope> {
+  const command = "create store";
+  const url = args.options["url"];
+
+  // Mode 1: write a pasted Saleor URL to .env (feature 012). -------------
+  if (url && !args.flags.has("create-environment")) {
+    const normalized = normalizeSaleorUrl(url);
+    if (!normalized.endpoint) {
+      return errorEnvelope(
+        command,
+        "The provided URL could not be normalized to a Saleor GraphQL endpoint.",
+        [
+          {
+            code: "INVALID_SALEOR_URL",
+            message: normalized.clarification ?? "Unrecognized Saleor URL.",
+            remediation: "Paste a Saleor Dashboard, GraphQL, or root Saleor Cloud URL.",
+          },
+        ],
+        { data: { riskContext: createStoreRiskContext(url) } },
       );
-      return;
     }
-    const organizationSlug = organization.slug;
-    dryData.organizationSlug = organizationSlug;
-    dryData.environmentName = environmentName;
-    dryData.requestUrl = `${CLOUD_API_BASE}/organizations/${organizationSlug}/environments/`;
-    dryData.requestBody = {
-      name: environmentName,
-      project: "jolly-project",
-      domain_label: domainLabel,
-      database_population: "sample",
-      service: "saleor",
-      region,
-    };
-    dryData.domainUrl = `https://${domainLabel}.saleor.cloud/graphql/`;
-    let summary = "Dry-run: prepared Saleor Cloud environment creation. Nothing was created and .env was not written.";
-    if (organization.available) {
-      status = "warning";
-      dryData.organizations = organization.available;
-      summary = `Dry-run: the Cloud token can access multiple organizations (${organization.available.join(", ")}); selected "${organizationSlug}". Re-run with --organization <slug> if this is not the intended organization. Nothing was created.`;
-      advisorySteps.push({
-        description: `If "${organizationSlug}" is not the intended organization, re-run with --organization <slug> (available: ${organization.available.join(", ")})`,
+
+    if (args.dryRun) {
+      return envelope({
+        command,
+        status: "success",
+        summary: "Previewed storing the Saleor endpoint; nothing was written.",
+        data: {
+          dryRun: true,
+          normalizedUrl: normalized.endpoint,
+          riskContext: createStoreRiskContext(normalized.endpoint),
+        },
+        nextSteps: [
+          {
+            description: "Run the command without --dry-run to write the endpoint to .env.",
+            command: `jolly create store --url ${normalized.endpoint}`,
+          },
+        ],
       });
     }
-    output(
-      buildEnvelope("create store", {
-        status,
-        summary,
-        data: dryData,
+
+    // Collision guard (feature 022): if .env already carries a DIFFERENT
+    // endpoint Jolly is being asked to overwrite, pause and ask rather than
+    // silently replacing state Jolly did not create. The agent decides via
+    // the feature 021 riskContext; --yes is its explicit go-ahead.
+    const existingEndpoint = loadEnvValues(projectDir())["NEXT_PUBLIC_SALEOR_API_URL"];
+    if (
+      existingEndpoint &&
+      existingEndpoint !== normalized.endpoint &&
+      !args.flags.has("yes")
+    ) {
+      return envelope({
+        command,
+        status: "warning",
+        summary:
+          "A different NEXT_PUBLIC_SALEOR_API_URL already exists in .env; " +
+          "Jolly paused instead of overwriting it. Re-run with --yes to replace it.",
+        data: {
+          collision: true,
+          existingEndpoint,
+          requestedEndpoint: normalized.endpoint,
+          riskContext: {
+            action: "overwrite Saleor endpoint",
+            target: "NEXT_PUBLIC_SALEOR_API_URL in .env",
+            riskLevel: "medium",
+            categories: ["destructive operations", "production configuration changes"],
+            reversible: false,
+            sideEffects: [
+              `Replaces the existing endpoint "${existingEndpoint}" with "${normalized.endpoint}"`,
+            ],
+            dryRunAvailable: true,
+          },
+        },
         checks: [
-          { id: "create-environment-dry-run", status: "pass" as CheckStatus, description: "Preview only — no Cloud API write, .env untouched" },
+          {
+            id: "saleor-endpoint-collision",
+            status: "warning",
+            description:
+              "An existing NEXT_PUBLIC_SALEOR_API_URL would be overwritten; not replaced without --yes.",
+          },
         ],
         nextSteps: [
-          ...advisorySteps,
-          { description: "Run jolly create store --create-environment (without --dry-run) to create the environment" },
+          {
+            description:
+              "Re-run with --yes to overwrite the existing endpoint (the agent decides).",
+            command: `jolly create store --url ${normalized.endpoint} --yes`,
+          },
         ],
-      }),
-    );
-    return;
-  }
-
-  // Built up progressively so partial results (organizationSlug,
-  // environmentKey, ...) survive into an error envelope — the test harness
-  // uses them to register teardown deletion of anything that was created.
-  const data: Record<string, unknown> = { riskContext: rc };
-  const checks: Check[] = [];
-
-  try {
-    // 1. Discover the organization from the Cloud API (or honor the
-    //    --organization override).
-    const organization = await resolveOrganization();
-    const organizationSlug = organization.slug;
-    data.organizationSlug = organizationSlug;
-    if (organization.available) {
-      status = "warning";
-      data.organizations = organization.available;
-      advisorySteps.push({
-        description: `If "${organizationSlug}" is not the intended organization, re-run with --organization <slug> (available: ${organization.available.join(", ")})`,
       });
-      checks.push({ id: "create-environment-org-discovered", status: "warning" as CheckStatus, description: `Multiple organizations accessible (${organization.available.join(", ")}); selected "${organizationSlug}". Re-run with --organization <slug> to override.` });
-    } else {
-      checks.push({ id: "create-environment-org-discovered", status: "pass" as CheckStatus, description: `Organization: ${organizationSlug}` });
     }
 
-    // 2. Create-or-reuse the project: reuse an existing project when one
-    //    exists, otherwise create one with plan "dev" (feature 012 Rule).
-    const projects = await listProjects(cloudToken, organizationSlug);
-    let projectSlug: string;
-    let projectName: string;
-    if (projects.length > 0) {
-      const project = projects[0];
-      projectSlug = String(project.slug ?? project.name);
-      projectName = String(project.name ?? projectSlug);
-      data.projectCreated = false;
-      data.projectReused = true;
-      checks.push({ id: "create-environment-project", status: "pass" as CheckStatus, description: `Reused existing project "${projectName}"` });
-    } else {
-      projectName = `jolly-project-${Date.now().toString(36)}`;
-      const created = await createProject(cloudToken, organizationSlug, {
-        name: projectName,
-        plan: "dev",
-        region,
-      });
-      projectSlug = String(created.slug ?? projectName);
-      data.projectCreated = true;
-      data.projectReused = false;
-      data.projectPlan = "dev";
-      checks.push({ id: "create-environment-project", status: "pass" as CheckStatus, description: `Created project "${projectName}" (plan dev)` });
-    }
-    data.projectName = projectName;
-
-    // 3. Resolve the concrete service identifier for the environment body.
-    const services = await listProjectServices(cloudToken, organizationSlug, projectSlug);
-    const service = pickService(services, region);
-
-    // 4. Create the environment (name/domain label honor the --name and
-    //    --domain-label overrides resolved above).
-    const environment = await createEnvironment(cloudToken, organizationSlug, {
-      name: environmentName,
-      project: projectSlug,
-      domain_label: domainLabel,
-      database_population: "sample",
-      service,
-      region,
+    writeEnvValues(projectDir(), { NEXT_PUBLIC_SALEOR_API_URL: normalized.endpoint });
+    return envelope({
+      command,
+      status: "success",
+      summary: "Stored the Saleor GraphQL endpoint as NEXT_PUBLIC_SALEOR_API_URL.",
+      data: {
+        stored: true,
+        envVar: "NEXT_PUBLIC_SALEOR_API_URL",
+        riskContext: createStoreRiskContext(normalized.endpoint),
+      },
+      checks: [
+        {
+          id: "saleor-endpoint-stored",
+          status: "pass",
+          description: "NEXT_PUBLIC_SALEOR_API_URL written to .env.",
+        },
+      ],
+      nextSteps: [
+        {
+          description: "Run jolly create app-token to acquire a Saleor app token.",
+          command: "jolly create app-token",
+        },
+      ],
     });
-    data.environmentName = environmentName;
-    if (environment.key) data.environmentKey = String(environment.key);
-    const taskId = String(environment.task_id ?? "");
-    data.taskId = taskId;
-    data.taskPollUrl = taskStatusUrl(taskId);
-    checks.push({ id: "create-environment-created", status: "pass" as CheckStatus, description: `Environment "${environmentName}" creation requested` });
-
-    // 5. Poll the provisioning task until SUCCEEDED.
-    const task = await pollTaskStatus(taskId);
-    data.taskStatus = "SUCCEEDED";
-    checks.push({ id: "create-environment-task", status: "pass" as CheckStatus, description: "Provisioning task SUCCEEDED" });
-
-    // Resolve the environment key if creation did not return one — the
-    // agent (and the test teardown) needs it to manage the environment.
-    if (!data.environmentKey) {
-      const environments = await listEnvironments(cloudToken, organizationSlug);
-      const match = environments.find(
-        (e) => e.domain_label === domainLabel || e.name === environmentName,
-      );
-      if (match?.key) data.environmentKey = String(match.key);
-    }
+  }
 
-    // 6. Extract the resulting domain from the task result and write the
-    //    GraphQL URL to .env.
-    const detail = data.environmentKey
-      ? await getEnvironment(cloudToken, organizationSlug, String(data.environmentKey))
-      : undefined;
-    const domainUrl = extractDomainUrl(task, detail ?? environment, domainLabel);
-    data.domainUrl = domainUrl;
-    writeEnvValues(cwd, { "NEXT_PUBLIC_SALEOR_API_URL": domainUrl });
-    data.envUpdated = true;
-    checks.push({ id: "create-environment-url-written", status: "pass" as CheckStatus, description: "NEXT_PUBLIC_SALEOR_API_URL written to .env" });
-
-    // 7. Create an app token via the Saleor GraphQL API and write it to .env.
-    const appToken = await acquireAppToken(domainUrl, cloudToken, "jolly-setup");
-    writeEnvValues(cwd, { "JOLLY_SALEOR_APP_TOKEN": appToken });
-    data.appTokenCreated = true;
-    checks.push({ id: "create-environment-app-token", status: "pass" as CheckStatus, description: "App token created and written to .env as JOLLY_SALEOR_APP_TOKEN" });
-
-    output(
-      buildEnvelope("create store", {
-        status,
-        summary:
-          status === "warning"
-            ? `Saleor Cloud environment created and connected in organization "${organizationSlug}" (multiple organizations were accessible — re-run with --organization <slug> if this was not the intended one).`
-            : "Saleor Cloud environment created and connected.",
-        data,
-        checks,
+  // Mode 2: provision a Saleor Cloud environment via the Cloud API. ------
+  const token = process.env["JOLLY_SALEOR_CLOUD_TOKEN"];
+  const region = args.options["region"] ?? "us-east-1";
+  const orgOverride = args.options["organization"];
+  const name = args.options["name"];
+  const domainLabel = args.options["domain-label"];
+
+  if (!token) {
+    return errorEnvelope(
+      command,
+      "No Saleor Cloud token is configured; cannot provision a store.",
+      [
+        {
+          code: "MISSING_CLOUD_TOKEN",
+          message: "JOLLY_SALEOR_CLOUD_TOKEN is required to create a Saleor Cloud store.",
+          remediation: "Run `jolly login --token <value>` first.",
+        },
+      ],
+      {
+        data: {
+          riskContext: createStoreRiskContext(`${cloudApiBase()} (organization unresolved)`),
+        },
         nextSteps: [
-          ...advisorySteps,
-          { description: "Run jolly init to install Saleor agent skills" },
-          { description: "Run jolly create storefront to clone Saleor Paper" },
+          {
+            description: "Run jolly login to acquire a Saleor Cloud token.",
+            command: "jolly login --token <value>",
+          },
         ],
-      }),
+      },
     );
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    const code = error instanceof CloudApiError ? error.code : "CREATE_ENVIRONMENT_FAILED";
-
-    if (code === "ENVIRONMENT_LIMIT_REACHED") {
-      errorExit(
-        buildEnvelope("create store", {
-          status: "error",
-          summary: "Environment creation rejected: the organization's sandbox environment limit is reached.",
-          data,
-          checks,
-          errors: [{
-            code: "ENVIRONMENT_LIMIT_REACHED",
-            message,
-            remediation: "Delete an unused environment or upgrade the organization's plan, then re-run jolly create store --create-environment.",
-          }],
-          nextSteps: [
-            { description: "Delete an unused environment in the Saleor Cloud console, or upgrade the plan, then re-run jolly create store --create-environment" },
-          ],
-        }),
-      );
+  }
+
+  // Resolve the organization. --mock-organizations injects a deterministic
+  // org list for the @logic multi-org warning scenario (no network).
+  let orgs: CloudOrganization[];
+  const mock = args.flags.has("mock-organizations")
+    ? ""
+    : (args.options["mock-organizations"] ?? undefined);
+  if (mock !== undefined) {
+    orgs = (mock.length > 0 ? mock.split(",") : ["org-one", "org-two"]).map((slug) => ({
+      slug: slug.trim(),
+    }));
+  } else {
+    try {
+      orgs = await listOrganizations(token);
+    } catch (err) {
+      return cloudErrorEnvelope(command, err, createStoreRiskContext(cloudApiBase()));
     }
+  }
 
-    errorExit(
-      buildEnvelope("create store", {
-        status: "error",
-        summary: `Failed to create Saleor Cloud environment: ${message}`,
-        data,
-        checks,
-        errors: [{ code, message }],
-      }),
+  let selectedOrg: string;
+  let multiOrgWarning = false;
+  if (orgOverride) {
+    selectedOrg = orgOverride;
+  } else if (orgs.length === 0) {
+    return errorEnvelope(
+      command,
+      "The Cloud token has access to no organizations.",
+      [
+        {
+          code: "NO_ORGANIZATIONS",
+          message: "No organizations are accessible with this Cloud token.",
+          remediation: "Confirm the token's permissions at https://cloud.saleor.io/tokens.",
+        },
+      ],
+      { data: { riskContext: createStoreRiskContext(cloudApiBase()) } },
     );
+  } else if (orgs.length === 1) {
+    selectedOrg = orgs[0].slug;
+  } else {
+    selectedOrg = orgs[0].slug;
+    multiOrgWarning = true;
   }
-}
 
-// ── Endpoint validation (--validate) ─────────────────────────────────────
-// Live introspection-style GraphQL validation: POST a minimal query and
-// require a JSON GraphQL response. Network failures (DNS, refused
-// connections) are caught and reported, never thrown (feature 012).
+  const resolvedTarget = `${cloudApiBase()}/organizations/${selectedOrg}/environments/`;
+  const effectiveName = name ?? "jolly-store";
+  const effectiveDomainLabel = domainLabel ?? effectiveName;
 
-interface EndpointValidation {
-  ok: boolean;
-  code: string;
-  message: string;
-}
-
-async function validateGraphqlEndpoint(url: string): Promise<EndpointValidation> {
-  let response: Response;
-  try {
-    response = await fetch(url, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ query: "{ __typename }" }),
-      signal: AbortSignal.timeout(30_000),
-    });
-  } catch (error: unknown) {
-    const message = error instanceof Error ? error.message : String(error);
-    return {
-      ok: false,
-      code: "ENDPOINT_UNREACHABLE",
-      message: `The Saleor GraphQL endpoint could not be reached (${message}). Check the URL for typos and confirm the instance is online, then re-run with --validate.`,
-    };
-  }
-  if (!response.ok) {
-    return {
-      ok: false,
-      code: "ENDPOINT_NOT_GRAPHQL",
-      message: `The endpoint responded with HTTP ${response.status} instead of a GraphQL result. Use the Saleor GraphQL endpoint (https://<store>.saleor.cloud/graphql/), then re-run with --validate.`,
-    };
-  }
-  let body: unknown;
-  try {
-    body = await response.json();
-  } catch {
-    return {
-      ok: false,
-      code: "ENDPOINT_NOT_GRAPHQL",
-      message: "The endpoint returned a non-JSON response to a GraphQL query, so it does not look like a GraphQL endpoint. Use the Saleor GraphQL endpoint (https://<store>.saleor.cloud/graphql/), then re-run with --validate.",
+  // --dry-run: show the real resolved request, write nothing. -----------
+  if (args.dryRun) {
+    const requestBody = {
+      name: effectiveName,
+      project: effectiveName,
+      domain_label: effectiveDomainLabel,
+      database_population: "sample",
+      service: "saleor",
+      region,
     };
+    const env = envelope({
+      command,
+      status: multiOrgWarning ? "warning" : "success",
+      summary: multiOrgWarning
+        ? `Previewed environment creation in "${selectedOrg}" (token has multiple organizations).`
+        : `Previewed environment creation in organization "${selectedOrg}".`,
+      data: {
+        dryRun: true,
+        method: "POST",
+        requestPath: `/platform/api/organizations/${selectedOrg}/environments/`,
+        requestUrl: resolvedTarget,
+        organization: selectedOrg,
+        region,
+        databaseTemplate: "sample",
+        requestBody,
+        riskContext: createStoreRiskContext(resolvedTarget),
+      },
+      nextSteps: [
+        {
+          description: "Run the command without --dry-run to create the environment.",
+          command: "jolly create store --create-environment",
+        },
+      ],
+    });
+    if (multiOrgWarning) {
+      env.data["availableOrganizations"] = orgs.map((o) => o.slug);
+      env.data["selectedOrganization"] = selectedOrg;
+    }
+    return env;
   }
-  const result = body as Record<string, unknown> | null;
-  const data = result?.data as Record<string, unknown> | undefined;
-  if (typeof data?.__typename !== "string" && !Array.isArray(result?.errors)) {
-    return {
-      ok: false,
-      code: "ENDPOINT_NOT_GRAPHQL",
-      message: "The endpoint returned JSON without a GraphQL data/errors shape. Use the Saleor GraphQL endpoint (https://<store>.saleor.cloud/graphql/), then re-run with --validate.",
-    };
+
+  // Multi-org without --organization (non-dry-run): warn before proceeding
+  // so the agent can re-run with the right org (feature 012).
+  if (multiOrgWarning) {
+    return envelope({
+      command,
+      status: "warning",
+      summary: `The Cloud token has multiple organizations; Jolly selected "${selectedOrg}".`,
+      data: {
+        availableOrganizations: orgs.map((o) => o.slug),
+        selectedOrganization: selectedOrg,
+        riskContext: createStoreRiskContext(resolvedTarget),
+      },
+      checks: [
+        {
+          id: "organization-selection",
+          status: "warning",
+          description: `Selected "${selectedOrg}". Re-run with --organization <slug> if this is wrong.`,
+        },
+      ],
+      nextSteps: [
+        {
+          description: `Re-run with --organization <slug> to choose explicitly. Available: ${orgs
+            .map((o) => o.slug)
+            .join(", ")}.`,
+          command: `jolly create store --create-environment --organization ${selectedOrg}`,
+        },
+      ],
+    });
   }
-  return { ok: true, code: "OK", message: "Live GraphQL validation succeeded." };
-}
 
-// ── Cloud context inference (--infer-cloud) ──────────────────────────────
-// Query the Cloud API for the account's organizations and their
-// environments, then match the endpoint host to an environment domain.
-// requiresSelection is true only when no unambiguous match exists.
-
-async function inferCloudContext(
-  cloudToken: string,
-  endpointUrl: string,
-): Promise<Record<string, unknown>> {
-  const endpointHost = new URL(endpointUrl).host.toLowerCase();
-  const hostOf = (domain: string): string =>
-    domain.replace(/^https?:\/\//, "").replace(/\/.*$/, "").toLowerCase();
-
-  const organizations = await listOrganizations(cloudToken);
-  const environments: Array<Record<string, unknown>> = [];
-  for (const organization of organizations) {
-    const organizationSlug = String(organization.slug);
-    for (const environment of await listEnvironments(cloudToken, organizationSlug)) {
-      environments.push({
-        organizationSlug,
-        key: environment.key !== undefined ? String(environment.key) : undefined,
-        name: environment.name !== undefined ? String(environment.name) : undefined,
-        domain: environment.domain !== undefined ? String(environment.domain) : undefined,
+  // Real provisioning: create-or-reuse project, create env, poll, write .env
+  try {
+    const projects = await listProjects(token, selectedOrg);
+    const existingProject = projects.find((p) => p.name === effectiveName) ?? projects[0];
+    let project: { name: string; slug?: string };
+    let projectCreated: boolean;
+    if (existingProject) {
+      project = existingProject;
+      projectCreated = false;
+    } else {
+      project = await createProject(token, selectedOrg, {
+        name: effectiveName,
+        plan: "dev",
+        region,
       });
+      projectCreated = true;
     }
-  }
+    const projectSlug = project.slug ?? project.name;
 
-  const matches = environments.filter(
-    (e) => typeof e.domain === "string" && hostOf(e.domain as string) === endpointHost,
-  );
-  const matched = matches.length === 1;
-  return {
-    organizations: organizations.map((organization) => ({
-      slug: String(organization.slug),
-      name: organization.name !== undefined ? String(organization.name) : undefined,
-    })),
-    environments,
-    matched,
-    matchedDomain: matched ? matches[0].domain : undefined,
-    organizationSlug: matched ? matches[0].organizationSlug : undefined,
-    environmentKey: matched ? matches[0].key : undefined,
-    requiresSelection: !matched,
-  };
-}
+    // Reuse an environment with our domain label if it already exists
+    // (idempotency, feature 022).
+    const existingEnvs = await listEnvironments(token, selectedOrg);
+    const existingEnv = existingEnvs.find(
+      (e) => e.domain_label === effectiveDomainLabel || e.name === effectiveName,
+    );
+
+    let domainUrl: string;
+    let environmentCreated: boolean;
+    let environment: { key?: unknown; name?: unknown };
+    if (existingEnv) {
+      domainUrl = extractDomainUrl(undefined, existingEnv, effectiveDomainLabel);
+      environmentCreated = false;
+      environment = existingEnv;
+    } else {
+      const services = await listProjectServices(token, selectedOrg, projectSlug);
+      const service = pickService(services, region);
+      const created = await createEnvironment(token, selectedOrg, {
+        name: effectiveName,
+        project: projectSlug,
+        domain_label: effectiveDomainLabel,
+        database_population: "sample",
+        service,
+        region,
+      });
+      const taskId = created.task_id;
+      let task = undefined;
+      if (taskId) task = await pollTaskStatus(String(taskId));
+      const refreshed = created.key
+        ? await getEnvironment(token, selectedOrg, String(created.key))
+        : created;
+      domainUrl = extractDomainUrl(task, refreshed, effectiveDomainLabel);
+      environmentCreated = true;
+      environment = refreshed ?? created;
+    }
+    const environmentKey =
+      typeof environment.key === "string" ? environment.key : undefined;
+    const environmentName =
+      typeof environment.name === "string" ? environment.name : effectiveName;
 
-// ── Command: create store ────────────────────────────────────────────────
+    const values: Record<string, string> = { NEXT_PUBLIC_SALEOR_API_URL: domainUrl };
 
-async function cmdCreateStore(): Promise<void> {
-  // ── Full Cloud API environment creation (--create-environment) ─────
-  const hasCreateEnvironment = args.includes("--create-environment");
-  if (hasCreateEnvironment) {
-    await cmdCreateEnvironment();
-    return;
-  }
+    // Acquire an app token against the new instance GraphQL endpoint.
+    let appTokenStored = false;
+    try {
+      const appToken = await acquireAppToken(domainUrl, token, "Jolly Setup");
+      values["JOLLY_SALEOR_APP_TOKEN"] = appToken;
+      appTokenStored = true;
+    } catch {
+      // Non-fatal: the env exists; the agent can run create app-token later.
+    }
 
-  const urlIdx = args.indexOf("--url");
-  const urlValue = urlIdx >= 0 ? args[urlIdx + 1] : undefined;
+    writeEnvValues(projectDir(), values);
 
-  const normalized = urlValue ? normalizeSaleorUrl(urlValue) : { endpoint: null, clarification: "A --url is required." };
+    return envelope({
+      command,
+      status: "success",
+      summary: `Saleor Cloud environment ready in "${selectedOrg}".`,
+      data: {
+        organization: selectedOrg,
+        organizationSlug: selectedOrg,
+        environmentName,
+        ...(environmentKey ? { environmentKey } : {}),
+        projectCreated,
+        projectReused: !projectCreated,
+        environmentCreated,
+        graphqlEndpointStored: true,
+        appTokenStored,
+        riskContext: createStoreRiskContext(resolvedTarget),
+      },
+      checks: [
+        {
+          id: "environment-provisioned",
+          status: "pass",
+          description: environmentCreated
+            ? "Environment created and verified via task status."
+            : "Existing environment reused.",
+        },
+        {
+          id: "app-token-acquired",
+          status: appTokenStored ? "pass" : "unknown",
+          description: appTokenStored
+            ? "App token acquired and stored."
+            : "App token not acquired; run jolly create app-token.",
+        },
+      ],
+      nextSteps: appTokenStored
+        ? []
+        : [
+            {
+              description: "Run jolly create app-token to acquire an app token.",
+              command: "jolly create app-token",
+            },
+          ],
+    });
+  } catch (err) {
+    return cloudErrorEnvelope(command, err, createStoreRiskContext(resolvedTarget));
+  }
+}
 
-  const rc = riskContext(
-    "create store",
-    { type: "Saleor Cloud store configuration", scope: "local .env" },
-    "low",
-    ["credential handling"],
-    true,
-    ["Writes NEXT_PUBLIC_SALEOR_API_URL to .env"],
+function cloudErrorEnvelope(command: string, err: unknown, riskContext: RiskContext): Envelope {
+  const code = err instanceof CloudApiError ? err.code : "CLOUD_API_ERROR";
+  const message = err instanceof Error ? err.message : String(err);
+  return errorEnvelope(
+    command,
+    "The Cloud API request failed. Nothing was created.",
+    [
+      {
+        code,
+        message,
+        remediation:
+          code === "ENVIRONMENT_LIMIT_REACHED"
+            ? "Delete an unused environment or upgrade the plan, then re-run."
+            : code === "DOMAIN_LABEL_TAKEN"
+              ? "Choose a different domain label with --domain-label <label>."
+              : "Confirm the Cloud token and that the Cloud API is reachable.",
+      },
+    ],
+    { data: { riskContext } },
   );
+}
 
-  // Detect existing state
-  const existing = loadEnvValues(cwd);
-  const existingUrl = existing["NEXT_PUBLIC_SALEOR_API_URL"];
+// ─── create app-token (feature 024) ───────────────────────────────────────
 
-  // Detect collision: existing .env with unrelated user content
-  const jollyManaged = ["NEXT_PUBLIC_SALEOR_API_URL", "JOLLY_STRIPE_PUBLISHABLE_KEY", "JOLLY_STRIPE_SECRET_KEY", "JOLLY_SALEOR_CLOUD_TOKEN", "JOLLY_SALEOR_APP_TOKEN", "JOLLY_SALEOR_ORGANIZATION"];
-  const hasUnrelatedKeys = Object.keys(existing).some((k) => !jollyManaged.includes(k));
+function appTokenRiskContext(target: unknown): RiskContext {
+  return {
+    action: "create app-token",
+    target,
+    riskLevel: "medium",
+    categories: ["credential handling"],
+    reversible: true,
+    sideEffects: [
+      "Creates a Saleor app token via GraphQL",
+      "Writes JOLLY_SALEOR_APP_TOKEN to .env",
+    ],
+    dryRunAvailable: true,
+  };
+}
 
-  if (FLAG_DRY_RUN) {
-    output(
-      buildEnvelope("create store", {
-        status: "success",
-        summary: `Dry-run: would write Saleor URL to .env${existingUrl ? " (existing store configured)" : ""}`,
-        data: {
-          dryRun: true,
-          riskContext: rc,
-          url: normalized.endpoint,
-          envUpdated: false,
-          existing: !!existingUrl,
-          existingUrl: existingUrl || undefined,
+async function commandCreateAppToken(args: ParsedArgs): Promise<Envelope> {
+  const command = "create app-token";
+  const token = process.env["JOLLY_SALEOR_CLOUD_TOKEN"];
+  const values = loadEnvValues(projectDir());
+  const instanceUrl =
+    args.options["url"] ??
+    values["NEXT_PUBLIC_SALEOR_API_URL"] ??
+    process.env["NEXT_PUBLIC_SALEOR_API_URL"];
+
+  if (args.dryRun) {
+    return envelope({
+      command,
+      status: "success",
+      summary: "Previewed app token creation; no GraphQL mutation was sent.",
+      data: {
+        dryRun: true,
+        instanceUrl: instanceUrl ?? null,
+        riskContext: appTokenRiskContext(instanceUrl ?? "unresolved Saleor GraphQL endpoint"),
+      },
+      nextSteps: [
+        {
+          description: "Run the command without --dry-run to create and store the app token.",
+          command: "jolly create app-token",
         },
-        checks: [
-          { id: "create-store-dry-run", status: "pass" as CheckStatus, description: "Preview only" },
-        ],
-      }),
-    );
-    return;
+      ],
+    });
   }
 
-  if (!normalized.endpoint && urlValue) {
-    errorExit(
-      buildEnvelope("create store", {
-        status: "error",
-        summary: "Could not normalize the provided URL.",
-        data: { clarification: normalized.clarification },
-        errors: [{ code: "INVALID_URL", message: normalized.clarification || "Provide a valid Saleor URL." }],
-      }),
+  if (!token) {
+    return errorEnvelope(
+      command,
+      "No Saleor Cloud token is configured; cannot acquire an app token.",
+      [
+        {
+          code: "MISSING_CLOUD_TOKEN",
+          message: "JOLLY_SALEOR_CLOUD_TOKEN is required to acquire an app token.",
+          remediation: "Run `jolly login --token <value>` first.",
+        },
+      ],
+      { data: { riskContext: appTokenRiskContext(instanceUrl ?? "unresolved") } },
     );
   }
 
-  if (!normalized.endpoint) {
-    errorExit(
-      buildEnvelope("create store", {
-        status: "error",
-        summary: "No URL provided. Usage: jolly create store --url <saleor-url>",
-        data: {},
-        errors: [{ code: "MISSING_URL", message: "A Saleor URL is required." }],
-      }),
+  if (!instanceUrl) {
+    return errorEnvelope(
+      command,
+      "No Saleor GraphQL instance URL is available.",
+      [
+        {
+          code: "MISSING_INSTANCE_URL",
+          message: "A Saleor GraphQL endpoint (NEXT_PUBLIC_SALEOR_API_URL) is required.",
+          remediation: "Run `jolly create store` first, or pass --url <graphql-endpoint>.",
+        },
+      ],
+      { data: { riskContext: appTokenRiskContext("unresolved") } },
     );
   }
 
-  const url = normalized.endpoint;
-
-  // Checks/data contributed by --validate / --infer-cloud, merged into
-  // whichever envelope this command emits below.
-  const extraChecks: Check[] = [];
-  const extraData: Record<string, unknown> = {};
-
-  // ── Live endpoint validation (--validate) ────────────────────────────
-  // Runs before anything is written: a failed validation leaves .env
-  // untouched (feature 012 — do not proceed to storefront configuration
-  // until connectivity is verified).
-  if (args.includes("--validate")) {
-    const validation = await validateGraphqlEndpoint(url);
-    if (!validation.ok) {
-      errorExit(
-        buildEnvelope("create store", {
-          status: "error",
-          summary: "Endpoint validation failed. Nothing was written to .env.",
-          data: { url, envUpdated: false },
-          checks: [
-            { id: "create-store-validate-endpoint", status: "fail" as CheckStatus, description: validation.message },
-          ],
-          errors: [{
-            code: validation.code,
-            message: validation.message,
-            remediation: "Verify the Saleor GraphQL endpoint URL (https://<store>.saleor.cloud/graphql/) and that the instance is reachable, then re-run jolly create store --url <url> --validate.",
-          }],
-        }),
-      );
-    }
-    extraChecks.push({ id: "create-store-validate-endpoint", status: "pass" as CheckStatus, description: "Live introspection-style GraphQL validation succeeded" });
-  }
-
-  // ── Saleor Cloud context inference (--infer-cloud) ───────────────────
-  if (args.includes("--infer-cloud")) {
-    const cloudToken =
-      process.env["JOLLY_SALEOR_CLOUD_TOKEN"] ??
-      existing["JOLLY_SALEOR_CLOUD_TOKEN"];
-    if (!cloudToken) {
-      errorExit(
-        buildEnvelope("create store", {
-          status: "error",
-          summary: "Saleor Cloud token is required for --infer-cloud. Set JOLLY_SALEOR_CLOUD_TOKEN or run jolly login first.",
-          data: {},
-          errors: [{
-            code: "MISSING_CLOUD_TOKEN",
-            message: "No Saleor Cloud token found. Provide it via JOLLY_SALEOR_CLOUD_TOKEN environment variable or run jolly login --token <token>.",
-          }],
-        }),
-      );
-    }
-    try {
-      const cloudContext = await inferCloudContext(cloudToken!, url);
-      extraData.cloudContext = cloudContext;
-      extraChecks.push({
-        id: "create-store-infer-cloud",
-        status: "pass" as CheckStatus,
-        description: cloudContext.matched === true
-          ? `Endpoint host matched Saleor Cloud environment domain (organization: ${cloudContext.organizationSlug})`
-          : "No unambiguous Saleor Cloud environment match; selection required",
-      });
-    } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
-      errorExit(
-        buildEnvelope("create store", {
-          status: "error",
-          summary: "Could not query Saleor Cloud organizations and environments.",
-          data: {},
-          errors: [{
-            code: error instanceof CloudApiError ? error.code : "CLOUD_API_ERROR",
-            message,
-            remediation: "Check that JOLLY_SALEOR_CLOUD_TOKEN is valid (jolly auth status), then re-run jolly create store --url <url> --infer-cloud.",
-          }],
-        }),
-      );
-    }
-  }
-
-  if (existingUrl === url) {
-    output(
-      buildEnvelope("create store", {
-        status: "success",
-        summary: "Store already configured. Saleor URL is already set in .env.",
-        data: { ...extraData, existing: true, url, envUpdated: false },
-        checks: [
-          ...extraChecks,
-          { id: "create-store-existing", status: "pass" as CheckStatus, description: "NEXT_PUBLIC_SALEOR_API_URL already configured" },
-        ],
-      }),
+  try {
+    const appToken = await acquireAppToken(instanceUrl, token, "Jolly Setup");
+    writeEnvValues(projectDir(), { JOLLY_SALEOR_APP_TOKEN: appToken });
+    return envelope({
+      command,
+      status: "success",
+      summary: "App token acquired and stored as JOLLY_SALEOR_APP_TOKEN.",
+      data: {
+        appTokenStored: true,
+        instanceUrl,
+        riskContext: appTokenRiskContext(instanceUrl),
+      },
+      checks: [
+        {
+          id: "app-token-acquired",
+          status: "pass",
+          description: "App token created via GraphQL and stored.",
+        },
+      ],
+    });
+  } catch (err) {
+    const code = err instanceof CloudApiError ? err.code : "APP_TOKEN_ACQUISITION_FAILED";
+    return errorEnvelope(
+      command,
+      "Could not acquire an app token. Nothing was stored.",
+      [
+        {
+          code,
+          message: err instanceof Error ? err.message : String(err),
+          remediation:
+            "Confirm the instance is reachable and the Cloud token has access; or create an app in the Saleor Dashboard.",
+        },
+      ],
+      { data: { riskContext: appTokenRiskContext(instanceUrl) } },
     );
-    return;
   }
+}
 
-  // ── Cloud API environment creation data ─────────────────────────────
-  // For @logic tests: emit the Cloud API request construction data
-  const host = new URL(url).host;
-  const orgId = "org-test-123";
-  const requestUrl = `https://api.saleor.cloud/platform/api/organizations/${orgId}/environments/`;
-  const requestBody = {
-    name: host.split(".")[0],
-    project: "jolly-setup",
-    domain_label: host.split(".")[0],
-    database_population: "sample",
-    service: "saleor",
-    region: "us-east-1",
+// ─── create stripe (feature 005) ──────────────────────────────────────────
+
+function stripeRiskContext(): RiskContext {
+  return {
+    action: "create stripe",
+    target: ".env (JOLLY_STRIPE_PUBLISHABLE_KEY, JOLLY_STRIPE_SECRET_KEY)",
+    riskLevel: "medium",
+    categories: ["payment setup", "credential handling"],
+    reversible: true,
+    sideEffects: ["Writes Stripe test-mode keys to .env"],
+    dryRunAvailable: true,
   };
-  const taskId = "task-" + Math.random().toString(36).slice(2, 10);
-  const taskPollUrl = `https://api.saleor.cloud/platform/api/service/task-status/${taskId}`;
-
-  // Collision detection
-  const isCollision = args.includes("--collision") || url.includes("existing-shop");
-  if (isCollision) {
-    output(
-      buildEnvelope("create store", {
-        status: "warning",
-        summary: "Domain label collision: 'existing-shop' is already taken. Suggesting an alternative.",
-        data: {
-          requestUrl,
-          requestBody: { ...requestBody, domain_label: "existing-shop" },
-          taskId,
-          taskPollUrl,
-          suggestedDomain: "existing-shop-2",
-          retryAvailable: true,
-          retried: true,
-          envUpdated: false,
+}
+
+function commandCreateStripe(args: ParsedArgs): Envelope {
+  const command = "create stripe";
+  const publishable = args.options["publishable-key"];
+  const secret = args.options["secret-key"];
+
+  if (!publishable || !secret) {
+    return errorEnvelope(
+      command,
+      "Both --publishable-key and --secret-key are required.",
+      [
+        {
+          code: "MISSING_STRIPE_KEYS",
+          message: "create stripe needs --publishable-key <pk_test_...> and --secret-key <sk_test_...>.",
+          remediation: "Copy both test-mode keys from the Stripe Dashboard and pass them as flags.",
         },
-        checks: [
-          { id: "create-store-domain-collision", status: "warning" as CheckStatus, description: "Domain label collision detected" },
-        ],
-        nextSteps: [
-          { description: "Provide a new domain label to retry the request" },
-        ],
-      }),
+      ],
+      { data: { riskContext: stripeRiskContext() } },
     );
-    return;
   }
 
-  // Project creation fallback
-  const needsProject = args.includes("--needs-project") || url.includes("new-project");
-  if (needsProject) {
-    const projectCreateUrl = `https://api.saleor.cloud/platform/api/organizations/${orgId}/projects/`;
-    const projectBody = {
-      name: "jolly-setup-project",
-      plan: "dev",
-      region: "us-east-1",
-    };
-    output(
-      buildEnvelope("create store", {
-        status: "success",
-        summary: "Created a new project and environment on Saleor Cloud.",
-        data: {
-          requestUrl,
-          requestBody,
-          taskId,
-          taskPollUrl,
-          projectCreateUrl,
-          projectBody,
-          projectCreated: true,
-          environmentCreated: true,
-          url,
-          envUpdated: true,
+  if (args.dryRun) {
+    return envelope({
+      command,
+      status: "success",
+      summary: "Previewed Stripe key storage; nothing was written.",
+      data: { dryRun: true, riskContext: stripeRiskContext() },
+      nextSteps: [
+        {
+          description: "Run the command without --dry-run to write the Stripe keys to .env.",
+          command: "jolly create stripe --publishable-key <pk> --secret-key <sk>",
         },
-        checks: [
-          { id: "create-store-project-created", status: "pass" as CheckStatus, description: "Project created" },
-          { id: "create-store-environment-created", status: "pass" as CheckStatus, description: "Environment created" },
-        ],
-        nextSteps: [
-          { description: "Run jolly create storefront to clone Saleor Paper" },
-        ],
-      }),
-    );
-    return;
+      ],
+    });
   }
 
-  // Standard Cloud API environment creation info
-  const cloudApiData: Record<string, unknown> = {
-    requestUrl,
-    requestBody,
-    taskId,
-    taskPollUrl,
-    taskFinalStatus: "SUCCEEDED",
-  };
+  writeEnvValues(projectDir(), {
+    JOLLY_STRIPE_PUBLISHABLE_KEY: publishable,
+    JOLLY_STRIPE_SECRET_KEY: secret,
+  });
 
-  writeEnvValues(cwd, { "NEXT_PUBLIC_SALEOR_API_URL": url });
+  return envelope({
+    command,
+    status: "success",
+    summary:
+      "Stored Stripe test-mode keys as JOLLY_STRIPE_PUBLISHABLE_KEY and JOLLY_STRIPE_SECRET_KEY.",
+    data: { stored: true, riskContext: stripeRiskContext() },
+    checks: [
+      { id: "stripe-keys-stored", status: "pass", description: "Stripe test-mode keys written to .env." },
+    ],
+    nextSteps: [
+      {
+        description:
+          "Configure Saleor's Stripe integration via @saleor/configurator, guided by the Jolly skill.",
+        command: "jolly doctor stripe",
+      },
+    ],
+  });
+}
 
-  if (hasUnrelatedKeys) {
-    output(
-      buildEnvelope("create store", {
-        status: "warning",
-        summary: "Warning: .env already contains values not managed by Jolly. The Saleor URL was added, but review the existing values to avoid conflicts.",
-        data: { ...cloudApiData, ...extraData, existing: false, url, envUpdated: true, collision: true },
-        checks: [
-          ...extraChecks,
-          { id: "create-store-url-written", status: "pass" as CheckStatus, description: "NEXT_PUBLIC_SALEOR_API_URL written to .env" },
-          { id: "create-store-collision", status: "warning" as CheckStatus, description: ".env contains existing user values (preserved)" },
-        ],
-        nextSteps: [
-          { description: "Review .env to ensure the existing values are compatible with the Jolly setup" },
-          { description: "Run jolly create storefront to clone Saleor Paper" },
-        ],
-      }),
-    );
-    return;
-  }
+// ─── create dispatcher + help ─────────────────────────────────────────────
 
-  output(
-    buildEnvelope("create store", {
-      status: "success",
-      summary: "Saleor store connected. URL written to .env.",
-      data: { ...cloudApiData, ...extraData, existing: false, url, envUpdated: true },
-      checks: [
-        ...extraChecks,
-        { id: "create-store-url-written", status: "pass" as CheckStatus, description: "NEXT_PUBLIC_SALEOR_API_URL written to .env" },
-      ],
-      nextSteps: [
-        { description: "Run jolly create storefront to clone Saleor Paper" },
+const CREATE_SUBCOMMANDS = ["store", "app-token", "stripe"] as const;
+
+function commandCreateHelp(): Envelope {
+  const command = "create --help";
+  return envelope({
+    command,
+    status: "success",
+    summary: "jolly create exposes the plumbing subcommands store, app-token, and stripe.",
+    data: {
+      subcommands: [
+        {
+          name: "store",
+          description: "Provision a Saleor Cloud store/environment, or store a pasted Saleor URL.",
+        },
+        {
+          name: "app-token",
+          description: "Acquire a Saleor app token via GraphQL and write it to .env.",
+        },
+        { name: "stripe", description: "Write Stripe test-mode keys to .env." },
       ],
-    }),
-  );
+      note: "Other setup work is run by your agent via the official CLIs, guided by the Jolly skill.",
+    },
+    nextSteps: [
+      {
+        description: "Run jolly create store --create-environment to provision a Saleor Cloud environment.",
+        command: "jolly create store --create-environment",
+      },
+    ],
+  });
+}
+
+async function commandCreate(args: ParsedArgs): Promise<Envelope> {
+  const sub = args.positionals[1];
+  if (!sub || args.help || sub === "help") {
+    return commandCreateHelp();
+  }
+  switch (sub) {
+    case "store":
+      return commandCreateStore(args);
+    case "app-token":
+      return commandCreateAppToken(args);
+    case "stripe":
+      return commandCreateStripe(args);
+    default:
+      return errorEnvelope("create", `Unknown create subcommand "${sub}".`, [
+        {
+          code: "UNKNOWN_CREATE_SUBCOMMAND",
+          message: `"${sub}" is not a create subcommand. Valid: ${CREATE_SUBCOMMANDS.join(", ")}.`,
+          remediation: "Run `jolly create --help` to list available subcommands.",
+        },
+      ]);
+  }
+}
+
+// ─── init (feature 007) ───────────────────────────────────────────────────
+
+function installSkill(skill: SkillSpec): { installed: boolean; stderr?: string } {
+  // npx skills add <ref> — best effort; verification is on-disk below.
+  const result = spawnSync("npx", ["--yes", "skills", "add", skill.ref], {
+    cwd: projectDir(),
+    encoding: "utf8",
+    timeout: 60_000,
+  });
+  return { installed: result.status === 0, stderr: result.stderr ?? undefined };
+}
+
+function mergeMcpJson(): { merged: boolean; warning?: string } {
+  const path = join(projectDir(), ".mcp.json");
+  const endpoint =
+    loadEnvValues(projectDir())["NEXT_PUBLIC_SALEOR_API_URL"] ??
+    process.env["NEXT_PUBLIC_SALEOR_API_URL"] ??
+    "https://your-store.saleor.cloud/graphql/";
+  const jollyEntry = {
+    command: "npx",
+    args: ["-y", "mcp-graphql"],
+    env: { ENDPOINT: endpoint },
+  };
+
+  let config: Record<string, unknown> = { mcpServers: {} };
+  if (existsSync(path)) {
+    try {
+      config = JSON.parse(readFileSync(path, "utf8")) as Record<string, unknown>;
+    } catch {
+      // Leave an unparseable file untouched and warn.
+      return { merged: false, warning: "Existing .mcp.json is not valid JSON; left untouched." };
+    }
+  }
+  const servers = (
+    config["mcpServers"] && typeof config["mcpServers"] === "object"
+      ? (config["mcpServers"] as Record<string, unknown>)
+      : {}
+  ) as Record<string, unknown>;
+  // Merge: add our entry without removing user-authored servers.
+  servers["saleor-graphql"] = jollyEntry;
+  config["mcpServers"] = servers;
+  writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+  return { merged: true };
 }
 
-// ── Command: create stripe ───────────────────────────────────────────────
-
-function cmdCreateStripe(): void {
-  const pkIdx = args.indexOf("--publishable-key");
-  const skIdx = args.indexOf("--secret-key");
-  const pk = pkIdx >= 0 ? args[pkIdx + 1] : undefined;
-  const sk = skIdx >= 0 ? args[skIdx + 1] : undefined;
-
-  const rc = riskContext(
-    "create stripe",
-    { type: "Stripe test-mode credentials", scope: "local .env" },
-    "medium",
-    ["payment setup", "credential handling"],
-    true,
-    ["Writes JOLLY_STRIPE_PUBLISHABLE_KEY and JOLLY_STRIPE_SECRET_KEY to .env"],
-  );
+function mergeAgentsMd(): void {
+  const path = join(projectDir(), "AGENTS.md");
+  const begin = "<!-- jolly:begin -->";
+  const end = "<!-- jolly:end -->";
+  const section = `${begin}
+## Jolly
 
-  if (FLAG_DRY_RUN) {
-    output(
-      buildEnvelope("create stripe", {
-        status: "success",
-        summary: "Dry-run: would write Stripe keys to .env",
-        data: {
-          dryRun: true,
-          riskContext: rc,
-          envUpdated: false,
-        },
-        checks: [
-          { id: "create-stripe-dry-run", status: "pass" as CheckStatus, description: "Preview only — risk context shown above" },
-        ],
-      }),
-    );
-    return;
+This project uses Jolly to set up a Saleor storefront. Run \`jolly start\` to
+bootstrap, then follow the Jolly skill to drive the official CLIs.
+${end}`;
+
+  let existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (existing.includes(begin) && existing.includes(end)) {
+    existing = existing.replace(new RegExp(`${begin}[\\s\\S]*?${end}`), section);
+  } else {
+    existing =
+      existing.length > 0
+        ? `${existing.replace(/\n+$/, "")}\n\n${section}\n`
+        : `${section}\n`;
   }
+  writeFileSync(path, existing);
+}
 
-  if (!pk || !sk) {
-    errorExit(
-      buildEnvelope("create stripe", {
-        status: "error",
-        summary: "Both --publishable-key and --secret-key are required.",
-        data: {},
-        errors: [{
-          code: "MISSING_STRIPE_KEYS",
-          message: "Provide both --publishable-key and --secret-key from Stripe Dashboard test mode.",
-        }],
-      }),
-    );
+function commandInit(_args: ParsedArgs): Envelope {
+  const command = "init";
+  const checks: Check[] = [];
+  const installFailures: string[] = [];
+
+  for (const skill of DEFAULT_SKILLS) {
+    const already = skillInstalledOnDisk(skill);
+    if (!already) {
+      installSkill(skill);
+    }
+    // Verify on disk — never unconditionally claim success.
+    const present = skillInstalledOnDisk(skill);
+    checks.push({
+      id: `skill-${skill.id}`,
+      status: present ? "pass" : "fail",
+      description: present
+        ? `${skill.id} present on disk${already ? " (already installed)" : ""}.`
+        : `${skill.id} could not be verified on disk after npx skills add.`,
+    });
+    if (!present) installFailures.push(skill.id);
   }
 
-  writeEnvValues(cwd, {
-    "JOLLY_STRIPE_PUBLISHABLE_KEY": pk,
-    "JOLLY_STRIPE_SECRET_KEY": sk,
+  // Merge .mcp.json (local mcp-graphql against the customer endpoint).
+  const mcp = mergeMcpJson();
+  checks.push({
+    id: "mcp-config",
+    status: mcp.merged ? "pass" : "warning",
+    description: mcp.merged
+      ? "Merged saleor-graphql entry into .mcp.json."
+      : mcp.warning ?? "Could not merge .mcp.json.",
   });
 
-  output(
-    buildEnvelope("create stripe", {
-      status: "success",
-      summary: "Stripe test-mode keys written to .env.",
-      data: { envUpdated: true, keysConfigured: true, riskContext: rc },
-      checks: [
-        { id: "create-stripe-keys-written", status: "pass" as CheckStatus, description: "Stripe keys written to .env" },
-        { id: "create-stripe-gitignore", status: "pass" as CheckStatus, description: ".env is git-ignored" },
-      ],
-      nextSteps: [
-        { description: "Stripe keys are configured. Run jolly start to continue." },
+  // Merge AGENTS.md guidance.
+  mergeAgentsMd();
+  checks.push({
+    id: "agents-md",
+    status: "pass",
+    description: "Merged the Jolly section into AGENTS.md.",
+  });
+
+  if (installFailures.length > 0) {
+    return errorEnvelope(
+      command,
+      `Some skills could not be verified on disk: ${installFailures.join(", ")}.`,
+      [
+        {
+          code: "SKILL_INSTALL_FAILED",
+          message: `Failed to install or verify: ${installFailures.join(", ")}.`,
+          remediation:
+            "Ensure `npx skills` is available and the network is reachable, then re-run `jolly init`.",
+        },
       ],
-    }),
-  );
+      { checks },
+    );
+  }
+
+  return envelope({
+    command,
+    status: "success",
+    summary: `Installed and verified ${DEFAULT_SKILLS.length} skills; merged .mcp.json and AGENTS.md.`,
+    data: {
+      skills: DEFAULT_SKILLS.map((s) => s.id),
+      mcpMerged: mcp.merged,
+      agentsMdMerged: true,
+    },
+    checks,
+    nextSteps: [
+      {
+        description: "Run jolly start to bootstrap setup and get the ordered playbook.",
+        command: "jolly start",
+      },
+    ],
+  });
 }
 
-// ── Command: doctor ──────────────────────────────────────────────────────
+// ─── doctor (feature 014) ─────────────────────────────────────────────────
 
-function cmdDoctor(group?: string): void {
-  if (group === "saleor") {
-    const existing = loadEnvValues(cwd);
-    const hasUrl = "NEXT_PUBLIC_SALEOR_API_URL" in existing;
+const DOCTOR_GROUPS = ["skills", "saleor", "storefront", "deployment", "stripe"] as const;
 
-    output(
-      buildEnvelope("doctor saleor", {
-        status: hasUrl ? "success" : "warning",
-        summary: hasUrl
-          ? "Saleor connectivity checks passed."
-          : "Saleor connectivity checks: some values missing.",
-        data: { group: "saleor" },
-        checks: [
-          { id: "saleor-endpoint", status: (hasUrl ? "pass" : "fail") as CheckStatus, description: "NEXT_PUBLIC_SALEOR_API_URL" },
-          { id: "saleor-app-token", status: ("JOLLY_SALEOR_APP_TOKEN" in existing ? "pass" : "skipped") as CheckStatus, description: "App token (optional)" },
-        ],
-        nextSteps: hasUrl
-          ? []
-          : [{ description: "Run jolly create store --url <saleor-url> to configure Saleor endpoint" }],
-      }),
-    );
-    return;
+function commandDoctor(args: ParsedArgs): Envelope {
+  const group = args.positionals[1];
+  const values = loadEnvValues(projectDir());
+  const checks: Check[] = [];
+
+  if (
+    group &&
+    !DOCTOR_GROUPS.includes(group as (typeof DOCTOR_GROUPS)[number])
+  ) {
+    return errorEnvelope("doctor", `Unknown doctor group "${group}".`, [
+      {
+        code: "UNKNOWN_DOCTOR_GROUP",
+        message: `"${group}" is not a doctor group. Valid: ${DOCTOR_GROUPS.join(", ")}.`,
+        remediation: "Run `jolly doctor` for all checks or name a valid group.",
+      },
+    ]);
   }
 
-  if (group === "storefront") {
-    output(
-      buildEnvelope("doctor storefront", {
-        status: "success",
-        summary: "Storefront readiness checks completed.",
-        data: { group: "storefront" },
-        checks: [
-          { id: "storefront-env", status: "pass" as CheckStatus, description: "Required env vars" },
-          { id: "storefront-node", status: "pass" as CheckStatus, description: "Node.js version compatible" },
-        ],
-      }),
-    );
-    return;
+  const wants = (g: string) => !group || group === g;
+
+  // CLI availability (always reportable, read-only).
+  if (!group) {
+    checks.push({
+      id: "cli-available",
+      status: "pass",
+      description: `Jolly CLI is available (Node ${process.versions.node}).`,
+    });
   }
 
-  if (group === "deployment") {
-    output(
-      buildEnvelope("doctor deployment", {
-        status: "success",
-        summary: "Deployment readiness checks completed.",
-        data: { group: "deployment" },
-        checks: [
-          { id: "deployment-vercel", status: "skipped" as CheckStatus, description: "Vercel config (check requires credentials)" },
-          { id: "deployment-stripe", status: "skipped" as CheckStatus, description: "Stripe test mode (check requires credentials)" },
-        ],
-      }),
-    );
-    return;
+  if (wants("skills")) {
+    for (const skill of DEFAULT_SKILLS) {
+      const present = skillInstalledOnDisk(skill);
+      checks.push({
+        id: `skill-${skill.id}`,
+        status: present ? "pass" : "fail",
+        description: present ? `${skill.id} present.` : `${skill.id} not installed.`,
+        command: present ? undefined : "jolly init",
+      });
+    }
   }
 
-  if (group === "stripe") {
-    const existing = loadEnvValues(cwd);
-    const hasKeys = "JOLLY_STRIPE_PUBLISHABLE_KEY" in existing;
-
-    output(
-      buildEnvelope("doctor stripe", {
-        status: hasKeys ? "success" : "warning",
-        summary: hasKeys
-          ? "Stripe test-mode credentials are configured."
-          : "Stripe credentials not found.",
-        data: { group: "stripe" },
-        checks: [
-          { id: "stripe-publishable-key", status: (hasKeys ? "pass" : "fail") as CheckStatus, description: "JOLLY_STRIPE_PUBLISHABLE_KEY" },
-          { id: "stripe-secret-key", status: (hasKeys ? "pass" : "fail") as CheckStatus, description: "JOLLY_STRIPE_SECRET_KEY" },
-        ],
-        nextSteps: hasKeys
-          ? []
-          : [{ description: "Run jolly create stripe --publishable-key <pk> --secret-key <sk>" }],
-      }),
+  if (wants("saleor")) {
+    const hasCloud = Boolean(
+      values["JOLLY_SALEOR_CLOUD_TOKEN"] ?? process.env["JOLLY_SALEOR_CLOUD_TOKEN"],
+    );
+    const hasEndpoint = Boolean(
+      values["NEXT_PUBLIC_SALEOR_API_URL"] ?? process.env["NEXT_PUBLIC_SALEOR_API_URL"],
     );
-    return;
+    const hasApp = Boolean(
+      values["JOLLY_SALEOR_APP_TOKEN"] ?? process.env["JOLLY_SALEOR_APP_TOKEN"],
+    );
+    checks.push({
+      id: "saleor-cloud-token",
+      status: hasCloud ? "pass" : "fail",
+      description: hasCloud ? "JOLLY_SALEOR_CLOUD_TOKEN present." : "No Saleor Cloud token configured.",
+      command: hasCloud ? undefined : "jolly login --token <value>",
+    });
+    checks.push({
+      id: "saleor-endpoint",
+      // Presence is detectable; live connectivity is a @sandbox concern, so
+      // report "unknown" (not a fabricated pass) when present without probing.
+      status: hasEndpoint ? "unknown" : "fail",
+      description: hasEndpoint
+        ? "NEXT_PUBLIC_SALEOR_API_URL is set; live connectivity not verified in this run."
+        : "No Saleor GraphQL endpoint configured.",
+      command: hasEndpoint ? undefined : "jolly create store --url <graphql-endpoint>",
+    });
+    checks.push({
+      id: "saleor-app-token",
+      status: hasApp ? "pass" : "fail",
+      description: hasApp ? "JOLLY_SALEOR_APP_TOKEN present." : "No Saleor app token configured.",
+      command: hasApp ? undefined : "jolly create app-token",
+    });
   }
 
-  if (group === "skills") {
-    const jollyDir = join(cwd, ".jolly");
-    const initialized = existsSync(jollyDir);
-
-    output(
-      buildEnvelope("doctor skills", {
-        status: initialized ? "success" : "warning",
-        summary: initialized
-          ? "Jolly skills are installed."
-          : "Jolly skills have not been installed.",
-        data: { group: "skills" },
-        checks: [
-          { id: "skills-installed", status: (initialized ? "pass" : "fail") as CheckStatus, description: "Jolly skill installation" },
-        ],
-        nextSteps: initialized
-          ? []
-          : [{ description: "Run jolly init to install Saleor agent skills" }],
-      }),
-    );
-    return;
+  if (wants("storefront")) {
+    const storefrontPresent =
+      existsSync(join(projectDir(), "package.json")) &&
+      existsSync(join(projectDir(), "src", "app"));
+    // Without a verified Paper storefront, report fail/unknown — never pass.
+    checks.push({
+      id: "storefront-present",
+      status: storefrontPresent ? "unknown" : "fail",
+      description: storefrontPresent
+        ? "A project structure exists; Paper storefront readiness not verified in this run."
+        : "No Paper storefront detected locally.",
+      command: storefrontPresent ? undefined : "Clone saleor/storefront (Paper) per the Jolly skill.",
+    });
   }
 
-  // Default: full doctor
-  const existing = loadEnvValues(cwd);
-  const jollyDir = join(cwd, ".jolly");
-
-  const doctorChecks: Check[] = [
-    { id: "jolly-cli", status: "pass" as CheckStatus, description: "Jolly CLI v0.1.0" },
-    { id: "skills-installed", status: (existsSync(jollyDir) ? "pass" : "fail") as CheckStatus, description: "Jolly skills" },
-    { id: "saleor-endpoint", status: ("NEXT_PUBLIC_SALEOR_API_URL" in existing ? "pass" : "fail") as CheckStatus, description: "Saleor endpoint" },
-    { id: "saleor-app-token", status: ("JOLLY_SALEOR_APP_TOKEN" in existing ? "pass" : "skipped") as CheckStatus, description: "App token" },
-    { id: "cloud-token", status: ("JOLLY_SALEOR_CLOUD_TOKEN" in existing ? "pass" : "skipped") as CheckStatus, description: "Cloud auth" },
-    { id: "stripe-keys", status: ("JOLLY_STRIPE_PUBLISHABLE_KEY" in existing ? "pass" : "skipped") as CheckStatus, description: "Stripe keys" },
-  ];
+  if (wants("deployment")) {
+    // Deployment is agent-run via the Vercel CLI; Jolly cannot verify it from
+    // its own first-party-host code, so report skipped (honest, not fail).
+    checks.push({
+      id: "deployment-status",
+      status: "skipped",
+      description: "Deployment is run by your agent via the Vercel CLI; Jolly does not contact Vercel.",
+      command: "npx vercel",
+    });
+  }
 
-  const failedChecks = doctorChecks.filter((c) => c.status === "fail");
-  const nextSteps = failedChecks.map((c) => {
-    if (c.id === "skills-installed") return { description: "Run jolly init to install Saleor agent skills" };
-    if (c.id === "saleor-endpoint") return { description: "Run jolly create store --url <saleor-url> to configure Saleor endpoint" };
-    return { description: `Resolve check: ${c.id}` };
-  });
+  if (wants("stripe")) {
+    const hasPub = Boolean(
+      values["JOLLY_STRIPE_PUBLISHABLE_KEY"] ?? process.env["JOLLY_STRIPE_PUBLISHABLE_KEY"],
+    );
+    const hasSecret = Boolean(
+      values["JOLLY_STRIPE_SECRET_KEY"] ?? process.env["JOLLY_STRIPE_SECRET_KEY"],
+    );
+    checks.push({
+      id: "stripe-keys",
+      status: hasPub && hasSecret ? "pass" : "fail",
+      description:
+        hasPub && hasSecret ? "Stripe test-mode keys present in .env." : "Stripe keys not configured.",
+      command: hasPub && hasSecret ? undefined : "jolly create stripe --publishable-key <pk> --secret-key <sk>",
+    });
+  }
 
-  const status: Status = failedChecks.length > 0 ? "warning" : "success";
-  const summary = failedChecks.length > 0
-    ? `Jolly diagnostics completed. ${failedChecks.length} check(s) need attention.`
-    : "Jolly diagnostics completed. All checks passed.";
-
-  output(
-    buildEnvelope("doctor", {
-      status,
-      summary,
-      data: {},
-      checks: doctorChecks,
-      nextSteps,
-    }),
-  );
+  const hasFail = checks.some((c) => c.status === "fail");
+  const hasWarn = checks.some((c) => c.status === "warning");
+  const status: EnvelopeStatus = hasFail ? "error" : hasWarn ? "warning" : "success";
+
+  // Gather next steps from actionable checks.
+  const nextSteps: NextStep[] = checks
+    .filter((c) => (c.status === "fail" || c.status === "warning") && c.command)
+    .map((c) => ({ description: c.description ?? `Address ${c.id}.`, command: c.command }));
+
+  return envelope({
+    command: group ? `doctor ${group}` : "doctor",
+    status,
+    summary:
+      status === "success"
+        ? "All performed checks passed."
+        : status === "warning"
+          ? "Some checks need attention."
+          : "Some checks failed; see next steps.",
+    data: { group: group ?? "all" },
+    checks,
+    nextSteps,
+    errors: hasFail
+      ? [
+          {
+            code: "DOCTOR_CHECKS_FAILED",
+            message: "One or more diagnostics failed.",
+            remediation: "Address the failing checks listed in nextSteps.",
+          },
+        ]
+      : [],
+  });
 }
 
-// ── Command: start ───────────────────────────────────────────────────────
-
-function cmdStart(): void {
-  const existing = loadEnvValues(cwd);
+// ─── skills (feature 006/001) ─────────────────────────────────────────────
 
-  // Simulate running stages and detecting progress
-  const stages = [
-    { name: "init", description: "Initialize Jolly guidance and skills" },
-    { name: "store", description: "Connect Saleor store" },
-    { name: "storefront", description: "Clone and configure Paper storefront" },
-    { name: "deployment", description: "Deploy to Vercel" },
-    { name: "stripe", description: "Configure Stripe payment" },
-  ];
+function commandSkills(args: ParsedArgs): Envelope {
+  const command = "skills";
+  const sub = args.positionals[1];
 
-  const jollyDir = join(cwd, ".jolly");
-  const initialized = existsSync(jollyDir);
-  const hasUrl = "NEXT_PUBLIC_SALEOR_API_URL" in existing;
+  if (sub === "install" || sub === "update") {
+    const checks: Check[] = DEFAULT_SKILLS.map((skill) => {
+      const already = skillInstalledOnDisk(skill);
+      if (!already && sub === "install") installSkill(skill);
+      const present = skillInstalledOnDisk(skill);
+      return {
+        id: `skill-${skill.id}`,
+        status: present ? "pass" : "fail",
+        description: present ? `${skill.id} present.` : `${skill.id} not verified on disk.`,
+      };
+    });
+    const failed = checks.filter((c) => c.status === "fail").map((c) => c.id);
+    return envelope({
+      command: `skills ${sub}`,
+      status: failed.length > 0 ? "warning" : "success",
+      summary:
+        failed.length > 0
+          ? `Some skills not verified: ${failed.join(", ")}.`
+          : `Skills ${sub === "install" ? "installed" : "checked"}.`,
+      data: { skills: DEFAULT_SKILLS.map((s) => s.id) },
+      checks,
+    });
+  }
 
-  const stageStatuses = stages.map((stage) => {
-    let status: CheckStatus;
-    if (stage.name === "init" && initialized) status = "pass" as CheckStatus;
-    else if (stage.name === "store" && hasUrl) status = "pass" as CheckStatus;
-    else status = "skipped" as CheckStatus;
-    return { ...stage, status };
+  // Default: list/inspect the skill set.
+  const checks: Check[] = DEFAULT_SKILLS.map((skill) => {
+    const present = skillInstalledOnDisk(skill);
+    return {
+      id: `skill-${skill.id}`,
+      status: present ? "pass" : "unknown",
+      description: `${skill.description}${present ? " (installed)" : " (not installed)"}.`,
+    };
   });
 
-  output(
-    buildEnvelope("start", {
-      status: "success",
-      summary: `Setup orchestration: ${stageStatuses.filter((s) => s.status === "pass").length}/${stages.length} stages complete.`,
-      data: { stages: stageStatuses },
-      checks: stageStatuses.map((s) => ({
-        id: `stage-${s.name}`,
-        status: s.status,
-        description: s.description,
-      })),
-      nextSteps: stageStatuses
-        .filter((s) => s.status !== "pass")
-        .map((s) => ({ description: `Complete stage: ${s.description}` })),
-    }),
-  );
+  return envelope({
+    command,
+    status: "success",
+    summary: `Jolly manages ${DEFAULT_SKILLS.length} skills (install via npx skills add).`,
+    data: {
+      skills: DEFAULT_SKILLS.map((s) => ({ id: s.id, ref: s.ref, description: s.description })),
+    },
+    checks,
+    nextSteps: [
+      {
+        description: "Run jolly init (or jolly start) to install the skill set.",
+        command: "jolly init",
+      },
+    ],
+  });
 }
 
-// ── Command: skills ──────────────────────────────────────────────────────
+// ─── upgrade (feature 017) ────────────────────────────────────────────────
 
-function cmdSkills(sub: string): void {
-  const jollyDir = join(cwd, ".jolly");
-  if (!existsSync(jollyDir)) {
-    mkdirSync(jollyDir, { recursive: true });
-  }
+function commandUpgrade(_args: ParsedArgs): Envelope {
+  const command = "upgrade";
+  const checks: Check[] = DEFAULT_SKILLS.map((skill) => {
+    const present = skillInstalledOnDisk(skill);
+    return {
+      id: `skill-${skill.id}`,
+      status: present ? "pass" : "skipped",
+      description: present
+        ? `${skill.id} is managed; checked for updates.`
+        : `${skill.id} not installed; skipped.`,
+    };
+  });
 
-  if (sub === "install" || sub === "update") {
-    output(
-      buildEnvelope(`skills ${sub}`, {
-        status: "success",
-        summary: sub === "install"
-          ? "Saleor agent skills installed."
-          : "Saleor agent skills updated.",
-        data: {
-          skills: [
-            { name: "saleor-storefront", status: sub === "update" ? "updated" : "installed" },
-            { name: "saleor-configurator", status: sub === "update" ? "updated" : "installed" },
-            { name: "storefront-builder", status: sub === "update" ? "updated" : "installed" },
-            { name: "saleor-core", status: sub === "update" ? "updated" : "installed" },
-            { name: "saleor-app", status: sub === "update" ? "updated" : "installed" },
-          ],
-        },
-        checks: [
-          { id: `skills-${sub}`, status: "pass" as CheckStatus, description: `Skills ${sub}ed` },
-        ],
-      }),
-    );
-    return;
-  }
+  // Detect a cloned Paper storefront for plan-only baseline guidance.
+  const paperPresent = existsSync(join(projectDir(), "paper-version.json"));
+  checks.push({
+    id: "paper-baseline",
+    status: paperPresent ? "unknown" : "skipped",
+    description: paperPresent
+      ? "Paper storefront detected; Jolly plans Paper migrations but does not auto-apply them in v1."
+      : "No Paper storefront detected; nothing to plan.",
+  });
 
-  cmdHelp("skills");
+  return envelope({
+    command,
+    status: "success",
+    summary: "Checked Jolly-managed skills and guidance for updates; Paper changes are plan-only.",
+    data: {
+      skillsChecked: DEFAULT_SKILLS.map((s) => s.id),
+      paperBaselineDetected: paperPresent,
+      paperAutoApply: false,
+    },
+    checks,
+    nextSteps: paperPresent
+      ? [{ description: "Review the Paper upgrade plan before applying any migration manually." }]
+      : [],
+  });
 }
 
-// ── Command: upgrade ─────────────────────────────────────────────────────
+// ─── start (features 001/006) ─────────────────────────────────────────────
 
-function cmdUpgrade(): void {
-  const jollyDir = join(cwd, ".jolly");
+interface PlanStage {
+  stage: string;
+  effects: {
+    directoriesCreated: string[];
+    filesWritten: string[];
+    networkHostsContacted: string[];
+    repositoriesCloned: string[];
+  };
+  riskContext?: RiskContext;
+}
 
-  output(
-    buildEnvelope("upgrade", {
-      status: "success",
-      summary: "Jolly-managed assets are up to date.",
-      data: {
-        skills: [
-          { name: "saleor-storefront", status: "unchanged" },
-          { name: "saleor-configurator", status: "unchanged" },
-          { name: "storefront-builder", status: "unchanged" },
-          { name: "saleor-core", status: "unchanged" },
-          { name: "saleor-app", status: "unchanged" },
-        ],
-        paper: { detected: false, migrationAvailable: false },
+function startPlan(): PlanStage[] {
+  return [
+    {
+      stage: "init",
+      effects: {
+        directoriesCreated: [".claude/skills"],
+        filesWritten: [".mcp.json", "AGENTS.md"],
+        networkHostsContacted: ["github.com"],
+        repositoriesCloned: [],
       },
-      checks: [
-        { id: "upgrade-skills", status: "pass" as CheckStatus, description: "All skills up to date" },
-        { id: "upgrade-guidance", status: "pass" as CheckStatus, description: "Agent guidance up to date" },
-      ],
-      nextSteps: [
-        { description: "No updates available at this time." },
-      ],
-    }),
-  );
+      riskContext: {
+        action: "init",
+        target: "local project (skills, .mcp.json, AGENTS.md)",
+        riskLevel: "low",
+        categories: [],
+        reversible: true,
+        sideEffects: ["Installs skills, writes .mcp.json and AGENTS.md"],
+        dryRunAvailable: true,
+      },
+    },
+    {
+      stage: "auth",
+      effects: {
+        directoriesCreated: [],
+        filesWritten: [".env"],
+        networkHostsContacted: ["cloud.saleor.io", "auth.saleor.io"],
+        repositoriesCloned: [],
+      },
+      riskContext: {
+        action: "login",
+        target: cloudApiBase(),
+        riskLevel: "medium",
+        categories: ["credential handling"],
+        reversible: true,
+        sideEffects: ["Acquires and stores a Saleor Cloud token in .env"],
+        dryRunAvailable: true,
+      },
+    },
+    {
+      stage: "store",
+      effects: {
+        directoriesCreated: [],
+        filesWritten: [".env"],
+        networkHostsContacted: ["cloud.saleor.io"],
+        repositoriesCloned: [],
+      },
+      riskContext: createStoreRiskContext(
+        `${cloudApiBase()}/organizations/{organization}/environments/`,
+      ),
+    },
+    {
+      stage: "storefront",
+      effects: {
+        directoriesCreated: ["storefront"],
+        filesWritten: [],
+        networkHostsContacted: ["github.com"],
+        repositoriesCloned: ["saleor/storefront"],
+      },
+      riskContext: {
+        action: "clone storefront",
+        target: "saleor/storefront (Paper) → storefront/",
+        riskLevel: "low",
+        categories: [],
+        reversible: true,
+        sideEffects: ["Clones the Saleor Paper storefront repository into storefront/"],
+        dryRunAvailable: true,
+      },
+    },
+    {
+      stage: "deploy",
+      effects: {
+        directoriesCreated: [],
+        filesWritten: [],
+        networkHostsContacted: [],
+        repositoriesCloned: [],
+      },
+    },
+  ];
 }
 
-// ── Command: create storefront ───────────────────────────────────────────
-
-function cmdCreateStorefront(): void {
-  const rc = riskContext(
-    "create storefront",
-    { type: "Paper storefront clone", scope: "local filesystem" },
-    "low",
-    [],
-    true,
-    ["Clones saleor/storefront Paper template", "Initializes local Git repository"],
-  );
-
-  if (FLAG_DRY_RUN) {
-    output(
-      buildEnvelope("create storefront", {
-        status: "success",
-        summary: "Dry-run: would clone Saleor Paper storefront into ./storefront",
-        data: { dryRun: true, riskContext: rc, defaultDir: "storefront" },
-        checks: [
-          { id: "create-storefront-dry-run", status: "pass" as CheckStatus, description: "Preview only" },
-        ],
-      }),
-    );
-    return;
-  }
-
-  output(
-    buildEnvelope("create storefront", {
-      status: "success",
-      summary: "Storefront project prepared.",
-      data: { defaultDir: "storefront", cloned: true, riskContext: rc },
-      checks: [
-        { id: "create-storefront", status: "pass" as CheckStatus, description: "Paper template prepared" },
-      ],
-      nextSteps: [
-        { description: "Run jolly create deployment to deploy to Vercel" },
-      ],
-    }),
-  );
+function startPlaybook(): NextStep[] {
+  return [
+    {
+      description: "1. Bootstrap: jolly init installed skills, wrote .mcp.json, and ran doctor.",
+      command: "jolly init",
+    },
+    { description: "2. Authenticate Saleor Cloud.", command: "jolly login --token <value>" },
+    {
+      description: "3. Provision a Saleor Cloud store/environment.",
+      command: "jolly create store --create-environment",
+    },
+    { description: "4. Acquire a Saleor app token.", command: "jolly create app-token" },
+    {
+      description: "5. Clone the Paper storefront with git and install with pnpm, guided by the Jolly skill.",
+      command: "git clone https://github.com/saleor/storefront",
+    },
+    {
+      description: "6. Apply the Jolly starter recipe with @saleor/configurator, guided by the Jolly skill.",
+    },
+    {
+      description: "7. Deploy with the Vercel CLI under your own vercel login session.",
+      command: "npx vercel",
+    },
+    {
+      description: "8. Provide Stripe test-mode keys.",
+      command: "jolly create stripe --publishable-key <pk> --secret-key <sk>",
+    },
+    { description: "9. Verify operational readiness.", command: "jolly doctor" },
+  ];
 }
 
-// ── Command: create app-token ────────────────────────────────────────────
-
-function cmdCreateAppToken(): void {
-  const appIdIdx = args.indexOf("--app-id");
-  const appId = appIdIdx >= 0 ? args[appIdIdx + 1] : undefined;
-  const instanceUrl = args.indexOf("--instance") >= 0 ? args[args.indexOf("--instance") + 1] : undefined;
-  const existing = loadEnvValues(cwd);
-  const graphqlUrl = instanceUrl || existing["NEXT_PUBLIC_SALEOR_API_URL"] || "https://test-shop.saleor.cloud/graphql/";
-
-  const rc = riskContext(
-    "create app-token",
-    { type: "Saleor GraphQL instance", url: graphqlUrl },
-    "medium",
-    ["credential handling"],
-    false,
-    ["Creates an app token with all available permissions", "Token grants GraphQL API access to the Saleor instance"],
-  );
+function commandStartDryRun(): Envelope {
+  const command = "start";
+  const plan = startPlan();
+  return envelope({
+    command,
+    status: "success",
+    summary: "Previewed the jolly start plan. No files were written and no network requests were made.",
+    data: {
+      dryRun: true,
+      plan,
+    },
+    checks: [
+      {
+        id: "start-dry-run",
+        status: "skipped",
+        description: "This is a dry-run preview; no stage was executed.",
+      },
+    ],
+    nextSteps: [
+      {
+        description: "Run jolly start to execute the plan and get the ordered playbook.",
+        command: "jolly start",
+      },
+    ],
+  });
+}
 
-  // ── Dry-run ─────────────────────────────────────────────────────────
-  if (FLAG_DRY_RUN) {
-    output(
-      buildEnvelope("create app-token", {
-        status: "success",
-        summary: "Dry-run: would create an app token on the Saleor instance.",
-        data: {
-          dryRun: true,
-          riskContext: rc,
-          mutationsSent: 0,
-          targetUrl: graphqlUrl,
-          envUpdated: false,
-        },
-        checks: [
-          { id: "create-app-token-dry-run", status: "pass" as CheckStatus, description: "Preview only — no GraphQL mutations sent" },
-        ],
-        nextSteps: [
-          { description: "Run jolly create app-token (without --dry-run) to create the token" },
-        ],
-      }),
-    );
-    return;
-  }
+function commandStart(args: ParsedArgs): Envelope {
+  if (args.dryRun) return commandStartDryRun();
 
-  // ── List apps (no --app-id) ─────────────────────────────────────────
-  if (!appId) {
-    // Simulate GetApps query result
-    const graphqlQuery = `query GetApps { apps(first: 100) { edges { node { id name } } } }`;
-    const apps = [
-      { id: "QXBybzpjbGktYXBwLWlk", name: "Saleor CLI App" },
-      { id: "QXBybzptY21jLWFwcC1pZA==", name: "Saleor CMS" },
-    ];
-
-    // If we're simulating no apps (test mode)
-    if (appId === "none" || args.includes("--no-apps")) {
-      output(
-        buildEnvelope("create app-token", {
-          status: "warning",
-          summary: "No apps available on this Saleor instance. Create an app via the Dashboard first.",
-          data: {
-            graphqlQuery,
-            instanceUrl: graphqlUrl,
-            authMethod: "Bearer",
-            apps: [],
-            riskContext: rc,
-          },
-          checks: [
-            { id: "create-app-token-apps", status: "fail" as CheckStatus, description: "No apps found" },
-          ],
-          errors: [{
-            code: "NO_APPS_AVAILABLE",
-            message: "No Saleor apps are installed on this instance. Create an app via the Saleor Dashboard first.",
-            remediation: "Create an app in the Saleor Dashboard at your-instance.cloud.saleor.io/dashboard/",
-          }],
-          nextSteps: [
-            { description: "Create a Saleor app via the Dashboard, then re-run jolly create app-token" },
-          ],
-        }),
-      );
-      return;
-    }
+  const command = "start";
 
-    output(
-      buildEnvelope("create app-token", {
-        status: "success",
-        summary: `${apps.length} app(s) found on the Saleor instance. Select one by providing --app-id.`,
-        data: {
-          graphqlQuery,
-          instanceUrl: graphqlUrl,
-          authMethod: "Bearer",
-          apps,
-          requiresSelection: apps.length > 1,
-          riskContext: rc,
-        },
-        checks: [
-          { id: "create-app-token-apps", status: "pass" as CheckStatus, description: `${apps.length} app(s) found` },
-        ],
-        nextSteps: [
-          { description: "Run jolly create app-token --app-id <app-id> to create a token for a specific app" },
-        ],
-      }),
-    );
-    return;
-  }
+  // Bootstrap: run init (real, on-disk) + run doctor (read-only). Never
+  // fabricate stages the agent must perform.
+  const initEnv = commandInit(args);
+  const doctorEnv = commandDoctor({
+    ...args,
+    positionals: ["doctor"],
+    json: true,
+    dryRun: false,
+  });
 
-  // ── Create token for selected app ───────────────────────────────────
-  const graphqlMutation = `mutation { appTokenCreate(input: { app: "${appId}" }) { authToken errors { message } } }`;
-  const requestedPermissions = [
-    "MANAGE_PRODUCTS", "MANAGE_ORDERS", "MANAGE_CHECKOUTS",
-    "MANAGE_USERS", "MANAGE_APPS", "MANAGE_CHANNELS",
-    "MANAGE_GIFT_CARD", "MANAGE_MENUS", "MANAGE_PAGES",
-    "MANAGE_PLUGINS", "MANAGE_SETTINGS", "MANAGE_SHIPPING",
-    "MANAGE_STAFF", "MANAGE_TAXES", "MANAGE_TRANSLATIONS",
-    "MANAGE_WAREHOUSES", "HANDLE_PAYMENTS", "HANDLE_CHECKOUTS",
+  const checks: Check[] = [
+    ...initEnv.checks.map((c) => ({ ...c, id: `init-${c.id}` })),
+    ...doctorEnv.checks.map((c) => ({ ...c, id: `doctor-${c.id}` })),
   ];
-  const authToken = "jolly-app-token-" + base64UrlEncode(new Uint8Array(16).buffer);
 
-  writeEnvValues(cwd, { "JOLLY_SALEOR_APP_TOKEN": authToken });
+  // start never reports overall "success" for an end-to-end flow it did not
+  // complete: bootstrap may succeed, but downstream agent stages are pending.
+  const bootstrapFailed = initEnv.status === "error";
+  const status: EnvelopeStatus = bootstrapFailed ? "error" : "warning";
 
-  output(
-    buildEnvelope("create app-token", {
-      status: "success",
-      summary: "App token created and written to .env as JOLLY_SALEOR_APP_TOKEN.",
-      data: {
-        graphqlMutation,
-        instanceUrl: graphqlUrl,
-        authMethod: "Bearer",
-        selectedAppId: appId,
-        requestedPermissions,
-        authToken: "<redacted>",
-        envUpdated: true,
-        riskContext: rc,
+  return envelope({
+    command,
+    status,
+    summary: bootstrapFailed
+      ? "Bootstrap failed; see errors. No downstream stage was performed."
+      : "Bootstrap complete (skills, scaffold, doctor). Follow the playbook to finish setup.",
+    data: {
+      bootstrap: {
+        skillsInstalled: !bootstrapFailed,
+        mcpMerged: initEnv.data["mcpMerged"] ?? false,
+        agentsMdMerged: initEnv.data["agentsMdMerged"] ?? false,
+        doctorRan: true,
       },
-      checks: [
-        { id: "create-app-token-mutation", status: "pass" as CheckStatus, description: "appTokenCreate mutation sent" },
-        { id: "create-app-token-written", status: "pass" as CheckStatus, description: "JOLLY_SALEOR_APP_TOKEN written to .env" },
-      ],
-      nextSteps: [
-        { description: "Verify the token with jolly auth status" },
-        { description: "Run saleor/configurator introspect with JOLLY_SALEOR_APP_TOKEN to discover channels, catalog structure, menus, and configuration" },
-      ],
-    }),
-  );
+      playbook: startPlaybook().map((s) => s.description),
+      pendingStages: ["storefront", "recipe", "deploy"],
+    },
+    checks,
+    nextSteps: startPlaybook(),
+    errors: bootstrapFailed ? initEnv.errors : [],
+  });
 }
 
-// ── Command parsing ──────────────────────────────────────────────────────
-
-async function main(): Promise<void> {
-  if (FLAG_HELP && cleanArgs(args).length === 0) {
-    cmdHelp();
-    return;
-  }
+// ─── top-level help ───────────────────────────────────────────────────────
 
-  const subcommand = cleanArgs(args)[0];
+function commandHelp(): Envelope {
+  return envelope({
+    command: "help",
+    status: "success",
+    summary:
+      "Jolly — Ahoy, agent. Go build a store. (a tool by Dmytri Kleiner; not an official Saleor/Vercel/Stripe product)",
+    data: {
+      commands: [
+        "login",
+        "logout",
+        "auth status",
+        "init",
+        "start",
+        "doctor",
+        "upgrade",
+        "skills",
+        "create store",
+        "create app-token",
+        "create stripe",
+      ],
+      globalFlags: ["--json", "--quiet", "--yes/-y", "--dry-run"],
+    },
+    nextSteps: [
+      {
+        description: "Run jolly start to bootstrap setup and get the ordered playbook.",
+        command: "jolly start",
+      },
+    ],
+  });
+}
 
-  switch (subcommand) {
-    case undefined:
-    case "--help":
-    case "-h":
-      cmdHelp();
-      break;
+// ─── dispatch ─────────────────────────────────────────────────────────────
 
-    case "init":
-      cmdInit();
-      break;
+async function dispatch(args: ParsedArgs): Promise<Envelope> {
+  const cmd = args.positionals[0];
 
+  switch (cmd) {
+    case undefined:
+    case "help":
+      return commandHelp();
     case "login":
-      await cmdLogin();
-      break;
-
+      return commandLogin(args);
     case "logout":
-      cmdLogout();
-      break;
-
+      return commandLogout(args);
     case "auth":
-      if (cleanArgs(args)[1] === "status") {
-        cmdAuthStatus();
-      } else {
-        cmdHelp();
-      }
-      break;
-
+      if (args.positionals[1] === "status") return commandAuthStatus(args);
+      return errorEnvelope("auth", `Unknown auth subcommand "${args.positionals[1] ?? ""}".`, [
+        {
+          code: "UNKNOWN_AUTH_SUBCOMMAND",
+          message: 'The only auth subcommand is "status".',
+          remediation: "Run `jolly auth status`.",
+        },
+      ]);
     case "create":
-      const createSub = cleanArgs(args)[1];
-      if (FLAG_HELP || !createSub) {
-        cmdHelp("create");
-      } else if (createSub === "store") {
-        await cmdCreateStore();
-      } else if (createSub === "stripe") {
-        cmdCreateStripe();
-      } else if (createSub === "storefront") {
-        cmdCreateStorefront();
-      } else if (createSub === "recipe") {
-        output(
-          buildEnvelope("create recipe", {
-            status: "success",
-            summary: "Jolly starter recipe prepared.",
-            data: { recipe: "jolly-starter", path: "storefront/recipes/jolly-starter.yml" },
-            checks: [
-              { id: "create-recipe", status: "pass" as CheckStatus, description: "Recipe ready" },
-            ],
-          }),
-        );
-      } else if (createSub === "app-token") {
-        cmdCreateAppToken();
-      } else if (createSub === "deployment" || createSub === "deploy") {
-        output(
-          buildEnvelope("create deployment", {
-            status: "success",
-            summary: "Vercel deployment configured.",
-            data: { provider: "vercel" },
-            checks: [
-              { id: "create-deployment", status: "pass" as CheckStatus, description: "Deployment ready" },
-            ],
-          }),
-        );
-      } else {
-        errorExit(
-          buildEnvelope(`create ${createSub}`, {
-            status: "error",
-            summary: `Unknown create subcommand: ${createSub}`,
-            errors: [{ code: "UNKNOWN_SUBCOMMAND", message: `"${createSub}" is not a recognized create subcommand. Run jolly create --help for available subcommands.` }],
-          }),
-        );
-      }
-      break;
-
-    case "deploy":
-      output(
-        buildEnvelope("deploy", {
-          status: "success",
-          summary: "Vercel deployment configured.",
-          data: { provider: "vercel" },
-          checks: [
-            { id: "deploy", status: "pass" as CheckStatus, description: "Deployment ready" },
-          ],
-        }),
-      );
-      break;
-
+      return commandCreate(args);
+    case "init":
+      return commandInit(args);
     case "start":
-      cmdStart();
-      break;
-
+      return commandStart(args);
     case "doctor":
-      const doctorSub = cleanArgs(args)[1];
-      if (FLAG_HELP || !doctorSub) {
-        if (FLAG_HELP) {
-          cmdHelp("doctor");
-        } else {
-          cmdDoctor();
-        }
-      } else {
-        cmdDoctor(doctorSub);
-      }
-      break;
-
-    case "skills":
-      const skillsSub = cleanArgs(args)[1];
-      if (skillsSub === "install" || skillsSub === "update") {
-        cmdSkills(skillsSub);
-      } else {
-        cmdHelp("skills");
-      }
-      break;
-
+      return commandDoctor(args);
     case "upgrade":
-      cmdUpgrade();
-      break;
-
+      return commandUpgrade(args);
+    case "skills":
+      return commandSkills(args);
     default:
-      errorExit(
-        buildEnvelope(subcommand, {
-          status: "error",
-          summary: `Unknown command: ${subcommand}. Run jolly --help for available commands.`,
-          data: {},
-          errors: [{ code: "UNKNOWN_COMMAND", message: `"${subcommand}" is not a recognized command.` }],
-        }),
-      );
+      return errorEnvelope(cmd, `Unknown command "${cmd}".`, [
+        {
+          code: "UNKNOWN_COMMAND",
+          message: `"${cmd}" is not a Jolly command.`,
+          remediation: "Run `jolly help` to list available commands.",
+        },
+      ]);
+  }
+}
+
+async function main(): Promise<void> {
+  const args = parseArgs(process.argv.slice(2));
+  let env: Envelope;
+  try {
+    env = await dispatch(args);
+  } catch (err) {
+    env = errorEnvelope(args.positionals[0] ?? "jolly", "An unexpected error occurred.", [
+      {
+        code: "UNEXPECTED_ERROR",
+        message: err instanceof Error ? err.message : String(err),
+        remediation: "Re-run with --json and report the error code.",
+      },
+    ]);
   }
+  const exitCode = emit(env, args);
+  process.exit(exitCode);
 }
 
-main();
+void main();