@bezel-labs/bezel-kit 0.9.0 → 0.11.0

package/README.md

@@ -45,6 +45,8 @@ bezel init [options]            # create a bezel.json for this project
 bezel build [options]           # generate the outputs (default command)
 bezel install-mcp [--client]    # connect an AI coding tool to the Bezel MCP
 bezel install-skills [--client] # teach an AI coding tool how to work with Bezel
+bezel diff [--json]             # local edits not in Bezel yet; --json prints them for a push
+bezel sync [--discard-local-edits]   # apply tokens fetched by the Bezel MCP (.bezel/sync.json)
 ```
 
 `init` writes the config so you don't have to author it by hand, picking defaults from
@@ -75,21 +77,34 @@ the project link rather than the build:
 - `projectId` (optional) — the Bezel project this repo is linked to (a UUID).
 - `version` (recommended, default `latest`) — the tokens the Bezel MCP fetches: `latest`
   for the project's latest snapshot, or a published semver like `1.4.0`.
-- `revision` (written by the MCP) — the project revision `design-tokens.json` was last synced
-  from or pushed to. It lets a push preview tell local edits from changes made in Bezel since.
-  `bezel init --project` keeps it for the same project and drops it when the project changes.
-
-All three are read only by the Bezel MCP and ignored by `build`.
+Both are read only by the Bezel MCP and ignored by `build`.
 
 ```json
 {
   "projectId": "0f7a4c2e-1b3d-4e5f-8a9b-0c1d2e3f4a5b",
   "version": "latest",
-  "revision": 12,
   "variablesOutput": "src/bezel/variables.css"
 }
 ```
 
+### Lockfile — `design-tokens-lock.json`
+
+Like `package-lock.json` next to `package.json`: `bezel.json` says which project and version
+to track, and `design-tokens-lock.json` records what was resolved — the exact tokens and the
+project revision this repo last synced or pushed. Commit it together with
+`design-tokens.json` and never edit it. `bezel sync` is the only thing that writes it.
+
+- **Sync:** the Bezel MCP's `get-design-tokens-file` returns the lockfile text. Your agent
+  writes it to `.bezel/sync.json` (gitignored) and runs `bezel sync`, which writes the
+  lockfile and `design-tokens.json` together and rebuilds. It exits with code 2 instead of
+  dropping edits Bezel does not have (`--discard-local-edits` overrides).
+- **Push:** `bezel diff --json` prints your edits as JSON Patch operations with `test`
+  guards — the same format the Bezel app saves with — so only the edits travel. After the
+  Bezel MCP saves them, a sync moves the lockfile to the new revision (your edits are
+  already in Bezel, so the sync keeps them and pulls in anything others changed).
+
+`revision` in `bezel.json` (0.9.0) moved into the lockfile; `bezel init` removes the old key.
+
 Generated outputs live in their own directory because `build` overwrites them without
 asking and adds them to `.gitignore` — keeping them out of a hand-written `src/styles`
 means a generic name like `variables.css` can never clobber a file you wrote.
@@ -139,11 +154,14 @@ Either re-export `design-tokens.json` from Bezel, or pin the old key in `bezel.j
 
 - **Core (`.`):** `tokensToCss`, `emitCss`, `resolveCssOptions`, `getContexts`,
   `formatContextsModule`, `getFonts`, `formatFontsModule`, the `DEFAULT_CONTEXTS` /
-  `DEFAULT_NAME_EXTENSION` defaults, `AGENT_SKILL`, plus the related types.
+  `DEFAULT_NAME_EXTENSION` defaults, `AGENT_SKILL`, the lockfile helpers (`buildLockfile`,
+  `parseLockfile`, `serializeLockfile`, `isPatchApplied`, ...), plus the
+  related types.
 - **Agent skill (`./agent-skill`):** just `AGENT_SKILL` — the `bezel` skill text (`SKILL.md`,
   references, the `AGENTS.md` block, and a short summary for MCP `instructions`).
 - **Node (`./node`):** everything above, plus `generateVariablesCss`, `resolveOptions`,
-  `initConfig`, and the `DEFAULT_OUTPUT_DIR` / `DEFAULT_CONFIG_FILE` defaults.
+  `initConfig`, `diffTokens`, `syncFromStaging`, and the
+  `DEFAULT_OUTPUT_DIR` / `DEFAULT_CONFIG_FILE` defaults.
 
 ## Development
 

package/dist/agent-skill.cjs

