tileflow 0.1.0-alpha.6 → 0.1.0-alpha.7

package/dist/index.js

@@ -7,14 +7,14 @@ import { createHash as createHash4, randomBytes as randomBytes2 } from "crypto";
 import { existsSync, readFileSync, realpathSync } from "fs";
 import { readFile as readFile7, writeFile as writeFile2 } from "fs/promises";
 import { hostname } from "os";
-import { dirname as dirname10, isAbsolute as isAbsolute4, relative as relative5, resolve as resolve7, sep as sep5 } from "path";
+import { dirname as dirname11, isAbsolute as isAbsolute5, relative as relative5, resolve as resolve7, sep as sep5 } from "path";
 import { createInterface } from "readline/promises";
-import pc3 from "picocolors";
+import pc6 from "picocolors";
 import { createLocalCoordinates, setupCoordinates } from "@tileflow/coordinates-runtime";
 import {
   auditTileflowMapThemeValues,
   getTileflowStyleFontFaces,
-  parseResolvedTileflowMap as parseResolvedTileflowMap3,
+  parseResolvedTileflowMap as parseResolvedTileflowMap4,
   tileflowMapIdSchema as tileflowMapIdSchema2
 } from "@tileflow/core";
 import {
@@ -36,16 +36,19 @@ import {
   defaultTileflowApiUrl,
   defaultTileflowConfigPath,
   defaultTileflowManifestPath,
-  getTileflowMapNames as getTileflowMapNames3,
+  getTileflowMapNames as getTileflowMapNames4,
   loadTileflowConfigWithInputs as loadTileflowConfigWithInputs3,
-  TileflowValidationError as TileflowValidationError4
+  TileflowValidationError as TileflowValidationError5
 } from "@tileflow/dev/config";
 import {
   bindTileflowStyleFontBundle,
   prepareTileflowStyleFonts,
   TileflowFontCompilationError
 } from "@tileflow/dev/fonts";
-import { compileTileflowIconPackages as compileTileflowIconPackages2, TileflowIconCompilationError as TileflowIconCompilationError3 } from "@tileflow/dev/icons";
+import {
+  compileTileflowIconPackages as compileTileflowIconPackages2,
+  TileflowIconCompilationError as TileflowIconCompilationError3
+} from "@tileflow/dev/icons";
 import { resolveTileflowPreview } from "@tileflow/dev/preview";
 import {
   createTileflowComparisonRequestHandler,
@@ -2882,7 +2885,9 @@ import {
   getTileflowMapNames,
   loadTileflowConfigWithInputs as loadTileflowConfigWithInputs2
 } from "@tileflow/dev/config";
-import { compileTileflowIconPackages } from "@tileflow/dev/icons";
+import {
+  compileTileflowIconPackages
+} from "@tileflow/dev/icons";
 
 // src/icon-diff-report.ts
 import { randomUUID as randomUUID2 } from "crypto";
@@ -3441,7 +3446,7 @@ var tileflowIconDiffDocumentSchema = z4.object({
   hasChanges: z4.boolean()
 }).strict();
 function registerIconDiffCommand(icons, dependencies) {
-  icons.command("diff").description("Preview a local icon package against an active hosted revision").requiredOption("--against <environment>", "named map environment to compare").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Tileflow API key", process.env.TILEFLOW_API_KEY).requiredOption("--map-id <id>", "managed Map destination").option("--json", "print deterministic schema-version-1 JSON").option("--report <path>", "write a self-contained HTML visual report").option("--open", "open an explicitly requested report").option("--force", "replace a different explicitly requested report").action(async (options) => {
+  icons.command("diff").description("Preview a local icon package against an active hosted revision").requiredOption("--against <environment>", "named map environment to compare").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Tileflow API key", process.env.TILEFLOW_API_KEY).requiredOption("--map-id <id>", "managed Map destination").option("--json", "print deterministic schema-version-1 JSON").option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").option("--report <path>", "write a self-contained HTML visual report").option("--open", "open an explicitly requested report").option("--force", "replace a different explicitly requested report").action(async (options) => {
     try {
       await runIconDiff(options, dependencies);
     } catch (error) {
@@ -3477,9 +3482,14 @@ async function runIconDiff(options, dependencies) {
     throw new Error("Missing Tileflow API key. Run tileflow login or set TILEFLOW_API_KEY.");
   }
   const selectedProject = { ...project, maps: { [environment]: project.maps[environment] } };
+  const icons = {
+    ...options.cacheDir ? { cacheRoot: options.cacheDir } : {},
+    ...options.offline ? { offline: true } : {}
+  };
   const compiled = await compileTileflowIconPackages(selectedProject, {
     baseDirectory: dirname6(loaded.configFile),
     cwd: process.cwd(),
+    ...Object.keys(icons).length > 0 ? { icons } : {},
     target: "hosted"
   });
   const binding = compiled.bindings.find((candidate) => candidate.mapName === environment);
@@ -3633,7 +3643,7 @@ import {
   TileflowIconCompilationError as TileflowIconCompilationError2
 } from "@tileflow/dev/icons";
 function registerIconListCommand(icons, dependencies) {
-  icons.command("list").description("List each map icon directory composition as deterministic agent JSON").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--map <id>", "inspect one exact configured map").option("--json", "print deterministic schema-version-2 JSON").action(async (options) => {
+  icons.command("list").description("List each map icon directory composition as deterministic agent JSON").option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--map <id>", "inspect one exact configured map").option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").option("--json", "print deterministic schema-version-3 JSON").action(async (options) => {
     if (!options.json) {
       console.error(
         "tileflow icons list currently requires --json. Run tileflow icons list --json."
@@ -3651,7 +3661,7 @@ function registerIconListCommand(icons, dependencies) {
 }
 function createTileflowIconListJson(inspection) {
   return {
-    schemaVersion: 2,
+    schemaVersion: 3,
     pathBase: "cwd",
     maps: [...inspection.maps].sort((left, right) => compareCodeUnits6(left.name, right.name)).map((map) => createMapJson(map, inspection.catalogs))
   };
@@ -3671,9 +3681,14 @@ async function runIconList(options) {
       `Unknown map "${options.map}". Available maps: ${mapIds.join(", ") || "(none)"}`
     );
   }
+  const icons = {
+    ...options.cacheDir ? { cacheRoot: options.cacheDir } : {},
+    ...options.offline ? { offline: true } : {}
+  };
   const inspection = await inspectTileflowIconCatalogs(project, {
     baseDirectory: dirname7(loaded.configFile),
     cwd: process.cwd(),
+    ...Object.keys(icons).length > 0 ? { icons } : {},
     ...options.map ? { mapNames: [options.map] } : {}
   });
   process.stdout.write(serializeTileflowIconListJson(createTileflowIconListJson(inspection)));
@@ -3684,7 +3699,7 @@ function createMapJson(map, catalogs) {
   }
   const mapIcons = map.icons;
   const catalog = catalogs.find(
-    (candidate) => candidate.compiledPackage.contentHash === mapIcons.packageHash && sameStrings(candidate.directories, mapIcons.directories)
+    (candidate) => candidate.compiledPackage.contentHash === mapIcons.packageHash && sameContributors(candidate.contributors, mapIcons.contributors)
   );
   if (!catalog) {
     throw new Error(`Missing inspected icon catalog for map ${map.name}`);
@@ -3692,8 +3707,8 @@ function createMapJson(map, catalogs) {
   return {
     id: map.name,
     icons: {
-      kind: "directories",
-      directories: [...mapIcons.directories],
+      kind: "sources",
+      contributors: mapIcons.contributors.map(createContributorJson),
       finalIds: [...mapIcons.iconIds],
       insideWorkingTree: catalog.insideWorkingTree,
       replacements: catalog.replacements.map((replacement) => ({
@@ -3702,41 +3717,959 @@ function createMapJson(map, catalogs) {
         winner: replacement.winner
       })),
       packageHash: mapIcons.packageHash,
-      sources: [...catalog.icons].sort((left, right) => compareCodeUnits6(left.id, right.id)).map((icon) => ({
-        id: icon.id,
-        path: icon.source.path,
-        format: icon.source.format,
-        byteLength: icon.source.byteLength,
-        dimensions: icon.source.dimensions ? { width: icon.source.dimensions.width, height: icon.source.dimensions.height } : null
+      composition: mapIcons.composition,
+      sources: [...catalog.icons].sort((left, right) => compareCodeUnits6(left.id, right.id)).map(
+        (icon) => icon.source.kind === "icon-set" ? {
+          kind: "icon-set",
+          id: icon.id,
+          contributor: icon.source.contributor,
+          reference: icon.source.reference,
+          version: icon.source.version
+        } : {
+          kind: "file",
+          id: icon.id,
+          contributor: icon.source.contributor,
+          path: icon.source.path,
+          format: icon.source.format,
+          byteLength: icon.source.byteLength,
+          dimensions: icon.source.dimensions ? { width: icon.source.dimensions.width, height: icon.source.dimensions.height } : null
+        }
+      )
+    }
+  };
+}
+function createContributorJson(contributor) {
+  return contributor.kind === "icon-set" ? {
+    kind: "icon-set",
+    label: contributor.label,
+    iconIds: [...contributor.iconIds],
+    reference: contributor.reference,
+    version: contributor.version
+  } : {
+    kind: contributor.kind,
+    label: contributor.label,
+    iconIds: [...contributor.iconIds],
+    insideWorkingTree: contributor.insideWorkingTree
+  };
+}
+function sameContributors(left, right) {
+  return left.length === right.length && left.every((contributor, index) => contributor.label === right[index]?.label);
+}
+function printIconListError(error) {
+  if (error instanceof TileflowValidationError3) {
+    printIssues("Tileflow config has errors.", error.messages);
+    return;
+  }
+  if (error instanceof TileflowIconCompilationError2) {
+    printIssues("Tileflow icon catalog has errors.", error.issues);
+    return;
+  }
+  console.error(error instanceof Error ? error.message : "Icon catalog listing failed.");
+}
+function printIssues(heading, issues) {
+  console.error(
+    [heading, ...issues.map((issue) => `- ${issue.path || "(root)"}: ${issue.message}`)].join("\n")
+  );
+}
+
+// src/icon-lock-command.ts
+import { dirname as dirname8 } from "path";
+import pc3 from "picocolors";
+import {
+  collectTileflowIconSetReferences,
+  compareCodeUnits as compareCodeUnits7,
+  parseResolvedTileflowMap as parseResolvedTileflowMap2,
+  parseTileflowIconsLockfile,
+  tileflowIconSetReferenceSchema as tileflowIconSetReferenceSchema2,
+  tileflowIconsLockfileName
+} from "@tileflow/core";
+import {
+  getTileflowMapNames as getTileflowMapNames3,
+  loadValidTileflowConfigWithInputs as loadValidTileflowConfigWithInputs3,
+  TileflowValidationError as TileflowValidationError4
+} from "@tileflow/dev/config";
+import { readTileflowIconsLockfileText, writeTileflowIconsLockfile } from "@tileflow/dev/icons";
+
+// src/hosted-team.ts
+import pc from "picocolors";
+import { serializeCanonicalJson } from "@tileflow/core";
+async function resolveTeamAuthority(options, scopes, dependencies) {
+  let apiOrigin;
+  try {
+    apiOrigin = normalizeApiOrigin(options.apiUrl ?? dependencies.defaultApiUrl);
+  } catch (error) {
+    emitFailure(options.json, "invalid_api_url", safeMessage(error));
+    return null;
+  }
+  if (options.apiKey) {
+    if (!/^tf_live_[0-9a-f]{48}$/u.test(options.apiKey)) {
+      emitFailure(options.json, "invalid_team_data_key", "Team data API key is invalid.");
+      return null;
+    }
+    if (options.team) {
+      emitFailure(
+        options.json,
+        "team_selector_with_api_key",
+        "A Team data key already selects its Team; omit --team."
+      );
+      return null;
+    }
+    return { apiOrigin, credential: options.apiKey, team: null };
+  }
+  let config;
+  try {
+    config = await dependencies.loadAuthConfig();
+  } catch (error) {
+    emitFailure(options.json, "auth_state_unavailable", safeMessage(error));
+    return null;
+  }
+  const selected = resolveAccountSession(config, options.apiUrl ?? dependencies.defaultApiUrl);
+  if (selected.kind !== "selected") {
+    emitFailure(
+      options.json,
+      `account_session_${selected.kind}`,
+      selected.kind === "expired" ? "Account session expired. Run tileflow login." : "Run tileflow login."
+    );
+    return null;
+  }
+  const discovered = await listAccountTeams(selected.session);
+  if (!discovered.ok) {
+    emitFailure(options.json, "team_discovery_failed", discovered.error);
+    return null;
+  }
+  const requested = options.team ? /^@([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/u.exec(options.team) : null;
+  if (options.team && !requested) {
+    emitFailure(options.json, "invalid_team", "Team must use @team syntax.");
+    return null;
+  }
+  const team = requested ? discovered.teams.find(({ slug }) => slug === requested[1]) : discovered.teams.length === 1 ? discovered.teams[0] : null;
+  if (!team) {
+    const options_ = discovered.teams.map(({ slug }) => `@${slug}`);
+    emitFailure(
+      options.json,
+      options_.length > 1 ? "team_ambiguous" : "team_not_found",
+      options_.length > 1 ? `Choose one Team with --team: ${options_.join(", ")}.` : "No matching Team is available.",
+      { options: options_ }
+    );
+    return null;
+  }
+  const capability = await requestTeamCapability(selected.session, `@${team.slug}`, scopes);
+  if (!capability.ok) {
+    emitFailure(options.json, "team_capability_failed", capability.error);
+    return null;
+  }
+  return {
+    apiOrigin: selected.session.apiOrigin,
+    credential: capability.capability,
+    team
+  };
+}
+function authorizedTeamRequest(authority, path, method, init = {}) {
+  return requestHostedJson(authority.apiOrigin, path, {
+    ...init.body === void 0 ? {} : { body: init.body },
+    headers: { Authorization: `Bearer ${authority.credential}`, ...init.headers },
+    method
+  });
+}
+function emitJson(value) {
+  process.stdout.write(`${serializeCanonicalJson(value)}
+`);
+}
+function emitFailure(json, code, message, context = {}) {
+  if (json) {
+    process.stderr.write(
+      `${serializeCanonicalJson({ error: { code, ...context, message }, ok: false, schemaVersion: 1 })}
+`
+    );
+  } else {
+    console.error(`${pc.red("Error:")} ${message}`);
+  }
+  process.exitCode = 1;
+}
+function safeMessage(error) {
+  return error instanceof Error ? error.message : "Team command failed.";
+}
+
+// src/icon-set-command.ts
+import { isAbsolute as isAbsolute2 } from "path";
+import pc2 from "picocolors";
+import { z as z5 } from "zod";
+import {
+  tileflowIconSetPackageIdSchema,
+  tileflowIconSetPinSchema,
+  tileflowIconSetReferenceSchema
+} from "@tileflow/core";
+import { composeTileflowIconSources } from "@tileflow/dev/icons";
+var maximumCatalogPages = 100;
+var pageSize = 100;
+function registerIconSetCommands(program2, dependencies) {
+  const iconSet = program2.command("icon-set").description("Publish and manage versioned Team Icon Sets");
+  withTeamOptions(
+    iconSet.command("publish").description("Compile one local directory and publish it as an immutable Team revision").argument("<directory>", "repository-local icon directory").requiredOption("--id <id>", "Team-local Icon Set slug").requiredOption("--idempotency-key <key>", "durable retry key for this exact publication").option("--name <name>", "display name").option("--description <text>", "display description")
+  ).action(
+    async (directory, options) => {
+      try {
+        if (!isIconSetSlug(options.id)) {
+          return emitFailure(options.json, "invalid_icon_set_id", "Icon Set ID is invalid.");
+        }
+        if (!isIdempotencyKey(options.idempotencyKey)) {
+          return emitFailure(
+            options.json,
+            "invalid_idempotency_key",
+            "Idempotency key must be 8 to 128 characters from A-Z a-z 0-9 . _ : -"
+          );
+        }
+        const source = normalizeLocalDirectory(directory);
+        if (!source) {
+          return emitFailure(
+            options.json,
+            "invalid_icon_directory",
+            "Publish one repository-relative icon directory."
+          );
+        }
+        let iconPackage;
+        try {
+          const composed = await composeTileflowIconSources([source], {
+            cwd: process.cwd(),
+            target: "hosted"
+          });
+          if (!composed.package) throw new Error("The selected directory has no icons.");
+          iconPackage = composed.package;
+        } catch (error) {
+          return emitFailure(options.json, "icon_compilation_failed", safeMessage(error));
+        }
+        const authority = await resolveTeamAuthority(options, ["icons:write"], dependencies);
+        if (!authority) return;
+        const body = new FormData();
+        for (const file of iconPackage.files) {
+          const bytes = new Uint8Array(file.source.byteLength);
+          bytes.set(file.source);
+          body.append(
+            file.fileName,
+            new Blob([bytes.buffer], { type: file.contentType }),
+            file.fileName
+          );
+        }
+        const response = await authorizedTeamRequest(
+          authority,
+          `/v1/icon-sets/${encodeURIComponent(options.id)}/versions/${encodeURIComponent(iconPackage.contentHash)}`,
+          "PUT",
+          { body, headers: { "Idempotency-Key": options.idempotencyKey } }
+        );
+        if (!response.ok) return emitHttpFailure(options.json, response.status, "publish");
+        const parsed = publishResponseSchema.parse(response.body);
+        if (parsed.revision.pin && parsed.revision.pin.contentHash !== iconPackage.contentHash) {
+          return emitFailure(
+            options.json,
+            "icon_set_publish_unconfirmed",
+            "Publication response did not confirm the submitted generated artifact."
+          );
+        }
+        const metadata = {
+          ...options.description === void 0 ? {} : { description: options.description },
+          ...options.name === void 0 ? {} : { name: options.name }
+        };
+        if (Object.keys(metadata).length > 0) {
+          try {
+            const metadataResponse = await authorizedTeamRequest(
+              authority,
+              `/v1/icon-sets/${encodeURIComponent(options.id)}`,
+              "PATCH",
+              {
+                body: JSON.stringify(metadata),
+                headers: { "Content-Type": "application/json" }
+              }
+            );
+            if (!metadataResponse.ok || !catalogDetailResponseSchema.safeParse(metadataResponse.body).success) {
+              return emitFailure(
+                options.json,
+                "icon_set_metadata_update_failed",
+                "Icon Set publication succeeded, but display metadata could not be updated; rerun the same command."
+              );
+            }
+          } catch {
+            return emitFailure(
+              options.json,
+              "icon_set_metadata_update_failed",
+              "Icon Set publication succeeded, but display metadata could not be updated; rerun the same command."
+            );
+          }
+        }
+        const totalBytes = iconPackage.manifest.files.reduce(
+          (total, file) => total + file.byteLength,
+          0
+        );
+        const document = {
+          command: "icon-set publish",
+          iconSet: {
+            contentHash: iconPackage.contentHash,
+            iconCount: iconPackage.manifest.iconNames.length,
+            logicalId: options.id,
+            packageId: parsed.revision.pin?.packageId ?? null,
+            reference: parsed.revision.reference,
+            totalBytes,
+            version: parsed.revision.version,
+            versionId: parsed.revision.id
+          },
+          publication: parsed.changed ? "changed" : "unchanged",
+          schemaVersion: 1,
+          team: describeTeam(authority)
+        };
+        if (options.json) return emitJson(document);
+        console.log(
+          `${pc2.green("\u2713")} ${parsed.changed ? "Published" : "Unchanged"} ${pc2.bold(parsed.revision.reference)} revision ${parsed.revision.version}.`
+        );
+      } catch (error) {
+        emitFailure(options.json, "icon_set_publish_failed", boundedMessage(error, "publish"));
+      }
+    }
+  );
+  withTeamOptions(
+    iconSet.command("list").description("List Icon Sets owned by one Team").option("--archived", "list archived Icon Sets instead of active ones")
+  ).action(async (options) => {
+    try {
+      const authority = await resolveTeamAuthority(options, ["icons:read"], dependencies);
+      if (!authority) return;
+      const sets = await readAllPages(
+        authority,
+        "/v1/icon-sets",
+        options.archived ? { archived: "true" } : {},
+        catalogListResponseSchema,
+        (page) => page.sets,
+        (set) => set.id
+      );
+      const document = {
+        command: "icon-set list",
+        schemaVersion: 1,
+        sets,
+        team: describeTeam(authority)
+      };
+      if (options.json) return emitJson(document);
+      if (sets.length === 0) return console.log(pc2.gray("No Team Icon Sets."));
+      for (const set of sets) {
+        console.log(
+          `  ${pc2.bold(set.reference)} ${pc2.gray(set.archivedAt ? "archived" : `v${String(set.latestVersion ?? 0)}`)}`
+        );
+      }
+    } catch (error) {
+      emitFailure(options.json, "icon_set_list_failed", boundedMessage(error, "list"));
+    }
+  });
+  withTeamOptions(
+    iconSet.command("status").description("Show one Team Icon Set").argument("<slug>", "Team-local Icon Set slug")
+  ).action(async (slug, options) => {
+    await readCommand(slug, options, "icon-set status", async (authority) => {
+      const response = await authorizedTeamRequest(
+        authority,
+        `/v1/icon-sets/${encodeURIComponent(slug)}`,
+        "GET"
+      );
+      if (!response.ok) return { status: response.status };
+      const parsed = catalogDetailResponseSchema.parse(response.body);
+      return { value: { set: parsed.set } };
+    });
+  });
+  withTeamOptions(
+    iconSet.command("versions").description("List the retained revisions of one Team Icon Set").argument("<slug>", "Team-local Icon Set slug")
+  ).action(async (slug, options) => {
+    await readCommand(slug, options, "icon-set versions", async (authority) => {
+      const versions = await readAllPages(
+        authority,
+        `/v1/icon-sets/${encodeURIComponent(slug)}/versions`,
+        {},
+        versionsResponseSchema,
+        (page) => page.versions,
+        (revision) => revision.id
+      );
+      return { value: { versions: versions.map(describeRevision) } };
+    });
+  });
+  withTeamOptions(
+    iconSet.command("uses").description("List the known hosted deployments that retain one Team Icon Set").argument("<slug>", "Team-local Icon Set slug")
+  ).action(async (slug, options) => {
+    await readCommand(slug, options, "icon-set uses", async (authority) => {
+      const uses = await readAllPages(
+        authority,
+        `/v1/icon-sets/${encodeURIComponent(slug)}/uses`,
+        {},
+        usesResponseSchema,
+        (page) => page.uses,
+        (use) => `${use.deploymentId}\0${use.versionId}\0${String(use.ordinal)}`
+      );
+      return {
+        value: {
+          // Repository locks that were never deployed are unknowable to the catalog.
+          coverage: "known-hosted-deployments",
+          includesUndeployedRepositoryLocks: false,
+          uses
+        }
+      };
+    });
+  });
+  for (const [name, archived] of [
+    ["archive", true],
+    ["unarchive", false]
+  ]) {
+    withTeamOptions(
+      iconSet.command(name).description(
+        archived ? "Archive one Team Icon Set without removing its retained revisions" : "Return one archived Team Icon Set to the active catalog"
+      ).argument("<slug>", "Team-local Icon Set slug")
+    ).action(async (slug, options) => {
+      try {
+        if (!isIconSetSlug(slug)) {
+          return emitFailure(options.json, "invalid_icon_set_id", "Icon Set ID is invalid.");
+        }
+        const authority = await resolveTeamAuthority(options, ["icons:write"], dependencies);
+        if (!authority) return;
+        const response = await authorizedTeamRequest(
+          authority,
+          `/v1/icon-sets/${encodeURIComponent(slug)}`,
+          "PATCH",
+          {
+            body: JSON.stringify({ archived }),
+            headers: { "Content-Type": "application/json" }
+          }
+        );
+        if (!response.ok) return emitHttpFailure(options.json, response.status, name);
+        const parsed = catalogDetailResponseSchema.parse(response.body);
+        const document = {
+          command: `icon-set ${name}`,
+          schemaVersion: 1,
+          set: parsed.set,
+          team: describeTeam(authority)
+        };
+        if (options.json) return emitJson(document);
+        console.log(
+          `${pc2.green("\u2713")} ${archived ? "Archived" : "Restored"} ${pc2.bold(parsed.set.reference)}.`
+        );
+      } catch (error) {
+        emitFailure(options.json, `icon_set_${name}_failed`, boundedMessage(error, name));
+      }
+    });
+  }
+  withTeamOptions(
+    iconSet.command("purge").description("Permanently purge one exact Team Icon Set revision").argument("<slug>", "Team-local Icon Set slug").requiredOption("--version <version>", "exact positive revision to purge").requiredOption("--idempotency-key <key>", "durable retry key for this exact purge").requiredOption("--confirm <reference>", "repeat the exact @team/set@version being purged").option(
+      "--acknowledge-unknown-locks",
+      "acknowledge that undeployed repository locks are not discoverable"
+    )
+  ).action(
+    async (slug, options) => {
+      try {
+        if (!isIconSetSlug(slug)) {
+          return emitFailure(options.json, "invalid_icon_set_id", "Icon Set ID is invalid.");
+        }
+        if (!/^[1-9][0-9]*$/u.test(options.version) || !Number.isSafeInteger(+options.version)) {
+          return emitFailure(
+            options.json,
+            "invalid_icon_set_version",
+            "Purge requires one exact positive revision."
+          );
+        }
+        if (!isIdempotencyKey(options.idempotencyKey)) {
+          return emitFailure(
+            options.json,
+            "invalid_idempotency_key",
+            "Idempotency key must be 8 to 128 characters from A-Z a-z 0-9 . _ : -"
+          );
+        }
+        const confirmation = parsePurgeConfirmation(options.confirm);
+        if (!confirmation || confirmation.slug !== slug || confirmation.version !== Number(options.version)) {
+          return emitFailure(
+            options.json,
+            "purge_confirmation_mismatch",
+            "Purge confirmation must repeat the exact @team/set@version being purged."
+          );
+        }
+        if (options.acknowledgeUnknownLocks !== true) {
+          return emitFailure(
+            options.json,
+            "purge_unknown_locks_unacknowledged",
+            "Purge requires --acknowledge-unknown-locks; undeployed repository locks are not discoverable."
+          );
+        }
+        const authority = await resolveTeamAuthority(options, ["icons:write"], dependencies);
+        if (!authority) return;
+        if (authority.team && `@${authority.team.slug}` !== confirmation.team) {
+          return emitFailure(
+            options.json,
+            "purge_confirmation_mismatch",
+            "Purge confirmation must name the selected Team."
+          );
+        }
+        const response = await authorizedTeamRequest(
+          authority,
+          `/v1/icon-sets/${encodeURIComponent(slug)}/versions/${encodeURIComponent(options.version)}/purge`,
+          "POST",
+          {
+            body: JSON.stringify({
+              acknowledgeUnknownLocks: true,
+              confirmation: options.confirm
+            }),
+            headers: {
+              "Content-Type": "application/json",
+              "Idempotency-Key": options.idempotencyKey
+            }
+          }
+        );
+        if (!response.ok) return emitHttpFailure(options.json, response.status, "purge");
+        const parsed = purgeResponseSchema.parse(response.body);
+        const document = {
+          command: "icon-set purge",
+          result: parsed.result,
+          schemaVersion: 1,
+          team: describeTeam(authority)
+        };
+        if (options.json) return emitJson(document);
+        console.log(`${pc2.green("\u2713")} Purged ${pc2.bold(options.confirm)}.`);
+        console.log(pc2.yellow(`! ${parsed.result.warning}`));
+      } catch (error) {
+        emitFailure(options.json, "icon_set_purge_failed", boundedMessage(error, "purge"));
+      }
+    }
+  );
+  async function readCommand(slug, options, command2, run) {
+    try {
+      if (!isIconSetSlug(slug)) {
+        return emitFailure(options.json, "invalid_icon_set_id", "Icon Set ID is invalid.");
+      }
+      const authority = await resolveTeamAuthority(options, ["icons:read"], dependencies);
+      if (!authority) return;
+      const result = await run(authority);
+      if ("status" in result) return emitHttpFailure(options.json, result.status, command2);
+      const document = {
+        command: command2,
+        schemaVersion: 1,
+        team: describeTeam(authority),
+        ...result.value
+      };
+      if (options.json) return emitJson(document);
+      process.stdout.write(`${JSON.stringify(document, null, 2)}
+`);
+    } catch (error) {
+      emitFailure(
+        options.json,
+        `${command2.replaceAll(/[^a-z]+/gu, "_")}_failed`,
+        boundedMessage(error, command2)
+      );
+    }
+  }
+}
+function withTeamOptions(command2) {
+  return command2.option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON");
+}
+async function readAllPages(authority, path, query, schema, select, identify) {
+  const items = [];
+  const seenCursors = /* @__PURE__ */ new Set();
+  const seenIds = /* @__PURE__ */ new Set();
+  let cursor = null;
+  for (let page = 0; page < maximumCatalogPages; page += 1) {
+    const parameters = new URLSearchParams({ limit: String(pageSize), ...query });
+    if (cursor) parameters.set("cursor", cursor);
+    const response = await authorizedTeamRequest(
+      authority,
+      `${path}?${parameters.toString()}`,
+      "GET"
+    );
+    if (!response.ok) throw new IconSetTransportError(response.status);
+    const parsed = schema.parse(response.body);
+    for (const item of select(parsed)) {
+      const id = identify(item);
+      if (seenIds.has(id)) throw new Error("Icon Set list returned a duplicate row.");
+      seenIds.add(id);
+      items.push(item);
+    }
+    cursor = parsed.nextCursor ?? null;
+    if (!cursor) return items;
+    if (seenCursors.has(cursor)) throw new Error("Icon Set list repeated a cursor.");
+    seenCursors.add(cursor);
+  }
+  throw new Error("Icon Set list exceeded its safe page limit.");
+}
+var IconSetTransportError = class extends Error {
+  constructor(status) {
+    super(`Icon Set request failed (${status}).`);
+    this.status = status;
+    this.name = "IconSetTransportError";
+  }
+  status;
+};
+function emitHttpFailure(json, status, command2) {
+  emitFailure(json, `http_${status}`, `Icon Set ${command2} failed (${status}).`);
+}
+function boundedMessage(error, command2) {
+  if (error instanceof IconSetTransportError) return error.message;
+  if (error instanceof Error && /limit|cursor|duplicate row/u.test(error.message)) {
+    return error.message;
+  }
+  return `Icon Set ${command2} failed.`;
+}
+function describeTeam(authority) {
+  return authority.team ? { id: authority.team.id, slug: authority.team.slug } : null;
+}
+function describeRevision(revision) {
+  return {
+    iconCount: revision.iconCount,
+    id: revision.id,
+    packageId: revision.packageId,
+    publishedAt: revision.publishedAt,
+    purgedAt: revision.purgedAt,
+    reference: revision.reference,
+    totalBytes: revision.totalBytes,
+    version: revision.version
+  };
+}
+function normalizeLocalDirectory(value) {
+  if (!value || isAbsolute2(value) || value.includes("\\") || /[\p{Cc}]/u.test(value)) return null;
+  const normalized = value.startsWith("./") || value.startsWith("../") ? value : `./${value}`;
+  return normalized.replace(/\/+$/u, "");
+}
+function parsePurgeConfirmation(value) {
+  const separator = value.lastIndexOf("@");
+  if (separator <= 0 || value.length > 160) return null;
+  const reference = value.slice(0, separator);
+  const version = value.slice(separator + 1);
+  if (!tileflowIconSetReferenceSchema.safeParse(reference).success) return null;
+  if (!/^[1-9][0-9]*$/u.test(version) || !Number.isSafeInteger(Number(version))) return null;
+  return { slug: reference.split("/")[1], team: reference.split("/")[0], version: Number(version) };
+}
+function isIconSetSlug(value) {
+  return value.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value);
+}
+function isIdempotencyKey(value) {
+  return value.length >= 8 && value.length <= 128 && /^[A-Za-z0-9._:-]+$/u.test(value);
+}
+var cursorSchema = z5.string().min(1).max(2048).nullable();
+var isoDateSchema = z5.iso.datetime({ offset: true });
+var setSchema = z5.object({
+  id: z5.string().regex(/^ics_[A-Za-z0-9_-]{16}$/u),
+  reference: tileflowIconSetReferenceSchema,
+  name: z5.string().max(200),
+  description: z5.string().max(2e3),
+  archivedAt: isoDateSchema.nullable(),
+  latestVersion: z5.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
+  createdAt: isoDateSchema,
+  updatedAt: isoDateSchema
+}).strict();
+var revisionBaseSchema = z5.object({
+  id: z5.string().regex(/^icv_[A-Za-z0-9_-]{16}$/u),
+  reference: tileflowIconSetReferenceSchema,
+  version: z5.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  publishedAt: isoDateSchema,
+  purgedAt: isoDateSchema.nullable(),
+  iconCount: z5.number().int().min(0).max(256),
+  totalBytes: z5.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  publisher: z5.object({ kind: z5.enum(["credential", "membership"]), id: z5.string().max(200).nullable() }).strict()
+}).strict();
+var revisionSchema = revisionBaseSchema.extend({ pin: tileflowIconSetPinSchema.nullable() }).transform(({ id, reference, version, publishedAt, purgedAt, iconCount, totalBytes, pin }) => ({
+  iconCount,
+  id,
+  pin,
+  publishedAt,
+  purgedAt,
+  reference,
+  totalBytes,
+  version
+}));
+var revisionSummarySchema = revisionBaseSchema.extend({ packageId: tileflowIconSetPackageIdSchema.nullable() }).transform(
+  ({ id, reference, version, publishedAt, purgedAt, iconCount, totalBytes, packageId }) => ({
+    iconCount,
+    id,
+    packageId,
+    publishedAt,
+    purgedAt,
+    reference,
+    totalBytes,
+    version
+  })
+);
+var catalogListResponseSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  sets: z5.array(setSchema).max(pageSize),
+  nextCursor: cursorSchema.optional()
+}).strict();
+var catalogDetailResponseSchema = z5.object({ schemaVersion: z5.literal(1), set: setSchema }).strict();
+var versionsResponseSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  versions: z5.array(revisionSummarySchema).max(pageSize),
+  nextCursor: cursorSchema.optional()
+}).strict();
+var revisionResponseSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  archived: z5.boolean(),
+  revision: revisionSchema
+}).strict();
+var publishResponseSchema = z5.object({ schemaVersion: z5.literal(1), changed: z5.boolean(), revision: revisionSchema }).strict();
+var usesResponseSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  uses: z5.array(
+    z5.object({
+      deploymentId: z5.string().min(1).max(160),
+      deploymentVersion: z5.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+      mapId: z5.string().min(1).max(160),
+      mapName: z5.string().max(200).nullable(),
+      mapState: z5.string().max(64),
+      versionId: z5.string().regex(/^icv_[A-Za-z0-9_-]{16}$/u),
+      version: z5.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+      ordinal: z5.number().int().min(0).max(31),
+      relationship: z5.enum(["active", "retained"])
+    }).strict()
+  ).max(pageSize),
+  nextCursor: cursorSchema.optional(),
+  coverage: z5.literal("known-hosted-deployments"),
+  includesUndeployedRepositoryLocks: z5.literal(false)
+}).strict();
+var purgeResponseSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  result: z5.object({
+    schemaVersion: z5.literal(1),
+    versionId: z5.string().regex(/^icv_[A-Za-z0-9_-]{16}$/u),
+    version: z5.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    purged: z5.boolean(),
+    knownRetainedDeployments: z5.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    physicalBytesReleased: z5.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+    unknownRepositoryLocks: z5.boolean(),
+    warning: z5.string().max(400)
+  }).strict()
+}).strict();
+
+// src/icon-lock-command.ts
+function registerIconLockCommands(program2, dependencies) {
+  const icons = program2.commands.find((command2) => command2.name() === "icons") ?? program2.command("icons").description("Inspect managed Tileflow icons");
+  withLockOptions(
+    icons.command("install").description("Lock every declared Icon Set reference that has no exact pin yet").argument("[references...]", "declared @team/set references; omit for every declared set"),
+    dependencies
+  ).action(async (references, options) => {
+    await maintainLock("install", references, options);
+  });
+  withLockOptions(
+    icons.command("update").description("Move selected declared Icon Set references to their current latest revision").argument("[references...]", "declared @team/set references; omit for every declared set"),
+    dependencies
+  ).action(async (references, options) => {
+    await maintainLock("update", references, options);
+  });
+  withLockOptions(
+    icons.command("pin").description("Lock one declared Icon Set reference to one exact revision").argument("<reference>", "declared @team/set reference").requiredOption("--version <version>", "exact positive revision"),
+    dependencies
+  ).action(async (reference, options) => {
+    if (!/^[1-9][0-9]*$/u.test(options.version) || !Number.isSafeInteger(+options.version)) {
+      return emitFailure(
+        options.json,
+        "invalid_icon_set_version",
+        "Pin requires one exact positive revision."
+      );
+    }
+    await maintainLock("pin", [reference], options, Number(options.version));
+  });
+  async function maintainLock(operation, requested, options, version) {
+    let declared;
+    let baseDirectory;
+    try {
+      const loaded = await withTileflowConfigSecretsHidden(
+        () => loadValidTileflowConfigWithInputs3(options.config)
+      );
+      baseDirectory = dirname8(loaded.configFile);
+      declared = collectDeclaredReferences(loaded.project);
+    } catch (error) {
+      return emitFailure(
+        options.json,
+        error instanceof TileflowValidationError4 ? "config_invalid" : "config_load_failed",
+        error instanceof TileflowValidationError4 ? "Tileflow config has errors." : "Tileflow config could not be loaded."
+      );
+    }
+    const selection = selectReferences(operation, requested, declared);
+    if ("error" in selection) {
+      return emitFailure(options.json, selection.error.code, selection.error.message);
+    }
+    let expected;
+    let current;
+    try {
+      expected = await readTileflowIconsLockfileText(baseDirectory);
+      current = expected === null ? {} : await readCurrentPins(expected);
+    } catch {
+      return emitFailure(
+        options.json,
+        "icon_lock_unreadable",
+        `Existing ${tileflowIconsLockfileName} is unreadable; repair or remove it explicitly.`
+      );
+    }
+    const targets = operation === "install" ? selection.selected.filter((reference) => !current[reference]) : selection.selected;
+    if (targets.length === 0 && operation !== "install") {
+      return emitFailure(
+        options.json,
+        "icon_set_not_declared",
+        "Select at least one declared @team/set reference."
+      );
+    }
+    const authority = targets.length === 0 ? null : await resolveTeamAuthority(options, ["icons:read"], dependencies);
+    if (targets.length > 0 && !authority) return;
+    const resolved = {};
+    for (const reference of targets) {
+      const result = await resolvePin(authority, reference, version);
+      if ("error" in result) {
+        return emitFailure(options.json, result.error.code, result.error.message);
+      }
+      resolved[reference] = result.pin;
+    }
+    const sets = {};
+    for (const reference of declared.references) {
+      const pin = resolved[reference] ?? current[reference];
+      if (pin) sets[reference] = pin;
+    }
+    if (expected !== null || Object.keys(sets).length > 0) {
+      try {
+        await writeTileflowIconsLockfile(baseDirectory, { lockfileVersion: 1, sets }, expected);
+      } catch (error) {
+        const code = error !== null && typeof error === "object" && "code" in error ? String(error.code) : "icon_lock_write_failed";
+        return emitFailure(
+          options.json,
+          code,
+          code === "ICON_LOCK_CONFLICT" ? "The icon lock changed while this command ran; rerun it without discarding other pins." : "The icon lock could not be written."
+        );
+      }
+    }
+    const missing = declared.references.filter((reference) => !sets[reference]);
+    const document = {
+      command: `icons ${operation}`,
+      lockfile: tileflowIconsLockfileName,
+      missing,
+      schemaVersion: 1,
+      sets: declared.references.filter((reference) => sets[reference]).map((reference) => ({
+        changed: Boolean(resolved[reference]),
+        contentHash: sets[reference].contentHash,
+        packageId: sets[reference].packageId,
+        reference,
+        version: sets[reference].version,
+        versionId: sets[reference].versionId
       }))
+    };
+    if (options.json) return emitJson(document);
+    if (document.sets.length === 0) return console.log(pc3.gray("No Icon Set references declared."));
+    for (const entry of document.sets) {
+      console.log(
+        `  ${pc3.bold(entry.reference)} ${pc3.gray(`v${String(entry.version)}`)}${entry.changed ? "" : pc3.gray(" (unchanged)")}`
+      );
+    }
+    for (const reference of missing) {
+      console.log(pc3.yellow(`! ${reference} is declared but not locked.`));
+    }
+  }
+  async function resolvePin(authority, reference, version) {
+    const slug = reference.split("/")[1];
+    const selector = version === void 0 ? "latest" : String(version);
+    const response = await authorizedTeamRequest(
+      authority,
+      `/v1/icon-sets/${encodeURIComponent(slug)}/versions/${encodeURIComponent(selector)}`,
+      "GET"
+    );
+    if (!response.ok) {
+      return {
+        error: {
+          code: `http_${response.status}`,
+          message: `Resolving ${reference}@${selector} failed (${response.status}).`
+        }
+      };
+    }
+    const parsed = revisionResponseSchema.safeParse(response.body);
+    if (!parsed.success) {
+      return {
+        error: {
+          code: "icon_set_response_invalid",
+          message: `Resolving ${reference}@${selector} returned an invalid response.`
+        }
+      };
+    }
+    const revision = parsed.data.revision;
+    if (revision.reference !== reference) {
+      return {
+        error: {
+          code: "icon_set_reference_mismatch",
+          message: `Resolving ${reference} returned a different Icon Set.`
+        }
+      };
+    }
+    if (!revision.pin || revision.purgedAt !== null) {
+      return {
+        error: {
+          code: "icon_set_revision_unavailable",
+          message: `${reference}@${selector} has no retained delivery artifact.`
+        }
+      };
+    }
+    if (version !== void 0 && revision.version !== version) {
+      return {
+        error: {
+          code: "icon_set_revision_mismatch",
+          message: `${reference}@${selector} returned revision ${revision.version}.`
+        }
+      };
+    }
+    if (authority.team && revision.pin.teamId !== authority.team.id) {
+      return {
+        error: {
+          code: "icon_set_team_mismatch",
+          message: `${reference} is owned by a different Team.`
+        }
+      };
+    }
+    return { pin: revision.pin };
+  }
+}
+function withLockOptions(command2, dependencies) {
+  return command2.option("-c, --config <path>", "config path", dependencies.defaultConfigPath).option("--team <team>", "target Team as @team").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Team data API key", process.env.TILEFLOW_API_KEY).option("--json", "print deterministic schema-version-1 JSON");
+}
+function collectDeclaredReferences(project) {
+  const references = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const mapName of getTileflowMapNames3(project).sort(compareCodeUnits7)) {
+    const sources = parseResolvedTileflowMap2(project.maps[mapName]).icons ?? [];
+    for (const reference of collectTileflowIconSetReferences(sources)) {
+      if (seen.has(reference)) continue;
+      seen.add(reference);
+      references.push(reference);
+    }
+  }
+  return { references: references.sort(compareCodeUnits7) };
+}
+function selectReferences(operation, requested, declared) {
+  if (requested.length === 0) {
+    if (operation === "pin") {
+      return { error: { code: "icon_set_not_selected", message: "Pin one @team/set reference." } };
+    }
+    return { selected: [...declared.references] };
+  }
+  const selected = [];
+  for (const reference of requested) {
+    if (!tileflowIconSetReferenceSchema2.safeParse(reference).success) {
+      return {
+        error: {
+          code: "invalid_icon_set_reference",
+          message: `${reference} is not a canonical @team/set reference.`
+        }
+      };
+    }
+    if (!declared.references.includes(reference)) {
+      return {
+        error: {
+          code: "icon_set_not_declared",
+          message: `${reference} is not declared by any map; add iconSet('${reference}') first.`
+        }
+      };
+    }
+    if (!selected.includes(reference)) {
+      selected.push(reference);
     }
-  };
-}
-function sameStrings(left, right) {
-  return left.length === right.length && left.every((value, index) => value === right[index]);
-}
-function printIconListError(error) {
-  if (error instanceof TileflowValidationError3) {
-    printIssues("Tileflow config has errors.", error.messages);
-    return;
-  }
-  if (error instanceof TileflowIconCompilationError2) {
-    printIssues("Tileflow icon catalog has errors.", error.issues);
-    return;
   }
-  console.error(error instanceof Error ? error.message : "Icon catalog listing failed.");
+  return { selected: selected.sort(compareCodeUnits7) };
 }
-function printIssues(heading, issues) {
-  console.error(
-    [heading, ...issues.map((issue) => `- ${issue.path || "(root)"}: ${issue.message}`)].join("\n")
-  );
+async function readCurrentPins(contents) {
+  return (await parseTileflowIconsLockfile(contents)).sets;
 }
 
 // src/language-command.ts
 import { readFile as readFile4 } from "fs/promises";
 import { fileURLToPath } from "url";
 import {
-  serializeCanonicalJson,
+  serializeCanonicalJson as serializeCanonicalJson2,
   tileflowAuthoringManifest
 } from "@tileflow/core";
 import {
@@ -3778,7 +4711,7 @@ async function runLanguageCommand(command2, options, operation) {
 }
 function printManifest(manifest, options) {
   if (options.json) {
-    process.stdout.write(`${serializeCanonicalJson(manifest)}
+    process.stdout.write(`${serializeCanonicalJson2(manifest)}
 `);
     return;
   }
@@ -3789,7 +4722,7 @@ function printManifest(manifest, options) {
 }
 function printSchema(schema, options) {
   if (options.json) {
-    process.stdout.write(`${serializeCanonicalJson(schema)}
+    process.stdout.write(`${serializeCanonicalJson2(schema)}
 `);
     return;
   }
@@ -3841,7 +4774,7 @@ function resolveTileflowExternalOpenInvocation(target, platform) {
 }
 
 // src/project-commands.ts
-import pc from "picocolors";
+import pc4 from "picocolors";
 function registerProjectCommands(program2, dependencies) {
   const projects = program2.command("projects", { hidden: true }).description("Manage internal application destinations");
   projects.command("list").description("List application destinations accessible to the authenticated Tileflow account").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--include-archived", "include archived application destinations").option("--json", "print deterministic schema-version-1 JSON").action(async (options) => {
@@ -3855,14 +4788,14 @@ function registerProjectCommands(program2, dependencies) {
       command: "projects list",
       projects: result.items
     };
-    if (options.json) return emitJson(document);
+    if (options.json) return emitJson2(document);
     if (!result.items.length) {
-      console.log(pc.gray("No managed destinations found."));
+      console.log(pc4.gray("No managed destinations found."));
       return;
     }
     for (const target of result.items) {
       console.log(
-        `  ${target.project.archivedAt ? pc.yellow("\u25CB") : pc.green("\u25CF")} ${pc.bold(target.project.name)} ${pc.gray(target.reference)}${target.project.archivedAt ? pc.gray(" (archived)") : ""}`
+        `  ${target.project.archivedAt ? pc4.yellow("\u25CB") : pc4.green("\u25CF")} ${pc4.bold(target.project.name)} ${pc4.gray(target.reference)}${target.project.archivedAt ? pc4.gray(" (archived)") : ""}`
       );
     }
   });
@@ -3914,9 +4847,9 @@ function registerProjectCommands(program2, dependencies) {
         command: "projects create",
         ...asRecord2(result.body)
       };
-      if (options.json) return emitJson(document);
-      console.log(`${pc.green("\u2713")} Application ${pc.bold(options.name.trim())} is ready.`);
-      console.log(pc.gray(`Its technical selector is --project @${organization.slug}/${slug}.`));
+      if (options.json) return emitJson2(document);
+      console.log(`${pc4.green("\u2713")} Application ${pc4.bold(options.name.trim())} is ready.`);
+      console.log(pc4.gray(`Its technical selector is --project @${organization.slug}/${slug}.`));
     }
   );
   projects.command("show <target>").description("Show one application destination").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--json", "print deterministic schema-version-1 JSON").action(async (target, options) => {
@@ -3933,13 +4866,13 @@ function registerProjectCommands(program2, dependencies) {
     );
     if (!result.ok) return emitRemoteFailure(options.json, result);
     const document = { schemaVersion: 1, command: "projects show", ...asRecord2(result.body) };
-    if (options.json) return emitJson(document);
+    if (options.json) return emitJson2(document);
     const project = asRecord2(result.body).project;
     if (!isProjectItem(project)) {
       return emitLocalFailure(false, "invalid_response", "Destination response was invalid.");
     }
-    console.log(`${pc.bold(project.name)} ${pc.gray(target)}`);
-    console.log(project.archivedAt ? pc.yellow("Archived") : pc.green("Active"));
+    console.log(`${pc4.bold(project.name)} ${pc4.gray(target)}`);
+    console.log(project.archivedAt ? pc4.yellow("Archived") : pc4.green("Active"));
   });
   for (const archived of [true, false]) {
     const verb = archived ? "archive" : "unarchive";
@@ -3965,8 +4898,8 @@ function registerProjectCommands(program2, dependencies) {
         command: `projects ${verb}`,
         ...asRecord2(result.body)
       };
-      if (options.json) return emitJson(document);
-      console.log(`${pc.green("\u2713")} Application ${archived ? "archived" : "unarchived"}.`);
+      if (options.json) return emitJson2(document);
+      console.log(`${pc4.green("\u2713")} Application ${archived ? "archived" : "unarchived"}.`);
     });
   }
 }
