@kazee-ds/init 0.0.0-stage → 0.1.3

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @kazee-ds/init
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Preview-first setup for an existing standalone React or Vue application. Public release 0.1.2 pins core packages at 0.4.0. Verify the available npm versions before installing. Earlier CLI releases targeted private GitLab.
+
+From the design-system checkout, run:
+
+```sh
+node packages/init/bin/kazee-init.mjs --dir /absolute/path/to/application
+node packages/init/bin/kazee-init.mjs --dir /absolute/path/to/application --apply
+```
+
+Supply `--framework react|vue` or `--package-manager npm|pnpm|yarn` when detection
+is ambiguous or unavailable. Explicit choices do not override conflicting
+lockfiles. Yarn means Classic only; modern Yarn requires the manual guide.
+
+Init adds missing exact Kazee dependencies, merges a public npm scope mapping,
+appends a framework-specific managed section to `AGENTS.md`, and generates
+`kazee-setup.md`. It preserves unrelated configuration and rejects conflicting
+versions, registry mappings, edited managed content, workspaces, Next, and Nuxt.
+
+Preview never writes files. Apply preflights all four files and attempts to
+restore changes after ordinary write failures. Multi-file writes are not
+crash-atomic. Symlinked and hardlinked write targets are rejected.
+
+Public installs need no read credentials. Init neither creates auth entries nor prints existing credentials; unrelated registry settings are preserved.
+No installation, network requests, source edits, lockfile updates, Git operations,
+or CI changes occur inside init.
+
+Follow the generated guide to install dependencies, import CSS once, merge the
+lint config, and run application checks. ESLint 10 and appropriate parsers remain
+the application's responsibility. Bundled versions are not a latest-version query.
+
+See `docs/consumer-init.md` in the repository for verification and limitations.

package/bin/kazee-init.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { parseArgs } from 'node:util';
+import { createPlan, applyPlan, renderPlan } from '../src/setup.mjs';
+
+try {
+  const { values } = parseArgs({
+    options: {
+      dir: { type: 'string' },
+      framework: { type: 'string' },
+      'package-manager': { type: 'string' },
+      apply: { type: 'boolean', default: false },
+      help: { type: 'boolean', short: 'h' },
+    },
+    strict: true,
+    allowPositionals: false,
+  });
+  if (values.help) {
+    console.log(
+      'kazee-init [--dir PATH] [--framework react|vue] [--package-manager npm|pnpm|yarn] [--apply]\nPreview is the default. Yarn Classic only. Private registry access is a prerequisite.',
+    );
+  } else {
+    const plan = createPlan({
+      dir: values.dir,
+      framework: values.framework,
+      packageManager: values['package-manager'],
+    });
+    console.log(renderPlan(plan));
+    if (plan.conflicts.length) process.exitCode = 1;
+    else if (values.apply) {
+      applyPlan(plan);
+      console.log(
+        'Applied. Dependency installation, global CSS, and ESLint/CI integration still require the steps above.',
+      );
+    }
+  }
+} catch (error) {
+  // Never echo argv, manifest values, registry values, or arbitrary parse errors.
+  const safe = error.code?.startsWith('ERR_PARSE_ARGS')
+    ? 'Invalid arguments. Run kazee-init --help.'
+    : error instanceof Error && !error.code
+      ? error.message
+      : 'Unable to inspect or write the target. Check directory access and file types.';
+  console.error(safe);
+  process.exitCode = 1;
+}

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@kazee-ds/init",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.3",
+  "description": "Preview-first setup for Kazee Design System consumers",
+  "type": "module",
+  "bin": {
+    "kazee-init": "./bin/kazee-init.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "dependencies": {
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "publint": "^0.3.25"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/kazee.indonesia/kazee-design-system.git",
+    "directory": "packages/init"
+  },
+  "homepage": "https://kazee-design-system-023417.gitlab.io",
+  "scripts": {
+    "build": "node --check bin/kazee-init.mjs && node --check src/setup.mjs && node --check src/content.mjs",
+    "test": "node --test test/*.test.mjs",
+    "lint:package": "publint --strict"
+  }
 }

