@craftrpgs/cli 0.1.5 → 0.1.7

package/README.md

@@ -44,7 +44,6 @@ know how to work with the project the moment you open it.
 | `craft type new <Name>` | Author a new file type locally |
 | `craft image generate/upload` | Generate (including local or workspace reference images; opt-in in Settings) or upload images |
 | `craft image expressions/cutouts` | Preflight and persist character expression or cutout assets |
-| `craft env [name]` | Show or pin the environment for a directory |
 
 Every command takes `--json` for machine-readable output. Auth is via
 `craft login` (browser OAuth); credentials are stored locally and refreshed
@@ -52,16 +51,14 @@ automatically.
 
 Run `craft help <command>` for details on any of them.
 
-## Environments
+## Staying up to date
 
-The CLI talks to production (`craftrpgs.com`) by default. `craft env <name-or-url>`
-pins the current directory tree to another server via a one-line
-`.craft-env` file — handy for keeping a testing folder pointed at a dev
-server while the rest of your machine uses production. `--remote` and
-`CRAFT_REMOTE` accept an environment name or any origin URL. A cloned
-workspace always syncs with the server it was cloned from. (Craft
-developers: set `CRAFT_DEV=1` to enable the internal `local` and `staging`
-environment names.)
+The server only accepts the latest published version of the CLI. When a
+command is refused with a `cli_outdated` error, update and retry:
+
+```bash
+npm install -g @craftrpgs/cli@latest
+```
 
 ## Requirements
 

package/dist/bin.js

@@ -26773,6 +26773,7 @@ function truncateImageStyleInstructions(instructions) {
 function normalizeImageGenerationPrompt(prompt) {
   return truncateImageGenerationPrompt(prompt.trim());
 }
+var NON_DETAIL_KEYS = new Set(["name", "title", "description", "content"]);
 
 // ../shared/src/context-visibility.ts
 var CONTEXT_VISIBILITY_VALUES = [
@@ -26839,8 +26840,18 @@ function isAllowedImageUrl(value) {
     return false;
   }
 }
+var CHAT_ATTACHMENT_PATH_PREFIX = "/attachments/";
+function isChatAttachmentUrl(value) {
+  try {
+    return new URL(value).pathname.startsWith(CHAT_ATTACHMENT_PATH_PREFIX);
+  } catch {
+    return false;
+  }
+}
 var imageUrlSchema = exports_external.string().trim().min(1).max(2048).url().refine(isAllowedImageUrl, {
   message: "Image URL must use an approved media host."
+}).refine((value) => !isChatAttachmentUrl(value), {
+  message: "Chat attachments can't be saved as images. Upload the image instead."
 });
 
 // ../shared/src/validators/image-object.ts
@@ -26939,6 +26950,63 @@ var imageObjectSchema = exports_external.preprocess((input) => normalizeImageInp
   variations: exports_external.array(imageVariationSchema).max(MAX_FILE_TYPE_STATES).optional()
 }).strict());
 
+// ../shared/src/projects/first-steps.ts
+var FIRST_STEPS_VERSION = 1;
+var MAX_FIRST_STEPS_STEPS = 8;
+var MAX_FIRST_STEPS_WELCOME_LENGTH = 500;
+var MAX_FIRST_STEPS_STEP_TITLE_LENGTH = 80;
+var MAX_FIRST_STEPS_STEP_BODY_LENGTH = 300;
+var firstStepsStepIdSchema = exports_external.string().min(1).max(64);
+var firstStepsStepTitleSchema = exports_external.string().trim().min(1).max(MAX_FIRST_STEPS_STEP_TITLE_LENGTH);
+var firstStepsStepBodySchema = exports_external.string().trim().max(MAX_FIRST_STEPS_STEP_BODY_LENGTH);
+var firstStepsActionSchema = exports_external.discriminatedUnion("type", [
+  exports_external.object({
+    type: exports_external.literal("create-file"),
+    fileTypeSlug: exports_external.string().trim().min(1).max(120),
+    setAsRootMap: exports_external.boolean().optional()
+  }),
+  exports_external.object({
+    type: exports_external.literal("open-folder"),
+    folderPath: exports_external.string().trim().min(1).max(512)
+  }),
+  exports_external.object({
+    type: exports_external.literal("open-file"),
+    folderPath: exports_external.string().trim().max(512),
+    fileName: exports_external.string().trim().min(1).max(255)
+  }),
+  exports_external.object({
+    type: exports_external.literal("read-handbook"),
+    book: exports_external.enum(["player", "builder"]),
+    chapterId: exports_external.string().min(1).max(64).nullable().optional()
+  }),
+  exports_external.object({ type: exports_external.literal("open-assistant") }),
+  exports_external.object({ type: exports_external.literal("set-cover-image") }),
+  exports_external.object({ type: exports_external.literal("edit-overview") })
+]);
+var firstStepsStepSchema = exports_external.discriminatedUnion("kind", [
+  exports_external.object({
+    kind: exports_external.literal("action"),
+    id: firstStepsStepIdSchema,
+    title: firstStepsStepTitleSchema,
+    body: firstStepsStepBodySchema.optional(),
+    action: firstStepsActionSchema
+  }),
+  exports_external.object({
+    kind: exports_external.literal("info"),
+    id: firstStepsStepIdSchema,
+    title: firstStepsStepTitleSchema,
+    body: firstStepsStepBodySchema.optional()
+  })
+]);
+var firstStepsSchema = exports_external.object({
+  version: exports_external.literal(FIRST_STEPS_VERSION),
+  updatedAt: exports_external.string().max(40).optional(),
+  image: imageObjectSchema.nullable().optional(),
+  welcome: exports_external.string().trim().max(MAX_FIRST_STEPS_WELCOME_LENGTH).optional(),
+  steps: exports_external.array(firstStepsStepSchema).max(MAX_FIRST_STEPS_STEPS)
+});
+var RETIRED_ACTION_TYPES = new Set(["start-game"]);
+
 // ../shared/src/projects/manual.ts
 var MANUAL_VERSION = 1;
 var MAX_MANUAL_CHAPTERS = 50;
