Versions & Snapshots

Brand packages are versioned and immutable so the Portal can pin a version, diff two versions, and explain what changed. Versions are date-based — clearer for brand governance than semver, and matching how brand locks are already referenced (e.g. "v2 lock 2026-05-06") (ADR 0002 §7).

Snapshot layout

Each version is an immutable directory under the tenant's versions/:

registries/{ns}/
  brand-system.css            # working copy (next version in progress)
  versions/
    2026.06.05/               # immutable once published
      brand-system.css
      brand-profile.json      # governed profile instance (git-reviewed)
      requirements.schema.json
      asset-manifest.json     # asset IDs, versions, signed-URL policy, alt text, usage rules
      guidelines.json         # normalized docs summary

The first Vandoko snapshot is registries/vandoko/versions/2026.06.05/.

• brand-profile.json — the tenant's contract-instance values ({ namespace, contractVersion, tokens }), validated by BrandTokenProfileSchema.
• requirements.schema.json — generated from the canonical token contract.
• guidelines.json — a normalized, versioned summary of the brand guideline docs (sections, headings, asset refs) that the Portal's Guideline Viewer renders with its own components.
• asset-manifest.json — the per-tenant asset index plus the signed-URL policy.

Publishing — pnpm brand:snapshot

pnpm brand:snapshot

brand:snapshot (scripts/brand-snapshot.mjs) freezes the working copy into a new versions/{date}/ directory.

Each brand-system version gets a changelog entry so Portal snapshots can reference it to explain what changed.

Portal runtime API

The Portal consumes brand packages at runtime via an authenticated API, distinct from the shadcn-CLI install path. The endpoints (lib/brand-system-api.ts, app/api/brand-system/**):

GET  /api/brand-system/{brandId}/latest                 -> newest version payload
GET  /api/brand-system/{brandId}/{version}              -> immutable snapshot
GET  /api/brand-system/{brandId}/{version}/{file}       -> one snapshot file
POST /api/brand-system/validate                         -> validate a brand-profile against the contract

The {file} whitelist is brand-system.css, brand-profile.json, requirements.schema.json, asset-manifest.json, guidelines.json. brandId is the serving-namespace slug; versions are date-based (2026.06.05).

Gating

This route is key-gated like /r/*, not Clerk-session protected — proxy.ts matches it before the generic /api/* auth.protect() fallthrough. Every branch is force-dynamic + no-store.

The full matrix lives in the Registry Auth & Cache Contract (docs/registry-auth-contract.md).