tileflow 0.1.0-alpha.15 → 0.1.0-alpha.16

package/README.md

@@ -222,13 +222,17 @@ browser bundle, copied prompt, or command-line argument.
 ```sh
 npx tileflow login
 npx tileflow whoami --json
+npx tileflow deploy --origin https://www.example.com
 npx tileflow deploy --map-id map_AbCdEfGhIjKlMnOp
 npx tileflow status --map-id map_AbCdEfGhIjKlMnOp
 ```
 
-Replace the example Map ID with the destination created in Tileflow. It is a public identifier,
-not a credential or the portable `id` in your config. A CI deploy key must authorize that destination.
-`logout` removes the saved personal session.
+Without `--map-id`, a logged-in `deploy` first creates the Map in the Team you administer (it asks,
+or takes `--team @team`, when several qualify) with the browser access you choose: exact origins
+with `--origin`, or `--any-website`. It prints the Map ID to use for later deploys;
+`tileflow maps create` creates the Map without deploying. The Map ID is a public identifier, not a
+credential or the portable `id` in your config. CI always deploys an existing Map with a deploy key
+for that destination. `logout` removes the saved personal session.
 
 Deploy publishes the compiled concrete-theme family and managed icon assets; it does not ask the
 server to compile TypeScript. Repeating an unchanged deployment reuses its version. Build writers

package/dist/index.js

@@ -3,13 +3,13 @@
 // src/index.ts
 import { serve } from "@hono/node-server";
 import { Command } from "commander";
-import { createHash as createHash4, randomBytes as randomBytes2 } from "crypto";
+import { createHash as createHash4, randomBytes as randomBytes3 } 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 dirname13, isAbsolute as isAbsolute5, relative as relative6, resolve as resolve12, sep as sep5 } from "path";
-import { createInterface } from "readline/promises";
-import pc7 from "picocolors";
+import { createInterface as createInterface2 } from "readline/promises";
+import pc9 from "picocolors";
 import { createLocalCoordinates, setupCoordinates } from "@tileflow/coordinates-runtime";
 import {
   auditTileflowMapThemeValues as auditTileflowMapThemeValues2,
@@ -4447,6 +4447,88 @@ async function listAccountTeams(session, options = {}) {
   }
   return { ok: true, teams };
 }