package/src/content.mjs

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+
+export const RELEASE = Object.freeze({ framework: '0.5.0', styles: '0.5.0', lint: '0.4.0' });
+export const REGISTRY = 'https://registry.npmjs.org/';
+const INIT_VERSION = JSON.parse(
+  readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+).version;
+export const START = '<!-- kazee-ds:init:start -->';
+export const END = '<!-- kazee-ds:init:end -->';
+
+export function managedRules(framework) {
+  const template = readFileSync(
+    new URL('../templates/AGENTS.md', import.meta.url),
+    'utf8',
+  ).replaceAll('\r\n', '\n');
+  const other = framework === 'react' ? 'Vue' : 'React';
+  const filtered = template.replace(new RegExp(`## ${other} API\\n[\\s\\S]*?(?=\\n## |$)`), '');
+  return `${START}\n<!-- Template revision: 2026-10-28; init ${INIT_VERSION}; ${framework} -->\n${filtered.trim()}\n${END}`;
+}
+
+export function installCommand(manager, framework) {
+  const runtime = `@kazee-ds/${framework}@${RELEASE.framework} @kazee-ds/styles@${RELEASE.styles}`;
+  const lint = `@kazee-ds/eslint-config@${RELEASE.lint}`;
+  if (manager === 'npm')
+    return `npm install --save-exact ${runtime}\nnpm install --save-dev --save-exact ${lint}`;
+  if (manager === 'pnpm')
+    return `pnpm add --save-exact ${runtime}\npnpm add --save-dev --save-exact ${lint}`;
+  return `yarn add --exact ${runtime}\nyarn add --dev --exact ${lint}`;
+}
+
+export function setupGuide(framework, manager) {
+  const lintGuide = readFileSync(
+    new URL('../templates/consumer-lint.md', import.meta.url),
+    'utf8',
+  ).replaceAll('\r\n', '\n');
+  const heading =
+    framework === 'react'
+      ? '### Complete React/TypeScript example'
+      : '### Complete Vue/TypeScript example';
+  const section = lintGuide.slice(lintGuide.indexOf(heading));
+  const example = section.match(/```js\n([\s\S]*?)```/)[1];
+  return `# Kazee setup — ${framework}\n\nGenerated by @kazee-ds/init ${INIT_VERSION}. These are supported pinned versions, not a latest-version query.\n\n## Install dependencies\n\nPackages are distributed on public npm. No read token or login is required. Confirm the pinned versions exist on npm before installation.\n\n\`\`\`sh\n${installCommand(manager, framework)}\n\`\`\`\n\nCommit the updated package manifest and the application's existing lockfile after installation. Init does not install dependencies or update lockfiles.\n\n${manager === 'yarn' ? 'Yarn guidance is limited to Yarn Classic. Init does not create modern Yarn .yarnrc.yml authentication settings.\n\n' : ''}## Manual step: import shared CSS\n\nAdd this once to the application's existing global entry point:\n\n\`\`\`js\nimport '@kazee-ds/styles/index.css';\n\`\`\`\n\nIt includes the tokens. Keep the application's existing stylesheet imports. This step has not been performed by init.\n\n## Manual step: enable lint\n\nUse ESLint 10 with the application's existing parsers. This example assumes typescript-eslint${framework === 'vue' ? ' and eslint-plugin-vue' : ''} are installed. Adapt source globs to the application, preserve existing checks, and include consumerConfig in the exported flat config after parser setup.\n\n\`\`\`js\n${example}\`\`\`\n\nInit has not modified ESLint config or CI. Run lint in the application's CI; installing the package alone does not activate its rules.\n\n## Optional MCP reference\n\nConnect the Kazee MCP server using the client-specific configuration in the MCP guide. Start with get_catalog_versions and pass the exact installed framework package version to docs/examples tools. Init has not edited MCP client configuration or enabled a server.\n\n## Verify\n\nRun the application's existing lint, typecheck, and build scripts. Check Button activation/disabled behavior, Select keyboard selection, and shared styling. Report missing scripts instead of claiming they passed.\n\n- [Public Storybook](https://kazee-design-system-023417.gitlab.io)\n- [Installation guide](https://gitlab.com/kazee.indonesia/kazee-design-system/-/blob/main/docs/installation.md)\n- [Consumer lint guide](https://gitlab.com/kazee.indonesia/kazee-design-system/-/blob/main/docs/consumer-lint.md)\n\nThe source repository may remain private; published npm packages and Storybook are public.\n`;
+}

package/src/setup.mjs

