@craftrpgs/cli 0.1.3 → 0.1.5

package/README.md

@@ -7,7 +7,8 @@ back — git-style, with three-way sync and conflict handling.
 ```sh
 npm install -g @craftrpgs/cli
 craft login
-craft create "My World"
+craft systems                                # browse published game systems
+craft create "My World" --system "Ashes RPG" # build on one (--blank starts from scratch)
 cd my-world
 # edit files, then:
 craft status
@@ -28,9 +29,10 @@ know how to work with the project the moment you open it.
 | Command | What it does |
 |---|---|
 | `craft login` / `logout` | Browser sign-in (credentials stored per server) |
-| `craft create <name>` | Create a new project and clone it |
+| `craft create <name>` | Create a new project and clone it (`--system <id\|name>` builds on a published system; `--blank` starts from scratch) |
 | `craft clone <idOrUrl>` | Download a project as a local workspace |
 | `craft projects` | List projects your account owns |
+| `craft systems [query]` | Browse published game systems to build on (featured + community) |
 | `craft status` / `diff` | Show local changes (add `--remote` for drift) |
 | `craft check` | Validate the workspace locally (the same checks the server runs at push) |
 | `craft project-completeness` | Worldbuilding completeness report (recommendations; always exits 0) |

package/dist/bin.js

@@ -26939,6 +26939,22 @@ var imageObjectSchema = exports_external.preprocess((input) => normalizeImageInp
   variations: exports_external.array(imageVariationSchema).max(MAX_FILE_TYPE_STATES).optional()
 }).strict());
 
+// ../shared/src/projects/manual.ts
+var MANUAL_VERSION = 1;
+var MAX_MANUAL_CHAPTERS = 50;
+var MAX_MANUAL_TITLE_LENGTH = 120;
+var MAX_MANUAL_CONTENT_LENGTH = 1e5;
+var manualChapterSchema = exports_external.object({
+  id: exports_external.string().min(1).max(64),
+  title: exports_external.string().trim().min(1).max(MAX_MANUAL_TITLE_LENGTH),
+  content: exports_external.string().max(MAX_MANUAL_CONTENT_LENGTH)
+});
+var manualSchema = exports_external.object({
+  version: exports_external.literal(MANUAL_VERSION),
+  updatedAt: exports_external.string().max(40).optional(),
+  chapters: exports_external.array(manualChapterSchema).max(MAX_MANUAL_CHAPTERS)
+});
+
 // ../shared/src/projects/project-import.ts
 var projectImportJsonValueSchema = exports_external.lazy(() => exports_external.union([
   exports_external.string(),
@@ -27027,7 +27043,9 @@ var projectImportProjectSettingsSchema = exports_external.object({
   gmToolSettings: gmToolSettingsInputSchema.optional(),
   rootMapFileReferenceId: exports_external.string().uuid().nullable().optional(),
   gm: projectImportGameMasterSettingsSchema.optional(),
-  preludeFlow: exports_external.unknown().nullable().optional()
+  preludeFlow: exports_external.unknown().nullable().optional(),
+  playerHandbook: manualSchema.nullable().optional(),
+  builderManual: manualSchema.nullable().optional()
 }).strict();
 var projectImportProjectSchema = exports_external.object({
   name: exports_external.string().trim().min(1),
@@ -27609,8 +27627,11 @@ var cliImageVariationsResponseSchema = exports_external.object({
 var cliCreateProjectRequestSchema = exports_external.object({
   name: exports_external.string().min(1).max(200),
   description: exports_external.string().max(2000).optional(),
-  seedStarterContent: exports_external.boolean().optional()
-}).strict();
+  seedStarterContent: exports_external.boolean().optional(),
+  systemProjectId: uuidSchema.optional()
+}).strict().refine((value) => !(value.systemProjectId && value.seedStarterContent !== undefined), {
+  message: "seedStarterContent does not apply when creating from a system — the system supplies the content"
+});
 var cliCreateProjectResponseSchema = exports_external.object({
   projectId: uuidSchema,
   containerId: uuidSchema
@@ -27626,6 +27647,26 @@ var cliProjectSummarySchema = exports_external.object({
 var cliProjectsListResponseSchema = exports_external.object({
   projects: exports_external.array(cliProjectSummarySchema)
 }).strict();
+var cliSystemSummarySchema = exports_external.object({
+  projectId: uuidSchema,
+  name: exports_external.string(),
+  description: exports_external.string().nullable(),
+  gameSystemName: exports_external.string().nullable(),
+  ownerUsername: exports_external.string().nullable(),
+  official: exports_external.boolean(),
+  featured: exports_external.boolean(),
+  tags: exports_external.array(exports_external.string()),
+  fileTypeNames: exports_external.array(exports_external.string()),
+  fileCount: exports_external.number().int().nonnegative().nullable(),
+  likeCount: exports_external.number().int().nonnegative(),
+  cloneCount: exports_external.number().int().nonnegative(),
+  publishedAt: exports_external.string().nullable()
+}).strict();
+var cliSystemsResponseSchema = exports_external.object({
+  featured: exports_external.array(cliSystemSummarySchema),
+  community: exports_external.array(cliSystemSummarySchema),
+  communityNextCursor: exports_external.string().nullable()
+}).strict();
 var cliFileVersionEntrySchema = exports_external.object({
   versionId: uuidSchema,
   createdAt: exports_external.string(),
@@ -41859,7 +41900,7 @@ function describeRemoteSource(resolved) {
 // package.json
 var package_default = {
   name: "@craftrpgs/cli",
-  version: "0.1.3",
+  version: "0.1.5",
   description: "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   license: "UNLICENSED",
   homepage: "https://craftrpgs.com",
@@ -42044,6 +42085,30 @@ function createCliClient({
       }
       return parseJson(response, cliCreateProjectResponseSchema, "create project");
     },
+    async fetchSystems({ q, tags, cursor, limit } = {}) {
+      const params = new URLSearchParams;
+      if (q) {
+        params.set("q", q);
+      }
+      for (const tag of tags ?? []) {
+        params.append("tags", tag);
+      }
+      if (cursor) {
+        params.set("cursor", cursor);
+      }
+      if (limit !== undefined) {
+        params.set("limit", String(limit));
+      }
+      const query = params.size > 0 ? `?${params.toString()}` : "";
+      const response = await request(`/api/projects/cli/systems${query}`);
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        throw new CliError(`Listing systems failed: ${await readErrorMessage(response)}`, 1);
+      }
+      return parseJson(response, cliSystemsResponseSchema, "systems");
+    },
     async listProjects() {
       const response = await request("/api/projects/cli/list");
       if (!response.ok) {
@@ -42397,6 +42462,7 @@ async function runClone(argv) {
 
 // src/commands/create.ts
 import { basename } from "node:path";
+import { createInterface } from "node:readline/promises";
 
 // src/commands/clone.ts
 import { existsSync as existsSync5 } from "node:fs";
@@ -42501,6 +42567,11 @@ async function downloadAndUnpackSnapshot2({
 
 // src/commands/create.ts
 var DIRECTORY_NAME_SEPARATORS = /[-_\s]+/;
+var UUID_IN_TEXT2 = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+var DIGITS_ONLY = /^\d+$/;
+var MAX_SYSTEM_MATCHES_SHOWN = 8;
+var NAME_RESOLUTION_PAGE_SIZE = 48;
+var NAME_RESOLUTION_MAX_PAGES = 10;
 function projectNameFromDirectory(dirName) {
   return dirName.split(DIRECTORY_NAME_SEPARATORS).filter((word) => word.length > 0).map((word) => (word[0]?.toUpperCase() ?? "") + word.slice(1)).join(" ");
 }
@@ -42509,6 +42580,8 @@ async function runCreate(argv) {
     argv,
     flags: {
       description: { type: "string" },
+      system: { type: "string" },
+      blank: { type: "boolean" },
       empty: { type: "boolean" },
       remote: { type: "string" },
       json: { type: "boolean" }
@@ -42517,11 +42590,16 @@ async function runCreate(argv) {
   });
   const [nameArg, dirPositional] = args.positionals;
   if (!nameArg) {
-    throw new CliError('Usage: craft create <name> [dir] — quote names with spaces, e.g. craft create "My World" (or `craft create .` to create here, named after this directory)', 2);
+    throw new CliError('Usage: craft create <name> [dir] [--system <id|name> | --blank] — quote names with spaces, e.g. craft create "My World" (or `craft create .` to create here, named after this directory)', 2);
   }
   if (nameArg === "." && dirPositional !== undefined) {
     throw new CliError('`craft create .` takes no [dir] — "." already means "create in the current directory, named after it". To pick the name yourself: craft create "My Name" .', 2);
   }
+  const systemArg = stringFlag(args, "system");
+  const wantsBlank = args.booleans.has("blank") || args.booleans.has("empty");
+  if (systemArg && wantsBlank) {
+    throw new CliError("--system cannot combine with --blank/--empty — a project either builds on a system or starts from scratch.", 2);
+  }
   const namedAfterCwd = nameArg === ".";
   const name = namedAfterCwd ? projectNameFromDirectory(basename(process.cwd())) : nameArg;
   if (!name) {
@@ -42537,14 +42615,25 @@ async function runCreate(argv) {
       loginHint: silentDefaultHint(resolved)
     })
   });
-  const description = stringFlag(args, "description");
-  const created = await client.createProject({
-    request: {
-      name,
-      ...description ? { description } : {},
-      ...args.booleans.has("empty") ? { seedStarterContent: false } : {}
-    }
+  const base = await resolveCreateBase({
+    client,
+    systemArg,
+    wantsBlank,
+    name,
+    nameArg,
+    interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY && !args.booleans.has("json"))
   });
+  const description = stringFlag(args, "description");
+  const request = { name };
+  if (description) {
+    request.description = description;
+  }
+  if (base.kind === "system") {
+    request.systemProjectId = base.systemProjectId;
+  } else {
+    request.seedStarterContent = false;
+  }
+  const created = await client.createProject({ request });
   const { targetDir, fileCount } = await downloadAndUnpackSnapshot2({
     client,
     projectId: created.projectId,
@@ -42557,11 +42646,13 @@ async function runCreate(argv) {
       name,
       remote,
       dir: targetDir,
-      files: fileCount
+      files: fileCount,
+      system: base.kind === "system" ? { projectId: base.systemProjectId, name: base.systemName } : null
     });
   } else {
+    const fromSystem = base.kind === "system" ? ` from system ${base.systemName ? `"${base.systemName}" ` : ""}(${base.systemProjectId})` : "";
     printLines([
-      `Created project "${name}" (${created.projectId}) on ${remote} ` + `(${describeRemoteSource(resolved)}).`,
+      `Created project "${name}" (${created.projectId}) on ${remote} ` + `(${describeRemoteSource(resolved)})${fromSystem}.`,
       ...namedAfterCwd ? [
         'Named after the current directory — `craft create "My Name" .` picks the name yourself.'
       ] : [],
@@ -42571,6 +42662,165 @@ async function runCreate(argv) {
   }
   return 0;
 }
+async function resolveCreateBase({
+  client,
+  systemArg,
+  wantsBlank,
+  name,
+  nameArg,
+  interactive
+}) {
+  if (systemArg) {
+    return await resolveSystemArg({ client, value: systemArg });
+  }
+  if (wantsBlank) {
+    return { kind: "blank" };
+  }
+  const catalog = await client.fetchSystems();
+  const featured = catalog?.featured ?? [];
+  if (featured.length === 0) {
+    return { kind: "blank" };
+  }
+  if (!interactive) {
+    throw new CliError(pickBaseGuidance({ nameArg, featured }), 2);
+  }
+  return await promptForBase({ name, featured });
+}
+async function resolveSystemArg({
+  client,
+  value
+}) {
+  const id = extractProjectId(value);
+  if (id) {
+    return { kind: "system", systemProjectId: id, systemName: null };
+  }
+  const catalog = await client.fetchSystems({
+    q: value,
+    limit: NAME_RESOLUTION_PAGE_SIZE
+  });
+  if (!catalog) {
+    throw new CliError("This server does not support creating from a system yet — update the server, or omit --system.", 1);
+  }
+  const candidates = [...catalog.featured, ...catalog.community];
+  let cursor = catalog.communityNextCursor;
+  for (let page = 1;cursor && page < NAME_RESOLUTION_MAX_PAGES; page += 1) {
+    const next = await client.fetchSystems({
+      q: value,
+      cursor,
+      limit: NAME_RESOLUTION_PAGE_SIZE
+    });
+    if (!next) {
+      break;
+    }
+    candidates.push(...next.community);
+    cursor = next.communityNextCursor;
+  }
+  const exact = candidates.filter((system) => system.name.toLowerCase() === value.toLowerCase());
+  const pool = exact.length > 0 ? exact : candidates;
+  const [only] = pool;
+  if (only && pool.length === 1) {
+    return {
+      kind: "system",
+      systemProjectId: only.projectId,
+      systemName: only.name
+    };
+  }
+  if (pool.length === 0) {
+    throw new CliError(`No published system matches "${value}" — browse the catalog with \`craft systems\`, then pass a name or id.`, 2);
+  }
+  throw new CliError([
+    `"${value}" matches ${pool.length} published systems — pass the id instead:`,
+    ...pool.slice(0, MAX_SYSTEM_MATCHES_SHOWN).map((system) => `  ${systemChoiceLabel(system)}  ${system.projectId}`)
+  ].join(`
+`), 2);
+}
+function extractProjectId(value) {
+  const matches = value.match(UUID_IN_TEXT2);
+  return matches?.at(-1)?.toLowerCase() ?? null;
+}
+function systemChoiceLabel(system) {
+  const parts = [
+    system.name,
+    system.gameSystemName ? `— ${system.gameSystemName}` : null,
+    system.ownerUsername ? `by ${system.ownerUsername}` : null,
+    system.official ? "(official)" : null
+  ];
+  return parts.filter((part) => Boolean(part)).join(" ");
+}
+function pickBaseGuidance({
+  nameArg,
+  featured
+}) {
+  const quoted = nameArg !== "." && nameArg.includes(" ") ? `"${nameArg}"` : nameArg;
+  return [
+    "Pick a base for the new project — new projects usually build on a published system:",
+    `  craft create ${quoted} --system <id|name>   # build on a system`,
+    `  craft create ${quoted} --blank              # start from scratch (an empty project)`,
+    "",
+    "Featured systems:",
+    ...featured.map((system) => `  ${systemChoiceLabel(system)}  ${system.projectId}`),
+    "",
+    "Browse or search the full catalog with `craft systems`."
+  ].join(`
+`);
+}
+function parseBaseAnswer(answer, featured) {
+  const trimmed = answer.trim();
+  const lowered = trimmed.toLowerCase();
+  if (lowered === "q" || lowered === "quit") {
+    return "quit";
+  }
+  if (lowered === "b" || lowered === "blank") {
+    return { kind: "blank" };
+  }
+  if (DIGITS_ONLY.test(trimmed)) {
+    const chosen = featured[Number.parseInt(trimmed, 10) - 1];
+    return chosen ? {
+      kind: "system",
+      systemProjectId: chosen.projectId,
+      systemName: chosen.name
+    } : "invalid";
+  }
+  const id = extractProjectId(trimmed);
+  if (id) {
+    const known = featured.find((system) => system.projectId === id);
+    return {
+      kind: "system",
+      systemProjectId: id,
+      systemName: known?.name ?? null
+    };
+  }
+  return "invalid";
+}
+async function promptForBase({
+  name,
+  featured
+}) {
+  printLines([
+    `Choose a base for "${name}" — new projects usually build on a system:`,
+    ...featured.map((system, index) => `  ${index + 1}) ${systemChoiceLabel(system)}`),
+    "  b) Blank project (empty — author your own file types)",
+    "More systems: `craft systems`, then rerun with --system <id|name>."
+  ]);
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (;; ) {
+      const answer = await rl.question(`Pick 1-${featured.length}, b for blank, or q to cancel: `);
+      const choice = parseBaseAnswer(answer, featured);
+      if (choice === "quit") {
+        throw new CliError("Cancelled — nothing was created.", 2);
+      }
+      if (choice !== "invalid") {
+        return choice;
+      }
+      printLines([
+        `Enter a number between 1 and ${featured.length}, a system id, b, or q.`
+      ]);
+    }
+  } finally {
+    rl.close();
+  }
+}
 // ../../node_modules/.bun/uuid@11.1.0/node_modules/uuid/dist/esm/rng.js
 import { randomFillSync } from "crypto";
 var rnds8Pool = new Uint8Array(256);