@@ -27045,7 +27113,8 @@ var projectImportProjectSettingsSchema = exports_external.object({
   gm: projectImportGameMasterSettingsSchema.optional(),
   preludeFlow: exports_external.unknown().nullable().optional(),
   playerHandbook: manualSchema.nullable().optional(),
-  builderManual: manualSchema.nullable().optional()
+  builderManual: manualSchema.nullable().optional(),
+  firstSteps: firstStepsSchema.nullable().optional()
 }).strict();
 var projectImportProjectSchema = exports_external.object({
   name: exports_external.string().trim().min(1),
@@ -27059,17 +27128,12 @@ var projectImportFileTypeDesignationSchema = exports_external.enum([
   "gm_instructions",
   "game_start"
 ]);
-var projectImportFileTypeCategorySchema = exports_external.enum([
-  "world",
-  "game_master",
-  "game_system"
-]);
 var projectImportFileTypeSchema = exports_external.object({
   key: projectImportKeySchema,
   name: exports_external.string().trim().min(1),
   contentType: exports_external.enum(["markdown", "json"]),
   designation: projectImportFileTypeDesignationSchema.nullable().optional(),
-  category: projectImportFileTypeCategorySchema.nullable().optional(),
+  category: exports_external.unknown().optional(),
   contextVisibility: exports_external.enum(CONTEXT_VISIBILITY_VALUES).optional(),
   agentEditable: exports_external.boolean().optional(),
   schema: projectImportJsonValueSchema.nullable().optional(),
@@ -27189,7 +27253,7 @@ var workspaceFileTypeFileSchema = exports_external.object({
   name: exports_external.string().min(1),
   contentType: exports_external.enum(["markdown", "json"]),
   designation: projectImportFileTypeDesignationSchema.nullable(),
-  category: exports_external.string().min(1).nullable().optional(),
+  category: exports_external.unknown().optional(),
   schemaHash: schemaHashSchema.optional(),
   schema: projectImportJsonValueSchema.nullable(),
   layout: projectImportJsonValueSchema.nullable(),
@@ -27307,7 +27371,7 @@ var cliPushCreateFileTypeOpSchema = exports_external.object({
   contentType: exports_external.enum(["markdown", "json"]),
   schema: projectImportJsonValueSchema.nullable().optional(),
   layout: projectImportJsonValueSchema.nullable().optional(),
-  category: exports_external.string().min(1).nullable().optional(),
+  category: exports_external.unknown().optional(),
   designation: projectImportFileTypeDesignationSchema.nullable().optional(),
   imageStyleInstructions: exports_external.string().transform(truncateImageStyleInstructions).nullable().optional(),
   showCoverImage: exports_external.boolean().optional(),
@@ -27740,6 +27804,12 @@ var cliFileRemoteStateSchema = exports_external.enum([
   "moved"
 ]);
 
+// ../shared/src/uuid.ts
+var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+  return UUID_REGEX.test(value);
+}
+
 // ../shared/src/expression/values.ts
 class ExpressionLambda {
   invoke;
@@ -28010,14 +28080,13 @@ var GLOBAL_BUILTINS_TABLE = {
     }
   }
 };
-var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function referenceIdFromValue(value) {
   if (typeof value === "string") {
-    return UUID_RE.test(value) ? value : null;
+    return isUuid(value) ? value : null;
   }
   if (isPlainObjectValue(value)) {
     const id = value.referenceId;
-    return typeof id === "string" && UUID_RE.test(id) ? id : null;
+    return typeof id === "string" && isUuid(id) ? id : null;
   }
   return null;
 }
@@ -35455,7 +35524,6 @@ var LOCKED_DESIGNATION_CONFIGS = {
   game_start: {
     name: "Game Start",
     contentType: "json",
-    category: "game_master",
     contextVisibility: "searchable",
     schemaMode: "base_fields_only",
     layoutMode: "none"
@@ -36009,7 +36077,6 @@ var extraTargetCandidatesCache = new WeakMap;
 
 // ../shared/src/cli/craft-block.ts
 var CRAFT_BLOCK_KEY = "$craft";
-var UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var KNOWN_BLOCK_KEYS = new Set(["referenceId", "settings", "metadata"]);
 var KNOWN_SETTINGS_KEYS = new Set([
   "contextVisibility",
@@ -36044,7 +36111,7 @@ function parseCraftBlockValue(value) {
     }
   }
   if (value.referenceId !== undefined) {
-    if (typeof value.referenceId === "string" && UUID_REGEX.test(value.referenceId)) {
+    if (typeof value.referenceId === "string" && isUuid(value.referenceId)) {
       block.referenceId = value.referenceId.toLowerCase();
     } else {
       warnings.push("$craft.referenceId is not a UUID — treated as absent (the file imports as id-less)");
@@ -37887,8 +37954,22 @@ var {
 } = shadcnComponentDefinitions;
 var roundedEnum = exports_external.nullable(exports_external.enum(["none", "sm", "md", "lg", "xl", "2xl", "full"]));
 var aspectRatioEnum = exports_external.nullable(exports_external.enum(["video", "square", "portrait", "tall", "ultrawide", "ultratall"]));
+var bgImageProp = exports_external.optional(exports_external.nullable(exports_external.string()));
+var bgImageFitEnum = exports_external.optional(exports_external.nullable(exports_external.enum(["cover", "contain", "tile", "tile-x", "tile-y"])));
+var BG_IMAGE_DOC = 'bgImage sets a background image URL (children render on top); bgImageFit controls how it fills: "cover" (default, crop to fill), "contain" (fit inside), "tile" / "tile-x" / "tile-y" (repeat at natural size for seamless textures).';
 var editPathProp = exports_external.optional(exports_external.nullable(exports_external.record(exports_external.string(), exports_external.string())));
 var EDIT_PATH_DOC = 'editPath redirects where an editable prop saves — e.g. editPath: { "value": "/resourceState/{key}/current" } writes there instead of the bound path, with {placeholders} filled from the current repeat item; this is how a control repeated over a computed (expression) array stays editable: display the computed row, write to the stored field.';
+var classNameProp = exports_external.optional(exports_external.nullable(exports_external.string()));
+function withClassNameProp(definition) {
+  const props = definition.props;
+  if (typeof props?.extend !== "function") {
+    return definition;
+  }
+  return {
+    ...definition,
+    props: props.extend({ className: classNameProp })
+  };
+}
 var extendedShadcnComponents = {
   Image: {
     props: exports_external.object({
@@ -37897,7 +37978,8 @@ var extendedShadcnComponents = {
       size: exports_external.nullable(exports_external.enum(["sm", "md", "lg", "full"])),
       align: exports_external.nullable(exports_external.enum(["left", "center", "right"])),
       aspectRatio: exports_external.optional(aspectRatioEnum),
-      stateKey: exports_external.optional(exports_external.nullable(exports_external.string()))
+      stateKey: exports_external.optional(exports_external.nullable(exports_external.string())),
+      className: classNameProp
     }),
     description: 'Image display with configurable size and alignment. size controls max width: sm (200px), md (400px), lg (600px), full (100%). align controls horizontal alignment: left, center, right. Defaults to full size, left aligned. aspectRatio crops the image to a fixed ratio: "video" (16:9), "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9), "ultratall" (9:32); omit to keep the natural ratio.',
     example: {
@@ -37915,11 +37997,13 @@ var extendedShadcnComponents = {
       justify: exports_external.nullable(exports_external.enum(["start", "center", "end", "between", "around"])),
       wrap: exports_external.nullable(exports_external.boolean()),
       bgColor: exports_external.nullable(exports_external.string()),
+      bgImage: bgImageProp,
+      bgImageFit: bgImageFitEnum,
       rounded: roundedEnum,
       className: exports_external.nullable(exports_external.string())
     }),
     slots: shadcnComponentDefinitions.Stack.slots,
-    description: "Flex layout container. bgColor sets background color (any CSS color value). Use className for extra Tailwind utilities (e.g. col-span-*, mt-4). Set wrap=true to allow line wrapping.",
+    description: `Flex layout container. bgColor sets background color (any CSS color value). ${BG_IMAGE_DOC} Use className for extra Tailwind utilities (e.g. col-span-*, mt-4). Set wrap=true to allow line wrapping.`,
     example: { direction: "vertical", gap: "md" }
   },
   Grid: {
@@ -37927,11 +38011,13 @@ var extendedShadcnComponents = {
       columns: exports_external.nullable(exports_external.number()),
       gap: exports_external.nullable(exports_external.enum(["sm", "md", "lg"])),
       bgColor: exports_external.nullable(exports_external.string()),
+      bgImage: bgImageProp,
+      bgImageFit: bgImageFitEnum,
       rounded: roundedEnum,
       className: exports_external.nullable(exports_external.string())
     }),
     slots: shadcnComponentDefinitions.Grid.slots,
-    description: "CSS grid layout. columns sets equal column count (supports 1-12). bgColor sets background color (any CSS color value). Use className for extra Tailwind utilities. Children can use className with col-span-* for responsive multi-column layouts.",
+    description: `CSS grid layout. columns sets equal column count (supports 1-12). bgColor sets background color (any CSS color value). ${BG_IMAGE_DOC} Use className for extra Tailwind utilities. Children can use className with col-span-* for responsive multi-column layouts.`,
     example: { columns: 2, gap: "md" }
   },
   Card: {
@@ -37941,12 +38027,14 @@ var extendedShadcnComponents = {
       maxWidth: exports_external.nullable(exports_external.enum(["sm", "md", "lg", "full"])),
       centered: exports_external.nullable(exports_external.boolean()),
       bgColor: exports_external.nullable(exports_external.string()),
+      bgImage: bgImageProp,
+      bgImageFit: bgImageFitEnum,
       borderColor: exports_external.nullable(exports_external.string()),
       rounded: roundedEnum,
       className: exports_external.nullable(exports_external.string())
     }),
     slots: shadcnComponentDefinitions.Card.slots,
-    description: "Container card with optional title/description. bgColor and borderColor accept any CSS color value. Use className for extra Tailwind utilities (e.g. col-span-*).",
+    description: `Container card with optional title/description. bgColor and borderColor accept any CSS color value. ${BG_IMAGE_DOC} Use className for extra Tailwind utilities (e.g. col-span-*).`,
     example: {
       title: "Character Stats",
       description: null
@@ -37956,7 +38044,8 @@ var extendedShadcnComponents = {
     props: exports_external.object({
       text: exports_external.string(),
       level: exports_external.nullable(exports_external.enum(["h1", "h2", "h3", "h4"])),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Section heading (h1–h4). Use color for custom text color (any CSS color value). Defaults to h2 if level is omitted.",
     example: { text: "Character Stats", level: "h3", color: "#ef4444" }
@@ -37966,6 +38055,7 @@ var extendedShadcnComponents = {
       text: exports_external.string(),
       variant: exports_external.nullable(exports_external.enum(["caption", "body", "muted", "lead", "code"])),
       color: exports_external.nullable(exports_external.string()),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Text paragraph with optional variant and custom color. Accepts any CSS color value. Bound text edits inline. ${EDIT_PATH_DOC}`,
@@ -37975,7 +38065,8 @@ var extendedShadcnComponents = {
     props: exports_external.object({
       text: exports_external.string(),
       variant: exports_external.nullable(exports_external.enum(["default", "secondary", "destructive", "outline"])),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Small inline badge/tag. When color is set (any CSS color value), it overrides the variant with a custom background color and auto-contrasted text.",
     example: { text: "Active", variant: "default", color: null }
@@ -37989,6 +38080,7 @@ var extendedShadcnComponents = {
       trackColor: exports_external.nullable(exports_external.string()),
       showValue: exports_external.nullable(exports_external.boolean()),
       stepper: exports_external.optional(exports_external.nullable(exports_external.boolean())),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Progress bar with optional label. color sets the indicator bar color, trackColor sets the background track color. showValue displays "value / max" text. stepper adds hover −/+ buttons that bump the bound value by 1 (clamped to 0..max) — prefer this over pairing a bar with a separate Stepper for the same field. All colors accept any CSS color value. ${EDIT_PATH_DOC}`,
@@ -38006,7 +38098,8 @@ var extendedShadcnComponents = {
       tabs: exports_external.array(exports_external.object({ label: exports_external.string(), value: exports_external.string() })),
       defaultValue: exports_external.nullable(exports_external.string()),
       value: exports_external.nullable(exports_external.string()),
-      bgColor: exports_external.nullable(exports_external.string())
+      bgColor: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     slots: _ShadcnTabs.slots,
     description: "Tab navigation. bgColor sets the tab list background color (any CSS color value).",
@@ -38023,6 +38116,10 @@ var referenceTargetSlugProps = {
   fileTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string())),
   pageTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string()))
 };
+var multiReferenceTargetSlugProps = {
+  ...referenceTargetSlugProps,
+  fileTypeSlugs: exports_external.optional(exports_external.nullable(exports_external.array(exports_external.string())))
+};
 var referenceValue = exports_external.union([
   exports_external.string(),
   exports_external.number(),
@@ -38035,7 +38132,7 @@ var referenceValue = exports_external.union([
 ]);
 var fileReferenceGridProps = exports_external.object({
   items: exports_external.array(exports_external.unknown()),
-  ...referenceTargetSlugProps,
+  ...multiReferenceTargetSlugProps,
   referenceField: exports_external.nullable(exports_external.string()),
   columns: exports_external.nullable(exports_external.number()),
   size: exports_external.nullable(exports_external.enum(["sm", "md", "lg"])),
@@ -38045,18 +38142,24 @@ var fileReferenceGridProps = exports_external.object({
   showAddNewOnHover: exports_external.optional(exports_external.nullable(exports_external.boolean())),
   addNewVariant: exports_external.optional(exports_external.nullable(exports_external.enum(["inline", "aside"]))),
   emptyState: exports_external.optional(exports_external.nullable(exports_external.string())),
+  titlePosition: exports_external.optional(exports_external.nullable(exports_external.enum(["bottom", "top", "overlay", "hidden"]))),
+  metadataPosition: exports_external.optional(exports_external.nullable(exports_external.enum(["inline", "below", "hidden"]))),
   metadataFields: exports_external.optional(exports_external.nullable(exports_external.array(exports_external.object({
     name: exports_external.string(),
     type: exports_external.enum(["string", "number", "boolean"]),
-    enum: exports_external.optional(exports_external.array(exports_external.string()))
-  }))))
+    enum: exports_external.optional(exports_external.array(exports_external.string())),
+    hidden: exports_external.optional(exports_external.nullable(exports_external.boolean())),
+    label: exports_external.optional(exports_external.nullable(exports_external.string()))
+  })))),
+  className: classNameProp
 });
 var craftComponents = {
   Checkbox: {
     props: exports_external.object({
       checked: exports_external.boolean(),
       label: exports_external.nullable(exports_external.string()),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Labeled checkbox for a boolean field. Bind checked to toggle it directly from the rendered view. color sets the checked box color (any CSS color value).",
     example: { checked: true, label: "Inspiration", color: null }
@@ -38065,7 +38168,8 @@ var craftComponents = {
     props: exports_external.object({
       checked: exports_external.boolean(),
       label: exports_external.nullable(exports_external.string()),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Labeled toggle switch for a boolean field — same data shape as Checkbox with a switch look. Bind checked to flip it directly from the rendered view. color sets the on-state color (any CSS color value).",
     example: { checked: true, label: "Concentrating", color: "#34d399" }
@@ -38080,7 +38184,8 @@ var craftComponents = {
       color: exports_external.nullable(exports_external.string()),
       emptyText: exports_external.nullable(exports_external.string()),
       showAddNew: exports_external.optional(exports_external.nullable(exports_external.boolean())),
-      showAddNewOnHover: exports_external.optional(exports_external.nullable(exports_external.boolean()))
+      showAddNewOnHover: exports_external.optional(exports_external.nullable(exports_external.boolean())),
+      className: classNameProp
     }),
     description: 'Plain list of values — traits, features, languages, rumors. items can be strings or objects (map object fields with labelField and descriptionField). variant "bullet" (default) and "numbered" stack items; "inline" flows them on one line joined by separator (default " · "). Bound string lists are editable inline. showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. color sets the item text color.',
     example: {
@@ -38103,7 +38208,8 @@ var craftComponents = {
       icon: exports_external.nullable(exports_external.string()),
       variant: exports_external.nullable(exports_external.enum(["quote", "panel"])),
       color: exports_external.nullable(exports_external.string()),
-      bgColor: exports_external.nullable(exports_external.string())
+      bgColor: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: 'Framed lore/flavor block. variant "quote" (default) renders italic text behind a left accent border with an optional em-dash attribution; "panel" renders a soft filled box with an optional icon and title. icon accepts any text/emoji (e.g. "\uD83D\uDCDC"). color tints the accent and title, bgColor sets the panel background.',
     example: {
@@ -38126,7 +38232,8 @@ var craftComponents = {
       color: exports_external.nullable(exports_external.string()),
       fileTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string())),
       fileTypeSlugs: exports_external.optional(exports_external.nullable(exports_external.array(exports_external.string()))),
-      pageTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string()))
+      pageTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string())),
+      className: classNameProp
     }),
     description: `Live value pulled from a referenced file — display another file type's data without copying it. Bind source to a reference field (single or list) and set field to the path to read from each referenced file's content (e.g. "acBonus", "stats.speed"); "$title"/"$name" read the file name. Multiple referenced files join with separator (default ", ") or render as chips with format "badge". Read-only — the value lives on the referenced file. Provide fileTypeSlug when the schema does not already annotate the reference field.`,
     example: {
@@ -38142,7 +38249,8 @@ var craftComponents = {
   Markdown: {
     props: exports_external.object({
       content: exports_external.string(),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Renders markdown text with prose styling. Supports bold, italic, code, links, and lists. Use color for custom text color.",
     example: {
@@ -38155,7 +38263,8 @@ var craftComponents = {
       items: exports_external.array(exports_external.tuple([exports_external.string(), exports_external.union([exports_external.string(), exports_external.number()])])),
       cols: exports_external.nullable(exports_external.number()),
       color: exports_external.nullable(exports_external.string()),
-      bgColor: exports_external.nullable(exports_external.string())
+      bgColor: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Grid of labeled stat values. Each item is a [label, value] tuple. Use color for value text color and bgColor for cell background color.",
     example: {
@@ -38180,7 +38289,8 @@ var craftComponents = {
       derivedLabel: exports_external.nullable(exports_external.string()),
       cols: exports_external.nullable(exports_external.number()),
       color: exports_external.nullable(exports_external.string()),
-      bgColor: exports_external.nullable(exports_external.string())
+      bgColor: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Grid of labeled stat cells that pair an editable base value with a derived/calculated value, such as ability score plus modifier.",
     example: {
@@ -38201,12 +38311,12 @@ var craftComponents = {
       options: exports_external.optional(exports_external.nullable(exports_external.array(exports_external.string()))),
       variant: exports_external.nullable(exports_external.enum(["default", "secondary", "outline", "destructive"])),
       color: exports_external.nullable(exports_external.string()),
-      fileTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string())),
-      pageTypeSlug: exports_external.optional(exports_external.nullable(exports_external.string())),
+      ...multiReferenceTargetSlugProps,
       showAddNew: exports_external.optional(exports_external.nullable(exports_external.boolean())),
-      showAddNewOnHover: exports_external.optional(exports_external.nullable(exports_external.boolean()))
+      showAddNewOnHover: exports_external.optional(exports_external.nullable(exports_external.boolean())),
+      className: classNameProp
     }),
-    description: "Wrapped row of badges. Use for tags, abilities, skills, etc. Provide options to show a preset add menu for fixed vocabularies. showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. When color is set, it overrides the variant with a custom background color. For compact reference arrays, provide fileTypeSlug so the rendered view can resolve names and add references with a picker.",
+    description: "Wrapped row of badges. Use for tags, abilities, skills, etc. Provide options to show a preset add menu for fixed vocabularies. showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. When color is set, it overrides the variant with a custom background color. For compact reference arrays, provide fileTypeSlug (or fileTypeSlugs when the field targets multiple file types) so the rendered view can resolve names and add references with a picker; fields whose schema already declares reference targets need no slug prop.",
     example: {
       items: ["Slash", "Block", "Charge"],
       options: ["Slash", "Block", "Charge", "Parry"],
@@ -38227,7 +38337,8 @@ var craftComponents = {
         field: exports_external.string()
       }))),
       showProgress: exports_external.nullable(exports_external.boolean()),
-      emptyText: exports_external.nullable(exports_external.string())
+      emptyText: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Read-only checklist for arrays of tasks or objectives. Items can be strings or objects. Use labelField, checkedField, and descriptionField to map object fields; metaFields renders extra badges.",
     example: {
@@ -38287,6 +38398,7 @@ var craftComponents = {
       emptyColor: exports_external.nullable(exports_external.string()),
       size: exports_external.nullable(exports_external.enum(["sm", "md", "lg"])),
       showValue: exports_external.nullable(exports_external.boolean()),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Row of filled/empty dots for small resource pools — spell slots, ki points, uses per rest, condition pips. Bind value to a number field; when the field is editable, clicking a dot sets the value (clicking the topmost filled dot clears it). max is the pool size (defaults to 5, capped at 25 dots) and can also bind to a field. color sets filled dots, emptyColor unfilled dots (any CSS color value). showValue displays "value / max" text. Values bound to expression fields render read-only unless editPath provides a stored write target. ${EDIT_PATH_DOC}`,
@@ -38310,6 +38422,7 @@ var craftComponents = {
       showMax: exports_external.nullable(exports_external.boolean()),
       color: exports_external.nullable(exports_external.string()),
       size: exports_external.nullable(exports_external.enum(["sm", "md", "lg"])),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Numeric counter with −/+ buttons for one-tap turn-time edits — hit points, ammo, sorcery points, momentum. Bind value to a number field; each tap saves immediately. min defaults to 0 (set a negative min to allow values below zero), max is uncapped when null and can bind to a field (e.g. {"$state": "/hitPointMax"}), step defaults to 1. showMax renders "23 / 40". The value is also click-to-type editable. ${EDIT_PATH_DOC}`,
@@ -38332,6 +38445,7 @@ var craftComponents = {
       onLabel: exports_external.nullable(exports_external.string()),
       offLabel: exports_external.nullable(exports_external.string()),
       color: exports_external.nullable(exports_external.string()),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Single boolean as a one-tap control — inspiration, concentration, death-save boxes, armor-used flags. Bind value to a boolean field; clicking flips and saves it. variant: "switch" (default), "checkbox", or "chip" (a lit/dim pill; onLabel/offLabel override the pill text per state). ${EDIT_PATH_DOC}`,
@@ -38355,6 +38469,7 @@ var craftComponents = {
       color: exports_external.nullable(exports_external.string()),
       size: exports_external.nullable(exports_external.enum(["sm", "md", "lg"])),
       showValue: exports_external.nullable(exports_external.boolean()),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Row of square boxes for health/stress/harm tracks. Two modes: bind value to a number field for a filled-count track (click box N to set, click the topmost filled box to clear), or bind states to a string-array field for multi-state tracks where clicking a box cycles empty → each stateOption → empty (e.g. World of Darkness bashing/lethal/aggravated). stateOptions is [{label, symbol}]; the stored array holds labels. boxes is the track length (default 10, cap 30). groupEvery adds a visual gap every N boxes (e.g. 3 for Blades stress). ${EDIT_PATH_DOC}`,
@@ -38386,7 +38501,8 @@ var craftComponents = {
         })
       ]))),
       label: exports_external.nullable(exports_external.string()),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Always-visible roster of toggle chips bound to a string-array field — conditions (poisoned, prone, grappled), exhaustion, status effects. Active chips are lit, inactive ones dim; clicking toggles membership and saves. Unlike BadgeList, the full option set stays visible for at-a-glance combat state. options entries are strings or {label, value?, color?}.",
     example: {
@@ -38405,6 +38521,7 @@ var craftComponents = {
       emptyColor: exports_external.nullable(exports_external.string()),
       size: exports_external.nullable(exports_external.enum(["sm", "md", "lg"])),
       showValue: exports_external.nullable(exports_external.boolean()),
+      className: classNameProp,
       editPath: editPathProp
     }),
     description: `Segmented circular progress clock (Blades in the Dark style) for project clocks, countdowns, and faction progress. Bind value to a number field; clicking a segment fills up to it, clicking the last filled segment clears it. segments is 2-12 (default 4). color fills segments, emptyColor the unfilled ones. ${EDIT_PATH_DOC}`,
@@ -38427,7 +38544,8 @@ var craftComponents = {
         type: exports_external.nullable(exports_external.enum(["string", "number", "boolean"]))
       })),
       label: exports_external.nullable(exports_external.string()),
-      emptyText: exports_external.nullable(exports_external.string())
+      emptyText: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: 'Table bound to an array of objects with declared columns — spell lists, inventories with quantity/weight, attack tables. Each column maps a field (dot paths supported, e.g. "item.name"); cells edit inline and save back to that row when the array is a stored field — rows of a computed (expression) array render read-only. Use type: "number" for numeric columns. For arrays of file references prefer FileReferenceGrid; DataTable is for structured plain-object rows.',
     example: {
@@ -38448,7 +38566,8 @@ var craftComponents = {
     props: exports_external.object({
       items: exports_external.array(exports_external.tuple([exports_external.string(), exports_external.string()])),
       labelColor: exports_external.nullable(exports_external.string()),
-      valueColor: exports_external.nullable(exports_external.string())
+      valueColor: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: "Vertical list of labeled field/value pairs. Use labelColor and valueColor for custom text colors.",
     example: {
@@ -38466,7 +38585,8 @@ var craftComponents = {
       src: exports_external.nullable(exports_external.string()),
       title: exports_external.nullable(exports_external.string()),
       subtitle: exports_external.nullable(exports_external.string()),
-      aspectRatio: aspectRatioEnum
+      aspectRatio: aspectRatioEnum,
+      className: classNameProp
     }),
     description: 'Hero image with optional text overlay. Always renders a gradient fallback when no image is set. aspectRatio defaults to "video" (16:9); also supports "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9) for slim banner rows, and "ultratall" (9:32) for narrow full-height columns.',
     example: {
@@ -38480,7 +38600,8 @@ var craftComponents = {
     props: exports_external.object({
       value: exports_external.union([exports_external.string(), exports_external.number()]),
       format: exports_external.nullable(exports_external.enum(["date", "relative", "distance"])),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: 'Formatted date display. "date" shows "April 29, 2024", "relative" shows "yesterday", "distance" shows "2 days ago". Use color for custom text color.',
     example: { value: 1714400000000, format: "distance", color: null }
@@ -38490,7 +38611,8 @@ var craftComponents = {
       value: exports_external.number(),
       style: exports_external.nullable(exports_external.enum(["decimal", "currency", "percent"])),
       currency: exports_external.nullable(exports_external.string()),
-      color: exports_external.nullable(exports_external.string())
+      color: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: 'Formatted number display. "decimal" shows "1,234.56", "currency" shows "$1,234.56", "percent" shows "85%". Use color for custom text color.',
     example: {
@@ -38509,9 +38631,10 @@ var craftComponents = {
         label: exports_external.string(),
         value: exports_external.union([exports_external.string(), exports_external.number()])
       }))),
-      ...referenceTargetSlugProps
+      ...multiReferenceTargetSlugProps,
+      className: classNameProp
     }),
-    description: "Dropdown select. Provide static options array, a fileTypeSlug to populate from files of that type, or both. value is the selected option's value or an object with referenceId plus a readable name.",
+    description: "Dropdown select. Provide static options array, a fileTypeSlug to populate from files of that type (or fileTypeSlugs when the field targets multiple file types), or both. value is the selected option's value or an object with referenceId plus a readable name. Fields whose schema already declares reference targets need no slug prop.",
     example: {
       value: "fighter",
       label: "Class",
@@ -38527,7 +38650,8 @@ var craftComponents = {
       value: exports_external.nullable(exports_external.string()),
       label: exports_external.nullable(exports_external.string()),
       placeholder: exports_external.nullable(exports_external.string()),
-      showLabel: exports_external.optional(exports_external.nullable(exports_external.boolean()))
+      showLabel: exports_external.optional(exports_external.nullable(exports_external.boolean())),
+      className: classNameProp
     }),
     description: 'Voice picker for character dialogue. Bind value to a string field with format "voice". A blank value inherits the GM voice, and the web renderer shows preview controls for each voice. showLabel defaults to true; set it false to hide the label.',
     example: {
@@ -38539,7 +38663,7 @@ var craftComponents = {
   },
   FileReferenceGrid: {
     props: fileReferenceGridProps,
-    description: 'Grid of cards showing referenced files with their images and titles. Provide items (array of file reference ids, slugs, names, reference objects, or objects), fileTypeSlug to identify the file type, and referenceField for object arrays (e.g. "item" for [{item: {referenceId, name}, quantity: 2}]). Metadata fields like quantity render as badges. emptyState customizes the full-width empty message and defaults to "None.". showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. addNewVariant defaults to "inline" and accepts "aside" to place one compact add control beside the grid label. imageAspectRatio overrides the card image ratio: "video" (16:9), "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9), "ultratall" (9:32, e.g. tall party-roster portraits).',
+    description: `Grid of cards showing referenced files with their images and titles. Provide items (array of file reference ids, slugs, names, reference objects, or objects), fileTypeSlug to identify the file type — or fileTypeSlugs listing every target type for multi-type reference fields (the add picker then offers per-type filtering and stores qualified "type/slug" values) — and referenceField for object arrays (e.g. "item" for [{item: {referenceId, name}, quantity: 2}]). Fields whose schema already declares reference targets need no slug prop. Metadata fields like quantity render as badges. titlePosition moves each card's name: "bottom" (default, below the image), "top" (above the image), "overlay" (over the lower edge of the image), or "hidden". metadataPosition moves the metadata badges: "inline" (default, beside the name), "below" (their own wrapping row under the name — fits longer text values), or "hidden". metadataFields entries accept hidden: true to keep a field editable in the card's edit dialog without displaying it, and label to rename it there; omitting a field from the list removes it from display, editing, and new-row defaults alike. emptyState customizes the full-width empty message and defaults to "None.". showAddNew defaults to true; set it false to hide the add control. showAddNewOnHover defaults to true; set it false to keep Add visible on desktop. addNewVariant defaults to "inline" and accepts "aside" to place one compact add control beside the grid label. imageAspectRatio overrides the card image ratio: "video" (16:9), "square" (1:1), "portrait" (3:4), "tall" (9:16), "ultrawide" (32:9), "ultratall" (9:32, e.g. tall party-roster portraits).`,
     example: {
       items: [
         {
@@ -38594,7 +38718,8 @@ var craftComponents = {
         display: exports_external.nullable(exports_external.enum(["bar", "fraction", "badges", "text"]))
       })),
       conditionsField: exports_external.nullable(exports_external.string()),
-      notesField: exports_external.nullable(exports_external.string())
+      notesField: exports_external.nullable(exports_external.string()),
+      className: classNameProp
     }),
     description: 'Turn order tracker for encounters/combat. Displays a sorted list of combatants with configurable stats. Each combatant has a "type" field: "character" (stats pulled live from a character page via "page" VFS path and pageFieldMapping) or "monster" (all stats inline — hp, maxHp, ac, etc. — with optional "statBlockPage" for reference only). pageFieldMapping maps combatant field names to character page content fields (e.g. {"hp": "hitPoints"}). Special values: "$title" for page title, "$coverImage" for page image. stats defines which columns to show.',
     example: {
@@ -38643,12 +38768,12 @@ var craftComponents = {
 };
 var craftCatalog = defineCatalog(schema, {
   components: {
-    Separator,
-    Accordion,
-    Collapsible,
-    Avatar,
-    Alert,
-    Table,
+    Separator: withClassNameProp(Separator),
+    Accordion: withClassNameProp(Accordion),
+    Collapsible: withClassNameProp(Collapsible),
+    Avatar: withClassNameProp(Avatar),
+    Alert: withClassNameProp(Alert),
+    Table: withClassNameProp(Table),
     ...extendedShadcnComponents,
     ...craftComponents
   },
@@ -40424,7 +40549,7 @@ function printLines(lines) {
 }
 
 // src/commands/check.ts
-var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 async function runCheck(argv) {
   const args = parseCommandArgs({
     argv,
@@ -40671,7 +40796,7 @@ function checkReferenceIds({
   const malformed = [];
   for (const file2 of scan.files) {
     const blockId = file2.craftBlock?.referenceId;
-    if (blockId !== undefined && !UUID_RE2.test(blockId)) {
+    if (blockId !== undefined && !UUID_RE.test(blockId)) {
       malformed.push(`${file2.path} ($craft.referenceId is not a UUID)`);
       continue;
     }
@@ -40907,7 +41032,7 @@ function isReferenceValue(record2) {
     return false;
   }
   if ("referenceId" in record2) {
-    return typeof record2.referenceId === "string" && UUID_RE2.test(record2.referenceId);
+    return typeof record2.referenceId === "string" && UUID_RE.test(record2.referenceId);
   }
   return nonBlankString(record2.slug);
 }
@@ -41900,7 +42025,7 @@ function describeRemoteSource(resolved) {
 // package.json
 var package_default = {
   name: "@craftrpgs/cli",
-  version: "0.1.5",
+  version: "0.1.7",
   description: "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   license: "UNLICENSED",
   homepage: "https://craftrpgs.com",
@@ -41927,7 +42052,7 @@ var package_default = {
     "@craft/flow": "workspace:*",
     "@craft/shared": "workspace:*",
     fflate: "^0.8.3",
-    typescript: "5.9.3",
+    typescript: "7.0.2",
     uuid: "11.1.0",
     zod: "4.3.6"
   }
@@ -42039,6 +42164,16 @@ function createCliClient({
     if (response.status === 401) {
       throw new CliError(UNAUTHORIZED_HELP, 2);
     }
+    if (response.status === 426) {
+      const { code, message, details } = await readErrorBody(response);
+      throw new CliApiError({
+        message,
+        code: code ?? "cli_outdated",
+        status: response.status,
+        exitCode: 2,
+        details
+      });
+    }
     return response;
   }
   async function parseJson(response, schema2, what) {
@@ -43835,9 +43970,10 @@ var SYSTEM_ACCOUNT_IDS = new Set(Object.values(SYSTEM_ACCOUNTS));
 import { randomUUID } from "node:crypto";
 var LEADING_SLASH_RE = /^\//;
 var CONTENT_EXTENSION_RE = /\.(json|md)$/i;
-var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE2 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function entryName(entry) {
-  const base = (entry.path.split("/").at(-1) ?? entry.path).replace(CONTENT_EXTENSION_RE, "");
+  const livePath = entry.movedTo ?? entry.path;
+  const base = (livePath.split("/").at(-1) ?? livePath).replace(CONTENT_EXTENSION_RE, "");
   const suffix = `.${entry.fileType}`;
   return base.endsWith(suffix) ? base.slice(0, -suffix.length) : base;
 }
@@ -43870,8 +44006,12 @@ function resolveLink({
   if (!trimmed) {
     return { status: "unknown" };
   }
-  const fromEntry = (entry) => entry.fileId ? { status: "resolved", referenceId: entry.referenceId } : { status: "unpushed" };
-  if (UUID_RE3.test(trimmed)) {
+  const fromEntry = (entry) => entry.fileId ? {
+    status: "resolved",
+    referenceId: entry.referenceId,
+    name: entryName(entry)
+  } : { status: "unpushed" };
+  if (UUID_RE2.test(trimmed)) {
     const lowered = trimmed.toLowerCase();
     const byReference = ledger.files.find((entry) => entry.referenceId.toLowerCase() === lowered);
     if (byReference) {
@@ -43889,6 +44029,13 @@ function resolveLink({
   if (bySlug) {
     return fromEntry(bySlug);
   }
+  const nameKey = generateSlug(trimmed.replace(/^<@|>$/g, ""));
+  if (nameKey) {
+    const byName = ledger.files.find((entry) => generateSlug(entryName(entry)) === nameKey);
+    if (byName) {
+      return fromEntry(byName);
+    }
+  }
   return { status: "unknown" };
 }
 function referenceIdToPath({
@@ -44222,7 +44369,7 @@ async function runImageGenerate(argv) {
     styleLine = "Style: none stored — set settings.imageStyleInstructions in .craft/project.json for consistent art.";
   }
   printLines([
-    `Generated image (${result.model}, ${result.size ?? "default size"}, ${result.unitsSpent} ${result.currency}):`,
+    `Generated image (${result.model}, ${result.size ?? "default size"}, ${toDisplay(result.unitsSpent)} ${result.currency}):`,
     `  ${result.image.url ?? "<no url returned>"}`,
     styleLine,
     "",
@@ -44263,7 +44410,7 @@ function toActionableError(error48, operation = "generation") {
     if (currency === "credits") {
       return actionable("Not enough credits to generate this image. Buy credits in Craft, then retry.", 1);
     }
-    return actionable("Not enough energy to generate this image. Wait for your daily energy to refill, " + "or retry with --credits to spend purchased credits instead.", 1);
+    return actionable("Not enough energy to generate this image. Retry with --credits to spend " + "purchased credits, or subscribe in Craft for a daily energy allowance.", 2);
   }
   if (error48.code === "validation_error" && error48.status === 422) {
     return actionable(`The provider refused this generation: ${error48.message}. ` + "Adjust the prompt (or reference images) and retry.", 1);
@@ -44935,6 +45082,8 @@ var FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V6 = "file-designation-metadata:v6"
 var FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V7 = "file-designation-metadata:v7";
 var FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V8 = "file-designation-metadata:v8";
 var GAME_START_OPENING_MAX_LENGTH = 1e4;
+var GAME_START_MAX_OPENING_BEATS = 50;
+var GAME_START_MAX_CHARACTER_OPENINGS = 100;
 var GM_INSTRUCTION_TRIGGER_PHASES = [
   "post_player_message",
   "post_gm_message"
@@ -45137,10 +45286,25 @@ var GmInstructionMetadataSchema = exports_external.union([
   GmInstructionToolMetadataSchema,
   GmInstructionNarrativeMetadataSchema
 ]);
+var GameStartOpeningBeatSpeakerSchema = exports_external.discriminatedUnion("kind", [
+  exports_external.object({ kind: exports_external.literal("gm") }),
+  exports_external.object({
+    kind: exports_external.literal("character"),
+    fileReferenceId: exports_external.string().uuid(),
+    name: exports_external.string().trim().max(200).optional()
+  })
+]);
+var GameStartOpeningBeatSchema = exports_external.object({
+  id: exports_external.string().uuid(),
+  speaker: GameStartOpeningBeatSpeakerSchema,
+  text: exports_external.string().trim().min(1).max(GAME_START_OPENING_MAX_LENGTH),
+  expression: exports_external.string().trim().max(80).nullish()
+});
 var GameStartOpeningSchema = exports_external.discriminatedUnion("kind", [
   exports_external.object({
     kind: exports_external.literal("static"),
-    message: exports_external.string().trim().min(1).max(GAME_START_OPENING_MAX_LENGTH)
+    message: exports_external.string().trim().min(1).max(GAME_START_OPENING_MAX_LENGTH),
+    beats: exports_external.array(GameStartOpeningBeatSchema).max(GAME_START_MAX_OPENING_BEATS).optional()
   }),
   exports_external.object({
     kind: exports_external.literal("dynamic"),
@@ -45150,16 +45314,55 @@ var GameStartOpeningSchema = exports_external.discriminatedUnion("kind", [
 var GameStartCharacterSchema = exports_external.object({
   fileReferenceId: exports_external.string().uuid()
 });
-var GameStartMetadataSchema = exports_external.object({
+var GameStartCharacterOpeningSchema = exports_external.object({
+  characterFileReferenceId: exports_external.string().uuid(),
+  opening: GameStartOpeningSchema
+});
+function combinedOpeningLength(opening) {
+  if (opening.kind !== "static" || !opening.beats) {
+    return 0;
+  }
+  return opening.beats.reduce((total, beat) => total + beat.text.length, 0);
+}
+var GameStartMetadataObjectSchema = exports_external.object({
   startingLocationFileReferenceId: exports_external.string().uuid().nullable().optional(),
   startingCharacters: exports_external.array(GameStartCharacterSchema).default([]),
   opening: GameStartOpeningSchema.default({
     kind: "static",
     message: "Welcome to the game. What would you like to do first?"
   }),
+  characterOpenings: exports_external.array(GameStartCharacterOpeningSchema).max(GAME_START_MAX_CHARACTER_OPENINGS).default([]),
   displayOrder: exports_external.number().int().default(0),
   openingInstructions: exports_external.string().max(GAME_START_OPENING_MAX_LENGTH).default("")
 });
+var GameStartMetadataSchema = GameStartMetadataObjectSchema.superRefine((metadata, ctx) => {
+  if (combinedOpeningLength(metadata.opening) > GAME_START_OPENING_MAX_LENGTH) {
+    ctx.addIssue({
+      code: "custom",
+      path: ["opening", "beats"],
+      message: `Combined opening beats must be at most ${GAME_START_OPENING_MAX_LENGTH} characters.`
+    });
+  }
+  const seenCharacterReferenceIds = new Set;
+  metadata.characterOpenings.forEach((characterOpening, index) => {
+    const referenceId = characterOpening.characterFileReferenceId.toLowerCase();
+    if (seenCharacterReferenceIds.has(referenceId)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["characterOpenings", index, "characterFileReferenceId"],
+        message: "Each character can only have one opening override."
+      });
+    }
+    seenCharacterReferenceIds.add(referenceId);
+    if (combinedOpeningLength(characterOpening.opening) > GAME_START_OPENING_MAX_LENGTH) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["characterOpenings", index, "opening", "beats"],
+        message: `Combined opening beats must be at most ${GAME_START_OPENING_MAX_LENGTH} characters.`
+      });
+    }
+  });
+});
 var FileDesignationMetadataV1Schema = exports_external.object({
   schemaVersionId: exports_external.literal(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V1).default(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V1),
   map: MapDataV1Schema.optional(),
@@ -45604,6 +45807,123 @@ ${remedies.join(`
 
 // src/commands/meta.ts
 import { readFile as readFile11 } from "node:fs/promises";
+
+// ../shared/src/game-starts/authoring.ts
+function speakerNameForLink(link) {
+  const base = link.split("/").filter(Boolean).at(-1);
+  const name = base?.split(".")[0]?.trim();
+  return name || undefined;
+}
+function isRecord14(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function translateOpening(opening, where, resolveLink2) {
+  if (!isRecord14(opening)) {
+    return opening;
+  }
+  const openingInput = { ...opening };
+  if (!Array.isArray(openingInput.beats)) {
+    return openingInput;
+  }
+  const beats = openingInput.beats.map((beat, index) => {
+    if (!isRecord14(beat)) {
+      return beat;
+    }
+    const beatInput = { ...beat };
+    if (typeof beatInput.id !== "string") {
+      beatInput.id = crypto.randomUUID();
+    }
+    const speaker = beatInput.speaker;
+    const context = {
+      where: `${where}.beats[${index}].speaker`,
+      expects: "character"
+    };
+    if (speaker === "gm") {
+      beatInput.speaker = { kind: "gm" };
+    } else if (typeof speaker === "string") {
+      const resolved = resolveLink2(speaker, context);
+      beatInput.speaker = {
+        kind: "character",
+        fileReferenceId: resolved?.referenceId ?? null,
+        name: resolved?.name ?? speakerNameForLink(speaker)
+      };
+    } else if (isRecord14(speaker) && "character" in speaker) {
+      const { character, ...speakerRest } = speaker;
+      const resolved = resolveLink2(character, {
+        ...context,
+        where: `${context.where}.character`
+      });
+      beatInput.speaker = {
+        kind: "character",
+        name: resolved?.name ?? (typeof character === "string" ? speakerNameForLink(character) : undefined),
+        ...speakerRest,
+        fileReferenceId: resolved?.referenceId ?? null
+      };
+    }
+    return beatInput;
+  });
+  openingInput.beats = beats;
+  if (typeof openingInput.message !== "string" && openingInput.kind === "static") {
+    const projectable = beats.filter((beat) => isRecord14(beat) && typeof beat.text === "string");
+    openingInput.message = projectable.map((beat) => {
+      const speaker = isRecord14(beat.speaker) ? beat.speaker : undefined;
+      const name = speaker && speaker.kind === "character" && typeof speaker.name === "string" ? speaker.name : null;
+      return name ? `${name}: ${beat.text}` : beat.text;
+    }).join(`
+
+`).slice(0, GAME_START_OPENING_MAX_LENGTH);
+  }
+  return openingInput;
+}
+function translateGameStartAuthoringInput({
+  raw,
+  resolveLink: resolveLink2
+}) {
+  const input = { ...raw };
+  if ("startingLocation" in input) {
+    input.startingLocationFileReferenceId = resolveLink2(input.startingLocation, {
+      where: "startingLocation",
+      expects: "location"
+    })?.referenceId ?? null;
+    input.startingLocation = undefined;
+  }
+  if (Array.isArray(input.startingCharacters)) {
+    input.startingCharacters = input.startingCharacters.map((character, index) => {
+      if (typeof character === "string") {
+        return {
+          fileReferenceId: resolveLink2(character, {
+            where: `startingCharacters[${index}]`,
+            expects: "character"
+          })?.referenceId ?? null
+        };
+      }
+      return character;
+    });
+  }
+  if ("opening" in input) {
+    input.opening = translateOpening(input.opening, "opening", resolveLink2);
+  }
+  if (Array.isArray(input.characterOpenings)) {
+    input.characterOpenings = input.characterOpenings.map((characterOpening, index) => {
+      if (!isRecord14(characterOpening)) {
+        return characterOpening;
+      }
+      const entry = { ...characterOpening };
+      if ("character" in entry) {
+        entry.characterFileReferenceId = resolveLink2(entry.character, {
+          where: `characterOpenings[${index}].character`,
+          expects: "character"
+        })?.referenceId ?? null;
+        entry.character = undefined;
+      }
+      entry.opening = translateOpening(entry.opening, `characterOpenings[${index}].opening`, resolveLink2);
+      return entry;
+    });
+  }
+  return input;
+}
+
+// src/commands/meta.ts
 var META_USAGE = `Usage: craft meta get <path> [--json]
 ` + `       craft meta set-game-start <game-start-path> --file <json>
 ` + `       craft meta set-gm-trigger <gm-instruction-path> (--file <json> | --clear)
@@ -45669,7 +45989,12 @@ async function runMetaGet(argv) {
   const gameStart = parsed?.gameStart ? {
     ...parsed.gameStart,
     startingLocation: pathForReference(workspace, parsed.gameStart.startingLocationFileReferenceId),
-    startingCharacters: parsed.gameStart.startingCharacters.map((character) => pathForReference(workspace, character.fileReferenceId) ?? character.fileReferenceId)
+    startingCharacters: parsed.gameStart.startingCharacters.map((character) => pathForReference(workspace, character.fileReferenceId) ?? character.fileReferenceId),
+    opening: projectOpeningForOutput(workspace, parsed.gameStart.opening),
+    characterOpenings: parsed.gameStart.characterOpenings.map((characterOpening) => ({
+      character: pathForReference(workspace, characterOpening.characterFileReferenceId) ?? characterOpening.characterFileReferenceId,
+      opening: projectOpeningForOutput(workspace, characterOpening.opening)
+    }))
   } : null;
   if (gameStart) {
     gameStart.startingLocationFileReferenceId = undefined;
@@ -45690,46 +46015,47 @@ async function runMetaGet(argv) {
   });
   return 0;
 }
+function projectOpeningForOutput(workspace, opening) {
+  if (opening.kind !== "static" || !opening.beats?.length) {
+    return opening;
+  }
+  return {
+    kind: "static",
+    beats: opening.beats.map((beat) => ({
+      speaker: beat.speaker.kind === "gm" ? "gm" : pathForReference(workspace, beat.speaker.fileReferenceId) ?? beat.speaker.fileReferenceId,
+      text: beat.text,
+      ...beat.expression ? { expression: beat.expression } : {}
+    }))
+  };
+}
 function translateGameStartInput(workspace, raw) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new CliError("The game start JSON must be a single object.", 2);
   }
-  const input = { ...raw };
   const failures = [];
-  const resolve6 = (link, where) => {
-    if (link === null || link === undefined) {
-      return null;
-    }
-    if (typeof link !== "string") {
-      failures.push(`${where}: expected a path/slug string`);
+  const input = translateGameStartAuthoringInput({
+    raw: { ...raw },
+    resolveLink: (link, { where }) => {
+      if (link === null || link === undefined) {
+        return null;
+      }
+      if (typeof link !== "string") {
+        failures.push(`${where}: expected a path/slug string`);
+        return null;
+      }
+      const resolution = resolveLink({ ledger: workspace.ledger, link });
+      if (resolution.status === "resolved") {
+        return { referenceId: resolution.referenceId, name: resolution.name };
+      }
+      failures.push(resolution.status === "unpushed" ? `${where}: "${link}" has not been pushed yet — push it first` : `${where}: "${link}" does not resolve to a tracked file`);
       return null;
     }
-    const resolution = resolveLink({ ledger: workspace.ledger, link });
-    if (resolution.status === "resolved") {
-      return resolution.referenceId;
-    }
-    failures.push(resolution.status === "unpushed" ? `${where}: "${link}" has not been pushed yet — push it first` : `${where}: "${link}" does not resolve to a tracked file`);
-    return null;
-  };
-  if ("startingLocation" in input) {
-    input.startingLocationFileReferenceId = resolve6(input.startingLocation, "startingLocation");
-    input.startingLocation = undefined;
-  }
-  if (Array.isArray(input.startingCharacters)) {
-    input.startingCharacters = input.startingCharacters.map((character, index) => {
-      if (typeof character === "string") {
-        return {
-          fileReferenceId: resolve6(character, `startingCharacters[${index}]`)
-        };
-      }
-      return character;
-    });
-  }
+  });
   if (failures.length > 0) {
     throw new CliError(`Nothing was saved — some references do not resolve to pushed files:
 ` + `${failures.map((f) => `  ${f}`).join(`
 `)}
-` + "Use workspace paths, slug.type tokens, or referenceIds of PUSHED files.", 2);
+` + "Use workspace paths (preferred), slug.type tokens, slugs, or file names of PUSHED files.", 2);
   }
   return input;
 }
@@ -46056,7 +46382,7 @@ function escapeRegExp(value) {
 // src/commands/project-completeness.ts
 var TRIVIAL_DESCRIPTION_LENGTH = 40;
 var CROSS_LINK_FILE_THRESHOLD = 5;
-var UUID_RE4 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+var UUID_RE3 = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 var SCRATCH_NAME_RE = /\b(?:test|asdf|scratch|repro|tmp|todo|example)\b/i;
 async function runProjectCompleteness(argv) {
   const args = parseCommandArgs({
@@ -46422,7 +46748,7 @@ function isReferenceValue2(record2) {
     return false;
   }
   if ("referenceId" in record2) {
-    return typeof record2.referenceId === "string" && UUID_RE4.test(record2.referenceId);
+    return typeof record2.referenceId === "string" && UUID_RE3.test(record2.referenceId);
   }
   return nonBlankString(record2.slug);
 }
@@ -46828,7 +47154,7 @@ async function removeStaleManagedSkills({
 // src/engine/pull.ts
 import { mkdir as mkdir6, rename as rename4, rm as rm7, rmdir } from "node:fs/promises";
 import { dirname as dirname7 } from "node:path";
-function isRecord14(value) {
+function isRecord15(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function serializeContentForDisk({
@@ -46841,9 +47167,9 @@ function serializeContentForDisk({
   const craftBlock = referenceId ? craftBlockForEmbedding({
     referenceId,
     ...settings ? { settings } : {},
-    ...isRecord14(metadata) ? { metadata } : {}
+    ...isRecord15(metadata) ? { metadata } : {}
   }) : null;
-  if (contentType === "markdown" && isRecord14(content)) {
+  if (contentType === "markdown" && isRecord15(content)) {
     return serializeMarkdown({
       name: typeof content.name === "string" ? content.name : undefined,
       description: typeof content.description === "string" ? content.description : undefined,
@@ -46851,7 +47177,7 @@ function serializeContentForDisk({
       content: typeof content.content === "string" ? content.content : ""
     }, { craftBlock });
   }
-  if (craftBlock && isRecord14(content)) {
+  if (craftBlock && isRecord15(content)) {
     return `${JSON.stringify({
       [CRAFT_BLOCK_KEY]: craftBlock,
       ...stripCraftBlock(content)
@@ -46866,7 +47192,7 @@ function contentTypeForPath2(path) {
 }
 function applyMetaBase(entry, body) {
   entry.settings = craftFileSettingsFromWire(body.settings);
-  entry.metadataHash = isRecord14(body.metadata) ? hashCanonicalJson(body.metadata) : undefined;
+  entry.metadataHash = isRecord15(body.metadata) ? hashCanonicalJson(body.metadata) : undefined;
 }
 function emptyResult() {
   return {
@@ -47755,7 +48081,7 @@ import { join as join7 } from "node:path";
 
 // src/engine/plan.ts
 var MAX_CLI_PUSH_OPS = 500;
-function isRecord15(value) {
+function isRecord16(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 var PATHSPEC_LEADING_DOT_SLASH = /^\.\//;
@@ -47876,7 +48202,6 @@ function buildPushPlan(input) {
         contentType: local.contentType,
         schema: local.schema,
         ...local.layout != null ? { layout: local.layout } : {},
-        ...local.category !== undefined ? { category: local.category } : {},
         designation: local.designation,
         ...local.imageStyleInstructions !== undefined ? { imageStyleInstructions: local.imageStyleInstructions } : {},
         ...local.showCoverImage !== undefined ? { showCoverImage: local.showCoverImage } : {},
@@ -47940,7 +48265,7 @@ function buildPushPlan(input) {
       continue;
     }
     let content = scanned.content;
-    if (isRecord15(content) && content.name !== newBaseName.value.baseName) {
+    if (isRecord16(content) && content.name !== newBaseName.value.baseName) {
       content = { ...content, name: newBaseName.value.baseName };
       nameRewrites.push({
         diskPath: toPath,
@@ -50080,7 +50405,7 @@ async function workspaceRemote2() {
 
 // src/commands/type.ts
 import { existsSync as existsSync9 } from "node:fs";
-var TYPE_USAGE = "Usage: craft type new <Name> [--markdown] [--designation <token>] [--category <token>]";
+var TYPE_USAGE = "Usage: craft type new <Name> [--markdown] [--designation <token>]";
 var STARTER_JSON_SCHEMA = {
   type: "object",
   properties: {},
@@ -50099,7 +50424,6 @@ async function runTypeNew(argv) {
     flags: {
       markdown: { type: "boolean" },
       designation: { type: "string" },
-      category: { type: "string" },
       json: { type: "boolean" }
     },
     maxPositionals: 1
@@ -50131,7 +50455,6 @@ async function runTypeNew(argv) {
     name,
     contentType,
     designation,
-    category: stringFlag(args, "category") ?? null,
     schema: contentType === "json" ? STARTER_JSON_SCHEMA : null,
     layout: null,
     imageStyleInstructions: null,
@@ -50145,7 +50468,7 @@ async function runTypeNew(argv) {
     `Create files of the type as <Anything>.${typeSlugExtension} anywhere in the workspace.`,
     "Push the new type and its files together with `craft push --include-types`."
   ] : [
-    `Markdown types need no schema — edit ${typeFilePath} only if you want a designation or category.`,
+    `Markdown types need no schema — edit ${typeFilePath} only if you want a designation.`,
     `Create files of the type as <Anything>.${typeSlugExtension} anywhere in the workspace.`,
     "Push the new type and its files together with `craft push --include-types`."
   ];
@@ -50287,7 +50610,7 @@ var HELP_COMMAND_LINES = `  clone <projectIdOrUrl> [dir]   Download a project as
   resolve <path>                 Mark a conflict resolved \u2014 your version wins
   checkout <path>                Take the remote version of a conflicted file
   mv <from> <to>                 Rename/move a file, keeping its identity
-  type new <Name> [--markdown] [--designation <t>] [--category <t>]
+  type new <Name> [--markdown] [--designation <t>]
                                  Author a new file type locally (push with --include-types)
   voices [--language <code>] [--gender <t>] [--age <t>]
                                  List voice ids and traits for characters and the GM
@@ -50548,7 +50871,7 @@ Rename/move a file while keeping its identity (history, references). The
 move is recorded in the ledger and pushed as a move op on the next
 \`craft push\`; editing the file's content before pushing is fine.
 `,
-  type: `Usage: craft type new <Name> [--markdown] [--designation <token>] [--category <token>]
+  type: `Usage: craft type new <Name> [--markdown] [--designation <token>]
 
 Scaffold a new file type at .craft/file-types/<slug>.json. Edit its schema,
 create files as <Anything>.<slug>.json, then push everything together with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftrpgs/cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   "license": "UNLICENSED",
   "homepage": "https://craftrpgs.com",
@@ -24,10 +24,10 @@
     "typecheck": "tsc --noEmit"
   },
   "devDependencies": {
-    "@craft/flow": "workspace:*",
-    "@craft/shared": "workspace:*",
+    "@craft/flow": "0.0.1",
+    "@craft/shared": "0.0.1",
     "fflate": "^0.8.3",
-    "typescript": "5.9.3",
+    "typescript": "7.0.2",
     "uuid": "11.1.0",
     "zod": "4.3.6"
   }