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

package/docs/agent-icon-composition.md

@@ -9,21 +9,35 @@ 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
+Its top-level fields, in order, are `schemaVersion: 3`, `pathBase: "cwd"`, and `maps`.
+Schema version 3 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.
+and tests. It replaces version 2's directory-only shape so a locked `iconSet('@team/set')`
+contributor can be represented without inventing a local path.
 
 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:
+`sources` for a prepared ordered composition. A `sources` entry contains:
 
-- `directories`, in the exact left-to-right authoring order, using config-relative paths or safe
-  `npm:<package>/<path>` descriptors;
+- `contributors`, in the exact left-to-right authoring order. Each has a `kind` of `local`,
+  `package` or `icon-set`, a `label` (a config-relative path, a safe `npm:<package>/<path>`
+  descriptor, or the canonical `@team/set` reference) and the `iconIds` it declares. Filesystem
+  contributors also report `insideWorkingTree`; shared contributors report their exact locked
+  `reference` and integer `version`.
 - `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`.
+- `replacements`, naming the replaced and winning contributor export for every later exact-ID
+  replacement, by authored file for filesystem contributors and by `@team/set` for shared ones;
+- `sources`, one entry for each winning ID. A `file` entry carries the cwd-relative `path`, format,
+  byte length and intrinsic dimensions; an `icon-set` entry carries the exact `reference` and
+  `version` and deliberately has no path, because a shared revision publishes verified generated
+  cells rather than original artwork. Both carry the winning `contributor` ordinal.
+- `composition`, the exact ordered `tileflow-icon-composition-v1` receipt when the map declares a
+  shared set, and `null` otherwise; and
+- `insideWorkingTree` and the deterministic generated `packageHash`.
+
+Listing reads the exact `tileflow.icons.lock.json` beside the selected config. It never resolves a
+catalog head, so a newly published revision does not change this output until `tileflow icons
+install`, `update` or `pin` changes the lock. `--cache-dir` selects the verified artifact cache root
+and `--offline` fails a cache miss instead of hydrating it.
 
 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
@@ -37,8 +51,9 @@ uses `../` and `insideWorkingTree: false`; no absolute path is emitted. Listing
 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
+The Tileflow command performs no authentication, browser/server launch, or file write. It performs
+no network request when every locked artifact is already in the verified cache, and `--offline`
+forbids hydration entirely. 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

package/docs/command-families.md

@@ -8,11 +8,19 @@ Start with the [tileflow guide](https://github.com/tileflow/tileflow-sdk/blob/ma
 | 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`  |
+| Team Icon Sets    | `icon-set publish/list/status/versions/uses/archive/unarchive/purge`                           |
+| Repository locks  | `icons install`, `icons update`, `icons pin`                                                   |
 | 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.
 
+`icon-set` and `icons` are deliberately separate. `icon-set` needs Team authority and changes the
+remote catalog. `icons list` and `icons diff` are keyless local inspection, and
+`icons install|update|pin` are the only commands that resolve `latest` or write
+`tileflow.icons.lock.json`. See the
+[Team Icon Set workflow](https://github.com/tileflow/tileflow-sdk/blob/main/packages/cli/docs/team-icon-sets.md).
+
 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/team-icon-sets.md

@@ -0,0 +1,121 @@
+# 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` and a Map
+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 every declared reference that has no pin yet and leaves existing pins alone.
+`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.
+
+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; `--offline` fails a cache miss instead of hydrating it.
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tileflow",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.7",
   "license": "Apache-2.0",
   "description": "CLI-only tools for Tileflow config, capture, visual testing, and deploy.",
   "type": "module",
@@ -36,11 +36,11 @@
   },
   "dependencies": {
     "@hono/node-server": "2.0.10",
-    "@tileflow/capture": ">=0.1.0-alpha.23 <0.1.0-beta.0",
+    "@tileflow/capture": ">=0.1.0-alpha.24 <0.1.0-beta.0",
     "@tileflow/coordinates": ">=0.1.0-alpha.1 <0.1.0-beta.0",
     "@tileflow/coordinates-runtime": ">=0.1.0-alpha.3 <0.1.0-beta.0",
-    "@tileflow/core": ">=0.1.0-alpha.25 <0.1.0-beta.0",
-    "@tileflow/dev": ">=0.1.0-alpha.24 <0.1.0-beta.0",
+    "@tileflow/core": ">=0.1.0-alpha.26 <0.1.0-beta.0",
+    "@tileflow/dev": ">=0.1.0-alpha.25 <0.1.0-beta.0",
     "@tileflow/maps": ">=0.1.0-alpha.4 <0.1.0-beta.0",
     "commander": "^15.0.0",
     "hono": "4.13.5",