cms-field-vocabulary 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+## 1.0.0 (2026-09-02)
+
+### Features
+
+* **catalog:** add CMS field vocabulary [skip release] ([3e6885e](https://github.com/JFusco/cms-field-vocabulary/commit/3e6885ece8aa7cdc2a419e56d84da8703225f55c))
+* **release:** publish cms vocabulary ([d16ab56](https://github.com/JFusco/cms-field-vocabulary/commit/d16ab568514c80e9904c5923303f399912b42805))
+
+# Changelog
+
+All notable changes are published by semantic-release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Fusco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/OPERATING.md

@@ -0,0 +1,214 @@
+# Operating cms-field-vocabulary
+
+This runbook is for maintainers responsible for official-source review, generated catalog integrity, consumer projections, and releases.
+
+## Operating invariants
+
+- `sources/profiles/*.json` is the only human-authored vendor vocabulary.
+- Every documented claim resolves to an official source ID and locator in `sources/official-sources.json`.
+- `sources.lock.json` records a reviewed observation; a scanner cannot accept or update it.
+- Product versions and authoring, management, storage, delivery, and SDK surfaces remain distinct.
+- Framework behavior is consumer policy, not vendor authority.
+- Generated catalogs, platform pages, distributions, and consumer projections are reproducible and never hand-edited.
+- Coding agents receive selected contracts, not the full catalog or duplicated prose.
+- Publication runs only through the authorized `main` release workflow. npm trusted publishing with GitHub OIDC is the normal credential path; a one-time granular token is permitted only to bootstrap the first unscoped package release.
+
+## Routine quality operation
+
+Use the pinned toolchain:
+
+```sh
+corepack enable
+corepack prepare pnpm@11.1.1 --activate
+pnpm install --frozen-lockfile
+```
+
+Before merge:
+
+```sh
+pnpm run verify:ci
+pnpm run test:packed
+```
+
+The pull-request `Quality` workflow runs the complete non-fixing gate. `Commit message lint` validates the pull-request title and every commit. The packed-consumer test is also part of release readiness and must pass before publication.
+
+Generated drift is repaired from source:
+
+```sh
+pnpm run catalog:build
+pnpm run types:build
+```
+
+Never repair `catalog/`, `docs/platforms/`, or `dist/` directly.
+
+## Vendor-documentation freshness
+
+The `Vendor documentation freshness` workflow runs an index scan daily at 13:17 UTC and runs an index scan plus the full official-source scan every Monday at 13:47 UTC. A manual dispatch can select either depth. It has read-only repository access plus permission to open or update issues.
+
+The workflow:
+
+1. checks out the repository without persisted credentials;
+2. runs the release-index scan, adding the full official-source scan on the weekly schedule or a manual `full` dispatch;
+3. verifies that the scanner did not mutate the checkout;
+4. uploads logs and evidence for 30 days;
+5. opens or updates a source-specific attention issue when either scan reports drift or retrieval fails, and uses a scanner-integrity issue when the checkout changes.
+
+It does not edit source, update `sources.lock.json`, open a vocabulary pull request, or publish.
+
+### Triage an attention issue
+
+1. Open the linked workflow run and download the artifact.
+2. Inspect `index.log`, `full.log`, and `worktree-status.txt`.
+3. Identify each observation that is not `unchanged`.
+4. Open the registered official URL and review the exact locator in `sources/official-sources.json`.
+5. Check the page's product/version context and whether the source is `exhaustive` or `supplemental`.
+6. Compare every field and claim in the affected source profile.
+
+Use these dispositions:
+
+| Condition | Action |
+| --- | --- |
+| Transient/unreachable | Retry later; do not change claims or the reviewed lock |
+| Cosmetic document change | Retain it in the scan artifact; it does not create an attention issue or require a lock refresh by itself |
+| Claim-changing | The bounded observed token set is unchanged but claim content moved; update only supported structured claims and evidence, then rebuild |
+| Enumeration-changing | The independent observed token set changed, required tokens disappeared, or discovery could not safely run; audit the entire surface, exact casing, extension boundary, and consumer impact |
+| Version-changing | Add or migrate a versioned profile; do not silently widen a pinned profile |
+| Removed/moved page | Locate an official replacement, update the manifest and locators, and retain review evidence in the pull request |
+
+After review, update only the affected observations:
+
+```sh
+pnpm sources:review -- <source-id> [<source-id>...]
+```
+
+Then run:
+
+```sh
+pnpm run catalog:build
+pnpm run verify:ci
+pnpm run test:packed
+```
+
+`pnpm sources:review -- --all` is reserved for an intentional complete-lock refresh. `--allow-manual` is an exception for an independently reviewed official source that automation cannot retrieve; the pull request must explain the failure and review method, and the reviewer must manually verify every required token. It cannot override a fetched observation that reports missing tokens or establish a new independent enumeration baseline.
+
+Close the attention issue only after the reviewed pull request is merged or the evidence establishes a transient false alarm. Link the issue to the reviewing pull request.
+
+## Review and release impact
+
+The source entry's `reviewOwner` reviews vendor meaning. A second maintainer should review changes that alter any of the following:
+
+- an exhaustive enumeration;
+- canonical field IDs;
+- value, storage, or delivery shapes;
+- official or contract-derived rendering operations;
+- agent-policy rules or renderer bindings;
+- consumer adapter routing;
+- schema versions or public exports;
+- source-lock or projection digest behavior.
+
+Treat canonical-ID removals or renames, profile removal, incompatible schema changes, changed selected-contract meaning, and incompatible public API changes as breaking. Additive native facts are normally minor after `1.0.0`; corrected evidence or prose that does not change a contract is normally patch. Confirm the actual semantic-release result with a dry run.
+
+## Release model
+
+`semantic-release` owns versions, tags, release notes, the changelog, npm publication, and the release commit. Do not run `npm version`, edit the package version manually, create the release tag manually, or reuse an existing version.
+
+Configured analysis rules are:
+
+| Conventional change | Release after `1.0.0` |
+| --- | --- |
+| `feat:` | Minor |
+| `type!:` or `type(scope)!:` | Major |
+| `fix:`, `docs:`, `chore:`, `ci:`, `refactor:`, `test:`, and other configured non-feature types | Patch |
+
+The initial semantic-release publication, when no prior release tag exists, is `1.0.0`. The repository remains `0.0.0-development` until that authorized publication.
+
+Release preflight rejects `BREAKING CHANGE:` bodies because aggregated release bodies can cause accidental majors. Use `!` in the conventional subject for an intentional breaking change.
+
+The literal commit marker `[skip release]` skips only the release job on a push; other quality and wiki workflows still run. Reserve it for a verified non-package follow-up such as recording durable wiki evidence for a release that has already completed. Do not use it to bypass publication for a contract or package change.
+
+## Trusted publication boundary
+
+`.github/workflows/release.yml` is the only publisher. On an authorized `main` push or dispatch it:
+
+- validates release commits;
+- runs the complete quality gate;
+- packs and clean-installs the tarball;
+- performs an npm publish dry run;
+- invokes `semantic-release` to assign the version, update the changelog, publish npm with provenance, create the immutable `v${version}` tag, push the release commit, and publish the GitHub Release.
+
+The workflow grants `contents: write` for the release commit, tag, and GitHub Release, and `id-token: write` for npm trusted publishing and provenance. Bind the npm trusted publisher to `JFusco/cms-field-vocabulary` and `.github/workflows/release.yml`; use a protected GitHub environment when the npm binding requires one.
+
+If npm does not allow the trusted publisher to be attached before the unscoped package exists, create a least-privileged one-time granular access token that can create and publish `cms-field-vocabulary`, store it temporarily as the repository secret `NPM_TOKEN`, and run the same release workflow. `@semantic-release/npm` attempts OIDC first and uses the token only as a fallback. Immediately after `1.0.0` exists, bind the trusted publisher, delete the GitHub secret, and revoke the token. Do not retain a long-lived npm token for later releases.
+
+## First release: 1.0.0
+
+Use this checklist after the trusted publication path is approved:
+
+1. Confirm the npm package name belongs to the project and bind the trusted publisher if npm already permits it.
+2. Confirm branch protection and required checks are active on `main`.
+3. Confirm there is no existing `v1.0.0` tag or published `cms-field-vocabulary@1.0.0`.
+4. Resolve every vendor-freshness attention issue that affects shipped claims.
+5. Confirm `sources.lock.json` contains every registered source and that all generated output is current.
+6. Run locally from a clean checkout:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm run verify:ci
+pnpm run test:packed
+pnpm run release:dry
+```
+
+7. Inspect the dry-run release notes and packed file list. Confirm the proposed version is exactly `1.0.0`.
+8. If the new package cannot yet accept a trusted-publisher binding, install the one-time `NPM_TOKEN` repository secret described above.
+9. Dispatch or allow the release job from `main`.
+10. After a token-bootstrap release, bind the trusted publisher, delete the GitHub secret, and revoke the token before any later release.
+11. Do not retry blindly if the job becomes uncertain after npm publication. Check npm, GitHub Releases, and tags first.
+12. Promote the Phase 1 wiki archive from `partial` to `implemented`, record the npm/tag/GitHub Release evidence, verify the wiki locally, and push that documentation-only commit with `[skip release]` so it cannot create an unintended `1.0.1`.
+
+### Verify 1.0.0
+
+After publication, verify all release outputs:
+
+```sh
+npm view cms-field-vocabulary@1.0.0 version dist.integrity dist.tarball dist.attestations --json
+npm view cms-field-vocabulary@1.0.0 --json
+```
+
+Confirm:
+
+- npm reports version `1.0.0` and provenance;
+- GitHub contains immutable tag `v1.0.0` and the corresponding release notes;
+- `CHANGELOG.md` and `package.json` contain the semantic-release update on `main`;
+- a clean consumer can install `1.0.0`, run `sync`, `check`, and `resolve`;
+- the tarball contains the catalog, profile projections, schemas, source manifest, reviewed source lock, runtime distribution, CLI, and operator documentation, but not repository workflows, tests, environment files, or wiki internals.
+
+## Subsequent releases
+
+For each later release:
+
+1. Review commits since the last `vX.Y.Z` tag.
+2. Run release preflight and dry run.
+3. Confirm freshness review and generated projections are current.
+4. Confirm the proposed semantic version matches contract impact.
+5. Publish only from the trusted `main` workflow.
+6. Verify npm provenance, tag, GitHub release, release commit, and clean-consumer behavior.
+
+## Failed or harmful release
+
+Do not rewrite a GitHub tag, overwrite an npm version, or force-push release history.
+
+For a non-security defect, deprecate the affected npm version with a concise migration message and publish a fixed higher version. For a suspected compromise, stop publication, disable or rotate affected credentials and trusted-publisher access, preserve workflow evidence, follow [SECURITY.md](./SECURITY.md), deprecate the affected version, and release from a newly verified clean commit.
+
+If semantic-release fails after one external side effect, inspect npm, GitHub tags, GitHub Releases, and `main` before rerunning. Resume only after determining which operations completed.
+
+## Consumer incident response
+
+If a selected contract is wrong but official evidence has not changed:
+
+1. identify whether the defect is canonical vendor data, a contract-derived operation, agent policy, or consumer routing;
+2. fix the owning structured layer only;
+3. add a regression test for both compiled catalog and selected output;
+4. publish the appropriate higher version;
+5. have consumers update the exact dependency, run `sync`, and commit or verify the regenerated projection according to their repository policy.
+
+Do not patch generated consumer files or copy corrected prose into adapters as a workaround.

package/README.md

@@ -0,0 +1,162 @@
+# cms-field-vocabulary
+
+[![npm version](https://img.shields.io/npm/v/cms-field-vocabulary.svg)](https://www.npmjs.com/package/cms-field-vocabulary)
+
+`cms-field-vocabulary` is an official-source-backed catalog of native CMS field types and a deterministic contract generator for coding agents. It keeps vendor nomenclature, value shapes, rendering implications, and consumer-specific policy in one structured package without copying the same vocabulary prose into every adapter repository.
+
+Stable publication begins at `1.0.0` and is owned by `semantic-release`. Source checkouts can retain the development placeholder until the release job assigns a version.
+
+## What this package guarantees
+
+- Native field tokens come from official vendor documentation or official vendor repositories recorded in `sources/official-sources.json`.
+- Every documented claim carries a source ID and stable locator. A claim that official evidence does not support compiles as `undocumented`; it is not inferred or filled in.
+- Product versions and schema surfaces stay separate. An authoring label, management-schema token, storage type, delivery type, and SDK type are not treated as synonyms.
+- Consumer output is deterministic for an exact package version, configuration, profile, and selected set of canonical field IDs.
+- Framework guidance is labeled separately from vendor authority. Consumer policy cannot masquerade as an official claim.
+
+This package does not define a cross-CMS universal field enum, promise that open CMS installations cannot add custom types, or replace the vendor documentation linked by each claim.
+
+## Authority and generated output
+
+The repository has one vocabulary-authoring path:
+
+1. `sources/official-sources.json` registers official evidence, its version mode, completeness, locator, expected tokens, allowed hosts, and review owner.
+2. `sources/profiles/*.json` is the canonical human-authored vocabulary. Each file covers one product version, surface, and transport.
+3. `profiles/agent/*.json` contains framework or coding-agent policy. It is not vendor evidence.
+4. `profiles/consumers/*.json` routes a consumer's adapter names to exact vocabulary profiles.
+5. `catalog/`, `docs/platforms/`, `dist/`, and consumer projections are generated from those inputs.
+
+Generated Markdown is a readable view, not another source of truth. Do not edit generated files or reproduce their field tables in adapter rules, skills, or application documentation. Consumers should resolve the contracts they need from the installed package.
+
+## Included profiles
+
+Seven CMS identities are represented by sixteen versioned surface profiles:
+
+| Platform | Profile | Surface | Version boundary |
+| --- | --- | --- | --- |
+| Contentful | `contentful.cma.saas` | Management | SaaS snapshot observed 2026-09-01 |
+| Contentstack | `contentstack.cma.saas` | Management | SaaS snapshot observed 2026-09-01 |
+| Optimizely SaaS | `optimizely-saas.cms-api-v1` | Management | CMS SaaS API v1 |
+| Optimizely SaaS | `optimizely-saas.sdk-2` | SDK | `@optimizely/cms-sdk` 2.x contract snapshot |
+| Optimizely PaaS | `optimizely-paas.cms12-model` | SDK/model | CMS 12 model and editor surface |
+| Optimizely PaaS | `optimizely-paas.cms12-property-data-type` | Storage | `EPiServer.dll` 12.0.3 enum |
+| Optimizely PaaS | `optimizely-paas.cms13-admin` | Authoring | CMS 13 admin labels |
+| Optimizely PaaS | `optimizely-paas.cms13-model` | SDK/model | CMS 13 .NET content model types |
+| SitecoreAI | `sitecore-ai.authoring.current` | Authoring | Rolling SitecoreAI snapshot observed 2026-09-01 |
+| SitecoreAI | `sitecore-ai.content-sdk2` | SDK | Rolling SitecoreAI delivery with Content SDK 2.x |
+| Sitecore XP | `sitecore-on-prem.xp104-authoring` | Authoring | XP 10.4 editor vocabulary |
+| Sitecore XP | `sitecore-on-prem.headless22` | SDK | XP 10.4 with Headless Services 22 |
+| WordPress | `wordpress.core71-meta` | Storage | Core 7.1 `register_meta` |
+| WordPress | `wordpress.core71-rest-schema` | Delivery | Core 7.1 REST JSON Schema |
+| WordPress | `wordpress.core71-block-attributes` | Storage | Core 7.1 block attribute `type` |
+| WordPress | `wordpress.core71-block-attribute-source` | Storage | Core 7.1 block attribute `source` |
+
+The `extensibility` value on each profile tells consumers whether the documented vocabulary is closed at that exact profile, discoverable, or open. It does not change the evidence threshold for adding native types.
+
+## Requirements and installation
+
+- Node.js 24.14.0 or newer
+- pnpm 11.1.1 for repository development
+
+After `1.0.0` is published:
+
+```sh
+pnpm add cms-field-vocabulary
+```
+
+Create `cms-field-vocabulary.config.json` in the consuming repository:
+
+```json
+{
+  "$schema": "./node_modules/cms-field-vocabulary/schemas/consumer-config.schema.json",
+  "packageName": "cms-field-vocabulary",
+  "profile": "generic",
+  "adapter": "contentful",
+  "target": "generated/cms-field-vocabulary"
+}
+```
+
+The available consumer profiles are `generic`, `ai-orchestration`, and `cos`. They may use different adapter names while routing to the same canonical vendor profiles. `generic` and `ai-orchestration` emit coding-agent contracts. The future-facing `cos` profile emits compact official-data shards containing only profile identity plus field `canonicalId`, exact `nativeToken`, optional `displayName`, `valueShape`, and `formats`; it contains no rendering operations, agent profile, renderer bindings, consumer policy, evidence, or descriptive claim prose.
+
+## Synchronize and verify a consumer projection
+
+Synchronize the exact installed package into the configured target:
+
+```sh
+pnpm exec cms-field-vocabulary sync --config cms-field-vocabulary.config.json --if-needed
+```
+
+Verify it in CI without accepting drift:
+
+```sh
+pnpm exec cms-field-vocabulary check --config cms-field-vocabulary.config.json
+```
+
+The target contains:
+
+- a generated ownership marker;
+- package, catalog, and source-lock identity in `source.json`;
+- exact adapter-to-profile routing in `adapters.json`;
+- deterministic adapter contracts under `contracts/`;
+- a SHA-256 projection manifest.
+
+Synchronization accepts relative config paths and absolute config paths that remain inside the consumer root. It refuses absolute or escaping targets, config paths outside the consumer root, symlink traversal, unmarked directories, unexpected files, and locally modified generated files. Replacement is staged and renamed atomically. Treat the entire target as generated and never edit it manually.
+
+## Resolve only the fields needed by an agent
+
+Agent context should contain selected contracts, not the whole catalog. Resolve one or more canonical field IDs from one exact CMS profile:
+
+```sh
+pnpm exec cms-field-vocabulary resolve \
+  --config cms-field-vocabulary.config.json \
+  --field-id optimizely-saas.sdk-2.contentReference \
+  --rendering-selection optimizely-saas.sdk-2.contentReference:content-reference-usage=media \
+  --output artifacts/cms-fields/component-contract.json
+```
+
+Each repeatable `--rendering-selection` uses the exact closed syntax `<field-id>:<discriminator>=<value>`. `resolve` first verifies the installed projection, rejects field IDs from different profiles, applies only the configured consumer's agent policy, sorts and deduplicates the requested IDs, and writes a deterministic selected contract. A selected field with mutually exclusive rendering branches fails closed until its discriminator is supplied. Unknown, duplicate, unrequested, and unsupported selections also fail before output is written. Claim provenance stays in the catalog for audit and review; it is intentionally omitted from normal agent context.
+
+The CLI requires at least one `--field-id`. The programmatic file resolver treats an explicitly empty field list as a successful no-op, returns `null`, and creates no output file.
+
+A consuming adapter should identify the field IDs required by the current component and load that selected artifact. It should not paste field definitions or rendering prose from this repository into its own permanent rules.
+
+Selected-contract size is guarded by committed byte and deterministic token-estimate ceilings in `profiles/context-budget.json`. `pnpm run context:check` rejects growth; maintainers use `pnpm run context:update` only after reviewing an intentional contract expansion.
+
+## Programmatic API
+
+```ts
+import {
+  getProfile,
+  resolveFieldContracts,
+} from 'cms-field-vocabulary';
+
+const profile = getProfile('optimizely-saas.sdk-2');
+const selected = resolveFieldContracts({
+  profileId: profile.id,
+  fieldIds: [
+    'optimizely-saas.sdk-2.contentReference',
+  ],
+  agentProfile: 'react-nextjs',
+  renderingSelections: [{
+    fieldId: 'optimizely-saas.sdk-2.contentReference',
+    discriminator: 'content-reference-usage',
+    value: 'media',
+  }],
+});
+```
+
+Selection-gated operations carry a closed discriminator in the contract. Supplying `renderingSelections` projects only the matching branch; an unknown, duplicate, unrequested, or unsupported choice fails closed.
+
+`resolveFieldContracts` returns `null` immediately when `fieldIds` is empty. Callers should omit `inputs.cmsFieldContracts` in that case so a CMS-free job receives no CMS profile, agent, renderer, or contract metadata.
+
+The root export also provides catalog lookup and projection functions. Package subpath exports expose the generated catalog, JSON Schemas, and consumer profiles. The published tarball also includes the official source manifest and reviewed source lock for filesystem-based audit tooling.
+
+## Freshness is reviewed, not auto-authored
+
+A scheduled, read-only workflow checks registered official release/version indexes daily and runs a full official-source scan weekly. It normalizes fetched documents, compares reviewed hashes, verifies required evidence tokens, and independently extracts complete token sets from structurally bounded official-source regions. The required-token check proves approved facts still have evidence; the independent observed-token hash detects native types added or removed without first adding them to the manifest. Claim text drift is classified separately when the observed enumeration is unchanged. Raw-only cosmetic churn remains visible in the uploaded report but does not create an attention issue.
+
+The scanner never edits vocabulary source, updates the reviewed lock, opens a vocabulary pull request, or publishes a package. A maintainer must inspect the official source at the recorded locator, update structured claims when warranted, run the explicit source-review command, and pass the full quality gate. See [CONTRIBUTING.md](./CONTRIBUTING.md) for evidence rules and [OPERATING.md](./OPERATING.md) for the freshness and release runbooks.
+
+## License and security
+
+The package is available under the [MIT License](./LICENSE). Report security issues according to [SECURITY.md](./SECURITY.md).

package/SECURITY.md

@@ -0,0 +1,49 @@
+# Security policy
+
+## Supported versions
+
+The first public release is `1.0.0`. After release, security fixes are provided for the latest `1.x` release. Development snapshots such as `0.0.0-development` and older minors are not supported distribution channels.
+
+| Version | Supported |
+| --- | --- |
+| Latest `1.x` | Yes |
+| Development snapshots | No |
+| Older major versions | No |
+
+Support here means the maintainers will assess a report and, when warranted, publish a fixed release. No response-time or remediation-time guarantee is made.
+
+## Report a vulnerability privately
+
+Use [GitHub private vulnerability reporting](https://github.com/JFusco/cms-field-vocabulary/security/advisories/new). Include:
+
+- affected package version and entry point;
+- reproduction steps or a minimal proof of concept;
+- security impact and required preconditions;
+- whether the issue affects the CLI, programmatic API, source scanner, generated projection, packed artifact, or release process;
+- any suggested mitigation.
+
+Do not open a public issue with exploit details, tokens, private repository paths, or unpublished vendor information. If private vulnerability reporting is unavailable, open a minimal public issue asking the maintainer to establish a private channel, without describing the vulnerability.
+
+Normal corrections to a public CMS field token, description, source locator, or freshness observation are data-quality issues and can use the public issue tracker. Treat one as a security report when crafted catalog data or vendor content can cause code execution, path traversal, credential disclosure, package compromise, or another security boundary failure.
+
+## Security boundaries
+
+Official vendor pages are evidence, but fetched page content is still untrusted input. The freshness scanner:
+
+- follows only HTTPS sources and checks every redirect against each source's host allowlist;
+- limits redirects, retries, response time, and fetch concurrency;
+- normalizes documents and compares hashes and declared tokens;
+- writes reports only;
+- does not update canonical profiles, accept a new source lock, create a vocabulary pull request, or publish a package.
+
+Human review remains required before `sources.lock.json` or canonical vocabulary source changes.
+
+Consumer projection code rejects absolute or escaping target paths, symlink traversal, unmarked targets, unexpected files, and modified generated files. It writes into a staging directory and replaces a verified target by rename. A vulnerability that bypasses any of those checks is in scope.
+
+Published packages are configured for public npm provenance. Packed-artifact verification checks the expected file boundary, installs the tarball into clean consumers, and scans packed content for known credential and local-path patterns. These controls reduce risk but do not make vendor documentation or generated coding guidance a security warranty.
+
+## Maintainer response
+
+Maintainers should acknowledge the report privately, reproduce it in an isolated environment, determine affected versions, and coordinate a fix and advisory before public disclosure. For a compromised release, pause publication, revoke affected credentials or trusted-publisher access, deprecate the affected npm version, and publish a clean higher version. Do not overwrite an existing npm version or move an existing release tag.
+
+Never request or accept production CMS credentials, npm tokens, GitHub tokens, or customer content as part of a reproduction.

package/bin/cms-field-vocabulary.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+
+import {
+  checkProjection,
+  resolveProjectionFields,
+  syncProjection,
+} from '../dist/index.js';
+
+function usage() {
+  console.error([
+    'Usage:',
+    '  cms-field-vocabulary sync --config <path> [--if-needed]',
+    '  cms-field-vocabulary check --config <path>',
+    '  cms-field-vocabulary resolve --config <path> --field-id <id>... [--rendering-selection <field-id>:<discriminator>=<value>]... --output <path>',
+  ].join('\n'));
+}
+
+function parseRenderingSelection(value) {
+  const match = /^([^:]+):([^=]+)=([^=]+)$/.exec(value);
+  if (!match) {
+    throw new Error('--rendering-selection must use <field-id>:<discriminator>=<value>');
+  }
+  return { fieldId: match[1], discriminator: match[2], value: match[3] };
+}
+
+function parseArguments(argv) {
+  const [command, ...rest] = argv;
+  const options = {
+    command,
+    config: null,
+    output: null,
+    fieldIds: [],
+    renderingSelections: [],
+    ifNeeded: false,
+    seen: new Set(),
+  };
+  function readValue(index, flag) {
+    const value = rest[index + 1];
+    if (!value || value.startsWith('--')) throw new Error(`${flag} requires a value`);
+    return value;
+  }
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    if (argument === '--if-needed') {
+      if (options.seen.has(argument)) throw new Error(`Duplicate option: ${argument}`);
+      options.seen.add(argument);
+      options.ifNeeded = true;
+    }
+    else if (argument === '--config' || argument === '--output') {
+      if (options.seen.has(argument)) throw new Error(`Duplicate option: ${argument}`);
+      options.seen.add(argument);
+      const value = readValue(index, argument);
+      if (argument === '--config') options.config = value;
+      else options.output = value;
+      index += 1;
+    }
+    else if (argument === '--field-id') {
+      options.seen.add(argument);
+      options.fieldIds.push(readValue(index, argument));
+      index += 1;
+    }
+    else if (argument === '--rendering-selection') {
+      options.seen.add(argument);
+      options.renderingSelections.push(parseRenderingSelection(readValue(index, argument)));
+      index += 1;
+    }
+    else throw new Error(`Unknown argument: ${argument}`);
+  }
+  return options;
+}
+
+function rejectOptions(options, command, flags) {
+  for (const flag of flags) {
+    if (options.seen.has(flag)) throw new Error(`${flag} is not valid for ${command}`);
+  }
+}
+
+try {
+  const options = parseArguments(process.argv.slice(2));
+  if (!options.config) throw new Error('--config is required');
+  if (options.command === 'sync') {
+    rejectOptions(options, 'sync', ['--output', '--field-id', '--rendering-selection']);
+    const status = await syncProjection({ configPath: options.config, ifNeeded: options.ifNeeded });
+    console.log(status === 'current' ? 'CMS field projection is current.' : 'CMS field projection synchronized.');
+  } else if (options.command === 'check') {
+    rejectOptions(options, 'check', ['--if-needed', '--output', '--field-id', '--rendering-selection']);
+    await checkProjection({ configPath: options.config });
+    console.log('CMS field projection is current.');
+  } else if (options.command === 'resolve') {
+    rejectOptions(options, 'resolve', ['--if-needed']);
+    if (!options.output) throw new Error('--output is required');
+    if (options.fieldIds.length === 0) throw new Error('resolve requires at least one --field-id');
+    const selected = await resolveProjectionFields({
+      configPath: options.config,
+      fieldIds: options.fieldIds,
+      renderingSelections: options.renderingSelections,
+      output: options.output,
+    });
+    console.log(`Resolved ${selected?.contracts.length || 0} selected CMS field contract(s).`);
+  } else {
+    usage();
+    process.exitCode = 2;
+  }
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  usage();
+  process.exitCode = 1;
+}