@machinemetrics/mm-react-components 1.0.0-rc.1 → 1.0.0-rc.2

package/agent-docs/ai-agent-init-guide.md

@@ -38,7 +38,8 @@ The init script performs minimal automated setup:
 
 1. **Installs the component library** - `@machinemetrics/mm-react-components`
 2. **Creates/updates CSS import** - Adds `/styles` import with pre-compiled CSS
-3. **Done!** - No build tools, no configuration files needed
+3. **Optional: Carbide AI skill** - If you say yes, you choose tool (Cursor, Copilot, Claude, Gemini) and scope: **project** (this repo only) or **user** (global, all projects)
+4. **Done!** - No build tools, no configuration files needed
 
 ### What's Included
 
@@ -137,7 +138,6 @@ your-project/
 ├── src/
 │   ├── index.css (with @import '.../styles')
 │   └── App.tsx (root with className="carbide")
-├── mm-components-examples/   (if you ran mm-init)
 ├── package.json
 └── node_modules/
     └── @machinemetrics/mm-react-components/
@@ -303,7 +303,7 @@ npx @machinemetrics/mm-react-components mm-init
 // Ensure carbide class is applied to root element
 <div className="carbide">
   <YourApp />
-</div>;
+</div>
 ```
 
 ### Issue: Build errors with TypeScript

package/agent-docs/cursor-skill-mm-carbide.md

@@ -38,20 +38,20 @@ npx @machinemetrics/mm-react-components mm-install-skill --target=copilot --scop
 
 **Options**
 
-| Option | Values | Default | Description |
-|--------|--------|---------|-------------|
-| `--target` | `cursor`, `copilot`, `claude`, `gemini` | `cursor` | Which tool’s skill directory to use |
-| `--scope` | `project`, `user` | `project` | Project/workspace directory (cwd) or user home |
-| `--force` | — | — | Overwrite even when version matches (skip version check) |
+| Option     | Values                                  | Default   | Description                                              |
+| ---------- | --------------------------------------- | --------- | -------------------------------------------------------- |
+| `--target` | `cursor`, `copilot`, `claude`, `gemini` | `cursor`  | Which tool’s skill directory to use                      |
+| `--scope`  | `project`, `user`                       | `project` | Project/workspace directory (cwd) or user home           |
+| `--force`  | —                                       | —         | Overwrite even when version matches (skip version check) |
 
 **Paths by target (project vs user)**
 
-| Target | Project (cwd) | User (home) |
-|--------|----------------|-------------|
-| cursor | `.cursor/skills/mm-carbide` | `~/.cursor/skills/mm-carbide` |
+| Target  | Project (cwd)               | User (home)                    |
+| ------- | --------------------------- | ------------------------------ |
+| cursor  | `.cursor/skills/mm-carbide` | `~/.cursor/skills/mm-carbide`  |
 | copilot | `.github/skills/mm-carbide` | `~/.copilot/skills/mm-carbide` |
-| claude | `.claude/skills/mm-carbide` | `~/.claude/skills/mm-carbide` |
-| gemini | `.gemini/skills/mm-carbide` | `~/.gemini/skills/mm-carbide` |
+| claude  | `.claude/skills/mm-carbide` | `~/.claude/skills/mm-carbide`  |
+| gemini  | `.gemini/skills/mm-carbide` | `~/.gemini/skills/mm-carbide`  |
 
 Re-running the same command checks the installed skill version against the package version and updates the skill if the package is newer. To get the latest skill after upgrading the package, run `npm update @machinemetrics/mm-react-components` (if desired) then `npx @machinemetrics/mm-react-components mm-install-skill` again (with the same `--target`/`--scope` if you use them).
 
@@ -61,7 +61,9 @@ The skill triggers when the user asks to create or generate a UI, widget, screen
 
 ## Contents
 
-- **SKILL.md** — Main instructions: components (only library exports, compound components, `cn()`, `data-slot`), widget rules (visual-first, 80/20, insight-driven), technical (dimensions, responsive, containment, no hallucinated data), and optional version check at use time.
-- **reference.md** — Key exports and patterns (PageHeader, DataTable, Form, ChartContainer, etc.) and a short widget rules summary (when to use charts vs metrics, accessibility).
+- **SKILL.md** — Main instructions: components (only library exports, compound components, `cn()`, `data-slot`); **theme and styling** (CSS variables only, variants, layout, `.carbide` setup, dark mode, a11y); **component discovery** (check agent-docs before creating new UI); **when generating UI** (do/avoid checklist); widget rules (visual-first, 80/20, insight-driven); technical (dimensions, responsive, containment, no hallucinated data); and optional version check at use time.
+- **reference.md** — **Styling and conventions** (tokens, variants, layout, setup); **component discovery** (agent-docs index); key exports and patterns (PageHeader, DataTable, Form, ChartContainer, etc.); short widget rules summary (when to use charts vs metrics, accessibility).
 
 Full widget and visualization rules are in the skill as **widget-rules.md** (installed with the skill). In this repo, see [cursor-skill/mm-carbide/widget-rules.md](../cursor-skill/mm-carbide/widget-rules.md).
+
+For which app rules were migrated into the skill, see [docs/RULE_MIGRATION_TO_CARBIDE_SKILL.md](../docs/RULE_MIGRATION_TO_CARBIDE_SKILL.md).

package/agent-docs/init-readme.md

@@ -15,7 +15,7 @@ This directory contains comprehensive documentation and tools for setting up the
 
 ### Scripts and Tools
 
-- **mm-init** – Package bin (run via `npx @machinemetrics/mm-react-components mm-init`). Uses `npx-init.cjs` under the hood and installs the library, adds `/styles` import, creates examples, and optionally installs the Carbide skill or runs Chakra migration.
+- **mm-init** – Package bin (run via `npx @machinemetrics/mm-react-components mm-init`). Uses `scripts/init.cjs`; installs the library, adds `/styles` import, creates examples, and optionally installs the Carbide skill (project or user/global) or runs Chakra migration.
 
 ## Quick Start
 
@@ -23,7 +23,13 @@ This directory contains comprehensive documentation and tools for setting up the
 
 ```bash
 # From your React project root (run via npx; no install needed)
