@atomixstudio/mcp 1.0.6 → 1.0.8

package/README.md

@@ -7,11 +7,11 @@ MCP (Model Context Protocol) server and CLI for Atomix Design System. Query and
 The easiest way to use Atomix is via the CLI:
 
 ```bash
-# Sync design tokens to your project
+# Sync tokens + AI rules (default behavior)
 npx heyatomix sync
 
-# Sync tokens + AI rules files (.cursorrules, etc.)
-npx heyatomix sync --rules
+# Sync tokens only (skip AI rules)
+npx heyatomix sync --no-rules
 
 # Create config file
 npx heyatomix init
@@ -28,16 +28,25 @@ npx heyatomix init
 
 ### `heyatomix sync`
 
-Sync design tokens to a local file in your project.
+Sync design tokens and AI rules to your project. **Both tokens and AI guidance rules sync by default** since the rules reference tokens.
 
 ```bash
-npx heyatomix sync                    # Sync to ./tokens.css
+npx heyatomix sync                    # Sync tokens + AI rules
+npx heyatomix sync --no-rules         # Sync tokens only
 npx heyatomix sync -o src/tokens.css  # Custom output path
 npx heyatomix sync --format scss      # Output as SCSS
-npx heyatomix sync --rules            # Also sync AI rules files
 npx heyatomix sync -y                 # Auto-confirm changes
 ```
 
+**⚠️ Important: File Structure**
+
+The output file (e.g., `tokens.css`) is **completely rewritten** on each sync:
+
+- ✅ **Preserved**: CSS custom properties (variables) - both design system tokens and custom variables
+- ❌ **Lost**: Regular CSS rules (selectors, classes, media queries, etc.)
+
+**Best Practice**: Keep your tokens file separate from custom CSS. Use a separate file (e.g., `custom.css` or `styles.css`) for custom styles.
+
 ### `heyatomix init`
 
 Create a `.atomixrc` config file:
@@ -64,7 +73,7 @@ This creates:
 | `--api-key` | API key for private design systems |
 | `--output, -o` | Output file path [./tokens.css] |
 | `--format` | Output format (see below) |
-| `--rules, -r` | Also sync AI rules files |
+| `--no-rules` | Skip syncing AI rules (tokens + rules sync by default) |
 | `--rules-dir` | Directory for rules files [project root] |
 | `-y, --yes` | Auto-confirm changes |
 
@@ -152,7 +161,7 @@ Once connected, AI tools can use these:
 
 ## AI Rules Files
 
-When using `--rules`, these files are synced based on which AI tools you use:
+By default, `sync` also updates AI rules files based on which AI tools you use:
 
 | File | AI Tool |
 |------|---------|
@@ -170,7 +179,7 @@ The rules include your design system's governance guidelines and token usage ins
 **CLI:**
 
 ```bash
-npx heyatomix sync --rules
+npx heyatomix sync
 ```
 
 **Natural language (via MCP):**
@@ -196,6 +205,14 @@ npx heyatomix sync --rules
 - [Atomix Studio](https://atomixstudio.eu)
 - [MCP Protocol](https://modelcontextprotocol.io)
 
+## Publishing (maintainers)
+
+This package bundles `@atomixstudio/sync-core` so a single publish works from npm. To republish:
+
+1. From repo root, build sync-core (needed for local types): `cd packages/atomix-sync-core && pnpm run build`
+2. From `packages/mcp-user`: `pnpm run build` then `npm publish --access public`
+3. Bump version in `package.json` before each new publish.
+
 ## License
 
 MIT