@vegastack/design 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -0,0 +1,78 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  FLOATING: () => FLOATING,
+  TIMINGS: () => TIMINGS,
+  cn: () => cn
+});
+module.exports = __toCommonJS(src_exports);
+var import_clsx = require("clsx");
+var import_tailwind_merge = require("tailwind-merge");
+var twMerge = (0, import_tailwind_merge.extendTailwindMerge)({
+  extend: {
+    classGroups: {
+      "font-size": [
+        {
+          text: [
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "label",
+            "label-sm",
+            "code",
+            "code-sm",
+            "mono-label",
+            "display-sm",
+            "display-md",
+            "display-lg",
+            "display-xl"
+          ]
+        }
+      ]
+    }
+  }
+});
+function cn(...inputs) {
+  return twMerge((0, import_clsx.clsx)(inputs));
+}
+var TIMINGS = {
+  /** How long transient success feedback holds before reverting (CopyButton "Copied ✓"). */
+  feedbackRevertMs: 1500,
+  /** Debounce before auto-persisting a text field (AutoSaveInput). */
+  autoSaveDebounceMs: 800,
+  /** Hover delay before a rich preview (HoverCard) opens — guards accidental opens. */
+  hoverOpenDelayMs: 700,
+  /** Hover delay before a rich preview closes — lets the pointer travel into the card. */
+  hoverCloseDelayMs: 300
+};
+var FLOATING = {
+  sideOffsetAttached: 4,
+  sideOffsetDetached: 8,
+  collisionPadding: 8
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FLOATING,
+  TIMINGS,
+  cn
+});

package/dist/index.d.cts

@@ -0,0 +1,56 @@
+import { ClassValue } from 'clsx';
+export { ClassValue } from 'clsx';
+
+/**
+ * Merges Tailwind CSS class names with intelligent conflict resolution.
+ *
+ * Combines `clsx` for conditional classes and `tailwind-merge` to handle
+ * conflicting Tailwind utilities (e.g., `px-2` and `px-4` → keeps last one).
+ *
+ * @param inputs - Class names, objects, arrays, or conditional values
+ * @returns Merged and deduplicated class string
+ *
+ * @example
+ * cn('px-2 py-1', 'px-4') // 'py-1 px-4'
+ * cn('text-foreground', isError && 'text-destructive')
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * @internal Registry theme-scope plumbing lives at `@vegastack/design/theme-scope`, NOT here.
+ * It calls `React.createContext()` at module scope, which is `undefined` under the `react-server`
+ * condition — re-exporting it from this entry would make every Server Component that imports
+ * `cn` crash on import. This entry stays server-safe by contract (see tsup.config.ts).
+ * Product code should use `MarketingSurface` rather than either symbol.
+ */
+/**
+ * Interaction timing constants (ms) — design decisions, not magic numbers (register P2-14).
+ * Single source for every JS-driven delay in the registry; change one value and every
+ * component that expresses that role follows.
+ */
+declare const TIMINGS: {
+    /** How long transient success feedback holds before reverting (CopyButton "Copied ✓"). */
+    readonly feedbackRevertMs: 1500;
+    /** Debounce before auto-persisting a text field (AutoSaveInput). */
+    readonly autoSaveDebounceMs: 800;
+    /** Hover delay before a rich preview (HoverCard) opens — guards accidental opens. */
+    readonly hoverOpenDelayMs: 700;
+    /** Hover delay before a rich preview closes — lets the pointer travel into the card. */
+    readonly hoverCloseDelayMs: 300;
+};
+/**
+ * Floating-surface positioning constants (px) — the unified sideOffset/collisionPadding
+ * pair (register P2-14). Two offset roles, one collision padding:
+ * - `sideOffsetAttached` (4): menu-like popups that read as attached to their trigger
+ *   (dropdown, context menu, select, emoji picker).
+ * - `sideOffsetDetached` (8): floating panels that read as detached (popover, hover-card,
+ *   tooltip).
+ * Submenus deliberately use 0 (flush) and are not part of this contract.
+ */
+declare const FLOATING: {
+    readonly sideOffsetAttached: 4;
+    readonly sideOffsetDetached: 8;
+    readonly collisionPadding: 8;
+};
+
+export { FLOATING, TIMINGS, cn };

package/dist/index.d.ts

@@ -16,6 +16,13 @@ export { ClassValue } from 'clsx';
  */
 declare function cn(...inputs: ClassValue[]): string;
 
