@symbo.ls/mcp 1.0.25 → 1.0.27

package/README.md

@@ -105,16 +105,50 @@ No API keys required for documentation tools. Project management tools require a
 pip install symbols-mcp
 ```
 
-Or with `uv`:
+Or with `uv` (no install needed):
 
 ```bash
 uvx symbols-mcp
 ```
 
+Or via npm:
+
+```bash
+npx @symbo.ls/mcp
+```
+
 ## Configuration
 
-Add to your MCP client config (e.g. `mcp.json`):
+### Recommended (auto-updates on every launch)
 
+```json
+{
+  "mcpServers": {
+    "symbols": {
+      "command": "uvx",
+      "args": ["--refresh", "symbols-mcp"]
+    }
+  }
+}
+```
+
+The `--refresh` flag checks PyPI for a newer version each time the server starts. Adds ~1-2s to startup but ensures you always have the latest rules and documentation.
+
+### Alternative configs
+
+**npm (also auto-updates):**
+```json
+{
+  "mcpServers": {
+    "symbols": {
+      "command": "npx",
+      "args": ["-y", "@symbo.ls/mcp"]
+    }
+  }
+}
+```
+
+**Pinned version (manual updates):**
 ```json
 {
   "mcpServers": {
@@ -126,6 +160,19 @@ Add to your MCP client config (e.g. `mcp.json`):
 }
 ```
 
+### Manual update
+
+```bash
+# pip
+pip install --upgrade symbols-mcp
+
+# uv (clear cache and re-run)
+uv cache clean symbols-mcp && uvx symbols-mcp
+
+# npm
+npm update -g @symbo.ls/mcp
+```
+
 ### Transport modes
 
 By default, the server runs over **stdio**. For SSE transport:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mcp",
-  "version": "1.0.25",
+  "version": "1.0.27",
   "description": "Symbols.app MCP — docs, code generation, publishing, CLI/SDK reference",
   "mcpName": "io.github.symbo-ls/symbols-mcp",
   "files": [

package/symbols_mcp/skills/AUDIT.md

@@ -6,8 +6,6 @@ Follow this protocol exactly. Execute each phase in order. Do not skip steps.
 
 ## 1. Install the MCP Server
 
-Run the following command to install:
-
 ```bash
 pip install symbols-mcp
 ```
@@ -16,14 +14,14 @@ pip install symbols-mcp
 
 ## 2. Configure the MCP Server
 
-Add this configuration to your MCP settings:
+Add this configuration to your MCP settings (uses `--refresh` to auto-update on every launch):
 
 ```json
 {
   "mcpServers": {
     "symbols": {
       "command": "uvx",
-      "args": ["symbols-mcp"]
+      "args": ["--refresh", "symbols-mcp"]
     }
   }
 }

package/symbols_mcp/skills/DEFAULT_STYLES.md

@@ -8,12 +8,9 @@ These are the **recommended default design system values** for all newly created
 
 ```js
 export default {
-  '@default': {
-    base: 16,
-    ratio: 1.25,
-    range: [-5, 12],
-    subSequence: true,
-  },
+  base: 16,
+  ratio: 1.25,
+  subSequence: true,
 }
 ```
 
@@ -25,16 +22,13 @@ export default {
 
 ```js
 export default {
-  '@default': {
-    base: 16,
-    ratio: 1.25,
-    range: [-5, 12],
-    subSequence: true,
-  },
+  base: 16,
+  ratio: 1.618,
+  subSequence: true,
 }
 ```
 
-Uses the same scale as typography. Tokens: `A` = 20px, `B` = 25px, `Z` = 16px, etc.
+Golden ratio (1.618) for spacing. Tokens: `A` = 16px, `B` = 26px, `C` = 42px, etc.
 
 ---
 

package/symbols_mcp/skills/DESIGN_SYSTEM.md

@@ -285,18 +285,32 @@ Title: { fontWeight: 700 }
 
 Golden Ratio scale (1.618 default). Applies to `padding`, `margin`, `gap`, `width`, `height`, `boxSize`, `borderRadius`/`round`, `inset`, `top`, `left`, `right`, `bottom`, etc.
 
-| Token | Approx value | Use |
+### Token stepping system
+
+Each letter is a major step. Sub-numbers are minor increments between letters. The sequence flows continuously — each sub-step is one tone increase:
+
+```
+... X < X1 < X2 < Z < Z1 < Z2 < A < A1 < A2 < A3 < B < B1 < B2 < B3 < C ...
+```
+
+How many sub-steps exist between letters depends on the range — smaller ranges (W, X) have only 1-2 sub-steps, larger ranges (A, B, C) have up to 3.
+
+**To increase slightly:** go up one sub-step (e.g. `A` → `A1`, or `B2` → `B3`)
+**To increase moderately:** go up one letter (e.g. `A` → `B`)
+**To decrease:** reverse direction (e.g. `B` → `A3`, or `A` → `Z2`)
+
+| Token range | Approx px | Use |
 |---|---|---|
-| `W`-`W2` | 2-4 px | Micro gaps, offsets |
-| `X`-`X2` | 4-6 px | Icon padding, tight gaps |
-| `Z`-`Z2` | 10-16 px | Compact padding |
-| `A`-`A2` | 16-26 px | Default padding, gutters |
-| `B`-`B2` | 26-42 px | Section padding |
-| `C`-`C2` | 42-68 px | Container padding, avatar sizes |
-| `D`-`D2` | 68-110 px | Large sections |
-| `E`-`F` | 110-178 px | Hero padding, max-widths |
-
-Sub-sequence rules: `W` and `X` only have `W`, `W1`, `W2` and `X`, `X1`, `X2`. Sub-tokens like `W4`, `X4` do NOT exist. Sub-steps `3` and `4` (e.g. `A3`, `A4`, `B3`, `B4`) only appear from `A` and above.
+| `W`-`W2` | 2-4 | Micro gaps, offsets |
+| `X`-`X2` | 4-6 | Icon padding, tight gaps |
+| `Z`-`Z2` | 10-16 | Compact padding |
+| `A`-`A3` | 16-26 | Default padding, gutters |
+| `B`-`B3` | 26-42 | Section padding |
+| `C`-`C3` | 42-68 | Container padding, avatar sizes |
+| `D`-`D3` | 68-110 | Large sections |
+| `E`-`F` | 110-178 | Hero padding, max-widths |
+
+Typography tokens use the same letter system for `fontSize`.
 
 ### Shorthand spacing
 

package/symbols_mcp/skills/PROJECT_STRUCTURE.md

@@ -402,7 +402,8 @@ npm i -g @symbo.ls/cli
 
 | Goal | Command |
 |------|---------|
-| Local-only (fastest) | `smbls create <project-name> && cd <project-name> && npm start` |
+| Default (with `system/default` library) | `smbls create <project-name> && cd <project-name> && npm start` |
+| Blank (no shared libraries) | `smbls create <project-name> --blank-shared-libraries && cd <project-name> && npm start` |
 | Platform-linked (collaboration + remote preview) | `smbls project create <project-name> --create-new && cd <project-name> && npm start` |
 
 ### Authentication

package/symbols_mcp/skills/RULES.md

@@ -1230,6 +1230,24 @@ color: { blue50: '#eff6ff', blue100: '#dbeafe', blue200: '#bfdbfe', blue300: '#9
 
 ---
 
+## Rule 46 — Fetched shared libraries are READONLY — override locally instead
+
+When shared libraries are fetched from the platform (`smbls fetch`/`smbls sync`), both `sharedLibraries.js` and the `.symbols_local/libs/` folders are strictly **readonly** — they are overwritten on every fetch/sync. Never edit fetched library files. To override shared library components, define them in your local project files — the app always wins at runtime.
+
+`sharedLibraries.js` can be manually edited when custom-linking to local folders (advanced use case). But fetched libraries must never be modified.
+
+```js
+// ❌ WRONG — editing fetched .symbols_local/libs/ files
+// These are overwritten on every fetch/sync
+
+// ✅ CORRECT — override in local components/
+// If shared library has Button with theme: 'primary',
+// define your own Button in components/Button.js to override it
+export const Button = { theme: 'dialog', padding: 'Z A' }
+```
+
+---
+
 ## Rule 44 — Never chain CSS selectors — use nesting instead
 
 Media queries (`@dark`, `@mobileL`) and pseudo-classes (`:hover`, `:active`) must be nested as separate objects, never chained into a single key string.

package/symbols_mcp/skills/SHARED_LIBRARIES.md

@@ -1,6 +1,25 @@
 # sharedLibraries
 
-sharedLibraries is a mechanism in the Symbols framework that allows projects to inherit components, functions, methods, state, designSystem, pages, files, snippets, and dependencies from external library projects. Libraries are merged into the consuming app's context at runtime — no manual re-exports needed.
+sharedLibraries allows projects to inherit components, functions, methods, state, designSystem, pages, files, snippets, and dependencies from external library projects. Libraries are merged into the consuming app's context at runtime — no manual re-exports needed.
+
+**CRITICAL: When shared libraries are fetched from the platform, both `sharedLibraries.js` and `.symbols_local/libs/` folders are strictly READONLY — they are overwritten on every `smbls fetch`/`smbls sync`.** To override shared library components, define them in your local project files (app always wins).
+
+`sharedLibraries.js` can be manually edited for custom linking to local folders (advanced use case), but fetched content must never be modified.
+
+---
+
+## Key Format: `owner/key`
+
+All shared library identifiers use the `owner/key` format. Default owner is `system`.
+
+| Input | Normalized |
+|---|---|
+| `system/default` | `system/default` |
+| `default` | `system/default` |
+| `default.symbo.ls` | `system/default` (deprecated) |
+| `myorg/mylib` | `myorg/mylib` |
+
+The `.symbo.ls` suffix is deprecated and stripped automatically.
 
 ---
 
@@ -11,41 +30,45 @@ sharedLibraries is a mechanism in the Symbols framework that allows projects to
 Three supported formats:
 
 ```json
-// Array of strings (library keys)
-"sharedLibraries": ["brand", "shared"]
+// Array of strings (owner/key or bare key)
+"sharedLibraries": ["system/default", "system/landing"]
 
 // Object with key:version
-"sharedLibraries": { "brand": "1.0.0", "shared": "latest" }
+"sharedLibraries": { "system/default": "1.0.0" }
 
-// Object with key:config (used in editor)
-"sharedLibraries": {
-  "brand": { "version": "1.0.0", "destDir": "../brand" },
-  "shared": { "destDir": "../shared" }
-}
+// Object with key:config
+"sharedLibraries": { "system/default": { "version": "1.0.0", "destDir": "./custom" } }
 ```
 
-All formats are normalized by the CLI (`cli/helpers/symbolsConfig.js:246-268`) to: `[{ key, version, destDir }]`
+All formats normalize keys to `owner/key` via `normalizeLibraryKey()`.
 
-### sharedLibraries.js
+### sharedLibraries.js (auto-generated on fetch/sync)
 
-Each package has a `sharedLibraries.js` that imports other packages' `context.js` and exports them as an array:
+The CLI generates this file automatically after `smbls fetch`/`smbls sync`:
 
 ```js
-import brand from '../brand/context.js'
-import shared from '../shared/context.js'
+import systemDefault from '../.symbols_local/libs/system--default/context.js'
 
-export default [brand, shared]
+export default [systemDefault]
 ```
 
-For remote libraries fetched from the platform:
+This file is overwritten on every fetch/sync. To customize behavior, override components/state/designSystem in your local project files instead.
 
-```js
-import platformSymboLs from '../.symbols_local/libs/platform.symbo.ls/context.js'
-import docsSymboLs from '../.symbols_local/libs/docs.symbo.ls/context.js'
+### File Structure After Fetch
 
-export default [platformSymboLs, docsSymboLs]
+Directory names use `owner--key` format (double dash separator):
+
+```
+.symbols_local/libs/
+  system--default/        # owner--key directory convention
+    context.js
+    components/
+    designSystem/
+    ...
 ```
 
+The `owner--key` directory convention matches mermaid hosting URLs (`key--owner.preview.symbols.app`).
+
 ### context.js
 
 The `sharedLibraries` array is included in the context export:
@@ -82,29 +105,31 @@ This runs early in context initialization, **before** designSystem, state, compo
 
 ### Merge Logic
 
-`smbls/src/prepare.js:240-251`:
+`smbls/src/prepare.js`:
 
 ```js
 export const prepareSharedLibs = (context) => {
   const sharedLibraries = context.sharedLibraries
   for (let i = 0; i < sharedLibraries.length; i++) {
     const sharedLib = sharedLibraries[i]
-    if (context.type === 'template') {
-      overwriteShallow(context.designSystem, sharedLib.designSystem)
-      deepMerge(context, sharedLib, ['designSystem'], 1)
-    } else {
-      deepMerge(context, sharedLib, [], 1)
+    for (const key in sharedLib) {
+      if (isObject(sharedLib[key]) && isObject(context[key])) {
+        if (key === 'designSystem') {
+          deepDefaults(context[key], sharedLib[key])
+        } else {
+          for (const k in sharedLib[key]) {
+            if (!(k in context[key])) context[key][k] = sharedLib[key][k]
+          }
+        }
+      } else if (!(key in context)) {
+        context[key] = sharedLib[key]
+      }
     }
   }
 }
 ```
 
-**Two strategies:**
-
-| App Type | designSystem | Everything Else |
-|----------|-------------|-----------------|
-| **template** | `overwriteShallow` — library completely replaces template's designSystem | `deepMerge` with designSystem excluded |
-| **regular** | `deepMerge` (app wins) | `deepMerge` (app wins) |
+**The app ALWAYS wins.** Shared libraries only fill in missing keys (`!(k in context[key])`). designSystem uses `deepDefaults` which fills nested gaps while preserving all local values.
 
 ### deepMerge Behavior
 
@@ -184,56 +209,36 @@ So the final component resolution is: **App > Shared Libraries > UIKit**
 
 ## CLI Integration
 
-### Scaffolding (`cli/bin/fs.js:231-345`)
+### Project Creation
 
-`scaffoldSharedLibraries()`:
-1. Reads `sharedLibraries` from project JSON
-2. Creates each library as a full project folder via frank's `toFS()`
-3. Default location: `.symbols_local/libs/`
-4. Generates `sharedLibraries.js` with import statements
-
-### Fetch (`cli/bin/fetch.js`)
-
-When fetching from the platform:
-- Pulls full project data including `sharedLibraries` array
-- Each library is a complete Symbols project object
-- Extracts version info and stores in lock file
+```bash
+smbls create my-app                           # Default: adds system/default + fetches
+smbls create my-app --blank-shared-libraries  # Blank: no shared libraries, skips fetch
+```
 
-### toJSON (`frank/toJSON.js:170-183`)
+When creating with default libraries:
+1. Project is created on the platform
+2. `system/default` library is attached via API
+3. Local files are scaffolded
+4. `smbls fetch` runs to pull library data into `.symbols_local/libs/`
 
-Context modules list includes sharedLibraries:
+### Library Management
 
-```js
-const CONTEXT_MODULES = [
-  { name: 'state', path: './state.js', style: 'default' },
-  { name: 'dependencies', path: './dependencies.js', style: 'default' },
-  { name: 'sharedLibraries', path: './sharedLibraries.js', style: 'default' },
-  { name: 'components', path: './components/index.js', style: 'namespace' },
-  { name: 'snippets', path: './snippets/index.js', style: 'namespace' },
-  { name: 'pages', path: './pages/index.js', style: 'default' },
-  { name: 'functions', path: './functions/index.js', style: 'namespace' },
-  { name: 'methods', path: './methods/index.js', style: 'namespace' },
-  { name: 'designSystem', path: './designSystem/index.js', style: 'default' },
-  { name: 'files', path: './files/index.js', style: 'default' },
-  { name: 'config', path: './config.js', style: 'default' }
-]
+```bash
+smbls project libs available          # List all available libraries (shows owner/key)
+smbls project libs list               # List libraries linked to current project
+smbls project libs add system/default # Add by owner/key
+smbls project libs add default        # Bare key → system/default
+smbls project libs remove default     # Remove library
 ```
 
-### Validation (`cli/bin/validate-domql-runner.js:323-342`)
-
-`mergeSharedLibraries()` merges all library exports for DOMQL validation:
+### Scaffolding
 
-```js
-function mergeSharedLibraries(sharedLibraries) {
-  const merged = { pages: {}, components: {}, functions: {}, methods: {}, snippets: {} }
-  for (const lib of libs) {
-    if (isPlainObject(lib?.pages)) Object.assign(merged.pages, lib.pages)
-    if (isPlainObject(lib?.components)) Object.assign(merged.components, lib.components)
-    // ...
-  }
-  return merged
-}
-```
+`scaffoldSharedLibraries()` in `cli/bin/fs.js`:
+1. Reads `sharedLibraries` from project JSON
+2. Creates each library as a full project folder via frank's `toFS()`
+3. Default location: `.symbols_local/libs/`
+4. Auto-generates `sharedLibraries.js` with import statements (overwritten every time)
 
 ---
 
@@ -289,12 +294,13 @@ prepareContext() {
 
 ## Key Takeaways
 
-1. **No re-exports needed** — components/functions from a shared library are automatically available in the consuming app's context
-2. **App always wins** — app's own definitions take precedence over shared libraries
-3. **Order matters** — first library in the array has priority over later ones for filling undefined slots
-4. **Templates are special** — designSystem is fully overwritten (shallow) rather than deep-merged
-5. **Methods are protected** — METHODS_EXL prevents shared libraries from overwriting element methods and internal references
-6. **No circular detection** — JavaScript's ESM module system prevents infinite loops naturally; circular deps resolve as undefined values
+1. **Fetched shared libraries are readonly** — `sharedLibraries.js` and `.symbols_local/libs/` are overwritten on fetch/sync. Manual editing only for custom local linking.
+2. **App always wins** — local project definitions take precedence over shared libraries
+3. **Override by defining locally** — to change a shared library component, define it in your local `components/` with the same name
+4. **Order matters** — first library in the array has priority over later ones for filling undefined slots
+5. **Key format is `owner/key`** — bare keys default to `system/` owner
+6. **`smbls create` defaults to `system/default`** — use `--blank-shared-libraries` for no libraries
+7. **Methods are protected** — METHODS_EXL prevents shared libraries from overwriting element methods and internal references
 
 ---
 
@@ -307,6 +313,7 @@ prepareContext() {
 | deepMerge | `smbls/packages/utils/object.js` | 61-76 |
 | overwriteShallow | `smbls/packages/utils/object.js` | 431-439 |
 | METHODS_EXL | `smbls/packages/utils/keys.js` | 147-152 |
+| Key normalization | `smbls/packages/cli/helpers/libraryKeyUtils.js` | — |
 | Config normalization | `smbls/packages/cli/helpers/symbolsConfig.js` | 246-268 |
 | FS scaffolding | `smbls/packages/cli/bin/fs.js` | 231-345 |
 | Context modules | `smbls/packages/frank/toJSON.js` | 170-183 |