@bezel-labs/bezel-kit 0.8.1 → 0.10.0

package/dist/cli.cjs

@@ -24,15 +24,15 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli.ts
-var import_node_fs2 = require("fs");
-var import_promises5 = require("fs/promises");
+var import_node_fs3 = require("fs");
+var import_promises6 = require("fs/promises");
 var import_node_url = require("url");
 var import_node_util = require("util");
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 
 // src/node.ts
-var import_promises2 = require("fs/promises");
-var import_node_path3 = require("path");
+var import_promises3 = require("fs/promises");
+var import_node_path4 = require("path");
 
 // src/config.ts
 var import_node_path = require("path");
@@ -462,23 +462,314 @@ function mergeGitignore(existing, entries) {
   return mergeManagedBlock(existing, entries, { start: START, end: END });
 }
 
+// src/lockfile.ts
+var LOCKFILE_NAME = "design-tokens-lock.json";
+var LOCKFILE_VERSION = 1;
+var SYNC_STAGING_PATH = ".bezel/sync.json";
+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));
+}
+
 // 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 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 after a preview and confirmation, 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 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\nNothing in this repo pushes back to Bezel. A change that must survive the next sync belongs in the Bezel app.\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 overwritten by the next sync from Bezel. Tell the user when a change should be made in the Bezel app instead, and never silently sync over their local edits.\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\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.\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), 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\nWarn before overwriting a `design-tokens.json` that has local edits.\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.\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, then rebuild. |\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 and version. Unknown version -> list of available versions. |\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 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     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 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. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, `preview-design-tokens-push` with its operations, showing the `confirmationPrompt` word for word, `push-design-tokens` only after the user says yes, then a sync. Never push without that confirmation, and never push from a "sync" or "pull" request.\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 `preview-design-tokens-push` with `projectId`, the printed `operations` and `baseRevision` unchanged, and `version` as `trackedVersion`. It saves nothing.\n4. `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`).\n5. `ready`: show `confirmationPrompt` to the user word for word and wait. Do not push on silence, a question, or a different request.\n6. After an explicit yes, call `push-design-tokens` with the same `projectId`, `operations`, and `baseRevision`.\n7. 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\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| `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, preview, confirm with the user, and push the repo's token edits to the linked project, 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` to show verbatim. Saves nothing. |\n| `push-design-tokens` | `projectId`, `operations`, `baseRevision?` | Saves the previewed edits as a new revision. Call only after the user confirms the preview. 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 token edits are replaced by the next sync (`get-design-tokens-file` via the Bezel MCP, or a download from the app), so tell the user when a change should be made in Bezel.\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 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 overwritten by the next sync from Bezel. Tell the user when a change should be made in the Bezel app instead, and never silently sync over their local edits.'
+  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, run `npx bezel diff --json`, call `preview-design-tokens-push` with its operations, show the confirmation prompt word for word, call `push-design-tokens` only after the user says yes, then sync to update the lockfile.\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. `npx bezel diff` lists them. Never sync over them silently: offer to push them first. Pushing means `npx bezel diff --json`, `preview-design-tokens-push` with its operations, showing the `confirmationPrompt` word for word, `push-design-tokens` only after the user says yes, then a sync. Never push without that confirmation, and never push from a "sync" or "pull" request.\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.'
 };
 
 // src/init.ts
+var import_node_fs2 = require("fs");
+var import_promises2 = require("fs/promises");
+var import_node_path3 = require("path");
+
+// src/tokens-sync.ts
 var import_node_fs = require("fs");
 var import_promises = require("fs/promises");
 var import_node_path2 = require("path");