+/**
+ * @internal Registry theme-scope plumbing lives at `@vegastack/design/theme-scope`, NOT here.
+ * It calls `React.createContext()` at module scope, which is `undefined` under the `react-server`
+ * condition — re-exporting it from this entry would make every Server Component that imports
+ * `cn` crash on import. This entry stays server-safe by contract (see tsup.config.ts).
+ * Product code should use `MarketingSurface` rather than either symbol.
+ */
 /**
  * Interaction timing constants (ms) — design decisions, not magic numbers (register P2-14).
  * Single source for every JS-driven delay in the registry; change one value and every

package/dist/preset.cjs

@@ -0,0 +1,37 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/preset.ts
+var preset_exports = {};
+__export(preset_exports, {
+  vegastackPreset: () => vegastackPreset
+});
+module.exports = __toCommonJS(preset_exports);
+var vegastackPreset = {
+  /** The token package this preset is bound to. */
+  tokens: "@vegastack/design-tokens",
+  /** CSS entry consumers import to get the full setup. */
+  css: "@vegastack/design/preset.css",
+  /** Tailwind major version this preset targets. */
+  tailwind: 4
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  vegastackPreset
+});

package/dist/preset.d.cts

@@ -0,0 +1,19 @@
+/**
+ * `@vegastack/design/preset` — Tailwind v4 setup metadata for VegaStack.
+ *
+ * Tailwind v4 is CSS-first (no JS `presets` array), so the real "preset" is the
+ * shipped `preset.css` (`@import "@vegastack/design/preset.css"`), which
+ * wires Tailwind + tw-animate-css + the VegaStack token theme + base reset in one
+ * import. This module exposes machine-readable metadata for tooling/agents.
+ */
+declare const vegastackPreset: {
+    /** The token package this preset is bound to. */
+    readonly tokens: "@vegastack/design-tokens";
+    /** CSS entry consumers import to get the full setup. */
+    readonly css: "@vegastack/design/preset.css";
+    /** Tailwind major version this preset targets. */
+    readonly tailwind: 4;
+};
+type VegastackPreset = typeof vegastackPreset;
+
+export { type VegastackPreset, vegastackPreset };

package/dist/theme-scope.cjs

@@ -0,0 +1,56 @@
+"use strict";
+"use client";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/theme-scope.tsx
+var theme_scope_exports = {};
+__export(theme_scope_exports, {
+  InternalThemeScopeProvider: () => InternalThemeScopeProvider,
+  useInternalThemeScope: () => useInternalThemeScope
+});
+module.exports = __toCommonJS(theme_scope_exports);
+var React = __toESM(require("react"), 1);
+var import_jsx_runtime = require("react/jsx-runtime");
+var InternalThemeScopeContext = React.createContext(
+  void 0
+);
+function InternalThemeScopeProvider({
+  children,
+  scope
+}) {
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(InternalThemeScopeContext.Provider, { value: scope, children });
+}
+function useInternalThemeScope() {
+  return React.useContext(InternalThemeScopeContext);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  InternalThemeScopeProvider,
+  useInternalThemeScope
+});

package/dist/theme-scope.d.cts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+/**
+ * Carries a semantic theme-scope class through React's tree, including across
+ * portals whose DOM nodes are mounted outside the scoped source subtree.
+ *
+ * @internal Registry infrastructure only. This is not a consumer-facing
+ * theming API; use `MarketingSurface` to establish the supported scope.
+ */
+declare function InternalThemeScopeProvider({ children, scope, }: {
+    children: React.ReactNode;
+    scope: string;
+}): React.JSX.Element;
+/**
+ * Reads the nearest semantic theme-scope class so portaled surfaces can apply
+ * it to their actual DOM roots instead of falling back to the page theme.
+ *
+ * @internal Registry infrastructure only. Components outside the canonical
+ * overlay implementations must not depend on this hook.
+ */
+declare function useInternalThemeScope(): string | undefined;
+
+export { InternalThemeScopeProvider, useInternalThemeScope };

package/dist/theme-scope.d.ts