+npx @machinemetrics/mm-react-components
+
+# Or explicitly:
 npx @machinemetrics/mm-react-components mm-init
+
+# If you see "could not determine executable to run", use:
+npx -p @machinemetrics/mm-react-components mm-init
 ```
 
 ### 2. Manual Setup (Complete Control)
@@ -41,8 +47,7 @@ Follow the detailed instructions in `ai-agent-init-guide.md` for step-by-step ma
 ### What mm-init Does
 
 - Installs the library and adds the pre-compiled CSS import to your `index.css` (or creates it).
-- Creates example components in `mm-components-examples/`.
-- Optionally installs the Carbide AI skill and offers Chakra UI migration if detected.
+- Optionally installs the Carbide AI skill (project-only or user/global) and offers Chakra UI migration if detected.
 
 ### Project Structure (zero-config)
 
@@ -51,7 +56,6 @@ your-project/
 ├── src/
 │   ├── index.css (with @import '.../styles')
 │   └── App.tsx (add className="carbide" to root)
-├── mm-components-examples/   (created by mm-init)
 ├── package.json
 └── node_modules/
     └── @machinemetrics/mm-react-components/

package/agent-docs/init-troubleshooting.md

@@ -4,6 +4,25 @@
 
 ### 1. Script Execution Issues
 
+#### Error: `npm error could not determine executable to run`
+
+**Cause**: Some npm/npx versions cannot pick a binary when the package has multiple bin entries and no command is given, or when the package is resolved from a local/cached copy that lacks the expected layout.
+
+**Solution**:
+
+```bash
+# Option 1: Run without a command (uses default init binary)
+npx @machinemetrics/mm-react-components
+
+# Option 2: Explicitly specify the package and command
+npx -p @machinemetrics/mm-react-components mm-init
+
+# Option 3: Pin version and run
+npx @machinemetrics/mm-react-components@latest mm-init
+```
+
+If you are inside a project that has `@machinemetrics/mm-react-components` as a dependency, npx may use that copy instead of the registry; the local copy may not have been built with bin scripts. Use Option 2 from the project root or a folder that does not have the package in `node_modules`.
+
 #### Error: `npx: command not found`
 
 **Cause**: NPX not installed or not in PATH.

package/dist/cursor-skill/mm-carbide/SKILL.md

@@ -8,10 +8,31 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
 ## Components
 
 - Use **only** exports from `@machinemetrics/mm-react-components`. Do not create new components or use other UI libraries.
-- Use compound components as in the library: Dialog + DialogTrigger + DialogContent; Form + FormField; DataTable + column descriptors; Sheet, DropdownMenu, Tabs, etc.
+- Use compound components as in the library: Dialog + DialogTrigger + DialogContent; Form + FormField; DataTable + column descriptors; Card + CardHeader + CardContent + CardFooter; Sheet, DropdownMenu, Tabs, etc. Never replace them with raw divs and custom classes.
 - Use `cn()` from the library and Tailwind for layout and styling. Respect `data-slot` for Carbide theming where applicable.
 - For a component list and patterns, see [reference.md](reference.md). For full widget and visualization rules, see [widget-rules.md](widget-rules.md).
 
+## Theme and styling
+
+- **CSS variables only.** Never hardcode colors, spacing, radii, or shadows. Use semantic tokens: `--background`, `--foreground`, `--primary`, `--muted`, `--muted-foreground`, `--destructive`, `--border`, `--ring`, etc.
+- **Variants over one-off styles.** Use component variants and sizes (e.g. Button: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"`). Do not apply brand colors or one-off Tailwind color classes to components.
+- **Layout.** Use Flexbox/Grid and `gap-*` for spacing; avoid manual margin chains. Prefer `className="flex flex-col gap-4"` (or similar) over stacking margins.
+- **App setup.** Consumers must import the library styles and wrap the app (or Carbide subtree) in an element with class `carbide` so the theme applies. See [reference.md](reference.md) for setup.
+- **Dark mode.** All styling must work in both light and dark mode via CSS variables; do not hardcode colors that break theme switching.
+- **Accessibility.** Use visible focus states, keyboard support, and semantic structure; avoid relying on color alone.
+
+## Component discovery
+
+**When the package is installed in this project:** Check the package’s **agent-docs** at `node_modules/@machinemetrics/mm-react-components/agent-docs/` (start with **agent-documentation-reference.md**). Prefer using or composing library components over building from scratch.
+
+**When the package is not installed in this workspace:** agent-docs will not exist. Use this skill’s [reference.md](reference.md) for components and patterns and [widget-rules.md](widget-rules.md) for widget rules. Recommend the user install the package in the project (`npx @machinemetrics/mm-react-components mm-init` or `npm install @machinemetrics/mm-react-components`) so full docs and setup guides are available.
+
+## When generating UI
+
+**Do:** Import from the library; use compound components and variants; use Tailwind for layout and spacing; include proper TypeScript types and accessibility (focus, ARIA where needed).
+
+**Avoid:** Hardcoded colors (e.g. `bg-blue-600`, `text-gray-500`); inline brand styling; non-semantic HTML; missing focus or labels on interactive elements.
+
 ## Widget rules
 
 - **Visual, not textual**: Every widget must include at least one chart, graph, or visual data representation. Text is for titles, labels, and brief annotations only (80% visuals / 20% text max).
