Add user-imported provider pack contract

.github/workflows/ci.yaml

@@ -68,6 +68,7 @@ jobs:
           test -s README.md
           test -s AGENTS.md
           test -s CONTRACT.md
+          test -s PROVIDER_PACKS.md
           test -s LICENSE
           test -s THIRD_PARTY_LICENSES.md
 

AGENTS.md

@@ -6,7 +6,7 @@ Write repository content, code comments, commit messages, issues, and pull reque
 
 ## Scope
 
-- Keep this repository limited to the public core theme catalog, icons, font metrics, and their Rust and npm distribution artifacts.
+- Keep this repository limited to the public core theme catalog, icons, font metrics, user-imported provider-pack contract, and their Rust and npm distribution artifacts.
 - Keep parsing, validation, layout, and SVG rendering in their owning repositories.
 - Do not add authentication, billing, entitlement, network access, paid themes, or customer data.
 - Do not publish a theme schema or compatibility promise before its public contract and conformance data are reviewed.
@@ -16,7 +16,8 @@ Write repository content, code comments, commit messages, issues, and pull reque
 - Treat repository-authored work as Apache-2.0 unless a file explicitly states otherwise.
 - Before adding a third-party font, icon, or asset, record its source, copyright holder, exact license, required license text, attribution, modification status, and redistribution conditions in `THIRD_PARTY_LICENSES.md`.
 - Do not commit an asset with unclear provenance, incompatible terms, or restrictions that prevent the intended Cargo, npm, WASM, or commercial application distribution.
-- Keep paid or proprietary theme bundles outside this public repository.
+- Keep vendor assets with custom terms out of the core catalog and generated packages. A user-imported provider pack may reference local assets only when its manifest preserves source, terms, hashes, artwork policy, and notice data.
+- Do not add paid or proprietary theme delivery.
 
 ## Delivery
 

CONTRACT.md

@@ -2,7 +2,7 @@
 
 ## Status
 
-This document defines the draft `1.0` catalog document shape. Catalog and package version `0.2.0` remain pre-1.0 and may change incompatibly before a stable release. Registry publication is outside this repository change.
+This document defines the draft `1.0` core catalog document shape. Catalog and package version `0.3.0` remain pre-1.0 and may change incompatibly before a stable release. Registry publication is outside this repository change. User-imported provider packs use the separate contract in [`PROVIDER_PACKS.md`](./PROVIDER_PACKS.md); their custom-term assets never enter this core catalog.
 
 The JSON Schema at [`schemas/catalog.schema.json`](./schemas/catalog.schema.json) is the machine-readable source of truth. [`catalog/catalog.json`](./catalog/catalog.json) is the only source catalog. Generated Cargo and npm copies must not be edited directly. The schema is copied into both packages; `$schema` is an editor-facing canonical repository URL and runtime consumers do not fetch it.
 
@@ -69,7 +69,7 @@ SVG validation uses an element and attribute allowlist. It rejects scripts, even
 
 ## Cargo and npm boundary
 
-Cargo `stack-theme` exposes typed Rust records, `catalog()`, `catalog_json()`, `catalog_schema_json()`, `icon_svg()`, `CATALOG_VERSION`, and `CATALOG_REVISION`. npm `@stack-sh/theme` exposes the equivalent frozen `catalog`, `iconAssets`, `iconSvg()`, `catalogVersion`, and `catalogRevision`, plus TypeScript declarations and catalog, metadata, and schema JSON subpath exports. Referenced SVG and license files are copied into both package roots; SVG bytes are also embedded behind the Rust and JavaScript accessors so runtime consumers never resolve catalog paths through the host.
+Cargo `stack-theme` exposes typed Rust records, `catalog()`, `catalog_json()`, `catalog_schema_json()`, `provider_pack_schema_json()`, `icon_svg()`, `CATALOG_VERSION`, and `CATALOG_REVISION`. npm `@stack-sh/theme` exposes the equivalent frozen `catalog`, `providerPackSchema`, `iconAssets`, `iconSvg()`, `catalogVersion`, and `catalogRevision`, plus TypeScript declarations and both schema JSON subpath exports. Referenced core SVG and license files are copied into both package roots; core SVG bytes are also embedded behind the Rust and JavaScript accessors so runtime consumers never resolve catalog paths through the host. Provider-pack asset bytes are supplied by the user and are not embedded.
 
 `npm run generate` validates the source catalog, checks package version equality, computes one revision, and updates both package artifacts. `npm run generate:check` fails when a generated artifact is missing or stale. Generated package data is checked into Git so Cargo and npm builds do not need network, filesystem discovery, Git, a clock, locale, or host font measurement at runtime.
 