+async function listMapSetupTeams(session, options = {}) {
+  let response;
+  try {
+    response = await requestHostedJson(
+      session.apiOrigin,
+      "/v1/cli/map-setup/teams",
+      { headers: authorizationHeaders(session.accountSession) },
+      options
+    );
+  } catch (error) {
+    return { error: safeTransportError(error, "Team discovery failed."), ok: false };
+  }
+  if (!response.ok) {
+    return {
+      error: response.status === 401 ? rejectedAccountSessionMessage : `Team discovery failed (${response.status}).`,
+      ok: false
+    };
+  }
+  const body = asRecord(response.body);
+  if (!response.json || body.schemaVersion !== 1 || !Array.isArray(body.teams) || !body.teams.every(isMapSetupTeam)) {
+    return { error: "Team discovery returned an invalid response.", ok: false };
+  }
+  return { ok: true, teams: body.teams };
+}
+async function createManagedMapSetup(session, input, options = {}) {
+  let response;
+  try {
+    response = await requestHostedJson(
+      session.apiOrigin,
+      "/v1/cli/maps",
+      {
+        ...jsonRequest("POST", input),
+        headers: {
+          ...authorizationHeaders(session.accountSession),
+          "Content-Type": "application/json"
+        }
+      },
+      options
+    );
+  } catch (error) {
+    return {
+      code: "setup_failed",
+      error: safeTransportError(error, "Map setup request failed."),
+      ok: false
+    };
+  }
+  const body = asRecord(response.body);
+  if (!response.ok) {
+    if (response.status === 401) {
+      return { code: "account_session_rejected", error: rejectedAccountSessionMessage, ok: false };
+    }
+    const code = mapSetupFailureMessages[body.code] ? body.code : null;
+    return code ? { code, error: mapSetupFailureMessages[code], ok: false } : { code: "setup_failed", error: `Map setup failed (${response.status}).`, ok: false };
+  }
+  const map = asRecord(body.map);
+  const team = asRecord(body.team);
+  const delivery = asRecord(body.delivery);
+  if (!response.json || body.schemaVersion !== 1 || typeof map.id !== "string" || !/^map_[A-Za-z0-9_-]{16}$/u.test(map.id) || map.name !== null && typeof map.name !== "string" || map.state !== "setup_pending" && map.state !== "active" || typeof team.name !== "string" || `@${String(team.slug)}` !== input.team || !Array.isArray(delivery.allowedOrigins) || !delivery.allowedOrigins.every((origin) => typeof origin === "string") || delivery.allowedOrigins.length !== input.allowedOrigins.length) {
+    return { code: "setup_failed", error: "Map setup returned an invalid response.", ok: false };
+  }
+  return {
+    ok: true,
+    value: {
+      allowedOrigins: delivery.allowedOrigins,
+      map: { id: map.id, name: map.name, state: map.state },
+      team: { name: team.name, slug: team.slug }
+    }
+  };
+}
+var mapSetupFailureMessages = {
+  invalid_request: "Tileflow rejected the Map setup request.",
+  map_limit: "This Team has reached its Map limit. Archive or delete a Map, or change the plan, in the Tileflow dashboard.",
+  permission_required: "Only a Team Admin can create Maps.",
+  setup_conflict: "This setup key was already used with another Team or browser access choice. Omit --setup-key to start a new setup.",
+  team_not_found: "No Team you administer matches this Team."
+};
+function isMapSetupTeam(value) {
+  const team = asRecord(value);
+  return typeof team.eligible === "boolean" && typeof team.name === "string" && typeof team.slug === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u.test(team.slug) && (team.unavailableReason === void 0 || team.unavailableReason === "map_limit") && Object.keys(team).every(
+    (key) => ["eligible", "name", "slug", "unavailableReason"].includes(key)
+  );
+}
 async function publishHostedStyle(api, body, responseLabel, options = {}) {
   const response = await requestHostedJson(
     api.apiUrl,
@@ -6917,10 +6999,299 @@ async function readCurrentPins(contents) {
   return (await parseTileflowIconsLockfile(contents)).sets;
 }
 
+// src/map-commands.ts
+import pc5 from "picocolors";
+
+// src/map-setup.ts
+import { randomBytes as randomBytes2 } from "crypto";
+import { createInterface } from "readline/promises";
+import pc4 from "picocolors";
+var maximumOrigins2 = 20;
+var exactHost = /^(?:[a-z0-9-]+(?:\.[a-z0-9-]+)*|\[[0-9a-f:.]+\])$/u;
+var teamReference = /^@([A-Za-z0-9][A-Za-z0-9._-]{0,127})$/u;
+var setupKeyPattern = /^[\x21-\x7e]{8,128}$/u;
+function resolveMapSetupTeam(teams, requestedSlug) {
+  if (requestedSlug !== void 0) {
+    const team = teams.find(({ slug }) => slug === requestedSlug);
+    if (!team) return { kind: "not_found" };
+    return team.eligible ? { kind: "selected", team } : { kind: "map_limit" };
+  }
+  const eligible = teams.filter((team) => team.eligible);
+  if (eligible.length === 1) return { kind: "selected", team: eligible[0] };
+  if (eligible.length > 1) return { kind: "choose", teams: eligible };
+  return teams.some((team) => team.unavailableReason === "map_limit") ? { kind: "map_limit" } : { kind: "none" };
+}
+function normalizeBrowserOrigin(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return null;
+  }
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password || url.pathname !== "/" || url.search || url.hash || !exactHost.test(url.hostname) || value.toLowerCase() !== url.origin.toLowerCase()) {
+    return null;
+  }
+  return url.origin.toLowerCase();
+}
+function parseBrowserAccess(options) {
+  const values = options.origin ?? [];
+  if (options.anyWebsite && values.length > 0) {
+    return { error: "Choose either --any-website or --origin, not both.", ok: false };
+  }
+  if (options.anyWebsite) return { ok: true, value: { kind: "any" } };
+  if (values.length === 0) return { ok: true, value: null };
+  return parseOriginList(values);
+}
+function parseOriginList(values) {
+  const origins = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    const origin = normalizeBrowserOrigin(value.trim());
+    if (!origin) {
+      return {
+        error: `${JSON.stringify(value)} is not an exact website origin such as https://example.com (no path or wildcard).`,
+        ok: false
+      };
+    }
+    origins.add(origin);
+  }
+  if (origins.size === 0 || origins.size > maximumOrigins2) {
+    return { error: `Enter between 1 and ${maximumOrigins2} website origins.`, ok: false };
+  }
+  return { ok: true, value: { kind: "selected", origins: [...origins].sort() } };
+}
+function checkMapSetupOptions(options) {
+  if (options.team !== void 0 && !teamReference.test(options.team)) {
+    return { code: "invalid_team", error: "Team must use @team syntax.", ok: false };
+  }
+  if (options.setupKey !== void 0 && !setupKeyPattern.test(options.setupKey)) {
+    return {
+      code: "invalid_setup_key",
+      error: "Setup key must be 8 to 128 visible ASCII characters without spaces.",
+      ok: false
+    };
+  }
+  if (options.name !== void 0 && (options.name.length < 1 || options.name.length > 200 || options.name !== options.name.trim() || /\p{Cc}/u.test(options.name))) {
+    return { code: "invalid_name", error: "Map name must be 1 to 200 characters.", ok: false };
+  }
+  const access = parseBrowserAccess(options);
+  return access.ok ? { access: access.value, ok: true } : { code: "invalid_browser_access", error: access.error, ok: false };
+}
+async function setUpManagedMap(session, options, dependencies) {
+  const checked = checkMapSetupOptions(options);
+  if (!checked.ok) return checked;
+  const discovered = await listMapSetupTeams(session, dependencies.request);
+  if (!discovered.ok) {
+    return { code: "team_discovery_failed", error: discovered.error, ok: false };
+  }
+  const resolution = resolveMapSetupTeam(
+    discovered.teams,
+    options.team ? teamReference.exec(options.team)[1] : void 0
+  );
+  let team = null;
+  if (resolution.kind === "selected") team = resolution.team;
+  else if (resolution.kind === "choose") {
+    team = dependencies.prompts ? await dependencies.prompts.chooseTeam(resolution.teams) : null;
+    if (!team) {
+      const choices = resolution.teams.map(({ slug }) => `@${slug}`);
+      return {
+        code: "team_ambiguous",
+        error: `Several Teams can own this Map. Choose one with --team: ${choices.join(", ")}.`,
+        ok: false,
+        options: choices
+      };
+    }
+  } else if (resolution.kind === "map_limit") {
+    return {
+      code: "map_limit",
+      error: options.team ? `${options.team} has reached its Map limit. Archive or delete a Map, or change the plan, in the Tileflow dashboard.` : "Every Team you administer has reached its Map limit. Archive or delete a Map, or change the plan, in the Tileflow dashboard.",
+      ok: false
+    };
+  } else if (resolution.kind === "not_found") {
+    return { code: "team_not_found", error: `You do not administer ${options.team}.`, ok: false };
+  } else {
+    return {
+      code: "no_eligible_team",
+      error: "This account does not administer a Team. Ask a Team Admin to create the Map.",
+      ok: false
+    };
+  }
+  const access = checked.access ?? (dependencies.prompts ? await dependencies.prompts.chooseAccess() : null);
+  if (!access) {
+    return {
+      code: "browser_access_required",
+      error: "Choose which websites may load this Map: --origin <origin> (repeatable) for exact sites, or --any-website.",
+      ok: false
+    };
+  }
+  const setupKey = options.setupKey ?? `cli-${randomBytes2(16).toString("hex")}`;
+  const created = await createManagedMapSetup(
+    session,
+    {
+      allowedOrigins: access.kind === "any" ? [] : access.origins,
+      idempotencyKey: setupKey,
+      ...options.name ? { name: options.name } : {},
+      team: `@${team.slug}`
+    },
+    dependencies.request
+  );
+  return created.ok ? { ok: true, setupKey, value: created.value } : created;
+}
+function describeBrowserAccess(allowedOrigins) {
+  return allowedOrigins.length === 0 ? "Any website" : allowedOrigins.join(", ");
+}
+function createTerminalPrompts(json2 = false) {
+  if (json2 || !process.stdin.isTTY || !process.stdout.isTTY) return null;
+  return {
+    async chooseTeam(teams) {
+      console.log(`${pc4.cyan("?")} Which Team should own the new Map?`);
+      teams.forEach(
+        (team, index) => console.log(`  ${index + 1}) ${team.name} ${pc4.gray(`@${team.slug}`)}`)
+      );
+      const answer = await ask("Team number", (value) => {
+        const index = Number(value);
+        return Number.isInteger(index) && index >= 1 && index <= teams.length ? teams[index - 1] : null;
+      });
+      return answer;
+    },
+    async chooseAccess() {
+      console.log(`${pc4.cyan("?")} Which websites may load this Map in a browser?`);
+      console.log("  1) Only selected websites (recommended)");
+      console.log("  2) Any website");
+      const mode = await ask(
+        "Choice",
+        (value) => value === "1" ? "selected" : value === "2" ? "any" : null
+      );
+      if (mode === null) return null;
+      if (mode === "any") return { kind: "any" };
+      return ask("Website origins, separated by spaces (https://example.com)", (value) => {
+        const parsed = parseOriginList(value.split(/[\s,]+/u).filter(Boolean));
+        if (!parsed.ok) console.log(`  ${pc4.yellow(parsed.error)}`);
+        return parsed.ok ? parsed.value : null;
+      });
+    }
+  };
+}
+async function ask(question, parse3) {
+  const readline = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+      const value = parse3((await readline.question(`  ${question}: `)).trim());
+      if (value !== null) return value;
+    }
+    return null;
+  } finally {
+    readline.close();
+  }
+}
+
+// src/map-commands.ts
+function registerMapCommands(program2, dependencies) {
+  const maps = program2.command("maps").description("Manage Tileflow managed Maps");
+  addMapSetupOptions(
+    maps.command("create").description("Create a managed Map for this account, ready for tileflow deploy --map-id").option("--api-url <url>", "Tileflow API URL", process.env.TILEFLOW_API_URL).option("--name <name>", "Map name shown in the dashboard").option("--json", "print deterministic schema-version-1 JSON")
+  ).action(async (options) => {
+    const session = await loadSession(options, dependencies);
+    if (!session) return;
+    const result = await setUpManagedMap(session, options, {
+      prompts: createTerminalPrompts(options.json)
+    });
+    if (!result.ok) {
+      emitFailure(
+        options.json,
+        result.code,
+        result.error,
+        result.options ? { options: result.options } : {}
+      );
+      return;
+    }
+    const next = `tileflow deploy --map-id ${result.value.map.id}`;
+    if (options.json) {
+      emitJson({
+        command: "maps create",
+        delivery: { allowedOrigins: result.value.allowedOrigins },
+        map: result.value.map,
+        next,
+        ok: true,
+        schemaVersion: 1,
+        setupKey: result.setupKey,
+        team: result.value.team
+      });
+      return;
+    }
+    printCreatedMap(result.value);
+    console.log(`
+${pc5.bold("Next step")}`);
+    console.log(`  ${pc5.cyan("\u2022")} Publish the repository map with ${pc5.cyan(next)}.`);
+  });
+}
+function addMapSetupOptions(command2) {
+  return command2.option("--team <team>", "Team that owns a new Map, as @team").option(
+    "--origin <origin>",
+    "exact website origin that may load a new Map (repeatable)",
+    (value, previous = []) => [...previous, value]
+  ).option("--any-website", "let any website load a new Map").option("--setup-key <key>", "repeat an interrupted Map creation with the key it printed");
+}
+function hasMapSetupOptions(options) {
+  return options.team !== void 0 || (options.origin?.length ?? 0) > 0 || options.anyWebsite === true || options.setupKey !== void 0;
+}
+async function createMapForDeploy(options, dependencies) {
+  const session = await loadSession(options, dependencies);
+  if (!session) return null;
+  console.log(`${pc5.cyan("i")} No --map-id given; creating a managed Map for this deploy.`);
+  const result = await setUpManagedMap(session, options, {
+    prompts: dependencies.prompts === void 0 ? createTerminalPrompts() : dependencies.prompts
+  });
+  if (!result.ok) {
+    emitFailure(false, result.code, result.error);
+    return null;
+  }
+  printCreatedMap(result.value);
+  console.log(
+    pc5.gray(
+      `If this deploy is interrupted, rerun it with --setup-key ${result.setupKey} to reuse the same Map.`
+    )
+  );
+  return result.value.map.id;
+}
+function printCreatedMap(created) {
+  console.log(
+    `${pc5.green("\u2713")} Created ${pc5.bold(created.map.id)} in ${created.team.name} ${pc5.gray(`@${created.team.slug}`)}.`
+  );
+  console.log(
+    `${pc5.gray("Websites:".padEnd(13))} ${describeBrowserAccess(created.allowedOrigins)}`
+  );
+}
+async function loadSession(options, dependencies) {
+  let apiUrl;
+  try {
+    apiUrl = normalizeApiOrigin(options.apiUrl ?? dependencies.defaultApiUrl);
+  } catch (error) {
+    emitFailure(options.json, "invalid_api_url", safeMessage(error));
+    return null;
+  }
+  let config;
+  try {
+    config = await dependencies.loadAuthConfig();
+  } catch (error) {
+    emitFailure(options.json, "auth_state_unavailable", safeMessage(error));
+    return null;
+  }
+  const selected = resolveAccountSession(config, apiUrl);
+  if (selected.kind !== "selected") {
+    emitFailure(
+      options.json,
+      `account_session_${selected.kind}`,
+      selected.kind === "expired" ? "The Tileflow account session has expired. Run tileflow login." : "Creating a Map needs a Tileflow account session. Run tileflow login."
+    );
+    return null;
+  }
+  return selected.session;
+}
+
 // src/model-command.ts
 import { lstat as lstat5 } from "fs/promises";
 import { basename as basename4, dirname as dirname11, relative as relative4, resolve as resolve8 } from "path";