@@ -26,7 +47,9 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
 
 ## Setup, init, and migration
 
-For **project setup**, **initialization** (`mm-init`), **Chakra UI migration**, or the **full documentation index**, use the package’s **agent-docs** (shipped with the package). When the package is installed: `node_modules/@machinemetrics/mm-react-components/agent-docs/`. Start with **agent-documentation-reference.md** for the index; use **ai-agent-init-guide.md** for setup and **ai-agent-guide.md** (and chakra-migration-*) for migration.
+**When the package is installed in this project:** Use the package’s **agent-docs** at `node_modules/@machinemetrics/mm-react-components/agent-docs/` for setup, initialization (`mm-init`), Chakra UI migration, and the full doc index. Start with **agent-documentation-reference.md**; use **ai-agent-init-guide.md** for setup and **ai-agent-guide.md** (and chakra-migration-\*) for migration.
+
+**When the package is not installed:** agent-docs is not available. Recommend running `npx @machinemetrics/mm-react-components mm-init` from the project root (or `npm install @machinemetrics/mm-react-components` then adding the styles import and `.carbide` class). After install, agent-docs will be in node_modules for full guides.
 
 ## Version check while using
 

package/dist/cursor-skill/mm-carbide/reference.md

@@ -1,5 +1,18 @@
 # mm-carbide reference
 
+## Styling and conventions
+
+- **Colors and tokens:** Use only CSS variables / semantic tokens (e.g. `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`, `text-destructive`). Never use raw Tailwind color classes like `bg-blue-600` or `text-gray-500`.
+- **Variants and sizes:** Use component props: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"` where supported. Same variant names apply across Button, Badge, and other components.
+- **Layout:** Use `flex`, `grid`, and `gap-*` for spacing; avoid ad-hoc margins between siblings.
+- **Setup:** Import library styles (e.g. `import '@machinemetrics/mm-react-components/styles'`) and wrap the app (or Carbide root) in `<div className="carbide">` so the theme and fonts apply.
+
+## Component discovery
+
+**When the package is installed in this project:** Check **agent-docs** at `node_modules/@machinemetrics/mm-react-components/agent-docs/`; use **agent-documentation-reference.md** as the index for existing components and patterns.
+
+**When the package is not installed in this workspace:** agent-docs is not present. Use this reference and [widget-rules.md](widget-rules.md); recommend installing the package in the project (`mm-init` or `npm install @machinemetrics/mm-react-components`) for the full doc set.
+
 ## Key exports (from @machinemetrics/mm-react-components)
 
 Import from the package main entry (see `src/index.ts` in the repo for the full list).

package/dist/docs/GETTING_STARTED.md

@@ -15,7 +15,6 @@ This will:
 
 - ✅ Install the component library
 - ✅ Add pre-compiled CSS import to your `index.css`
-- ✅ Create example components
 - ✅ Optionally install the Carbide AI skill and offer Chakra UI migration if detected
 
 ## 📋 Manual Setup