@codecademy/gamut 68.6.2-alpha.b5fcec.0 → 68.6.2-alpha.d829f9.0

package/agent-tools/skills/gamut-testing/SKILL.md

@@ -1,221 +0,0 @@
----
-name: gamut-testing
-description: Use this skill when writing or fixing unit tests for React components that use Gamut — prefer setupRtl from @codecademy/gamut-tests, harness patterns for useLogicalProperties and ColorMode, RTL/dir testing, emotion matchers, or removing jest.mock of @codecademy/gamut / gamut-styles.
----
-
-# Gamut Testing
-
-Source: `@codecademy/gamut-tests` — [`index.tsx`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-tests/src/index.tsx)
-
----
-
----
-
-## What `MockGamutProvider` does (under `setupRtl`)
-
-`MockGamutProvider` forwards to `GamutProvider` with:
-
-- `useCache={false}` — stable Emotion output across tests
-- `useGlobals={false}` — no global Reboot/Typography bleed between files
-- `theme={theme}` — full token theme for styled components
-- Optional `useLogicalProperties` — forwarded for logical vs physical CSS in variance
-
-You normally do not import `MockGamutProvider` for plain component tests; `setupRtl` already wraps the component under test once. Import it inside a harness when the SUT needs a non-default provider flag or extra wrappers (see below).
-
----
-
-## Decision guide
-
-| Scenario                                                         | Prefer                                                                                                                                                                                                                         |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Default unit test for a Gamut (or app) component                 | `setupRtl(Component, defaultProps)` once per file / describe                                                                                                                                                                   |
-| Vary `useLogicalProperties` across cases                         | Harness that accepts `useLogicalProperties` and wraps `MockGamutProvider`, then `setupRtl(Harness, defaults)`; pass overrides per `it` / `describe.each`                                                                       |
-| Need `ColorMode` (or other context) around the SUT               | Harness with `<ColorMode>` inside the tree, then `setupRtl(Harness)` — no need for raw `render` unless you are testing the provider itself                                                                                     |
-| `dir` / RTL behavior (e.g. mirrored layout, `useElementDir`)     | Keep using `setupRtl` for the component; set `document.documentElement.setAttribute('dir', 'rtl' \| 'ltr')` (and scroll/viewport stubs if needed) in `beforeEach` / `afterEach`; reset `dir` after tests so suites do not leak |
-| Storybook-only mock, chromatic-style wrapper, or non-RTL harness | `MockGamutProvider` (± `ColorMode`) in the exported wrapper component                                                                                                                                                          |
-
----
-
-## `setupRtl` — primary pattern
-
-```tsx
-import { setupRtl } from '@codecademy/gamut-tests';
-
-import { MyComponent } from '../MyComponent';
-
-const renderView = setupRtl(MyComponent, {
-  label: 'Default label',
-  onClick: jest.fn(),
-});
-
-it('renders the label', () => {
-  const { view } = renderView();
-  expect(view.getByText('Default label')).toBeInTheDocument();
-});
-
-it('accepts prop overrides', () => {
-  const { view } = renderView({ label: 'Override' });
-  expect(view.getByText('Override')).toBeInTheDocument();
-});
-```
-
-`renderView` returns `{ view, props, update }`:
-
-- `view` — RTL `RenderResult` (`getByRole`, `getByLabelText`, `getByText`, …)
-- `props` — resolved props (handy for `jest.fn()` assertions)
-- `update` — re-render with new props without remounting
-
-### Query and interaction habits (RTL)
-
-- Prefer `getByRole`, `getByLabelText`, and accessible names over CSS selectors or snapshotting class strings unless you are explicitly testing styling.
-- Prefer `@testing-library/user-event` over `fireEvent` when simulating real input (import `userEvent` from `@testing-library/user-event` in current major versions).
-
-### Accessing mock functions via `props`
-
-```tsx
-import userEvent from '@testing-library/user-event';
-
-it('calls onClick when clicked', async () => {
-  const { view, props } = renderView();
-  await userEvent.click(view.getByRole('button'));
-  expect(props.onClick).toHaveBeenCalled();
-});
-```
-
----
-
-## Harness + `setupRtl` when the wrapper is not default
-
-`setupRtl` always wraps with `MockGamutProvider` with default props. To vary `useLogicalProperties`, add `ColorMode`, or compose other providers, define a small harness and pass `setupRtl` that harness — still one `renderView` factory, still `props` / `update` ergonomics.
-
-### Varying `useLogicalProperties` (logical vs physical CSS)
-
-```tsx
-import { MockGamutProvider, setupRtl } from '@codecademy/gamut-tests';
-
-import { MyComponent } from '../MyComponent';
-
-type HarnessProps = React.ComponentProps<typeof MyComponent> & {
-  useLogicalProperties?: boolean;
-};
-
-const MyHarness = ({ useLogicalProperties, ...rest }: HarnessProps) => (
-  <MockGamutProvider useLogicalProperties={useLogicalProperties}>
-    <MyComponent {...rest} />
-  </MockGamutProvider>
-);
-
-const renderView = setupRtl(MyHarness, { width: '200px' });
-
-describe.each([
-  { useLogicalProperties: true as const, widthProp: 'inlineSize' as const },
-  { useLogicalProperties: false as const, widthProp: 'width' as const },
-])(
-  'useLogicalProperties=$useLogicalProperties',
-  ({ useLogicalProperties, widthProp }) => {
-    it(`uses ${widthProp}`, () => {
-      const { view } = renderView({ useLogicalProperties });
-      expect(view.getByTestId('my-component-root')).toHaveStyle({
-        [widthProp]: '200px',
-      });
-    });
-  }
-);
-```
-
-The outer `setupRtl` wrapper adds a default `MockGamutProvider`; the harness’s inner `MockGamutProvider` sets `useLogicalProperties` for the subtree under test (nested `GamutProvider` / theme is the nearest one Emotion and variance see).
-
-### `ColorMode` without abandoning `setupRtl`
-
-```tsx
-import { ColorMode } from '@codecademy/gamut-styles';
-import { setupRtl } from '@codecademy/gamut-tests';
-
-const DarkHarness = (props: React.ComponentProps<typeof MyComponent>) => (
-  <ColorMode mode="dark">
-    <MyComponent {...props} />
-  </ColorMode>
-);
-
-const renderDark = setupRtl(DarkHarness, { title: 'Hi' });
-```
-
-Use `MockGamutProvider` only inside the harness if you also need a non-default Gamut flag and `ColorMode` in the same tree; otherwise `setupRtl(DarkHarness)` is enough.
-
----
-
-## Raw `render` + `MockGamutProvider` — rare
-
-Reserve `render` from `@testing-library/react` + manual `MockGamutProvider` for cases where a harness would be more obscure than a single inline tree (e.g. highly dynamic one-off trees). If the same wrapper appears more than once, switch to a harness + `setupRtl`.
-
----
-
-## RTL / `dir` and document-level behavior
-
-Some components (e.g. overlays that call `useElementDir`) resolve direction from `document.documentElement` when there is no real target node. For those tests:
-
-- Set `document.documentElement.setAttribute('dir', 'rtl')` (or `'ltr'`) around the scenario, `unmount` between LTR and RTL assertions when re-rendering, and restore `dir` in `afterEach` so other tests start clean.
-- Combine with the harness pattern above when `useLogicalProperties` affects which longhand wins (`left` vs `insetInlineStart`, etc.).
-
----
-
-## Emotion style assertions
-
-Install `@emotion/jest` matchers if you absolutely need to enable CSS-in-JS assertions:
-
-```tsx
-import { matchers } from '@emotion/jest';
-
-expect.extend(matchers);
-```
-
-Then assert on styles:
-
-```tsx
-expect(element).toHaveStyle({ borderRadius: '2px' });
-expect(element).toHaveStyleRule('padding', '1rem');
-```
-
-Use `theme` from `@codecademy/gamut-styles` instead of hardcoding token strings:
-
-```tsx
-import { theme } from '@codecademy/gamut-styles';
-
-expect(element).toHaveStyle({ columnGap: theme.spacing[40] });
-```
-
----
-
-## Visual test wrappers and Storybook
-
-Exported mocks and stories may wrap with `MockGamutProvider` and `ColorMode` explicitly (no `setupRtl` in Storybook):
-
-```tsx
-import { MockGamutProvider } from '@codecademy/gamut-tests';
-import { ColorMode } from '@codecademy/gamut-styles';
-
-export const MyComponentMock: React.FC<ComponentProps<typeof MyComponent>> = (
-  props
-) => (
-  <MockGamutProvider>
-    <ColorMode mode="light">
-      <MyComponent {...props} />
-    </ColorMode>
-  </MockGamutProvider>
-);
-```
-
----
-
-## Common anti-patterns
-
-| Anti-pattern                                                      | Fix                                                                                                |
-| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `jest.mock('@codecademy/gamut', () => ({ ... }))`                 | Remove; use `setupRtl` (or harness + `setupRtl`)                                                   |
-| `jest.mock('@codecademy/gamut-styles', ...)`                      | Remove; `MockGamutProvider` / `setupRtl` supplies theme                                            |
-| `GamutProvider` in test files                                     | Use `MockGamutProvider` only when building a harness or story; default tests go through `setupRtl` |
-| `import { setupRtl } from 'component-test-setup'` in Gamut / apps | Import `setupRtl` from `@codecademy/gamut-tests` so `MockGamutProvider` is applied                 |
-| Repeated `render(<MockGamutProvider>…`                            | Harness + `setupRtl`, or a shared `renderView` factory                                             |
-| One `setupRtl` call per `it`                                      | Define `renderView` once outside `describe`, call it inside each `it`                              |
-| Asserting raw CSS strings for tokens                              | Use `theme` from `@codecademy/gamut-styles`                                                        |
-| Leaking `dir="rtl"` between tests                                 | Reset `document.documentElement` in `afterEach`                                                    |