@@ -25,14 +25,14 @@ __export(agent_skill_exports, {
 module.exports = __toCommonJS(agent_skill_exports);
 var AGENT_SKILL = {
   name: "bezel",
-  description: "Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.",
+  description: "Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.",
   files: {
-    "SKILL.md": '---\nname: bezel\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\n---\n\n# Bezel in this repository\n\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\n\n```\nBezel app (cloud, source of truth)\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\n  -> bezel build                 reads bezel.json for options and output paths\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\n     contexts.ts, fonts.ts       optional generated TypeScript modules\n```\n\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when they are pushed through the Bezel MCP, after a preview and the user\'s explicit yes (see "Pushing changes back to Bezel"); until then the next sync replaces them.\n\n## Hard rules\n\n1. Never edit a generated file. They start with `/* Generated by bezel \u2014 do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo\'s package manager runner). Confirm the outputs were rewritten before finishing.\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `"includeAll": true`. Adding a token without an `exportName` produces no variable.\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed, and a sync from Bezel overwrites them. Never silently sync over local edits: say so and offer to push them first. Pushing means `preview-design-tokens-push`, showing its `confirmationPrompt` word for word, then `push-design-tokens-file` only after the user says yes. Never push without that confirmation, and never push from a "sync" or "pull" request.\n\n## The tokens file\n\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\n\n```json\n"semantic": {\n  "color": {\n    "primary": {\n      "$type": "color",\n      "$root": { "$value": "{base.color.green.500}" },\n      "dark":  { "$value": { "colorSpace": "oklch", "components": [0.85, 0.16, 152] } },\n      "$extensions": { "com.bezel.app": { "exportName": ["primary", "ring"] } }\n    }\n  }\n}\n```\n\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\n- `$extensions["com.bezel.app"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\n\n## What to do for common requests\n\n| Request | Edit | Then |\n|---|---|---|\n| Change a color, size, radius, or font value | The token\'s `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\n| "Pull the latest tokens" / "sync from Bezel" | See the next section | Rebuild |\n| "Push my changes to Bezel" / save local token edits back | Nothing locally; follow "Pushing changes back to Bezel" | Write the returned `revision` to `bezel.json`; rebuild only if the file was re-synced |\n\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\n\n## Pulling the latest tokens from Bezel\n\n`bezel.json` `projectId` and `version` (`"latest"` or a published semver) say which Bezel project and snapshot this repo tracks. `revision` records the project revision the file was last synced from or pushed to.\n\nWith the Bezel MCP connected: call `get-design-tokens-file` with that `projectId` and `version`, write the returned `content` string to `design-tokens.json` verbatim (no reformatting), set `"revision"` in `bezel.json` to the returned `revision`, then rebuild. The `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\n\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild.\n\nBefore overwriting a `design-tokens.json` that has local edits, stop and offer to push them first (next section) or confirm they should be discarded.\n\n## Pushing changes back to Bezel\n\nNeeds the Bezel MCP. Pushing saves this repo\'s `design-tokens.json` as the project\'s working tokens (`latest`), so the Bezel app stays the source of truth and everyone who syncs gets the change. Publishing a version still happens in the Bezel app.\n\n1. Read `projectId`, `version`, and `revision` from `bezel.json`. If `version` is a semver, tell the user the push updates the working project, not that pinned release.\n2. Call `preview-design-tokens-push` with the exact file text as `content`, `revision` as `baseRevision`, and `version` as `trackedVersion`. It saves nothing.\n3. `invalid` or `blocked`: report the errors and stop (`blocked` is a plan limit on groups, themes, or descriptions). `no-changes`: say the project already matches. Theme keys the file uses that the project does not have yet are added to the project by the push, within the plan\'s theme limit; the preview lists them as `addedContexts`.\n4. `ready`: show `confirmationPrompt` to the user word for word and wait. Do not push on silence, a question, or a different request.\n5. After an explicit yes, call `push-design-tokens-file` with the same `content` and `expectedRevision` = the preview\'s `currentRevision`. `conflict` means Bezel changed in between: go back to step 2.\n6. Write the returned `revision` to `bezel.json`. If the result says `normalized`, sync once (`get-design-tokens-file`, write verbatim, rebuild) so the local file matches Bezel byte for byte.\n\nThe `push-project` prompt walks through this.\n\n## With the Bezel MCP connected\n\nPrefer small, targeted calls over reading the whole tokens file:\n\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\n- `design-review` to check a component description against the tokens.\n\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\n\n## Setting up a repo that is not on Bezel yet\n\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\n',
-    "references/bezel-json.md": '# bezel.json reference\n\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\n\n| Field | Default | Used by | Meaning |\n|---|---|---|---|\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\n| `version` | `"latest"` | MCP | Which tokens snapshot to fetch: `"latest"` or a published semver such as `"1.4.0"`. Set with `--tokens-version`. |\n| `revision` | none | MCP | Project revision the file was last synced from or pushed to. Written by the MCP after a sync or push, never by hand; lets a push preview warn when Bezel changed since. `bezel init --project` drops it when the project changes. |\n| `variablesOutput` | `"src/bezel/variables.css"` | build | Generated CSS file. Import this from the app entry. |\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\n| `contexts` | `{ "$root": ":root", "dark": ".dark", "light": ".light" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\n| `colorFormat` | `"oklch"` | build | `"oklch"` or `"hex"`. |\n| `dimensionUnit` | `"preserve"` | build | `"preserve"` keeps authored units; `"rem"` converts `px` to `rem`. |\n| `nameExtension` | `"com.bezel.app"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\n| `gitignorePath` | `".gitignore"` | build | Which `.gitignore` to manage. |\n| `cwd` | process cwd | build | Base directory paths resolve against. |\n\n`projectId`, `version`, and `revision` are ignored by `bezel build`; everything else is ignored by the MCP.\n\n## CLI\n\n```\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\n```\n\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\n',
-    "references/mcp-tools.md": "# Bezel MCP quick reference\n\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\n\n## Guided workflows\n\n| Tool / prompt | Use |\n|---|---|\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\n| `sync-project` (prompt) | Refresh `design-tokens.json` from the linked project and version, record the revision, then rebuild. Offers to push local edits first instead of overwriting them. |\n| `push-project` (prompt) | Preview, confirm with the user, and push the repo's `design-tokens.json` to the linked project as its working tokens; records the new revision. |\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\n\n## Discovery\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\n\n## Repo sync\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `get-design-tokens-file` | `projectId`, `version?` | The exact `design-tokens.json` content to write to disk, plus project name, version, and `revision` (store it in `bezel.json`). Unknown version -> list of available versions. |\n| `preview-design-tokens-push` | `projectId`, `content`, `baseRevision?`, `trackedVersion?` | Diff of the file against the project's working tokens, validation and plan-limit problems, the themes the file would add (`addedContexts`), a `stale` flag when Bezel changed since the last sync, and a `confirmationPrompt` to show the user verbatim. Saves nothing. |\n| `push-design-tokens-file` | `projectId`, `content`, `expectedRevision` | Saves the file as the project's working tokens, only when the project is still at `expectedRevision` (else `conflict`). Call only after the user confirms the preview. Returns the new `revision`. |\n\n## Reading tokens\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\n\n## Generating code\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\n\n## Color and unit math (deterministic)\n\n| Tool | Parameters |\n|---|---|\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\n\n## Review and history\n\n| Tool | Parameters |\n|---|---|\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\n| `get-chat-history` | `projectId` |\n| `search-chat-history` | `projectId`, `query` |\n\n## Resources\n\n- `bezel://projects`: your projects with ids and names.\n- `bezel://agent-guide`: this skill's text.\n"
+    "SKILL.md": '---\nname: bezel\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\n---\n\n# Bezel in this repository\n\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\n\n```\nBezel app (cloud, source of truth)\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\n     design-tokens-lock.json     what was last synced or pushed (tokens + revision); commit it\n  -> bezel build                 reads bezel.json for options and output paths\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\n     contexts.ts, fonts.ts       optional generated TypeScript modules\n```\n\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when the user asks to push them through the Bezel MCP (see "Pushing changes back to Bezel").\n\n## Hard rules\n\n1. Never edit a generated file. They start with `/* Generated by bezel \u2014 do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo\'s package manager runner). Confirm the outputs were rewritten before finishing.\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `"includeAll": true`. Adding a token without an `exportName` produces no variable.\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a "sync" or "pull" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.\n\n## The tokens file\n\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\n\n```json\n"semantic": {\n  "color": {\n    "primary": {\n      "$type": "color",\n      "$root": { "$value": "{base.color.green.500}" },\n      "dark":  { "$value": { "colorSpace": "oklch", "components": [0.85, 0.16, 152] } },\n      "$extensions": { "com.bezel.app": { "exportName": ["primary", "ring"] } }\n    }\n  }\n}\n```\n\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\n- `$extensions["com.bezel.app"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\n\n## What to do for common requests\n\n| Request | Edit | Then |\n|---|---|---|\n| Change a color, size, radius, or font value | The token\'s `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\n| "Pull the latest tokens" / "sync from Bezel" | See the next section | `bezel sync` rebuilds |\n| "Push my changes to Bezel" / save local token edits back | Nothing by hand; follow "Pushing changes back to Bezel" | Sync, which updates the lockfile |\n\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\n\n## Pulling the latest tokens from Bezel\n\n`bezel.json` `projectId` and `version` (`"latest"` or a published semver) say which Bezel project and snapshot this repo tracks. `design-tokens-lock.json` records the tokens and project revision this repo last synced or pushed, like `package-lock.json` next to `package.json`. Only `bezel sync` writes it.\n\nWith the Bezel MCP connected:\n\n1. Run `npx bezel diff`. If it lists local edits, stop and offer to push them first (next section). A lockfile problem it reports is fixed by this sync.\n2. Call `get-design-tokens-file` with that `projectId` and `version`. Write the returned `lockfileContent` exactly as returned to `.bezel/sync.json`.\n3. Run `npx bezel sync`. It checks the staged file, writes `design-tokens-lock.json` and then `design-tokens.json`, deletes the staged file, and rebuilds.\n   - Exit code 2 means `design-tokens.json` has edits Bezel does not have. Show the message and offer to push them. Use `npx bezel sync --discard-local-edits` only when the user says to drop them.\n   - `unknown command "sync"` means the installed `@bezel-labs/bezel-kit` is too old. Update it first.\n\nThe `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\n\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild. Pushing later needs a lockfile, so sync through the MCP when it becomes available.\n\n## Pushing changes back to Bezel\n\nNeeds the Bezel MCP. A push sends only your edits, as JSON Patch operations, the same way the Bezel app saves. Bezel applies them to the project\'s working tokens (`latest`) and keeps changes others made in the meantime. Publishing a version still happens in the Bezel app.\n\n1. Run `npx bezel diff --json`. `"ok": false` prints what to do (every lockfile problem is fixed by a sync). `"operations": []` means nothing to push.\n2. If `bezel.json` `version` is a semver, tell the user the push updates the working project, not that pinned release.\n3. Call `push-design-tokens` with `projectId`, the printed `operations` and `baseRevision` unchanged, and `version` as `trackedVersion`. If Bezel is still at `baseRevision`, it saves straight away; the user\'s request to push is the go-ahead.\n4. `needs-confirmation`: Bezel changed since the last sync, so nothing was saved. Show `confirmationPrompt` to the user word for word and wait. Only after an explicit yes, call `push-design-tokens` again with the same arguments and `confirmed: true`. Silence, a question, or a different request means no push.\n5. `invalid` or `blocked`: report and stop (`blocked` is a plan limit). `conflict`: the listed tokens changed in Bezel too; follow `nextStep`. `no-changes` with `alreadyApplied`: an earlier push saved these edits but the sync after it did not run; sync now. Themes the edits use that the project lacks are added by the push (`addedContexts`).\n6. A push is not finished until the repo is synced. Sync as in the previous section, steps 2 and 3: `get-design-tokens-file`, write `lockfileContent` to `.bezel/sync.json`, run `npx bezel sync`. Your edits are already in Bezel, so the sync keeps them, pulls in anything others changed, and moves the lockfile to the new revision. Then tell the user to commit `design-tokens.json` and `design-tokens-lock.json` together.\n\n`preview-design-tokens-push` takes the same arguments and shows what a push would change without saving, for when the user asks first. The `push-project` prompt walks through this.\n\n## With the Bezel MCP connected\n\nPrefer small, targeted calls over reading the whole tokens file:\n\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\n- `design-review` to check a component description against the tokens.\n\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\n\n## Setting up a repo that is not on Bezel yet\n\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\n',
+    "references/bezel-json.md": '# bezel.json reference\n\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\n\n| Field | Default | Used by | Meaning |\n|---|---|---|---|\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\n| `version` | `"latest"` | MCP | Which tokens snapshot to fetch: `"latest"` or a published semver such as `"1.4.0"`. Set with `--tokens-version`. |\n| `variablesOutput` | `"src/bezel/variables.css"` | build | Generated CSS file. Import this from the app entry. |\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\n| `contexts` | `{ "$root": ":root", "dark": ".dark", "light": ".light" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\n| `colorFormat` | `"oklch"` | build | `"oklch"` or `"hex"`. |\n| `dimensionUnit` | `"preserve"` | build | `"preserve"` keeps authored units; `"rem"` converts `px` to `rem`. |\n| `nameExtension` | `"com.bezel.app"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\n| `gitignorePath` | `".gitignore"` | build | Which `.gitignore` to manage. |\n| `cwd` | process cwd | build | Base directory paths resolve against. |\n\n`projectId` and `version` are ignored by `bezel build`; everything else is ignored by the MCP. The synced revision lives in `design-tokens-lock.json`, not here.\n\n## design-tokens-lock.json\n\nCommitted next to `design-tokens.json`, like `package-lock.json` next to `package.json`. It records the tokens and project revision this repo last synced or pushed: `lockfileVersion`, `projectId`, `version`, `revision`, and `tokens`. `bezel diff` compares `design-tokens.json` against it to find local edits. Only `bezel sync` writes it, after every sync and every push; never edit it. `bezel init --project` deletes a lockfile that belongs to a different project.\n\n## CLI\n\n```\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\nbezel diff [--json]                                                        local edits vs design-tokens-lock.json (--json: JSON Patch operations for a push)\nbezel sync [--discard-local-edits]                                         apply .bezel/sync.json: write the lockfile and design-tokens.json, then build\n```\n\n`bezel sync` exits with code 2 when `design-tokens.json` has edits Bezel does not have; other problems exit with 1.\n\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\n',
+    "references/mcp-tools.md": "# Bezel MCP quick reference\n\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\n\n## Guided workflows\n\n| Tool / prompt | Use |\n|---|---|\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\n| `sync-project` (prompt) | Refresh `design-tokens.json` and `design-tokens-lock.json` from the linked project and version through `bezel sync`. Offers to push local edits first instead of overwriting them. |\n| `push-project` (prompt) | Diff and push the repo's token edits to the linked project (asking the user first only when Bezel changed), then sync so `design-tokens-lock.json` moves to the new revision. |\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\n\n## Discovery\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\n\n## Repo sync\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `get-design-tokens-file` | `projectId`, `version?` | `lockfileContent`: the full `design-tokens-lock.json` text (tokens + `revision`). Write it to `.bezel/sync.json` and run `npx bezel sync`. Unknown version -> list of available versions. |\n| `preview-design-tokens-push` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?` | Checks the edits from `npx bezel diff --json` against the working tokens: plan-limit problems, `conflict` (tokens edited here and in Bezel), themes the edits add (`addedContexts`), `behind` when Bezel moved on (those changes are kept), and a `confirmationPrompt`. Saves nothing; optional, for when the user wants to see a push first. |\n| `push-design-tokens` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?`, `confirmed?` | Saves the edits as a new revision when Bezel is still at `baseRevision`. If Bezel changed, saves nothing and returns `needs-confirmation` with a `confirmationPrompt`; call again with `confirmed: true` only after the user says yes. Returns the new `revision`. Sync right after it so the lockfile moves to that revision. |\n\n## Reading tokens\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\n\n## Generating code\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\n\n## Color and unit math (deterministic)\n\n| Tool | Parameters |\n|---|---|\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\n\n## Review and history\n\n| Tool | Parameters |\n|---|---|\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\n| `get-chat-history` | `projectId` |\n| `search-chat-history` | `projectId`, `query` |\n\n## Resources\n\n- `bezel://projects`: your projects with ids and names.\n- `bezel://agent-guide`: this skill's text.\n"
   },
-  agentsMdBlock: '## Bezel design tokens\n\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions["com.bezel.app"]`).\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\n- The Bezel app is the source of truth. Local edits to `design-tokens.json` are not in Bezel until pushed, and the next sync (`get-design-tokens-file` via the Bezel MCP, or a download from the app) replaces them. Before syncing over local edits, or when asked to push, call `preview-design-tokens-push`, show its confirmation prompt word for word, and call `push-design-tokens-file` only after the user says yes.\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.',
-  summary: 'Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\n\n## Hard rules\n\n1. Never edit a generated file. They start with `/* Generated by bezel \u2014 do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo\'s package manager runner). Confirm the outputs were rewritten before finishing.\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `"includeAll": true`. Adding a token without an `exportName` produces no variable.\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed, and a sync from Bezel overwrites them. Never silently sync over local edits: say so and offer to push them first. Pushing means `preview-design-tokens-push`, showing its `confirmationPrompt` word for word, then `push-design-tokens-file` only after the user says yes. Never push without that confirmation, and never push from a "sync" or "pull" request.'
+  agentsMdBlock: '## Bezel design tokens\n\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions["com.bezel.app"]`).\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\n- The Bezel app is the source of truth. `design-tokens-lock.json` records what was last synced or pushed; never edit it, and commit it together with `design-tokens.json`. `npx bezel diff` lists local edits that are not in Bezel yet.\n- Sync through the Bezel MCP: write `get-design-tokens-file`\'s `lockfileContent` to `.bezel/sync.json`, then run `npx bezel sync` (it writes both files and refuses to drop unpushed edits). To push (only when asked), run `npx bezel diff --json`, call `push-design-tokens` with its operations, then sync to update the lockfile. If it returns `needs-confirmation` (Bezel changed meanwhile), show the confirmation prompt word for word and call again with `confirmed: true` only after the user says yes.\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.',
+  summary: 'Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\n\n## Hard rules\n\n1. Never edit a generated file. They start with `/* Generated by bezel \u2014 do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo\'s package manager runner). Confirm the outputs were rewritten before finishing.\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `"includeAll": true`. Adding a token without an `exportName` produces no variable.\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a "sync" or "pull" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.'
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {

package/dist/agent-skill.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/agent-skill.ts"],"sourcesContent":["/* Generated from skill/bezel by scripts/build-agent-skill.mjs — do not edit by hand. */\n\n/** The Bezel agent skill, embedded so it can be installed into a repo or served by the Bezel MCP. */\nexport interface AgentSkill {\n  /** Skill name; also the folder name under `.claude/skills` or `.agents/skills`. */\n  name: string\n  /** Frontmatter description: when the skill applies. */\n  description: string\n  /** Skill files keyed by path relative to the skill folder (`SKILL.md`, `references/...`). */\n  files: Record<string, string>\n  /** Markdown placed inside the managed block of AGENTS.md. */\n  agentsMdBlock: string\n  /** Description plus the hard rules, sized for an MCP `instructions` field. */\n  summary: string\n}\n\nexport const AGENT_SKILL: AgentSkill = {\n  name: \"bezel\",\n  description: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\",\n  files: {\n    \"SKILL.md\": \"---\\nname: bezel\\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\\n---\\n\\n# Bezel in this repository\\n\\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\\n\\n```\\nBezel app (cloud, source of truth)\\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\\n  -> bezel build                 reads bezel.json for options and output paths\\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\\n     contexts.ts, fonts.ts       optional generated TypeScript modules\\n```\\n\\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when they are pushed through the Bezel MCP, after a preview and the user's explicit yes (see \\\"Pushing changes back to Bezel\\\"); until then the next sync replaces them.\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed, and a sync from Bezel overwrites them. Never silently sync over local edits: say so and offer to push them first. Pushing means `preview-design-tokens-push`, showing its `confirmationPrompt` word for word, then `push-design-tokens-file` only after the user says yes. Never push without that confirmation, and never push from a \\\"sync\\\" or \\\"pull\\\" request.\\n\\n## The tokens file\\n\\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\\n\\n```json\\n\\\"semantic\\\": {\\n  \\\"color\\\": {\\n    \\\"primary\\\": {\\n      \\\"$type\\\": \\\"color\\\",\\n      \\\"$root\\\": { \\\"$value\\\": \\\"{base.color.green.500}\\\" },\\n      \\\"dark\\\":  { \\\"$value\\\": { \\\"colorSpace\\\": \\\"oklch\\\", \\\"components\\\": [0.85, 0.16, 152] } },\\n      \\\"$extensions\\\": { \\\"com.bezel.app\\\": { \\\"exportName\\\": [\\\"primary\\\", \\\"ring\\\"] } }\\n    }\\n  }\\n}\\n```\\n\\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\\n- `$extensions[\\\"com.bezel.app\\\"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\\n\\n## What to do for common requests\\n\\n| Request | Edit | Then |\\n|---|---|---|\\n| Change a color, size, radius, or font value | The token's `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\\n| \\\"Pull the latest tokens\\\" / \\\"sync from Bezel\\\" | See the next section | Rebuild |\\n| \\\"Push my changes to Bezel\\\" / save local token edits back | Nothing locally; follow \\\"Pushing changes back to Bezel\\\" | Write the returned `revision` to `bezel.json`; rebuild only if the file was re-synced |\\n\\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\\n\\n## Pulling the latest tokens from Bezel\\n\\n`bezel.json` `projectId` and `version` (`\\\"latest\\\"` or a published semver) say which Bezel project and snapshot this repo tracks. `revision` records the project revision the file was last synced from or pushed to.\\n\\nWith the Bezel MCP connected: call `get-design-tokens-file` with that `projectId` and `version`, write the returned `content` string to `design-tokens.json` verbatim (no reformatting), set `\\\"revision\\\"` in `bezel.json` to the returned `revision`, then rebuild. The `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\\n\\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild.\\n\\nBefore overwriting a `design-tokens.json` that has local edits, stop and offer to push them first (next section) or confirm they should be discarded.\\n\\n## Pushing changes back to Bezel\\n\\nNeeds the Bezel MCP. Pushing saves this repo's `design-tokens.json` as the project's working tokens (`latest`), so the Bezel app stays the source of truth and everyone who syncs gets the change. Publishing a version still happens in the Bezel app.\\n\\n1. Read `projectId`, `version`, and `revision` from `bezel.json`. If `version` is a semver, tell the user the push updates the working project, not that pinned release.\\n2. Call `preview-design-tokens-push` with the exact file text as `content`, `revision` as `baseRevision`, and `version` as `trackedVersion`. It saves nothing.\\n3. `invalid` or `blocked`: report the errors and stop (`blocked` is a plan limit on groups, themes, or descriptions). `no-changes`: say the project already matches. Theme keys the file uses that the project does not have yet are added to the project by the push, within the plan's theme limit; the preview lists them as `addedContexts`.\\n4. `ready`: show `confirmationPrompt` to the user word for word and wait. Do not push on silence, a question, or a different request.\\n5. After an explicit yes, call `push-design-tokens-file` with the same `content` and `expectedRevision` = the preview's `currentRevision`. `conflict` means Bezel changed in between: go back to step 2.\\n6. Write the returned `revision` to `bezel.json`. If the result says `normalized`, sync once (`get-design-tokens-file`, write verbatim, rebuild) so the local file matches Bezel byte for byte.\\n\\nThe `push-project` prompt walks through this.\\n\\n## With the Bezel MCP connected\\n\\nPrefer small, targeted calls over reading the whole tokens file:\\n\\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\\n- `design-review` to check a component description against the tokens.\\n\\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\\n\\n## Setting up a repo that is not on Bezel yet\\n\\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\\n\",\n    \"references/bezel-json.md\": \"# bezel.json reference\\n\\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\\n\\n| Field | Default | Used by | Meaning |\\n|---|---|---|---|\\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\\n| `version` | `\\\"latest\\\"` | MCP | Which tokens snapshot to fetch: `\\\"latest\\\"` or a published semver such as `\\\"1.4.0\\\"`. Set with `--tokens-version`. |\\n| `revision` | none | MCP | Project revision the file was last synced from or pushed to. Written by the MCP after a sync or push, never by hand; lets a push preview warn when Bezel changed since. `bezel init --project` drops it when the project changes. |\\n| `variablesOutput` | `\\\"src/bezel/variables.css\\\"` | build | Generated CSS file. Import this from the app entry. |\\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\\n| `contexts` | `{ \\\"$root\\\": \\\":root\\\", \\\"dark\\\": \\\".dark\\\", \\\"light\\\": \\\".light\\\" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\\n| `colorFormat` | `\\\"oklch\\\"` | build | `\\\"oklch\\\"` or `\\\"hex\\\"`. |\\n| `dimensionUnit` | `\\\"preserve\\\"` | build | `\\\"preserve\\\"` keeps authored units; `\\\"rem\\\"` converts `px` to `rem`. |\\n| `nameExtension` | `\\\"com.bezel.app\\\"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\\n| `gitignorePath` | `\\\".gitignore\\\"` | build | Which `.gitignore` to manage. |\\n| `cwd` | process cwd | build | Base directory paths resolve against. |\\n\\n`projectId`, `version`, and `revision` are ignored by `bezel build`; everything else is ignored by the MCP.\\n\\n## CLI\\n\\n```\\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\\n```\\n\\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\\n\",\n    \"references/mcp-tools.md\": \"# Bezel MCP quick reference\\n\\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\\n\\n## Guided workflows\\n\\n| Tool / prompt | Use |\\n|---|---|\\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\\n| `sync-project` (prompt) | Refresh `design-tokens.json` from the linked project and version, record the revision, then rebuild. Offers to push local edits first instead of overwriting them. |\\n| `push-project` (prompt) | Preview, confirm with the user, and push the repo's `design-tokens.json` to the linked project as its working tokens; records the new revision. |\\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\\n\\n## Discovery\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\\n\\n## Repo sync\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `get-design-tokens-file` | `projectId`, `version?` | The exact `design-tokens.json` content to write to disk, plus project name, version, and `revision` (store it in `bezel.json`). Unknown version -> list of available versions. |\\n| `preview-design-tokens-push` | `projectId`, `content`, `baseRevision?`, `trackedVersion?` | Diff of the file against the project's working tokens, validation and plan-limit problems, the themes the file would add (`addedContexts`), a `stale` flag when Bezel changed since the last sync, and a `confirmationPrompt` to show the user verbatim. Saves nothing. |\\n| `push-design-tokens-file` | `projectId`, `content`, `expectedRevision` | Saves the file as the project's working tokens, only when the project is still at `expectedRevision` (else `conflict`). Call only after the user confirms the preview. Returns the new `revision`. |\\n\\n## Reading tokens\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\\n\\n## Generating code\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\\n\\n## Color and unit math (deterministic)\\n\\n| Tool | Parameters |\\n|---|---|\\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\\n\\n## Review and history\\n\\n| Tool | Parameters |\\n|---|---|\\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\\n| `get-chat-history` | `projectId` |\\n| `search-chat-history` | `projectId`, `query` |\\n\\n## Resources\\n\\n- `bezel://projects`: your projects with ids and names.\\n- `bezel://agent-guide`: this skill's text.\\n\"\n  },\n  agentsMdBlock: \"## Bezel design tokens\\n\\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions[\\\"com.bezel.app\\\"]`).\\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\\n- The Bezel app is the source of truth. Local edits to `design-tokens.json` are not in Bezel until pushed, and the next sync (`get-design-tokens-file` via the Bezel MCP, or a download from the app) replaces them. Before syncing over local edits, or when asked to push, call `preview-design-tokens-push`, show its confirmation prompt word for word, and call `push-design-tokens-file` only after the user says yes.\\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.\",\n  summary: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel after a preview and confirmation, and using the Bezel MCP tools.\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed, and a sync from Bezel overwrites them. Never silently sync over local edits: say so and offer to push them first. Pushing means `preview-design-tokens-push`, showing its `confirmationPrompt` word for word, then `push-design-tokens-file` only after the user says yes. Never push without that confirmation, and never push from a \\\"sync\\\" or \\\"pull\\\" request.\",\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,IAAM,cAA0B;AAAA,EACrC,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AAAA,IACL,YAAY;AAAA,IACZ,4BAA4B;AAAA,IAC5B,2BAA2B;AAAA,EAC7B;AAAA,EACA,eAAe;AAAA,EACf,SAAS;AACX;","names":[]}
+{"version":3,"sources":["../src/agent-skill.ts"],"sourcesContent":["/* Generated from skill/bezel by scripts/build-agent-skill.mjs — do not edit by hand. */\n\n/** The Bezel agent skill, embedded so it can be installed into a repo or served by the Bezel MCP. */\nexport interface AgentSkill {\n  /** Skill name; also the folder name under `.claude/skills` or `.agents/skills`. */\n  name: string\n  /** Frontmatter description: when the skill applies. */\n  description: string\n  /** Skill files keyed by path relative to the skill folder (`SKILL.md`, `references/...`). */\n  files: Record<string, string>\n  /** Markdown placed inside the managed block of AGENTS.md. */\n  agentsMdBlock: string\n  /** Description plus the hard rules, sized for an MCP `instructions` field. */\n  summary: string\n}\n\nexport const AGENT_SKILL: AgentSkill = {\n  name: \"bezel\",\n  description: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\",\n  files: {\n    \"SKILL.md\": \"---\\nname: bezel\\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\\n---\\n\\n# Bezel in this repository\\n\\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\\n\\n```\\nBezel app (cloud, source of truth)\\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\\n     design-tokens-lock.json     what was last synced or pushed (tokens + revision); commit it\\n  -> bezel build                 reads bezel.json for options and output paths\\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\\n     contexts.ts, fonts.ts       optional generated TypeScript modules\\n```\\n\\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when the user asks to push them through the Bezel MCP (see \\\"Pushing changes back to Bezel\\\").\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a \\\"sync\\\" or \\\"pull\\\" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.\\n\\n## The tokens file\\n\\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\\n\\n```json\\n\\\"semantic\\\": {\\n  \\\"color\\\": {\\n    \\\"primary\\\": {\\n      \\\"$type\\\": \\\"color\\\",\\n      \\\"$root\\\": { \\\"$value\\\": \\\"{base.color.green.500}\\\" },\\n      \\\"dark\\\":  { \\\"$value\\\": { \\\"colorSpace\\\": \\\"oklch\\\", \\\"components\\\": [0.85, 0.16, 152] } },\\n      \\\"$extensions\\\": { \\\"com.bezel.app\\\": { \\\"exportName\\\": [\\\"primary\\\", \\\"ring\\\"] } }\\n    }\\n  }\\n}\\n```\\n\\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\\n- `$extensions[\\\"com.bezel.app\\\"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\\n\\n## What to do for common requests\\n\\n| Request | Edit | Then |\\n|---|---|---|\\n| Change a color, size, radius, or font value | The token's `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\\n| \\\"Pull the latest tokens\\\" / \\\"sync from Bezel\\\" | See the next section | `bezel sync` rebuilds |\\n| \\\"Push my changes to Bezel\\\" / save local token edits back | Nothing by hand; follow \\\"Pushing changes back to Bezel\\\" | Sync, which updates the lockfile |\\n\\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\\n\\n## Pulling the latest tokens from Bezel\\n\\n`bezel.json` `projectId` and `version` (`\\\"latest\\\"` or a published semver) say which Bezel project and snapshot this repo tracks. `design-tokens-lock.json` records the tokens and project revision this repo last synced or pushed, like `package-lock.json` next to `package.json`. Only `bezel sync` writes it.\\n\\nWith the Bezel MCP connected:\\n\\n1. Run `npx bezel diff`. If it lists local edits, stop and offer to push them first (next section). A lockfile problem it reports is fixed by this sync.\\n2. Call `get-design-tokens-file` with that `projectId` and `version`. Write the returned `lockfileContent` exactly as returned to `.bezel/sync.json`.\\n3. Run `npx bezel sync`. It checks the staged file, writes `design-tokens-lock.json` and then `design-tokens.json`, deletes the staged file, and rebuilds.\\n   - Exit code 2 means `design-tokens.json` has edits Bezel does not have. Show the message and offer to push them. Use `npx bezel sync --discard-local-edits` only when the user says to drop them.\\n   - `unknown command \\\"sync\\\"` means the installed `@bezel-labs/bezel-kit` is too old. Update it first.\\n\\nThe `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\\n\\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild. Pushing later needs a lockfile, so sync through the MCP when it becomes available.\\n\\n## Pushing changes back to Bezel\\n\\nNeeds the Bezel MCP. A push sends only your edits, as JSON Patch operations, the same way the Bezel app saves. Bezel applies them to the project's working tokens (`latest`) and keeps changes others made in the meantime. Publishing a version still happens in the Bezel app.\\n\\n1. Run `npx bezel diff --json`. `\\\"ok\\\": false` prints what to do (every lockfile problem is fixed by a sync). `\\\"operations\\\": []` means nothing to push.\\n2. If `bezel.json` `version` is a semver, tell the user the push updates the working project, not that pinned release.\\n3. Call `push-design-tokens` with `projectId`, the printed `operations` and `baseRevision` unchanged, and `version` as `trackedVersion`. If Bezel is still at `baseRevision`, it saves straight away; the user's request to push is the go-ahead.\\n4. `needs-confirmation`: Bezel changed since the last sync, so nothing was saved. Show `confirmationPrompt` to the user word for word and wait. Only after an explicit yes, call `push-design-tokens` again with the same arguments and `confirmed: true`. Silence, a question, or a different request means no push.\\n5. `invalid` or `blocked`: report and stop (`blocked` is a plan limit). `conflict`: the listed tokens changed in Bezel too; follow `nextStep`. `no-changes` with `alreadyApplied`: an earlier push saved these edits but the sync after it did not run; sync now. Themes the edits use that the project lacks are added by the push (`addedContexts`).\\n6. A push is not finished until the repo is synced. Sync as in the previous section, steps 2 and 3: `get-design-tokens-file`, write `lockfileContent` to `.bezel/sync.json`, run `npx bezel sync`. Your edits are already in Bezel, so the sync keeps them, pulls in anything others changed, and moves the lockfile to the new revision. Then tell the user to commit `design-tokens.json` and `design-tokens-lock.json` together.\\n\\n`preview-design-tokens-push` takes the same arguments and shows what a push would change without saving, for when the user asks first. The `push-project` prompt walks through this.\\n\\n## With the Bezel MCP connected\\n\\nPrefer small, targeted calls over reading the whole tokens file:\\n\\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\\n- `design-review` to check a component description against the tokens.\\n\\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\\n\\n## Setting up a repo that is not on Bezel yet\\n\\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\\n\",\n    \"references/bezel-json.md\": \"# bezel.json reference\\n\\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\\n\\n| Field | Default | Used by | Meaning |\\n|---|---|---|---|\\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\\n| `version` | `\\\"latest\\\"` | MCP | Which tokens snapshot to fetch: `\\\"latest\\\"` or a published semver such as `\\\"1.4.0\\\"`. Set with `--tokens-version`. |\\n| `variablesOutput` | `\\\"src/bezel/variables.css\\\"` | build | Generated CSS file. Import this from the app entry. |\\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\\n| `contexts` | `{ \\\"$root\\\": \\\":root\\\", \\\"dark\\\": \\\".dark\\\", \\\"light\\\": \\\".light\\\" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\\n| `colorFormat` | `\\\"oklch\\\"` | build | `\\\"oklch\\\"` or `\\\"hex\\\"`. |\\n| `dimensionUnit` | `\\\"preserve\\\"` | build | `\\\"preserve\\\"` keeps authored units; `\\\"rem\\\"` converts `px` to `rem`. |\\n| `nameExtension` | `\\\"com.bezel.app\\\"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\\n| `gitignorePath` | `\\\".gitignore\\\"` | build | Which `.gitignore` to manage. |\\n| `cwd` | process cwd | build | Base directory paths resolve against. |\\n\\n`projectId` and `version` are ignored by `bezel build`; everything else is ignored by the MCP. The synced revision lives in `design-tokens-lock.json`, not here.\\n\\n## design-tokens-lock.json\\n\\nCommitted next to `design-tokens.json`, like `package-lock.json` next to `package.json`. It records the tokens and project revision this repo last synced or pushed: `lockfileVersion`, `projectId`, `version`, `revision`, and `tokens`. `bezel diff` compares `design-tokens.json` against it to find local edits. Only `bezel sync` writes it, after every sync and every push; never edit it. `bezel init --project` deletes a lockfile that belongs to a different project.\\n\\n## CLI\\n\\n```\\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\\nbezel diff [--json]                                                        local edits vs design-tokens-lock.json (--json: JSON Patch operations for a push)\\nbezel sync [--discard-local-edits]                                         apply .bezel/sync.json: write the lockfile and design-tokens.json, then build\\n```\\n\\n`bezel sync` exits with code 2 when `design-tokens.json` has edits Bezel does not have; other problems exit with 1.\\n\\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\\n\",\n    \"references/mcp-tools.md\": \"# Bezel MCP quick reference\\n\\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\\n\\n## Guided workflows\\n\\n| Tool / prompt | Use |\\n|---|---|\\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\\n| `sync-project` (prompt) | Refresh `design-tokens.json` and `design-tokens-lock.json` from the linked project and version through `bezel sync`. Offers to push local edits first instead of overwriting them. |\\n| `push-project` (prompt) | Diff and push the repo's token edits to the linked project (asking the user first only when Bezel changed), then sync so `design-tokens-lock.json` moves to the new revision. |\\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\\n\\n## Discovery\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\\n\\n## Repo sync\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `get-design-tokens-file` | `projectId`, `version?` | `lockfileContent`: the full `design-tokens-lock.json` text (tokens + `revision`). Write it to `.bezel/sync.json` and run `npx bezel sync`. Unknown version -> list of available versions. |\\n| `preview-design-tokens-push` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?` | Checks the edits from `npx bezel diff --json` against the working tokens: plan-limit problems, `conflict` (tokens edited here and in Bezel), themes the edits add (`addedContexts`), `behind` when Bezel moved on (those changes are kept), and a `confirmationPrompt`. Saves nothing; optional, for when the user wants to see a push first. |\\n| `push-design-tokens` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?`, `confirmed?` | Saves the edits as a new revision when Bezel is still at `baseRevision`. If Bezel changed, saves nothing and returns `needs-confirmation` with a `confirmationPrompt`; call again with `confirmed: true` only after the user says yes. Returns the new `revision`. Sync right after it so the lockfile moves to that revision. |\\n\\n## Reading tokens\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\\n\\n## Generating code\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\\n\\n## Color and unit math (deterministic)\\n\\n| Tool | Parameters |\\n|---|---|\\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\\n\\n## Review and history\\n\\n| Tool | Parameters |\\n|---|---|\\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\\n| `get-chat-history` | `projectId` |\\n| `search-chat-history` | `projectId`, `query` |\\n\\n## Resources\\n\\n- `bezel://projects`: your projects with ids and names.\\n- `bezel://agent-guide`: this skill's text.\\n\"\n  },\n  agentsMdBlock: \"## Bezel design tokens\\n\\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions[\\\"com.bezel.app\\\"]`).\\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\\n- The Bezel app is the source of truth. `design-tokens-lock.json` records what was last synced or pushed; never edit it, and commit it together with `design-tokens.json`. `npx bezel diff` lists local edits that are not in Bezel yet.\\n- Sync through the Bezel MCP: write `get-design-tokens-file`'s `lockfileContent` to `.bezel/sync.json`, then run `npx bezel sync` (it writes both files and refuses to drop unpushed edits). To push (only when asked), run `npx bezel diff --json`, call `push-design-tokens` with its operations, then sync to update the lockfile. If it returns `needs-confirmation` (Bezel changed meanwhile), show the confirmation prompt word for word and call again with `confirmed: true` only after the user says yes.\\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.\",\n  summary: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a \\\"sync\\\" or \\\"pull\\\" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.\",\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAgBO,IAAM,cAA0B;AAAA,EACrC,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AAAA,IACL,YAAY;AAAA,IACZ,4BAA4B;AAAA,IAC5B,2BAA2B;AAAA,EAC7B;AAAA,EACA,eAAe;AAAA,EACf,SAAS;AACX;","names":[]}

package/dist/agent-skill.js

@@ -1,6 +1,6 @@
 import {
   AGENT_SKILL
-} from "./chunk-WQRF54FG.js";
+} from "./chunk-F7TW5YYD.js";
 export {
   AGENT_SKILL
 };

package/dist/chunk-F7TW5YYD.js

@@ -0,0 +1,17 @@
+// src/agent-skill.ts
+var AGENT_SKILL = {
+  name: "bezel",
+  description: "Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.",
+  files: {
+    "SKILL.md": '---\nname: bezel\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\n---\n\n# Bezel in this repository\n\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\n\n```\nBezel app (cloud, source of truth)\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\n     design-tokens-lock.json     what was last synced or pushed (tokens + revision); commit it\n  -> bezel build                 reads bezel.json for options and output paths\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\n     contexts.ts, fonts.ts       optional generated TypeScript modules\n```\n\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when the user asks to push them through the Bezel MCP (see "Pushing changes back to Bezel").\n\n## Hard rules\n\n1. Never edit a generated file. They start with `/* Generated by bezel \u2014 do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo\'s package manager runner). Confirm the outputs were rewritten before finishing.\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `"includeAll": true`. Adding a token without an `exportName` produces no variable.\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a "sync" or "pull" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.\n\n## The tokens file\n\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\n\n```json\n"semantic": {\n  "color": {\n    "primary": {\n      "$type": "color",\n      "$root": { "$value": "{base.color.green.500}" },\n      "dark":  { "$value": { "colorSpace": "oklch", "components": [0.85, 0.16, 152] } },\n      "$extensions": { "com.bezel.app": { "exportName": ["primary", "ring"] } }\n    }\n  }\n}\n```\n\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\n- `$extensions["com.bezel.app"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\n\n## What to do for common requests\n\n| Request | Edit | Then |\n|---|---|---|\n| Change a color, size, radius, or font value | The token\'s `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\n| "Pull the latest tokens" / "sync from Bezel" | See the next section | `bezel sync` rebuilds |\n| "Push my changes to Bezel" / save local token edits back | Nothing by hand; follow "Pushing changes back to Bezel" | Sync, which updates the lockfile |\n\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\n\n## Pulling the latest tokens from Bezel\n\n`bezel.json` `projectId` and `version` (`"latest"` or a published semver) say which Bezel project and snapshot this repo tracks. `design-tokens-lock.json` records the tokens and project revision this repo last synced or pushed, like `package-lock.json` next to `package.json`. Only `bezel sync` writes it.\n\nWith the Bezel MCP connected:\n\n1. Run `npx bezel diff`. If it lists local edits, stop and offer to push them first (next section). A lockfile problem it reports is fixed by this sync.\n2. Call `get-design-tokens-file` with that `projectId` and `version`. Write the returned `lockfileContent` exactly as returned to `.bezel/sync.json`.\n3. Run `npx bezel sync`. It checks the staged file, writes `design-tokens-lock.json` and then `design-tokens.json`, deletes the staged file, and rebuilds.\n   - Exit code 2 means `design-tokens.json` has edits Bezel does not have. Show the message and offer to push them. Use `npx bezel sync --discard-local-edits` only when the user says to drop them.\n   - `unknown command "sync"` means the installed `@bezel-labs/bezel-kit` is too old. Update it first.\n\nThe `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\n\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild. Pushing later needs a lockfile, so sync through the MCP when it becomes available.\n\n## Pushing changes back to Bezel\n\nNeeds the Bezel MCP. A push sends only your edits, as JSON Patch operations, the same way the Bezel app saves. Bezel applies them to the project\'s working tokens (`latest`) and keeps changes others made in the meantime. Publishing a version still happens in the Bezel app.\n\n1. Run `npx bezel diff --json`. `"ok": false` prints what to do (every lockfile problem is fixed by a sync). `"operations": []` means nothing to push.\n2. If `bezel.json` `version` is a semver, tell the user the push updates the working project, not that pinned release.\n3. Call `push-design-tokens` with `projectId`, the printed `operations` and `baseRevision` unchanged, and `version` as `trackedVersion`. If Bezel is still at `baseRevision`, it saves straight away; the user\'s request to push is the go-ahead.\n4. `needs-confirmation`: Bezel changed since the last sync, so nothing was saved. Show `confirmationPrompt` to the user word for word and wait. Only after an explicit yes, call `push-design-tokens` again with the same arguments and `confirmed: true`. Silence, a question, or a different request means no push.\n5. `invalid` or `blocked`: report and stop (`blocked` is a plan limit). `conflict`: the listed tokens changed in Bezel too; follow `nextStep`. `no-changes` with `alreadyApplied`: an earlier push saved these edits but the sync after it did not run; sync now. Themes the edits use that the project lacks are added by the push (`addedContexts`).\n6. A push is not finished until the repo is synced. Sync as in the previous section, steps 2 and 3: `get-design-tokens-file`, write `lockfileContent` to `.bezel/sync.json`, run `npx bezel sync`. Your edits are already in Bezel, so the sync keeps them, pulls in anything others changed, and moves the lockfile to the new revision. Then tell the user to commit `design-tokens.json` and `design-tokens-lock.json` together.\n\n`preview-design-tokens-push` takes the same arguments and shows what a push would change without saving, for when the user asks first. The `push-project` prompt walks through this.\n\n## With the Bezel MCP connected\n\nPrefer small, targeted calls over reading the whole tokens file:\n\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\n- `design-review` to check a component description against the tokens.\n\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\n\n## Setting up a repo that is not on Bezel yet\n\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\n',
+    "references/bezel-json.md": '# bezel.json reference\n\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\n\n| Field | Default | Used by | Meaning |\n|---|---|---|---|\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\n| `version` | `"latest"` | MCP | Which tokens snapshot to fetch: `"latest"` or a published semver such as `"1.4.0"`. Set with `--tokens-version`. |\n| `variablesOutput` | `"src/bezel/variables.css"` | build | Generated CSS file. Import this from the app entry. |\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\n| `contexts` | `{ "$root": ":root", "dark": ".dark", "light": ".light" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\n| `colorFormat` | `"oklch"` | build | `"oklch"` or `"hex"`. |\n| `dimensionUnit` | `"preserve"` | build | `"preserve"` keeps authored units; `"rem"` converts `px` to `rem`. |\n| `nameExtension` | `"com.bezel.app"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\n| `gitignorePath` | `".gitignore"` | build | Which `.gitignore` to manage. |\n| `cwd` | process cwd | build | Base directory paths resolve against. |\n\n`projectId` and `version` are ignored by `bezel build`; everything else is ignored by the MCP. The synced revision lives in `design-tokens-lock.json`, not here.\n\n## design-tokens-lock.json\n\nCommitted next to `design-tokens.json`, like `package-lock.json` next to `package.json`. It records the tokens and project revision this repo last synced or pushed: `lockfileVersion`, `projectId`, `version`, `revision`, and `tokens`. `bezel diff` compares `design-tokens.json` against it to find local edits. Only `bezel sync` writes it, after every sync and every push; never edit it. `bezel init --project` deletes a lockfile that belongs to a different project.\n\n## CLI\n\n```\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\nbezel diff [--json]                                                        local edits vs design-tokens-lock.json (--json: JSON Patch operations for a push)\nbezel sync [--discard-local-edits]                                         apply .bezel/sync.json: write the lockfile and design-tokens.json, then build\n```\n\n`bezel sync` exits with code 2 when `design-tokens.json` has edits Bezel does not have; other problems exit with 1.\n\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\n',
+    "references/mcp-tools.md": "# Bezel MCP quick reference\n\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\n\n## Guided workflows\n\n| Tool / prompt | Use |\n|---|---|\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\n| `sync-project` (prompt) | Refresh `design-tokens.json` and `design-tokens-lock.json` from the linked project and version through `bezel sync`. Offers to push local edits first instead of overwriting them. |\n| `push-project` (prompt) | Diff and push the repo's token edits to the linked project (asking the user first only when Bezel changed), then sync so `design-tokens-lock.json` moves to the new revision. |\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\n\n## Discovery\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\n\n## Repo sync\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `get-design-tokens-file` | `projectId`, `version?` | `lockfileContent`: the full `design-tokens-lock.json` text (tokens + `revision`). Write it to `.bezel/sync.json` and run `npx bezel sync`. Unknown version -> list of available versions. |\n| `preview-design-tokens-push` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?` | Checks the edits from `npx bezel diff --json` against the working tokens: plan-limit problems, `conflict` (tokens edited here and in Bezel), themes the edits add (`addedContexts`), `behind` when Bezel moved on (those changes are kept), and a `confirmationPrompt`. Saves nothing; optional, for when the user wants to see a push first. |\n| `push-design-tokens` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?`, `confirmed?` | Saves the edits as a new revision when Bezel is still at `baseRevision`. If Bezel changed, saves nothing and returns `needs-confirmation` with a `confirmationPrompt`; call again with `confirmed: true` only after the user says yes. Returns the new `revision`. Sync right after it so the lockfile moves to that revision. |\n\n## Reading tokens\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\n\n## Generating code\n\n| Tool | Parameters | Returns |\n|---|---|---|\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\n\n## Color and unit math (deterministic)\n\n| Tool | Parameters |\n|---|---|\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\n\n## Review and history\n\n| Tool | Parameters |\n|---|---|\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\n| `get-chat-history` | `projectId` |\n| `search-chat-history` | `projectId`, `query` |\n\n## Resources\n\n- `bezel://projects`: your projects with ids and names.\n- `bezel://agent-guide`: this skill's text.\n"
+  },
+  agentsMdBlock: '## Bezel design tokens\n\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions["com.bezel.app"]`).\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\n- The Bezel app is the source of truth. `design-tokens-lock.json` records what was last synced or pushed; never edit it, and commit it together with `design-tokens.json`. `npx bezel diff` lists local edits that are not in Bezel yet.\n- Sync through the Bezel MCP: write `get-design-tokens-file`\'s `lockfileContent` to `.bezel/sync.json`, then run `npx bezel sync` (it writes both files and refuses to drop unpushed edits). To push (only when asked), run `npx bezel diff --json`, call `push-design-tokens` with its operations, then sync to update the lockfile. If it returns `needs-confirmation` (Bezel changed meanwhile), show the confirmation prompt word for word and call again with `confirmed: true` only after the user says yes.\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.',
+  summary: 'Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\n\n## Hard rules\n\n1. Never edit a generated file. They start with `/* Generated by bezel \u2014 do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo\'s package manager runner). Confirm the outputs were rewritten before finishing.\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `"includeAll": true`. Adding a token without an `exportName` produces no variable.\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a "sync" or "pull" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.'
+};
+
+export {
+  AGENT_SKILL
+};
+//# sourceMappingURL=chunk-F7TW5YYD.js.map

package/dist/chunk-F7TW5YYD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/agent-skill.ts"],"sourcesContent":["/* Generated from skill/bezel by scripts/build-agent-skill.mjs — do not edit by hand. */\n\n/** The Bezel agent skill, embedded so it can be installed into a repo or served by the Bezel MCP. */\nexport interface AgentSkill {\n  /** Skill name; also the folder name under `.claude/skills` or `.agents/skills`. */\n  name: string\n  /** Frontmatter description: when the skill applies. */\n  description: string\n  /** Skill files keyed by path relative to the skill folder (`SKILL.md`, `references/...`). */\n  files: Record<string, string>\n  /** Markdown placed inside the managed block of AGENTS.md. */\n  agentsMdBlock: string\n  /** Description plus the hard rules, sized for an MCP `instructions` field. */\n  summary: string\n}\n\nexport const AGENT_SKILL: AgentSkill = {\n  name: \"bezel\",\n  description: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\",\n  files: {\n    \"SKILL.md\": \"---\\nname: bezel\\ndescription: Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\\n---\\n\\n# Bezel in this repository\\n\\nBezel is a design-token platform. Designers maintain the tokens in the Bezel app; this repo holds an exported copy and generates CSS from it with `@bezel-labs/bezel-kit`.\\n\\n```\\nBezel app (cloud, source of truth)\\n  -> design-tokens.json          DTCG file at the repo root, exported from Bezel\\n     design-tokens-lock.json     what was last synced or pushed (tokens + revision); commit it\\n  -> bezel build                 reads bezel.json for options and output paths\\n  -> variables.css               one CSS scope per context (:root, .dark, .light, ...)\\n     contexts.ts, fonts.ts       optional generated TypeScript modules\\n```\\n\\nThe Bezel app stays the source of truth. Local edits to `design-tokens.json` reach Bezel only when the user asks to push them through the Bezel MCP (see \\\"Pushing changes back to Bezel\\\").\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a \\\"sync\\\" or \\\"pull\\\" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.\\n\\n## The tokens file\\n\\n`design-tokens.json` follows the W3C Design Tokens (DTCG) format. Every token is an object with a `$type` and one `$value` per context:\\n\\n```json\\n\\\"semantic\\\": {\\n  \\\"color\\\": {\\n    \\\"primary\\\": {\\n      \\\"$type\\\": \\\"color\\\",\\n      \\\"$root\\\": { \\\"$value\\\": \\\"{base.color.green.500}\\\" },\\n      \\\"dark\\\":  { \\\"$value\\\": { \\\"colorSpace\\\": \\\"oklch\\\", \\\"components\\\": [0.85, 0.16, 152] } },\\n      \\\"$extensions\\\": { \\\"com.bezel.app\\\": { \\\"exportName\\\": [\\\"primary\\\", \\\"ring\\\"] } }\\n    }\\n  }\\n}\\n```\\n\\n- Context keys (`$root`, `dark`, `light`, or whatever `bezel.json` `contexts` lists) sit inside the token. `$root` is the base; other contexts only need the values that differ.\\n- `$value` is either a literal (DTCG color, dimension, font family, ...) or a reference like `{base.color.green.500}`. References are resolved to literal values in the generated CSS.\\n- `$extensions[\\\"com.bezel.app\\\"].exportName` is the list of CSS variable names the token emits. One token can emit several (`foreground`, `card-foreground`). An empty list means no variable.\\n- Groups (`base`, `semantic`, `color`, ...) are plain nesting with no `$type`.\\n\\n## What to do for common requests\\n\\n| Request | Edit | Then |\\n|---|---|---|\\n| Change a color, size, radius, or font value | The token's `$value` in the right context key (`$root` for every mode, `dark` for dark mode only) | Rebuild |\\n| A value should differ in dark mode | Add or edit the `dark` key on that token | Rebuild |\\n| New CSS variable | Add a token with `$type`, `$root.$value`, and an `exportName` (or reference an existing token) | Rebuild |\\n| Rename a CSS variable | Change the `exportName` entry; update every consumer of the old `--name` | Rebuild |\\n| New theme or brand context | Add the context to `bezel.json` `contexts` (name -> selector) and add that key to the tokens that differ | Rebuild |\\n| Change where files are generated | Edit `variablesOutput` / `contextsOutput` / `fontsOutput` in `bezel.json`; update the CSS import | Rebuild, delete the old outputs |\\n| \\\"Pull the latest tokens\\\" / \\\"sync from Bezel\\\" | See the next section | `bezel sync` rebuilds |\\n| \\\"Push my changes to Bezel\\\" / save local token edits back | Nothing by hand; follow \\\"Pushing changes back to Bezel\\\" | Sync, which updates the lockfile |\\n\\nFind the token for an existing variable by searching `design-tokens.json` for its name inside an `exportName` array.\\n\\n## Pulling the latest tokens from Bezel\\n\\n`bezel.json` `projectId` and `version` (`\\\"latest\\\"` or a published semver) say which Bezel project and snapshot this repo tracks. `design-tokens-lock.json` records the tokens and project revision this repo last synced or pushed, like `package-lock.json` next to `package.json`. Only `bezel sync` writes it.\\n\\nWith the Bezel MCP connected:\\n\\n1. Run `npx bezel diff`. If it lists local edits, stop and offer to push them first (next section). A lockfile problem it reports is fixed by this sync.\\n2. Call `get-design-tokens-file` with that `projectId` and `version`. Write the returned `lockfileContent` exactly as returned to `.bezel/sync.json`.\\n3. Run `npx bezel sync`. It checks the staged file, writes `design-tokens-lock.json` and then `design-tokens.json`, deletes the staged file, and rebuilds.\\n   - Exit code 2 means `design-tokens.json` has edits Bezel does not have. Show the message and offer to push them. Use `npx bezel sync --discard-local-edits` only when the user says to drop them.\\n   - `unknown command \\\"sync\\\"` means the installed `@bezel-labs/bezel-kit` is too old. Update it first.\\n\\nThe `sync-project` prompt walks through this, including linking a project when `projectId` is missing. Never pick a project or version yourself; ask when it is ambiguous.\\n\\nWithout the MCP: ask the user to download `design-tokens.json` from the project in the Bezel app and replace the file at the repo root, then rebuild. Pushing later needs a lockfile, so sync through the MCP when it becomes available.\\n\\n## Pushing changes back to Bezel\\n\\nNeeds the Bezel MCP. A push sends only your edits, as JSON Patch operations, the same way the Bezel app saves. Bezel applies them to the project's working tokens (`latest`) and keeps changes others made in the meantime. Publishing a version still happens in the Bezel app.\\n\\n1. Run `npx bezel diff --json`. `\\\"ok\\\": false` prints what to do (every lockfile problem is fixed by a sync). `\\\"operations\\\": []` means nothing to push.\\n2. If `bezel.json` `version` is a semver, tell the user the push updates the working project, not that pinned release.\\n3. Call `push-design-tokens` with `projectId`, the printed `operations` and `baseRevision` unchanged, and `version` as `trackedVersion`. If Bezel is still at `baseRevision`, it saves straight away; the user's request to push is the go-ahead.\\n4. `needs-confirmation`: Bezel changed since the last sync, so nothing was saved. Show `confirmationPrompt` to the user word for word and wait. Only after an explicit yes, call `push-design-tokens` again with the same arguments and `confirmed: true`. Silence, a question, or a different request means no push.\\n5. `invalid` or `blocked`: report and stop (`blocked` is a plan limit). `conflict`: the listed tokens changed in Bezel too; follow `nextStep`. `no-changes` with `alreadyApplied`: an earlier push saved these edits but the sync after it did not run; sync now. Themes the edits use that the project lacks are added by the push (`addedContexts`).\\n6. A push is not finished until the repo is synced. Sync as in the previous section, steps 2 and 3: `get-design-tokens-file`, write `lockfileContent` to `.bezel/sync.json`, run `npx bezel sync`. Your edits are already in Bezel, so the sync keeps them, pulls in anything others changed, and moves the lockfile to the new revision. Then tell the user to commit `design-tokens.json` and `design-tokens-lock.json` together.\\n\\n`preview-design-tokens-push` takes the same arguments and shows what a push would change without saving, for when the user asks first. The `push-project` prompt walks through this.\\n\\n## With the Bezel MCP connected\\n\\nPrefer small, targeted calls over reading the whole tokens file:\\n\\n- `get-project-manifest` first: groups, counts, types, contexts, no values.\\n- `query-tokens` to find tokens by group, type, name, or `exportName`; `get-token-by-path` for one token with every context value.\\n- `get-token-bundle` for a curated set per task (`theming-setup`, `button`, `card`, `form`, ...).\\n- `export-tokens` and `get-framework-overrides` to generate CSS, JS/TS objects, or Tailwind / shadcn / Mantine config from tokens.\\n- `contrast-check`, `color-convert`, `color-ramp`, `unit-convert` for deterministic math instead of estimating.\\n- `design-review` to check a component description against the tokens.\\n\\nSee `references/mcp-tools.md` for the full list and `references/bezel-json.md` for every config field.\\n\\n## Setting up a repo that is not on Bezel yet\\n\\nRun the `setup-project` tool (or the `/mcp__bezel__setup-project` prompt) and follow it; it installs `@bezel-labs/bezel-kit`, writes `bezel.json`, fetches the tokens, builds, and wires the CSS import. Do not improvise the steps.\\n\",\n    \"references/bezel-json.md\": \"# bezel.json reference\\n\\n`bezel.json` lives at the repo root (or the working directory `bezel build` runs in). `bezel build` loads it automatically; `bezel init` writes it. The tokens input is always `design-tokens.json` in that same directory and is not configurable.\\n\\n| Field | Default | Used by | Meaning |\\n|---|---|---|---|\\n| `projectId` | none | MCP | UUID of the Bezel project this repo tracks. Set with `npx bezel init --project <uuid>`. |\\n| `version` | `\\\"latest\\\"` | MCP | Which tokens snapshot to fetch: `\\\"latest\\\"` or a published semver such as `\\\"1.4.0\\\"`. Set with `--tokens-version`. |\\n| `variablesOutput` | `\\\"src/bezel/variables.css\\\"` | build | Generated CSS file. Import this from the app entry. |\\n| `contextsOutput` | none | build | When set, writes a TypeScript module exporting `CONTEXTS` (the context names). |\\n| `fontsOutput` | none | build | When set, writes a TypeScript module exporting `FONTS` (web fonts derived from the tokens). |\\n| `contexts` | `{ \\\"$root\\\": \\\":root\\\", \\\"dark\\\": \\\".dark\\\", \\\"light\\\": \\\".light\\\" }` | build | Context name -> CSS selector. The first entry is the base context and is emitted in full; the rest are override-only blocks. |\\n| `colorFormat` | `\\\"oklch\\\"` | build | `\\\"oklch\\\"` or `\\\"hex\\\"`. |\\n| `dimensionUnit` | `\\\"preserve\\\"` | build | `\\\"preserve\\\"` keeps authored units; `\\\"rem\\\"` converts `px` to `rem`. |\\n| `nameExtension` | `\\\"com.bezel.app\\\"` | build | The `$extensions` key that holds `exportName`. Only change for files exported before the 0.3.0 rename. |\\n| `includeAll` | `false` | build | Also emit a variable for every token without an `exportName`, named by its kebab-cased path (`--base-color-primary-500`). |\\n| `write` | `true` | build | `false` returns the CSS without writing files (programmatic use). |\\n| `gitignore` | `true` | build | Maintain a `# bezel:start` ... `# bezel:end` block in `.gitignore` listing the generated outputs. |\\n| `gitignorePath` | `\\\".gitignore\\\"` | build | Which `.gitignore` to manage. |\\n| `cwd` | process cwd | build | Base directory paths resolve against. |\\n\\n`projectId` and `version` are ignored by `bezel build`; everything else is ignored by the MCP. The synced revision lives in `design-tokens-lock.json`, not here.\\n\\n## design-tokens-lock.json\\n\\nCommitted next to `design-tokens.json`, like `package-lock.json` next to `package.json`. It records the tokens and project revision this repo last synced or pushed: `lockfileVersion`, `projectId`, `version`, `revision`, and `tokens`. `bezel diff` compares `design-tokens.json` against it to find local edits. Only `bezel sync` writes it, after every sync and every push; never edit it. `bezel init --project` deletes a lockfile that belongs to a different project.\\n\\n## CLI\\n\\n```\\nbezel init [--project <uuid>] [--tokens-version <v>] [--dir <path>] ...   create or update bezel.json\\nbezel build [--stdout] [--no-gitignore] ...                                generate the outputs (default command)\\nbezel install-mcp [--client <name>]                                        connect an AI coding tool to the Bezel MCP\\nbezel install-skills [--client <name>] [--no-agents-md]                    install this skill into the repo\\nbezel diff [--json]                                                        local edits vs design-tokens-lock.json (--json: JSON Patch operations for a push)\\nbezel sync [--discard-local-edits]                                         apply .bezel/sync.json: write the lockfile and design-tokens.json, then build\\n```\\n\\n`bezel sync` exits with code 2 when `design-tokens.json` has edits Bezel does not have; other problems exit with 1.\\n\\n`bezel init` on an existing `bezel.json` with `--project` or `--tokens-version` updates only those keys. Any other re-run leaves the file alone unless `--force` is passed, which agents must not do.\\n\",\n    \"references/mcp-tools.md\": \"# Bezel MCP quick reference\\n\\nRemote server at `https://mcp.bezel.new/mcp` (Streamable HTTP, OAuth). The server returns data and instructions; the coding agent performs every local file edit and command. Project-scoped tools take the `projectId` from `bezel.json` or from `find-project`.\\n\\n## Guided workflows\\n\\n| Tool / prompt | Use |\\n|---|---|\\n| `setup-project` (tool and prompt) | Resumable setup: install bezel-kit, link a project, write `bezel.json`, fetch tokens, build, wire the CSS import, optional Crystal live preview. |\\n| `sync-project` (prompt) | Refresh `design-tokens.json` and `design-tokens-lock.json` from the linked project and version through `bezel sync`. Offers to push local edits first instead of overwriting them. |\\n| `push-project` (prompt) | Diff and push the repo's token edits to the linked project (asking the user first only when Bezel changed), then sync so `design-tokens-lock.json` moves to the new revision. |\\n| `safe-usage-guide` (prompt) | Context-budget rules: manifest first, targeted queries, cite token paths. |\\n| `manifest-first-workflow`, `context-resolution` (prompts) | Recommended reading order and how contexts resolve. |\\n| `get-agent-guide` (tool) | Returns this skill's text when the repo has no local copy. |\\n\\n## Discovery\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `find-project` | `query?` | All owned projects (name + id), or one project resolved from a name or UUID. |\\n| `get-project-manifest` | `projectId` | Groups, token counts, types, contexts. No values. Call this first. |\\n\\n## Repo sync\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `get-design-tokens-file` | `projectId`, `version?` | `lockfileContent`: the full `design-tokens-lock.json` text (tokens + `revision`). Write it to `.bezel/sync.json` and run `npx bezel sync`. Unknown version -> list of available versions. |\\n| `preview-design-tokens-push` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?` | Checks the edits from `npx bezel diff --json` against the working tokens: plan-limit problems, `conflict` (tokens edited here and in Bezel), themes the edits add (`addedContexts`), `behind` when Bezel moved on (those changes are kept), and a `confirmationPrompt`. Saves nothing; optional, for when the user wants to see a push first. |\\n| `push-design-tokens` | `projectId`, `operations`, `baseRevision?`, `trackedVersion?`, `confirmed?` | Saves the edits as a new revision when Bezel is still at `baseRevision`. If Bezel changed, saves nothing and returns `needs-confirmation` with a `confirmationPrompt`; call again with `confirmed: true` only after the user says yes. Returns the new `revision`. Sync right after it so the lockfile moves to that revision. |\\n\\n## Reading tokens\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `query-tokens` | `projectId`, `groupPath?`, `tokenType?`, `search?`, `exportName?`, `contextKey?`, `resolveAliases?` | Filtered tokens. |\\n| `get-token-by-path` | `projectId`, `tokenPath`, `contextKey?`, `resolveAliases?` | One token with every context value and alias detail. |\\n| `get-token-bundle` | `projectId`, `intent` | Curated set: `theming-setup`, `button`, `card`, `input`, `form`, `auth-page`, `dashboard-shell`. |\\n| `get-project-contexts` | `projectId` | Context groups and values (theme modes, platforms, brands). |\\n| `resolve-context` | `projectId`, `contextGroup`, `contextValue` | Canonical context value or a structured error. |\\n\\n## Generating code\\n\\n| Tool | Parameters | Returns |\\n|---|---|---|\\n| `export-tokens` | `projectId`, `format` (`css-variables`, `js-object`, `ts-object`), filters, `prefix?`, `includeAll?` | Generated code with aliases resolved. |\\n| `get-framework-overrides` | `projectId`, `framework` (`tailwind`, `shadcn`, `mantine`), `version?`, filters | Framework config derived from the tokens. |\\n\\n## Color and unit math (deterministic)\\n\\n| Tool | Parameters |\\n|---|---|\\n| `contrast-check` | `foreground`, `background` -> WCAG ratio, grade, recommendations |\\n| `color-convert` | `color`, `targetFormat`, `manipulation?`, `mixColor?` |\\n| `color-ramp` | `baseColor`, `steps`, `endColor?`, `colorSpace?` |\\n| `unit-convert` | `value`, `fromUnit`, `toUnit`, `rootFontSize?`, `parentFontSize?` |\\n\\n## Review and history\\n\\n| Tool | Parameters |\\n|---|---|\\n| `design-review` | `projectId`, `componentDescription`, `tokenPathsUsed?`, `contextKey?` |\\n| `get-chat-history` | `projectId` |\\n| `search-chat-history` | `projectId`, `query` |\\n\\n## Resources\\n\\n- `bezel://projects`: your projects with ids and names.\\n- `bezel://agent-guide`: this skill's text.\\n\"\n  },\n  agentsMdBlock: \"## Bezel design tokens\\n\\n- `design-tokens.json` at the repo root is the source for every design token. Edit it to change a color, size, font, or radius, or to add a CSS variable (add an `exportName` under `$extensions[\\\"com.bezel.app\\\"]`).\\n- Files under the Bezel output folder (`variablesOutput`, `contextsOutput`, `fontsOutput` in `bezel.json`; `src/bezel/` by default) are generated. Never edit them; they are overwritten on every build.\\n- After changing `design-tokens.json` or `bezel.json`, run `npm run tokens` (or `npx bezel build`) and check the outputs were rewritten.\\n- Dark mode and other contexts are keys inside each token (`$root`, `dark`, `light`). Add a value under the context key instead of writing a CSS override.\\n- The Bezel app is the source of truth. `design-tokens-lock.json` records what was last synced or pushed; never edit it, and commit it together with `design-tokens.json`. `npx bezel diff` lists local edits that are not in Bezel yet.\\n- Sync through the Bezel MCP: write `get-design-tokens-file`'s `lockfileContent` to `.bezel/sync.json`, then run `npx bezel sync` (it writes both files and refuses to drop unpushed edits). To push (only when asked), run `npx bezel diff --json`, call `push-design-tokens` with its operations, then sync to update the lockfile. If it returns `needs-confirmation` (Bezel changed meanwhile), show the confirmation prompt word for word and call again with `confirmed: true` only after the user says yes.\\n- Never run `bezel init --force`; it discards the existing `bezel.json`. Use `--project` or `--tokens-version` to update a single key.\\n- Full guidance: the `bezel` skill in `.claude/skills/bezel/SKILL.md` or `.agents/skills/bezel/SKILL.md`.\",\n  summary: \"Use when the repo has bezel.json or design-tokens.json and the task touches design tokens, theme colors, spacing, typography, radii, CSS variables, dark mode, or files under the Bezel output folder (src/bezel by default). Edit design-tokens.json, never the generated variables.css / contexts.ts / fonts.ts, then run the tokens build. Also covers pulling the latest tokens from the Bezel app, pushing local token edits back to Bezel when the user asks, and using the Bezel MCP tools.\\n\\n## Hard rules\\n\\n1. Never edit a generated file. They start with `/* Generated by bezel — do not edit by hand. */` and live at the paths named in `bezel.json` (`variablesOutput`, `contextsOutput`, `fontsOutput`; default folder `src/bezel/`). `bezel build` overwrites them without asking and they are gitignored.\\n2. To change a token value or add a variable, edit `design-tokens.json`, then rebuild. Never hand-write the CSS variable.\\n3. After any change to `design-tokens.json` or `bezel.json`, run the tokens build: `npm run tokens` when that script exists, otherwise `npx bezel build` (use the repo's package manager runner). Confirm the outputs were rewritten before finishing.\\n4. Only tokens with an `exportName` become CSS variables unless `bezel.json` sets `\\\"includeAll\\\": true`. Adding a token without an `exportName` produces no variable.\\n5. Never pass `--force` to `bezel init`; it discards the existing `bezel.json`. `--project` and `--tokens-version` update their own keys without it.\\n6. Local edits to `design-tokens.json` are not in Bezel until they are pushed. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, then `push-design-tokens` with its operations, then a sync. Push only when the user asks to push, never from a \\\"sync\\\" or \\\"pull\\\" request. When Bezel changed since the last sync, the push returns `needs-confirmation`: show its `confirmationPrompt` word for word and pass `confirmed: true` only after the user says yes.\\n7. Never write or edit `design-tokens-lock.json`, and never write a synced `design-tokens.json` from MCP output yourself. Only `bezel sync` writes them, after every sync and every push, so the two files always agree. Commit both files together.\",\n}\n"],"mappings":";AAgBO,IAAM,cAA0B;AAAA,EACrC,MAAM;AAAA,EACN,aAAa;AAAA,EACb,OAAO;AAAA,IACL,YAAY;AAAA,IACZ,4BAA4B;AAAA,IAC5B,2BAA2B;AAAA,EAC7B;AAAA,EACA,eAAe;AAAA,EACf,SAAS;AACX;","names":[]}

package/dist/{chunk-DXZXDPQ6.js → chunk-N57FDE2K.js}

@@ -371,6 +371,112 @@ export type FontDef = { family: string; weights: number[] }
 `;
 }
 
+// src/lockfile.ts
+var LOCKFILE_NAME = "design-tokens-lock.json";
+var LOCKFILE_VERSION = 1;
+var SYNC_STAGING_PATH = ".bezel/sync.json";
+function buildLockfile(input) {
+  return {
+    lockfileVersion: LOCKFILE_VERSION,
+    projectId: input.projectId,
+    version: input.version,
+    revision: input.revision,
+    tokens: input.tokens
+  };
+}
+function serializeLockfile(lockfile) {
+  return `${JSON.stringify(lockfile, null, 2)}
+`;
+}
+function serializeTokensFile(tokens) {
+  return `${JSON.stringify(tokens, null, 2)}
+`;
+}
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function parseLockfile(text, name = LOCKFILE_NAME) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    const merged = /^(<<<<<<<|=======|>>>>>>>)/m.test(text);
+    return {
+      ok: false,
+      reason: "invalid-json",
+      message: merged ? `${name} has git merge conflict markers. Do not resolve them by hand; sync from Bezel to rewrite it.` : `${name} is not valid JSON. Sync from Bezel to rewrite it.`
+    };
+  }
+  if (!isRecord(parsed) || parsed["lockfileVersion"] !== LOCKFILE_VERSION || typeof parsed["projectId"] !== "string" || typeof parsed["version"] !== "string" || typeof parsed["revision"] !== "number" || !isRecord(parsed["tokens"])) {
+    return {
+      ok: false,
+      reason: "invalid-shape",
+      message: `${name} is not a version ${LOCKFILE_VERSION} Bezel lockfile. Sync from Bezel to rewrite it.`
+    };
+  }
+  return { ok: true, lockfile: parsed };
+}
+
+// src/patch-applied.ts
+var MISSING = /* @__PURE__ */ Symbol("missing");
+var decodeSegment = (segment) => segment.replace(/~1/g, "/").replace(/~0/g, "~");
+function valueAt(document, pointer) {
+  if (pointer === "") return document;
+  let node = document;
+  for (const raw of pointer.split("/").slice(1)) {
+    const segment = decodeSegment(raw);
+    if (Array.isArray(node)) {
+      const index = Number(segment);
+      if (!Number.isInteger(index) || index < 0 || index >= node.length) return MISSING;
+      node = node[index];
+    } else if (typeof node === "object" && node !== null && Object.prototype.hasOwnProperty.call(node, segment)) {
+      node = node[segment];
+    } else {
+      return MISSING;
+    }
+  }
+  return node;
+}
+function jsonEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, i) => jsonEqual(item, b[i]));
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every(
+    (key) => Object.prototype.hasOwnProperty.call(b, key) && jsonEqual(a[key], b[key])
+  );
+}
+function isOperationApplied(document, operation) {
+  switch (operation.op) {
+    case "test":
+      return true;
+    case "add":
+    case "replace": {
+      const current = valueAt(document, operation.path);
+      return current !== MISSING && jsonEqual(current, operation.value);
+    }
+    case "remove":
+      return valueAt(document, operation.path) === MISSING;
+    case "copy": {
+      const target = valueAt(document, operation.path);
+      return target !== MISSING && jsonEqual(target, valueAt(document, operation.from ?? ""));
+    }
+    case "move":
+      return valueAt(document, operation.path) !== MISSING && (operation.from === void 0 || valueAt(document, operation.from) === MISSING);
+    default:
+      return false;
+  }
+}
+function unappliedOperations(document, operations) {
+  return operations.filter((operation) => operation.op !== "test" && !isOperationApplied(document, operation));
+}
+function isPatchApplied(document, operations) {
+  return unappliedOperations(document, operations).length === 0;
+}
+
 // src/index.ts
 function tokensToCss(tokens, options = {}) {
   return emitCss(tokens, resolveCssOptions(options));
@@ -394,6 +500,17 @@ export {
   formatContextsModule,
   getFonts,
   formatFontsModule,
+  LOCKFILE_NAME,
+  LOCKFILE_VERSION,
+  SYNC_STAGING_PATH,
+  buildLockfile,
+  serializeLockfile,
+  serializeTokensFile,
+  parseLockfile,
+  jsonEqual,
+  isOperationApplied,
+  unappliedOperations,
+  isPatchApplied,
   tokensToCss
 };
-//# sourceMappingURL=chunk-DXZXDPQ6.js.map
+//# sourceMappingURL=chunk-N57FDE2K.js.map