@@ -0,0 +1,353 @@
+import {
+  lstatSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  realpathSync,
+  existsSync,
+  openSync,
+  closeSync,
+  ftruncateSync,
+  fstatSync,
+} from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import semver from 'semver';
+import {
+  RELEASE,
+  REGISTRY,
+  START,
+  END,
+  managedRules,
+  setupGuide,
+  installCommand,
+} from './content.mjs';
+
+const FILES = ['package.json', '.npmrc', 'AGENTS.md', 'kazee-setup.md'];
+const SECTIONS = ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies'];
+const LOCKS = {
+  'package-lock.json': 'npm',
+  'npm-shrinkwrap.json': 'npm',
+  'pnpm-lock.yaml': 'pnpm',
+  'yarn.lock': 'yarn',
+};
+const newline = (text) => (text?.includes('\r\n') ? '\r\n' : '\n');
+
+function readSafe(path) {
+  let stat;
+  try {
+    stat = lstatSync(path);
+  } catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw error;
+  }
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink > 1) {
+    throw new Error(`Expected a regular, unlinked file: ${path}`);
+  }
+  const bytes = readFileSync(path);
+  if (bytes.includes(0) || !Buffer.from(bytes.toString('utf8')).equals(bytes)) {
+    throw new Error(`Expected UTF-8 text: ${path}`);
+  }
+  return bytes.toString('utf8');
+}
+
+function manifest(text) {
+  try {
+    const pkg = JSON.parse(text);
+    if (!pkg || typeof pkg !== 'object' || Array.isArray(pkg)) throw new Error();
+    for (const section of SECTIONS) {
+      if (
+        pkg[section] !== undefined &&
+        (!pkg[section] ||
+          typeof pkg[section] !== 'object' ||
+          Array.isArray(pkg[section]) ||
+          Object.values(pkg[section]).some((v) => typeof v !== 'string'))
+      )
+        throw new Error();
+    }
+    return pkg;
+  } catch {
+    throw new Error('package.json must be valid JSON with dependency maps of string versions.');
+  }
+}
+
+function checkTarget(dir, pkg) {
+  if (pkg.workspaces || existsSync(join(dir, 'pnpm-workspace.yaml')))
+    throw new Error('Workspace targets are not supported in init 0.1.0.');
+  for (let parent = dirname(dir); parent !== dirname(parent); parent = dirname(parent)) {
+    if (existsSync(join(parent, 'pnpm-workspace.yaml')))
+      throw new Error('Nested workspace targets are not supported.');
+    const parentFile = join(parent, 'package.json');
+    if (existsSync(parentFile)) {
+      try {
+        if (JSON.parse(readFileSync(parentFile, 'utf8')).workspaces)
+          throw new Error('Nested workspace targets are not supported.');
+      } catch (error) {
+        if (error.message.includes('workspace targets')) throw error;
+      }
+    }
+  }
+  const deps = Object.assign({}, ...SECTIONS.map((s) => pkg[s]));
+  if (deps.next || deps.nuxt || deps['@nuxt/kit'])
+    throw new Error(
+      'Next/Nuxt adapters are outside init 0.1.0; use the manual installation guide.',
+    );
+}
+
+function detectFramework(pkg, choice) {
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const found = ['react', 'vue'].filter((name) => deps[name]);
+  if (choice && !['react', 'vue'].includes(choice))
+    throw new Error('Unsupported framework; choose react or vue.');
+  if (choice && !found.includes(choice))
+    throw new Error('Selected framework must already be a direct dependency.');
+  if (!choice && found.length !== 1)
+    throw new Error('Select a framework explicitly with --framework react or vue.');
+  return choice || found[0];
+}
+
+function detectManager(dir, pkg, choice) {
+  if (choice && !['npm', 'pnpm', 'yarn'].includes(choice))
+    throw new Error('Unsupported package manager.');
+  const declared = pkg.packageManager?.match(/^(npm|pnpm|yarn)@(\d+)\./);
+  if (pkg.packageManager && !declared) throw new Error('Unsupported packageManager declaration.');
+  if (declared?.[1] === 'yarn' && declared[2] !== '1')
+    throw new Error('Only Yarn Classic is supported; use the manual guide for modern Yarn.');
+  if (existsSync(join(dir, '.yarnrc.yml')))
+    throw new Error('Modern Yarn configuration requires the manual installation guide.');
+  const found = [
+    ...new Set(
+      Object.entries(LOCKS)
+        .filter(([file]) => existsSync(join(dir, file)))
+        .map(([, manager]) => manager),
+    ),
+  ];
+  const evidence = new Set([
+    ...found,
+    ...(declared ? [declared[1]] : []),
+    ...(choice ? [choice] : []),
+  ]);
+  if (evidence.size > 1)
+    throw new Error('Package manager conflict between selection, packageManager, or lockfiles.');
+  if (!evidence.size)
+    throw new Error(
+      'Select a package manager explicitly with --package-manager npm, pnpm, or yarn.',
+    );
+  if (
+    evidence.has('yarn') &&
+    !declared &&
+    (!existsSync(join(dir, 'yarn.lock')) ||
+      !readFileSync(join(dir, 'yarn.lock'), 'utf8').includes('# yarn lockfile v1'))
+  ) {
+    throw new Error(
+      'Cannot verify Yarn Classic from lockfile; declare packageManager yarn@1.x or use the manual guide.',
+    );
+  }
+  return [...evidence][0];
+}
+
+function editRegistry(text, conflicts) {
+  let result = text || '';
+  const eol = newline(text);
+  for (const [key, value] of [['@kazee-ds:registry', REGISTRY]]) {
+    const values = result
+      .split(/\r?\n/)
+      .map((line) => line.trim())
+      .filter((line) => !line.startsWith('#') && !line.startsWith(';'))
+      .filter((line) => line.split('=')[0].trim() === key)
+      .map((line) => line.slice(line.indexOf('=') + 1).trim());
+    if (values.length > 1 || values.some((v) => v !== value))
+      conflicts.push(`.npmrc: conflicting setting for ${key} (value redacted).`);
+    else if (!values.length)
+      result += `${result && !result.endsWith('\n') ? eol : ''}${key}=${value}${eol}`;
+  }
+  return result;
+}
+
+function editRules(text, framework, conflicts) {
+  const original = text || '';
+  const eol = newline(text);
+  const block = managedRules(framework).replaceAll('\n', eol);
+  const starts = original.split(START).length - 1;
+  const ends = original.split(END).length - 1;
+  if (!starts && !ends)
+    return `${original}${original ? `${original.endsWith('\n') ? '' : eol}${eol}` : ''}${block}${eol}`;
+  const begin = original.indexOf(START);
+  const finish = original.indexOf(END);
+  if (
+    starts !== 1 ||
+    ends !== 1 ||
+    finish < begin ||
+    original.slice(begin, finish + END.length) !== block
+  ) {
+    conflicts.push(
+      'AGENTS.md: existing managed section differs or has malformed/duplicate markers; review manually.',
+    );
+  }
+  return original;
+}
+
+export function createPlan({
+  dir = process.cwd(),
+  framework: choice,
+  packageManager: managerChoice,
+} = {}) {
+  const target = resolve(dir);
+  if (lstatSync(target).isSymbolicLink() || !lstatSync(target).isDirectory())
+    throw new Error('Target must be a regular application directory.');
+  const root = realpathSync(target);
+  const before = Object.fromEntries(FILES.map((file) => [file, readSafe(join(root, file))]));
+  if (before['package.json'] === null) throw new Error('No package.json in the target directory.');
+  const pkg = manifest(before['package.json']);
+  checkTarget(root, pkg);
+  const framework = detectFramework(pkg, choice);
+  const packageManager = detectManager(root, pkg, managerChoice);
+  const conflicts = [];
+  const manual = [
+    'Import shared CSS once in the global entry.',
+    'Merge consumerConfig after existing parser configuration and enable lint in CI.',
+    'Run application lint, typecheck, build, and interaction checks.',
+  ];
+  const eslint = SECTIONS.map((s) => pkg[s]?.eslint).filter(Boolean);
+  if (!eslint.length)
+    manual.unshift('Install ESLint 10 and the framework parsers before enabling Kazee lint.');
+  const deps = Object.assign({}, ...SECTIONS.map((s) => pkg[s]));
+  const peers =
+    framework === 'react'
+      ? [
+          ['react', '>=19.0.0'],
+          ['react-dom', '>=19.0.0'],
+        ]
+      : [['vue', '>=3.4.0']];
+  for (const [name, required] of peers) {
+    if (!deps[name])
+      manual.push(
+        `Install or review the required ${name} peer dependency (${required}); init does not change framework versions.`,
+      );
+    else if (
+      !semver.validRange(deps[name]) ||
+      !semver.minVersion(deps[name]) ||
+      !semver.subset(deps[name], required)
+    )
+      conflicts.push(
+        `package.json: ${name} must satisfy the published peer contract (${required}); resolve manually.`,
+      );
+  }
+  if (!deps['typescript-eslint'] && !deps['@typescript-eslint/parser'])
+    manual.push(
+      'The TypeScript parser is not declared; install or review the application parser setup.',
+    );
+  if (framework === 'vue' && !deps['eslint-plugin-vue'] && !deps['vue-eslint-parser'])
+    manual.push('A Vue SFC parser is not declared; install or review the Vue ESLint setup.');
+  for (const range of eslint) {
+    if (
+      !semver.validRange(range) ||
+      !semver.minVersion(range) ||
+      !semver.subset(range, '>=10.0.0 <11.0.0')
+    )
+      conflicts.push(
+        'package.json: ESLint must be constrained to supported stable major 10; resolve manually.',
+      );
+  }
+  for (const [name, version, section] of [
+    [`@kazee-ds/${framework}`, RELEASE.framework, 'dependencies'],
+    ['@kazee-ds/styles', RELEASE.styles, 'dependencies'],
+    ['@kazee-ds/eslint-config', RELEASE.lint, 'devDependencies'],
+  ]) {
+    const locations = SECTIONS.filter((s) => pkg[s]?.[name] !== undefined);
+    if (locations.some((s) => s !== section || pkg[s][name] !== version))
+      conflicts.push(`package.json: review existing ${name} version or dependency section.`);
+    else if (!locations.length) {
+      pkg[section] ||= {};
+      pkg[section][name] = version;
+    }
+  }
+  const indent = before['package.json'].match(/\n([\t ]+)"/)?.[1] || '  ';
+  const pkgText =
+    JSON.stringify(pkg, null, indent).replaceAll('\n', newline(before['package.json'])) +
+    (before['package.json'].endsWith('\n') ? newline(before['package.json']) : '');
+  const guide = setupGuide(framework, packageManager).replaceAll(
+    '\n',
+    newline(before['kazee-setup.md']),
+  );
+  if (before['kazee-setup.md'] !== null && before['kazee-setup.md'] !== guide)
+    conflicts.push('kazee-setup.md: existing file differs; review manually.');
+  const after = {
+    'package.json':
+      JSON.stringify(pkg) === JSON.stringify(manifest(before['package.json']))
+        ? before['package.json']
+        : pkgText,
+    '.npmrc': editRegistry(before['.npmrc'], conflicts),
+    'AGENTS.md': editRules(before['AGENTS.md'], framework, conflicts),
+    'kazee-setup.md': guide,
+  };
+  return {
+    root,
+    framework,
+    packageManager,
+    conflicts,
+    manual,
+    changes: FILES.map((name) => ({
+      name,
+      before: before[name],
+      after: after[name],
+      changed: before[name] !== after[name],
+    })),
+  };
+}
+
+export function renderPlan(plan, applied = false) {
+  return `${applied ? 'Applied' : 'Preview (no files written)'}: ${plan.framework}, ${plan.packageManager}\n${plan.changes.map((c) => `${c.changed ? 'CHANGE' : 'UNCHANGED'} ${c.name}`).join('\n')}\n${plan.conflicts.map((s) => `BLOCKED ${s}`).join('\n')}\n\nNext: install public npm dependencies (no read token required):\n${installCommand(plan.packageManager, plan.framework)}\n\nManual steps:\n${plan.manual.map((s) => `- ${s}`).join('\n')}\n`;
+}
+
+export function applyPlan(plan, { write = writeFileSync } = {}) {
+  if (plan.conflicts.length)
+    throw new Error('Resolve preview conflicts before applying; no files written.');
+  if (realpathSync(plan.root) !== plan.root || lstatSync(plan.root).isSymbolicLink())
+    throw new Error('Target directory changed since preview.');
+  if (plan.changes.length !== FILES.length || plan.changes.some((c, i) => c.name !== FILES[i]))
+    throw new Error('Invalid plan file targets.');
+  for (const change of plan.changes) {
+    if (readSafe(join(plan.root, change.name)) !== change.before)
+      throw new Error(`${change.name} changed since preview; no files written.`);
+  }
+  const touched = [];
+  try {
+    for (const change of plan.changes.filter((c) => c.changed)) {
+      const fd = openSync(join(plan.root, change.name), change.before === null ? 'wx' : 'r+');
+      try {
+        const opened = fstatSync(fd);
+        const current = lstatSync(join(plan.root, change.name));
+        if (
+          !current.isFile() ||
+          current.isSymbolicLink() ||
+          opened.nlink > 1 ||
+          opened.ino !== current.ino ||
+          (process.platform !== 'win32' && opened.dev !== current.dev)
+        )
+          throw new Error('File target changed during apply.');
+        touched.push(change);
+        ftruncateSync(fd, 0);
+        write(fd, change.after, { encoding: 'utf8' });
+      } finally {
+        closeSync(fd);
+      }
+    }
+  } catch {
+    const failed = [];
+    for (const change of touched.reverse()) {
+      const path = join(plan.root, change.name);
+      try {
+        readSafe(path);
+        if (change.before === null) {
+          if (existsSync(path)) unlinkSync(path);
+        } else writeFileSync(path, change.before, 'utf8');
+      } catch {
+        failed.push(change.name);
+      }
+    }
+    throw new Error(
+      `Write failed. Attempted files: ${touched.map((c) => c.name).join(', ')}. ${failed.length ? `Restoration failed for: ${failed.join(', ')}; inspect manually.` : 'All attempted files restored.'}`,
+    );
+  }
+  return plan;
+}

package/templates/AGENTS.md

@@ -0,0 +1,63 @@
+# Kazee Design System consumer rules
+
+Apply these rules to UI work in this application alongside its existing project instructions. Keep the application's established framework, package manager, routing, localization, data flow, and API contracts.
+
+## Check the installed contract first
+
+- Read this application's `package.json` and lockfile before changing UI. Use its installed package version as the API contract.
+- Use the installed version's public catalog. Published 0.2.0 exposes eight components per framework; the prepared 0.3.0 catalog has 32. Do not assume a component exists in an older version.
+- When Kazee MCP is connected, read `get_catalog_versions`, then `list_components`, `get_component_docs`, and `get_component_examples` using this framework and exact installed version. Otherwise inspect the installed package's public types when uncertain. A prop accepted by React Aria, Reka UI, or another UI library is not automatically supported by Kazee components.
+- Start file discovery in application source, manifests, and the installed Kazee package's public entry points/types. Do not recursively list all of `node_modules` or investigate React Aria/Reka UI internals for routine component usage.
+- Investigate dependency internals only when a concrete type, build, or runtime failure remains unexplained by the public contract. Identify that failure and the relevant file before expanding the search. When the requested behavior, build, and typecheck pass, report the result and any unrun checks instead of continuing speculative API research.
+- Browse states in the public [Storybook](https://kazee-design-system-023417.gitlab.io). The catalog may differ from the installed version; check types before copying an example.
+- Follow the [installation guide](https://gitlab.com/kazee.indonesia/kazee-design-system/-/blob/main/docs/installation.md) for package setup. Reading the guide requires GitLab project access; installing packages requires registry credentials. Storybook is public. Never print, commit, or embed registry tokens in frontend code.
+
+## Kazee MCP
+
+MCP is a read-only reference, not an installer or validator. It needs no token at runtime. Never provide token values to a tool. Candidate catalogs do not establish registry publication. Unknown versions must not be silently replaced with newer APIs. Run the application's actual checks after using examples and report missing or unrun validation.
+
+## Reuse the foundation
+
+- Use Kazee `Button` and `Select` for matching new UI in areas adopting this design system. Preserve existing application abstractions that already wrap them correctly.
+- Import from `@kazee-ds/react` or `@kazee-ds/vue` public entry points. Do not copy package source into the application or import private build files.
+- Do not bypass these components by importing React Aria or Reka UI directly to recreate their behavior. Keep unrelated existing integrations outside the task unchanged.
+- Import `@kazee-ds/styles/index.css` once at the application's global CSS entry. It includes the tokens; do not add a duplicate token stylesheet.
+- Use the public props for supported component styling. Do not rely on `className` or `style` on Kazee wrappers, or override their internal classes to create undocumented variants. Style application layout on surrounding elements.
+- Common Button variants include `primary`, `secondary`, and `danger`; sizes are `sm`, `md`, and `lg`. Read the exact versioned contract for additional variants, icon-only and pending support. Defaults are `primary` and `md`; use `danger` for destructive actions.
+
+## React API
+
+- Import `Button` and `Select` from `@kazee-ds/react`.
+- Button activation: `onPress`; disabled state: `isDisabled`. Do not substitute `onClick` or `disabled`.
+- Select requires `label` and `options`. Options have a string `id`, a string `label`, and optional `isDisabled`.
+- Controlled Select: `value` (string or `null`) and `onChange` (receives the selected string ID). Uncontrolled Select: `defaultValue`. Do not mix controlled and uncontrolled state.
+- Use only documented public props. Do not invent `isLoading`, `loading`, `asChild`, `href`, or additional variants.
+
+## Vue API
+
+- Import `Button` and `Select` from `@kazee-ds/vue`.
+- Button activation: `@press`; disabled state: `disabled`. Do not substitute React prop names.
+- Select requires `label` and `options`. Options have a string `id`, a string `label`, and optional `isDisabled` (including in Vue).
+- Controlled Select: `v-model` with a string or `undefined`. Uncontrolled Select: `defaultValue`. Do not mix controlled and uncontrolled state.
+- Use only documented public props. Do not invent `loading`, `asChild`, `href`, or additional variants.
+
+## Tokens, themes, and accessibility
+
+- Use existing semantic color variables for new UI adopting the system, such as `--ds-color-surface-default`, `--ds-color-text-default`, and `--ds-color-border-subtle`. Check the installed token CSS before referencing a variable. Do not invent token names or use primitive color variables as semantic colors.
+- Reuse available spacing and radius tokens, such as `--ds-space-4` and `--ds-radius-md`, where they fit. Follow the application's existing conventions for values the foundation does not yet define.
+- Preserve the application's existing theme mechanism. If integrating Kazee light/dark modes, coordinate `data-theme="light"` or `data-theme="dark"` at the document root so portal content receives the same theme. Do not create a second theme toggle or interpolate unchecked tenant input into CSS.
+- Keep Select's visible label and meaningful Button text. React icon-only buttons need an accessible name via the supported `aria-label` prop; verify the installed contract for other cases.
+- Set Button `type="submit"` explicitly when it submits a form; the default is `button`.
+- Preserve keyboard access, focus indication, disabled states, and the application's translations. For pending requests, use existing application feedback and guard request handlers; do not add unsupported loading props to Kazee components.
+
+## When a component or capability is missing
+
+- State the gap. Use an existing suitable application component or an accessible native element for the requested screen, and use available tokens where appropriate.
+- Keep a necessary fallback local to the application. Do not introduce another component library or redesign unrelated screens as part of routine adoption.
+- A shared Kazee component needs a separate contribution in the design-system repository with a shared React/Vue contract and its quality gates. Do not present an application fallback as a published Kazee component.
+
+## Verify the change
+
+- Run the application's relevant build, typecheck, lint, and existing tests using its own scripts. Do not assume design-system monorepo commands exist here.
+- For changed interactions, check Button activation and disabled behavior, Select selection, and keyboard focus. Check existing light/dark modes and responsive layout where affected.
+- Report what was actually verified and any checks that could not run. These instructions guide agent behavior; they do not install lint rules or enforce CI by themselves.

package/templates/consumer-lint.md

@@ -0,0 +1,135 @@
+# Consumer lint rules
+
+[`@kazee-ds/eslint-config`](../packages/eslint-config) provides a reusable ESLint flat configuration. Version `0.1.0` implements two rules for the Button/Select foundation shipped in React/Vue `0.1.1` and styles/tokens `0.1.2`. It is an ESM package for ESLint 10 and Node 22.16 or later, with TypeScript declarations and no runtime dependencies. Adding `AGENTS.md` alone does not enable these checks.
+
+## Rules
+
+| Rule                   | Reports                                                                                                                                    |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `kazee/public-imports` | Imports from private or nonexistent exports of the four foundation packages, and direct imports from React Aria, React Stately, or Reka UI |
+| `kazee/component-api`  | Selected unsupported props/events and static Button size/variant values on components imported directly from Kazee                         |
+
+The import rule checks static imports, re-exports, literal dynamic imports, and unshadowed literal `require` calls. Public CSS/JSON exports and framework `package.json` exports remain allowed.
+
+The component rule recognizes React JSX imports (including aliases and namespace imports) and Vue SFC `<script setup>` imports used in templates (including aliases, kebab-case names, and namespace imports). It distinguishes local components from imported Kazee components, including React lexical shadowing and Vue template variables.
+
+Examples of reported mistakes:
+
+```tsx
+import { Button } from '@kazee-ds/react';
+
+// Use onPress and isDisabled.
+const save = (
+  <Button onClick={saveWorkspace} disabled={busy}>
+    Save
+  </Button>
+);
+
+// Use primary, secondary, or danger; sm, md, or lg.
+const other = (
+  <Button variant="outline" size="xl">
+    Save
+  </Button>
+);
+```
+
+```vue
+<script setup lang="ts">
+import { Button, Select } from '@kazee-ds/vue';
+</script>
+
+<template>
+  <!-- Use disabled and @press. -->
+  <Button :is-disabled="busy" @click="save">Save</Button>
+  <!-- Use v-model for controlled selection. -->
+  <Select :value="workspace" label="Workspace" :options="options" />
+</template>
+```
+
+The rule also rejects loading props, `asChild`, `href`, and styling props on these Kazee components. Apply application layout and feedback outside the component. It reports diagnostics only; it does not autofix events, change application state, or rewrite imports.
+
+## Enable in a consuming application
+
+Configure authenticated GitLab Registry access using the [installation guide](installation.md). Keep the application's existing ESLint configuration, parsers, plugins, package manager, and lockfile, then install:
+
+```sh
+npm install --save-dev --save-exact @kazee-ds/eslint-config@0.1.0
+```
+
+Merge the configuration object into the application's existing flat config, after its framework/parser setup:
+
+```js
+import { consumerConfig } from '@kazee-ds/eslint-config';
+
+// Add this object to your existing exported flat-config array.
+const kazeeRules = consumerConfig({
+  files: ['src/**/*.{js,jsx,ts,tsx,vue}'],
+});
+```
+
+`kazeeRules` must actually be included in the exported configuration; declaring it alone does not enable anything. Adjust `files` to the application's source directories (for example `app/` or `components/`). Scope it to areas adopting Kazee if the application still has unrelated headless-library integrations. The config intentionally forbids those imports in its selected files.
+
+Use an ESLint 10 flat-config setup with a parser that supports the application's syntax: a TypeScript/JSX parser for React, or `vue-eslint-parser` with its TypeScript parser configured for Vue SFCs. The rules use `context.sourceCode` and Vue parser services; they do not configure parsers or add the general framework lint rules themselves.
+
+Run the application's lint command and ensure it runs in the consuming project's CI. Update the lint package version and lockfile when adopting a different Kazee contract. Existing applications that copied the earlier standalone file can switch their config import to `@kazee-ds/eslint-config`, then remove the unused copy. The monorepo's old `tooling/eslint/consumer.mjs` entry point remains a re-export for compatibility.
+
+### Complete React/TypeScript example
+
+The following minimal `eslint.config.mjs` assumes ESLint 10 and `typescript-eslint` are already installed. Merge the Kazee config into the application's fuller rules rather than discarding its existing checks.
+
+```js
+import tseslint from 'typescript-eslint';
+import { consumerConfig } from '@kazee-ds/eslint-config';
+
+export default [
+  { ignores: ['dist/**', 'node_modules/**'] },
+  ...tseslint.configs.recommended,
+  {
+    files: ['src/**/*.{ts,tsx}'],
+    languageOptions: { parserOptions: { ecmaFeatures: { jsx: true } } },
+  },
+  consumerConfig({ files: ['src/**/*.{ts,tsx}'] }),
+];
+```
+
+### Complete Vue/TypeScript example
+
+This minimal `eslint.config.mjs` assumes ESLint 10, `eslint-plugin-vue`, and `typescript-eslint` are already installed. The application owns the parsers; installing Kazee's lint package does not replace them.
+
+```js
+import tseslint from 'typescript-eslint';
+import vue from 'eslint-plugin-vue';
+import { consumerConfig } from '@kazee-ds/eslint-config';
+
+export default [
+  { ignores: ['dist/**', 'node_modules/**'] },
+  ...tseslint.configs.recommended,
+  ...vue.configs['flat/recommended'],
+  {
+    files: ['**/*.vue'],
+    languageOptions: { parserOptions: { parser: tseslint.parser } },
+  },
+  consumerConfig({ files: ['src/**/*.{ts,vue}'] }),
+];
+```
+
+## Verification in this repository
+
+```sh
+pnpm test:consumer-lint
+pnpm lint
+```
+
+The test suite checks valid usage, reported mistakes, and false-positive cases. It lives in `packages/eslint-config/test` and runs through the normal package tests in CI's `unit-and-packages` job; `test:consumer-lint` remains a focused alias. The root configuration consumes the workspace package for applications and the existing token/style source scope; it keeps headless imports available to the React/Vue package implementations themselves. Manual sandbox projects are excluded from the root lint command, and can be checked separately with a config using the same rules and appropriate parsers.
+
+Version `0.1.0` was published and reinstalled from GitLab in isolated React and Vue consumers. Valid usage passed, incorrect APIs/private imports were rejected, and declarations, typechecks, and builds passed. See the [release and verification record](decisions/0007-eslint-config-private-release.md) for evidence and limits.
+
+## Limits
+
+- This is not full prop/type validation. Keep framework typechecking and interaction tests.
+- Computed import paths, JSX spreads, Vue `v-bind` objects, dynamic directive arguments, and dynamic size/variant values are not evaluated.
+- Components re-exported through an application barrel, Vue Options API registration, globally registered components, and dynamic `<component :is>` usage are outside the initial component rule's scope.
+- Rules do not inspect CSS values, prove a global stylesheet import exists, or require every native Button/Select to be replaced.
+- These checks guide code usage, not whether an agent read its instruction file or searched dependency internals.
+
+See the [agent setup guide](agent-setup.md) for complementary instructions.