@@ -4008,7 +4941,7 @@ async function requireCommandSession(options, dependencies) {
   try {
     config = await dependencies.loadAuthConfig();
   } catch (error) {
-    emitLocalFailure(options.json, "auth_state_unavailable", safeMessage(error));
+    emitLocalFailure(options.json, "auth_state_unavailable", safeMessage2(error));
     return null;
   }
   const resolved = resolveAccountSession(config, options.apiUrl ?? dependencies.defaultApiUrl);
@@ -4087,13 +5020,13 @@ function emitRemoteFailure(json, result) {
 function emitLocalFailure(json, code, message, details = {}) {
   if (json) {
     console.error(message);
-    emitJson({ schemaVersion: 1, ok: false, error: { code, ...details } });
+    emitJson2({ schemaVersion: 1, ok: false, error: { code, ...details } });
   } else {
-    console.error(`${pc.red("\u2715")} ${message}`);
+    console.error(`${pc4.red("\u2715")} ${message}`);
   }
   process.exitCode = 1;
 }
-function emitJson(value) {
+function emitJson2(value) {
   process.stdout.write(`${JSON.stringify(value)}
 `);
 }
@@ -4119,21 +5052,21 @@ function validName(value) {
   const normalized = value.trim();
   return normalized.length > 0 && normalized.length <= 200 && !/[\p{Cc}]/u.test(normalized);
 }
-function safeMessage(error) {
+function safeMessage2(error) {
   return error instanceof Error && error.message.length <= 300 ? error.message : "Tileflow auth state is unavailable.";
 }
 
 // src/tileset-command.ts
-import pc2 from "picocolors";
-import { serializeCanonicalJson as serializeCanonicalJson3 } from "@tileflow/core";
+import pc5 from "picocolors";
+import { serializeCanonicalJson as serializeCanonicalJson4 } from "@tileflow/core";
 import { inspectTileflowPmtiles } from "@tileflow/dev/tilesets";
-import { z as z6 } from "zod";
+import { z as z7 } from "zod";
 
 // src/tileset-upload.ts
 import { createHash } from "crypto";
 import { open as open4, stat } from "fs/promises";
-import { z as z5 } from "zod";
-import { serializeCanonicalJson as serializeCanonicalJson2 } from "@tileflow/core";
+import { z as z6 } from "zod";
+import { serializeCanonicalJson as serializeCanonicalJson3 } from "@tileflow/core";
 var teamTilesetPartSize = 16777216;
 var maximumTeamTilesetBytes = 4e9;
 var authorizationBatchSize = 16;
@@ -4273,7 +5206,7 @@ async function prepareTeamTilesetUpload(file) {
   };
   return Object.freeze({
     byteCount: identity.size,
-    contentHash: createHash("sha256").update(serializeCanonicalJson2(contentIdentity)).digest("hex"),
+    contentHash: createHash("sha256").update(serializeCanonicalJson3(contentIdentity)).digest("hex"),
     contentHashAlgorithm: "sha256-fixed-parts-v1",
     identity,
     partSize: teamTilesetPartSize,
@@ -4289,7 +5222,7 @@ function createTeamTilesetUploadIdempotencyKey(tilesetId, upload) {
     );
   }
   return createHash("sha256").update(
-    serializeCanonicalJson2({
+    serializeCanonicalJson3({
       byteCount: upload.byteCount,
       contentHash: upload.contentHash,
       contentHashAlgorithm: upload.contentHashAlgorithm,
@@ -4695,34 +5628,34 @@ function asRecord3(value) {
 function defaultSleep(milliseconds) {
   return new Promise((resolve8) => setTimeout(resolve8, milliseconds));
 }
-var identifierSchema = z5.string().min(20).max(80).regex(/^[A-Za-z0-9_-]+$/u);
-var uploadPartStatusSchema = z5.object({
-  byteCount: z5.number().int().min(1).max(teamTilesetPartSize),
-  partNumber: z5.number().int().min(1).max(239),
-  uploaded: z5.boolean(),
-  validationState: z5.enum(["mismatch", "pending", "processing", "valid"])
+var identifierSchema = z6.string().min(20).max(80).regex(/^[A-Za-z0-9_-]+$/u);
+var uploadPartStatusSchema = z6.object({
+  byteCount: z6.number().int().min(1).max(teamTilesetPartSize),
+  partNumber: z6.number().int().min(1).max(239),
+  uploaded: z6.boolean(),
+  validationState: z6.enum(["mismatch", "pending", "processing", "valid"])
 }).strict();
-var publishedVersionSchema = z5.object({
-  byteCount: z5.number().int().min(1).max(maximumTeamTilesetBytes),
-  contentHash: z5.string().regex(/^[0-9a-f]{64}$/u),
-  contentHashAlgorithm: z5.literal("sha256-fixed-parts-v1"),
-  publishedVersion: z5.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  schemaVersion: z5.literal(1),
-  state: z5.literal("published"),
+var publishedVersionSchema = z6.object({
+  byteCount: z6.number().int().min(1).max(maximumTeamTilesetBytes),
+  contentHash: z6.string().regex(/^[0-9a-f]{64}$/u),
+  contentHashAlgorithm: z6.literal("sha256-fixed-parts-v1"),
+  publishedVersion: z6.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  schemaVersion: z6.literal(1),
+  state: z6.literal("published"),
   versionId: identifierSchema.regex(/^tsv_[A-Za-z0-9_-]+$/u)
 }).strict();
-var uploadControlSchema = z5.object({
-  byteCount: z5.number().int().min(1).max(maximumTeamTilesetBytes),
-  contentHash: z5.string().regex(/^[0-9a-f]{64}$/u),
-  contentHashAlgorithm: z5.literal("sha256-fixed-parts-v1"),
-  expiresAt: z5.iso.datetime({ offset: true }),
-  failure: z5.object({ code: z5.string().regex(/^TF_[A-Z0-9_]{1,96}$/u) }).strict().nullable(),
-  partCount: z5.number().int().min(1).max(239),
-  parts: z5.array(uploadPartStatusSchema).max(239),
-  partSize: z5.literal(teamTilesetPartSize),
-  publishedVersion: z5.null(),
-  schemaVersion: z5.literal(1),
-  state: z5.enum([
+var uploadControlSchema = z6.object({
+  byteCount: z6.number().int().min(1).max(maximumTeamTilesetBytes),
+  contentHash: z6.string().regex(/^[0-9a-f]{64}$/u),
+  contentHashAlgorithm: z6.literal("sha256-fixed-parts-v1"),
+  expiresAt: z6.iso.datetime({ offset: true }),
+  failure: z6.object({ code: z6.string().regex(/^TF_[A-Z0-9_]{1,96}$/u) }).strict().nullable(),
+  partCount: z6.number().int().min(1).max(239),
+  parts: z6.array(uploadPartStatusSchema).max(239),
+  partSize: z6.literal(teamTilesetPartSize),
+  publishedVersion: z6.null(),
+  schemaVersion: z6.literal(1),
+  state: z6.enum([
     "aborted",
     "aborting",
     "expired",
@@ -4735,32 +5668,32 @@ var uploadControlSchema = z5.object({
     "uploading",
     "validating"
   ]),
-  uploadId: z5.string().min(20).max(80).regex(/^tsu_[A-Za-z0-9_-]+$/u),
-  versionId: z5.null()
+  uploadId: z6.string().min(20).max(80).regex(/^tsu_[A-Za-z0-9_-]+$/u),
+  versionId: z6.null()
 }).strict();
-var uploadSessionSchema = z5.union([publishedVersionSchema, uploadControlSchema]);
-var authorizationSchema = z5.object({
-  expiresAt: z5.iso.datetime({ offset: true }),
-  headers: z5.object({
-    "Content-Length": z5.string().regex(/^[1-9][0-9]{0,9}$/u),
-    "Content-MD5": z5.string().regex(/^[A-Za-z0-9+/]{22}==$/u)
+var uploadSessionSchema = z6.union([publishedVersionSchema, uploadControlSchema]);
+var authorizationSchema = z6.object({
+  expiresAt: z6.iso.datetime({ offset: true }),
+  headers: z6.object({
+    "Content-Length": z6.string().regex(/^[1-9][0-9]{0,9}$/u),
+    "Content-MD5": z6.string().regex(/^[A-Za-z0-9+/]{22}==$/u)
   }).strict(),
-  method: z5.literal("PUT"),
-  partNumber: z5.number().int().min(1).max(239),
-  url: z5.url().max(8192).refine((value) => {
+  method: z6.literal("PUT"),
+  partNumber: z6.number().int().min(1).max(239),
+  url: z6.url().max(8192).refine((value) => {
     const url = new URL(value);
     return url.protocol === "https:" && !url.username && !url.password && !url.hash;
   })
 }).strict();
-var authorizationResponseSchema = z5.object({
-  authorizations: z5.array(authorizationSchema).min(1).max(16),
-  schemaVersion: z5.literal(1)
+var authorizationResponseSchema = z6.object({
+  authorizations: z6.array(authorizationSchema).min(1).max(16),
+  schemaVersion: z6.literal(1)
 }).strict();
-var partReceiptResponseSchema = z5.object({
-  changed: z5.boolean(),
-  etag: z5.string().regex(/^[0-9a-f]{32}$/u),
-  partNumber: z5.number().int().min(1).max(239),
-  schemaVersion: z5.literal(1)
+var partReceiptResponseSchema = z6.object({
+  changed: z6.boolean(),
+  etag: z6.string().regex(/^[0-9a-f]{32}$/u),
+  partNumber: z6.number().int().min(1).max(239),
+  schemaVersion: z6.literal(1)
 }).strict();
 
 // src/tileset-command.ts
@@ -4780,11 +5713,11 @@ function registerTilesetCommands(program2, dependencies) {
           sample: options.sample
         });
         if (options.json) {
-          process.stdout.write(`${serializeCanonicalJson3(inspection)}
+          process.stdout.write(`${serializeCanonicalJson4(inspection)}
 `);
           return;
         }
-        console.log(`${pc2.green("\u2713")} PMTiles archive is valid.`);
+        console.log(`${pc5.green("\u2713")} PMTiles archive is valid.`);
         console.log(`  Type: ${inspection.contract.tileType}`);
         console.log(`  Zooms: ${inspection.contract.minzoom}-${inspection.contract.maxzoom}`);
         console.log(`  Source layers: ${inspection.contract.sourceLayers.length}`);
@@ -4794,7 +5727,7 @@ function registerTilesetCommands(program2, dependencies) {
           );
         }
         for (const warning of inspection.warnings) {
-          console.log(`${pc2.yellow("!")} ${warning.message}`);
+          console.log(`${pc5.yellow("!")} ${warning.message}`);
         }
       } catch (error) {
         const record = asRecord4(error);
@@ -4803,11 +5736,11 @@ function registerTilesetCommands(program2, dependencies) {
         const message = error instanceof Error ? error.message : "Tileset inspection failed.";
         if (options.json) {
           process.stderr.write(
-            `${serializeCanonicalJson3({ error: { code, message, path }, ok: false, schemaVersion: 1 })}
+            `${serializeCanonicalJson4({ error: { code, message, path }, ok: false, schemaVersion: 1 })}
 `
           );
         } else {
-          console.error(`${pc2.red("Error:")} ${message}`);
+          console.error(`${pc5.red("Error:")} ${message}`);
         }
         process.exitCode = 1;
       }
@@ -4889,9 +5822,9 @@ function registerTilesetCommands(program2, dependencies) {
             version: { id: publication.versionId, number: publication.version }
           }
         };
-        if (options.json) return emitJson2(document);
+        if (options.json) return emitJson(document);
         console.log(
-          `${pc2.green("\u2713")} ${publication.changed ? "Published" : "Unchanged"} ${pc2.bold(options.id)} in ${authority.team ? `@${authority.team.slug}` : "the Team bound to the data key"}.`
+          `${pc5.green("\u2713")} ${publication.changed ? "Published" : "Unchanged"} ${pc5.bold(options.id)} in ${authority.team ? `@${authority.team.slug}` : "the Team bound to the data key"}.`
         );
       } catch (error) {
         if (error instanceof TeamTilesetUploadError) {
@@ -4910,10 +5843,10 @@ function registerTilesetCommands(program2, dependencies) {
       if (!authority) return;
       const items = await fetchAllTeamTilesets(authority);
       const document = { command: "tileset list", schemaVersion: 1, tilesets: items };
-      if (options.json) return emitJson2(document);
-      if (items.length === 0) return console.log(pc2.gray("No Team tilesets."));
+      if (options.json) return emitJson(document);
+      if (items.length === 0) return console.log(pc5.gray("No Team tilesets."));
       for (const item of items) {
-        console.log(`  ${pc2.bold(item.logicalName)} ${pc2.gray(item.status)}`);
+        console.log(`  ${pc5.bold(item.logicalName)} ${pc5.gray(item.status)}`);
       }
     } catch {
       emitFailure(options.json, "tileset_list_failed", "Tileset list failed.");
@@ -4939,9 +5872,9 @@ function registerTilesetCommands(program2, dependencies) {
       }
       const parsed = tilesetDetailResponseSchema.parse(response.body);
       const document = { command: "tileset status", schemaVersion: 1, tileset: parsed.tileset };
-      if (options.json) return emitJson2(document);
+      if (options.json) return emitJson(document);
       const item = parsed.tileset;
-      console.log(`${pc2.bold(item.name)} ${pc2.gray(item.state)}`);
+      console.log(`${pc5.bold(item.name)} ${pc5.gray(item.state)}`);
       console.log(`  ID: ${item.id}`);
       console.log(`  Current version: ${String(item.currentVersion ?? "unpublished")}`);
     } catch {
@@ -4991,90 +5924,13 @@ function registerTilesetCommands(program2, dependencies) {
       }
       const parsed = tilesetPurgeResponseSchema.parse(response.body);
       const document = { command: "tileset purge", schemaVersion: 1, ...parsed };
-      if (options.json) return emitJson2(document);
-      console.log(`${pc2.green("\u2713")} Purge ${parsed.reclamation}.`);
+      if (options.json) return emitJson(document);
+      console.log(`${pc5.green("\u2713")} Purge ${parsed.reclamation}.`);
     } catch {
       emitFailure(options.json, "tileset_purge_failed", "Tileset purge failed.");
     }
   });
 }
-async function resolveTeamAuthority(options, scopes, dependencies) {
-  let apiOrigin;
-  try {
-    apiOrigin = normalizeApiOrigin(options.apiUrl ?? dependencies.defaultApiUrl);
-  } catch (error) {
-    emitFailure(options.json, "invalid_api_url", safeMessage2(error));
-    return null;
-  }
-  if (options.apiKey) {
-    if (!/^tf_live_[0-9a-f]{48}$/u.test(options.apiKey)) {
-      emitFailure(options.json, "invalid_team_data_key", "Team data API key is invalid.");
-      return null;
-    }
-    if (options.team) {
-      emitFailure(
-        options.json,
-        "team_selector_with_api_key",
-        "A Team data key already selects its Team; omit --team."
-      );
-      return null;
-    }
-    return { apiOrigin, credential: options.apiKey, team: null };
-  }
-  let config;
-  try {
-    config = await dependencies.loadAuthConfig();
-  } catch (error) {
-    emitFailure(options.json, "auth_state_unavailable", safeMessage2(error));
-    return null;
-  }
-  const selected = resolveAccountSession(config, options.apiUrl ?? dependencies.defaultApiUrl);
-  if (selected.kind !== "selected") {
-    emitFailure(
-      options.json,
-      `account_session_${selected.kind}`,
-      selected.kind === "expired" ? "Account session expired. Run tileflow login." : "Run tileflow login."
-    );
-    return null;
-  }
-  const discovered = await listAccountTeams(selected.session);
-  if (!discovered.ok) {
-    emitFailure(options.json, "team_discovery_failed", discovered.error);
-    return null;
-  }
-  const requested = options.team ? /^@([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/u.exec(options.team) : null;
-  if (options.team && !requested) {
-    emitFailure(options.json, "invalid_team", "Team must use @team syntax.");
-    return null;
-  }
-  const team = requested ? discovered.teams.find(({ slug }) => slug === requested[1]) : discovered.teams.length === 1 ? discovered.teams[0] : null;
-  if (!team) {
-    const options_ = discovered.teams.map(({ slug }) => `@${slug}`);
-    emitFailure(
-      options.json,
-      options_.length > 1 ? "team_ambiguous" : "team_not_found",
-      options_.length > 1 ? `Choose one Team with --team: ${options_.join(", ")}.` : "No matching Team is available.",
-      { options: options_ }
-    );
-    return null;
-  }
-  const capability = await requestTeamCapability(selected.session, `@${team.slug}`, scopes);
-  if (!capability.ok) {
-    emitFailure(options.json, "team_capability_failed", capability.error);
-    return null;
-  }
-  return {
-    apiOrigin: selected.session.apiOrigin,
-    credential: capability.capability,
-    team
-  };
-}
-function authorizedTeamRequest(authority, path, method) {
-  return requestHostedJson(authority.apiOrigin, path, {
-    headers: { Authorization: `Bearer ${authority.credential}` },
-    method
-  });
-}
 async function fetchAllTeamTilesets(authority) {
   const items = [];
   const seenCursors = /* @__PURE__ */ new Set();
@@ -5111,21 +5967,6 @@ async function fetchAllTeamTilesets(authority) {
   }
   throw new Error("Tileset list exceeded its safe page limit.");
 }
-function emitJson2(value) {
-  process.stdout.write(`${serializeCanonicalJson3(value)}
-`);
-}
-function emitFailure(json, code, message, context = {}) {
-  if (json) {
-    process.stderr.write(
-      `${serializeCanonicalJson3({ error: { code, ...context, message }, ok: false, schemaVersion: 1 })}
-`
-    );
-  } else {
-    console.error(`${pc2.red("Error:")} ${message}`);
-  }
-  process.exitCode = 1;
-}
 function isTilesetId(value) {
   return /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(value) && !["terrain", "world"].includes(value);
 }
@@ -5143,75 +5984,72 @@ function inspectionOptionError(message) {
     path: "includeValues"
   });
 }
-function safeMessage2(error) {
-  return error instanceof Error ? error.message : "Tileset command failed.";
-}
 function asRecord4(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
-var safeIdentifierSchema2 = z6.string().min(1).max(160).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
-var physicalTilesetIdSchema = z6.string().min(20).max(80).regex(/^tls_[A-Za-z0-9_-]+$/u);
-var cursorSchema = z6.string().min(1).max(2048).nullable();
-var tilesetInventoryItemSchema = z6.object({
-  currentVersion: z6.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
-  hasCurrent: z6.boolean(),
+var safeIdentifierSchema2 = z7.string().min(1).max(160).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u);
+var physicalTilesetIdSchema = z7.string().min(20).max(80).regex(/^tls_[A-Za-z0-9_-]+$/u);
+var cursorSchema2 = z7.string().min(1).max(2048).nullable();
+var tilesetInventoryItemSchema = z7.object({
+  currentVersion: z7.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
+  hasCurrent: z7.boolean(),
   id: physicalTilesetIdSchema,
-  logicalName: z6.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
-  name: z6.string().min(1).max(200),
-  retainedBytes: z6.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
-  retainedDeploymentCount: z6.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
-  status: z6.enum(["active", "purging", "retired"]),
-  updatedAt: z6.iso.datetime({ offset: true }),
-  usedByMapCount: z6.number().int().min(0).max(Number.MAX_SAFE_INTEGER)
+  logicalName: z7.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+  name: z7.string().min(1).max(200),
+  retainedBytes: z7.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  retainedDeploymentCount: z7.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  status: z7.enum(["active", "purging", "retired"]),
+  updatedAt: z7.iso.datetime({ offset: true }),
+  usedByMapCount: z7.number().int().min(0).max(Number.MAX_SAFE_INTEGER)
 }).strict();
-var tilesetListResponseSchema = z6.object({
-  nextCursor: cursorSchema.optional(),
-  schemaVersion: z6.literal(1),
-  tilesets: z6.array(tilesetInventoryItemSchema).max(100)
+var tilesetListResponseSchema = z7.object({
+  nextCursor: cursorSchema2.optional(),
+  schemaVersion: z7.literal(1),
+  tilesets: z7.array(tilesetInventoryItemSchema).max(100)
 }).strict();
-var tilesetDependencySchema = z6.object({
-  active: z6.boolean(),
+var tilesetDependencySchema = z7.object({
+  active: z7.boolean(),
   deploymentId: safeIdentifierSchema2,
-  deploymentVersion: z6.number().int().positive().max(Number.MAX_SAFE_INTEGER),
-  environment: z6.string().min(1).max(64),
+  deploymentVersion: z7.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  environment: z7.string().min(1).max(64),
   mapId: safeIdentifierSchema2,
   sourceId: safeIdentifierSchema2
 }).strict();
-var tilesetDetailResponseSchema = z6.object({
-  schemaVersion: z6.literal(1),
-  tileset: z6.object({
-    attribution: z6.string().max(4096).nullable(),
-    currentVersion: z6.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
-    dependencies: z6.array(tilesetDependencySchema).max(25),
-    dependencyNextCursor: cursorSchema,
+var tilesetDetailResponseSchema = z7.object({
+  schemaVersion: z7.literal(1),
+  tileset: z7.object({
+    attribution: z7.string().max(4096).nullable(),
+    currentVersion: z7.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable(),
+    dependencies: z7.array(tilesetDependencySchema).max(25),
+    dependencyNextCursor: cursorSchema2,
     id: physicalTilesetIdSchema,
-    name: z6.string().min(1).max(200),
-    slug: z6.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
-    state: z6.enum(["active", "purging", "purged"])
+    name: z7.string().min(1).max(200),
+    slug: z7.string().min(1).max(128).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u),
+    state: z7.enum(["active", "purging", "purged"])
   }).strict()
 }).strict();
-var purgeDependencySchema = z6.object({
+var purgeDependencySchema = z7.object({
   deploymentId: safeIdentifierSchema2,
   mapId: safeIdentifierSchema2,
   sourceId: safeIdentifierSchema2
 }).strict();
-var tilesetInUseResponseSchema = z6.object({
-  code: z6.literal("TF_TILESET_IN_USE"),
-  dependencies: z6.array(purgeDependencySchema).max(32),
-  error: z6.literal("Tileset is used by retained Map deployments"),
-  nextCursor: cursorSchema
+var tilesetInUseResponseSchema = z7.object({
+  code: z7.literal("TF_TILESET_IN_USE"),
+  dependencies: z7.array(purgeDependencySchema).max(32),
+  error: z7.literal("Tileset is used by retained Map deployments"),
+  nextCursor: cursorSchema2
 }).strict();
-var tilesetPurgeResponseSchema = z6.object({
-  deliveryFence: z6.enum(["complete", "pending"]),
-  pendingVersions: z6.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
-  reclamation: z6.enum(["complete", "pending"]),
-  state: z6.enum(["purged", "purging"]),
+var tilesetPurgeResponseSchema = z7.object({
+  deliveryFence: z7.enum(["complete", "pending"]),
+  pendingVersions: z7.number().int().min(0).max(Number.MAX_SAFE_INTEGER),
+  reclamation: z7.enum(["complete", "pending"]),
+  state: z7.enum(["purged", "purging"]),
   tilesetId: physicalTilesetIdSchema
 }).strict();
 
 // src/visual-command.ts
 import { lstat as lstat4, readFile as readFile6 } from "fs/promises";
-import { dirname as dirname9, isAbsolute as isAbsolute3, parse as parse2, relative as relative4, resolve as resolve6, sep as sep4 } from "path";
+import { dirname as dirname10, isAbsolute as isAbsolute4, parse as parse2, relative as relative4, resolve as resolve6, sep as sep4 } from "path";
 import {
   analyzeTileflowCaptureReference,
   compareTileflowCaptureToBaseline,
@@ -5225,12 +6063,12 @@ import {
   tileflowVisualArtifactLimits,
   validateTileflowVisualReferencePng
 } from "@tileflow/capture";
-import { compareCodeUnits as compareCodeUnits8 } from "@tileflow/core";
+import { compareCodeUnits as compareCodeUnits9 } from "@tileflow/core";
 
 // src/visual-compare-command.ts
 import { createHash as createHash3 } from "crypto";
 import { lstat as lstat3, readFile as readFile5, realpath } from "fs/promises";
-import { basename as basename3, dirname as dirname8, extname, isAbsolute as isAbsolute2, parse, relative as relative3, resolve as resolve5, sep as sep3 } from "path";
+import { basename as basename3, dirname as dirname9, extname, isAbsolute as isAbsolute3, parse, relative as relative3, resolve as resolve5, sep as sep3 } from "path";
 import {
   compareTileflowCapturesForReview,
   createTileflowCaptureSession as createTileflowCaptureSession2,
@@ -5239,9 +6077,9 @@ import {
   tileflowSyntheticAssetOrigin as tileflowSyntheticAssetOrigin2
 } from "@tileflow/capture";
 import {
-  compareCodeUnits as compareCodeUnits7,
+  compareCodeUnits as compareCodeUnits8,
   normalizeTileflowCaptureScene as normalizeTileflowCaptureScene2,
-  parseResolvedTileflowMap as parseResolvedTileflowMap2,
+  parseResolvedTileflowMap as parseResolvedTileflowMap3,
   resolveThemeSelection,
   tileflowCaptureSceneLimits
 } from "@tileflow/core";
@@ -5671,7 +6509,7 @@ async function prepareVisualCompareOutput(plan, leftArtifacts, rightArtifacts, c
       documentPath: relativePath(cwd, plan.output.documentPath),
       reportPath: relativePath(cwd, plan.output.reportPath)
     },
-    warnings: [...warnings].sort(compareCodeUnits7)
+    warnings: [...warnings].sort(compareCodeUnits8)
   };
   const report = renderTileflowVisualCompareReport({
     generatedBy: "Tileflow CLI",
@@ -5959,7 +6797,7 @@ async function runVisualCompareWatch(plan, openReport) {
   }
 }
 function resolveVisualCompareSide(artifacts, config, requestedMap, requestedTheme, role) {
-  const availableMaps = Object.keys(artifacts.project.maps).sort(compareCodeUnits7);
+  const availableMaps = Object.keys(artifacts.project.maps).sort(compareCodeUnits8);
   const map = requestedMap ?? (availableMaps.length === 1 ? availableMaps[0] : void 0);
   if (!map) {
     throw new Error(
@@ -5972,7 +6810,7 @@ function resolveVisualCompareSide(artifacts, config, requestedMap, requestedThem
       `Unknown ${role} map "${map}". Available maps: ${availableMaps.join(", ") || "(none)"}.`
     );
   }
-  const resolvedMap = parseResolvedTileflowMap2(candidate);
+  const resolvedMap = parseResolvedTileflowMap3(candidate);
   const theme = resolveThemeSelection(resolvedMap, requestedTheme).name;
   if (!artifacts.styles[map]?.[theme]) {
     throw new Error(`The ${role} map theme "${map}/${theme}" was not compiled.`);
@@ -6028,7 +6866,7 @@ async function resolveVisualCompareOutput(cwd, value, managed, force, watch, zoo
   if (extname(reportPath).toLowerCase() !== ".html") {
     throw new Error("--report must name an .html file.");
   }
-  const reportDirectory = dirname8(reportPath);
+  const reportDirectory = dirname9(reportPath);
   if (reportDirectory === cwd || reportDirectory === parse(reportPath).root) {
     throw new Error("Visual compare output must use a dedicated subdirectory.");
   }
@@ -6168,7 +7006,7 @@ function createVisualCompareInventory(assetDirectory, assets) {
         throw new Error("Visual compare produced an invalid managed asset path.");
       }
       return { path: relativeAssetPath, sha256: sha256Source(source) };
-    }).sort((left, right) => compareCodeUnits7(left.path, right.path))
+    }).sort((left, right) => compareCodeUnits8(left.path, right.path))
   };
 }
 function serializeVisualCompareInventory(inventory) {
@@ -6176,7 +7014,7 @@ function serializeVisualCompareInventory(inventory) {
 `;
 }
 async function readVisualCompareInventory(assetDirectory, inventoryPath, boundary) {
-  await assertNoSymlinkComponents(dirname8(inventoryPath), boundary);
+  await assertNoSymlinkComponents(dirname9(inventoryPath), boundary);
   let info;
   try {
     info = await lstat3(inventoryPath);
@@ -6200,7 +7038,7 @@ async function readVisualCompareInventory(assetDirectory, inventoryPath, boundar
   const assets = [];
   for (const asset of inventory.assets) {
     const path = resolve5(assetDirectory, asset.path);
-    await assertNoSymlinkComponents(dirname8(path), boundary);
+    await assertNoSymlinkComponents(dirname9(path), boundary);
     let assetInfo;
     try {
       assetInfo = await lstat3(path);
@@ -6243,7 +7081,7 @@ function validateVisualCompareInventory(input) {
     return { path: asset.path, sha256: asset.sha256 };
   });
   const paths = assets.map((asset) => asset.path);
-  const sortedPaths = [...paths].sort(compareCodeUnits7);
+  const sortedPaths = [...paths].sort(compareCodeUnits8);
   if (new Set(paths).size !== paths.length || paths.some((path, index) => path !== sortedPaths[index])) {
     throw new Error("Visual compare inventory asset paths must be unique and sorted.");
   }
@@ -6263,8 +7101,8 @@ function isVisualCompareOwnedAssetName(value) {
   return Number.isInteger(row) && row >= 1 && row <= tileflowVisualCompareLimits.maximumRows;
 }
 function hasExactKeys(record, keys) {
-  const actual = Object.keys(record).sort(compareCodeUnits7);
-  const expected = [...keys].sort(compareCodeUnits7);
+  const actual = Object.keys(record).sort(compareCodeUnits8);
+  const expected = [...keys].sort(compareCodeUnits8);
   return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
 }
 function sha256Source(source) {
@@ -6281,7 +7119,7 @@ async function canonicalPathIdentity(path) {
       return process.platform === "win32" ? canonical.toLowerCase() : canonical;
     } catch (error) {
       if (!isMissingPathComponent(error)) throw error;
-      const parent = dirname8(current);
+      const parent = dirname9(current);
       if (parent === current) {
         const canonical = absolute.normalize("NFC");
         return process.platform === "win32" ? canonical.toLowerCase() : canonical;
@@ -6358,7 +7196,7 @@ function portablePathIdentity(path) {
 }
 function isInside(parent, child) {
   const path = relative3(parent, child);
-  return path === "" || path !== ".." && !path.startsWith(`..${sep3}`) && !isAbsolute2(path);
+  return path === "" || path !== ".." && !path.startsWith(`..${sep3}`) && !isAbsolute3(path);
 }
 function pathsOverlap(left, right) {
   return isInside(left, right) || isInside(right, left);
@@ -6438,7 +7276,7 @@ function createTileflowVisualDiffJson(comparisons, cwd) {
   return {
     schemaVersion: 1,
     command: "visual.diff",
-    comparisons: [...comparisons].sort((left, right) => compareCodeUnits8(left.comparison.scene, right.comparison.scene)).map(({ comparison, baselinePath, actualPath, diffPath, reportPath }) => ({
+    comparisons: [...comparisons].sort((left, right) => compareCodeUnits9(left.comparison.scene, right.comparison.scene)).map(({ comparison, baselinePath, actualPath, diffPath, reportPath }) => ({
       ...createTileflowVisualComparisonDocument(comparison),
       baselinePath: relativePath(cwd, baselinePath),
       actualPath: relativePath(cwd, actualPath),
@@ -6653,7 +7491,7 @@ async function runVisualUpdate(scenes, options) {
           renderer: capture.renderer,
           networkDependent: capture.networkDependent
         },
-        warnings: [...capture.warnings].sort(compareCodeUnits8)
+        warnings: [...capture.warnings].sort(compareCodeUnits9)
       });
       outputFiles.push(
         { path: files.pngPath, source: capture.png },
@@ -6670,7 +7508,7 @@ async function runVisualUpdate(scenes, options) {
     const document = {
       schemaVersion: 1,
       command: "visual.update",
-      updates: updates.sort((left, right) => compareCodeUnits8(left.scene, right.scene))
+      updates: updates.sort((left, right) => compareCodeUnits9(left.scene, right.scene))
     };
     if (options.json) {
       process.stdout.write(serializeTileflowVisualCommandJson(document));
@@ -6726,7 +7564,7 @@ async function readBaselineFiles(directory, scene) {
   return { kind: "complete", pngPath, receiptPath, baseline: { png, receipt } };
 }
 async function readOptionalArtifact(path, boundary, maximumBytes) {
-  await assertNoSymlinkComponents(dirname9(path), boundary);
+  await assertNoSymlinkComponents(dirname10(path), boundary);
   let info;
   try {
     info = await lstat4(path);
@@ -6816,7 +7654,7 @@ function portablePathIdentity2(path) {
 }
 function isInside2(parent, child) {
   const path = relative4(parent, child);
-  return path === "" || path !== ".." && !path.startsWith(`..${sep4}`) && !isAbsolute3(path);
+  return path === "" || path !== ".." && !path.startsWith(`..${sep4}`) && !isAbsolute4(path);
 }
 function isMissingFile5(error) {
   return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
@@ -6831,9 +7669,10 @@ var defaultApiUrl = defaultTileflowApiUrl;
 var defaultAppUrl = "https://tileflow.dev";
 var defaultConfigPath = defaultTileflowConfigPath;
 var defaultManifestPath = defaultTileflowManifestPath;
-program.name("tileflow").description("Beautiful maps from config.").version(packageJson.version).showHelpAfterError(pc3.gray("\nRun tileflow <command> --help for usage.")).showSuggestionAfterError();
+program.name("tileflow").description("Beautiful maps from config.").version(packageJson.version).showHelpAfterError(pc6.gray("\nRun tileflow <command> --help for usage.")).showSuggestionAfterError();
 registerLanguageCommand(program);
 registerTilesetCommands(program, { defaultApiUrl, loadAuthConfig });
+registerIconSetCommands(program, { defaultApiUrl, loadAuthConfig });
 program.command("init").description("Create a starter tileflow.config.ts").option("-f, --force", "overwrite an existing config").action(async (options) => {
   const configPath = resolve7(process.cwd(), defaultConfigPath);
   const ignorePath = resolve7(process.cwd(), ".gitignore");
@@ -6852,9 +7691,9 @@ program.command("init").description("Create a starter tileflow.config.ts").optio
   }
   logSuccess(`Created ${pathLabel(defaultConfigPath)}.`);
   printKeyValue("Path", pathLabel(configPath));
-  printKeyValue("Map", pc3.bold("madrid"));
+  printKeyValue("Map", pc6.bold("madrid"));
   printNextSteps([
-    `Install ${pc3.cyan("@tileflow/core")} and ${pc3.cyan("@tileflow/maps")} in this project if needed.`,
+    `Install ${pc6.cyan("@tileflow/core")} and ${pc6.cyan("@tileflow/maps")} in this project if needed.`,
     `Preview locally with ${command("tileflow preview")}.`,
     `Validate the config with ${command("tileflow validate")}.`
   ]);
@@ -6947,172 +7786,181 @@ program.command("validate").description("Validate a Tileflow config").option("-c
   "--api-base-url <url>",
   "Tileflow API base URL used to resolve official map assets",
   process.env.TILEFLOW_API_URL ?? defaultApiUrl
-).option("--json", "print deterministic schema-version-1 JSON").action(async (options) => {
-  if (options.target !== "local" && options.target !== "hosted") {
-    if (options.json) {
-      const failure = createTileflowCommandFailureDocument4(
-        "validate",
-        {
-          code: "INVALID_TARGET",
-          issues: [
-            {
-              code: "INVALID_TARGET",
-              message: `Invalid validation target: ${options.target}`,
-              path: "target",
-              phase: "command-validation"
-            }
-          ],
-          phase: "command-validation"
-        },
-        process.cwd(),
-        { code: "INVALID_TARGET", phase: "command-validation" }
-      );
-      process.stderr.write(serializeTileflowCommandDocument4(failure));
+).option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").option("--json", "print deterministic schema-version-1 JSON").action(
+  async (options) => {
+    if (options.target !== "local" && options.target !== "hosted") {
+      if (options.json) {
+        const failure = createTileflowCommandFailureDocument4(
+          "validate",
+          {
+            code: "INVALID_TARGET",
+            issues: [
+              {
+                code: "INVALID_TARGET",
+                message: `Invalid validation target: ${options.target}`,
+                path: "target",
+                phase: "command-validation"
+              }
+            ],
+            phase: "command-validation"
+          },
+          process.cwd(),
+          { code: "INVALID_TARGET", phase: "command-validation" }
+        );
+        process.stderr.write(serializeTileflowCommandDocument4(failure));
+        process.exitCode = 1;
+        return;
+      }
+      logError(`Invalid validation target: ${options.target}`);
+      printNextSteps([
+        `Use ${command("tileflow validate --target local")} or ${command("tileflow validate --target hosted")}.`
+      ]);
       process.exitCode = 1;
       return;
     }
-    logError(`Invalid validation target: ${options.target}`);
-    printNextSteps([
-      `Use ${command("tileflow validate --target local")} or ${command("tileflow validate --target hosted")}.`
-    ]);
-    process.exitCode = 1;
-    return;
-  }
-  let failureDefaults = { code: "CONFIG_LOAD_FAILED", phase: "config-load" };
-  try {
-    if (!options.json) logInfo(`Validating ${pathLabel(options.config)}.`);
-    const loaded = await withTileflowConfigSecretsHidden(
-      () => loadTileflowConfigWithInputs3(options.config)
-    );
-    const project = loaded.project;
-    const baseDirectory = dirname10(loaded.configFile);
-    failureDefaults = { code: "CONFIG_INVALID", phase: "config-validation" };
-    assertValidTileflowConfig2(project);
-    const mapNames = getTileflowMapNames3(project).sort();
-    failureDefaults = { code: "ICON_COMPILATION_FAILED", phase: "icon-compilation" };
-    const compiledIcons = await compileTileflowIconPackages2(project, {
-      baseDirectory,
-      cwd: process.cwd(),
-      target: options.target
-    });
-    const mapAssets = createCompiledMapAssets(
-      compiledIcons,
-      (binding) => options.target === "hosted" ? `${normalizeUrl(options.apiBaseUrl)}/sprites/preflight/${binding.packageHash}/sprite` : `/tileflow/icons/${binding.mapName}/sprite`
-    );
-    failureDefaults = { code: "STYLE_INVALID", phase: "style-validation" };
-    const compiledStyles = createTileflowStyles(project, {
-      apiBaseUrl: options.apiBaseUrl,
-      mapAssets
-    });
-    failureDefaults = { code: "TF_LOCAL_TILESET_INVALID", phase: "local-tileset-resolution" };
-    const localTilesets = await prepareTileflowLocalTilesets(project, compiledStyles, {
-      assetBaseUrl: "/tileflow",
-      baseDirectory,
-      cwd: process.cwd()
-    });
-    failureDefaults = { code: "FONT_COMPILATION_FAILED", phase: "font-compilation" };
-    const { styles } = await prepareTileflowStyleFonts(project, localTilesets.styles, {
-      assetBaseUrl: "/tileflow",
-      baseDirectory,
-      cwd: process.cwd(),
-      target: options.target
-    });
-    failureDefaults = { code: "HOSTED_INCOMPATIBLE", phase: "hosted-validation" };
-    const hostedIssues = options.target === "hosted" ? inspectTileflowHostedCompatibility(project, styles) : [];
-    if (hostedIssues.length > 0) {
-      if (!options.json) {
-        printHostedCompatibilityIssues(hostedIssues);
-        return;
-      }
-      throw Object.assign(new Error("Tileflow config is not Hosted-compatible."), {
-        code: "HOSTED_INCOMPATIBLE",
-        issues: hostedIssues.map((issue) => ({
+    let failureDefaults = { code: "CONFIG_LOAD_FAILED", phase: "config-load" };
+    try {
+      if (!options.json) logInfo(`Validating ${pathLabel(options.config)}.`);
+      const loaded = await withTileflowConfigSecretsHidden(
+        () => loadTileflowConfigWithInputs3(options.config)
+      );
+      const project = loaded.project;
+      const baseDirectory = dirname11(loaded.configFile);
+      failureDefaults = { code: "CONFIG_INVALID", phase: "config-validation" };
+      assertValidTileflowConfig2(project);
+      const mapNames = getTileflowMapNames4(project).sort();
+      failureDefaults = { code: "ICON_COMPILATION_FAILED", phase: "icon-compilation" };
+      const compiledIcons = await compileTileflowIconPackages2(project, {
+        baseDirectory,
+        cwd: process.cwd(),
+        icons: resolveIconOptions(options),
+        target: options.target
+      });
+      const mapAssets = createCompiledMapAssets(
+        compiledIcons,
+        (binding) => options.target === "hosted" ? `${normalizeUrl(options.apiBaseUrl)}/sprites/preflight/${binding.packageHash}/sprite` : `/tileflow/icons/${binding.mapName}/sprite`
+      );
+      failureDefaults = { code: "STYLE_INVALID", phase: "style-validation" };
+      const compiledStyles = createTileflowStyles(project, {
+        apiBaseUrl: options.apiBaseUrl,
+        mapAssets
+      });
+      failureDefaults = { code: "TF_LOCAL_TILESET_INVALID", phase: "local-tileset-resolution" };
+      const localTilesets = await prepareTileflowLocalTilesets(project, compiledStyles, {
+        assetBaseUrl: "/tileflow",
+        baseDirectory,
+        cwd: process.cwd()
+      });
+      failureDefaults = { code: "FONT_COMPILATION_FAILED", phase: "font-compilation" };
+      const { styles } = await prepareTileflowStyleFonts(project, localTilesets.styles, {
+        assetBaseUrl: "/tileflow",
+        baseDirectory,
+        cwd: process.cwd(),
+        target: options.target
+      });
+      failureDefaults = { code: "HOSTED_INCOMPATIBLE", phase: "hosted-validation" };
+      const hostedIssues = options.target === "hosted" ? inspectTileflowHostedCompatibility(project, styles) : [];
+      if (hostedIssues.length > 0) {
+        if (!options.json) {
+          printHostedCompatibilityIssues(hostedIssues);
+          return;
+        }
+        throw Object.assign(new Error("Tileflow config is not Hosted-compatible."), {
           code: "HOSTED_INCOMPATIBLE",
-          message: issue.message,
-          path: issue.path,
+          issues: hostedIssues.map((issue) => ({
+            code: "HOSTED_INCOMPATIBLE",
+            message: issue.message,
+            path: issue.path,
+            phase: "hosted-validation"
+          })),
           phase: "hosted-validation"
-        })),
-        phase: "hosted-validation"
-      });
-    }
-    const themeWarnings = mapNames.flatMap(
-      (mapName) => auditTileflowMapThemeValues(project.maps[mapName]).filter(
-        ({ severity }) => severity === "warning"
-      )
-    );
-    const diagnostics = themeWarnings.length === 0 ? [] : createTileflowStructuredDiagnostics2({ diagnostics: themeWarnings }, process.cwd(), {
-      code: "VALIDATION_WARNING",
-      phase: "theme-audit"
-    });
-    const checks = [
-      "Config schema",
-      "Icon asset closure",
-      "Text provider closure",
-      "Named map styles",
-      "MapLibre style semantics",
-      ...options.target === "hosted" ? ["Hosted compatibility"] : []
-    ];
-    if (options.json) {
-      const summary = createTileflowCommandSummary2({
-        code: "VALIDATION_OK",
-        command: "validate",
-        message: `Tileflow config is valid (${plural(mapNames.length, "map")}).`,
-        ok: true,
-        path: "",
-        phase: "validation",
-        severity: "info",
-        suggestion: "No changes are required."
+        });
+      }
+      const themeWarnings = mapNames.flatMap(
+        (mapName) => auditTileflowMapThemeValues(project.maps[mapName]).filter(
+          ({ severity }) => severity === "warning"
+        )
+      );
+      const diagnostics = themeWarnings.length === 0 ? [] : createTileflowStructuredDiagnostics2({ diagnostics: themeWarnings }, process.cwd(), {
+        code: "VALIDATION_WARNING",
+        phase: "theme-audit"
       });
-      process.stdout.write(
-        serializeTileflowCommandDocument4({
-          ...summary,
-          target: options.target,
-          maps: mapNames,
-          checks,
-          diagnostics
-        })
+      const sharedIconMaps = Object.keys(compiledIcons.compositions).sort();
+      const checks = [
+        "Config schema",
+        "Icon asset closure",
+        ...sharedIconMaps.length > 0 ? ["Locked Icon Set composition"] : [],
+        "Text provider closure",
+        "Named map styles",
+        "MapLibre style semantics",
+        ...options.target === "hosted" ? ["Hosted compatibility"] : []
+      ];
+      if (options.json) {
+        const summary = createTileflowCommandSummary2({
+          code: "VALIDATION_OK",
+          command: "validate",
+          message: `Tileflow config is valid (${plural(mapNames.length, "map")}).`,
+          ok: true,
+          path: "",
+          phase: "validation",
+          severity: "info",
+          suggestion: "No changes are required."
+        });
+        process.stdout.write(
+          serializeTileflowCommandDocument4({
+            ...summary,
+            target: options.target,
+            maps: mapNames,
+            checks,
+            diagnostics
+          })
+        );
+        return;
+      }
+      logSuccess(`Config is valid (${plural(mapNames.length, "map")}).`);
+      printChecks(checks);
+      for (const diagnostic of diagnostics) {
+        logWarning(`${diagnostic.path || "(root)"}: ${diagnostic.message}`);
+      }
+    } catch (error) {
+      if (!options.json) throw error;
+      const failure = createTileflowCommandFailureDocument4(
+        "validate",
+        error,
+        process.cwd(),
+        failureDefaults
       );
-      return;
-    }
-    logSuccess(`Config is valid (${plural(mapNames.length, "map")}).`);
-    printChecks(checks);
-    for (const diagnostic of diagnostics) {
-      logWarning(`${diagnostic.path || "(root)"}: ${diagnostic.message}`);
+      process.stderr.write(serializeTileflowCommandDocument4(failure));
+      process.exitCode = 1;
     }
-  } catch (error) {
-    if (!options.json) throw error;
-    const failure = createTileflowCommandFailureDocument4(
-      "validate",
-      error,
-      process.cwd(),
-      failureDefaults
-    );
-    process.stderr.write(serializeTileflowCommandDocument4(failure));
-    process.exitCode = 1;
   }
-});
+);
 program.command("build").description("Generate static Tileflow styles").option("-c, --config <path>", "config path", defaultConfigPath).option("-o, --out <path>", "output directory", "dist/tileflow").option(
   "--api-base-url <url>",
   "Tileflow API base URL used to resolve official map assets",
   process.env.TILEFLOW_API_URL ?? defaultApiUrl
-).action(async (options) => {
-  logInfo(`Building ${pathLabel(options.config)}.`);
-  await withTileflowConfigSecretsHidden(
-    () => writeTileflowBuildArtifacts({
-      config: options.config,
-      outDir: options.out,
-      styleBaseUrl: ".",
-      apiBaseUrl: options.apiBaseUrl
-    })
-  );
-  logSuccess("Built Tileflow artifacts.");
-  printKeyValue("Output", pathLabel(resolve7(process.cwd(), options.out)));
-});
+).option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").action(
+  async (options) => {
+    logInfo(`Building ${pathLabel(options.config)}.`);
+    const icons = resolveIconOptions(options);
+    await withTileflowConfigSecretsHidden(
+      () => writeTileflowBuildArtifacts({
+        config: options.config,
+        outDir: options.out,
+        styleBaseUrl: ".",
+        apiBaseUrl: options.apiBaseUrl,
+        ...icons ? { icons } : {}
+      })
+    );
+    logSuccess("Built Tileflow artifacts.");
+    printKeyValue("Output", pathLabel(resolve7(process.cwd(), options.out)));
+  }
+);
 program.command("preview").alias("dev").description("Run a local map preview").option("-c, --config <path>", "config path", defaultConfigPath).option("--against-config <path>", "second config for the comparison workbench").option("--against-map <name>", "map on the right; defaults to --map").option("--against-scene <name>", "committed standalone scene on the right").option("--against-theme <name>", "concrete theme on the right; defaults to --theme").option("--host <host>", "bind host: an explicit IP address or localhost", defaultTileflowDevHost).option("--map <name>", "preview one configured map").option("--theme <name>", "preview one concrete theme; defaults to the map default").option("-p, --port <port>", "preview port", "3333").option("--scene <name>", "preview one committed standalone map scene").option(
   "--api-base-url <url>",
   "Tileflow API base URL used to resolve official map assets",
   process.env.TILEFLOW_API_URL ?? defaultApiUrl
-).option("--json", "emit schema-version-1 NDJSON lifecycle events").action(
+).option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").option("--json", "emit schema-version-1 NDJSON lifecycle events").action(
   async (options) => {
     const port = parsePort(options.port);
     if (port === null) {
@@ -7165,10 +8013,12 @@ program.command("preview").alias("dev").description("Run a local map preview").o
     }
     await withTileflowConfigSecretsHidden(async () => {
       const origin = tileflowDevOrigin(host, port);
+      const icons = resolveIconOptions(options);
       const session = await createTileflowArtifactSession3({
         assetBaseUrl: origin,
         apiBaseUrl: options.apiBaseUrl,
         config: options.config,
+        ...icons ? { icons } : {},
         styleBaseUrl: origin,
         watch: true
       });
@@ -7268,7 +8118,7 @@ program.command("preview").alias("dev").description("Run a local map preview").o
 program.command("deploy").description("Deploy maps to Tileflow and write the frontend manifest").option("-c, --config <path>", "config path", defaultConfigPath).option("--manifest <path>", "manifest path written for frontend bundlers", defaultManifestPath).option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--api-key <key>", "Tileflow API key", process.env.TILEFLOW_API_KEY).option("--map-id <id>", "managed Map destination").option("--map <name>", "configured map to connect when the repository contains multiple maps").option(
   "--overwrite-self-hosted-manifest",
   "explicitly replace an existing self-hosted manifest at --manifest"
-).action(
+).option("--cache-dir <path>", "verified Icon Set artifact cache root").option("--offline", "fail a locked Icon Set cache miss instead of hydrating it").action(
   async (options) => {
     const source = resolveDeploySource(process.env);
     const resolveApi = (selectedMap) => requireApiOptions(options, {
@@ -7296,9 +8146,9 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       () => loadTileflowConfigWithInputs3(options.config)
     );
     const project = loaded.project;
-    const baseDirectory = dirname10(loaded.configFile);
+    const baseDirectory = dirname11(loaded.configFile);
     assertValidTileflowConfig2(project);
-    const configuredMapNames = getTileflowMapNames3(project);
+    const configuredMapNames = getTileflowMapNames4(project);
     const mapNames = selectManagedDeployMaps(configuredMapNames, options);
     if (!mapNames) return;
     if (!validateDeployTarget(options)) return;
@@ -7312,6 +8162,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
     const compiledIcons = await compileTileflowIconPackages2(deploymentProject, {
       baseDirectory,
       cwd: process.cwd(),
+      icons: resolveIconOptions(options),
       target: "hosted"
     });
     const bindingsByMap = new Map(
@@ -7392,7 +8243,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       );
       const action = uploaded.value.changed === false ? "Reused" : "Uploaded";
       logSuccess(
-        `${action} icon package ${pc3.bold(binding?.label ?? "Icons")} (${plural(iconPackage.manifest.iconNames.length, "icon")}, ${formatBytes3(totalBytes)}, ${iconPackage.contentHash.slice(0, 12)}).`
+        `${action} icon package ${pc6.bold(binding?.label ?? "Icons")} (${plural(iconPackage.manifest.iconNames.length, "icon")}, ${formatBytes3(totalBytes)}, ${iconPackage.contentHash.slice(0, 12)}).`
       );
       hostedSpriteByPackageHash.set(iconPackage.contentHash, uploaded.value.spriteUrl);
     }
@@ -7498,7 +8349,8 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
               map,
               sourceAssets: {
                 fonts: hostedFonts.sourceIdentities[mapName] ?? [],
-                icons: compiledIcons.sourceIdentities[mapName] ?? []
+                icons: compiledIcons.sourceIdentities[mapName] ?? [],
+                ...compiledIcons.compositions[mapName] ? { iconComposition: compiledIcons.compositions[mapName] } : {}
               },
               styles: styles[mapName]
             }
@@ -7513,6 +8365,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       const fontBundle = hostedFonts.bundles[mapName];
       return {
         iconBinding,
+        iconComposition: compiledIcons.compositions[mapName],
         iconPackage,
         fontBundle,
         mapName,
@@ -7531,14 +8384,20 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
         buildManifest: buildManifest2,
         fontBundle,
         iconBinding,
+        iconComposition,
         iconPackage,
         mapName,
         teamSources,
         styles: themeStyles
       } = deployment;
+      if (iconComposition && iconComposition.packageHash !== iconPackage?.contentHash) {
+        logError(`Icon composition does not match the effective package for ${mapName}.`);
+        process.exitCode = 1;
+        return;
+      }
       const themeNames = Object.keys(themeStyles).sort();
       logInfo(
-        `Deploying compiled map ${pc3.bold(mapName)} (${plural(themeNames.length, "theme")}).`
+        `Deploying compiled map ${pc6.bold(mapName)} (${plural(themeNames.length, "theme")}).`
       );
       const response = await publishHostedStyle(
         api,
@@ -7560,6 +8419,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
               label: iconBinding.label
             }
           } : {},
+          ...iconComposition ? { iconComposition } : {},
           ...fontBundle ? { fontBundle: { contentHash: fontBundle.contentHash } } : {},
           source
         },
@@ -7588,7 +8448,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
         process.exitCode = 1;
         return;
       }
-      const resolvedMap = parseResolvedTileflowMap3(deploymentProject.maps[mapName]);
+      const resolvedMap = parseResolvedTileflowMap4(deploymentProject.maps[mapName]);
       const mapBuild = buildManifest2.maps[mapName];
       deployedMaps[mapName] = {
         defaultTheme: resolvedMap.defaultTheme,
@@ -7617,9 +8477,9 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       };
       const versionLabel = Number.isInteger(body.version) ? ` (v${body.version})` : "";
       if (body.changed === false) {
-        logSuccess(`Unchanged ${pc3.bold(mapName)}${versionLabel}.`);
+        logSuccess(`Unchanged ${pc6.bold(mapName)}${versionLabel}.`);
       } else {
-        logSuccess(`Published ${pc3.bold(mapName)}${versionLabel}.`);
+        logSuccess(`Published ${pc6.bold(mapName)}${versionLabel}.`);
       }
     }
     const manifestPath = await writeDeployManifest(options.manifest, {
@@ -7693,6 +8553,7 @@ program.command("status").description("Show deployed compiled styles").option("-
   printMapStatus(status, api.apiUrl);
 });
 var iconsCommand = program.command("icons").description("Inspect managed Tileflow icons");
+registerIconLockCommands(program, { defaultApiUrl, defaultConfigPath, loadAuthConfig });
 registerIconListCommand(iconsCommand, { defaultConfigPath });
 registerIconDiffCommand(iconsCommand, {
   defaultApiUrl,
@@ -7782,10 +8643,12 @@ async function runTileflowComparisonPreview(options, address) {
     try {
       const leftCaptureConfig = comparisonCaptureConfigArgument(options.config);
       const rightCaptureConfig = comparisonCaptureConfigArgument(rightConfig);
+      const comparisonIcons = resolveIconOptions(options);
       leftSession = await createTileflowArtifactSession3({
         apiBaseUrl: options.apiBaseUrl,
         assetBaseUrl: `${origin}${leftBasePath}`,
         config: options.config,
+        ...comparisonIcons ? { icons: comparisonIcons } : {},
         inspection: true,
         styleBaseUrl: `${origin}${leftBasePath}`,
         watch: true
@@ -7794,6 +8657,7 @@ async function runTileflowComparisonPreview(options, address) {
         apiBaseUrl: options.apiBaseUrl,
         assetBaseUrl: `${origin}${rightBasePath}`,
         config: rightConfig,
+        ...comparisonIcons ? { icons: comparisonIcons } : {},
         inspection: true,
         styleBaseUrl: `${origin}${rightBasePath}`,
         watch: true
@@ -7925,7 +8789,7 @@ function comparisonCaptureConfigArgument(configPath) {
   const absoluteDefaultPath = existsSync(defaultRequestedPath) ? realpathSync(defaultRequestedPath) : defaultRequestedPath;
   if (absoluteConfigPath === absoluteDefaultPath) return void 0;
   const relativeConfigPath = relative5(cwd, absoluteConfigPath);
-  if (relativeConfigPath === "" || relativeConfigPath === ".." || relativeConfigPath.startsWith(`..${sep5}`) || isAbsolute4(relativeConfigPath)) {
+  if (relativeConfigPath === "" || relativeConfigPath === ".." || relativeConfigPath.startsWith(`..${sep5}`) || isAbsolute5(relativeConfigPath)) {
     throw new Error(
       "Comparison configs must be inside the current working directory so Copy command can remain reproducible."
     );
@@ -7964,7 +8828,7 @@ async function loginWithDeviceFlow(options) {
     codeChallenge,
     deviceName: hostname()
   });
-  printKeyValue("Code", pc3.bold(authorization.userCode));
+  printKeyValue("Code", pc6.bold(authorization.userCode));
   printKeyValue("URL", link(authorization.verificationUriComplete));
   if (options.noBrowser) {
     logMuted("Open the URL above to continue.");
@@ -7974,7 +8838,7 @@ async function loginWithDeviceFlow(options) {
       output: process.stdout
     });
     try {
-      await readline.question(`${pc3.cyan("?")} Press Enter to open Tileflow Dashboard...`);
+      await readline.question(`${pc6.cyan("?")} Press Enter to open Tileflow Dashboard...`);
       openBrowser(authorization.verificationUriComplete);
     } finally {
       readline.close();
@@ -8027,7 +8891,7 @@ function openBrowser(url, errorsToStderr = false) {
 async function writeDeployManifest(manifestPath, manifest) {
   const outputPath = resolve7(process.cwd(), manifestPath);
   await writeAtomicFile({
-    boundaryPath: dirname10(outputPath),
+    boundaryPath: dirname11(outputPath),
     force: true,
     label: "Deploy manifest",
     managed: true,
@@ -8037,6 +8901,13 @@ async function writeDeployManifest(manifestPath, manifest) {
   });
   return manifestPath;
 }
+function resolveIconOptions(options) {
+  const icons = {
+    ...options.cacheDir ? { cacheRoot: options.cacheDir } : {},
+    ...options.offline ? { offline: true } : {}
+  };
+  return Object.keys(icons).length > 0 ? icons : void 0;
+}
 function createCompiledMapAssets(compiled, resolveSprite) {
   return Object.fromEntries(
     compiled.bindings.map((binding) => [
@@ -8190,7 +9061,7 @@ async function requireApiOptions(options, behavior = {}) {
     if (!behavior.silent) {
       logError("CI requires an explicit Tileflow credential with access to the target Map.");
       printNextSteps([
-        `Set ${pc3.cyan("TILEFLOW_API_KEY")} from the CI secret store.`,
+        `Set ${pc6.cyan("TILEFLOW_API_KEY")} from the CI secret store.`,
         "The saved personal account session is never used in CI."
       ]);
     }
@@ -8270,7 +9141,7 @@ function printTileflowPreviewError(error) {
     printValidationErrors(error.issues);
     return;
   }
-  if (error instanceof TileflowValidationError4) {
+  if (error instanceof TileflowValidationError5) {
     printValidationErrors(error.messages);
     return;
   }
@@ -8282,7 +9153,7 @@ function printCliError(error) {
     printValidationErrors(error.issues);
     return;
   }
-  if (error instanceof TileflowValidationError4) {
+  if (error instanceof TileflowValidationError5) {
     printValidationErrors(error.messages);
     return;
   }
@@ -8296,17 +9167,17 @@ function printCliError(error) {
   }
   const message = error instanceof Error ? error.message : "Command failed.";
   if (message.includes("Cannot find module '@tileflow/core'")) {
-    logError(`Cannot load ${pc3.cyan("@tileflow/core")} from this project.`);
+    logError(`Cannot load ${pc6.cyan("@tileflow/core")} from this project.`);
     printNextSteps([
-      `Install ${pc3.cyan("@tileflow/core")} in this project.`,
+      `Install ${pc6.cyan("@tileflow/core")} in this project.`,
       `Run the command again from the project root.`
     ]);
     return;
   }
   if (message.includes("Cannot find module '@tileflow/maps'")) {
-    logError(`Cannot load ${pc3.cyan("@tileflow/maps")} from this project.`);
+    logError(`Cannot load ${pc6.cyan("@tileflow/maps")} from this project.`);
     printNextSteps([
-      `Install ${pc3.cyan("@tileflow/maps")} in this project.`,
+      `Install ${pc6.cyan("@tileflow/maps")} in this project.`,
       `Run the command again from the project root.`
     ]);
     return;
@@ -8317,51 +9188,51 @@ function printCliError(error) {
   }
 }
 function logSuccess(message) {
-  console.log(`${pc3.green("\u2713")} ${message}`);
+  console.log(`${pc6.green("\u2713")} ${message}`);
 }
 function logError(message) {
-  console.log(`${pc3.red("\u2715")} ${message}`);
+  console.log(`${pc6.red("\u2715")} ${message}`);
 }
 function logWarning(message) {
-  console.log(`${pc3.yellow("!")} ${message}`);
+  console.log(`${pc6.yellow("!")} ${message}`);
 }
 function logInfo(message) {
-  console.log(`${pc3.cyan("i")} ${message}`);
+  console.log(`${pc6.cyan("i")} ${message}`);
 }
 function logMuted(message) {
-  console.log(pc3.gray(message));
+  console.log(pc6.gray(message));
 }
 function printTitle(title, subtitle) {
-  console.log(pc3.bold(title));
+  console.log(pc6.bold(title));
   if (subtitle) {
-    console.log(pc3.gray(subtitle));
+    console.log(pc6.gray(subtitle));
   }
 }
 function printKeyValue(label, value) {
-  console.log(`${pc3.gray(`${label}:`.padEnd(13))} ${value}`);
+  console.log(`${pc6.gray(`${label}:`.padEnd(13))} ${value}`);
 }
 function printChecks(items) {
   for (const item of items) {
-    console.log(`  ${pc3.green("\u2713")} ${item}`);
+    console.log(`  ${pc6.green("\u2713")} ${item}`);
   }
 }
 function printNextSteps(steps) {
   if (steps.length === 0) return;
   console.log(`
-${pc3.bold("Next steps")}`);
+${pc6.bold("Next steps")}`);
   for (const step of steps) {
-    console.log(`  ${pc3.cyan("\u2022")} ${step}`);
+    console.log(`  ${pc6.cyan("\u2022")} ${step}`);
   }
 }
 function printValidationErrors(messages) {
   logError("Tileflow config has errors.");
   for (const message of messages) {
-    const path = message.path ? pc3.cyan(message.path) : pc3.cyan("(root)");
-    console.log(`  ${pc3.red("\u2715")} ${path} ${pc3.gray("-")} ${message.message}`);
+    const path = message.path ? pc6.cyan(message.path) : pc6.cyan("(root)");
+    console.log(`  ${pc6.red("\u2715")} ${path} ${pc6.gray("-")} ${message.message}`);
   }
 }
 function printAccountDetails(session) {
-  printKeyValue("Account", pc3.bold(session.account.name));
+  printKeyValue("Account", pc6.bold(session.account.name));
   printKeyValue("Email", session.account.email);
   printKeyValue("API", link(session.apiOrigin));
   printKeyValue("Expires", formatDate(session.expiresAt));
@@ -8390,11 +9261,11 @@ function printDeployedMaps(maps) {
   const entries = Object.entries(maps);
   if (entries.length === 0) return;
   console.log(`
-${pc3.bold("Maps")}`);
+${pc6.bold("Maps")}`);
   for (const [name, map] of entries) {
     for (const [themeName, theme] of Object.entries(map.themes)) {
       const label = `${name}/${themeName}`;
-      console.log(`  ${pc3.green("\u2713")} ${label.padEnd(24)} ${link(theme.styleUrl)}`);
+      console.log(`  ${pc6.green("\u2713")} ${label.padEnd(24)} ${link(theme.styleUrl)}`);
     }
   }
 }
@@ -8412,7 +9283,7 @@ function plural(count, singular, pluralForm = `${singular}s`) {
   return `${count} ${count === 1 ? singular : pluralForm}`;
 }
 function command(value) {
-  return pc3.cyan(value);
+  return pc6.cyan(value);
 }
 function cliInvocation(parts) {
   return parts.map(quoteCliArgument).join(" ");
@@ -8421,10 +9292,10 @@ function quoteCliArgument(value) {
   return /^[A-Za-z0-9_./:@%+=,-]+$/u.test(value) ? value : `'${value.replaceAll("'", `'"'"'`)}'`;
 }
 function link(value) {
-  return pc3.cyan(value);
+  return pc6.cyan(value);
 }
 function pathLabel(value) {
-  return pc3.cyan(value);
+  return pc6.cyan(value);
 }
 function starterConfig() {
   return `import { defineMap, defineTheme, labels, poi } from "@tileflow/core";
@@ -8470,15 +9341,15 @@ function printHostedCompatibilityIssues(issues) {
 }
 function printMapStatus(status, apiUrl) {
   printTitle("Tileflow status");
-  printKeyValue("Map", pc3.bold(status.mapId));
+  printKeyValue("Map", pc6.bold(status.mapId));
   console.log(`
-${pc3.bold("Styles")}`);
+${pc6.bold("Styles")}`);
   if (status.styles.length === 0) {
     logMuted("  No styles deployed.");
   }
   for (const style of status.styles) {
     console.log(
-      `  ${pc3.green("\u2713")} ${style.environment.padEnd(16)} ${link(`${apiUrl}/maps/${style.mapId}/style.json`).padEnd(36)} ${formatBytes3(style.size).padStart(10)}  ${pc3.gray(formatDate(style.uploaded))}`
+      `  ${pc6.green("\u2713")} ${style.environment.padEnd(16)} ${link(`${apiUrl}/maps/${style.mapId}/style.json`).padEnd(36)} ${formatBytes3(style.size).padStart(10)}  ${pc6.gray(formatDate(style.uploaded))}`
     );
   }
 }