@craftrpgs/cli 0.2.0-alpha.0 → 0.2.0-alpha.1

package/dist/bin.js

@@ -26899,6 +26899,7 @@ End each reply on something concrete in front of the player's character that the
 ];
 var RESPONSE_LENGTH = "Response length";
 var ROLL_NUMBERS = "Roll numbers in narration";
+var LONG_TRAVEL = "Long-distance travel";
 var PLATFORM_OPTIONS = [
   {
     revision: 3,
@@ -26984,6 +26985,46 @@ var PLATFORM_OPTIONS = [
         }
       ]
     }
+  },
+  {
+    revision: 1,
+    option: {
+      key: "platform-long-distance-travel",
+      label: LONG_TRAVEL,
+      description: "What happens when the party travels somewhere far away.",
+      kind: "one",
+      default: ["up-to-gm"],
+      choices: [
+        {
+          key: "up-to-gm",
+          label: "Up to the GM",
+          description: "The Game Master decides when the road is worth playing.",
+          instructions: []
+        },
+        {
+          key: "fast-travel",
+          label: "Fast travel",
+          description: "Skip ahead to the destination, with the trip summed up.",
+          instructions: [
+            {
+              when: "always",
+              body: `When the party travels somewhere far (a trip of hours or more), take them straight there in the same reply: record it as arriving ("Move Kael and Mira to Harrowmere"), never "set out for", sum up the trip in a sentence or two (how long it took, how the way went), and go on from the arrival. When the player set out from the map, tell the arrival the same way.`
+            }
+          ]
+        },
+        {
+          key: "journey",
+          label: "Journey",
+          description: "Travel there step by step, with the road played out.",
+          instructions: [
+            {
+              when: "always",
+              body: `When the party travels somewhere far (a trip of hours or more), play it as a journey to where the player said they are going. Set out first ("Kael and Mira set out for Harrowmere by the coast road; it takes about three days"), then tell the way in stages over several replies, for as long as the distance really takes: the road and the weather, rests and camps, people and trouble met on the way, with time passing as it would ("It is now dusk"). The party stays on the way the whole time: a camp or a rest is told with the time it takes, never a move to a camp or a stretch of road. Someone met stops the journey where they meet; when the party goes on from there, record it as "Kael and Mira set out again for Harrowmere", never as a move farther along the road. Keep heading for the place the player named unless they change course, and record the arrival ("Move Kael and Mira to Harrowmere") only once the way has been travelled. When the player set out from the map, they are already on the way: go on with the journey.`
+            }
+          ]
+        }
+      ]
+    }
   }
 ];
 
@@ -41012,6 +41053,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 FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V9 = "file-designation-metadata:v9";
+var FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V10 = "file-designation-metadata:v10";
+var FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V11 = "file-designation-metadata:v11";
 var GAME_START_OPENING_MAX_LENGTH = 1e4;
 var GAME_START_MAX_OPENING_BEATS = 50;
 var GAME_START_MAX_CHARACTER_OPENINGS = 100;