@@ -49696,6 +49946,138 @@ function renderStatus(status, openConflicts = []) {
   return lines;
 }
 
+// src/commands/systems.ts
+var MAX_NAME_WIDTH = 40;
+var MAX_BLURB_LENGTH = 100;
+async function runSystems(argv) {
+  const args = parseCommandArgs({
+    argv,
+    flags: {
+      tag: { type: "string", repeatable: true },
+      community: { type: "boolean" },
+      cursor: { type: "string" },
+      limit: { type: "string" },
+      remote: { type: "string" },
+      json: { type: "boolean" }
+    },
+    maxPositionals: 1
+  });
+  const [query] = args.positionals;
+  const tags = args.strings.get("tag") ?? [];
+  const cursor = stringFlag(args, "cursor");
+  const limit = parseLimit(stringFlag(args, "limit"));
+  const pinned = await workspaceRemote2();
+  const resolved = resolveRemote({
+    flagRemote: stringFlag(args, "remote"),
+    context: pinned ? { remote: pinned, source: "workspace" } : null
+  });
+  const remote = resolved.remote;
+  const client = createCliClient({
+    remote,
+    auth: await resolveTokenProvider({
+      remote,
+      loginHint: silentDefaultHint(resolved)
+    })
+  });
+  const catalog = await client.fetchSystems({
+    ...query ? { q: query } : {},
+    ...tags.length > 0 ? { tags } : {},
+    ...cursor ? { cursor } : {},
+    ...limit !== undefined ? { limit } : {}
+  });
+  if (!catalog) {
+    throw new CliError("This server does not support browsing systems from the CLI yet — update the server, or browse systems in the Craft app.", 1);
+  }
+  if (args.booleans.has("json")) {
+    printJson({
+      remote,
+      featured: catalog.featured.map(withIsoPublishedAt),
+      community: catalog.community.map(withIsoPublishedAt),
+      communityNextCursor: catalog.communityNextCursor
+    });
+    return 0;
+  }
+  const isFiltered = Boolean(query) || tags.length > 0;
+  const showFeatured = !(args.booleans.has("community") || cursor);
+  const featured = showFeatured ? catalog.featured : [];
+  const lines = [];
+  if (featured.length > 0) {
+    lines.push(`${featured.length} featured system(s) on ${remote}:`, ...systemLines(featured), "");
+  }
+  if (catalog.community.length > 0) {
+    const label = isFiltered ? `matching community system(s) on ${remote}` : `community system(s) on ${remote}, newest first`;
+    lines.push(`${catalog.community.length} ${label}:`, ...systemLines(catalog.community));
+    if (catalog.communityNextCursor) {
+      lines.push(`  …more: craft systems --community --cursor ${catalog.communityNextCursor}`);
+    }
+    lines.push("");
+  }
+  if (featured.length === 0 && catalog.community.length === 0) {
+    printLines([
+      isFiltered ? `No published systems match${query ? ` "${query}"` : ""}${tags.length > 0 ? ` (tags: ${tags.join(", ")})` : ""} on ${remote}.` : `No published systems on ${remote} yet.`
+    ]);
+    return 0;
+  }
+  lines.push('Start a project from one: craft create "My World" --system <id|name>');
+  if (!isFiltered) {
+    lines.push("Search: craft systems <query> — narrow by tag with --tag <tag>.");
+  }
+  printLines(lines);
+  return 0;
+}
+function parseLimit(raw) {
+  if (raw === undefined) {
+    return;
+  }
+  const limit = Number.parseInt(raw, 10);
+  if (!Number.isFinite(limit) || limit < 1) {
+    throw new CliError(`--limit must be a positive number, got "${raw}"`, 2);
+  }
+  return limit;
+}
+function withIsoPublishedAt(system) {
+  return {
+    ...system,
+    publishedAt: system.publishedAt ? toIsoTimestamp(system.publishedAt) : null
+  };
+}
+function systemLines(systems) {
+  const nameWidth = Math.min(MAX_NAME_WIDTH, Math.max(...systems.map((system) => system.name.length)));
+  return systems.flatMap((system) => {
+    const name = system.name.length > MAX_NAME_WIDTH ? `${system.name.slice(0, MAX_NAME_WIDTH - 1)}…` : system.name.padEnd(nameWidth);
+    const details = [
+      system.gameSystemName,
+      system.ownerUsername ? `by ${system.ownerUsername}` : null,
+      system.official ? "official" : null,
+      `${system.fileCount ?? 0} files`,
+      `${system.cloneCount} clones`,
+      system.tags.length > 0 ? `tags: ${system.tags.join(", ")}` : null
+    ].filter((part) => Boolean(part)).join(" · ");
+    const lines = [`  ${name}  ${system.projectId}  ${details}`];
+    const blurb = descriptionBlurb(system.description);
+    if (blurb) {
+      lines.push(`      ${blurb}`);
+    }
+    return lines;
+  });
+}
+function descriptionBlurb(description) {
+  const firstLine = description?.trim().split(`
+`, 1)[0]?.trim();
+  if (!firstLine) {
+    return null;
+  }
+  return firstLine.length > MAX_BLURB_LENGTH ? `${firstLine.slice(0, MAX_BLURB_LENGTH - 1)}…` : firstLine;
+}
+async function workspaceRemote2() {
+  try {
+    const workspace = await loadWorkspaceContext();
+    return workspace.config.remote;
+  } catch {
+    return null;
+  }
+}
+
 // src/commands/type.ts
 import { existsSync as existsSync9 } from "node:fs";
 var TYPE_USAGE = "Usage: craft type new <Name> [--markdown] [--designation <token>] [--category <token>]";