+var import_fast_json_patch = __toESM(require("fast-json-patch"), 1);
+var { compare } = import_fast_json_patch.default;
+var SYNC_HINT = 'Sync from Bezel (ask your agent to "sync my Bezel tokens").';
+async function readLink(cwd) {
+  const path = (0, import_node_path2.resolve)(cwd, DEFAULT_CONFIG_FILE);
+  if (!(0, import_node_fs.existsSync)(path)) {
+    return { ok: false, reason: "no-config", message: `No ${DEFAULT_CONFIG_FILE} here. Run "bezel init --project <uuid>" first.` };
+  }
+  let config;
+  try {
+    config = JSON.parse(await (0, import_promises.readFile)(path, "utf8"));
+  } catch {
+    return { ok: false, reason: "no-config", message: `${DEFAULT_CONFIG_FILE} is not valid JSON.` };
+  }
+  if (typeof config.projectId !== "string" || config.projectId === "") {
+    return {
+      ok: false,
+      reason: "no-project",
+      message: `${DEFAULT_CONFIG_FILE} has no projectId. Link the repo with "bezel init --project <uuid>".`
+    };
+  }
+  const version = typeof config.version === "string" && config.version !== "" ? config.version : "latest";
+  return { ok: true, link: { projectId: config.projectId, version } };
+}
+async function readTokensFile(cwd) {
+  const path = (0, import_node_path2.resolve)(cwd, DEFAULT_INPUT);
+  if (!(0, import_node_fs.existsSync)(path)) {
+    return { ok: false, reason: "no-tokens-file", message: `No ${DEFAULT_INPUT} here. ${SYNC_HINT}` };
+  }
+  try {
+    const parsed = JSON.parse(await (0, import_promises.readFile)(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("not an object");
+    return { ok: true, tokens: parsed };
+  } catch {
+    return {
+      ok: false,
+      reason: "tokens-file-invalid",
+      message: `${DEFAULT_INPUT} is not a JSON object. Fix the file (or sync from Bezel to replace it).`
+    };
+  }
+}
+async function readCurrentLockfile(cwd) {
+  const path = (0, import_node_path2.resolve)(cwd, LOCKFILE_NAME);
+  if (!(0, import_node_fs.existsSync)(path)) return { ok: true, lockfile: null };
+  const parsed = parseLockfile(await (0, import_promises.readFile)(path, "utf8"));
+  if (parsed.ok === false) return { ok: false, reason: "lockfile-invalid", message: parsed.message };
+  return { ok: true, lockfile: parsed.lockfile };
+}
+function checkLockMatchesLink(lockfile, link, name) {
+  if (lockfile.projectId !== link.projectId) {
+    return {
+      ok: false,
+      reason: "project-mismatch",
+      message: `${name} is for project ${lockfile.projectId}, but ${DEFAULT_CONFIG_FILE} links ${link.projectId}. ${SYNC_HINT}`
+    };
+  }
+  if (lockfile.version !== link.version) {
+    return {
+      ok: false,
+      reason: "version-mismatch",
+      message: `${name} holds version "${lockfile.version}", but ${DEFAULT_CONFIG_FILE} tracks "${link.version}". ${SYNC_HINT}`
+    };
+  }
+  return null;
+}
+function changedPaths(operations) {
+  const paths = /* @__PURE__ */ new Set();
+  for (const operation of operations) {
+    if (operation.op === "test") continue;
+    const segments = [];
+    for (const raw of operation.path.split("/").slice(1)) {
+      const segment = raw.replace(/~1/g, "/").replace(/~0/g, "~");
+      if (segment.startsWith("$")) break;
+      segments.push(segment);
+    }
+    paths.add(segments.length > 0 ? segments.join(".") : "(root)");
+  }
+  return [...paths];
+}
+async function diffTokens({ cwd = process.cwd() } = {}) {
+  const link = await readLink(cwd);
+  if (link.ok === false) return link;
+  const current = await readCurrentLockfile(cwd);
+  if (current.ok === false) return current;
+  if (current.lockfile === null) {
+    return {
+      ok: false,
+      reason: "no-lockfile",
+      message: `No ${LOCKFILE_NAME} yet, so local edits cannot be told apart from Bezel's tokens. ${SYNC_HINT}`
+    };
+  }
+  const mismatch = checkLockMatchesLink(current.lockfile, link.link, LOCKFILE_NAME);
+  if (mismatch) return mismatch;
+  const local = await readTokensFile(cwd);
+  if (local.ok === false) return local;
+  const operations = compare(current.lockfile.tokens, local.tokens, true);
+  return {
+    ok: true,
+    projectId: current.lockfile.projectId,
+    version: current.lockfile.version,
+    baseRevision: current.lockfile.revision,
+    operations
+  };
+}
+async function syncFromStaging({
+  cwd = process.cwd(),
+  discardLocalEdits = false
+} = {}) {
+  const stagingPath = (0, import_node_path2.resolve)(cwd, SYNC_STAGING_PATH);
+  if (!(0, import_node_fs.existsSync)(stagingPath)) {
+    return {
+      ok: false,
+      reason: "no-staging",
+      message: `Nothing to sync: ${SYNC_STAGING_PATH} is missing. Write the "lockfileContent" from the Bezel MCP's get-design-tokens-file there first.`
+    };
+  }
+  const incoming = parseLockfile(await (0, import_promises.readFile)(stagingPath, "utf8"), SYNC_STAGING_PATH);
+  if (incoming.ok === false) {
+    return {
+      ok: false,
+      reason: "staging-invalid",
+      message: `${incoming.message.replace(/ Sync from Bezel to rewrite it\.$/, "")} Write the "lockfileContent" from get-design-tokens-file to ${SYNC_STAGING_PATH} exactly as returned, then run "bezel sync" again.`
+    };
+  }
+  const next = incoming.lockfile;
+  const link = await readLink(cwd);
+  if (link.ok === false) return link;
+  const mismatch = checkLockMatchesLink(next, link.link, SYNC_STAGING_PATH);
+  if (mismatch) {
+    return {
+      ...mismatch,
+      message: `${SYNC_STAGING_PATH} is for project ${next.projectId} version "${next.version}", but ${DEFAULT_CONFIG_FILE} links ${link.link.projectId} version "${link.link.version}". Fetch the tokens for the linked project and version, or relink with "bezel init --project <uuid> --tokens-version <v>".`
+    };
+  }
+  const tokensPath = (0, import_node_path2.resolve)(cwd, DEFAULT_INPUT);
+  let discardedEdits = 0;
+  let tokensChanged = true;
+  if ((0, import_node_fs.existsSync)(tokensPath)) {
+    const local = await readTokensFile(cwd);
+    if (local.ok === true) {
+      tokensChanged = !jsonEqual(local.tokens, next.tokens);
+      const current = await readCurrentLockfile(cwd);
+      const base = current.ok === true && current.lockfile !== null && checkLockMatchesLink(current.lockfile, link.link, LOCKFILE_NAME) === null ? current.lockfile : null;
+      if (tokensChanged) {
+        if (base === null) {
+          if (!discardLocalEdits) {
+            return {
+              ok: false,
+              reason: "unknown-local-edits",
+              message: `${DEFAULT_INPUT} differs from Bezel's tokens and there is no usable ${LOCKFILE_NAME} to tell local edits from older Bezel tokens. If the file has no edits worth keeping, run "bezel sync --discard-local-edits" to replace it.`
+            };
+          }
+        } else {
+          const localEdits = compare(base.tokens, local.tokens, true);
+          const unpushed = unappliedOperations(next.tokens, localEdits);
+          if (unpushed.length > 0 && !discardLocalEdits) {
+            const paths = changedPaths(unpushed);
+            return {
+              ok: false,
+              reason: "unpushed-edits",
+              unpushedPaths: paths,
+              message: `${DEFAULT_INPUT} has ${unpushed.length} local ${unpushed.length === 1 ? "edit" : "edits"} Bezel does not have (${paths.slice(0, 10).join(", ")}${paths.length > 10 ? ", ..." : ""}). Push them to Bezel first, or run "bezel sync --discard-local-edits" to drop them.`
+            };
+          }
+          discardedEdits = unpushed.length;
+        }
+      }
+    } else if (!discardLocalEdits) {
+      return {
+        ...local,
+        message: `${local.message.replace(/ \(or sync from Bezel to replace it\)/, "")} Or run "bezel sync --discard-local-edits" to replace it with Bezel's tokens.`
+      };
+    }
+  }
+  await (0, import_promises.writeFile)((0, import_node_path2.resolve)(cwd, LOCKFILE_NAME), serializeLockfile(next), "utf8");
+  if (tokensChanged) await (0, import_promises.writeFile)(tokensPath, serializeTokensFile(next.tokens), "utf8");
+  await (0, import_promises.rm)(stagingPath, { force: true });
+  return { ok: true, projectId: next.projectId, version: next.version, revision: next.revision, tokensChanged, discardedEdits };
+}
+async function removeLockfileForOtherProject(cwd, projectId) {
+  const path = (0, import_node_path2.resolve)(cwd, LOCKFILE_NAME);
+  if (!(0, import_node_fs.existsSync)(path)) return false;
+  try {
+    const parsed = JSON.parse(await (0, import_promises.readFile)(path, "utf8"));
+    if (parsed.projectId === projectId) return false;
+  } catch {
+  }
+  await (0, import_promises.rm)(path, { force: true });
+  return true;
+}
+
+// src/init.ts
 var isUuid = (value) => /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
 var isTokensVersion = (value) => value === "latest" || /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?$/.test(value);
 var joinPath = (dir, file) => dir === "" ? file : `${dir.replace(/\/+$/, "")}/${file}`;
@@ -492,11 +783,11 @@ async function initConfig(options = {}) {
     );
   }
   const cwd = options.cwd ?? process.cwd();
-  const toAbs = (p) => (0, import_node_path2.isAbsolute)(p) ? p : (0, import_node_path2.resolve)(cwd, p);
+  const toAbs = (p) => (0, import_node_path3.isAbsolute)(p) ? p : (0, import_node_path3.resolve)(cwd, p);
   const configPath = toAbs(DEFAULT_CONFIG_FILE);
-  const hasTokensFile = (0, import_node_fs.existsSync)(toAbs(DEFAULT_INPUT));
-  const isTypeScript = (0, import_node_fs.existsSync)(toAbs("tsconfig.json"));
-  const hasSrc = (0, import_node_fs.existsSync)(toAbs("src"));
+  const hasTokensFile = (0, import_node_fs2.existsSync)(toAbs(DEFAULT_INPUT));
+  const isTypeScript = (0, import_node_fs2.existsSync)(toAbs("tsconfig.json"));
+  const hasSrc = (0, import_node_fs2.existsSync)(toAbs("src"));
   const outputDir = options.outputDir ?? (hasSrc ? DEFAULT_OUTPUT_DIR : FALLBACK_OUTPUT_DIR);
   const wantsContexts = options.contextsOutput !== void 0 || (options.contexts ?? isTypeScript);
   const wantsFonts = options.fontsOutput !== void 0 || (options.fonts ?? isTypeScript);
@@ -513,21 +804,24 @@ async function initConfig(options = {}) {
   if (options.colorFormat) config.colorFormat = options.colorFormat;
   if (options.dimensionUnit) config.dimensionUnit = options.dimensionUnit;
   if (options.includeAll) config.includeAll = true;
-  if ((0, import_node_fs.existsSync)(configPath) && !options.force) {
+  if ((0, import_node_fs2.existsSync)(configPath) && !options.force) {
     const wantsLinkUpdate = options.projectId !== void 0 || options.version !== void 0;
     if (!wantsLinkUpdate) {
       return { configPath, config, written: false, updated: false, hasTokensFile, isTypeScript };
     }
-    const existing = JSON.parse(await (0, import_promises.readFile)(configPath, "utf8"));
+    const existing = JSON.parse(await (0, import_promises2.readFile)(configPath, "utf8"));
+    delete existing.revision;
     const { projectId: previousProjectId, version: previousVersion, ...rest } = existing;
     const merged = {};
     const projectId = options.projectId ?? previousProjectId;
     if (projectId !== void 0) merged.projectId = projectId;
     merged.version = options.version ?? previousVersion ?? "latest";
     Object.assign(merged, rest);
-    await (0, import_promises.writeFile)(configPath, `${JSON.stringify(merged, null, 2)}
+    await (0, import_promises2.writeFile)(configPath, `${JSON.stringify(merged, null, 2)}
 `, "utf8");
+    const removedLockfile2 = projectId !== void 0 ? await removeLockfileForOtherProject(cwd, projectId) : false;
     return {
+      removedLockfile: removedLockfile2,
       configPath,
       config: merged,
       written: true,
@@ -538,13 +832,14 @@ async function initConfig(options = {}) {
       isTypeScript
     };
   }
-  await (0, import_promises.writeFile)(configPath, `${JSON.stringify(config, null, 2)}
+  await (0, import_promises2.writeFile)(configPath, `${JSON.stringify(config, null, 2)}
 `, "utf8");
-  return { configPath, config, written: true, updated: false, hasTokensFile, isTypeScript };
+  const removedLockfile = config.projectId !== void 0 ? await removeLockfileForOtherProject(cwd, config.projectId) : false;
+  return { configPath, config, written: true, updated: false, removedLockfile, hasTokensFile, isTypeScript };
 }
 async function readPackageScripts(cwd) {
   try {
-    const raw = await (0, import_promises.readFile)((0, import_node_path2.resolve)(cwd, "package.json"), "utf8");
+    const raw = await (0, import_promises2.readFile)((0, import_node_path3.resolve)(cwd, "package.json"), "utf8");
     const parsed = JSON.parse(raw);
     return parsed.scripts ?? {};
   } catch {
@@ -557,7 +852,7 @@ async function generateVariablesCss(options = {}) {
   const resolved = resolveOptions(options);
   let raw;
   try {
-    raw = await (0, import_promises2.readFile)(resolved.inputPath, "utf8");
+    raw = await (0, import_promises3.readFile)(resolved.inputPath, "utf8");
   } catch (err) {
     throw new Error(
       `bezel: could not read tokens file at "${resolved.inputPath}". A "design-tokens.json" file must exist at the project root.
@@ -573,17 +868,17 @@ ${err.message}`);
   }
   const css = emitCss(tokens, resolved);
   if (resolved.write) {
-    await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(resolved.variablesOutputPath), { recursive: true });
-    await (0, import_promises2.writeFile)(resolved.variablesOutputPath, css, "utf8");
+    await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(resolved.variablesOutputPath), { recursive: true });
+    await (0, import_promises3.writeFile)(resolved.variablesOutputPath, css, "utf8");
     if (resolved.contextsOutput) {
       const contextsModule = formatContextsModule(getContexts(tokens));
-      await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(resolved.contextsOutput), { recursive: true });
-      await (0, import_promises2.writeFile)(resolved.contextsOutput, contextsModule, "utf8");
+      await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(resolved.contextsOutput), { recursive: true });
+      await (0, import_promises3.writeFile)(resolved.contextsOutput, contextsModule, "utf8");
     }
     if (resolved.fontsOutput) {
       const fontsModule = formatFontsModule(getFonts(tokens));
-      await (0, import_promises2.mkdir)((0, import_node_path3.dirname)(resolved.fontsOutput), { recursive: true });
-      await (0, import_promises2.writeFile)(resolved.fontsOutput, fontsModule, "utf8");
+      await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(resolved.fontsOutput), { recursive: true });
+      await (0, import_promises3.writeFile)(resolved.fontsOutput, fontsModule, "utf8");
     }
     if (resolved.gitignore) {
       await updateGitignore(resolved);
@@ -592,15 +887,17 @@ ${err.message}`);
   return css;
 }
 async function updateGitignore(resolved) {
-  const dir = (0, import_node_path3.dirname)(resolved.gitignorePath);
+  const dir = (0, import_node_path4.dirname)(resolved.gitignorePath);
   const outputs = [
     resolved.variablesOutputPath,
     resolved.contextsOutput,
-    resolved.fontsOutput
+    resolved.fontsOutput,
+    // The MCP's sync payload is a temporary hand-off file; the lockfile itself is committed.
+    (0, import_node_path4.resolve)((0, import_node_path4.dirname)(resolved.inputPath), SYNC_STAGING_PATH)
   ].filter((p) => p !== null);
   const entries = [];
   for (const output of outputs) {
-    const rel = (0, import_node_path3.relative)(dir, output);
+    const rel = (0, import_node_path4.relative)(dir, output);
     if (rel === "" || rel.startsWith("..")) {
       process.stderr.write(
         `bezel: skipping .gitignore entry for "${output}" \u2014 outside ${resolved.gitignorePath}
@@ -608,29 +905,29 @@ async function updateGitignore(resolved) {
       );
       continue;
     }
-    entries.push(`/${rel.split(import_node_path3.sep).join("/")}`);
+    entries.push(`/${rel.split(import_node_path4.sep).join("/")}`);
   }
   if (entries.length === 0) return;
   let existing = "";
   try {
-    existing = await (0, import_promises2.readFile)(resolved.gitignorePath, "utf8");
+    existing = await (0, import_promises3.readFile)(resolved.gitignorePath, "utf8");
   } catch {
   }
   const next = mergeGitignore(existing, entries);
   if (next !== existing) {
-    await (0, import_promises2.mkdir)(dir, { recursive: true });
-    await (0, import_promises2.writeFile)(resolved.gitignorePath, next, "utf8");
+    await (0, import_promises3.mkdir)(dir, { recursive: true });
+    await (0, import_promises3.writeFile)(resolved.gitignorePath, next, "utf8");
   }
 }
 
 // src/install-mcp.ts
 var import_node_child_process = require("child_process");
-var import_promises4 = require("fs/promises");
-var import_node_path5 = require("path");
+var import_promises5 = require("fs/promises");
+var import_node_path6 = require("path");
 
 // src/install-skills.ts
-var import_promises3 = require("fs/promises");
-var import_node_path4 = require("path");
+var import_promises4 = require("fs/promises");
+var import_node_path5 = require("path");
 var SKILL_CLIENTS = ["claude-code", "codex", "cursor", "all"];
 var AGENTS_MD_START = "<!-- bezel:start (generated by bezel install-skills \u2014 do not edit) -->";
 var AGENTS_MD_END = "<!-- bezel:end -->";
@@ -649,50 +946,50 @@ function mergeAgentsMd(existing) {
 }
 async function readIfExists(path) {
   try {
-    return await (0, import_promises3.readFile)(path, "utf8");
+    return await (0, import_promises4.readFile)(path, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") return void 0;
     throw error;
   }
 }
 async function writeManaged(cwd, path, content, result) {
-  const rel = (0, import_node_path4.relative)(cwd, path);
+  const rel = (0, import_node_path5.relative)(cwd, path);
   const existing = await readIfExists(path);
   if (existing === content) {
     result.unchanged.push(rel);
     return;
   }
-  await (0, import_promises3.mkdir)((0, import_node_path4.dirname)(path), { recursive: true });
+  await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(path), { recursive: true });
   if (existing !== void 0) {
     try {
-      await (0, import_promises3.writeFile)(`${path}.bezel-backup`, existing, { flag: "wx", mode: 384 });
+      await (0, import_promises4.writeFile)(`${path}.bezel-backup`, existing, { flag: "wx", mode: 384 });
       result.backedUp.push(rel);
     } catch (error) {
       if (error.code !== "EEXIST") throw error;
     }
   }
-  await (0, import_promises3.writeFile)(path, content, "utf8");
+  await (0, import_promises4.writeFile)(path, content, "utf8");
   result.written.push(rel);
 }
 async function installSkills(options) {
-  const cwd = (0, import_node_path4.resolve)(options.cwd ?? process.cwd());
+  const cwd = (0, import_node_path5.resolve)(options.cwd ?? process.cwd());
   const result = { written: [], unchanged: [], backedUp: [], hints: [] };
   for (const dir of skillDirectories(options.client)) {
     for (const [file, content] of Object.entries(AGENT_SKILL.files)) {
-      await writeManaged(cwd, (0, import_node_path4.join)(cwd, dir, AGENT_SKILL.name, file), content, result);
+      await writeManaged(cwd, (0, import_node_path5.join)(cwd, dir, AGENT_SKILL.name, file), content, result);
     }
   }
   if (options.agentsMd ?? true) {
-    const agentsPath = (0, import_node_path4.join)(cwd, "AGENTS.md");
+    const agentsPath = (0, import_node_path5.join)(cwd, "AGENTS.md");
     const existing = await readIfExists(agentsPath) ?? "";
     const merged = mergeAgentsMd(existing);
     if (merged === existing) {
       result.unchanged.push("AGENTS.md");
     } else {
-      await (0, import_promises3.writeFile)(agentsPath, merged, "utf8");
+      await (0, import_promises4.writeFile)(agentsPath, merged, "utf8");
       result.written.push("AGENTS.md");
     }
-    const claudeMd = await readIfExists((0, import_node_path4.join)(cwd, "CLAUDE.md"));
+    const claudeMd = await readIfExists((0, import_node_path5.join)(cwd, "CLAUDE.md"));
     if (claudeMd !== void 0 && !claudeMd.includes("@AGENTS.md")) {
       result.hints.push(
         "CLAUDE.md exists and does not include AGENTS.md. Add a line containing `@AGENTS.md` to CLAUDE.md so Claude Code loads the Bezel rules."
@@ -854,11 +1151,11 @@ async function installMcp(clientName, options = {}) {
       );
     }
   } else if (client === "cursor" || client === "vscode") {
-    const path = (0, import_node_path5.resolve)(client === "cursor" ? ".cursor/mcp.json" : ".vscode/mcp.json");
+    const path = (0, import_node_path6.resolve)(client === "cursor" ? ".cursor/mcp.json" : ".vscode/mcp.json");
     let raw = "{}";
     let exists = false;
     try {
-      raw = await (0, import_promises4.readFile)(path, "utf8");
+      raw = await (0, import_promises5.readFile)(path, "utf8");
       exists = true;
     } catch (error) {
       if (error.code !== "ENOENT") throw error;
@@ -872,9 +1169,9 @@ async function installMcp(clientName, options = {}) {
       );
     }
     if (merged !== raw) {
-      await (0, import_promises4.mkdir)((0, import_node_path5.dirname)(path), { recursive: true });
-      if (exists) await (0, import_promises4.writeFile)(`${path}.bezel-backup`, raw, { flag: "wx", mode: 384 });
-      await (0, import_promises4.writeFile)(path, merged, { flag: exists ? "w" : "wx" });
+      await (0, import_promises5.mkdir)((0, import_node_path6.dirname)(path), { recursive: true });
+      if (exists) await (0, import_promises5.writeFile)(`${path}.bezel-backup`, raw, { flag: "wx", mode: 384 });
+      await (0, import_promises5.writeFile)(path, merged, { flag: exists ? "w" : "wx" });
     }
     console.log(`Bezel configured in ${path}`);
   } else {
@@ -922,8 +1219,15 @@ Usage:
                            Teach claude-code, codex, cursor, or all about Bezel
   bezel init [options]     Create a bezel.json for this project
   bezel build [options]    Generate the outputs (default command)
+  bezel diff [--json]      Local edits not in Bezel yet (vs ${LOCKFILE_NAME});
+                           --json prints them as JSON Patch operations for a push
+  bezel sync [--discard-local-edits]
+                           Apply the tokens the Bezel MCP returned (${SYNC_STAGING_PATH}):
+                           writes ${LOCKFILE_NAME} and design-tokens.json, then builds.
+                           Run after every sync and every push.
 
 Reads design-tokens.json from the project root (the working directory).
+Commit design-tokens.json and ${LOCKFILE_NAME} together; never edit the lockfile by hand.
 
 install-mcp options:
       --skills                  Also run install-skills for the same client (skips the question)
@@ -968,9 +1272,9 @@ TypeScript project unless you pass the paths explicitly.
 --project and --tokens-version update only their own key in an existing bezel.json; no --force needed.
 `;
 async function loadConfig(path) {
-  const abs = (0, import_node_path6.resolve)(process.cwd(), path);
+  const abs = (0, import_node_path7.resolve)(process.cwd(), path);
   if (/\.json$/.test(abs)) {
-    return JSON.parse(await (0, import_promises5.readFile)(abs, "utf8"));
+    return JSON.parse(await (0, import_promises6.readFile)(abs, "utf8"));
   }
   const mod = await import((0, import_node_url.pathToFileURL)(abs).href);
   return mod.default ?? mod;
@@ -994,6 +1298,8 @@ var OPTIONS = {
   "no-contexts": { type: "boolean" },
   "no-fonts": { type: "boolean" },
   force: { type: "boolean", short: "f" },
+  json: { type: "boolean" },
+  "discard-local-edits": { type: "boolean" },
   help: { type: "boolean", short: "h" }
 };
 var TOKENS_FILE_HINT = "Add design-tokens.json to the project root \u2014 ask your AI agent for it via the\n     Bezel MCP, or download it from your project.";
@@ -1014,7 +1320,7 @@ async function runInit(values) {
     projectId: values.project,
     version: values["tokens-version"]
   });
-  const configName = (0, import_node_path6.relative)(cwd, result.configPath) || DEFAULT_CONFIG_FILE;
+  const configName = (0, import_node_path7.relative)(cwd, result.configPath) || DEFAULT_CONFIG_FILE;
   if (result.updated) {
     if (values.project) {
       const changed = result.previousProjectId && result.previousProjectId !== values.project;
@@ -1026,6 +1332,10 @@ async function runInit(values) {
     }
     if (result.config.version !== result.previousVersion) {
       process.stderr.write(`bezel: set version to ${result.config.version} in ${configName}
+`);
+    }
+    if (result.removedLockfile) {
+      process.stderr.write(`bezel: removed ${LOCKFILE_NAME} (it belonged to the previous project)
 `);
     }
     if (!result.hasTokensFile) {
@@ -1062,7 +1372,7 @@ ${TOKENS_FILE_HINT}
   if (!scripts["tokens"]) {
     steps.push('Add "tokens": "bezel build" to your package.json scripts.');
   }
-  if (!skillDirectories("all").some((dir) => (0, import_node_fs2.existsSync)((0, import_node_path6.resolve)(cwd, dir, "bezel")))) {
+  if (!skillDirectories("all").some((dir) => (0, import_node_fs3.existsSync)((0, import_node_path7.resolve)(cwd, dir, "bezel")))) {
     steps.push("Teach your AI coding agent about Bezel: npx bezel install-skills");
   }
   steps.push(`Run the build, then import ${result.config.variablesOutput} in your entry file.`);
@@ -1071,7 +1381,7 @@ ${TOKENS_FILE_HINT}
 `));
 }
 async function runBuild(values) {
-  const configPath = values.config ?? ((0, import_node_fs2.existsSync)((0, import_node_path6.resolve)(process.cwd(), DEFAULT_CONFIG_FILE)) ? DEFAULT_CONFIG_FILE : void 0);
+  const configPath = values.config ?? ((0, import_node_fs3.existsSync)((0, import_node_path7.resolve)(process.cwd(), DEFAULT_CONFIG_FILE)) ? DEFAULT_CONFIG_FILE : void 0);
   const fileConfig = configPath ? await loadConfig(configPath) : {};
   const options = { ...fileConfig };
   if (values["variables-output"]) options.variablesOutput = values["variables-output"];
@@ -1090,6 +1400,59 @@ async function runBuild(values) {
 `);
   }
 }
+var EXIT_UNPUSHED_EDITS = 2;
+async function runDiff(values) {
+  const result = await diffTokens({ cwd: process.cwd() });
+  const json = values.json;
+  if (result.ok === false) {
+    if (json) process.stdout.write(`${JSON.stringify(result, null, 2)}
+`);
+    process.stderr.write(`bezel: ${result.message}
+`);
+    process.exitCode = 1;
+    return;
+  }
+  if (json) {
+    const { projectId, version, baseRevision, operations } = result;
+    process.stdout.write(`${JSON.stringify({ ok: true, projectId, version, baseRevision, operations })}
+`);
+    return;
+  }
+  const edits = result.operations.filter((operation) => operation.op !== "test");
+  if (edits.length === 0) {
+    process.stdout.write(`In sync with Bezel revision ${result.baseRevision} (${result.version}). No local edits.
+`);
+    return;
+  }
+  const paths = changedPaths(result.operations);
+  process.stdout.write(
+    `${edits.length} local ${edits.length === 1 ? "edit" : "edits"} not in Bezel yet (based on revision ${result.baseRevision}):
+`
+  );
+  for (const path of paths.slice(0, 50)) process.stdout.write(`  ${path}
+`);
+  if (paths.length > 50) process.stdout.write(`  ...and ${paths.length - 50} more
+`);
+  process.stdout.write('Push them with the Bezel MCP ("push my token changes to Bezel").\n');
+}
+async function runSync(values) {
+  const result = await syncFromStaging({ cwd: process.cwd(), discardLocalEdits: values["discard-local-edits"] });
+  if (result.ok === false) {
+    process.stderr.write(`bezel: ${result.message}
+`);
+    process.exitCode = result.reason === "unpushed-edits" || result.reason === "unknown-local-edits" ? EXIT_UNPUSHED_EDITS : 1;
+    return;
+  }
+  process.stderr.write(
+    `bezel: synced revision ${result.revision} (${result.version}) of project ${result.projectId} into ${LOCKFILE_NAME}${result.tokensChanged ? " and design-tokens.json" : "; design-tokens.json already matched"}
+`
+  );
+  if (result.discardedEdits > 0) {
+    process.stderr.write(`bezel: discarded ${result.discardedEdits} local ${result.discardedEdits === 1 ? "edit" : "edits"}
+`);
+  }
+  await runBuild(values);
+}
 async function main(argv) {
   const { values, positionals } = (0, import_node_util.parseArgs)({
     args: argv,
@@ -1113,6 +1476,14 @@ async function main(argv) {
     await runInit(values);
     return;
   }
+  if (command === "diff") {
+    await runDiff(values);
+    return;
+  }
+  if (command === "sync") {
+    await runSync(values);
+    return;
+  }
   if (command !== "build") {
     process.stderr.write(`bezel: unknown command "${command}".