tileflow 0.1.0-alpha.5 → 0.1.0-alpha.6

package/docs/agent-icon-composition.md

@@ -0,0 +1,49 @@
+# Agent icon composition
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+List the effective local catalog used by the exported map:
+
+```sh
+npx tileflow icons list --json
+```
+
+The successful stdout contract is one deterministic JSON document followed by exactly one newline.
+Its top-level fields, in order, are `schemaVersion: 2`, `pathBase: "cwd"`, and `maps`.
+Schema version 2 is a compatibility boundary: removing or renaming a field or changing an enum's
+meaning requires a new schema version. Additive optional fields require corresponding documentation
+and tests.
+
+Each sorted map entry has one `id` and an `icons` value. `icons.kind` is `none` for `icons: []`, or
+`directories` for a prepared ordered composition. A directory entry contains:
+
+- `directories`, in the exact left-to-right authoring order, using config-relative paths or safe
+  `npm:<package>/<path>` descriptors;
+- `finalIds`, the sorted canonical lower-kebab IDs in the resulting sprite;
+- `replacements`, with the replaced path and winning path for every later exact-ID replacement;
+- `sources`, with the winning ID, cwd-relative path, format, byte length, and intrinsic dimensions;
+- `insideWorkingTree`; and
+- the deterministic generated `packageHash`.
+
+There is deliberately no parallel catalog registry, provider kind, semantic mapping, external
+sprite branch, or arbitrary source-to-runtime renaming. `<id>.<ext>` publishes `<id>` and the
+reserved pattern form `<id>.pattern.<ext>` also publishes `<id>`. This lets an
+agent answer “which directory wins this icon?” directly from one map record without reconstructing
+hidden provider state. Use `--map <id>` to select one exact map when internal orchestration supplies
+more than one.
+
+All reported paths are relative to the invocation working directory. A source outside that tree
+uses `../` and `insideWorkingTree: false`; no absolute path is emitted. Listing follows local
+authoring semantics. Run `npx tileflow validate --target hosted` separately before a
+hosted deploy to check containment, portable IDs, SVG safety, and hosted limits.
+
+The Tileflow command performs no authentication, network request, browser/server launch, or file
+write. It removes an ambient `TILEFLOW_API_KEY` before importing config. As with every config-aware
+command, loading `tileflow.config.ts` executes repository code and is not a sandbox; side effects in
+that code remain the repository's responsibility. Success emits no ANSI or progress prose. Usage,
+config, source, decode, and render failures exit 1, write diagnostics to stderr, and leave stdout
+empty.
+
+The output contains no source contents or source hash, rendered cells, atlas coordinates,
+image/base64 payload, credential, timestamp, random value, or absolute path. Open a reported local
+source path with normal repository tools only when the pixels themselves are needed.

package/docs/build-artifacts.md

@@ -0,0 +1,33 @@
+# Build artifacts
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+`tileflow build` resolves the exported map lineage, validates executable config and MapLibre
+semantics, compiles its ordered package/local icon directories and selected text provider, and
+writes `manifest.json`, one `styles/<map>/<theme>.json` per concrete appearance, and every referenced
+sprite/font asset. The manifest records `defaultTheme`, optional `systemThemes`, and the exact theme
+catalog; it never flattens a default into a second style alias. A
+map with text has exactly one provider: local/package `fonts` directories or a `glyphs` descriptor
+whose `fontStacks` are explicit. The default output is `dist/tileflow`; choose another directory
+explicitly with `--out`:
+
+```sh
+npx tileflow build --out public/tileflow
+```
+
+Named hosted sources with `local` archives are for account-free validation, development, preview,
+and capture. `tileflow build` rejects them instead of copying, publishing, or taking ownership of
+user data. For production, either publish managed data explicitly with `tileset publish` or serve
+it from infrastructure owned by the application. A local declaration never selects either path
+implicitly.
+
+Preview, capture, and the React/Vue/Svelte adapters register Tileflow's local PMTiles protocol
+before MapLibre reads the compiled Style. Its URL is stable by logical tileset ID; physical local
+snapshot generations do not change Style identity. Standalone Capture retains one snapshot for the
+render. Application Capture uses the application's server; Tileflow's local handler provides
+immutable, ETag-guarded PMTiles reads, but does not freeze every local dataset for the complete
+screenshot window.
+
+Build is local and credential-free. Hosted compatibility is a separate
+`tileflow validate --target hosted` preflight. Primary map data must remain Tileflow World; named
+Team sources are validated and resolved independently.

