@mnstry/atelier 0.2.0-alpha.1

package/docs/attestation.md

@@ -0,0 +1,201 @@
+# Attestation
+
+An attestation is a small governed document (`atelier-attestation@v1`,
+`contracts/atelier-attestation.v1.schema.json`) in which an issuer records an
+admission decision about one payload document — an export, a readiness run, or
+a claim. It binds that decision to the exact payload bytes through a canonical
+hash, names the issuer, and either carries a signature or explicitly declares
+itself unsigned.
+
+An attestation is a record of a decision, not the decision mechanism. It never
+grants runtime authority, never mutates anything, and never substitutes for
+running the published validators yourself.
+
+## Admission versus conformance
+
+The two words are deliberately kept apart, and the schema enforces the split
+structurally:
+
+- Conformance is public and offline. Anyone can run the published validators
+  in this package against a document and reach the same answer. No attestation
+  is needed to establish conformance, and no attestation can establish it.
+- Admission is a decision by a specific issuer to accept a specific payload
+  into a specific destination. An attestation only records an admission
+  decision. MNSTRY's private validator only ever decides MNSTRY admission; it
+  does not define, extend, or gate conformance.
+
+`verdict.scope` is the constant `"admission"`. A document claiming a
+conformance verdict cannot validate against the schema, so the vocabulary
+cannot drift into "certified conformant" territory by accident.
+
+The admission decision itself is one of `admitted`, `rejected`, or
+`needs-review`, with optional machine-readable `reasons` entries
+(`code` + `message`) explaining a rejection or review request.
+
+## Canonical payload hash
+
+`subject.payloadHash` binds the attestation to exact payload content. The
+procedure is normative:
+
+1. Canonicalize the attested payload document with RFC 8785 (JSON
+   Canonicalization Scheme, JCS).
+2. Hash the canonical bytes with SHA-256.
+3. Encode the digest as lowercase hexadecimal (64 characters).
+
+The fields are pinned accordingly: `algorithm` is the constant `"sha-256"`,
+`canonicalization` is the constant `"RFC8785-JCS"`, and `digest` must match
+`^[0-9a-f]{64}$`. A relying party that re-canonicalizes the payload and gets a
+different digest must treat the attestation as not applying to that payload.
+
+This package ships the reference implementation of this procedure —
+`src/attestation/jcs.mjs` (RFC 8785 canonicalization), `src/attestation/sign.mjs`
+(hashing, signing, verification), and the `atelier attestation hash|sign|verify`
+command line. The contract fixes the procedure and the encoding; the
+implementation is replaceable by anything that produces the same bytes.
+
+`subject.schema` names the contract of the attested payload (for example
+`atelier-export@v1`), `subject.ref` carries its stable identifier (exportId,
+runId, or claimId), and optional `subject.references` entries cross-reference
+related claims, runs, exports, or protocols.
+
+## Signature semantics
+
+`signature` is required in shape and nullable in value. Every attestation must
+say one of two things — silently absent is not expressible:
+
+- `"signature": null` — the attestation is unsigned and therefore
+  non-authoritative. It is advisory only: useful as a local record or a
+  tooling artifact, but it proves nothing about who issued it.
+- A signature object — `algorithm` (`ed25519` or `es256`), `keyId`, and a
+  base64url `value`. An admission decision is authoritative only when it
+  carries a signature whose `keyId` the relying party recognizes as belonging
+  to the claimed issuer.
+
+The `issuer` block asserts identity (`id`, `role`, optional `keyId`); the
+signature is what makes that assertion checkable. `issuer.role` distinguishes
+an admission authority from a tool or a self-attestation, but the role field
+alone confers no authority.
+
+Verifier implementation is in scope (see the verification procedure below).
+Key distribution and trust establishment remain policy-level: relying parties
+decide which keys they recognize, and MNSTRY publishes its admission public
+keys out of band.
+
+## Signing procedure
+
+The signing input is the UTF-8 encoding of the RFC 8785 (JCS) canonicalization
+of the attestation document with its `signature` member set to `null`. That
+sentence is normative; everything else here is mechanics.
+
+- To sign: take a schema-valid attestation whose `signature` is `null`,
+  canonicalize it, sign the canonical bytes, and embed the result as
+  `{ "algorithm": ..., "keyId": ..., "value": ... }` where `value` is the
+  unpadded base64url encoding of the raw signature bytes.
+- To verify: take the signed document, replace `signature` with `null`,
+  canonicalize, and verify `signature.value` over those bytes.
+- `ed25519` signatures are raw 64-byte RFC 8032 signatures.
+- `es256` signatures are the 64-byte IEEE P1363 concatenation of r and s,
+  not DER. A DER-encoded signature also fits the schema's base64url pattern,
+  so a verifier must not accept one by accident and a signer must never emit
+  one — both signature shapes are 64 bytes (86 base64url characters).
+
+A signer must refuse to sign a document that is not schema-valid, already
+carries a signature, or names an `issuer.keyId` different from the signing
+key's `keyId`.
+
+## Verification procedure
+
+`verifyAttestation` returns `{ valid, reasons }` and collects every applicable
+reason instead of stopping at the first, in this order:
+
+1. `schema.invalid` — the document fails the attestation schema.
+2. `signature.missing` — `signature` is `null`. An unsigned attestation is
+   non-authoritative, so verification fails by definition.
+3. `signature.algorithm-mismatch` — `signature.algorithm` does not match the
+   public key document's `algorithm` (or its JWK is for another curve).
+4. `signature.key-id-mismatch` — `signature.keyId` does not match the public
+   key document's `keyId`.
+5. `issuer.key-id-mismatch` — `issuer.keyId` is present and differs from
+   `signature.keyId`.
+6. `signature.invalid` — cryptographic verification fails over the signing
+   input defined above.
+
+Payload binding is checked separately by `verifyPayloadBinding`, with reasons
+`payload.digest-mismatch` (recomputed canonical digest differs from
+`subject.payloadHash.digest`) and `payload.schema-field-mismatch` (the
+payload's `schema` field differs from `subject.schema`). Signature validity
+and payload binding are independent answers: a signature can be genuine while
+the attestation is being presented against the wrong payload, and vice versa.
+
+## Key format and the local key file
+
+Key material is handled as JWK only — never PEM. The private key file lives in
+the signing project's working directory, is gitignored by default, and must
+never be committed:
+
+```json
+{
+  "keyId": "example-issuer-2026",
+  "algorithm": "ed25519",
+  "privateKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "wafd…", "d": "9dfu…" }
+}
+```
+
+The signing key loads with fail-closed precedence: the
+`ATELIER_ATTESTATION_KEY_JSON` environment variable (key file JSON), then
+`--key <file>`, then `./atelier-attestation-key.local.json` in the current
+directory. If none is present, signing exits with code 2 — there is no
+"sign without a key" mode.
+
+The public key document is freely shareable and is what verifiers consume:
+
+```json
+{
+  "keyId": "example-issuer-2026",
+  "algorithm": "ed25519",
+  "publicKeyJwk": { "kty": "OKP", "crv": "Ed25519", "x": "wafd…" }
+}
+```
+
+Errors and logs may name `keyId` and `algorithm`, and never any JWK member
+value.
+
+## Command line
+
+```
+atelier attestation hash <payload.json>
+atelier attestation sign <attestation.json> [--key FILE] [--out FILE]
+atelier attestation verify <attestation.json> --public-key FILE [--payload FILE] [--json]
+atelier attestation keygen --key-id ID [--algorithm ed25519|es256] [--out FILE]
+```
+
+- `hash` prints the canonical `payloadHash` object for a payload document.
+- `sign` signs an unsigned attestation with the local signing key and writes
+  the signed document to stdout or `--out`.
+- `verify` checks the signature against a public key file, plus payload
+  binding when `--payload` is given; `--json` prints `{ valid, reasons }`.
+  When no `--payload` is given, the output says so explicitly.
+- `keygen` generates a key pair, writes the private key file (mode 0600,
+  refusing to overwrite an existing file), and prints only the public key
+  document.
+
+Exit codes: 0 success (for `verify`: valid), 1 `verify` judged the attestation
+invalid, 2 usage or input error.
+
+## Fixtures and tests
+
+Reference documents live in `fixtures/atelier-attestation/` (`valid/` and
+`invalid/`), and `test/attestation-contract.test.mjs` validates all of them
+against the schema, asserting that each invalid fixture fails for its intended
+reason.
+
+`valid/` fixtures are schema-valid shapes; only `signed-roundtrip.v1.json` is
+also cryptographically real. Its signature was produced once at authoring time
+with a throwaway key whose private half was never persisted; the public half
+is committed as `keys/roundtrip-issuer.public.v1.json`, and its digest is the
+real canonical hash of `fixtures/atelier-export/sample-studio-offer.v1.json`.
+`test/attestation-signing.test.mjs` verifies the committed signature and the
+payload binding on every run (and never re-signs), alongside a tamper matrix
+asserting the exact failure reason for each mutation.
+`test/attestation-jcs.test.mjs` pins the canonicalizer to the RFC 8785 vectors,
+and `test/attestation-cli.test.mjs` exercises the command line end to end.

package/docs/continuity.md

@@ -0,0 +1,55 @@
+# Distribution continuity commitment
+
+Anyone building on this package needs to know their access cannot be revoked
+by a repository permission change. This document is MNSTRY's answer, and it is
+written to survive skeptical reading.
+
+## What the license already guarantees
+
+Every copy of this package you have received is licensed under Apache-2.0.
+That grant is perpetual and irrevocable for the copy you hold: nothing MNSTRY
+does later — repository changes, relicensing of future versions, commercial
+disagreements — removes your right to use, modify, and redistribute the
+version you received, subject only to the license's own terms (including the
+NOTICE attribution obligation and the trademark limits in `TRADEMARKS.md`).
+
+## What MNSTRY commits to beyond the license
+
+1. **Source grant on every tag.** Every tagged release that MNSTRY
+   distributes to a collaborator or partner is theirs to keep. If your access
+   channel is the Git repository and that access ever ends, you retain every
+   tag you fetched, with full Apache-2.0 rights over it. MNSTRY will not ask
+   for deletion of received tagged source and has no license mechanism to do
+   so.
+2. **npm publication at public release.** When the package's public flip
+   happens, tagged releases will be published to the npm registry under
+   `@mnstry/atelier` with public access, making the registry — not repository
+   permission — the distribution channel of record.
+3. **Contract compatibility by machinery.** From tag `v0.2.0-alpha.0`
+   onward, the published contracts are under a compatibility gate
+   (`npm run contract:compat`): documents valid against the baseline tag must
+   stay valid, and schema widening outside `ext` containers is refused by a
+   schema-vs-schema differ. Breaking changes require a new major contract
+   version, recorded in `CHANGELOG.md` under a **Breaking** bullet and in the
+   migrations map.
+4. **Conformance stays offline.** Validating documents against the published
+   contracts requires only this package and never a MNSTRY service. No future
+   version will make offline conformance depend on a network call — that is
+   enforced by the egress gate, not promised by intention.
+
+## What this document does not promise
+
+- It does not promise that unreleased work, private extension packs, or
+  MNSTRY's runtime services are or will become open.
+- It does not promise support, maintenance windows, or acceptance of
+  contributions.
+- It does not grant trademark rights; `TRADEMARKS.md` governs naming.
+
+## Verifying instead of trusting
+
+- The license grant: `LICENSE` (Apache-2.0, section 2 — "perpetual,
+  worldwide, non-exclusive, no-charge, royalty-free, irrevocable").
+- The compatibility gate: `scripts/check-contract-compat.mjs` and
+  `contracts/compat-baseline.json`.
+- The offline-conformance property: `npm run egress:check` and the served-CSP
+  assertions in the test suite.

package/docs/contract-stability.md

@@ -0,0 +1,111 @@
+# Contract stability
+
+How the Atelier contracts evolve without breaking pinned consumers: the
+stability epoch, the `contractVersion` field, the reserved `ext` extension
+containers and their must-ignore rules, the widening ban, the deprecation
+policy, and the compatibility gate that enforces all of it mechanically.
+
+## The stability epoch
+
+The contracts underwent one sanctioned flag-day break — the epoch. All
+breaking surgery landed together, before the next release tag: the
+vendor-neutral runtime owner vocabulary, the `ext` containers, the optional
+`contractVersion` field, the claim provider addition, and the schema const
+alignments. The individual changes are listed in the changelog.
+
+The first tag cut after this surgery is the epoch baseline. The compatibility
+gate pins to it through `contracts/compat-baseline.json` and is deliberately
+inert — a clean pass with a notice — until that tag exists.
+
+From the epoch onward the rule is mechanical: any change that widens the
+accepted document space outside `ext` is a new major version, and the gate
+enforces this automatically, because validators pinned to the baseline reject
+widened documents.
+
+## Contract version
+
+Every document contract declares an optional root `contractVersion` field:
+
+- Type: string matching `^1\.[0-9]+\.[0-9]+$`.
+- Semantics: the contract revision (major.minor.patch) the producer targeted.
+- The major digit must equal the schema's `@vN` suffix.
+- Absence means `1.0.0`.
+- Producers should emit it; validators must not require it.
+
+Schemas are not republished per revision. The `schema` consts stay `…@v1`;
+each schema root carries a `$comment` naming the current revision (for
+example `contract revision 1.1.0 (contract-stability epoch)`), which is the
+machine-visible revision marker.
+
+## Extension containers
+
+Every object subschema that closes itself with `additionalProperties: false`
+— the root and every nested closed object — declares an optional `ext`
+property of type object. `ext` never appears in `required`. This placement is
+uniform across all contracts and is enforced by the contract hygiene test, so
+new contracts pick up the rule automatically.
+
+`ext` is the only sanctioned place for data the contracts do not define.
+Producers may add namespaced members; vendor-prefixed keys are recommended.
+Contents are not validated at v1 and carry no authority over first-class
+fields.
+
+## Must-ignore rules
+
+- Documents are closed at every level except `ext`. Unknown properties
+  outside `ext` are rejected — typo safety is a feature, not a bug.
+- `ext` members must be ignored by consumers that do not recognize them, must
+  not alter the meaning of first-class fields, and must not be required to
+  interpret the document.
+- Safety scanners are exempt from must-ignore. The dry-run validator's
+  mutation-intent, target-field, and source-reference scanners descend into
+  every nested object, including `ext`, and fail closed. A mutation flag or
+  an unsupported runtime target hidden inside `ext` is still a refusal;
+  must-ignore never suppresses a refusal.
+
+## The widening ban
+
+A v1 revision may tighten constraints or add semantics carried in `ext`;
+anything that widens the accepted document space outside `ext` is a new
+major. Widening includes adding enum values, opening a closed object, adding
+optional first-class properties, and relaxing a pattern or a bound. The
+compatibility gate turns this policy into a mechanical check: a widened
+document fails validation under the baseline's validators.
+
+## Deprecation policy
+
+- Deprecating a field or value starts with a dated notice in the docs, at
+  least one minor revision before any behavioral change.
+- Deprecated fields keep validating for their entire deprecation window.
+- Removal — or any other change that rejects previously valid documents —
+  happens only at a major version.
+
+## The compatibility gate
+
+`scripts/check-contract-compat.mjs` (npm script `contract:compat`) validates
+the current document corpus against the validators of a past release:
+
+1. Resolve the baseline: a `--baseline <ref>` override, else the
+   `baselineTag` in `contracts/compat-baseline.json`. A null `baselineTag`
+   means the epoch is not yet tagged; the gate prints a notice and passes.
+2. For each corpus entry, fetch the old schema from the baseline ref.
+   Contracts that do not exist at the baseline are reported as new since
+   baseline and skipped — new contracts are always admissible.
+3. Compile the old schema and validate the current corpus against it: valid
+   fixtures, registered sample documents, and generated documents such as the
+   bundled readiness protocols. Generated documents are the ones most likely
+   to drift, so they are always included.
+4. Any rejection names the fixture, the contract, and the baseline, and fails
+   the gate.
+
+A self-consistency test runs the same plumbing with the working tree as its
+own baseline, so the machinery is proven even while the gate is inert.
+
+## Baseline procedure at release time
+
+Cutting a release tag updates `contracts/compat-baseline.json` in the release
+commit, setting `baselineTag` to the tag being cut, and runs
+`npm run contract:compat` as part of the release checks. During the following
+development cycle the gate therefore validates the evolving corpus against
+the most recent release's validators. The first tag after the epoch is the
+first baseline; before it exists, the gate stays inert.

package/docs/distributions.md

@@ -0,0 +1,220 @@
+# Distributions
+
+A distribution is a branded wrapper package around `@mnstry/atelier`. It gives
+a partner or program its own command name, display name, and look while the
+MNSTRY Atelier package underneath keeps doing all of the work. This document
+describes the model, the one invariant every distribution must hold, the
+attribution requirement, and how to build one.
+
+## The three-tier model
+
+1. **Root package** — `@mnstry/atelier`. Owns every command, contract,
+   validator, and the bundled MNSTRY readiness pack. Published and versioned by
+   MNSTRY.
+2. **Distribution wrapper** — a small npm package (for example Loomworks
+   Studio) that depends on the root package, ships a branded bin, and may add
+   extension packs, skills, and projection branding. It never modifies the
+   root package.
+3. **End workspace** — what a user of the distribution initializes and works
+   in. Workspaces created through a distribution are ordinary Atelier
+   workspaces; nothing about them is fork-specific.
+
+Because the wrapper is a dependency edge and not a fork, upgrading a
+distribution is `npm install` of a newer root package, and every root gate
+(contracts, boundary rules, egress checks) applies unchanged.
+
+## The invariant
+
+Add and rebrand, never alter root semantics.
+
+A distribution may add commands of its own, add extension packs, add skills,
+and restyle the projection. It must not remap or shadow root commands, replace
+or edit bundled readiness protocols, or alter the bundled MNSTRY pack in any
+way. Extension packs are the additive path: namespaced protocols load
+alongside the bundled twelve, they never substitute for them. A wrapper that
+changes what a root command means is a fork, not a distribution.
+
+## Attribution requirement
+
+Distributions must carry MNSTRY attribution. The normative wording of this
+requirement lives in `TRADEMARKS.md` under "Required attribution" — this
+document deliberately does not restate it, so the two cannot drift. See also
+`docs/attestation.md` for how admission decisions are recorded.
+
+Three related obligations live alongside it:
+
+- **Quiet software.** Anything carrying the MNSTRY marks is bound by the
+  "Quiet software" clause in `TRADEMARKS.md`: attribution is a passive line,
+  never an upsell, interruption, or call-to-action.
+- **Applications without a CLI.** An app powered by this package that ships no
+  CLI carries the attribution in its user-facing credits or about surface —
+  see "Applications" in `TRADEMARKS.md`.
+- **NOTICE.** The package ships a `NOTICE` file at its root; under
+  Apache-2.0 section 4(d), every derivative redistribution must reproduce it.
+
+Mechanically, attribution has three surfaces:
+
+- **CLI output — automatic.** `runCli` renders the attribution line in
+  `--version` and `--help` output for any non-default brand. A wrapper that
+  dispatches through `runCli` does not need to print anything itself.
+- **Distribution README — blocking.** The distribution's root `README.md`
+  must contain the exact byte string `powered by MNSTRY Atelier`. Surrounding
+  text is free.
+- **Pack manifest — advisory.** An extension-pack manifest should declare
+  `"ext": { "mnstry.atelier/attribution": "powered by MNSTRY Atelier" }`.
+  The `mnstry.atelier/attribution` key is distinct from the `mnstry.atelier`
+  container used for projection branding.
+
+`atelier distribution check` verifies the last two, plus a CLI probe: the
+README byte string is blocking (exit 1 when absent), and when the target's
+`package.json` declares a bin, the check **executes that bin** with
+`--version` (spawned with the current Node, working directory set to the
+target, real pipes) and requires the attribution in its output — this closes
+the loophole where a wrapper injects no-op output streams into `runCli`.
+Because the probe runs the target's code, only point it at distributions you
+trust. A target that looks like a distribution (declares `@mnstry/atelier`,
+ships `packs/`, or carries `atelier.project.json`) but declares no probe-able
+bin — or whose `package.json` does not parse — is a blocking failure; only a
+target with none of those markers gets an advisory skip. The manifest key is
+reported but never blocks. Run it from the distribution root, or point it
+elsewhere with `--target DIR`; `--pack DIR` overrides the default
+`packs/*/atelier.pack.json` manifest lookup. Exit codes: 0 checks passed,
+1 blocking attribution failure, 2 usage error.
+
+## Building a distribution: the Loomworks walkthrough
+
+The reference distribution, Loomworks Studio, lives at
+`examples/loomworks-studio/` in this repository; the steps below are the
+complete recipe it follows, and `npm run distribution:smoke` runs that recipe
+against a packed tarball on every publish. Paths are relative to the wrapper
+package root, for example `~/workspace/loomworks-studio`.
+
+### 1. Create the wrapper package
+
+```json
+{
+  "name": "loomworks-studio",
+  "private": true,
+  "type": "module",
+  "version": "0.1.0",
+  "bin": { "loomworks": "bin/loomworks.mjs" },
+  "dependencies": { "@mnstry/atelier": "file:../.." }
+}
+```
+
+A published distribution depends on a released `@mnstry/atelier` version
+instead of a `file:` path.
+
+### 2. Write the branded bin
+
+The whole wrapper story is one small file:
+
+```js
+#!/usr/bin/env node
+import { runCli } from '@mnstry/atelier/cli'
+import { createRequire } from 'node:module'
+const { version } = createRequire(import.meta.url)('../package.json')
+process.exit(await runCli({
+  argv: process.argv.slice(2),
+  brand: { command: 'loomworks', displayName: 'Loomworks Studio', version },
+}))
+```
+
+With that in place, `loomworks --version` prints
+`Loomworks Studio 0.1.0 — powered by MNSTRY Atelier <root version>` and
+`loomworks --help` opens with the display name and the attribution line — both
+rendered by `runCli`, neither maintained by the wrapper.
+
+### 3. Put the attribution line in the README
+
+Add the exact byte string `powered by MNSTRY Atelier` near the top of the
+wrapper's `README.md`. This is what `distribution check` blocks on.
+
+### 4. Brand the projection
+
+Workspace projections read
+`ext["mnstry.atelier"].distribution` from `atelier.project.json`:
+
+```json
+{
+  "ext": {
+    "mnstry.atelier": {
+      "distribution": {
+        "name": "Loomworks Studio",
+        "eyebrow": "studio projection",
+        "theme": { "accent": "#7a9e7e" }
+      }
+    }
+  }
+}
+```
+
+The "MNSTRY Tenant Readiness" section heading in the rendered projection stays
+as is: it names the bundled MNSTRY pack.
+
+### 5. Add an extension pack
+
+Branded protocols live under `packs/<pack-name>/` with a manifest
+(`atelier.pack.json`, schema `mnstry-atelier-extension-pack@v1`) whose
+protocol ids are namespaced, for example `loomworks.readiness:open-intake`.
+The manifest carries the advisory attribution key:
+
+```json
+{
+  "ext": { "mnstry.atelier/attribution": "powered by MNSTRY Atelier" }
+}
+```
+
+Extension protocols load alongside the bundled twelve; they never replace
+them. Note that pack contributions to the tenant readiness packet ride in an
+unschema'd runtime document (`mnstry.tenant-readiness-packet@v1`) whose shape
+is pinned by tests, not by the versioned contracts the compat gate checks.
+
+Declared pack paths resolve from the directory holding `atelier.project.json`
+and may not contain `..` segments, so the pack directory has to sit inside the
+config directory. Put the workspace config wherever the packs are, not one
+level above them — `examples/loomworks-studio/` keeps both at the wrapper
+root for exactly this reason.
+
+### 6. Ship skills
+
+Distribution skills follow the root package's dual-tree convention:
+`skills/claude/<skill-name>/SKILL.md` and a byte-identical
+`skills/codex/<skill-name>/SKILL.md`.
+
+### 7. Verify
+
+```
+loomworks distribution check
+```
+
+Exit 0 means the README attribution is present; the output also reports
+whether each pack manifest declares the advisory attribution key. The repo's
+distribution smoke gate runs the same check against the installed example.
+
+## `ext["mnstry.atelier"].distribution` reference
+
+All fields are optional; absence renders the default MNSTRY Atelier styling.
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `name` | string | Display name used in the projection title and eyebrow. |
+| `eyebrow` | string | Second half of the eyebrow line (default `local projection`). |
+| `theme` | object | Color overrides, keyed by theme token name. |
+
+Theme token names: `background`, `surface`, `text`, `accent`, `eyebrow`. Each
+maps to a CSS custom property (`--atelier-bg`, `--atelier-surface`,
+`--atelier-text`, `--atelier-accent`, `--atelier-eyebrow`).
+
+Hex-only rule: every theme value must be a CSS hex color of 3, 4, 6, or 8
+digits (`#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`), and unknown theme keys fail
+the build rather than silently dropping. Values are interpolated into a style
+block, so non-hex input fails the build fast — this is an injection guard, not
+a stylistic preference.
+
+## Admission
+
+A distribution changes branding, not authority. Admission of any payload into
+a MNSTRY destination is decided and recorded exactly as for the root package —
+see `docs/attestation.md` for the admission model and how attestations record
+those decisions.