@codecademy/gamut 68.6.2-alpha.1fc7ca.0 → 68.6.2-alpha.f8b396.0

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

@@ -0,0 +1,221 @@
+---
+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

@@ -0,0 +1,115 @@
+---
+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

@@ -0,0 +1,98 @@
+---
+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

@@ -0,0 +1,212 @@
+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 };