tileflow 0.1.0-alpha.1 → 0.1.0-alpha.11

package/docs/local-visual-feedback.md

@@ -0,0 +1,268 @@
+# Local visual feedback
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+Explore with capture itself. The first run may install Playwright's exact pinned Chromium headless
+shell into its versioned per-user cache:
+
+```sh
+npx tileflow capture \
+  --map madrid \
+  --theme dark \
+  --center=-3.69201,40.40871 \
+  --zoom=16.15 \
+  --width=1200 \
+  --height=1200 \
+  --json
+```
+
+The successful entry includes a normalized `definition` with its concrete `theme`, `camera`,
+`viewport`, and default map `target`. Copy it under a chosen `scenes.<name>` key; the CLI never rewrites
+executable TypeScript config. Then commit the bounded scene so agents and CI render the same map,
+camera, and viewport:
+
+```ts
+import {defineMap} from '@tileflow/core';
+import {streets} from '@tileflow/maps';
+
+export default defineMap({
+  id: 'madrid',
+  name: 'Madrid',
+  version: 1,
+  extends: streets,
+  scenes: {
+    'madrid-desktop': {
+      theme: 'dark',
+      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+      viewport: {width: 1280, height: 800, dpr: 1},
+    },
+    'madrid-product': {
+      theme: 'dark',
+      camera: {type: 'center', center: [-3.7038, 40.4168], zoom: 12},
+      viewport: {width: 390, height: 844, dpr: 2},
+      target: {
+        kind: 'application',
+        path: '/maps/madrid',
+        captureId: 'product-map',
+      },
+    },
+  },
+});
+```
+
+`scenes` is tooling metadata owned by this map. It is not inherited and does not enter the
+cartographic compiler; tooling supplies the exported map ID when it normalizes a scene internally.
+Every scene stores a concrete theme; omission and browser-only `system` are invalid.
+
+### Live comparison workbench
+
+Use the ordinary preview server with a right-hand selection to compare two maps or themes while
+authoring:
+
+```sh
+# Two maps or themes from one config.
+npx tileflow preview \
+  --map harad --theme light \
+  --against-map ferraris --against-theme light
+
+# Or compare against another config.
+npx tileflow preview \
+  --config ./candidate.config.ts --map candidate \
+  --against-config ./reference.config.ts --against-map reference
+```
+
+Any `--against-*` option opens the comparison workbench. Both previews remain same-origin and share
+one synchronized camera. The toolbar switches between side-by-side, split, opacity overlay, and
+blink modes; the selected mode, camera, split, opacity, and active interaction side survive in the
+URL. Each config has its own watched, last-known-good session, so an invalid edit shows bounded
+diagnostics without discarding the last valid map and recovers automatically after a fix.
+
+Enable **Inspect** and click a rendered feature to see its bounded feature data, paint/layout values,
+zoom-curve samples, and compiler contribution sidecar. The sprite gallery shows the compiled atlas,
+not source directories. **Copy scene** produces a concrete-theme scene for the current camera and
+viewport; **Copy command** produces the corresponding capture command. The inspector sidecar exists
+only in memory in this local workbench and is not emitted by `tileflow build`.
+
+### Reproducible two-style review
+
+For shareable evidence with exact pixels, use headless capture instead of the live preview:
+
+```sh
+npx tileflow visual compare \
+  --config ./candidate.config.ts --map candidate --theme light \
+  --against-config ./reference.config.ts --against-map reference --against-theme light \
+  --center=-3.7038,40.4168 --zooms=12,14,16 \
+  --width=1200 --height=800 --dpr=1 --region=0,0,1200,760 \
+  --diff --open --json
+```
+
+`--against-config` is explicit and may name the same config. Both sides use one camera, viewport,
+DPR, ordered zoom matrix, pinned browser session, and concrete theme. At most 16 zooms and 64 MiB
+of aggregate embedded PNG data are accepted; an earlier preflight also caps the matrix at
+67,108,864 aggregate physical pixels. The default transaction writes
+`.tileflow/comparisons/compare.html`, a machine-readable sibling JSON document, and PNG/receipt-v4
+pairs below `compare.assets`; `--diff` adds a highlighted diff when identities are comparable. The
+HTML embeds every image, uses a restrictive CSP, performs no network request, and offers the same
+side-by-side, wipe, overlay, and blink review modes.
+
+`--region=x,y,width,height` selects one shared physical-pixel rectangle for compact appearance
+profiles. Review JSON uses the explicit signed direction `rightMinusLeft`; the region does not crop
+captures, changed-pixel metrics, or diffs.
+
+Stdout and the sibling JSON use the same schema-version-1 `visual.compare` document: concrete
+left/right selections, shared camera and viewport, zoom-sorted rows with Review v1 documents and
+relative artifact paths, report/document paths, and sorted warnings. This document and the watch
+NDJSON described below are versioned compatibility boundaries.
+
+The asset directory also contains a bounded schema-version-1
+`.tileflow-visual-compare.json` inventory. It assigns ownership only to the listed sibling assets
+and records each exact SHA-256. A later successful transaction removes stale generated rows or
+diffs only when that valid prior inventory names them, preserves unrelated files, and refuses a
+managed asset that has been modified, replaced by a symlink/non-file, or grown beyond its bound.
+`--force` does not weaken those ownership checks. The inventory is capped at 64 KiB and the complete
+report, JSON, inventory, PNGs, receipts, stale cleanup, and optional diffs commit or roll back as one
+file transaction.
+
+Different pixels are ordinary review evidence and exit 0. A frame, dimension, runtime, or exact
+data mismatch exits 1 and suppresses pixel metrics because the images are not comparable.
+`--allow-data-mismatch` keeps a data-mismatch report inspectable with exit 0, but does not invent
+pixel metrics. `--watch` observes both configs, cancels stale renders, preserves the last complete
+report through invalid edits, and emits deterministic NDJSON with `--json`. An explicit report path
+requires `--force` in watch mode; the managed default path is safely replaceable.
+
+Watch events are `watching`, `building`, `invalid`, `recovered`, `generation-complete`, `failed`,
+and `stopped`, with monotonic comparison generations and source-side generations where applicable.
+Without `--allow-data-mismatch`, an incompatible generation emits `failed`, does not replace the
+last complete report, and remains an unresolved failure; an allowed data mismatch emits
+`generation-complete` but still has no pixel metrics. An orderly stop exits 0 only after at least
+one complete generation and no unresolved invalid or failed state; otherwise it exits 1.
+
+Render one checkpoint, or recapture after every edit:
+
+```sh
+npx tileflow capture madrid-desktop --json
+npx tileflow capture --all --json
+npx tileflow capture madrid-desktop --watch --json
+```
+
+Use the first command when you want a single image and the last command while refining a map. Watch
+mode stays open, follows changes to the config, its local imports, and its effective icons and fonts,
+and writes a new PNG after each valid edit. Keeping the browser ready makes repeated renders faster.
+If an edit is invalid, the last good image remains in place and capture resumes automatically after
+the fix. Stop watch mode with `Ctrl+C`. It accepts named committed scenes or `--all`, not exploratory
+camera options.
+
+Standalone scenes need no app server, account, API key, MCP service, system Chrome, or visible
+window. The first command—or the first capture—may provision Playwright's pinned Chromium headless
+shell in its versioned per-user cache. `--no-browser-install` makes a prepared/offline environment
+strict. Tileflow never falls back to a system browser or packages the browser in npm.
+
+For prepared or offline CI, install ahead of time with
+`npx tileflow setup capture --json`. Use `setup capture --no-browser-install` or
+`capture --no-browser-install` as an enforcement check that the exact shell is already cached.
+
+For an application scene, its route and component props must render the committed camera. Tileflow
+uses the camera in scene identity but does not mutate arbitrary application map state.
+
+One-shot success JSON is one deterministic schema-version-1 document plus one newline. It contains
+sorted scene/map/theme/target entries, relative output and receipt paths, image hash/dimensions/DPR,
+renderer identity, remote-dependency state, and warnings; it contains no image bytes, credential,
+origin, absolute path, user, or timestamp. Managed output is an atomic pair under
+`.tileflow/captures/<scene>.png` and `<scene>.receipt.json`. `tileflow init` ignores managed captures
+and `.tileflow/diffs` when creating a new `.gitignore`. Explicit output replacement requires
+`--force`; symlinks and path escapes fail closed.
+
+Each written receipt uses capture schema v4 and records the concrete theme. A Tileflow World
+capture resolves its TileJSON once for
+the whole capture session and records the exact `world-v1` release plus descriptor, archive, data
+contract, and product-contract hashes. All selected scenes and retries therefore use one immutable
+World release even if `current` moves while the command is running.
+
+One-shot `--json` failures leave stdout empty and write exactly one deterministic failure document
+to stderr with `code`, `phase`, bounded diagnostics, and optional origin-only resource metadata.
+
+Watch JSON is NDJSON with monotonic `building`, `invalid`, `recovered`, `captured`, `failed`, and
+`stopped` generation events. It watches config, transitive local imports, and effective icon/font
+files, preserves the last good capture through invalid edits, cancels stale work, and reuses one
+headless Browser. An orderly stop exits 0 only after a successful capture with no unresolved
+terminal failure.
+
+### Capture through the real application
+
+Application scenes use the app's existing Vite, Next.js, Webpack, or custom loopback server. Start
+only that normal server; Tileflow does not run a package script, scan ports, or start
+`tileflow preview`:
+
+```sh
+npm run dev
+TILEFLOW_APP_ORIGIN=http://127.0.0.1:3000 \
+  npx tileflow capture madrid-product --json
+```
+
+The React, Vue, and Svelte wrappers expose `data-tileflow-map`, the resolved concrete
+`data-tileflow-theme`, optional `data-tileflow-capture-id`, and
+`data-tileflow-state="loading|idle|error"`. The headless client selects exactly one target, verifies
+the theme, and waits for idle. Use `--url` for one explicit full loopback URL, `--selector` to
+override target selection, and `--frame map|viewport` to override framing. Origins and URLs must be
+credential-free loopback HTTP(S) without fragments. Each navigation uses a fresh context without a
+reused profile, cookies, local storage, or service workers.
+
+### Match a reference and protect the result
+
+While refining a style, compare the current scene with any reference screenshot:
+
+```sh
+npx tileflow visual analyze madrid-desktop \
+  --reference ./design-reference.png --region=0,0,1200,760 --json
+```
+
+`visual analyze` renders exactly one committed scene and writes the current image and a JSON report
+under `.tileflow/analysis` by default. The report includes both images' dimensions and dominant
+colors. When their physical dimensions match, it also includes exact and perceptual pixel metrics,
+mean channel difference, a high-contrast `.diff.png`, and signed
+`appearance.actualMinusReference` luminance, OKLab, edge-density, and local-contrast evidence. The
+optional region affects only those appearance metrics. The reference PNG is never modified or
+treated as a baseline.
+
+Once the map is approved, save it as the expected baseline and use that image to catch later
+regressions:
+
+```sh
+# Save the reviewed current render as the expected baseline.
+npx tileflow visual update madrid-desktop \
+  --baseline-dir test/visual-baselines --json
+
+# Compare a fresh render without changing the baseline.
+npx tileflow visual diff madrid-desktop \
+  --baseline-dir test/visual-baselines --json
+
+# Or apply the operation to every committed scene.
+npx tileflow visual diff --all \
+  --baseline-dir test/visual-baselines --json
+
+# In CI, return exit 2 when the pixels have changed.
+npx tileflow visual diff madrid-desktop \
+  --baseline-dir test/visual-baselines --fail-on changed --json
+```
+
+`visual diff` and `visual update` require either one or more positional scene names or `--all`;
+those forms are mutually exclusive. `visual analyze` always accepts exactly one scene.
+
+The baseline directory holds the reviewed expected PNG and its receipt. The files generated by a
+comparison are working evidence: the current `.actual.png`, a transparent high-contrast
+`.diff.png` when comparable, and a `.visual.json` report under `.tileflow/diffs` by default.
+`visual diff` may replace those working files on each run, but it never changes the baseline. This
+separation prevents a check from silently accepting the change it was meant to reveal.
+
+Before comparing, `visual diff` validates the baseline PNG and receipt, including their hashes,
+dimensions, runtime, and scene identity, without executing or fetching baseline metadata.
+Statuses are `unchanged`, `changed`, `missing-baseline`, `scene-mismatch`, and `runtime-mismatch`.
+Same-size images report exact RGBA changed pixels and an informational fixed-threshold perceptual
+metric; exact inequality determines changed.
+
+Changed pixels exit 0 by default so a person or agent can inspect the working files.
+`--fail-on changed` exits 2 for CI; missing or incompatible baselines and operational failures exit 1.
+
+Run `visual update` again only after reviewing and accepting the new render. It is the only
+command that creates or changes baseline pairs, and it never stages, commits, or pushes. Remote
+tiles, glyphs, and sprites are reported because their pixels can change independently of the style.