package/docs/cli-setup-and-defaults.md

@@ -0,0 +1,56 @@
+# CLI setup and defaults
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+CLI-only tools for Tileflow config, preview, validation, capture, and hosted deploy. The package
+requires Node.js 22 or newer and intentionally exposes only the `tileflow` binary; importing
+`tileflow` as a JavaScript library is not a supported surface.
+
+Local config, validation, build, preview, and hosted-compatibility checks require
+no Tileflow account or API key:
+
+```sh
+npm install @tileflow/core@alpha @tileflow/maps@alpha
+npm install --save-dev --save-exact tileflow@alpha
+npx tileflow init
+npx tileflow validate
+npx tileflow validate --target hosted
+npx tileflow build
+npx tileflow preview
+```
+
+The generated config imports `streets`, extends it, materializes a custom dark theme from
+`streetsThemes.dark`, and declares the starter's theme family, modules, and view. Streets already
+owns its complete icon and glyph providers, so the leaf does not repeat font stacks or know a
+delivery URL.
+
+Install the exact project dependency first; then `npx tileflow` runs its local executable. Other
+package managers work; use the equivalent command for the lockfile already owned by the project.
+
+`tileflow preview` previews the map exported by `tileflow.config.ts` and uses its configured `view`.
+Select one of that map's committed standalone scenes explicitly:
+
+```sh
+npx tileflow preview --scene madrid-mobile
+```
+
+To work on another map, point `--config` at another singular config. Multi-map catalogs are internal
+orchestration used by this repository's workbench and are not a second public config shape.
+
+`tileflow dev` remains a compatibility alias. The `preview` name distinguishes this SDK preview
+server from an application's own `npm run dev` process.
+
+`--api-base-url` selects the origin used by official World, Bathymetry vector, Bathymetry DEM,
+Nautical, and terrain TileJSON sources in the generated preview style. In particular, a hybrid
+Bathymetry map resolves `/tiles/bathymetry/tiles.json` and `/tiles/bathymetry/dem/tiles.json` from
+that one origin. `TILEFLOW_API_URL` supplies the same value when the flag is omitted, which lets a
+local tiles stack serve all sidecars without changing map authoring.
+
+The preview binds only `127.0.0.1` by default. Network exposure is never implicit. To bind another
+interface, pass one explicit IP literal (or `localhost`) with `--host`, for example
+`tileflow preview --host 192.0.2.10`. URL-, path-, and hostname-shaped values are rejected.
+
+A map preview accepts `--theme <concrete-name>`; omission selects its declared default. A scene
+preview applies its committed concrete theme, camera, and CSS viewport dimensions. Capture remains the
+authority for exact DPR and pixels. Scenes whose target is an application must be viewed through
+that application's normal development server.

package/docs/command-families.md

@@ -0,0 +1,18 @@
+# Command families
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+| Family            | Commands                                                                                       |
+| ----------------- | ---------------------------------------------------------------------------------------------- |
+| Semantic language | `language manifest`, `language schema`                                                         |
+| Map authoring     | `init`, `validate`, `inspect`, `explain`, `semantic-diff`, `build`, `preview` (`dev` alias)    |
+| Local evidence    | `setup capture`, `capture`, `visual compare`, `visual analyze`, `visual diff`, `visual update` |
+| Data and assets   | `tileset inspect`, `tileset publish/list/status/purge`, `inspect features`, `icons list/diff`  |
+| Account           | `login`, `logout`, `whoami`                                                                    |
+| Hosted delivery   | `deploy`, `status`                                                                             |
+
+Run `tileflow <command> --help` (or the family help, such as `tileflow icons --help`) for the exact
+arguments and bounded JSON modes.
+
+The CLI retains the hidden `projects` command family as a compatibility and support surface for the
+internal application boundary. It is not part of the ordinary workflow or the product catalog.

package/docs/coordinates.md