@@ -0,0 +1,23 @@
+import * as React from 'react';
+
+/**
+ * Carries a semantic theme-scope class through React's tree, including across
+ * portals whose DOM nodes are mounted outside the scoped source subtree.
+ *
+ * @internal Registry infrastructure only. This is not a consumer-facing
+ * theming API; use `MarketingSurface` to establish the supported scope.
+ */
+declare function InternalThemeScopeProvider({ children, scope, }: {
+    children: React.ReactNode;
+    scope: string;
+}): React.JSX.Element;
+/**
+ * Reads the nearest semantic theme-scope class so portaled surfaces can apply
+ * it to their actual DOM roots instead of falling back to the page theme.
+ *
+ * @internal Registry infrastructure only. Components outside the canonical
+ * overlay implementations must not depend on this hook.
+ */
+declare function useInternalThemeScope(): string | undefined;
+
+export { InternalThemeScopeProvider, useInternalThemeScope };

package/dist/theme-scope.js

@@ -0,0 +1,21 @@
+"use client";
+
+// src/theme-scope.tsx
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+var InternalThemeScopeContext = React.createContext(
+  void 0
+);
+function InternalThemeScopeProvider({
+  children,
+  scope
+}) {
+  return /* @__PURE__ */ jsx(InternalThemeScopeContext.Provider, { value: scope, children });
+}
+function useInternalThemeScope() {
+  return React.useContext(InternalThemeScopeContext);
+}
+export {
+  InternalThemeScopeProvider,
+  useInternalThemeScope
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vegastack/design",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "VegaStack design system — cn utility, icon runtime, Tailwind v4 preset, and the vegastack-design CLI (tokens ship separately as @vegastack/design-tokens)",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,9 @@
     "url": "git+https://github.com/VegaStack/vegastack-design.git",
     "directory": "packages/design"
   },
+  "engines": {
+    "node": ">=24.14.0"
+  },
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -16,6 +19,7 @@
     "dist",
     "bin",
     "css",
+    "skills",
     "preset.css"
   ],
   "bin": {
@@ -24,39 +28,56 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
     },
     "./icons": {
       "types": "./dist/icons/index.d.ts",
-      "import": "./dist/icons/index.js"
+      "import": "./dist/icons/index.js",
+      "require": "./dist/icons/index.cjs",
+      "default": "./dist/icons/index.js"
+    },
+    "./theme-scope": {
+      "types": "./dist/theme-scope.d.ts",
+      "import": "./dist/theme-scope.js",
+      "require": "./dist/theme-scope.cjs",
+      "default": "./dist/theme-scope.js"
     },
     "./preset": {
       "types": "./dist/preset.d.ts",
-      "import": "./dist/preset.js"
+      "import": "./dist/preset.js",
+      "require": "./dist/preset.cjs",
+      "default": "./dist/preset.js"
     },
     "./preset.css": "./preset.css",
     "./theme.css": "./css/theme.css",
     "./base.css": "./css/base.css",
-    "./utilities.css": "./css/utilities.css"
+    "./utilities.css": "./css/utilities.css",
+    "./package.json": "./package.json"
   },
   "dependencies": {
     "clsx": "^2.1.1",
-    "lucide-react": "^1.24.0",
     "tailwind-merge": "^3.6.0",
-    "thesvg": "^3.2.6",
-    "@vegastack/design-tokens": "0.1.0"
+    "tsconfig-paths": "^4.2.0",
+    "tw-animate-css": "^1.4.0",
+    "@vegastack/design-tokens": "^0.2.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "tailwindcss": "^4.3.2",
-    "tw-animate-css": "^1.4.0"
+    "lucide-react": "^1.24.0",
+    "thesvg": "^3.2.6",
+    "tailwindcss": "^4.3.2"
   },
   "peerDependenciesMeta": {
     "tailwindcss": {
       "optional": true
     },
-    "tw-animate-css": {
+    "lucide-react": {
+      "optional": true
+    },
+    "thesvg": {
       "optional": true
     }
   },
@@ -66,23 +87,24 @@
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
     "eslint": "^10.7.0",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "lucide-react": "^1.24.0",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "tailwindcss": "^4.3.2",
+    "thesvg": "^3.2.6",
     "tw-animate-css": "^1.4.0",
     "typescript": "^6.0.3",
-    "@vegastack/typescript-config": "0.0.0",
-    "@vegastack/eslint-config": "0.0.0"
+    "@vegastack/eslint-config": "0.0.0",
+    "@vegastack/typescript-config": "0.0.0"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "scripts": {
     "build": "tsup",
     "lint": "eslint . && pnpm run verify",
     "verify": "node ../../tooling/verify-preset-source.mjs",
     "typecheck": "tsc --noEmit",
-    "test": "node test/compare.test.mjs && node test/check-updates.test.mjs"
+    "test": "node test/compare.test.mjs && node test/check-updates.test.mjs && node test/skills-install.test.mjs"
   }
 }