package/agent-tools/skills/gamut-theming/SKILL.md

@@ -1,115 +0,0 @@
----
-name: gamut-theming
-description: Use this skill when choosing or extending Gamut themes (Core, Admin, Platform, LX Studio, Percipio), wiring GamutProvider and Emotion theme TypeScript augmentation, or following CreatingThemes — not for day-to-day css(), variant(), or states() patterns (see gamut-style-utilities).
----
-
-# Gamut Theming
-
-Source: `@codecademy/gamut-styles`
-
-See also: [`gamut-style-utilities`](../gamut-style-utilities/SKILL.md) (`css`, `variant`, `states`, `StyleProps`, `useTheme` escape hatch). [`gamut-color-mode`](../gamut-color-mode/SKILL.md) (semantic color, `<ColorMode>`, `<Background>`). [`gamut-system-props`](../gamut-system-props/SKILL.md) (`system.*`, responsive `Box` props).
-
-## Overview
-
-Gamut uses Emotion's theme system. Themes are org-specific token bundles (colors, typography, spacing, etc.). The active theme is set at the app root with `<GamutProvider theme={...}>`; child styled components read tokens through Emotion context.
-
-For authoring component styles (`css`, `variant`, `states`, system props, ColorMode), use the skills linked above and the styleguide [Best practices](https://gamut.codecademy.com/?path=/docs-meta-best-practices--page).
-
-## Install
-
-```sh
-yarn add @codecademy/gamut-kit @emotion/react @emotion/styled
-```
-
-`gamut-kit` bundles `gamut`, `gamut-icons`, `gamut-illustrations`, `gamut-patterns`, `gamut-styles`, `variance`, and `gamut-tests`.
-
-Full guide: [Meta / Installation](https://gamut.codecademy.com/?path=/docs-meta-installation--page) in Storybook (CSP `nonce` on `GamutProvider`, Jest, Next/Gatsby entry points).
-
-Optionally add a `peerDependencies` block in `package.json` listing `@codecademy/gamut`, `@codecademy/gamut-icons`, `@codecademy/gamut-illustrations`, `@codecademy/gamut-patterns`, `@codecademy/gamut-styles`, `@codecademy/gamut-tests`, and `@codecademy/variance` (e.g. `"*"`) so editors surface those packages — see Meta / Installation for the JSON snippet.
-
-## Required wrapper
-
-Wrap the app root in `<GamutProvider>` from `@codecademy/gamut-styles`. This wires up the theme, color mode, and logical properties for all child components.
-
-At runtime, `GamutProvider` defaults to Core when `theme` is omitted (`theme = coreTheme` in the implementation). For non-Core products and for TypeScript (`theme` is required on `GamutProviderProps`), pass `theme` explicitly using the table below.
-
-```tsx
-import { GamutProvider, theme } from '@codecademy/gamut-styles';
-
-const App = () => (
-  <GamutProvider theme={theme}>{/* app content */}</GamutProvider>
-);
-```
-
-## Available themes
-
-| Theme     | Used for                                                   | Import from `@codecademy/gamut-styles` |
-| --------- | ---------------------------------------------------------- | -------------------------------------- |
-| Core      | Codecademy default                                         | `coreTheme` or `theme` (default)       |
-| Admin     | Codecademy admin tools                                     | `adminTheme`                           |
-| Platform  | Codecademy learning environment / shared platform surfaces | `platformTheme`                        |
-| LX Studio | Learning Experience Studio                                 | `lxStudioTheme`                        |
-| Percipio  | Skillsoft Percipio platform                                | `percipioTheme`                        |
-
-## TypeScript (`theme.d.ts`)
-
-Augment `@emotion/react` so `props.theme` in `styled` / `css` matches the same theme object you pass to `<GamutProvider theme={...}>`. If the types disagree, system props and token autocomplete will not line up with runtime.
-
-Add a root `theme.d.ts` (or merge into your existing global types):
-
-```tsx
-// theme.d.ts
-import '@emotion/react';
-
-import type { CoreTheme } from '@codecademy/gamut-styles';
-
-declare module '@emotion/react' {
-  export interface Theme extends CoreTheme {}
-}
-```
-
-Use the theme interface that matches your provider:
-
-| `GamutProvider` `theme` prop | Import for `Theme extends …` |
-| ---------------------------- | ---------------------------- |
-| `theme` or `coreTheme`       | `CoreTheme`                  |
-| `adminTheme`                 | `AdminTheme`                 |
-| `platformTheme`              | `PlatformTheme`              |
-| `lxStudioTheme`              | `LxStudioTheme`              |
-| `percipioTheme`              | `PercipioTheme`              |
-
-Example when the app uses Percipio:
-
-```tsx
-// theme.d.ts
-import '@emotion/react';
-
-import type { PercipioTheme } from '@codecademy/gamut-styles';
-
-declare module '@emotion/react' {
-  export interface Theme extends PercipioTheme {}
-}
-```
-
-See Emotion’s [TypeScript / define a theme](https://emotion.sh/docs/typescript#define-a-theme) for details.
-
-## Theme vs color mode vs style API
-
-| Concern                                                 | Where to read           |
-| ------------------------------------------------------- | ----------------------- |
-| Which `theme` object to pass to `GamutProvider`         | This skill              |
-| Light / dark semantic colors, `ColorMode`, `Background` | `gamut-color-mode`      |
-| `css` / `variant` / `states`, `useTheme` for non-CSS JS | `gamut-style-utilities` |
-| Composed `system.*` props on styled primitives / `Box`  | `gamut-system-props`    |
-| Spacing, breakpoints, page grid                         | `gamut-layout`          |
-
-## Creating a new theme
-
-See [Creating Themes](https://gamut.codecademy.com/?path=/docs-foundations-theme-creating-themes--docs) in Storybook. Themes are defined in `@codecademy/gamut-styles` and must extend the base theme shape with all required token keys.
-
-## Key principles
-
-- Pick the correct theme export for the product so tokens and fonts match design intent.
-- Align `theme.d.ts` / `Theme extends …` with the same theme interface you pass to `GamutProvider`.
-- Components stay portable across themes when they use token and semantic aliases rather than one-off hex; authoring rules live in `gamut-style-utilities` and `gamut-color-mode`.
-- `GamutProvider` wires theme, color mode, and logical-properties settings at the root; individual components should not hard-code which org theme is active.

package/agent-tools/skills/gamut-typography/SKILL.md

@@ -1,98 +0,0 @@
----
-name: gamut-typography
-description: Use this skill when creating or reviewing UI text in Gamut apps — headlines, body, captions, labels, code snippets, or text-heavy layouts. Covers theme-specific stacks (Core Apercu/Suisse vs Percipio/LX Skillsoft), fontSize / lineHeight tokens, semantic fontWeight title (700 vs 500), line length, and alignment for Codecademy-branded surfaces.
----
-
-# Gamut Typography
-
-Implementation source of truth: [`packages/gamut-styles/src/variables/typography.ts`](https://github.com/Codecademy/gamut/blob/main/packages/gamut-styles/src/variables/typography.ts) and themes under [`packages/gamut-styles/src/themes`](https://github.com/Codecademy/gamut/tree/main/packages/gamut-styles/src/themes).
-
-## Scope by theme
-
-| Themes                | `fontFamily.base`                        | `fontFamily.accent`                       | `fontWeight.title` |
-| --------------------- | ---------------------------------------- | ----------------------------------------- | ------------------ |
-| Core, Admin, Platform | Apercu stack                             | Suisse + Apercu stack                     | 700                |
-| Percipio              | Skillsoft Text                           | Skillsoft Sans; `monospace` → Roboto Mono | 500                |
-| LX Studio             | Skillsoft Text / Sans (same as Percipio) | Same                                      | 500                |
-
-Admin and Platform extend Core for colors / modes only — typography matches Core.
-
-Licensing: Apercu is licensed for Codecademy surfaces only; Skillsoft products use Percipio/LX stacks.
-
-Use `fontWeight="title"` for headlines / emphasis roles — never hardcode `700` on Percipio/LX unless SPECIFICALLY noted in Figma designs.
-
-## Font weight (semantic)
-
-| Token   | Core / Admin / Platform | Percipio / LX Studio |
-| ------- | ----------------------- | -------------------- |
-| `base`  | 400                     | 400                  |
-| `title` | 700                     | 500                  |
-
-Headlines, CTAs, and buttons should use `fontWeight="title"` so Percipio/LX get 500, Core gets 700. Literal `700` breaks Skillsoft branding on those themes.
-
-## Font size scale (`fontSize`)
-
-Theme keys: `64`, `44`, `34`, `26`, `22`, `20`, `18`, `16`, `14`.
-
-```tsx
-import { css } from '@codecademy/gamut-styles';
-import styled from '@emotion/styled';
-import { system } from '@codecademy/gamut-styles';
-
-const Paragraph = styled.p(system.typography);
-<Paragraph fontSize={16} lineHeight="base" />;
-
-const Styled = styled.div(css({ fontSize: 14, fontFamily: 'base' }));
-```
-
-## Line height (`lineHeight`)
-
-Tokens: `base` (1.5), `spacedTitle` (1.3), `title` (1.2). Prefer tokens over raw decimals. Only specify `lineHeight` when specified by design.
-
-## Line length
-
-| Context            | Target                   |
-| ------------------ | ------------------------ |
-| Single-column body | ~66 characters (max ~85) |
-| Multi-column       | ≤50 characters per line  |
-| Minimum            | ~45 characters           |
-
-## Accessing typography tokens
-
-```tsx
-import { system } from '@codecademy/gamut-styles';
-import { variance } from '@codecademy/variance';
-
-const Heading = styled.h2(variance.compose(system.typography, system.space));
-
-<Heading
-  fontSize={26}
-  fontFamily="base"
-  fontWeight="title"
-  lineHeight="title"
-  mb={8}
-/>;
-
-import { css } from '@codecademy/gamut-styles';
-
-const Caption = styled.span(
-  css({ fontFamily: 'accent', fontSize: 14, color: 'text-secondary' })
-);
-```
-
-Prefer `<Text>` from `@codecademy/gamut` with `variant` / `as` — see Storybook [Typography / Text](https://gamut.codecademy.com/?path=/docs-typography-text--docs).
-
-## Codecademy (Core / Admin / Platform) — voice and layout
-
-Do not blindly apply to Percipio/LX without brand guidance.
-
-- `fontFamily="base"` (Apercu): default UI and marketing type. Emphasis inside body copy: Italic, not Bold for intra-paragraph stress.
-- `fontFamily="accent"` (Suisse stack): technical accent — code snippets, captions, labels. Use sparingly; glyph box reads larger — step down ~10–15% vs equivalent `base` size.
-- Alignment: left-align by default; center only short marketing headlines; avoid right-align except tabs / numerics.
-- Letter-spacing: do not tweak tracking unless design specifies.
-
-## Semantic vs visual headings
-
-- `<Text as="h1">` … `<Text as="h6">` gets default heading styles: each tag maps to the same scale as `variant="title-xxl"` … `variant="title-xs"` (`h1` largest through `h6` smallest). Plain `<Text>` defaults to `as="span"` (inherits font size).
-- Use `variant` plus `fontSize` / `fontWeight` / `lineHeight` (and other system props) to override element defaults when the outline needs one heading level but the UI needs another visual weight — e.g. `<Text as="h2" variant="title-sm">`.
-- Still pick `h1`–`h6` for document structure and assistive tech; overrides are for intentional divergence between semantics and appearance.

package/bin/commands/plugin/install.mjs

@@ -1,212 +0,0 @@
-import { cp, mkdir, readdir, rm, symlink } from 'node:fs/promises';
-import { resolve } from 'node:path';
-
-import { claudePluginSpec, marketplaceName } from '../../lib/claude.mjs';
-import { cursorDestPath } from '../../lib/cursor.mjs';
-import {
-  installDesignMd,
-  listCanonicalThemes,
-  resolveTheme,
-} from '../../lib/design.mjs';
-import { log, warn } from '../../lib/io.mjs';
-import { getFlag, resolvePluginDir } from '../../lib/resolve-plugin-dir.mjs';
-import { runCommand } from '../../lib/run-command.mjs';
-
-export const TARGETS = ['cursor', 'claude'];
-export const SCOPES = ['all', 'skills', 'rules', 'agents'];
-
-export function help() {
-  log(`
-Usage:
-  gamut plugin install [target] [options]
-
-Install the Gamut plugin into an AI tool.
-
-Arguments:
-  target               Tool to install into (default: cursor)
-                       cursor | claude
-
-Options:
-  --scope <scope>      Content to install (default: all)
-                       all | skills | rules | agents
-  --theme <theme>      Copy DESIGN.*.md to ./DESIGN.md in the current directory
-                       core | admin | platform | percipio | lxstudio
-                       (admin/platform use Codecademy DESIGN; aliases: codecademy, cc, lx-studio)
-  --force              Overwrite existing DESIGN.md when using --theme
-  --plugin-dir <path>  Override the bundled agent-tools directory
-  -h, --help           Show this help message
-
-Examples:
-  gamut plugin install
-  gamut plugin install claude
-  gamut plugin install cursor --theme core
-  gamut plugin install cursor --theme percipio --force
-  gamut plugin install cursor --scope skills
-  gamut plugin install cursor --plugin-dir ./my-agent-tools
-`);
-}
-
-// ---------------------------------------------------------------------------
-
-/** Directories in the plugin source that should not be installed to Cursor. */
-const CURSOR_IGNORE = new Set([
-  '.claude-plugin', // Claude Code manifest — not a Cursor concept
-]);
-
-/** @param {string} sourceRoot @param {string} scope */
-async function installCursor(sourceRoot, scope) {
-  const dest = await cursorDestPath(sourceRoot);
-
-  if ((process.env.CURSOR_INSTALL_METHOD ?? 'copy') !== 'copy') {
-    // Symlink the whole plugin dir (dev convenience)
-    await rm(dest, { recursive: true, force: true });
-    await symlink(resolve(sourceRoot), dest, 'dir');
-    log(`Cursor: symlinked to ${dest}`);
-    return;
-  }
-
-  // Selective copy: always include the cursor manifest, then scoped content dirs
-  await rm(dest, { recursive: true, force: true });
-  await mkdir(dest, { recursive: true });
-
-  await cp(`${sourceRoot}/.cursor-plugin`, `${dest}/.cursor-plugin`, {
-    recursive: true,
-  });
-
-  let dirs;
-  if (scope === 'all') {
-    const entries = await readdir(sourceRoot, { withFileTypes: true });
-    dirs = entries
-      .filter(
-        (e) =>
-          e.isDirectory() &&
-          !e.name.startsWith('.') &&
-          !CURSOR_IGNORE.has(e.name)
-      )
-      .map((e) => e.name);
-  } else {
-    dirs = [scope];
-  }
-
-  await Promise.all(
-    dirs.map((dir) =>
-      cp(`${sourceRoot}/${dir}`, `${dest}/${dir}`, { recursive: true }).catch(
-        () => {
-          // directory may be empty/missing — not an error
-        }
-      )
-    )
-  );
-
-  const scopeLabel = scope === 'all' ? 'all content' : scope;
-  log(`Cursor: installed (${scopeLabel}) → ${dest}`);
-}
-
-// Claude Code loads skills/, agents/ from the plugin source. rules/ is Cursor-specific
-// (.mdc format). Claude marketplace registers the full sourceRoot.
-
-/** @param {string} sourceRoot */
-async function installClaude(sourceRoot) {
-  const spec = await claudePluginSpec(sourceRoot);
-  const mpName = marketplaceName(spec);
-  const root = resolve(sourceRoot);
-
-  let code = await runCommand('claude', [
-    'plugin',
-    'marketplace',
-    'add',
-    root,
-    '--scope',
-    'user',
-  ]);
-  if (code !== 0) {
-    warn(
-      `warning: "claude plugin marketplace add" exited ${code} — ` +
-        `if it's already registered this is safe to ignore.`
-    );
-    code = await runCommand('claude', [
-      'plugin',
-      'marketplace',
-      'update',
-      mpName,
-    ]);
-    if (code !== 0) {
-      throw new Error(
-        `claude plugin marketplace add/update failed (exit ${code}).\n` +
-          `Try manually: claude plugin marketplace add ${root}`
-      );
-    }
-  }
-
-  code = await runCommand('claude', [
-    'plugin',
-    'install',
-    spec,
-    '--scope',
-    'user',
-  ]);
-  if (code !== 0) {
-    throw new Error(
-      `claude plugin install failed (exit ${code}).\n` +
-        `Try manually: claude plugin install ${spec} --scope user`
-    );
-  }
-
-  log(`Claude Code: installed ${spec} (user scope)`);
-  log(
-    `  Tip: run /reload-plugins in Claude Code if skills don't appear immediately.`
-  );
-  log(`  One-off without install: claude --plugin-dir ${root}`);
-}
-
-// ---------------------------------------------------------------------------
-
-/**
- * gamut plugin install [cursor|claude] [--scope all|skills|rules|agents]
- *                                            [--plugin-dir <path>]
- *
- * @param {string[]} args
- */
-export default async function install(args) {
-  const target = args.find((a) => !a.startsWith('-')) ?? 'cursor';
-  const scope = getFlag(args, '--scope', 'all') ?? 'all';
-
-  if (!TARGETS.includes(target)) {
-    throw new Error(
-      `Unknown target: "${target}". Choose from: ${TARGETS.join(', ')}`
-    );
-  }
-  if (!SCOPES.includes(scope)) {
-    throw new Error(
-      `Unknown scope: "${scope}". Choose from: ${SCOPES.join(', ')}`
-    );
-  }
-
-  const pluginDir = await resolvePluginDir(args);
-  const theme = getFlag(args, '--theme');
-  const force = args.includes('--force');
-
-  if (theme) {
-    resolveTheme(theme);
-  }
-
-  if (target === 'cursor') {
-    await installCursor(pluginDir, scope);
-  } else if (target === 'claude') {
-    await installClaude(pluginDir);
-  }
-
-  if (theme) {
-    const { dest, label } = await installDesignMd(
-      pluginDir,
-      process.cwd(),
-      theme,
-      {
-        force,
-      }
-    );
-    log(`DESIGN.md: installed (${label}) → ${dest}`);
-  }
-}
-
-export { listCanonicalThemes };