@@ -0,0 +1,68 @@
+# Coordinates
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+These local commands require an explicitly provided compatible runtime distribution. No public
+native runtime download is currently offered; package installation or the default setup URL does
+not supply one. The verified production profile is Linux x64 on Debian 12, glibc 2.36 and Node 24.
+The examples below use development artifacts and do not establish public platform support.
+
+Coordinates commands use a locally provisioned execution release. They do not use Map
+configuration, account state, or a Hosted fallback. Provision first from a distribution source, then
+run the local commands against the active cache entry or an explicit runtime directory.
+
+```sh
+tileflow setup coordinates --source /path/to/distribution.json --cache-dir /path/to/coordinates-cache --development --json
+tileflow coordinates search --query ETRS89 --runtime-dir /path/to/installed-release --development --json
+tileflow coordinates describe --id EPSG:25830 --runtime-dir /path/to/installed-release --development --json
+tileflow coordinates operations --from EPSG:4258 --to EPSG:25832 --runtime-dir /path/to/installed-release --development --json
+tileflow coordinates transform --from EPSG:4258 --to EPSG:25832 --positions '[[12,55]]' --runtime-dir /path/to/installed-release --development --json
+```
+
+`setup coordinates --source` accepts a distribution URL, a local `distribution.json`, or a directory
+that contains one. `--archive` is a local archive alias and rejects URLs. Setup verifies every asset
+declared by the selected distribution before it records the active release. `--development` is
+required for a development distribution.
+
+Every execution command accepts `--runtime-dir`, `--release`, and `--development`. With no
+`--runtime-dir`, it opens the cache entry selected by setup. `search` accepts `--query`, `describe`
+accepts `--id`, `operations` accepts `--from` and `--to`, and `transform` also accepts JSON
+`--positions`.
+
+For a complete request, use exactly one of `--request '<json>'` or `--input <file|->`. These forms
+cannot be combined with the command's convenience request flags. Input is limited to 32 KiB, must be
+valid UTF-8 JSON, and `-` reads standard input. Success writes one JSON document to stdout. A
+structured failure writes one JSON document to stderr and exits with status 1. Plain `--help` remains
+human-readable; `--help --json` is a structured failure.
+
+`tileflow explain` compiles exactly one map/theme selection through `createStyleResult()` and emits
+its structured `report` and safe compiler `diagnostics`; it deliberately omits the usually large
+MapLibre `style`. In a singular config, `--map` is optional; a multi-map workbench requires it.
+`--theme` defaults to that map's declared default. `--inspection` adds opt-in, read-only
+physical-output provenance to the report. Its physical layer IDs and indexes are diagnostic
+observations only: they are not stable application or authoring targets, and no semantic operation
+accepts them. The JSON document has this stable projection:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "explain",
+  "ok": true,
+  "selection": {"map": "madrid", "theme": "dark"},
+  "authoringManifestSchemaVersion": 2,
+  "compilation": {"ok": true, "diagnostics": [], "report": {}},
+  "diagnostics": []
+}
+```
+
+`tileflow semantic-diff --from-config <path> --to-config <path>` compares the sole map exported by
+each ordinary config, which is the normal agent workflow for reviewing a change across two files or
+checkouts. If either endpoint is a multi-map `*.workspace.ts`, select that endpoint explicitly with
+`--from-map` or `--to-map`; selectors are rejected for singular configs. The existing
+`--config <workspace> --from <map> --to <map>` form remains as the same-workspace shortcut. Paired
+config options and workspace options cannot be mixed.
+
+The successful document adds `diff`, whose exact core shape is `{schemaVersion, from, to, summary,
+changes}`; each change is `add`, `remove`, or `change` at an RFC 6901 JSON Pointer. Differences are
+informational, so a non-empty diff still exits successfully. Selection, load, validation, asset, or
+compilation failures leave stdout empty and emit one safe structured document on stderr.

package/docs/deterministic-agent-diagnostics.md

@@ -0,0 +1,47 @@
+# Deterministic agent diagnostics
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+Use JSON mode when an agent or CI job needs to validate or reason about the resolved config:
+
+```sh
+npx tileflow validate --json
+npx tileflow inspect --json
+npx tileflow inspect --map madrid --json
+npx tileflow language manifest --json
+npx tileflow language schema --json
+npx tileflow explain --map madrid --theme dark --json
+npx tileflow semantic-diff --from-config before/tileflow.config.ts --to-config after/tileflow.config.ts --json
+npx tileflow semantic-diff --config maps.workspace.ts --from before --to after --json
+```
+
+`validate`, `inspect`, `explain`, and `semantic-diff` success writes exactly one
+schema-version-1 command envelope to stdout. The two discovery commands intentionally return their
+contracts raw instead of wrapping them: `language manifest --json` emits authoring-manifest version
+2 and `language schema --json` emits config-reference version 4. Every JSON-mode failure, including
+failure to load either raw discovery contract, leaves stdout empty and writes one schema-version-1
+command failure to stderr. Command summaries and every failure diagnostic contain `phase`, `code`,
+`path`, `severity`, `message`, and a bounded safe `suggestion`; diagnostics are sorted and
+deduplicated deterministically.
+
+Config inspection returns the resolved map, parent-to-leaf lineage, declared paths, leaf-level merge
+provenance, and an explicit `themeContract`: default/system selection, shared token schema,
+concrete values, typography, lighting, differences from the default, and stable audit diagnostics.
+It omits the executable input-file graph and sanitizes credentials, URL queries,
+secret-shaped values, data URLs, and absolute filesystem paths. The generated
+[`modules-api-reference.json`](https://github.com/tileflow/tileflow-sdk/blob/main/docs/modules-api-reference.json) is the machine-readable
+map/module schema; its default `authoring` entrypoint tells an agent how to write the singular
+config with `extends` and `scenes`, while its named `resolved` entrypoint matches inspection and
+compiler input. Both are produced from executable core schemas rather than a handwritten parallel
+API list.
+
+`tileflow language manifest --json` discovers the complete closed semantic language without loading
+a project: compiler identity, domains and their dependencies, public operations, expression-builder
+signatures and limits, render selectors, semantic fields/features, diagnostics, reports, commands,
+and schema references. `tileflow language schema --json` returns the packaged generated JSON Schema
+that those references address. Together they are the canonical bootstrap surface for an authoring
+agent; neither command writes files or accesses the network.
+
+Each manifest command entry declares its `outputKind`, `outputVersion`, and stable
+`outputSchemaRef`. `raw-authoring-manifest` and `raw-config-reference` identify the two bootstrap
+documents above; `command-envelope` identifies the ordinary version-1 CLI contract.

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

@@ -0,0 +1,190 @@
+# Hosted authentication and deploy
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+Hosted writes have two independent authorization paths:
+
+- Personal developer session: run `npx tileflow login` once for a
+  Tileflow API origin. Login authenticates the account and selects no Map.
+  Map commands exchange it for a brief Map capability; tileset commands use a separate Team data
+  capability.
+- CI key: create a dashboard `CI deploy` key, store it as
+  `TILEFLOW_API_KEY`, and let the repository workflow deploy without a local login. The server
+  binds that key to exactly one Map.
+
+Hosted control-plane requests stay pinned to the configured HTTP(S) origin, apply a hard bounded
+timeout, and stream at most 1 MiB of response data. CLI diagnostics never echo an untrusted remote
+response body or bearer credential.
+
+Inspect the account, then target the Map shown in the dashboard:
+
+```sh
+npx tileflow whoami --json
+npx tileflow deploy --map-id map_AbCdEfGhIjKlMnOp
+npx tileflow status --map-id map_AbCdEfGhIjKlMnOp
+npx tileflow logout
+```
+
+Changing or resetting the hosted account password revokes saved personal CLI sessions. The next
+account or hosted command stops with a clear message and asks you to run `tileflow login` again.
+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:
+
+```sh
+npx tileflow deploy \
+  --map-id map_AbCdEfGhIjKlMnOp \
+  --map store-locator
+```
+
+The Map ID is a public destination, not a credential. A successful server-confirmed deploy keeps
+unrelated manifest entries and records that Map's stable ID, hosted theme URLs, World `v1`
+generation, and fixed session usage mode. Browser access remains server-owned and is never read
+from or written to repository configuration. Do not add an API key or payment authority to a copied
+prompt.
+
+Team tileset commands exchange the same account session for a separate Team-scoped data capability;
+it carries no Map authority. Inspect and preview remain account-free:
+
+```sh
+npx tileflow tileset inspect ./data/stores.pmtiles --json
+npx tileflow tileset inspect ./data/stores.pmtiles \
+  --include-values category,status --json
+npx tileflow tileset publish ./data/stores.pmtiles \
+  --id stores --team @acme --attribution 'Store data © Example' --json
+npx tileflow tileset list --team @acme --json
+npx tileflow tileset status stores --team @acme --json
+```
+
+Inspection schema 1 separates authoritative PMTiles/TileJSON declarations from bounded MVT
+observations. Sampled fields report present/missing feature counts, observed distinct-value counts,
+numeric min/max, and truncation. Raw primitive values remain absent unless `--include-values`
+explicitly selects their comma-separated field names; the command emits at most 16 values per field,
+32 selected fields, and 256 characters per string. `--no-sample` returns only authoritative metadata
+and cannot be combined with value inspection. Directory traversal recomputes addressed-tile and
+tile-entry counts; the header's tile-content count is reported only as a nullable declaration and is
+not treated as authority.
+
+`publish --id` names a Team-local logical resource; Tileflow owns its opaque delivery ID. The
+command validates the archive locally before authentication, hashes it in fixed 16 MiB parts, then
+uploads at most four parts concurrently without buffering the complete file. Interrupted sessions
+remain resumable for 24 hours: rerunning the same command reconciles server receipts and transfers
+only missing parts. Normal Queue initialization is polled for at most two minutes before the command
+returns a resumable availability error. Retryable transfer failures receive fresh short-lived authorization; a changed
+local file stops before completion. Free accepts versions through exactly 2,000,000,000 bytes and
+Starter through exactly 4,000,000,000 bytes, subject to the Team's hosted-storage capacity.
+
+Publication completes only after server-side integrity and PMTiles validation. A compatible new
+version becomes current at the same stable TileJSON and tile URLs, so newly resolved browser
+requests see it without creating a Map deployment. Purge requires `--confirm <exact-id>` and fails
+with bounded dependency context while any retained Map deployment uses the resource. Automation may set a Team data
+`TILEFLOW_API_KEY`; that key selects its Team, so commands omit `--team` and never load account
+state.
+
+`tileset publish --json` emits schema version 2 with the Team selector when known, logical and
+opaque tileset identities, immutable version ID and number, exact byte count, content-hash
+algorithm/hash, final state, and `changed` or `unchanged` publication result. It never emits the
+local path, upload session, storage key, signed URL, ETag, credential, or retry details.
+
+An explicit key or `TILEFLOW_API_KEY` never uses the saved account session. The deploy API rejects a
+`--map-id` that does not match the key. Read-only hosted icon comparison validates the same binding
+before loading its baseline.
+
+A deploy-only key grants `styles:write` and `status:read`. Without additional permissions it cannot upload
+datasets or render images. Give it an expiration, rotate the repository secret
+before it expires, and avoid non-expiring CI keys.
+
+Detected CI never falls back to the credential saved by `tileflow login`: if
+`TILEFLOW_API_KEY` is absent, deploy stops before loading config or making a
+request. Once captured, the key is hidden from `process.env` and `--api-key` is removed from the
+temporary `process.argv` view before the CLI imports executable `tileflow.config.ts`; both process
+surfaces are restored after the protected operation. Every config-aware command uses the same
+scope, including validate, build, dev/watch, capture, visual, inspect, icon inspection, and deploy.
+This is defense in depth, not a sandbox; deploy only reviewed repository code on a trusted runner,
+and do not pass keys through the `--api-key` command line in CI.
+
+The [deploy documentation](https://tileflow.dev/docs/deploy) contains copyable
+GitHub Actions and GitLab CI workflows. Both use `npm ci`, the committed
+lockfile, and the repository-local CLI. GitHub exposes the key only to its deploy
+step. GitLab variables are job-scoped, so its example validates in a keyless job
+and deploys in a protected `production` job; the locked install and runner are
+part of that trusted job boundary. Both serialize publications and intentionally
+omit path filters because `tileflow.config.ts` can import arbitrary repository
+files.
+
+The CLI records bounded private provenance for GitHub Actions, GitLab CI,
+generic CI, and local runs. These provider fields are descriptive client
+reports, not OIDC attestations. Provider values can be overridden with:
+
+```txt
+TILEFLOW_DEPLOY_REPOSITORY
+TILEFLOW_DEPLOY_REVISION
+TILEFLOW_DEPLOY_REF
+TILEFLOW_DEPLOY_RUN_ID
+TILEFLOW_DEPLOY_RUN_URL
+```
+
+Invalid explicit values fail before a network write. Provider metadata that is
+missing, malformed, or too long is omitted. Secrets and the complete
+environment are never logged.
+
+A separate app-build step is absent from the minimal workflows. Self-hosted build and deploy emit the same
+runtime manifest version 1 shape; Hosted fields are optional identity metadata on its map/theme
+entries. Filesystem build writers refuse to replace a manifest carrying Hosted metadata by default,
+and deploy refuses to replace a purely local manifest. Prefer `emitBuildArtifacts: false` or
+separate output paths when the app deliberately packages a deploy manifest. The explicit
+`overwriteHostedManifest: true` build option and
+`tileflow deploy --overwrite-self-hosted-manifest` flag authorize that destination replacement. A
+retry of the same compiled theme family reuses its deployment version and prints `Unchanged`;
+changed cartography prints `Published` with a new version. Allowed websites is managed separately
+in Tileflow and is never read from repository config. The
+fingerprint binds resource references, not the changing bytes behind referenced
+glyph or sprite URLs. Every theme of one logical map publishes atomically; separate maps can still
+partially succeed when no remote batch release is used.
+
+All config, theme-style, icon, and compatibility preflight happens before the first style write. After
+that boundary the current Hosted API has no batch commit across repository-internal orchestration:
+one singular config can publish before a later config fails. The orchestrator then leaves the
+previous local manifest untouched, reports which publications succeeded, and tells the operator to
+retry; idempotent publication converges on that retry. The local manifest
+writer uses a durable same-directory temporary followed by direct rename and directory sync, so
+readers see either the previous or next complete manifest. Multi-file artifact writers remain
+rollback-capable sets. Neither mechanism is a remote transaction or can make several API writes
+all-or-none.
+
+Deploy treats the locally compiled MapLibre Style family as one logical-map artifact. The request
+contains an exact `styles[theme]` collection, per-theme canonical SHA-256 identities in the build
+manifest, only bounded hosting policy that does not belong in MapLibre itself, and the exact managed
+icon-package identity when the family has one. Delivery
+policy is not inherited with cartographic fields. Deploy does not serialize the module
+configuration, send a public `tileset` selector, or ask the hosted API to compile the map again.
+Hosted publication currently requires Tileflow World; `vectorTiles()` remains available for local
+builds and previews but fails deploy before any remote write. The API binds recognized
+Tileflow-owned world and terrain URLs to its generated map ID. A successful response must return
+exactly the submitted theme names and a hosted Style URL for each. Deploy writes strict runtime
+manifest version 1 with stable theme URLs, `colorScheme`, content revision, optional font faces and
+style IDs, rather than duplicating dataset configuration. No older manifest is normalized.
+
+For a map with `icons: ['./icons']`, hosted validation compiles the local SVG/PNG/JPEG/WebP files
+without a key. Ordered directories apply left to right and later exact IDs replace earlier files.
+Deploy uploads the four generated sprite files before its first style write and reuses
+byte-identical packages by content hash. Source icons and absolute paths remain local; generated
+atlas bytes and sorted icon names are public. Each hosted package is limited to 256 icons and 8 MiB
+generated bytes as a processing envelope. There is no package-count quota; physically retained
+generated packages share the organization's 5/10-GB hosted-storage pool with retained PMTiles,
+remain protected by deployment/library references, and otherwise enter the technical orphan grace
+before deletion. Upload success must confirm the submitted `contentHash`, exact icon count, exact
+generated byte total, one opaque `icp_<id>`, and the corresponding query-free
+`/sprites/<id>/sprite` URL. The CLI rejects any missing or divergent field before using that URL.
+
+Hosted deploy currently rejects local or package-owned web fonts before authentication or remote
+writes. Use self-hosted delivery or an explicit public glyph provider. Enabling managed font bundles
+requires a separately deployed ownership, quota, retention, and immutable-delivery contract.
+
+For both managed resource kinds, `assetSetSha256` remains a separate per-map output identity. It
+hashes each generated file's exact portable name, media type, byte count, and SHA-256 using Core's
+asset-set v1 contract; it does not hash only the icon-package manifest. Hosted must
+confirm the immutable resource bytes, reconstruct those same per-file identities (including the
+`icons/<mapId>/` prefix), and reject the Style when the submitted build-manifest hash diverges.

package/docs/inspect-vector-features.md

@@ -0,0 +1,19 @@
+# Inspect vector features
+
+Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/README.md) for installation and a complete first example.
+
+See which bounded source features the exported map sees near a camera before tuning taxonomy,
+density, or labels:
+
+```sh
+npx tileflow inspect features \
+  --center=-3.6927512,40.4086555 --zoom=16 \
+  --layers=poi --properties=name,category,type,icon,filter_rank,size_rank --json
+```
+
+The command supports HTTP(S) TileJSON/vector sources and returns only requested properties plus
+geometry summaries in stable order. Viewport, tiles, bytes, scanned/returned features, names, and
+timeouts are bounded. Safe provenance includes origins, a query-free TileJSON path, and configured
+source revision or `null`; credentials, URL queries, hidden properties, response bodies, and
+absolute paths are omitted. It is read-only apart from executable config's own possible side
+effects and removes `TILEFLOW_API_KEY` before loading config.