-import pc4 from "picocolors";
+import pc6 from "picocolors";
 import { z as z5 } from "zod";
 import { tileflowModelContentType } from "@tileflow/core";
 import {
@@ -6998,7 +7369,7 @@ function registerModelCommands(program2, dependencies) {
         const current = parsed.data.model.current;
         const action = parsed.data.changed ? "Published" : "Unchanged";
         console.log(
-          `${pc4.green("\u2713")} ${action} 3D model ${pc4.bold(name)} version ${current.version} (${formatBytes3(current.byteLength)}, ${formatCount(current.summary.levels[0]?.triangles ?? 0)} triangles).`
+          `${pc6.green("\u2713")} ${action} 3D model ${pc6.bold(name)} version ${current.version} (${formatBytes3(current.byteLength)}, ${formatCount(current.summary.levels[0]?.triangles ?? 0)} triangles).`
         );
       }
     }
@@ -7047,7 +7418,7 @@ function registerModelCommands(program2, dependencies) {
       for (const model of listed) {
         const current = model.current;
         console.log(
-          `${pc4.bold(model.name)}  ${current ? `version ${current.version}, ${formatBytes3(current.byteLength)}` : "no current version"}  ${model.usedByMaps === 1 ? "1 map" : `${model.usedByMaps} maps`}${model.state === "purging" ? pc4.yellow("  purging") : ""}`
+          `${pc6.bold(model.name)}  ${current ? `version ${current.version}, ${formatBytes3(current.byteLength)}` : "no current version"}  ${model.usedByMaps === 1 ? "1 map" : `${model.usedByMaps} maps`}${model.state === "purging" ? pc6.yellow("  purging") : ""}`
         );
       }
     }
