@symbo.ls/mcp 1.0.13 → 1.0.17

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@symbo.ls/mcp",
-  "version": "1.0.13",
-  "description": "MCP server for Symbols.app — documentation search and framework reference",
+  "version": "1.0.17",
+  "description": "MCP server for Symbols.app — documentation search, code generation, project management, publishing, CLI/SDK reference",
   "mcpName": "io.github.symbo-ls/symbols-mcp",
   "files": [
     "bin/",

package/symbols_mcp/skills/AUDIT.md

@@ -259,3 +259,5 @@ Produce the following deliverables:
    - Project issues (implementation-level) in project-feedback.md
 
 Enforce full DOMQL v3 purity across the entire codebase. No exceptions.
+
+**CRITICAL: There is NO concept of "known debt", "accepted violations", or "technical debt exceptions" in Symbols audits. Every violation MUST be fixed. Never label a violation as "known debt" or suggest it can be deferred. If the audit finds a Rule 30 violation (direct DOM manipulation), it must be rewritten using DOMQL declarative syntax — not acknowledged and kept. The same applies to ALL rules (27-33). Zero tolerance.**

package/symbols_mcp/skills/CLI.md

@@ -0,0 +1,374 @@
+# Symbols CLI Reference (`@symbo.ls/cli`)
+
+The `smbls` command-line interface for the Symbols design platform.
+
+**Install:** `npm install -g @symbo.ls/cli`
+**Version:** 3.7.5
+**Global command:** `smbls`
+
+---
+
+## Project Setup
+
+### `smbls init [dest]`
+Initialize or add Symbols to a project.
+- `--non-interactive` — disable prompts (requires flags)
+- `--name <name>` — project name
+- `--location <location>` — where to init: root or subfolder
+- `--v2-action <action>` — v2 project action: migrate, root, or subfolder
+- `-y, --yes` — skip confirmation prompts
+
+Auto-detects v2 projects and offers migration path.
+
+### `smbls create [dir]`
+Create and scaffold a new project.
+- `--workspace` — scaffold only symbols source files (no full repo, dir: ".")
+- `--create-new` — force create new platform project
+- `--link-existing` — force link to existing platform project
+- `--local-only` — local-only (no platform)
+- `--non-interactive` — disable prompts (requires flags)
+- `--project-name <name>` — platform project name
+- `--type <projectType>` — platform projectType
+- `--key <projectKey>` — platform project key
+- `--id <projectId>` — platform project id (for link mode)
+- `--visibility <visibility>` — platform visibility (default: private)
+- `--language <language>` — platform language (default: javascript)
+- `--branch <branch>` — local branch (default: main)
+- `--template <gitUrl>` — override template git repo URL
+- `--package-manager <manager>` — npm or yarn (default: npm)
+- `--no-dependencies` — skip installing dependencies
+- `--no-clone` — create folder instead of cloning from git
+- `--blank-shared-libraries` — create project with blank shared libraries
+- `--domql` — use DOMQL template (default: true)
+- `--remote` — clone feature/remote branch (default: true)
+- `--clean-from-git` — remove starter-kit git repository (default: true)
+- `-v, --verbose` — verbose output
+
+### `smbls install`
+Install Symbols into an existing project.
+- `-d, --dev` — run against local server
+- `-f, --fetch` — fetch config after install (default: true)
+- `--framework <framework>` — framework: domql or react
+- `-v, --verbose` — verbose output
+
+### `smbls eject`
+Eject from `@symbo.ls/runner` to explicit bundler dependencies.
+- `--no-install` — skip npm install after ejecting
+
+Updates package.json, removes @symbo.ls/runner, adds bundler deps, expands .parcelrc for parcel.
+
+---
+
+## Development
+
+### `smbls start [entry]`
+Start development server.
+- `-p, --port <port>` — port to use (default from symbols.json or 1234)
+- `--no-cache` — disable build cache
+- `--open` — open browser on start
+- `--bundler <bundler>` — force bundler: parcel, vite, or browser
+
+Supports pass-through args to underlying bundler. Auto-selects free port if specified port is busy. Browser mode injects importmap and globals script.
+
+### `smbls build [entry]`
+Build project for production.
+- `--no-cache` — disable build cache
+- `--no-optimize` — disable optimization
+- `--no-brender` — skip brender pre-rendering
+- `--out-dir <dir>` — output directory (default from symbols.json or dist)
+- `--bundler <bundler>` — force bundler: parcel, vite, or browser
+
+### `smbls brender [entry]`
+Pre-render static pages to HTML using server-side rendering.
+- `--out-dir <dir>` — output directory (default: brenderDistDir from symbols.json, or dist-brender)
+- `--no-isr` — disable ISR (skip client SPA bundle)
+- `--no-prefetch` — disable SSR data prefetching
+- `-w, --watch` — watch for changes and re-render
+
+Output: `dist-brender/` with static HTML, metadata, CSS, optional client bundle.
+
+### `smbls deploy`
+Deploy project to hosting providers.
+- `--provider <provider>` — deploy target: symbols, cloudflare, vercel, netlify, github-pages
+- `--init` — initialize deployment config without deploying
+- `--out-dir <dir>` — output directory for build
+- `--bundler <bundler>` — force bundler: parcel, vite, or browser
+
+Creates provider-specific config files (wrangler.jsonc, vercel.json, netlify.toml, GitHub Actions workflow).
+
+---
+
+## Sync & Configuration
+
+### `smbls fetch`
+Pull design system and project config from the Symbols platform.
+- `-d, --dev` — run against local server
+- `-v, --verbose` — verbose output
+- `--convert` — convert fetched config (default: true)
+- `--schema` — include schema (default: false)
+- `--force` — force override local changes
+- `--update` — override local changes from platform
+- `-y, --yes` — skip confirmation prompts
+- `--dist-dir <dir>` — directory to import files to
+- `--skip-confirm` — skip confirmation for local changes
+- `--non-interactive` — disable interactive prompts
+
+Includes git-based or mtime heuristic detection of local changes.
+
+### `smbls sync`
+Bidirectional sync with remote server (two-way merge with conflict resolution).
+- `-b, --branch <branch>` — branch to sync
+- `-m, --message <message>` — commit message
+- `-d, --dev` — run against local server
+- `-v, --verbose` — verbose output
+- `--mode <mode>` — sync mode: merge, remote, local, cancel
+- `--conflict-resolution <mode>` — conflict resolution: local or remote
+- `--non-interactive` — disable interactive prompts
+- `-y, --yes` — skip confirmation prompts
+
+Uses 3-way merge: local, remote, and base comparison.
+
+### `smbls push`
+Push local changes to the Symbols platform.
+- `-m, --message <message>` — commit message
+- `-v, --verbose` — verbose output
+- `-d, --dev` — run against local server
+- `--non-interactive` — disable interactive prompts
+- `-y, --yes` — skip confirmation prompts
+
+Shows diffs before confirmation.
+
+### `smbls publish`
+Build and publish project to preview environments.
+- `--env <envs...>` — environments to publish to (development, staging, production)
+- `--all` — publish to all environments
+- `--non-interactive` — disable prompts (requires --env or --all)
+- `-v, --verbose` — verbose output
+
+Preview URLs are auto-generated for each environment.
+
+### `smbls config`
+Interactively configure Symbols project settings.
+- `--non-interactive` — disable prompts
+- `--dist-dir <dir>` — set distribution directory
+- `--owner <owner>` — Symbols username
+- `--key <key>` — project key
+- `--branch <branch>` — default branch
+- `--version <version>` — version
+- `--dir <dir>` — Symbols source directory
+- `--runtime <runtime>` — environment: node, bun, deno, browser
+- `--bundler <bundler>` — build tool: parcel, vite, turbopack, webpack, rollup
+- `--package-manager <pm>` — npm, yarn, pnpm, bun
+- `--api-base-url <url>` — API base URL
+- `--deploy <target>` — deploy target: symbols, cloudflare, vercel, netlify, github-pages
+
+Updates `symbols.json` and `.symbols_local/config.json`.
+
+---
+
+## Collaboration & Authentication
+
+### `smbls login`
+Sign in to Symbols. Opens browser for OAuth/auth flow, stores credentials in `~/.smblsrc`.
+
+### `smbls signup`
+Create a new Symbols account.
+
+### `smbls logout`
+Sign out of Symbols (clears local credentials).
+
+### `smbls collab`
+Connect to real-time collaboration socket and live-sync changes.
+- `-b, --branch <branch>` — branch to collaborate on
+- `--no-sync-first` — skip initial sync (not recommended)
+- `-l, --live` — enable live collaboration mode (default: false)
+- `-d, --debounce-ms <ms>` — local changes debounce (default: 200ms)
+- `-v, --verbose` — verbose output
+
+---
+
+## Project Management
+
+### `smbls project <subcommand>`
+Project lifecycle management with subcommands:
+
+| Subcommand | Description |
+|---|---|
+| `create` | Create a new project |
+| `link` | Link local project to platform |
+| `delete` | Delete a project |
+| `update` | Update project metadata |
+| `list` | List projects |
+| `duplicate` | Duplicate a project |
+| `restore` | Restore a project |
+| `libs` | Library management (add, remove, list, available) |
+| `members` | Members management (add, remove, list, invite, role, acceptInvite, inviteLink) |
+| `versions` | Versions management (create, get, list, latest, publish, snapshot, update) |
+| `environments` | Environments management (list, activate, publish, upsert, update, delete) |
+| `pipeline` | Pipeline management (promote) |
+
+---
+
+## File Management
+
+### `smbls files <subcommand>`
+Upload, download, and manage project files.
+
+| Subcommand | Description | Key Options |
+|---|---|---|
+| `list` | List project-linked files | `--remote`, `--uploads`, `--limit <n>`, `--search <q>` |
+| `upload <paths...>` | Upload files to project | `--key`, `--visibility`, `--tags`, `--metadata`, `--mime`, `--overwrite` |
+| `download` | Download a file | `--key`, `--out <path>`, `--remote` |
+| `rm` | Remove file from project | `--key`, `--local-only`, `--force-remote` |
+
+---
+
+## AI Assistant
+
+### `smbls ask [question...]`
+Chat with AI about your Symbols project.
+- `--provider <provider>` — AI provider: claude, openai, gemini, ollama, symbols
+- `--model <model>` — model name
+- `--init` — configure AI settings and MCP
+
+**Supported providers and models:**
+| Provider | Models |
+|---|---|
+| Claude | claude-sonnet-4-6, claude-opus-4-6, claude-haiku-4-5-20251001 |
+| OpenAI | gpt-4o, gpt-4o-mini, o3-mini |
+| Gemini | gemini-2.5-pro, gemini-2.5-flash |
+| Ollama | llama3.3, codellama, mistral, deepseek-coder-v2 (local) |
+
+Config stored in `~/.smblsrc`. Environment variables: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GEMINI_API_KEY`.
+
+---
+
+## Utilities
+
+### `smbls convert [src] [dest]`
+Convert DOMQL components to other frameworks.
+- `--react` — convert to React
+- `--angular` — convert to Angular
+- `--vue2` — convert to Vue 2
+- `--vue3` — convert to Vue 3
+- `-o, --only <components>` — only convert specific components (comma-separated)
+- `-m, --merge <dir>` — recursive merge files into dest
+- `-v, --verbose` — verbose mode
+
+### `smbls migrate`
+Migrate a v2 Symbols project to v3.
+- `--yes` — skip confirmation
+- `--non-interactive` — disable all prompts
+
+Renames `.symbols/` to `.symbols_local/`, `smbls/` to `symbols/`, creates missing `symbols/app.js`, rewrites `symbols/index.js` to v3 format.
+
+### `smbls validate [target]`
+Validate DOMQL syntax in source files.
+- Uses esbuild to check JS/TS/JSX/TSX syntax
+- Reports violations, warnings, and compliance scores
+
+### `smbls clean`
+Clean Symbols temporary files.
+
+### `smbls sdk [method] [args...]`
+Proxy SDK service methods from the terminal.
+- `-l, --list` — list all available SDK methods
+- `-s, --service <name>` — filter methods by service name
+
+```bash
+smbls sdk --list                              # List all methods
+smbls sdk --list --service auth               # Filter by service
+smbls sdk getProjects                         # Call method
+smbls sdk getProjectByKey '{"key":"myapp"}'   # Call with arguments
+```
+
+### `smbls link-packages`
+Link all smbls packages into the project.
+- `-c, --capture` — capture and write all package names
+- `-j, --join` — join all links into one command (default: true)
+
+### `smbls servers`
+List and switch CLI servers (API base URLs).
+- `-s, --select` — interactively select active server
+
+### `smbls completion [shell]`
+Generate shell completion script.
+- `--install` — print install instructions
+
+### `smbls github <subcommand>`
+GitHub integration helpers.
+- `connect` — connect GitHub repository
+- `initActions` — initialize GitHub Actions workflow
+- `sync` — sync with GitHub
+
+---
+
+## Configuration Files
+
+### `symbols.json` (project root)
+Main project configuration:
+- `owner` — Symbols username
+- `key` — project identifier
+- `dir` — symbols source directory
+- `branch` — git branch (default: main)
+- `entry` — bundler entry point
+- `port` — dev server port
+- `distDir` — build output directory
+- `brenderDistDir` — brender output directory
+- `brender` — enable pre-rendering
+- `runtime` — node, bun, deno, or browser
+- `bundler` — parcel, vite, etc.
+- `packageManager` — npm, yarn, pnpm, bun
+- `libraries` / `librariesDir` — shared library config
+- `designSystem` — design system with buckets
+
+### `.symbols_local/config.json` (local)
+Local machine configuration:
+- `owner` — local username
+- `branch` — active branch
+- `projectKey` — linked project key
+- `projectId` — platform project ID
+- `apiBaseUrl` — API endpoint
+
+### `~/.smblsrc` (global)
+Global credentials and AI configuration.
+
+---
+
+## Common Workflows
+
+### New project from scratch
+```bash
+smbls create my-app
+cd my-app
+smbls start
+```
+
+### Add Symbols to existing project
+```bash
+cd existing-project
+smbls init
+smbls install
+smbls start
+```
+
+### Fetch, edit, push cycle
+```bash
+smbls fetch          # pull latest from platform
+# ... edit components ...
+smbls push -m "updated header"
+```
+
+### Deploy to production
+```bash
+smbls build
+smbls deploy --provider cloudflare
+# or
+smbls publish --env production
+```
+
+### Migrate v2 to v3
+```bash
+smbls migrate --yes
+smbls start
+```

package/symbols_mcp/skills/COMMON_MISTAKES.md

@@ -0,0 +1,225 @@
+# Common Mistakes — Wrong vs Correct DOMQL v3 Patterns
+
+This is a zero-tolerance reference. Every pattern in the "Wrong" column is FORBIDDEN. The audit tool catches all of them. There is no concept of "known debt" — every violation must be fixed to 100%.
+
+---
+
+## 1. Colors — use design system tokens, never hex/rgb
+
+```js
+// ❌ WRONG — raw hex values
+color: '#202124',  background: '#f1f3f4',  borderColor: '#dadce0'
+
+// ✅ CORRECT — named tokens from designSystem.color
+color: 'text',  background: 'headerBg',  borderColor: 'border'
+```
+
+---
+
+## 2. CSS — flatten at root level, never use `style: {}` wrapper
+
+```js
+// ❌ WRONG — CSS inside style: {} block
+FileName: {
+  tag: 'input',
+  style: { fontSize: '16px', border: 'none', color: '#202124' }
+}
+
+// ✅ CORRECT — CSS flat as props
+FileName: {
+  tag: 'input',
+  fontSize: 'A',  border: 'none',  color: 'text'
+}
+```
+
+---
+
+## 3. Spacing — use design system tokens, never raw px
+
+```js
+// ❌ WRONG — raw pixel values
+padding: '4px 10px',  height: '30px',  width: '1px',  gap: '4px'
+
+// ✅ CORRECT — spacing tokens
+padding: 'X Y',  height: 'B',  borderLeft: '1px solid border',  gap: 'X'
+```
+
+---
+
+## 4. Icons — use Icon component + `designSystem/icons`, never inline HTML
+
+```js
+// ❌ WRONG — inline HTML strings
+BtnBold: { extends: 'ToolbarBtn', html: '<b>B</b>' }
+BtnColorRed: { html: '<span style="color:#d93025;font-weight:bold">A</span>' }
+
+// ✅ CORRECT — Icon component with designSystem/icons
+BtnBold: { extends: 'ToolbarBtn', Icon: { extends: 'Icon', icon: 'bold', width: 'A', height: 'A' } }
+BtnColorRed: { extends: 'ToolbarBtn', color: 'danger', Icon: { extends: 'Icon', icon: 'colorA', width: 'A', height: 'A' } }
+
+// designSystem/icons.js:
+// bold: '<svg width="24" height="24" viewBox="0 0 24 24"><path d="..."/></svg>'
+// colorA: '<svg width="24" height="24" viewBox="0 0 24 24"><path d="..."/></svg>'
+```
+
+---
+
+## 5. Select options — use children + childExtends, never raw HTML
+
+```js
+// ❌ WRONG — raw html string of option tags
+FontSizeSelect: {
+  html: '<option value="12">12</option><option value="13" selected>13</option>...'
+}
+
+// ✅ CORRECT — declarative children with state
+FontSizeSelect: {
+  children: [10, 11, 12, 13, 14, 16, 18, 20, 24, 28, 32].map(sz => ({
+    label: String(sz), value: String(sz)
+  })),
+  childrenAs: 'state',
+  childExtends: 'FontSizeOption',
+}
+```
+
+---
+
+## 6. Grids/tables — declarative DOMQL, never `document.createElement`
+
+```js
+// ❌ WRONG — imperative DOM building
+GridWrapper: {
+  onRender: (el) => {
+    const table = document.createElement('table')
+    const th = document.createElement('th')
+    th.textContent = colLabel(c)
+    headRow.appendChild(th)
+    // ... hundreds of lines of imperative DOM
+    document.getElementById(`cell-${r}-${c}`)?.querySelector('input')?.focus()
+  }
+}
+
+// ✅ CORRECT — fully declarative DOMQL
+BodyRows: {
+  children: (el) => {
+    const rs = el.getRootState()
+    return rs.grid.map((row, r) => ({ cells: row.map((v, c) => ({ v, r, c })) }))
+  },
+  childrenAs: 'state',
+  childExtends: 'SpreadsheetRow',
+}
+
+SpreadsheetCell: {
+  CellInput: {
+    value: (el, s) => s.v,
+    onFocus: (e, el, s) => el.call('selectCell', { r: s.r, c: s.c }),
+  }
+}
+```
+
+---
+
+## 7. Dynamic text — reactive `text:` prop, never polling with `el.node.textContent`
+
+```js
+// ❌ WRONG — setInterval polling with el.node.textContent
+CellLabel: {
+  onRender: (el) => {
+    setInterval(() => {
+      el.node.textContent = colLabel(rs.sel.c) + (rs.sel.r + 1)
+    }, 50)
+  }
+}
+
+// ✅ CORRECT — reactive text prop
+CellLabel: {
+  text: (el) => {
+    const rs = el.getRootState()
+    return rs ? el.call('colLabel', rs.sel.c) + (rs.sel.r + 1) : 'A1'
+  }
+}
+```
+
+---
+
+## 8. Input value — reactive `value:` prop, never polling with `el.node.value`
+
+```js
+// ❌ WRONG — setInterval writing el.node.value
+FormulaInput: {
+  onRender: (el) => {
+    setInterval(() => {
+      if (document.activeElement !== el.node) return
+      el.node.value = rs.formulaBarValue
+    }, 60)
+  }
+}
+
+// ✅ CORRECT — reactive value prop
+FormulaInput: {
+  value: (el) => el.getRootState()?.formulaBarValue || '',
+}
+```
+
+---
+
+## 9. State — use `s` directly with `childrenAs: 'state'`, never `el.parent.state`
+
+```js
+// ❌ WRONG — parent state traversal
+value: (el) => el.parent.state.v,
+onFocus: (e, el) => el.call('selectCell', { r: el.parent.state.r, c: el.parent.state.c })
+
+// ✅ CORRECT — s inherited automatically via childrenAs: 'state'
+value: (el, s) => s.v,
+onFocus: (e, el, s) => el.call('selectCell', { r: s.r, c: s.c })
+```
+
+---
+
+## 10. Event handlers — correct signature for root vs local state
+
+```js
+// ❌ WRONG — s is local state, not root — breaks for global updates
+onInput: (e, el, s) => s.update({ filename: e.target.value })
+
+// ✅ CORRECT — el.getRootState() for global state, s for local inherited state
+onInput: (e, el) => el.getRootState().update({ filename: e.target.value })
+onBlur: (e, el, s) => el.call('commitEdit', { r: s.r, c: s.c, val: e.target.value })
+```
+
+---
+
+## 11. Rich text — DOMQL children with tokens, never inline `style=`
+
+```js
+// ❌ WRONG — html string with inline style
+PoweredBy: { html: 'Built with <strong style="color:#1a73e8">Symbols</strong>' }
+
+// ✅ CORRECT — DOMQL children with token colors
+PoweredBy: {
+  flow: 'x',
+  gap: 'X',
+  Prefix: { text: 'Built with' },
+  Sym: { tag: 'strong', color: 'accent', text: 'Symbols' },
+  Ver: { tag: 'span', text: ' · smbls@latest' },
+}
+```
+
+---
+
+## 12. Token alignment — aligned elements must share `fontSize`
+
+Spacing tokens are em-based. Mixed `fontSize` on siblings causes the same token to resolve to different px values.
+
+```js
+// ❌ WRONG — mixed fontSize, E resolves differently
+ColHeaderCell: { fontSize: 'Z1', width: 'E', ... }
+SpreadsheetCell: { fontSize: 'Z2', width: 'E', ... }  // wider than header!
+
+// ✅ CORRECT — all grid elements share the same fontSize
+ColHeaderCell:   { fontSize: 'Z1', width: 'E', ... }
+SpreadsheetCell: { fontSize: 'Z1', width: 'E', ... }
+RowNumberCell:   { fontSize: 'Z1', width: 'C', ... }
+CornerCell:      { fontSize: 'Z1', width: 'C', ... }
+```

package/symbols_mcp/skills/DEFAULT_COMPONENTS.md

@@ -1341,17 +1341,9 @@ export const CircleButton = {
 ```js
 export const CircleProgress = {
   tag: 'progress',
-  attr: {
-    max: ({
-      props
-    }) => props.max,
-    progress: ({
-      props
-    }) => props.progress,
-    value: ({
-      props
-    }) => props.value,
-  },
+  max: ({ props }) => props.max,
+  progress: ({ props }) => props.progress,
+  value: ({ props }) => props.value,
     boxSize: 'D D',
   value: 0.73,
   round: '100%',
@@ -2655,17 +2647,9 @@ export const Pills = {
 ```js
 export const Progress = {
   tag: 'progress',
-  attr: {
-    max: ({
-      props
-    }) => props.max,
-    progress: ({
-      props
-    }) => props.progress,
-    value: ({
-      props
-    }) => props.value,
-  },
+  max: ({ props }) => props.max,
+  progress: ({ props }) => props.progress,
+  value: ({ props }) => props.value,
     height: 'X',
   minWidth: 'F3',
   round: 'Y',

package/symbols_mcp/skills/LEARNINGS.md

@@ -176,7 +176,7 @@ onClick: (e, el, s) => {
 
 ## SPA Navigation — preventDefault Required
 
-When using `tag: 'a'` with `attr: { href: '/' }` AND an `onClick` handler, both the handler and the browser's default navigation fire. Always call `e.preventDefault()`.
+When using `tag: 'a'` with `href: '/'` AND an `onClick` handler, both the handler and the browser's default navigation fire. Always call `e.preventDefault()`.
 
 ```js
 export const NavLink = {