@@ -41212,6 +41255,142 @@ var MapDataV6Schema = MapDataV5Schema.extend({
 var MapDataV8Schema = MapDataV6Schema.extend({
   grid: MapGridSchema.nullable().default(null)
 });
+var MAP_EXIT_KINDS = [
+  "door",
+  "gate",
+  "stairs",
+  "ladder",
+  "hatch",
+  "path",
+  "road",
+  "dock",
+  "portal",
+  "other"
+];
+var MAP_EXIT_DIRECTIONS = [
+  "up",
+  "down",
+  "in",
+  "out",
+  "through"
+];
+var MapExitSchema = exports_external.object({
+  kind: exports_external.enum(MAP_EXIT_KINDS).default("door"),
+  to: exports_external.string().uuid().nullable().default(null),
+  direction: exports_external.enum(MAP_EXIT_DIRECTIONS).optional(),
+  arriveAt: exports_external.string().uuid().nullable().optional(),
+  main: exports_external.boolean().optional(),
+  locked: exports_external.boolean().optional(),
+  hidden: exports_external.boolean().optional()
+});
+var MapAreaV10Schema = MapAreaSchema.extend({
+  exit: MapExitSchema.optional()
+});
+var MapPointV10Schema = MapPointSchema.extend({
+  exit: MapExitSchema.optional()
+});
+var MapDataV10Schema = MapDataV8Schema.extend({
+  areas: exports_external.array(MapAreaV10Schema),
+  points: exports_external.array(MapPointV10Schema)
+});
+var COMPASS_DIRECTIONS = [
+  "north",
+  "northeast",
+  "east",
+  "southeast",
+  "south",
+  "southwest",
+  "west",
+  "northwest"
+];
+var PLACE_WAY_KINDS = [
+  ...MAP_EXIT_KINDS,
+  "bridge",
+  "ferry",
+  "tunnel",
+  "ritual"
+];
+var PLACE_WAY_DIRECTIONS = [
+  ...MAP_EXIT_DIRECTIONS,
+  ...COMPASS_DIRECTIONS
+];
+var relationWords = (max) => exports_external.string().trim().min(1).max(max);
+var PlaceWaySchema = MapExitSchema.extend({
+  kind: exports_external.enum(PLACE_WAY_KINDS).default("door"),
+  direction: exports_external.enum(PLACE_WAY_DIRECTIONS).optional(),
+  oneWay: exports_external.boolean().optional(),
+  when: relationWords(200).optional(),
+  requires: relationWords(200).optional(),
+  by: exports_external.string().uuid().optional(),
+  label: relationWords(120).optional(),
+  distance: relationWords(60).optional(),
+  time: relationWords(60).optional()
+});
+var MapAreaV11Schema = MapAreaSchema.extend({
+  exit: PlaceWaySchema.optional()
+});
+var MapPointV11Schema = MapPointSchema.extend({
+  exit: PlaceWaySchema.optional()
+});
+var MapDataV11Schema = MapDataV8Schema.extend({
+  areas: exports_external.array(MapAreaV11Schema),
+  points: exports_external.array(MapPointV11Schema)
+});
+var RelationIdSchema = exports_external.string().uuid();
+var RelationTargetSchema = exports_external.string().uuid();
+var InsideRelationSchema = exports_external.object({
+  id: RelationIdSchema,
+  type: exports_external.literal("inside"),
+  to: RelationTargetSchema,
+  level: exports_external.number().int().min(-100).max(500).optional()
+});
+var ConnectsRelationSchema = PlaceWaySchema.extend({
+  id: RelationIdSchema,
+  type: exports_external.literal("connects")
+});
+var OtherRelationSchema = exports_external.object({
+  id: RelationIdSchema,
+  type: exports_external.literal("other"),
+  to: RelationTargetSchema,
+  label: relationWords(120)
+});
+var PlaceRelationSchema = exports_external.discriminatedUnion("type", [
+  InsideRelationSchema,
+  ConnectsRelationSchema,
+  OtherRelationSchema
+]);
+var MAX_PLACE_RELATIONS = 100;
+var TRANSPORT_KINDS = [
+  "ship",
+  "boat",
+  "airship",
+  "wagon",
+  "caravan",
+  "carriage",
+  "train",
+  "car",
+  "bus",
+  "plane",
+  "mount",
+  "other"
+];
+var TRANSPORT_MEDIUMS = [
+  "water",
+  "land",
+  "air",
+  "rail",
+  "underground",
+  "space"
+];
+var TransportMetadataSchema = exports_external.object({
+  kind: exports_external.enum(TRANSPORT_KINDS),
+  travels: exports_external.enum(TRANSPORT_MEDIUMS).optional(),
+  speed: exports_external.object({
+    value: exports_external.number().positive(),
+    unit: exports_external.enum(["mph", "km/h", "knots"])
+  }).optional(),
+  capacity: exports_external.number().int().positive().optional()
+});
 var GmInstructionTriggerPhaseSchema = exports_external.enum(GM_INSTRUCTION_TRIGGER_PHASES);
 var GmInstructionToolEventSchema = exports_external.enum(GM_INSTRUCTION_TOOL_EVENTS);
 var GmInstructionNarrativeMetadataSchema = exports_external.object({
@@ -41403,24 +41582,36 @@ var FileDesignationMetadataV9Schema = FileDesignationMetadataV8Schema.extend({
   schemaVersionId: exports_external.literal(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V9).default(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V9),
   script: ScriptMetadataSchema.optional()
 });
-var MapSchema = FileDesignationMetadataV9Schema.shape.map.unwrap();
-var LocationDesignationMetadataSchema = FileDesignationMetadataV9Schema.pick({
+var FileDesignationMetadataV10Schema = FileDesignationMetadataV9Schema.extend({
+  schemaVersionId: exports_external.literal(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V10).default(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V10),
+  map: MapDataV10Schema.optional(),
+  transport: TransportMetadataSchema.optional()
+});
+var FileDesignationMetadataV11Schema = FileDesignationMetadataV10Schema.extend({
+  schemaVersionId: exports_external.literal(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V11).default(FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V11),
+  map: MapDataV11Schema.optional(),
+  relations: exports_external.array(PlaceRelationSchema).max(MAX_PLACE_RELATIONS).optional()
+});
+var MapSchema = FileDesignationMetadataV11Schema.shape.map.unwrap();
+var LocationDesignationMetadataSchema = FileDesignationMetadataV11Schema.pick({
   schemaVersionId: true,
-  map: true
+  map: true,
+  transport: true,
+  relations: true
 });
-var CharacterDesignationMetadataSchema = FileDesignationMetadataV9Schema.pick({
+var CharacterDesignationMetadataSchema = FileDesignationMetadataV11Schema.pick({
   schemaVersionId: true,
   playable: true
 });
-var GmInstructionDesignationMetadataSchema = FileDesignationMetadataV9Schema.pick({
+var GmInstructionDesignationMetadataSchema = FileDesignationMetadataV11Schema.pick({
   schemaVersionId: true,
   gmInstruction: true
 });
-var GameStartDesignationMetadataSchema = FileDesignationMetadataV9Schema.pick({
+var GameStartDesignationMetadataSchema = FileDesignationMetadataV11Schema.pick({
   schemaVersionId: true,
   gameStart: true
 });
-var ScriptDesignationMetadataSchema = FileDesignationMetadataV9Schema.pick({
+var ScriptDesignationMetadataSchema = FileDesignationMetadataV11Schema.pick({
   schemaVersionId: true,
   script: true
 });
@@ -41428,10 +41619,17 @@ function upgradeFileDesignationMetadata(input) {
   if (input === null || input === undefined) {
     return null;
   }
-  if (readSchemaVersionId(input) === FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V9) {
-    return FileDesignationMetadataV9Schema.parse(input);
+  const schemaVersionId = readSchemaVersionId(input);
+  if (schemaVersionId === FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V11) {
+    return FileDesignationMetadataV11Schema.parse(input);
   }
-  return upgradeV8MetadataToV9(upgradeMetadataToV8(input));
+  if (schemaVersionId === FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V10) {
+    return upgradeV10MetadataToV11(FileDesignationMetadataV10Schema.parse(input));
+  }
+  if (schemaVersionId === FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V9) {
+    return upgradeV10MetadataToV11(upgradeV9MetadataToV10(FileDesignationMetadataV9Schema.parse(input)));
+  }
+  return upgradeV10MetadataToV11(upgradeV9MetadataToV10(upgradeV8MetadataToV9(upgradeMetadataToV8(input))));
 }
 function upgradeMetadataToV8(input) {
   const schemaVersionId = readSchemaVersionId(input);
@@ -41518,6 +41716,18 @@ function upgradeV8MetadataToV9(metadata) {
     schemaVersionId: FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V9
   });
 }
+function upgradeV9MetadataToV10(metadata) {
+  return FileDesignationMetadataV10Schema.parse({
+    ...metadata,
+    schemaVersionId: FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V10
+  });
+}
+function upgradeV10MetadataToV11(metadata) {
+  return FileDesignationMetadataV11Schema.parse({
+    ...metadata,
+    schemaVersionId: FILE_DESIGNATION_METADATA_SCHEMA_VERSION_V11
+  });
+}
 function normalizeLegacyDefaultGrid(map2) {
   if (map2.grid?.mode !== "default") {
     return map2;
@@ -45379,7 +45589,7 @@ async function refreshWorkspaceScriptTypes({
 // package.json
 var package_default = {
   name: "@craftrpgs/cli",
-  version: "0.2.0-alpha.0",
+  version: "0.2.0-alpha.1",
   description: "Sync Craft projects with a local folder — clone, edit with any coding agent, push back.",
   license: "UNLICENSED",
   homepage: "https://craftrpgs.com",
@@ -45439,6 +45649,17 @@ var cliMetaWriteResponseSchema = exports_external.object({
   version: exports_external.object({ id: exports_external.string().min(1) }),
   linkStateChanged: exports_external.boolean().optional()
 });
+var cliPlacePairWriteResponseSchema = exports_external.object({
+  changedFileIds: exports_external.array(exports_external.string().min(1))
+});
+var cliLinkedLocationsResponseSchema = exports_external.object({
+  parent: exports_external.object({ referenceId: exports_external.string() }).nullable(),
+  places: exports_external.array(exports_external.object({
+    referenceId: exports_external.string(),
+    name: exports_external.string(),
+    pair: exports_external.record(exports_external.string(), exports_external.unknown())
+  }))
+});
 var cliFileMetaResponseSchema = exports_external.object({
   currentVersion: exports_external.object({
     id: exports_external.string().min(1),
@@ -45829,6 +46050,40 @@ function createCliClient({
     async putGmInstruction({ fileId, gmInstruction }) {
       return await putMetadata(`/api/files/${fileId}/gm-instruction`, { gmInstruction }, "GM instruction trigger save");
     },
+    async fetchLinkedLocations({ fileId }) {
+      const response = await request(`/api/files/${fileId}/relations`);
+      if (response.status === 404) {
+        return null;
+      }
+      if (!response.ok) {
+        const { code, message, details } = await readErrorBody(response);
+        throw new CliApiError({
+          message,
+          code,
+          status: response.status,
+          exitCode: 1,
+          details
+        });
+      }
+      return await parseJson(response, cliLinkedLocationsResponseSchema, "linked locations");
+    },
+    async putFileTransport({ fileId, transport }) {
+      return await putMetadata(`/api/files/${fileId}/transport`, { transport }, "transport save");
+    },
+    async putPlacePair({ fileId, otherFileId, pair }) {
+      const response = await request(`/api/files/${fileId}/relations/${otherFileId}`, pair === null ? { method: "DELETE" } : { method: "PUT", body: JSON.stringify(pair) });
+      if (!response.ok) {
+        const { code, message, details } = await readErrorBody(response);
+        throw new CliApiError({
+          message,
+          code,
+          status: response.status,
+          exitCode: response.status === 400 || response.status === 422 ? 2 : 1,
+          details
+        });
+      }
+      return await parseJson(response, cliPlacePairWriteResponseSchema, "linked location save");
+    },
     async putDesignationFlag({ fileId, flag, value }) {
       return await putMetadata(`/api/files/${fileId}/designation`, { flag, value }, "designation flag save");
     },
@@ -48549,11 +48804,66 @@ async function runLogout(argv) {
 
 // src/commands/map.ts
 import { readFile as readFile11 } from "node:fs/promises";
+
+// src/commands/place-metadata.ts
+function pathOrId(ledger, referenceId) {
+  return referenceIdToPath({ ledger, referenceId }) ?? referenceId;
+}
+function exitForOutput(ledger, exit) {
+  return {
+    ...exit,
+    ...typeof exit.to === "string" ? { to: pathOrId(ledger, exit.to) } : {},
+    ...typeof exit.by === "string" ? { by: pathOrId(ledger, exit.by) } : {}
+  };
+}
+function relationsForOutput(ledger, relations) {
+  return relations.map((relation) => exitForOutput(ledger, relation));
+}
+function listMapExitsForOutput(ledger, map2) {
+  return [...map2.areas, ...map2.points].flatMap((element) => element.exit ? [
+    {
+      element: element.label ?? element.id,
+      ...exitForOutput(ledger, element.exit)
+    }
+  ] : []);
+}
+function resolveExitInput({
+  ledger,
+  exit,
+  where,
+  failures
+}) {
+  if (typeof exit !== "object" || exit === null || Array.isArray(exit)) {
+    return exit;
+  }
+  const record2 = { ...exit };
+  for (const key of ["to", "by"]) {
+    const value = record2[key];
+    if (typeof value !== "string") {
+      continue;
+    }
+    const resolution = resolveLink({ ledger, link: value });
+    if (resolution.status === "resolved") {
+      record2[key] = resolution.referenceId;
+    } else {
+      failures.push({
+        where: `${where}.${key}`,
+        link: value,
+        reason: resolution.status
+      });
+    }
+  }
+  return record2;
+}
+
+// src/commands/map.ts
 var MAP_USAGE = `Usage: craft map get <location-path> [--json]
 ` + `       craft map set <location-path> --file <map.json>
 ` + `
-` + "The map JSON is the stored MapData shape; in `set` input, areas/points may\n" + 'use `"link": "<workspace path | slug.type | referenceId>"` instead of\n' + `fileReferenceId, and element ids are minted when omitted. Read
-` + ".craft/instructions/authoring-maps.md for the format and quality bar.";
+` + "The map JSON is the stored MapData shape; in `set` input, areas/points may\n" + 'use `"link": "<workspace path | slug.type | referenceId>"` instead of\n' + `fileReferenceId, and element ids are minted when omitted. An element's
+` + '`exit` (a door, stairs, a road to another location) takes `"to"` as a\n' + "workspace path too; no `to` is the way out to the parent map. `get` prints\n" + `links and exit targets as workspace paths. Read
+` + `.craft/instructions/authoring-maps.md for the format and
+` + ".craft/instructions/linking-locations.md for exits.";
 async function runMap(argv) {
   const [subcommand, ...rest] = argv;
   if (subcommand === "get") {
@@ -48575,16 +48885,22 @@ function hydrateMapForOutput(workspace, map2) {
     if (typeof element !== "object" || element === null) {
       return element;
     }
-    const record2 = element;
+    let record2 = element;
+    if (typeof record2.exit === "object" && record2.exit !== null) {
+      record2 = {
+        ...record2,
+        exit: exitForOutput(workspace.ledger, record2.exit)
+      };
+    }
     if (typeof record2.fileReferenceId !== "string") {
-      return element;
+      return record2;
     }
     const path = referenceIdToPath({
       ledger: workspace.ledger,
       referenceId: record2.fileReferenceId
     });
     if (!path) {
-      return element;
+      return record2;
     }
     const { fileReferenceId: _dropped, ...rest } = record2;
     return { ...rest, link: path };
@@ -48677,6 +48993,14 @@ function normalizeMapInput(workspace, raw) {
     if (record2.fileReferenceId === undefined) {
       record2.fileReferenceId = null;
     }
+    if (record2.exit !== undefined) {
+      record2.exit = resolveExitInput({
+        ledger: workspace.ledger,
+        exit: record2.exit,
+        where: `${kindLabel2}[${index}].exit`,
+        failures
+      });
+    }
     for (const [key, value] of Object.entries(defaults)) {
       if (record2[key] === undefined) {
         record2[key] = value;
@@ -48945,13 +49269,75 @@ function translateGameStartAuthoringInput({
   return input;
 }
 
+// ../shared/src/place-pairs.ts
+var PLACE_PAIR_KINDS = [
+  "same_place",
+  "contains",
+  "part_of",
+  "separate",
+  "other"
+];
+var PairWaySchema = PlaceWaySchema.omit({
+  to: true,
+  arriveAt: true,
+  main: true,
+  oneWay: true
+}).extend({
+  oneWay: exports_external.enum(["there", "back"]).optional()
+});
+var PairWordsSchema = exports_external.object({
+  text: exports_external.string().trim().min(1).max(120),
+  first: exports_external.enum(["a", "b"])
+});
+var PlacePairSchema = exports_external.object({
+  kind: exports_external.enum(PLACE_PAIR_KINDS),
+  parentRef: exports_external.string().uuid().optional(),
+  way: PairWaySchema.nullable(),
+  words: PairWordsSchema.nullable()
+});
+function placePairProblem({
+  pair,
+  aRef,
+  bRef
+}) {
+  if (aRef === bRef) {
+    return "A location can't be linked to itself.";
+  }
+  if (pair.kind === "same_place") {
+    if (!pair.parentRef) {
+      return "Pick the location they're both in.";
+    }
+    if (pair.parentRef === aRef || pair.parentRef === bRef) {
+      return "A location can't be inside itself.";
+    }
+  } else if (pair.parentRef) {
+    return "Only locations in one location name the location they're in.";
+  }
+  if (pair.kind === "separate" && !pair.way) {
+    return "Separate locations need a way between them.";
+  }
+  if (pair.kind === "other" && !pair.words) {
+    return "Say how they relate.";
+  }
+  if (pair.kind !== "other" && pair.words) {
+    return "Only something else has words of its own.";
+  }
+  return null;
+}
+
 // src/commands/meta.ts
+var PAIR_KIND_FIELD_RE = /^kind/;
 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)
 ` + `       craft meta set-playable <character-path> <true|false>
+` + `       craft meta set-transport <location-path> (--file <json> | --clear)
+` + `       craft meta link <location-path> <other-location-path> --file <json>
+` + `       craft meta unlink <location-path> <other-location-path>
 ` + `
-` + "See .craft/instructions/making-it-playable.md for the JSON shapes.";
+` + `See .craft/instructions/making-it-playable.md for game starts, triggers and
+` + `playable, and .craft/instructions/linking-locations.md for transports and
+` + "linked locations. `get` on a location shows its transport, its linked\n" + "locations (read from both ends) and its map's exits, with workspace paths.";
 async function runMeta(argv) {
   const [subcommand, ...rest] = argv;
   if (subcommand === "get") {
@@ -48966,6 +49352,15 @@ async function runMeta(argv) {
   if (subcommand === "set-playable") {
     return await runSetPlayable(rest);
   }
+  if (subcommand === "set-transport") {
+    return await runSetTransport(rest);
+  }
+  if (subcommand === "link") {
+    return await runLink(rest, "link");
+  }
+  if (subcommand === "unlink") {
+    return await runLink(rest, "unlink");
+  }
   throw new CliError(META_USAGE, 2);
 }
 async function readJsonFile2(inputPath) {
@@ -49028,6 +49423,8 @@ async function runMetaGet(argv) {
   if (gameStart) {
     gameStart.startingLocationFileReferenceId = undefined;
   }
+  const isLocation = meta3.fileType?.designation === "location" || Boolean(parsed?.map || parsed?.transport || parsed?.relations);
+  const linkedLocations = isLocation ? await linkedLocationsForOutput(workspace, client, entry.fileId) : undefined;
   printJson({
     path,
     fileType: entry.fileType,
@@ -49039,11 +49436,38 @@ async function runMetaGet(argv) {
       areas: parsed.map.areas.length,
       points: parsed.map.points.length,
       useParentMap: parsed.map.useParentMap ?? false,
+      exits: listMapExitsForOutput(workspace.ledger, parsed.map),
       hint: "Full map via `craft map get`."
-    } : null
+    } : null,
+    ...isLocation ? {
+      transport: parsed?.transport ?? null,
+      relations: relationsForOutput(workspace.ledger, parsed?.relations ?? []),
+      ...linkedLocations === undefined ? {} : { linkedLocations }
+    } : {}
   });
   return 0;
 }
+async function linkedLocationsForOutput(workspace, client, fileId) {
+  const linked = await client.fetchLinkedLocations({ fileId });
+  if (!linked) {
+    return;
+  }
+  return linked.places.map((place) => {
+    const pair = place.pair;
+    return {
+      location: pathForReference(workspace, place.referenceId) ?? place.name,
+      relation: pair.kind,
+      ...pair.parentRef ? { in: pathForReference(workspace, pair.parentRef) } : {},
+      ...pair.way ? {
+        way: exitForOutput(workspace.ledger, pair.way)
+      } : {},
+      ...pair.words ? {
+        words: pair.words.text,
+        wordsFirst: pair.words.first === "a" ? "location" : "other"
+      } : {}
+    };
+  });
+}
 function projectOpeningForOutput(workspace, opening) {
   if (opening.kind !== "static" || !opening.beats?.length) {
     return opening;
@@ -49220,6 +49644,159 @@ async function runSetPlayable(argv) {
   printLines([`Set playable: ${value} on ${path}.`]);
   return 0;
 }
+async function runSetTransport(argv) {
+  const args = parseCommandArgs({
+    argv,
+    flags: {
+      file: { type: "string" },
+      clear: { type: "boolean" },
+      json: { type: "boolean" }
+    },
+    maxPositionals: 1
+  });
+  const path = args.positionals[0];
+  const inputPath = stringFlag(args, "file");
+  const clear = args.booleans.has("clear");
+  const exactlyOneMode = clear ? !inputPath : Boolean(inputPath);
+  if (!(path && exactlyOneMode)) {
+    throw new CliError(META_USAGE, 2);
+  }
+  let transport = null;
+  if (inputPath) {
+    const parsed = LocationDesignationMetadataSchema.shape.transport.unwrap().safeParse(await readJsonFile2(inputPath));
+    if (!parsed.success) {
+      throw new CliError(`The transport JSON failed validation:
+` + parsed.error.issues.map((issue3) => `  ${issue3.path.join(".") || "(root)"}: ${issue3.message}`).join(`
+`), 2);
+    }
+    transport = parsed.data;
+  }
+  const workspace = await loadWorkspaceContext();
+  const entry = resolveTrackedEntry({ ledger: workspace.ledger, input: path });
+  const client = await workspaceClient(workspace);
+  const result = await client.putFileTransport({
+    fileId: entry.fileId,
+    transport
+  });
+  await freshenLedgerAfterMetaWrite({
+    root: workspace.root,
+    ledger: workspace.ledger,
+    fileId: entry.fileId,
+    versionId: result.version.id
+  });
+  if (args.booleans.has("json")) {
+    printJson({ path, saved: true, transport });
+    return 0;
+  }
+  printLines([
+    transport ? `Saved transport on ${path}: ${transport.kind}${transport.travels ? ` (${transport.travels})` : ""}.` : `Cleared transport on ${path}.`
+  ]);
+  return 0;
+}
+function translatePlacePairInput({
+  workspace,
+  raw,
+  aRef,
+  bRef
+}) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new CliError("The link JSON must be a single object.", 2);
+  }
+  const input = raw;
+  const failures = [];
+  let parentRef;
+  if (typeof input.in === "string") {
+    const resolution = resolveLink({
+      ledger: workspace.ledger,
+      link: input.in
+    });
+    if (resolution.status === "resolved") {
+      parentRef = resolution.referenceId;
+    } else {
+      failures.push({ where: "in", link: input.in, reason: resolution.status });
+    }
+  }
+  const way = input.way === undefined || input.way === null ? null : resolveExitInput({
+    ledger: workspace.ledger,
+    exit: input.way,
+    where: "way",
+    failures
+  });
+  if (failures.length > 0) {
+    throw new CliError(`Nothing was saved — some links do not resolve to pushed files:
+` + failures.map((failure2) => `  ${failure2.where}: "${failure2.link}"` + `${failure2.reason === "unpushed" ? " (tracked but not pushed yet)" : " (no tracked file matches)"}`).join(`
+`), 2);
+  }
+  const parsedWay = way === null ? null : PairWaySchema.safeParse(way);
+  const parsed = PlacePairSchema.safeParse({
+    kind: input.relation,
+    ...parentRef ? { parentRef } : {},
+    way: parsedWay?.success ? parsedWay.data : way,
+    words: typeof input.words === "string" ? { text: input.words, first: input.wordsFirst === "other" ? "b" : "a" } : null
+  });
+  if (!parsed.success) {
+    throw new CliError(`The link JSON failed validation:
+` + parsed.error.issues.map((issue3) => {
+      const field = issue3.path.join(".").replace(PAIR_KIND_FIELD_RE, "relation");
+      return `  ${field || "(root)"}: ${issue3.message}`;
+    }).join(`
+`), 2);
+  }
+  const problem = placePairProblem({ pair: parsed.data, aRef, bRef });
+  if (problem) {
+    throw new CliError(problem, 2);
+  }
+  return parsed.data;
+}
+async function runLink(argv, mode) {
+  const args = parseCommandArgs({
+    argv,
+    flags: { file: { type: "string" }, json: { type: "boolean" } },
+    maxPositionals: 2
+  });
+  const [path, otherPath] = args.positionals;
+  const inputPath = stringFlag(args, "file");
+  if (!(path && otherPath) || mode === "link" !== Boolean(inputPath)) {
+    throw new CliError(META_USAGE, 2);
+  }
+  const workspace = await loadWorkspaceContext();
+  const entry = resolveTrackedEntry({ ledger: workspace.ledger, input: path });
+  const other = resolveTrackedEntry({
+    ledger: workspace.ledger,
+    input: otherPath
+  });
+  const pair = inputPath ? translatePlacePairInput({
+    workspace,
+    raw: await readJsonFile2(inputPath),
+    aRef: entry.referenceId,
+    bRef: other.referenceId
+  }) : null;
+  const client = await workspaceClient(workspace);
+  const { changedFileIds } = await client.putPlacePair({
+    fileId: entry.fileId,
+    otherFileId: other.fileId,
+    pair
+  });
+  for (const fileId of changedFileIds) {
+    const meta3 = await client.fetchFileMeta({ fileId });
+    await freshenLedgerAfterMetaWrite({
+      root: workspace.root,
+      ledger: workspace.ledger,
+      fileId,
+      versionId: meta3.currentVersion.id
+    });
+  }
+  if (args.booleans.has("json")) {
+    printJson({ path, other: otherPath, saved: true, pair, changedFileIds });
+    return 0;
+  }
+  const changed = changedFileIds.length === 0 ? "nothing changed" : `${changedFileIds.length} location${changedFileIds.length === 1 ? "" : "s"} changed`;
+  printLines([
+    mode === "link" ? `Linked ${path} and ${otherPath} (${pair?.kind}): ${changed}.` : `Unlinked ${path} and ${otherPath}: ${changed}.`,
+    "See where each location now sits with `craft meta get`."
+  ]);
+  return 0;
+}
 
 // src/commands/mv.ts
 import { existsSync as existsSync8 } from "node:fs";
@@ -56055,9 +56632,12 @@ var HELP_COMMAND_LINES = `  clone <projectIdOrUrl> [dir]   Download a project as
   map get|set <location-path>    Read/author the interactive map stored on a
                                  location file (see "craft help map")
   meta get <path>                Show a file's designation metadata (game start
-                                 config, GM triggers, playable flag, map summary)
+                                 config, GM triggers, playable flag, map summary,
+                                 a location's transport and linked locations)
   meta set-game-start|set-gm-trigger|set-playable
                                  Configure playability metadata (see "craft help meta")
+  meta set-transport|link|unlink Make a location a ship/caravan, or link two
+                                 locations (see "craft help meta")
   vn list|create|pull|check|push|publish|assets
                                  Write visual novels: pull a story to a JSON
                                  file, edit it, push it back, publish it
@@ -56389,6 +56969,10 @@ Authoring format = the stored MapData shape with conveniences:
 - element "id"s are minted when omitted; point style defaults are applied.
 - required: "aspectRatio" matching the background image (4:3 for a default
   landscape-4-3 generation). background/scale/grid default to null.
+- an area/point may carry "exit": a way to another location, e.g.
+  {"kind":"stairs","to":"Places/The Inn Upstairs.location.json","direction":"up"}.
+  "to" takes a workspace path (or slug.type / referenceId); leave it out for
+  the way out to the parent map. \`get\` prints links and exit "to"s as paths.
 
 The background image URL must be Craft-hosted \u2014 generate one with
 \`craft image generate\` (or upload with \`craft image upload\`) and paste
@@ -56440,6 +57024,9 @@ chapters, where cutouts stand (desktop and phone), and pictures on pages.
        craft meta set-game-start <game-start-path> --file <json>
        craft meta set-gm-trigger <gm-instruction-path> (--file <json> | --clear)
        craft meta set-playable <character-path> <true|false>
+       craft meta set-transport <location-path> (--file <json> | --clear)
+       craft meta link <location-path> <other-location-path> --file <json>
+       craft meta unlink <location-path> <other-location-path>
 
 Designation metadata is app-managed and lives outside the working tree;
 these commands write the server directly (the target file must be pushed).
@@ -56461,6 +57048,23 @@ set-gm-trigger JSON (triggered GM rules; name \u2264120 / body \u2264500 chars):
 
 Read .craft/instructions/making-it-playable.md for how these fit together.
 
+set-transport JSON (a location that carries people; its deck plan is its map):
+  {"kind":"ship","travels":"water","speed":{"value":6,"unit":"knots"},"capacity":40}
+  kind: ship|boat|airship|wagon|caravan|carriage|train|car|bus|plane|mount|other
+
+link JSON \u2014 how <location> relates to <other>, the shape \`meta get\` prints
+under linkedLocations (it replaces whatever lay between the two):
+  {"relation":"part_of","way":{"kind":"stairs","direction":"up"}}
+  relation: same_place (both parts of "in": "<path>") | contains (other is part
+  of location) | part_of (location is part of other) | separate (needs "way") |
+  other (needs "words": "is the Shadowfell reflection of", "wordsFirst":
+  "location"|"other"). way: {kind, direction from location, oneWay:
+  "there"|"back", locked, hidden, when, requires, label, distance, time}.
+  A location is inside at most one place and never inside itself; linking can
+  move a place in or out of another. unlink removes everything between them.
+Read .craft/instructions/linking-locations.md for exits, transports and
+linked locations.
+
 upload: send a local image file (max 10MB; 50 per 24h, 1,000 per 24h for
 subscribers) to the project's media
 storage; the server re-encodes it to webp and returns the same pasteable

package/package.json

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