@@ -7064,7 +7435,7 @@ function registerModelCommands(program2, dependencies) {
     if (options.json) return emitJson({ ...detail, command: "models status", ok: true });
     const { model, versions, uses } = detail;
     console.log(
-      `${pc4.bold(model.name)}${model.state === "purging" ? pc4.yellow(" (purging)") : ""}`
+      `${pc6.bold(model.name)}${model.state === "purging" ? pc6.yellow(" (purging)") : ""}`
     );
     for (const version of versions) {
       const role = version.state === "current" ? "current" : version.state === "previous" ? "previous" : version.state;
@@ -7119,7 +7490,7 @@ function registerModelCommands(program2, dependencies) {
         model: parsed.data.model
       });
     console.log(
-      `${pc4.green("\u2713")} ${pc4.bold(name)} is at version ${previous.version} again; version ${current.version} is its previous one. Maps draw it on their next load.`
+      `${pc6.green("\u2713")} ${pc6.bold(name)} is at version ${previous.version} again; version ${current.version} is its previous one. Maps draw it on their next load.`
     );
   });
   withTeamOptions2(
@@ -7156,7 +7527,7 @@ function registerModelCommands(program2, dependencies) {
         purge: parsed.data.purge
       });
     console.log(
-      `${pc4.green("\u2713")} ${pc4.bold(name)} is being purged; its name is free once its files are deleted.`
+      `${pc6.green("\u2713")} ${pc6.bold(name)} is being purged; its name is free once its files are deleted.`
     );
   });
 }
@@ -7420,7 +7791,7 @@ function resolveTileflowExternalOpenInvocation(target, platform) {
 }
 
 // src/project-commands.ts
-import pc5 from "picocolors";
+import pc7 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) => {
@@ -7436,12 +7807,12 @@ function registerProjectCommands(program2, dependencies) {
     };
     if (options.json) return emitJson2(document);
     if (!result.items.length) {
-      console.log(pc5.gray("No managed destinations found."));
+      console.log(pc7.gray("No managed destinations found."));
       return;
     }
     for (const target of result.items) {
       console.log(
-        `  ${target.project.archivedAt ? pc5.yellow("\u25CB") : pc5.green("\u25CF")} ${pc5.bold(target.project.name)} ${pc5.gray(target.reference)}${target.project.archivedAt ? pc5.gray(" (archived)") : ""}`
+        `  ${target.project.archivedAt ? pc7.yellow("\u25CB") : pc7.green("\u25CF")} ${pc7.bold(target.project.name)} ${pc7.gray(target.reference)}${target.project.archivedAt ? pc7.gray(" (archived)") : ""}`
       );
     }
   });
@@ -7494,8 +7865,8 @@ function registerProjectCommands(program2, dependencies) {
         ...asRecord2(result.body)
       };
       if (options.json) return emitJson2(document);
-      console.log(`${pc5.green("\u2713")} Application ${pc5.bold(options.name.trim())} is ready.`);
-      console.log(pc5.gray(`Its technical selector is --project @${organization.slug}/${slug}.`));
+      console.log(`${pc7.green("\u2713")} Application ${pc7.bold(options.name.trim())} is ready.`);
+      console.log(pc7.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) => {
@@ -7517,8 +7888,8 @@ function registerProjectCommands(program2, dependencies) {
     if (!isProjectItem(project)) {
       return emitLocalFailure(false, "invalid_response", "Destination response was invalid.");
     }
-    console.log(`${pc5.bold(project.name)} ${pc5.gray(target)}`);
-    console.log(project.archivedAt ? pc5.yellow("Archived") : pc5.green("Active"));
+    console.log(`${pc7.bold(project.name)} ${pc7.gray(target)}`);
+    console.log(project.archivedAt ? pc7.yellow("Archived") : pc7.green("Active"));
   });
   for (const archived of [true, false]) {
     const verb = archived ? "archive" : "unarchive";
@@ -7545,7 +7916,7 @@ function registerProjectCommands(program2, dependencies) {
         ...asRecord2(result.body)
       };
       if (options.json) return emitJson2(document);
-      console.log(`${pc5.green("\u2713")} Application ${archived ? "archived" : "unarchived"}.`);
+      console.log(`${pc7.green("\u2713")} Application ${archived ? "archived" : "unarchived"}.`);
     });
   }
 }
@@ -7656,7 +8027,7 @@ function emitLocalFailure(json2, code, message, details = {}) {
     console.error(message);
     emitJson2({ schemaVersion: 1, ok: false, error: { code, ...details } });
   } else {
-    console.error(`${pc5.red("\u2715")} ${message}`);
+    console.error(`${pc7.red("\u2715")} ${message}`);
   }
   process.exitCode = 1;
 }