package/skills/vegastack-brand/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: vegastack-brand
+description: VegaStack marketing and external visual identity — logo usage, brand colour, and marketing typography, distinct from the product design system. Currently a deliberate stub with no assets. Use when asked about VegaStack branding, logo usage, marketing colours, or external-facing visual identity.
+---
+
+# VegaStack brand
+
+**This skill is a deliberate stub.** Marketing has not yet provided the brand assets (logo,
+marketing palette, marketing typography), so there is nothing here to apply yet.
+
+## What to do today
+
+For product UI, use the `vegastack-design-system` skill. Its OKLCH semantic tokens are the only
+locked visual identity VegaStack currently has.
+
+**Do not invent a marketing palette, logo treatment, or brand typography.** If a task needs one, say
+that the brand layer is not defined yet and ask, rather than generating something plausible that
+will later conflict with the real assets.
+
+Brand marks for external and marketing surfaces are rendered through `BrandIcon` from
+`@vegastack/design/icons` (backed by `thesvg`), which is available now.
+
+## Scope once populated
+
+- Logo usage: variants, clear-space, minimum sizes, prohibited treatments.
+- Brand colour and marketing typography — a separate layer from the product tokens, never a
+  replacement for them.
+- Marketing surface patterns, which in the component library are scoped to `.vs-marketing` and must
+  never appear in product UI.