Cargo.toml

@@ -7,7 +7,7 @@ edition = "2024"
 license = "Apache-2.0"
 repository = "https://github.com/stack-sh/theme"
 rust-version = "1.85"
-version = "0.2.0"
+version = "0.3.0"
 
 [workspace.dependencies]
 serde = { version = "1.0", features = ["derive"] }

PROVIDER_PACKS.md

@@ -0,0 +1,51 @@
+# User-imported provider icon packs
+
+## Status and boundary
+
+This document defines the draft `1.0` manifest for provider icons that a user imports from an official archive. It is separate from the core theme catalog because current AWS, Google Cloud, and Azure terms permit architecture-diagram use but do not provide a clear license for Stack to redistribute the asset bytes in Cargo, npm, Web, WebAssembly, or native binary packages.
+
+The Stack repository and packages contain only the Apache-2.0 manifest schema, types, and validation logic. They never contain, mirror, proxy, automatically download, or upload provider asset bytes. A host application must ask the user to select a local archive and accept the linked provider terms before creating a pack.
+
+## Manifest identity
+
+Every manifest requires:
+
+- `schemaVersion` and a semantically versioned `packVersion`;
+- one lowercase provider `id`, human-readable name, and matching icon namespace;
+- `distributionMode: "user-imported"`;
+- the official source page, archive URL, archive SHA-256, upstream release, retrieval date, terms URL, terms-review date, copyright statement, and `LicenseRef-*` identifier;
+- a rights record that fixes package redistribution, automatic download, and server upload to `false`, generated diagram embedding to `true`, and artwork preservation to `true`;
+- user-visible attribution, terms summary, and non-endorsement notice;
+- one or more provider-prefixed icon records.
+
+The schema records `archiveUrl` as provenance. It is not permission for a runtime consumer to fetch the URL. Import remains an explicit user-selected local operation.
+
+## Icon records
+
+An icon ID has the form `<provider>:<slug>`, such as `aws:s3`, `gcp:cloud-run`, or `azure:storage-accounts`. The prefix must equal `provider.id`. Each icon preserves a stable subject, official product name, recommended Stack node kind, upstream archive path, processed local SVG path, integer view box, original and processed SHA-256 hashes, and an ordered transformation log.
+
+The importer may perform only visual-preservation transformations needed for safe standalone SVG, such as removing metadata, converting stylesheet declarations to equivalent presentation attributes, removing unused identifiers, or normalizing XML. Recoloring, cropping, flipping, rotation, distortion, product substitution, or aspect-ratio changes are outside the contract.
+
+An empty transformation list requires identical original and processed hashes. A changed hash requires at least one declared transformation. The processed SVG must pass the same script, event-handler, external-reference, executable URL, and viewport safety checks as core assets.
+
+## Terms and output
+
+`rights.permittedOutputs` is copied from the reviewed provider terms rather than inferred from Stack's Apache-2.0 license. The manifest requires explicit acceptance of those linked terms. A renderer may embed an icon only in a listed output type and must preserve the official artwork.
+
+Rendered output should record provider ID, icon ID, official product name, upstream release, archive hash, terms URL, and pack revision. The CLI should emit a human-readable notice sidecar containing the manifest notice and every used asset. The product name should appear near the icon when the provider guidance recommends or requires it.
+
+Terms can change independently of a pack. Hosts must display the review date and source link, warn after `reviewAfter`, and allow a pack to be removed without changing the core catalog. A provider pack never overrides a core icon ID or another provider namespace.
+
+## Validation
+
+Repository validation covers JSON Schema shape, namespace equality, duplicate IDs and paths, source and processed hashes, transformation evidence, path containment, file presence, SVG safety, and Cargo/npm schema equality. No test fixture uses a real provider asset.
+
+Run:
+
+```sh
+npm run validate
+npm test
+npm run generate:check
+npm run typecheck
+cargo test --workspace --locked
+```