@@ -7800,7 +8171,7 @@ async function runRendererArtifactCommand(command2, options) {
 }
 
 // src/tileset-command.ts
-import pc6 from "picocolors";
+import pc8 from "picocolors";
 import { z as z7 } from "zod";
 import { serializeCanonicalJson as serializeCanonicalJson6 } from "@tileflow/core";
 import { inspectTileflowPmtiles } from "@tileflow/dev/tilesets";
@@ -8459,7 +8830,7 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
 `);
           return;
         }
-        console.log(`${pc6.green("\u2713")} PMTiles archive is valid.`);
+        console.log(`${pc8.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}`);
@@ -8469,7 +8840,7 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
           );
         }
         for (const warning of inspection.warnings) {
-          console.log(`${pc6.yellow("!")} ${warning.message}`);
+          console.log(`${pc8.yellow("!")} ${warning.message}`);
         }
       } catch (error) {
         const record = asRecord4(error);
@@ -8482,7 +8853,7 @@ function registerTilesetInspectCommand(parent, name = "inspect") {
 `
           );
         } else {
-          console.error(`${pc6.red("Error:")} ${message}`);
+          console.error(`${pc8.red("Error:")} ${message}`);
         }
         process.exitCode = 1;
       }
@@ -8570,7 +8941,7 @@ function registerTilesetCommands(program2, dependencies) {
         };
         if (options.json) return emitJson(document);
         console.log(
-          `${pc6.green("\u2713")} ${publication.changed ? "Published" : "Unchanged"} ${pc6.bold(options.id)} in ${authority.team ? `@${authority.team.slug}` : "the Team bound to the data key"}.`
+          `${pc8.green("\u2713")} ${publication.changed ? "Published" : "Unchanged"} ${pc8.bold(options.id)} in ${authority.team ? `@${authority.team.slug}` : "the Team bound to the data key"}.`
         );
       } catch (error) {
         if (error instanceof TeamTilesetUploadError) {
@@ -8590,9 +8961,9 @@ function registerTilesetCommands(program2, dependencies) {
       const items = await fetchAllTeamTilesets(authority);
       const document = { command: "tileset list", schemaVersion: 1, tilesets: items };
       if (options.json) return emitJson(document);
-      if (items.length === 0) return console.log(pc6.gray("No Team tilesets."));
+      if (items.length === 0) return console.log(pc8.gray("No Team tilesets."));
       for (const item of items) {
-        console.log(`  ${pc6.bold(item.logicalName)} ${pc6.gray(item.status)}`);
+        console.log(`  ${pc8.bold(item.logicalName)} ${pc8.gray(item.status)}`);
       }
     } catch {
       emitFailure(options.json, "tileset_list_failed", "Tileset list failed.");
@@ -8620,7 +8991,7 @@ function registerTilesetCommands(program2, dependencies) {
       const document = { command: "tileset status", schemaVersion: 1, tileset: parsed.tileset };
       if (options.json) return emitJson(document);
       const item = parsed.tileset;
-      console.log(`${pc6.bold(item.name)} ${pc6.gray(item.state)}`);
+      console.log(`${pc8.bold(item.name)} ${pc8.gray(item.state)}`);
       console.log(`  ID: ${item.id}`);
       console.log(`  Current version: ${String(item.currentVersion ?? "unpublished")}`);
     } catch {
@@ -8671,7 +9042,7 @@ function registerTilesetCommands(program2, dependencies) {
       const parsed = tilesetPurgeResponseSchema.parse(response.body);
       const document = { command: "tileset purge", schemaVersion: 1, ...parsed };
       if (options.json) return emitJson(document);
-      console.log(`${pc6.green("\u2713")} Purge ${parsed.reclamation}.`);
+      console.log(`${pc8.green("\u2713")} Purge ${parsed.reclamation}.`);
     } catch {
       emitFailure(options.json, "tileset_purge_failed", "Tileset purge failed.");
     }
@@ -9611,7 +9982,7 @@ var defaultApiUrl = defaultTileflowApiUrl;
 var defaultAppUrl = "https://tileflow.dev";
 var defaultConfigPath = defaultTileflowConfigPath2;
 var defaultManifestPath = defaultTileflowManifestPath;
-program.name("tileflow").description("Beautiful maps from config.").enablePositionalOptions().showHelpAfterError(pc7.gray("\nRun tileflow <command> --help for usage.")).showSuggestionAfterError();
+program.name("tileflow").description("Beautiful maps from config.").enablePositionalOptions().showHelpAfterError(pc9.gray("\nRun tileflow <command> --help for usage.")).showSuggestionAfterError();
 program.addHelpText("after", "\n  -V, --version  output the version number\n");
 registerDescribeCommand(program);
 registerLanguageCommand(program);
@@ -9636,9 +10007,9 @@ program.command("init").description("Create a starter tileflow.config.ts").optio
   }
   logSuccess(`Created ${pathLabel(defaultConfigPath)}.`);
   printKeyValue("Path", pathLabel(configPath));
-  printKeyValue("Map", pc7.bold("madrid"));
+  printKeyValue("Map", pc9.bold("madrid"));
   printNextSteps([
-    `Install ${pc7.cyan("@tileflow/core")} and ${pc7.cyan("@tileflow/maps")} in this project if needed.`,
+    `Install ${pc9.cyan("@tileflow/core")} and ${pc9.cyan("@tileflow/maps")} in this project if needed.`,
     `Preview locally with ${command("tileflow preview")}.`,
     `Validate the config with ${command("tileflow validate")}.`
   ]);
@@ -10205,12 +10576,17 @@ program.command("preview").description("Open Map DevTools with inspection and op
     });
   }
 );
-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("--with-native", "publish web and native-v1 together for the selected managed Map").option("--map <name>", "configured map to connect when the repository contains multiple maps").option(
+addMapSetupOptions(
+  program.command("deploy").description(
+    "Deploy maps to Tileflow and write the frontend manifest; without --map-id, create the Map first"
+  )
+).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; omit it to create a new Map").option("--with-native", "publish web and native-v1 together for the selected managed Map").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"
 ).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);