package/skills/vegastack-consume/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: vegastack-consume
+description: Set up a project to consume the VegaStack design system — install the public npm layer, wire the Tailwind v4 CSS and the provider, configure registry access, add components through the fail-closed integrity flow, override tokens, and keep copies up to date. Use when initialising a new project on VegaStack, adding the first component, fixing setup or registry-auth problems, or wiring the provider.
+---
+
+# Consume VegaStack
+
+Once setup is done, use the `vegastack-design-system` skill for day-to-day UI work.
+
+## 1. Install the public layer
+
+```bash
+npm i @vegastack/design
+```
+
+No credentials needed. It pulls in `@vegastack/design-tokens` as a dependency and provides `cn()`,
+the icon runtime, the Tailwind v4 preset, and the `vegastack-design` CLI.
+
+**Invoking the CLI.** The bin is `vegastack-design` but the package is `@vegastack/design`, so a
+bare `npx vegastack-design …` in a project that does not already have it installed would try to
+fetch an unrelated, unscoped package from npm. Use one of these instead — the first once it is a
+local dependency (it resolves from `node_modules` and never contacts the registry), the second for a
+standalone one-off:
+
+```bash
+pnpm exec vegastack-design <command>
+npx --package=@vegastack/design vegastack-design <command>
+```
+
+`@vegastack/ui` is private and is never installed downstream — components arrive by copy-in.
+
+## 2. Tailwind v4 CSS
+
+You must be on Tailwind v4.
+
+```css
+@import "tailwindcss";
+@import "@vegastack/design/theme.css"; /* :root + .dark + the @theme inline bridge */
+@import "@vegastack/design/base.css"; /* border-border, body bg, :focus-visible, pointer cursor
+                                            on interactive controls, reduced-motion, and
+                                            body { isolation: isolate } — see step 3 */
+```
+
+Or one import that bundles all of it plus tw-animate:
+
+```css
+@import "@vegastack/design/preset.css";
+```
+
+**No manual `@source` is required.** The preset already declares `@source` for the classes that live
+inside the published builds — the icon runtime, and the provider/Toaster classNames (sonner emits
+`group-[.toaster]:bg-popover`-style classes that Tailwind must be told to generate). Your own
+application and component source is scanned by Tailwind as usual.
+
+## 3. Wrap the app root in the provider
+
+```bash
+npx shadcn@latest add @vegastack/provider
+```
+
+This copies `VegaStackProvider` and `useVegaStackTheme` into your project, composing the `sonner`
+Toaster item.
+
+```tsx
+import { VegaStackProvider } from "@/components/ui/provider";
+
+// <html suppressHydrationWarning>  — next-themes mutates it
+<body className="isolate">
+  <VegaStackProvider>{children}</VegaStackProvider>
+</body>;
+```
+
+It bundles theme (next-themes, class-based dark), the Sonner toaster, and the Base UI tooltip and
+direction providers.
+
+**The `isolate` is required, not cosmetic.** Overlay components (Dialog, Sheet, Popover, Tooltip,
+Select, menus) portal to `<body>` and depend on a root stacking context to render above page
+content. Get it from `@vegastack/design/base.css` (which sets `body { isolation: isolate }`) or by
+putting `className="isolate"` on your `<body>` yourself. Without it, popups can render _under_ app
+chrome or mis-position in stacking-context-heavy layouts.
+
+## 4. Configure registry access
+
+Components come from a private registry behind Cloudflare Access service tokens.
+
+If the project has no `components.json` yet, create one first — pick the **base** style, never
+`radix`, because VegaStack components are Base UI:
+
+```bash
+pnpm dlx shadcn@latest init --base base
+```
+
+Then add the registry block to `components.json`:
+
+```json
+{
+  "registries": {
+    "@vegastack": {
+      "url": "https://design.vegastack.com/r/{name}.json",
+      "headers": {
+        "CF-Access-Client-Id": "${CF_ACCESS_CLIENT_ID}",
+        "CF-Access-Client-Secret": "${CF_ACCESS_CLIENT_SECRET}"
+      }
+    }
+  }
+}
+```
+
+Put the credentials in `.env.local`. Inspect before writing anything:
+
+```bash
+pnpm dlx shadcn@latest add @vegastack/button --dry-run
+```
+
+External and client projects are **tokenless** — components are copied in during development, and
+the shipped application holds zero VegaStack credentials.
+
+## 5. Add a component (fail-closed, three steps)
+
+This is the only safe way to add a component. Do not collapse it to a bare `shadcn add`: that leaves
+a time-of-check/time-of-use gap, because `shadcn add` re-fetches the item after any preflight.
+
+```bash
+# Create a private directory and choose a NEW file path inside it. The verifier refuses an
+# existing path or a symlink rather than overwriting or following it.
+DIR="$(mktemp -d "${TMPDIR:-/tmp}/vegastack-verify.XXXXXX")"; ITEM="$DIR/button.json"
+
+# 1) PRE-WRITE — verify signature + hash, and save the trusted bytes for step 3.
+npx --package=@vegastack/design vegastack-design verify --save "$ITEM" button
+
+# Retain the verified digest in the parent shell BEFORE shadcn or dependency code runs.
+EXPECTED="$(node -e 'process.stdout.write(JSON.parse(require("node:fs").readFileSync(process.argv[1],"utf8")).meta.integrity)' "$ITEM")"
+
+# 2) COPY-IN — shadcn writes the files, rewriting import aliases per your components.json.
+pnpm dlx shadcn@latest add @vegastack/button
+
+# 3) POST-WRITE — prove the copied files match the SAVED item. Exits 1 on any tampering.
+npx --package=@vegastack/design vegastack-design verify \
+  --post-write --item "$ITEM" --expected-integrity "$EXPECTED" --target-dir .
+```
+
+Add `--hash-only` to step 1 only for local development or before the signed manifest is deployed —
+it skips `cosign` and therefore does **not** prove provenance.
+
+What each step guarantees, what it deliberately does not, and every flag and environment variable:
+[references/registry-integrity.md](references/registry-integrity.md).
+
+## 6. Override tokens
+
+One file, one variable, and every component repaints in both themes:
+
+```css
+:root {
+  --primary: oklch(0.55 0.2 264);
+}
+```
+
+Never override a `--color-*` variable — that is the build-inlined bridge, not the runtime contract.
+
+## 7. Stay current
+
+Copy-in means no automatic updates.
+
+```bash
+npx --package=@vegastack/design vegastack-design check-updates    # ⬆ update · ≈ drift · ✓ up to date
+```
+
+Then per stale component: `shadcn add @vegastack/<name> --diff` to review, `--overwrite` to apply,
+and re-run the step-3 post-write verification. Details and CI wiring:
+[references/registry-integrity.md](references/registry-integrity.md).
+
+Add the Renovate preset `github>VegaStack/renovate-config` so additive token bumps arrive as PRs.
+
+## Install the agent skills
+
+If this project's agents do not already have them:
+
+```bash
+npx --package=@vegastack/design vegastack-design skills install
+```
+
+Writes the public VegaStack skills into `.claude/skills/` and `.agents/skills/`.