package/docs/native-artifacts.md

@@ -0,0 +1,174 @@
+# Native artifacts, local preview and Hosted deployment
+
+Use a project-local CLI version that includes the native artifact selector and a trusted
+`tileflow.config.ts`. Follow the [installation instructions](../README.md) first. Native commands
+prepare, serve or publish Tileflow artifacts; they do not install, start or qualify a mobile renderer.
+
+## Validate and build
+
+```sh
+npx tileflow validate --renderer native --target local --json
+npx tileflow build --renderer native --target local --out public/tileflow --json
+```
+
+`validate` prepares and checks the complete theme family without writing production output.
+`build` writes the checked generation beneath `public/tileflow/native`, including a strict version-1
+runtime manifest and a separate schema-v2 `native-build.json` record. Serve the complete renderer
+directory, not just the style. A failed compatibility check leaves existing output unchanged.
+
+Both commands accept `--renderer web|native`; omission means `web`. Renderer selection is separate
+from `--target local|hosted`. Existing `validate --target hosted` continues to perform web Hosted
+preflight. Native with `--target hosted` fails with `NATIVE_RENDERER_UNSUPPORTED` before loading the
+config or writing files. `build --target hosted` is not publication and is rejected. The explicit
+combined Hosted publication command below performs its own complete two-renderer preflight.
+
+JSON success uses the existing version-1 command envelope. Native results additionally identify
+`renderer: 'native'`, `profile: 'native-v1'` and `validation: 'static-artifacts'`. JSON failure writes
+one structured envelope to stderr, leaves stdout empty and exits nonzero. Native diagnostics have
+safe JSON Pointers, stable codes, severity and suggestions. Unknown renderer names are not echoed.
+The ordinary web commands and their default artifact bytes retain their existing behavior.
+
+## Watch and serve native artifacts
+
+`preview` selects the renderer with `--renderer`:
+
+```sh
+npx tileflow preview --renderer native --map stores --theme light
+```
+
+Native mode creates the existing watched artifact session with renderer `native`. It keeps the
+last-known-good native artifact family when a watched generation becomes invalid and replaces it
+only after a later valid generation is prepared. The endpoint is an **assets-only** development
+endpoint: it does not render a browser map, open the visual workbench, start Metro, launch a device,
+or establish visual/native acceptance.
+
+With the default host and port, the canonical runtime manifest is:
+
+```text
+http://127.0.0.1:3333/native/manifest.json
+```
+
+The manifest remains the ordinary strict version-1 Tileflow runtime manifest. Its style, sprite,
+font, tileset and generation references use the existing renderer-specific `/native/...` paths; no
+preview-only manifest schema is introduced. `--map` and `--theme` validate a desired map/theme
+against that finalized manifest but do not narrow or fork the served artifact family.
+
+Locally built sprites and fonts are served from the preview's own HTTP origin. Native preview checks
+each generation with that exact origin as its development origin, the same exception the application
+configures below. Resources on any other origin still require HTTPS. `validate` and `build` never
+apply this exception.
+
+Human output identifies the exact manifest URL, profile `native-v1`, and `assets-only` endpoint.
+Native NDJSON lifecycle events additionally carry `renderer`, `profile`, `manifest` and
+`assetsOnly`; the default and explicit `--renderer web` lifecycle/output contract remains the
+existing browser-preview contract.
+
+Metro remains the React Native application's JavaScript development server. The application points
+its Tileflow source at the native manifest URL and sets `source.developmentOrigin` to its exact HTTP
+origin, for example `http://127.0.0.1:3333`. Both addresses must be reachable from the target device;
+an Android emulator may use a different host address. Other resource origins still require HTTPS.
+The application supplies its own development networking setup. Tileflow
+does not add a Metro plugin, device discovery or a tunnel.
+
+`preview` still binds to `127.0.0.1` by default. Existing explicit `--host <ip-or-localhost>` behavior
+is preserved. Selecting another host does not add LAN discovery, a public tunnel, an iOS ATS
+exception, an Android cleartext exception, or any native application mutation; the application and
+developer remain responsible for making an explicitly selected development endpoint reachable
+under their own platform/network policy.
+
+Browser-only selections fail before config execution in native mode. In particular, committed
+`--scene` preview and every `--against-*` comparison-workbench option are unavailable with
+`--renderer native`. Native mode does not serve the browser preview root, preview JavaScript runtime,
+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.
+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
+into native style declarations. See the
+[profile contract](https://github.com/tileflow/tileflow-sdk/blob/main/packages/core/docs/native-artifact-profile.md)
+and [artifact layout](https://github.com/tileflow/tileflow-sdk/blob/main/packages/dev/docs/native-artifacts.md).
+
+## Publish web and Native together
+
+The pre-release source supports an explicit combined deployment against a compatible Hosted API.
+This is a wire and implementation contract, not a statement that a package or server release is
+available. The API must understand renderer-collection deployment schema 2.
+
+```sh
+npx tileflow deploy --with-native --map-id map_0123456789abcdef --map stores
+```
+
+`--map-id` selects the existing managed Tileflow Map. `--map` selects one map from the repository;
+it can be omitted only when the config contains one map. The command uses the ordinary deployment
+credential or account capability, not the publishable mobile credential. Do not put privileged
+credentials in mobile application configuration.
+
+Before authentication, upload or publication, the command loads the trusted config once, prepares
+its icon closure, compiles all web themes and lowers all Native themes from that same compiled
+input. It validates profile `native-v1`, hashes, authored identity, source ownership declarations,
+semantic POI provenance and overlay boundaries. Native incompatibility rejects the entire request;
+it cannot publish a new web family alone. Existing Hosted restrictions still apply, including the
+current rejection of package-owned web font bundles. This opt-in does not bypass those restrictions;
+use an explicitly configured glyph provider for this Hosted path.
+
+Shared icon packages use the existing content-addressed upload protocol once. The command replaces
+only the confirmed owned sprite URL, without reevaluating config, and sends one strict renderer
+collection to `POST /v1/styles`. The server verifies both complete families and their owned resources,
+stages immutable outputs, and activates them through the existing single deployment authority.
+A Native staging failure does not activate the replacement web family. Retry the same input after an
+interrupted response: the server's existing content identity determines reuse or a new deployment.
+
+The successful response has its own explicit schema version 2 and identifies one managed Map and
+deployment plus web and Native theme references. The CLI requires the complete matching response
+before atomically replacing `--manifest`. That local file stays a strict **runtime manifest v1 for
+web**, so existing bundlers do not receive unknown Native fields. The CLI separately prints the
+canonical Native manifest URL. A failed request or invalid response leaves the existing local file
+unchanged; an uncertain response is not proof that the server performed no publication.
+
+Ordinary `deploy` without `--with-native` keeps its schema-1 request and response behavior. A later
+web-only deployment does not inherit a Native family from an older deployment.
+
+## Native discovery and protected resources
+
+The canonical entry URL is on the application's configured API origin:
+
+```text
+https://api.example.test/maps/map_0123456789abcdef/native/manifest.json
+```
+
+This bounded, one-map runtime manifest is **public metadata**. It contains identity, theme names,
+revisions and references, never Style JSON, credentials or grants. It is served with `no-store` only
+for a coherent active Native deployment. Its GET is not a commercial completion event.
+
+Use that URL in the existing `Map` source descriptor, keeping the authored map name in `source.map`.
+The application configures its publishable mobile credential and approved API origin once, using the
+[React Native application configuration contract](../../react-native/docs/native-configuration.md).
+The SDK requires both the requested and final response URLs to be the exact canonical route for the
+declared managed Map. The manifest's `apiUrl` must exactly equal the configured canonical API origin;
+a remote document cannot create a trusted origin or choose where the credential is sent.
+
+The credential goes only to the configured API's `POST /v1/sessions/start`. It is not sent to the
+manifest, a CDN, a style URL or a redirect destination. Styles, TileJSON, tiles, sprites, glyphs and
+font resources remain protected by the existing grant and resource-ownership checks.
+
+A Native theme references `/maps/<mapId>/native/v<deploymentVersion>/<theme>.json` and requires a
+revision. The server verifies that version against the active deployment and the style's stored
+bytes against the revision. Before resource projection, the SDK checks the protected response URL
+and its Map/theme/deployment/revision metadata. If discovery became stale, it refetches the public
+manifest at most once for that selection, preserving its existing session and admission context.
+Another Map, origin, mode or older deployment cannot replace that ownership. A repeated failure
+enters the existing safe error/rollback path rather than mixing generations or looping indefinitely.
+
+Session start, public metadata discovery and Map rendering do not themselves assert a billable
+completion. Completion remains owned by the server's existing eligible protected GET 200/206 path.
+Disabled mobile delivery fails closed; publication does not enable it.
+
+## Qualification boundary
+
+Native local preview is artifact preparation and delivery only. A successful artifact or deployment
+response does not establish Hermes execution, iOS/Android rendering, device reachability, visual
+fidelity, package publication or product availability. Qualify the exact compatible SDK/API pair,
+React Native application, platform networking policy and native runtime separately.

package/docs/read-only-icon-comparison.md

@@ -0,0 +1,81 @@
+# Read-only icon comparison
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+Compare the exported map with its active hosted revision before deciding whether to deploy.
+These examples assume the configured map ID is `madrid`; replace the sample managed Map ID with
+your Dashboard destination and use personal CLI login or a credential with `status:read`.
+`--against` selects the exact map ID in the configuration, not a deployment-stage keyword:
+
+```sh
+npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against madrid
+npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against madrid --json
+npx tileflow icons diff --map-id map_AbCdEfGhIjKlMnOp --against madrid --report ./icon-diff.html
+```
+
+The command compiles only the exported map, performs authenticated read-only control-plane
+requests, and never uploads a package, creates a deployment, or writes the frontend manifest.
+Plain and JSON modes write no report; preparing locked inputs may download and write cache entries. A requested HTML report adds reads of the baseline's four
+public sprite files and
+embeds verified old/new images in one self-contained file. The report groups exact-cell icon
+previews under `Added`, `Modified`, and `Removed`. Added and removed cards show only the affected
+icon; modified cards compare `Before` with `Next`. A script-free 1x/2x selector defaults to 2x,
+switches the embedded density, and renders 1x at half the 2x preview size inside a stable frame so
+the selected state is immediately visible. Package hashes, generated sizes, and icon counts stay in
+collapsed `Details`. A map badge is shown only for a map-scoped report. It exposes no atlas
+implementation UI and contains no API key, remote runtime dependency, original icon source, or
+local source path. Use `--force` to replace different existing report bytes and `--open` only
+together with `--report`.
+
+An icon is `modified` when its rendered record changes: normalized 1x/2x pixel hashes, dimensions,
+SDF defaults or stretch/content layout. Fully transparent RGB is ignored in pixel hashes. Metadata
+edits can therefore mark an icon modified even when its pixel hashes are unchanged. Reports render
+SDF with asset defaults; raw downloadable PNGs still encode distance fields.
+
+`hasChanges` compares effective package content hashes. The manifest also hashes the four encoded
+artifacts, so a package can change while its per-icon list remains unchanged. Conversely, a fully
+shadowed dependency can change the map's composition receipt without changing its effective sprite.
+A clean icon diff is not evidence that the whole map needs no deployment. The report and digest analysis operate on
+generated sprite data; SVG, raster source files, and absolute paths stay on the local machine.
+
+`--json` writes exactly one deterministic schema-version-1 document plus a trailing newline. Its
+stable top-level fields, in order, are:
+
+```json
+{
+  "schemaVersion": 1,
+  "environment": "madrid",
+  "baseline": {"deploymentId": "dep_...", "package": null, "version": 7},
+  "proposed": {"package": null},
+  "icons": {"added": [], "removed": [], "modified": [], "unchangedCount": 0},
+  "generatedBytes": {"before": 0, "after": 0, "delta": 0},
+  "artifacts": {"report": null},
+  "hasChanges": false
+}
+```
+
+Package summaries, when present, contain `contentHash`, `iconCount`, `label`, and `totalBytes`.
+A missing hosted baseline is an initial comparison against an empty package. The command compares
+delivered icon records, canonical package manifests, and generated bytes; config-directory
+provenance and style-reference analysis belong to `icons list` and final style validation.
+
+Normal differences exit 0. Config, compilation, credential, network, response, and report errors
+exit 1 with diagnostics on stderr, even with `--json`. Invalid or unauthorized baselines are errors,
+not empty packages. `--config` selects a config file; `--api-url` and `--api-key` override hosted
+connection settings. `--cache-dir` selects the artifact cache and `--offline` disables only icon
+hydration: the authenticated hosted baseline request still occurs.
+
+This workflow does not provide OIDC, automatic secret installation, an official
+GitHub Action, an atomic multi-map deploy set, or a Tileflow-hosted remote
+builder.
+
+Docs: https://tileflow.dev/docs/development-and-deployment/icon-inspection-and-diffs
+
+### Team credentials and explicit Map targets
+
+A unified Team credential can combine data and Map operations. Use `TILEFLOW_API_KEY` and an
+explicit `--map-id` for deployment, status and hosted icon comparisons. The CLI sends that target
+with style, icon and font requests and verifies the credential covers it. The Hosted API must
+support unified credentials. All Maps includes future Maps; selected Maps is an explicit list.
+A legacy Map key keeps its original binding. Personal CLI login remains separate from machine
+credentials. Credential administration and Team management use the Hosted API or dashboard.

package/docs/team-icon-sets.md

@@ -0,0 +1,130 @@
+# Team Icon Sets and repository locks
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+A Team Icon Set is a named catalog resource such as `@acme/brand`. Publishing creates an immutable
+integer revision of the four generated sprite files. Maps in different repositories consume
+independently pinned revisions through `iconSet('@acme/brand')` without copying original artwork.
+
+Two command families cover this, and the split is deliberate. `icon-set` is a networked Team
+authority that changes the catalog. `icons list` stays local and needs no credential. `icons diff`
+compares prepared output with an active Hosted Map baseline, so it requires `--map-id`, the
+configured map ID in `--against`, and `status:read` authority through personal login or a scoped
+credential, but never mutates that Map. `install`, `update` and `pin` maintain the exact
+`tileflow.icons.lock.json` beside the selected config.
+
+Availability depends on your deployment and your Team's enabled features. Check
+`npx tileflow icon-set --help` for the installed command surface.
+
+## Authorize a Team
+
+Catalog commands need Team authority. Either sign in and let the CLI exchange your account session
+for a short-lived Team capability, or pass a Team data key:
+
+```sh
+npx tileflow login
+npx tileflow icon-set list --team @acme --json
+```
+
+Reads request `icons:read`; publication, archive state and purge request `icons:write`. A
+Map-scoped deploy key never gains catalog authority, and `--team` is rejected together with
+`--api-key` because a Team data key already selects its Team.
+
+## Publish a revision
+
+```sh
+npx tileflow icon-set publish ./icons --id brand --team @acme --idempotency-key brand-2026-09-14 --json
+```
+
+`publish` compiles exactly one repository-relative directory into `sprite.json`, `sprite.png`,
+`sprite@2x.json` and `sprite@2x.png`, then uploads those four files under one durable retry key.
+The first successful publication creates the set. Republishing identical bytes reports
+`"publication": "unchanged"` and returns the same revision rather than a new integer. Repeating an
+uncertain request with the same `--idempotency-key` returns its original result instead of creating
+extra history.
+
+`--name` and `--description` set bounded catalog display metadata after the immutable revision is
+confirmed. If that metadata update fails, the revision remains published; rerun the same command to
+retry the display update.
+
+The JSON receipt reports the Team, the canonical reference, the immutable revision and version ID,
+the package identity, the content hash, the byte count and whether the publication changed
+anything. It contains no credential, source path, or original artwork.
+
+## Inspect and manage the catalog
+
+```sh
+npx tileflow icon-set list --team @acme --json
+npx tileflow icon-set status brand --team @acme --json
+npx tileflow icon-set versions brand --team @acme --json
+npx tileflow icon-set uses brand --team @acme --json
+npx tileflow icon-set archive brand --team @acme --json
+npx tileflow icon-set unarchive brand --team @acme --json
+```
+
+Reads follow bounded cursors and reject a repeated page, a duplicate row or an unsafe page count.
+`uses` reports the known hosted deployments that retain a revision; its
+`includesUndeployedRepositoryLocks` field is always `false`, because a repository lock that was
+never deployed is not discoverable by the catalog. Archiving prevents new publication and implicit
+discovery while retained consumers keep working.
+
+## Purge an exact revision
+
+```sh
+npx tileflow icon-set purge brand --version 3 --team @acme \
+  --idempotency-key purge-brand-3 --confirm '@acme/brand@3' --acknowledge-unknown-locks --json
+```
+
+Purge needs all four guards: an exact positive `--version`, a durable `--idempotency-key`, a
+`--confirm` value repeating the exact `@team/set@version`, and `--acknowledge-unknown-locks`.
+The acknowledgement is not a formality. Purge tombstones the publication hold and keeps retained
+deployment holds, including fully shadowed dependencies; it cannot discover undeployed repository
+locks and cannot revoke public bytes that were already downloaded.
+
+## Maintain the repository lock
+
+```sh
+npx tileflow icons install --team @acme --json
+npx tileflow icons update @acme/brand --team @acme --json
+npx tileflow icons pin @acme/brand --version 3 --team @acme --json
+```
+
+These commands read the `iconSet()` references your config declares. `install` resolves the current
+latest revision for declared references that have no pin yet and leaves existing pins alone.
+Both `install [references...]` and `update [references...]` accept an optional subset; omitted
+selection means every declared reference.
+`update` moves the selected references to their current latest revision; omit the references to
+select every declared one. `pin` selects one exact revision and never resolves a head.
+
+They are the only build-adjacent commands that resolve `latest` or write the lock. Every requested
+reference is resolved before a single compare-and-swap write of the whole snapshot, so a partial
+lock is never produced and a concurrent writer fails the command rather than losing its pins. An
+undeclared reference is rejected before any request. No lock command rewrites `tileflow.config.ts`;
+add `iconSet('@team/set')` to your config first. Lock commands do not hydrate sprite files.
+Serialization retains pins for other declared references and removes stale undeclared references.
+They accept `--config` (or `-c`), `--team`, `--api-url`, `--api-key` and `--json`.
+Do not combine `--team` with an explicit or ambient `TILEFLOW_API_KEY`.
+
+The JSON receipt lists each locked reference with its revision, version ID, package identity and
+content hash, plus any declared reference that is still missing a pin.
+
+## Build, preview and deploy against the lock
+
+`validate`, `build`, `preview`, `deploy`, `icons list` and `icons diff` read the lock and compose
+one effective sprite. They never resolve a catalog head, so publishing a newer revision changes
+nothing in a repository until an explicit lock command runs. `--cache-dir` chooses the verified
+artifact cache root on commands that expose it (including `icons list` and `icons diff`);
+`--offline` fails a cache miss instead of hydrating it. These flags are not universal CLI options.
+Other entry points use their documented icon-resolution options or `TILEFLOW_ICON_CACHE_DIR`.
+Offline diff still needs its hosted baseline request.
+
+Hydration downloads only the four public files of the exact pinned artifact, from the trusted
+delivery origin, without credentials and without following redirects. Every file's length,
+checksum, sprite index, PNG geometry and per-icon pixel hashes are verified before use.
+
+Deploy uploads the effective composed package and sends the same ordered composition receipt in the
+build manifest and the request body, bound to that package's content hash. A referenced source
+revision is never re-uploaded by a deploy.
+
+Offline composition is not an offline map. Remote tiles, glyphs and other external resources keep
+their own requirements.