+    if (!validateMapSetupTarget(options, source)) return;
     const resolveApi = () => requireApiOptions(options, {
       allowStoredCredential: allowsStoredDeployCredential(source),
       assertExplicitKeyMap: true,
@@ -10230,7 +10606,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       );
       if (result) {
         logSuccess(
-          `${result.changed ? "Published" : "Unchanged"} ${pc7.bold(result.mapName)} web + native-v1 (v${result.version}).`
+          `${result.changed ? "Published" : "Unchanged"} ${pc9.bold(result.mapName)} web + native-v1 (v${result.version}).`
         );
         printKeyValue("Manifest", pathLabel(result.manifestPath));
         printKeyValue("Native", link(result.nativeManifestUrl));
@@ -10325,6 +10701,21 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       return;
     }
     const existingManifest = outputManifest;
+    let createdMapId = null;
+    if (!options.mapId) {
+      const deployedMapId2 = existingManifest?.maps[mapNames[0]]?.mapId;
+      if (deployedMapId2) {
+        logError(`${pc9.bold(mapNames[0])} is already deployed to ${deployedMapId2}.`);
+        printNextSteps([
+          `Deploy it again with ${command(`tileflow deploy --map-id ${deployedMapId2}`)}.`
+        ]);
+        process.exitCode = 1;
+        return;
+      }
+      createdMapId = await createMapForDeploy(options, { defaultApiUrl, loadAuthConfig });
+      if (!createdMapId) return;
+      options.mapId = createdMapId;
+    }
     const api = await resolveApi();
     if (!api) return;
     const hostedSpriteByPackageHash = /* @__PURE__ */ new Map();
@@ -10344,7 +10735,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 ${pc7.bold(binding?.label ?? "Icons")} (${plural(iconPackage.manifest.iconNames.length, "icon")}, ${formatBytes4(totalBytes)}, ${iconPackage.contentHash.slice(0, 12)}).`
+        `${action} icon package ${pc9.bold(binding?.label ?? "Icons")} (${plural(iconPackage.manifest.iconNames.length, "icon")}, ${formatBytes4(totalBytes)}, ${iconPackage.contentHash.slice(0, 12)}).`
       );
       hostedSpriteByPackageHash.set(iconPackage.contentHash, uploaded.value.spriteUrl);
     }
@@ -10506,7 +10897,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
       }
       const themeNames = Object.keys(themeStyles).sort();
       logInfo(
-        `Deploying compiled map ${pc7.bold(mapName)} (${plural(themeNames.length, "theme")}).`
+        `Deploying compiled map ${pc9.bold(mapName)} (${plural(themeNames.length, "theme")}).`
       );
       const response = await publishHostedStyle(
         api,
@@ -10588,14 +10979,14 @@ 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 ${pc7.bold(mapName)}${versionLabel}.`);
+        logSuccess(`Unchanged ${pc9.bold(mapName)}${versionLabel}.`);
       } else {
-        logSuccess(`Published ${pc7.bold(mapName)}${versionLabel}.`);
+        logSuccess(`Published ${pc9.bold(mapName)}${versionLabel}.`);
       }
       for (const teamModel of body.teamModels ?? []) {
         if (teamModel.sources !== "differ") continue;
         logWarning(
-          `3D model ${pc7.bold(teamModel.model)} draws its published version ${teamModel.version}, which was not prepared from this project's files. Run \`tileflow models publish\` to publish them.`
+          `3D model ${pc9.bold(teamModel.model)} draws its published version ${teamModel.version}, which was not prepared from this project's files. Run \`tileflow models publish\` to publish them.`
         );
       }
     }