@@ -49874,11 +50256,15 @@ var AUTH_COMMAND_LINES_DEV = `  login [--remote <env|origin>]  Sign in with your
 `;
 var HELP_COMMAND_LINES = `  clone <projectIdOrUrl> [dir]   Download a project as a local workspace
                                  ([dir] may be "." for the current directory)
-  create <name> [dir] [--description "..."] [--empty]
-                                 Create a new project and clone it locally:
-                                 craft create "My World" .   \u2192 current directory
-                                 craft create .              \u2192 here, named after the dir
-                                 (--empty skips the starter file types)
+  create <name> [dir] [--system <id|name> | --blank] [--description "..."]
+                                 Create a new project and clone it locally,
+                                 built on a published system (--system) or
+                                 empty (--blank). Run with neither to pick
+                                 from the featured systems.
+                                 craft create . \u2192 here, named after the dir
+  systems [query] [--tag <t>] [--community] [--limit <n>]
+                                 Browse published game systems to build on
+                                 (curated featured row + community catalog)
   projects                       List the projects your account owns
   log <path> [--limit <n>]       Show a file's version history (newest first)
   status [--remote] [--full]     Show local changes (and remote drift with --remote;
@@ -49968,28 +50354,51 @@ Examples:
   craft clone <id> my-dir       # into ./my-dir/
   craft clone <id> .            # into the current directory
 `,