README.md

@@ -1,10 +1,12 @@
 # Stack Theme
 
-`stack-sh/theme` is the canonical public catalog for Stack diagram themes, icons, and font metrics.
+`stack-sh/theme` is the canonical public contract for Stack diagram themes, icons, font metrics, and local provider icon packs.
 
-The draft catalog contract is defined by [`CONTRACT.md`](./CONTRACT.md) and [`schemas/catalog.schema.json`](./schemas/catalog.schema.json). The canonical source is [`catalog/catalog.json`](./catalog/catalog.json); Cargo and npm artifacts are generated from that source with one content revision.
+The draft core catalog contract is defined by [`CONTRACT.md`](./CONTRACT.md) and [`schemas/catalog.schema.json`](./schemas/catalog.schema.json). The separate local-only provider-pack contract is defined by [`PROVIDER_PACKS.md`](./PROVIDER_PACKS.md) and [`schemas/provider-pack.schema.json`](./schemas/provider-pack.schema.json). The canonical core source is [`catalog/catalog.json`](./catalog/catalog.json); Cargo and npm artifacts are generated from that source with one content revision.
 
-The current `0.2.0` catalog contains the core `default`, `light`, and `dark` themes, repository-authored fallbacks for every Stack 1.0 node kind, 12 provider-neutral explicit icons, and versioned host-independent font metrics. The explicit icon identifiers are `api`, `web`, `mobile`, `desktop`, `server`, `container`, `cluster`, `cloud`, `scheduler`, `webhook`, `identity`, and `observability`. Neither package has been released to a registry yet.
+The current `0.3.0` catalog contains the core `default`, `light`, and `dark` themes, repository-authored fallbacks for every Stack 1.0 node kind, 12 provider-neutral explicit icons, and versioned host-independent font metrics. The explicit icon identifiers are `api`, `web`, `mobile`, `desktop`, `server`, `container`, `cluster`, `cloud`, `scheduler`, `webhook`, `identity`, and `observability`. Neither package has been released to a registry yet.
+
+Provider-specific assets are not bundled. The provider-pack contract lets a CLI or browser validate an archive that the user explicitly selected from the provider's official source, keep it local, preserve the artwork, and carry source and terms notices into diagram output.
 
 ## Scope
 
@@ -14,10 +16,11 @@ This repository will own:
 - icon metadata and SVG-safe icon assets;
 - deterministic font metrics used by the layout engine;
 - equivalent Rust and npm artifacts generated from the same catalog data.
+- a provider-neutral manifest and validation contract for user-imported vendor icons.
 
 It does not own the Stack language, compilation, layout, SVG rendering, user authentication, billing, entitlement checks, or paid-theme delivery.
 
-Only free core themes belong in this public repository. Paid or proprietary theme bundles must be stored and distributed separately under their own terms.
+Only free, repository-authored core themes and assets belong in this public repository. Vendor asset bytes, paid themes, and proprietary delivery do not.
 
 ## Development
 
@@ -42,4 +45,4 @@ The local [core theme review](./review/index.html) renders every fallback withou
 
 Repository-authored source code, catalog data, and assets are licensed under the [Apache License 2.0](./LICENSE).
 
-Third-party fonts, icons, and other assets keep their own licenses and are not relicensed under Apache-2.0. Their provenance and redistribution terms must be recorded in [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md) before they are committed.
+Third-party fonts, icons, and other assets keep their own licenses and are not relicensed under Apache-2.0. Their provenance and redistribution terms must be recorded in [THIRD_PARTY_LICENSES.md](./THIRD_PARTY_LICENSES.md) before they are committed. Current provider icons are user-imported and are never committed or copied into the Cargo or npm packages.

catalog/catalog.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://raw.githubusercontent.com/stack-sh/theme/main/schemas/catalog.schema.json",
   "schemaVersion": "1.0",
-  "catalogVersion": "0.2.0",
+  "catalogVersion": "0.3.0",
   "reservedThemeIds": [],
   "fallbacks": {
     "missingThemeId": "default",