@@ -10612,6 +11003,7 @@ program.command("deploy").description("Deploy maps to Tileflow and write the fro
     const deployedMapId = Object.values(deployedMaps)[0]?.mapId;
     if (deployedMapId) {
       printNextSteps([
+        ...createdMapId ? [`Deploy later changes with ${command(`tileflow deploy --map-id ${createdMapId}`)}.`] : [],
         `Check hosted state with ${command(`tileflow status --map-id ${deployedMapId}`)}.`
       ]);
     }
@@ -10712,6 +11104,7 @@ registerProjectCommands(program, {
   defaultApiUrl,
   loadAuthConfig
 });
+registerMapCommands(program, { defaultApiUrl, loadAuthConfig });
 if (isRootCliVersionRequest(process.argv.slice(2))) {
   process.stdout.write(`${packageJson.version}
 `);
@@ -11003,17 +11396,17 @@ async function loginWithDeviceFlow(options) {
     codeChallenge,
     deviceName: hostname()
   });
-  printKeyValue("Code", pc7.bold(authorization.userCode));
+  printKeyValue("Code", pc9.bold(authorization.userCode));
   printKeyValue("URL", link(authorization.verificationUriComplete));
   if (options.noBrowser) {
     logMuted("Open the URL above to continue.");
   } else if (process.stdin.isTTY) {
-    const readline = createInterface({
+    const readline = createInterface2({
       input: process.stdin,
       output: process.stdout
     });
     try {
-      await readline.question(`${pc7.cyan("?")} Press Enter to open Tileflow Dashboard...`);
+      await readline.question(`${pc9.cyan("?")} Press Enter to open Tileflow Dashboard...`);
       openBrowser(authorization.verificationUriComplete);
     } finally {
       readline.close();
@@ -11050,7 +11443,7 @@ function createPkceChallenge(verifier) {
   return createHash4("sha256").update(verifier).digest("base64url");
 }
 function randomBase64Url(byteLength) {
-  return randomBytes2(byteLength).toString("base64url");
+  return randomBytes3(byteLength).toString("base64url");
 }
 function openBrowser(url, errorsToStderr = false) {
   openTileflowExternal(url, {
@@ -11102,11 +11495,6 @@ function createCompiledMapAssets(compiled, resolveSprite, modelAssets) {
   };
 }
 function selectManagedDeployMaps(mapNames, options) {
-  if (options.map && !options.mapId) {
-    logError("--map requires --map-id.");
-    process.exitCode = 1;
-    return null;
-  }
   if (options.map) {
     if (!mapNames.includes(options.map)) {
       logError(`Unknown Tileflow map: ${options.map}.`);
@@ -11116,24 +11504,40 @@ function selectManagedDeployMaps(mapNames, options) {
     }
     return [options.map];
   }
-  if (!options.mapId) return mapNames;
   if (mapNames.length === 1) return [mapNames[0]];
   logError(
     "This managed target requires an explicit map because the config contains multiple maps."
   );
   printKeyValue("Maps", mapNames.join(", "));
   printNextSteps([
-    `Retry with ${command(`tileflow deploy --map-id ${options.mapId} --map ${mapNames[0]}`)}.`
+    `Retry with ${command(`tileflow deploy ${options.mapId ? `--map-id ${options.mapId} ` : ""}--map ${mapNames[0]}`)}.`
   ]);
   process.exitCode = 1;
   return null;
 }
-function validateDeployTarget(options) {
-  if (!options.mapId) {
-    logError("Managed deploy requires --map-id.");
+function validateMapSetupTarget(options, source) {
+  const fail = (message, steps = []) => {
+    logError(message);
+    printNextSteps(steps);
     process.exitCode = 1;
     return false;
+  };
+  if (options.mapId) {
+    return hasMapSetupOptions(options) ? fail(
+      "--team, --origin, --any-website and --setup-key apply only when deploy creates a Map."
+    ) : true;
+  }
+  const createFirst = `Create the Map with ${command("tileflow maps create")} after ${command("tileflow login")}, then pass --map-id.`;
+  if (options.withNative) return fail("--with-native requires one valid --map-id.", [createFirst]);
+  if (options.apiKey || !allowsStoredDeployCredential(source)) {
+    return fail("Managed deploy with a Tileflow credential or in CI requires --map-id.", [
+      createFirst
+    ]);
   }
+  const checked = checkMapSetupOptions(options);
+  return checked.ok ? true : fail(checked.error);
+}
+function validateDeployTarget(options) {
   if (options.mapId && !/^map_[A-Za-z0-9_-]{16}$/u.test(options.mapId)) {
     logError("Managed Map ID is invalid.");
     process.exitCode = 1;
@@ -11214,7 +11618,7 @@ async function requireApiOptions(options, behavior = {}) {
     if (!behavior.silent) {
       logError("CI requires an explicit Tileflow credential with access to the target Map.");
       printNextSteps([
-        `Set ${pc7.cyan("TILEFLOW_API_KEY")} from the CI secret store.`,
+        `Set ${pc9.cyan("TILEFLOW_API_KEY")} from the CI secret store.`,
         "The saved personal account session is never used in CI."
       ]);
     }
@@ -11283,17 +11687,17 @@ function printCliError(error) {
   }
   const message = error instanceof Error ? error.message : "Command failed.";
   if (message.includes("Cannot find module '@tileflow/core'")) {
-    logError(`Cannot load ${pc7.cyan("@tileflow/core")} from this project.`);
+    logError(`Cannot load ${pc9.cyan("@tileflow/core")} from this project.`);
     printNextSteps([
-      `Install ${pc7.cyan("@tileflow/core")} in this project.`,
+      `Install ${pc9.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 ${pc7.cyan("@tileflow/maps")} from this project.`);
+    logError(`Cannot load ${pc9.cyan("@tileflow/maps")} from this project.`);
     printNextSteps([
-      `Install ${pc7.cyan("@tileflow/maps")} in this project.`,
+      `Install ${pc9.cyan("@tileflow/maps")} in this project.`,
       `Run the command again from the project root.`
     ]);
     return;
@@ -11304,51 +11708,51 @@ function printCliError(error) {
   }
 }
 function logSuccess(message) {
-  console.log(`${pc7.green("\u2713")} ${message}`);
+  console.log(`${pc9.green("\u2713")} ${message}`);
 }
 function logError(message) {
-  console.log(`${pc7.red("\u2715")} ${message}`);
+  console.log(`${pc9.red("\u2715")} ${message}`);
 }
 function logWarning(message) {
-  console.log(`${pc7.yellow("!")} ${message}`);
+  console.log(`${pc9.yellow("!")} ${message}`);
 }
 function logInfo(message) {
-  console.log(`${pc7.cyan("i")} ${message}`);
+  console.log(`${pc9.cyan("i")} ${message}`);
 }
 function logMuted(message) {
-  console.log(pc7.gray(message));
+  console.log(pc9.gray(message));
 }
 function printTitle(title, subtitle) {
-  console.log(pc7.bold(title));
+  console.log(pc9.bold(title));
   if (subtitle) {
-    console.log(pc7.gray(subtitle));
+    console.log(pc9.gray(subtitle));
   }
 }
 function printKeyValue(label, value) {
-  console.log(`${pc7.gray(`${label}:`.padEnd(13))} ${value}`);
+  console.log(`${pc9.gray(`${label}:`.padEnd(13))} ${value}`);
 }
 function printChecks(items) {
   for (const item of items) {
-    console.log(`  ${pc7.green("\u2713")} ${item}`);
+    console.log(`  ${pc9.green("\u2713")} ${item}`);
   }
 }
 function printNextSteps(steps) {
   if (steps.length === 0) return;
   console.log(`
-${pc7.bold("Next steps")}`);
+${pc9.bold("Next steps")}`);
   for (const step of steps) {
-    console.log(`  ${pc7.cyan("\u2022")} ${step}`);
+    console.log(`  ${pc9.cyan("\u2022")} ${step}`);
   }
 }
 function printValidationErrors(messages) {
   logError("Tileflow config has errors.");
   for (const message of messages) {
-    const path = message.path ? pc7.cyan(message.path) : pc7.cyan("(root)");
-    console.log(`  ${pc7.red("\u2715")} ${path} ${pc7.gray("-")} ${message.message}`);
+    const path = message.path ? pc9.cyan(message.path) : pc9.cyan("(root)");
+    console.log(`  ${pc9.red("\u2715")} ${path} ${pc9.gray("-")} ${message.message}`);
   }
 }
 function printAccountDetails(session) {
-  printKeyValue("Account", pc7.bold(session.account.name));
+  printKeyValue("Account", pc9.bold(session.account.name));
   printKeyValue("Email", session.account.email);
   printKeyValue("API", link(session.apiOrigin));
   printKeyValue("Expires", formatDate(session.expiresAt));
@@ -11377,11 +11781,11 @@ function printDeployedMaps(maps) {
   const entries = Object.entries(maps);
   if (entries.length === 0) return;
   console.log(`
-${pc7.bold("Maps")}`);
+${pc9.bold("Maps")}`);
   for (const [name, map] of entries) {
     for (const [themeName, theme] of Object.entries(map.themes)) {
       const label = `${name}/${themeName}`;
-      console.log(`  ${pc7.green("\u2713")} ${label.padEnd(24)} ${link(theme.styleUrl)}`);
+      console.log(`  ${pc9.green("\u2713")} ${label.padEnd(24)} ${link(theme.styleUrl)}`);
     }
   }
 }
@@ -11399,13 +11803,13 @@ function plural(count, singular, pluralForm = `${singular}s`) {
   return `${count} ${count === 1 ? singular : pluralForm}`;
 }
 function command(value) {
-  return pc7.cyan(value);
+  return pc9.cyan(value);
 }
 function link(value) {
-  return pc7.cyan(value);
+  return pc9.cyan(value);
 }
 function pathLabel(value) {
-  return pc7.cyan(value);
+  return pc9.cyan(value);
 }
 function starterConfig() {
   return `import { defineMap, defineTheme, labels, poi } from "@tileflow/core";
@@ -11451,15 +11855,15 @@ function printHostedCompatibilityIssues(issues) {
 }
 function printMapStatus(status, apiUrl) {
   printTitle("Tileflow status");
-  printKeyValue("Map", pc7.bold(status.mapId));
+  printKeyValue("Map", pc9.bold(status.mapId));
   console.log(`
-${pc7.bold("Styles")}`);
+${pc9.bold("Styles")}`);
   if (status.styles.length === 0) {
     logMuted("  No styles deployed.");
   }
   for (const style of status.styles) {
     console.log(
-      `  ${pc7.green("\u2713")} ${style.environment.padEnd(16)} ${link(`${apiUrl}/maps/${style.mapId}/style.json`).padEnd(36)} ${formatBytes4(style.size).padStart(10)}  ${pc7.gray(formatDate(style.uploaded))}`
+      `  ${pc9.green("\u2713")} ${style.environment.padEnd(16)} ${link(`${apiUrl}/maps/${style.mapId}/style.json`).padEnd(36)} ${formatBytes4(style.size).padStart(10)}  ${pc9.gray(formatDate(style.uploaded))}`
     );
   }
 }

package/docs/hosted-authentication-and-deploy.md

@@ -30,8 +30,41 @@ account or hosted command stops with a clear message and asks you to run `tilefl
 Project API and CI keys are independent project credentials and are not removed by a personal
 password change.
 
-The dashboard creates the Map and browser-access policy before repository setup. Keep that exact
-Map ID in the deploy action. If the config contains several maps, select the authored map explicitly:
+## Create the Map from the terminal
+
+After `tileflow login`, the CLI can create the Map itself; nothing has to be copied from the
+dashboard. Run `deploy` without `--map-id`, or create the Map first with `maps create`:
+
+```sh
+npx tileflow login
+npx tileflow deploy --origin https://www.example.com
+npx tileflow maps create --any-website --json
+```
+
+The new Map belongs to a Team you administer. When you administer exactly one Team that can add a
+Map, the CLI uses it; when several can, it asks, or takes `--team @team`; when none can, it stops
+and says why (no administered Team, or every Team has reached its Map limit).
+
+Browser access is always an explicit choice: `--origin` with an exact website origin such as
+`https://www.example.com` (repeat it for up to 20 sites), or `--any-website`. Paths, wildcards and
+bare host names are rejected. On a terminal the CLI asks; without one (for example when an agent
+runs it), a missing choice stops before anything is created and names the flags. Browser access
+is stored with the Map in Tileflow and can be changed in the dashboard; it is never written to the
+repository.
+
+`deploy` creates the Map only after the local config, assets and styles pass, then publishes to it
+in the same run and prints `tileflow deploy --map-id <mapId>` for later deploys. If the manifest
+already records a Map for that repository map, `deploy` stops and shows that command instead of
+creating another Map. Each creation prints a setup key; rerunning an interrupted command with
+`--setup-key <key>` returns the same Map instead of a second one.
+
+Map creation uses only the personal session. With `TILEFLOW_API_KEY`, `--api-key`, `--with-native`,
+or in CI, `deploy` requires `--map-id`.
+
+## Deploy to an existing Map
+
+A Map created in the dashboard, or by an earlier CLI run, is deployed with its exact Map ID. If the
+config contains several maps, select the authored map explicitly:
 
 ```sh
 npx tileflow deploy \

package/docs/native-artifacts.md

@@ -82,8 +82,8 @@ Browser-only selections fail before config execution in native mode. In particul
 compiler-inspection sidecars, or the dev handler's status/event control routes. Use ordinary/default
 web preview for those workflows.
 
-The `native-lowering-v1` preparation policy records fixed globe-to-Mercator normalization and
-finite cap/dash layer partitioning in `native-build.json`; it does not change web artifacts.
+The `native-lowering-v1` preparation policy records fixed globe-to-Mercator normalization, removal
+of a browser sky and finite cap/dash layer partitioning in `native-build.json`; it does not change web artifacts.
 Native preparation rejects adaptive/unknown projections, terrain, browser PMTiles/contour protocols,
 missing text providers and unsupported style values rather than degrading them silently. It preserves
 shared icon inheritance and independent sprite densities, and maps verified licensed TTF/OTF faces

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.15",
+  "version": "0.1.0-alpha.16",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -36,14 +36,14 @@
   },
   "dependencies": {
     "@hono/node-server": "2.1.3",
-    "@tileflow/capture": ">=0.1.0-alpha.32 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.33 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.2 <0.1.0-beta.0",
     "@tileflow/coordinates-runtime": ">=0.1.0-alpha.5 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.37 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.34 <0.1.0-beta.0",
-    "@tileflow/maps": ">=0.1.0-alpha.11 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.39 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.36 <0.1.0-beta.0",
+    "@tileflow/maps": ">=0.1.0-alpha.13 <0.1.0-beta.0",
     "commander": "^15.0.0",
-    "hono": "4.13.7",
+    "hono": "4.13.13",
     "picocolors": "^1.1.1",
     "zod": "^4.4.3"
   },