-  create: `Usage: craft create <name> [dir] [--description "..."] [--empty]
+  create: `Usage: craft create <name> [dir] [--system <id|name> | --blank] [--description "..."]
        craft create .           (create here, named after the current directory)
 
 Create a new project on the server and clone it into [dir] (defaults to a
 new folder named after the project; "." uses the current directory \u2014
 pre-existing dotfiles like .git/ are fine).
 
+New projects usually build on a published game system \u2014 a project shipping
+file types, rules content, and GM instructions to start from:
+
+  --system <id|name>  clone that system as your starting point
+                      (browse them with \`craft systems\`)
+  --blank             start with an empty project \u2014 no file types, no
+                      content; author your own with \`craft type new\` and
+                      push them with --include-types (--empty is an older
+                      alias)
+
+With neither, an interactive run offers the featured systems as a picker;
+scripts and agents must pass --system or --blank explicitly.
+
 Examples:
-  craft create "My World"           # creates ./my-world/
-  craft create "My World" my-dir    # creates ./my-dir/
-  craft create "My World" .         # into the current directory
-  craft create .                    # here, named after the directory
-
-By default the project seeds the standard starter file types (Character,
-Location, Equipment, Game Start, GM Instructions) plus example files \u2014
-generic fantasy-flavored; you may retool them. --empty skips all of that so
-you author every file type yourself (see \`craft type new\`).
+  craft create "My World" --system "Ashes RPG"  # build on a system
+  craft create "My World" --blank               # creates ./my-world/
+  craft create "My World" my-dir --blank        # creates ./my-dir/
+  craft create "My World" . --blank             # into the current directory
+  craft create . --blank                        # here, named after the dir
 `,
   projects: `Usage: craft projects
 
 List every project your account owns (name, id, last update, file count) \u2014
 newest activity first. Clone one with \`craft clone <projectId>\`.
+`,
+  systems: `Usage: craft systems [query] [--tag <tag>]... [--community] [--limit <n>] [--json]
+
+Browse published game systems \u2014 projects that ship file types, rules
+content, and GM instructions for other projects to build on. The featured
+row is curated; everything else is the community catalog, newest publish
+first.
+
+[query] matches name, system label, description, and author. --tag keeps
+only systems carrying every given tag (repeatable). --community lists the
+community catalog alone. Long listings page with --cursor <cursor>, printed
+at the end of each page (--json carries it as communityNextCursor).
+
+Start a project from a system: craft create "My World" --system <id|name>.
 `,
   log: `Usage: craft log <path> [--limit <n>]
 
@@ -50094,12 +50503,19 @@ content. File type changes from the zip apply only with --include-types
 (missing types are created, drifted types updated \u2014 the server revalidates
 existing files against schema changes). Project settings changes from the
 zip's .craft/project.json apply only with --include-settings; without it,
-differing settings are listed but left untouched.
+differing settings are listed but left untouched. Every field of
+project.json is diffed and applied individually: name, description, tags,
+and settings.* \u2014 theme, image, projectIcon, attribution, gameSystemName,
+headlineLabel, headline, body, authorsNotes, gallery, galleryLayout,
+isClonable, hideHeroTitle, imageStyleInstructions, autoImageGeneration,
+defaultImageModel, gmToolSettings, rootMapFileReferenceId, preludeFlow, gm,
+playerHandbook, builderManual.
 
 --dry-run shows the full plan without writing. --exclude <referenceId>
 skips individual rows from the plan (repeatable, or comma-separated; get the
 ids from a --dry-run --json plan). --exclude-setting <key> vetoes a single
-settings change (e.g. settings.preludeFlow). Runs inside the target
+settings change, named exactly as the plan's rows are keyed (e.g.
+settings.preludeFlow, settings.playerHandbook). Runs inside the target
 project's workspace, or anywhere with --project <projectId>. The apply is
 one atomic batch: on any per-file failure (409) nothing is written and every
 failure is listed. Exits 1 while conflicts or failures remain.
@@ -50257,7 +50673,7 @@ Examples:
   craft clone <id> my-dir       # into ./my-dir/
   craft clone <id> .            # into the current directory
 `,
-  create: `Usage: craft create <name> [dir] [--description "..."] [--empty]
+  create: `Usage: craft create <name> [dir] [--system <id|name> | --blank] [--description "..."]
        craft create .           (create here, named after the current directory)
 
 Create a new project on the server and clone it into [dir] (defaults to a
@@ -50265,16 +50681,17 @@ new folder named after the project; "." uses the current directory \u2014
 pre-existing dotfiles like .git/ are fine). Targets the current
 environment \u2014 check with \`craft env\`.
 
+New projects usually build on a published game system: --system <id|name>
+clones one as the starting point (browse with \`craft systems\`), --blank
+starts with an empty project (no file types; --empty is an older alias).
+With neither, an interactive run offers the featured systems as a picker;
+scripts and agents must pass --system or --blank explicitly.
+
 Examples:
-  craft create "My World"           # creates ./my-world/
-  craft create "My World" my-dir    # creates ./my-dir/
-  craft create "My World" .         # into the current directory
-  craft create .                    # here, named after the directory
-
-By default the project seeds the standard starter file types (Character,
-Location, Equipment, Game Start, GM Instructions) plus example files \u2014
-generic fantasy-flavored; you may retool them. --empty skips all of that so
-you author every file type yourself (see \`craft type new\`).
+  craft create "My World" --system "Ashes RPG"  # build on a system
+  craft create "My World" --blank               # creates ./my-world/
+  craft create "My World" my-dir --blank        # creates ./my-dir/
+  craft create . --blank                        # here, named after the dir
 `,
   projects: `Usage: craft projects
 
@@ -50282,6 +50699,21 @@ List every project your account owns (name, id, last update, file count) \u2014
 newest activity first. Uses the current workspace's remote when run inside
 one; otherwise the current environment (see \`craft help env\`). Clone one
 with \`craft clone <projectId>\`.
+`,
+  systems: `Usage: craft systems [query] [--tag <tag>]... [--community] [--limit <n>] [--json]
+
+Browse published game systems \u2014 projects that ship file types, rules
+content, and GM instructions for other projects to build on. The featured
+row is curated; everything else is the community catalog, newest publish
+first. Uses the current workspace's remote when run inside one; otherwise
+the current environment (see \`craft help env\`).
+
+[query] matches name, system label, description, and author. --tag keeps
+only systems carrying every given tag (repeatable). --community lists the
+community catalog alone. Long listings page with --cursor <cursor>, printed
+at the end of each page (--json carries it as communityNextCursor).
+
+Start a project from a system: craft create "My World" --system <id|name>.
 `
 };
 function commandHelp(topic) {
@@ -50297,6 +50729,7 @@ var COMMANDS = {
   clone: runClone,
   create: runCreate,
   projects: runProjects,
+  systems: runSystems,
   log: runLog,
   status: runStatus,
   check: runCheck,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftrpgs/cli",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   "license": "UNLICENSED",
   "homepage": "https://craftrpgs.com",