@symbo.ls/mcp-server 3.7.4 → 3.7.6

package/src/mcp-handler.js

@@ -3,6 +3,8 @@
  *
  * Uses pre-bundled skills data (generated by build.js) so it works
  * in both Node.js and Cloudflare Worker environments without fs access.
+ *
+ * Full parity with bin/symbols-mcp.js — 18 tools, all audit checks (Rules 27-33).
  */
 
 import { skills } from './skills-data.js';
@@ -27,7 +29,7 @@ function listSkillFiles() {
 }
 
 // ---------------------------------------------------------------------------
-// Audit helpers (deterministic rule checking)
+// Audit helpers (deterministic rule checking — Rules 27-33)
 // ---------------------------------------------------------------------------
 
 const V2_PATTERNS = [
@@ -57,8 +59,168 @@ const RULE_CHECKS = [
     'Components must be plain objects, not functions that return objects',
   ],
   [
-    /(?:padding|margin|gap|width|height)\s*:\s*['"]?\d+px/,
-    'Use design tokens (A, B, C) instead of hardcoded pixel values',
+    /\bextends\s*:\s*(?!['"])\w+/,
+    "FORBIDDEN: extends must be a quoted string name (extends: 'Name'), not a variable reference — register in components/ and use string lookup (Rule 10)",
+  ],
+  [
+    /extends\s*:\s*['"]Flex['"]/,
+    "Replace extends: 'Flex' with flow: 'x' or flow: 'y' — do NOT just remove it, the element needs flow to stay flex (Rule 26)",
+  ],
+  [/extends\s*:\s*['"]Box['"]/, "Remove extends: 'Box' — every element is already a Box (Rule 26)"],
+  [
+    /extends\s*:\s*['"]Text['"]/,
+    "Remove extends: 'Text' — any element with text: is already Text (Rule 26)",
+  ],
+  [
+    /\bchildExtends\s*:\s*\{/,
+    'FORBIDDEN: childExtends must be a quoted string name, not an inline object — register as a named component (Rule 10)',
+  ],
+  [
+    /(?:padding|margin|gap|width|height|fontSize|borderRadius|minWidth|maxWidth|minHeight|maxHeight|top|left|right|bottom|letterSpacing|lineHeight|borderWidth|outlineWidth)\s*:\s*['"]?\d+(?:\.\d+)?px/,
+    'FORBIDDEN: No raw px values — use design system tokens (A, B, C, etc.) instead of hardcoded pixels (Rule 28)',
+  ],
+  [
+    /(?:color|background|backgroundColor|borderColor|fill|stroke)\s*:\s*['"]#[0-9a-fA-F]/,
+    'Use design system color tokens (primary, secondary, white, gray.5) instead of hardcoded hex colors (Rule 27)',
+  ],
+  [
+    /(?:color|background|backgroundColor|borderColor|fill|stroke)\s*:\s*['"]rgb/,
+    'Use design system color tokens instead of hardcoded rgb/rgba values (Rule 27)',
+  ],
+  [
+    /(?:color|background|backgroundColor|borderColor|fill|stroke)\s*:\s*['"]hsl/,
+    'Use design system color tokens instead of hardcoded hsl/hsla values (Rule 27)',
+  ],
+  [
+    /<svg[\s>]/,
+    'FORBIDDEN: Use the Icon component for SVG icons — store SVGs in designSystem/icons, never inline (Rule 29)',
+  ],
+  [
+    /tag\s*:\s*['"]svg['"]/,
+    "FORBIDDEN: Never use tag: 'svg' — store SVGs in designSystem/icons and use Icon component (Rule 29)",
+  ],
+  [
+    /tag\s*:\s*['"]path['"]/,
+    "FORBIDDEN: Never use tag: 'path' — store SVG paths in designSystem/icons and use Icon component (Rule 29)",
+  ],
+  [
+    /extends\s*:\s*['"]Svg['"]/,
+    'Use Icon component for icons, not Svg — Svg is only for decorative/structural SVGs (Rule 29)',
+  ],
+  [
+    /\biconName\s*:/,
+    "FORBIDDEN: Use icon: not iconName: — the prop is icon: 'name' matching a key in designSystem/icons (Rule 29)",
+  ],
+  [
+    /document\.createElement\b/,
+    'FORBIDDEN: No direct DOM manipulation — use DOMQL declarative object syntax instead (Rule 30)',
+  ],
+  [
+    /\.querySelector\b/,
+    'FORBIDDEN: No DOM queries — reference elements by key name in the DOMQL object tree (Rule 30)',
+  ],
+  [
+    /\.appendChild\b/,
+    'FORBIDDEN: No direct DOM manipulation — nest children as object keys or use children array (Rule 30)',
+  ],
+  [
+    /\.removeChild\b/,
+    'FORBIDDEN: No direct DOM manipulation — use if: (el, s) => condition to show/hide (Rule 30)',
+  ],
+  [
+    /\.insertBefore\b/,
+    'FORBIDDEN: No direct DOM manipulation — use children array ordering (Rule 30)',
+  ],
+  [/\.innerHTML\s*=/, 'FORBIDDEN: No direct DOM manipulation — use text: or html: prop (Rule 30)'],
+  [
+    /\.classList\./,
+    "FORBIDDEN: No direct class manipulation — use isX + '.isX' pattern (Rule 19/30)",
+  ],
+  [
+    /\.setAttribute\b/,
+    'FORBIDDEN: No direct DOM manipulation — set attributes at root level in DOMQL (Rule 30)',
+  ],
+  [
+    /\.addEventListener\b/,
+    'FORBIDDEN: No direct event binding — use onX props: onClick, onInput, etc. (Rule 30)',
+  ],
+  [
+    /\.style\.\w+\s*=/,
+    'FORBIDDEN: No direct style manipulation — use DOMQL CSS-in-props (Rule 30)',
+  ],
+  [
+    /html\s*:\s*\(?.*\)?\s*=>\s*/,
+    'FORBIDDEN: Never use html: as a function returning markup — use DOMQL children, nesting, text:, and if: instead (Rule 31)',
+  ],
+  [
+    /return\s*`<\w+/,
+    'FORBIDDEN: Never return HTML template literals — use DOMQL declarative children and nesting (Rule 31)',
+  ],
+  [
+    /style\s*=\s*['"`]/,
+    'FORBIDDEN: No inline style= strings in html — use DOMQL CSS-in-props (Rule 31)',
+  ],
+  [
+    /window\.innerWidth/,
+    'FORBIDDEN: No window.innerWidth checks — use @mobileL, @tabletS responsive breakpoints (Rule 31)',
+  ],
+  [
+    /\.parentNode\b/,
+    'FORBIDDEN: No DOM traversal — use state and reactive props instead of walking the DOM tree (Rule 32)',
+  ],
+  [
+    /\.childNodes\b/,
+    'FORBIDDEN: No DOM traversal — use state-driven children with if: props (Rule 32)',
+  ],
+  [/\.textContent\b/, 'FORBIDDEN: No DOM property access — use state and text: prop (Rule 32)'],
+  [
+    /Array\.from\(\w+\.children\)/,
+    'FORBIDDEN: No DOM child iteration — use state arrays with children/childExtends and if: filtering (Rule 32)',
+  ],
+  [
+    /\.style\.display\s*=/,
+    'FORBIDDEN: No style.display toggling — use show:/hide: to toggle visibility or if: to remove from DOM (Rule 32)',
+  ],
+  [/\.style\.cssText\s*=/, 'FORBIDDEN: No direct cssText — use DOMQL CSS-in-props (Rule 32)'],
+  [
+    /\.dataset\./,
+    'FORBIDDEN: No dataset manipulation — use state and attr: for data-* attributes (Rule 32)',
+  ],
+  [
+    /\.remove\(\)/,
+    'FORBIDDEN: No DOM node removal — use if: (el, s) => condition to conditionally render (Rule 32)',
+  ],
+  [
+    /el\.node\.\w+\s*=/,
+    'FORBIDDEN: No direct el.node property assignment — use DOMQL props (placeholder:, value:, text:, etc.). Reading el.node is fine (Rule 39), writing is not (Rule 32)',
+  ],
+  [
+    /document\.getElementById\b/,
+    "FORBIDDEN: No document.getElementById — use el.lookdown('key') to find DOMQL elements (Rule 40)",
+  ],
+  [
+    /document\.querySelectorAll\b/,
+    "FORBIDDEN: No document.querySelectorAll — use el.lookdownAll('key') to find DOMQL elements (Rule 40)",
+  ],
+  [
+    /el\.parent\.state\b/,
+    "FORBIDDEN: Never use el.parent.state — with childrenAs: 'state', use s.field directly (Rule 36)",
+  ],
+  [
+    /el\.context\.designSystem\b/,
+    'FORBIDDEN: Never read designSystem from el.context in props — use token strings directly (Rule 38)',
+  ],
+  [
+    /^const\s+\w+\s*=\s*(?:\(|function)/m,
+    "FORBIDDEN: No module-level helper functions — move to functions/ and call via el.call('fnName') (Rule 33)",
+  ],
+  [
+    /^let\s+\w+\s*=/m,
+    'FORBIDDEN: No module-level variables — use el.scope for local state, functions/ for helpers (Rule 33)',
+  ],
+  [
+    /^var\s+\w+\s*=/m,
+    'FORBIDDEN: No module-level variables — use el.scope for local state, functions/ for helpers (Rule 33)',
   ],
 ];
 
@@ -76,7 +238,7 @@ function auditCode(code) {
   }
 
   for (const [pattern, message] of RULE_CHECKS) {
-    const regex = new RegExp(pattern.source, pattern.flags);
+    const regex = new RegExp(pattern.source, pattern.flags || 'g');
     let match;
     while ((match = regex.exec(code)) !== null) {
       const line = code.slice(0, match.index).split('\n').length;
@@ -97,6 +259,322 @@ function auditCode(code) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// JS-to-JSON conversion (mirrors frank pipeline)
+// ---------------------------------------------------------------------------
+
+const DATA_KEYS = [
+  'components',
+  'pages',
+  'snippets',
+  'functions',
+  'methods',
+  'designSystem',
+  'state',
+  'dependencies',
+  'files',
+  'config',
+];
+const CODE_SECTIONS = new Set(['components', 'pages', 'functions', 'methods', 'snippets']);
+
+function findObjectEnd(code, start) {
+  if (start >= code.length) return -1;
+  let i = start;
+  while (i < code.length && ' \t\n\r'.includes(code[i])) i++;
+  if (i >= code.length || !'{['.includes(code[i])) return -1;
+  const opener = code[i];
+  const closer = opener === '{' ? '}' : ']';
+  let depth = 1;
+  i++;
+  let inString = null,
+    inTemplate = false,
+    escaped = false;
+  while (i < code.length && depth > 0) {
+    const ch = code[i];
+    if (escaped) {
+      escaped = false;
+      i++;
+      continue;
+    }
+    if (ch === '\\') {
+      escaped = true;
+      i++;
+      continue;
+    }
+    if (inString) {
+      if (ch === inString) inString = null;
+      i++;
+      continue;
+    }
+    if (inTemplate) {
+      if (ch === '`') inTemplate = false;
+      i++;
+      continue;
+    }
+    if (ch === "'" || ch === '"') inString = ch;
+    else if (ch === '`') inTemplate = true;
+    else if (ch === opener) depth++;
+    else if (ch === closer) depth--;
+    i++;
+  }
+  return depth === 0 ? i : -1;
+}
+
+function parseJsToJson(sourceCode) {
+  const result = {};
+  const code = sourceCode.replace(/^\s*import\s+.*$/gm, '');
+  const stripped = code.trim();
+  if (stripped.startsWith('{')) {
+    try {
+      return JSON.parse(stripped);
+    } catch {}
+  }
+  const exportRe = /export\s+const\s+(\w+)\s*=\s*/g;
+  let m;
+  const matches = [];
+  while ((m = exportRe.exec(code)) !== null) matches.push(m);
+  for (const match of matches) {
+    const name = match[1];
+    const start = match.index + match[0].length;
+    const end = findObjectEnd(code, start);
+    if (end === -1) continue;
+    result[name] = code.slice(start, end).trim();
+  }
+  if (!matches.length) {
+    const defMatch = /export\s+default\s+/.exec(code);
+    if (defMatch) {
+      const start = defMatch.index + defMatch[0].length;
+      const end = findObjectEnd(code, start);
+      if (end !== -1) result['__default__'] = code.slice(start, end).trim();
+    }
+  }
+  return result;
+}
+
+function normalizeQuotes(s) {
+  const result = [];
+  let i = 0;
+  while (i < s.length) {
+    if (s[i] === "'") {
+      let j = i + 1;
+      while (j < s.length) {
+        if (s[j] === '\\' && j + 1 < s.length) {
+          j += 2;
+          continue;
+        }
+        if (s[j] === "'") break;
+        j++;
+      }
+      const inner = s.slice(i + 1, j).replace(/"/g, '\\"');
+      result.push(`"${inner}"`);
+      i = j + 1;
+    } else if (s[i] === '"') {
+      let j = i + 1;
+      while (j < s.length) {
+        if (s[j] === '\\' && j + 1 < s.length) {
+          j += 2;
+          continue;
+        }
+        if (s[j] === '"') break;
+        j++;
+      }
+      result.push(s.slice(i, j + 1));
+      i = j + 1;
+    } else {
+      result.push(s[i]);
+      i++;
+    }
+  }
+  return result.join('');
+}
+
+function isValuePosition(code, pos) {
+  let j = pos - 1;
+  while (j >= 0 && ' \t\n\r'.includes(code[j])) j--;
+  return j >= 0 && ':=,['.includes(code[j]);
+}
+
+function findFunctionEnd(code, start, isArrow) {
+  let i = start;
+  if (isArrow) {
+    const arrowPos = code.indexOf('=>', i);
+    if (arrowPos === -1) return -1;
+    i = arrowPos + 2;
+    while (i < code.length && ' \t\n\r'.includes(code[i])) i++;
+    if (i < code.length && code[i] === '{') return findObjectEnd(code, i);
+    let depth = 0;
+    while (i < code.length) {
+      const ch = code[i];
+      if ('({['.includes(ch)) depth++;
+      else if (')}]'.includes(ch)) {
+        if (depth === 0) return i;
+        depth--;
+      } else if (ch === ',' && depth === 0) return i;
+      i++;
+    }
+    return i;
+  } else {
+    const brace = code.indexOf('{', i);
+    if (brace === -1) return -1;
+    return findObjectEnd(code, brace);
+  }
+}
+
+function stringifyFunctionsInJs(code) {
+  const result = [];
+  let i = 0;
+  while (i < code.length) {
+    const rest = code.slice(i);
+    const arrowMatch = rest.match(/^(\([^)]*\)\s*=>|\w+\s*=>)\s*/);
+    const funcMatch = rest.match(/^function\s*\w*\s*\(/);
+    if (arrowMatch && isValuePosition(code, i)) {
+      const fnEnd = findFunctionEnd(code, i, true);
+      if (fnEnd > i) {
+        result.push(JSON.stringify(code.slice(i, fnEnd).trim()));
+        i = fnEnd;
+        continue;
+      }
+    }
+    if (funcMatch && isValuePosition(code, i)) {
+      const fnEnd = findFunctionEnd(code, i, false);
+      if (fnEnd > i) {
+        result.push(JSON.stringify(code.slice(i, fnEnd).trim()));
+        i = fnEnd;
+        continue;
+      }
+    }
+    result.push(code[i]);
+    i++;
+  }
+  return result.join('');
+}
+
+function jsObjToJson(rawJs) {
+  let s = rawJs.trim();
+  s = stringifyFunctionsInJs(s);
+  s = normalizeQuotes(s);
+  s = s.replace(/(?<=[\{,\n])\s*([a-zA-Z_$][\w$]*)\s*:/g, ' "$1":');
+  s = s.replace(/(?<=[\{,\n])\s*(@[\w$]+)\s*:/g, ' "$1":');
+  s = s.replace(/,\s*([}\]])/g, '$1');
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+}
+
+function encodeSchemaCode(codeStr) {
+  return codeStr.replace(/\n/g, '/////n').replace(/`/g, '/////tilde');
+}
+
+function buildSchemaItem(section, key, value) {
+  const codeStr = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  const item = {
+    title: key,
+    key,
+    type: section,
+    code: encodeSchemaCode(`export default ${codeStr}`),
+  };
+  if (section === 'components' || section === 'pages') {
+    Object.assign(item, {
+      settings: { gridOptions: {} },
+      props: {},
+      interactivity: [],
+      dataTypes: [],
+      error: null,
+    });
+  }
+  return item;
+}
+
+function buildChangesAndSchema(data) {
+  const changes = [],
+    granular = [],
+    orders = [];
+  for (const [sectionKey, sectionData] of Object.entries(data)) {
+    if (!DATA_KEYS.includes(sectionKey)) continue;
+    if (typeof sectionData !== 'object' || sectionData === null || Array.isArray(sectionData)) {
+      changes.push(['update', [sectionKey], sectionData]);
+      granular.push(['update', [sectionKey], sectionData]);
+      continue;
+    }
+    const sectionItemKeys = [];
+    for (const [itemKey, itemValue] of Object.entries(sectionData)) {
+      const itemPath = [sectionKey, itemKey];
+      changes.push(['update', itemPath, itemValue]);
+      sectionItemKeys.push(itemKey);
+      if (typeof itemValue === 'object' && itemValue !== null && !Array.isArray(itemValue)) {
+        const itemKeys = [];
+        for (const [propKey, propValue] of Object.entries(itemValue)) {
+          granular.push(['update', [...itemPath, propKey], propValue]);
+          itemKeys.push(propKey);
+        }
+        if (itemKeys.length) orders.push({ path: itemPath, keys: itemKeys });
+      } else {
+        granular.push(['update', itemPath, itemValue]);
+      }
+      if (CODE_SECTIONS.has(sectionKey)) {
+        const schemaItem = buildSchemaItem(sectionKey, itemKey, itemValue);
+        const schemaPath = ['schema', sectionKey, itemKey];
+        changes.push(['update', schemaPath, schemaItem]);
+        granular.push(['delete', [...schemaPath, 'code']]);
+        for (const [sk, sv] of Object.entries(schemaItem)) {
+          granular.push(['update', [...schemaPath, sk], sv]);
+        }
+      }
+    }
+    if (sectionItemKeys.length) orders.push({ path: [sectionKey], keys: sectionItemKeys });
+  }
+  return { changes, granular, orders };
+}
+
+// ---------------------------------------------------------------------------
+// API helpers
+// ---------------------------------------------------------------------------
+
+const API_BASE = 'https://api.symbols.app';
+
+const AUTH_HELP = `To authenticate, provide one of:
+- **token**: JWT from \`smbls login\` (stored in ~/.smblsrc) or env var SYMBOLS_TOKEN
+- **api_key**: API key (sk_live_...) from your project's integration settings
+
+To get a token:
+1. Run \`smbls login\` in your terminal, or
+2. Use the \`login\` tool with your email and password`;
+
+function authHeader(token, apiKey) {
+  if (apiKey) return { 'Authorization': `ApiKey ${apiKey}`, 'Content-Type': 'application/json' };
+  if (token) return { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' };
+  return null;
+}
+
+async function apiRequest(method, path, { token, api_key, body } = {}) {
+  const headers = authHeader(token, api_key);
+  if (!headers) return { success: false, error: 'No credentials provided', message: AUTH_HELP };
+  const opts = { method, headers };
+  if (body) opts.body = JSON.stringify(body);
+  const resp = await fetch(`${API_BASE}${path}`, opts);
+  try {
+    return await resp.json();
+  } catch {
+    return { success: false, error: `HTTP ${resp.status}`, message: await resp.text() };
+  }
+}
+
+async function resolveProjectId(project, token, apiKey) {
+  if (!project) return { id: '', error: 'Project identifier is required.' };
+  const isKey = project.startsWith('pr_') || !/^[0-9a-f]+$/.test(project);
+  if (isKey) {
+    const result = await apiRequest('GET', `/core/projects/key/${project}`, {
+      token,
+      api_key: apiKey,
+    });
+    if (result.success) return { id: result.data?._id || '', error: null };
+    return { id: '', error: `Project '${project}' not found: ${result.error || 'unknown error'}` };
+  }
+  return { id: project, error: null };
+}
+
 // ---------------------------------------------------------------------------
 // Tools
 // ---------------------------------------------------------------------------
@@ -110,34 +588,27 @@ const TOOLS = [
   },
   {
     name: 'search_symbols_docs',
-    description: 'Search the Symbols documentation knowledge base for relevant information.',
+    description:
+      'Search the Symbols documentation knowledge base for relevant information including CLI commands, SDK services, syntax, components, and more.',
     inputSchema: {
       type: 'object',
       properties: {
         query: {
           type: 'string',
-          description: 'Natural language search query about Symbols/DOMQL',
-        },
-        max_results: {
-          type: 'number',
-          description: 'Maximum number of results (1-5)',
-          default: 3,
+          description: 'Natural language search query about Symbols/DOMQL/CLI/SDK',
         },
+        max_results: { type: 'number', description: 'Maximum number of results (1-5)', default: 3 },
       },
       required: ['query'],
     },
   },
   {
     name: 'generate_component',
-    description:
-      'Generate a Symbols.app DOMQL v3 component from a description. Returns rules, syntax, component catalog, cookbook examples, and default library reference as context.',
+    description: 'Generate a Symbols.app DOMQL v3 component from a description with full context.',
     inputSchema: {
       type: 'object',
       properties: {
-        description: {
-          type: 'string',
-          description: 'What the component should do and look like',
-        },
+        description: { type: 'string', description: 'What the component should do and look like' },
         component_name: {
           type: 'string',
           description: 'PascalCase name for the component',
@@ -149,49 +620,54 @@ const TOOLS = [
   },
   {
     name: 'generate_page',
-    description:
-      'Generate a Symbols.app page with routing integration. Returns rules, project structure, patterns, snippets, and default library reference as context.',
+    description: 'Generate a Symbols.app page with routing integration and full context.',
     inputSchema: {
       type: 'object',
       properties: {
-        description: {
-          type: 'string',
-          description: 'What the page should contain and do',
-        },
-        page_name: {
-          type: 'string',
-          description: 'camelCase name for the page',
-          default: 'home',
-        },
+        description: { type: 'string', description: 'What the page should contain and do' },
+        page_name: { type: 'string', description: 'camelCase name for the page', default: 'home' },
       },
       required: ['description'],
     },
   },
   {
     name: 'convert_react',
-    description:
-      'Convert React/JSX code to Symbols.app DOMQL v3. Returns migration rules, syntax reference, and examples as context.',
+    description: 'Convert React/JSX code to Symbols.app DOMQL v3 with migration context.',
     inputSchema: {
       type: 'object',
       properties: {
-        source_code: {
-          type: 'string',
-          description: 'The React/JSX source code to convert',
-        },
+        source_code: { type: 'string', description: 'The React/JSX source code to convert' },
       },
       required: ['source_code'],
     },
   },
   {
     name: 'convert_html',
+    description: 'Convert raw HTML/CSS to Symbols.app DOMQL v3 components with full context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source_code: { type: 'string', description: 'The HTML/CSS source code to convert' },
+      },
+      required: ['source_code'],
+    },
+  },
+  {
+    name: 'convert_to_json',
     description:
-      'Convert raw HTML/CSS to Symbols.app DOMQL v3 components. Returns component catalog, syntax reference, and design tokens as context.',
+      'Convert DOMQL v3 JavaScript source code to platform JSON format for save_to_project.',
     inputSchema: {
       type: 'object',
       properties: {
         source_code: {
           type: 'string',
-          description: 'The HTML/CSS source code to convert',
+          description: 'JavaScript source code with export const/default statements',
+        },
+        section: {
+          type: 'string',
+          description:
+            'Target section: components, pages, functions, snippets, designSystem, state',
+          default: 'components',
         },
       },
       required: ['source_code'],
@@ -200,202 +676,149 @@ const TOOLS = [
   {
     name: 'audit_component',
     description:
-      'Audit a Symbols/DOMQL component for v3 compliance and best practices. Returns a structured report with violations, warnings, and compliance score.',
+      'Audit a Symbols/DOMQL component for v3 compliance — checks for v2 syntax, raw px values, hardcoded colors, direct DOM manipulation, and more.',
     inputSchema: {
       type: 'object',
       properties: {
-        component_code: {
-          type: 'string',
-          description: 'The JavaScript component code to audit',
-        },
+        component_code: { type: 'string', description: 'The JavaScript component code to audit' },
       },
       required: ['component_code'],
     },
   },
   {
-    name: 'login',
+    name: 'detect_environment',
     description:
-      'Log in to the Symbols platform with email and password. Returns a JWT token for use with publish and push tools.',
+      'Detect project type (local, CDN, JSON runtime, or remote server) based on project indicators.',
     inputSchema: {
       type: 'object',
       properties: {
-        email: {
-          type: 'string',
-          description: 'Symbols account email address',
-        },
-        password: {
-          type: 'string',
-          description: 'Symbols account password',
-        },
+        has_symbols_json: { type: 'boolean' },
+        has_symbols_dir: { type: 'boolean' },
+        has_package_json: { type: 'boolean' },
+        has_cdn_import: { type: 'boolean' },
+        has_iife_script: { type: 'boolean' },
+        has_json_data: { type: 'boolean' },
+        has_mermaid_config: { type: 'boolean' },
+        file_list: { type: 'string', default: '' },
       },
+    },
+  },
+  {
+    name: 'get_cli_reference',
+    description: 'Returns the complete Symbols CLI (@symbo.ls/cli) command reference.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'get_sdk_reference',
+    description: 'Returns the complete Symbols SDK (@symbo.ls/sdk) API reference.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'login',
+    description: 'Log in to the Symbols platform and get an access token.',
+    inputSchema: {
+      type: 'object',
+      properties: { email: { type: 'string' }, password: { type: 'string' } },
       required: ['email', 'password'],
     },
   },
   {
-    name: 'publish',
-    description:
-      'Publish a version of a Symbols project to the platform. Requires authentication via token or api_key.',
+    name: 'list_projects',
+    description: "List the user's Symbols projects (names, keys, IDs).",
+    inputSchema: {
+      type: 'object',
+      properties: { token: { type: 'string' }, api_key: { type: 'string' } },
+    },
+  },
+  {
+    name: 'create_project',
+    description: 'Create a new Symbols project on the platform.',
     inputSchema: {
       type: 'object',
       properties: {
-        project: {
-          type: 'string',
-          description: 'Project ID (MongoDB ObjectId) or project key (pr_xxxx)',
-        },
-        token: {
-          type: 'string',
-          description: 'JWT access token from login or ~/.smblsrc',
-        },
-        api_key: {
-          type: 'string',
-          description:
-            'API key (sk_live_...) from project integration settings. Alternative to token.',
-        },
-        version: {
-          type: 'string',
-          description: 'Version string or version ID to publish. Leave empty for latest.',
-          default: '',
-        },
-        branch: {
-          type: 'string',
-          description: 'Branch to publish from',
-          default: 'main',
-        },
+        name: { type: 'string' },
+        key: { type: 'string' },
+        token: { type: 'string' },
+        api_key: { type: 'string' },
+        visibility: { type: 'string', default: 'private' },
+      },
+      required: ['name'],
+    },
+  },
+  {
+    name: 'get_project',
+    description: "Get a project's current data (components, pages, design system, state).",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        token: { type: 'string' },
+        api_key: { type: 'string' },
+        branch: { type: 'string', default: 'main' },
       },
       required: ['project'],
     },
   },
   {
-    name: 'push',
+    name: 'save_to_project',
     description:
-      'Push/deploy a Symbols project to a specific environment. Requires authentication via token or api_key.',
+      'Save components/pages/data to a project — creates a new version with change tuples, granular changes, orders, and auto-generated schema entries.',
     inputSchema: {
       type: 'object',
       properties: {
-        project: {
-          type: 'string',
-          description: 'Project ID (MongoDB ObjectId) or project key (pr_xxxx)',
-        },
-        token: {
-          type: 'string',
-          description: 'JWT access token from login or ~/.smblsrc',
-        },
-        api_key: {
-          type: 'string',
-          description:
-            'API key (sk_live_...) from project integration settings. Alternative to token.',
-        },
-        environment: {
-          type: 'string',
-          description: 'Target environment key (e.g. "production", "staging", "dev")',
-          default: 'production',
-        },
-        mode: {
-          type: 'string',
-          description:
-            'Deploy mode — "latest" (newest from branch), "published" (current published version), "version" (specific version), or "branch" (track a branch)',
-          default: 'published',
-        },
-        version: {
-          type: 'string',
-          description: 'Required when mode is "version" — the version string or ID to deploy',
-          default: '',
-        },
-        branch: {
-          type: 'string',
-          description: 'Branch to deploy from when mode is "latest" or "branch"',
-          default: 'main',
-        },
+        project: { type: 'string' },
+        changes: { type: 'string', description: 'JSON string with project data' },
+        token: { type: 'string' },
+        api_key: { type: 'string' },
+        message: { type: 'string' },
+        branch: { type: 'string', default: 'main' },
+      },
+      required: ['project', 'changes'],
+    },
+  },
+  {
+    name: 'publish',
+    description: 'Publish a version of a Symbols project (make it live).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: { type: 'string' },
+        token: { type: 'string' },
+        api_key: { type: 'string' },
+        version: { type: 'string' },
+        branch: { type: 'string', default: 'main' },
       },
       required: ['project'],
     },
   },
   {
-    name: 'detect_environment',
-    description:
-      'Detect what type of Symbols environment the user is working in (local project, CDN, JSON runtime, or remote server) based on project indicators, and return the appropriate setup guide and code format.',
+    name: 'push',
+    description: 'Deploy a Symbols project to an environment (production, staging, dev).',
     inputSchema: {
       type: 'object',
       properties: {
-        has_symbols_json: {
-          type: 'boolean',
-          description: 'Whether symbols.json exists in the project root',
-        },
-        has_symbols_dir: {
-          type: 'boolean',
-          description: 'Whether a symbols/ directory exists with components/, pages/, etc.',
-        },
-        has_package_json: {
-          type: 'boolean',
-          description: 'Whether package.json exists with smbls dependency',
-        },
-        has_cdn_import: {
-          type: 'boolean',
-          description:
-            'Whether HTML files contain CDN imports (esm.sh/smbls, cdn.jsdelivr.net/npm/smbls, etc.)',
-        },
-        has_iife_script: {
-          type: 'boolean',
-          description: 'Whether HTML files use <script src="...smbls"> (IIFE global)',
-        },
-        has_json_data: {
-          type: 'boolean',
-          description: 'Whether the project uses frank-generated JSON data files',
-        },
-        has_mermaid_config: {
-          type: 'boolean',
-          description:
-            'Whether mermaid/wrangler config or GATEWAY_URL/JSON_PATH env vars are present',
-        },
-        file_list: {
-          type: 'string',
-          description:
-            'Comma-separated list of key files in the project root (e.g. "index.html,package.json,symbols.json")',
-        },
+        project: { type: 'string' },
+        token: { type: 'string' },
+        api_key: { type: 'string' },
+        environment: { type: 'string', default: 'production' },
+        mode: { type: 'string', default: 'published' },
+        version: { type: 'string' },
+        branch: { type: 'string', default: 'main' },
       },
+      required: ['project'],
     },
   },
 ];
 
-const API_BASE = 'https://api.symbols.app';
-
-const AUTH_HELP = `To authenticate, provide one of:
-- **token**: JWT from \`smbls login\` (stored in ~/.smblsrc) or env var SYMBOLS_TOKEN
-- **api_key**: API key (sk_live_...) from your project's integration settings
-
-To get a token:
-1. Run \`smbls login\` in your terminal, or
-2. Use the \`login\` tool with your email and password
-
-Your project can be identified by either:
-- **project**: MongoDB ObjectId (from project settings or symbols.json)
-- **project**: Project key (pr_xxxx, found in symbols.json or project URL)`;
-
-function authHeader(token, apiKey) {
-  if (apiKey) return { 'Authorization': `ApiKey ${apiKey}`, 'Content-Type': 'application/json' };
-  if (token) return { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' };
-  return null;
-}
-
-async function apiRequest(method, path, { token, api_key, body } = {}) {
-  const headers = authHeader(token, api_key);
-  if (!headers) return { success: false, error: 'No credentials provided', message: AUTH_HELP };
-  const resp = await fetch(`${API_BASE}${path}`, {
-    method,
-    headers,
-    body: body ? JSON.stringify(body) : undefined,
-  });
-  try {
-    return await resp.json();
-  } catch {
-    return { success: false, error: `HTTP ${resp.status}`, message: await resp.text() };
-  }
-}
+const MANDATORY_REQUIREMENTS = `- **MANDATORY: ALL values MUST use design system tokens** — spacing (A, B, C, D), colors (primary, surface, white, gray.5), typography (fontSize: 'B'). ZERO px values, ZERO hex colors, ZERO rgb/hsl.
+- Use Icon component for SVGs — store icons in designSystem/icons
+- NO direct DOM manipulation — all structure via DOMQL declarative syntax
+- NO variables outside component scope — use el.call('fn') or el.scope`;
 
 async function callTool(name, args = {}) {
-  if (name === 'get_project_rules') {
-    return readSkill('RULES.md');
-  }
+  if (name === 'get_project_rules') return readSkill('RULES.md');
+  if (name === 'get_cli_reference') return readSkill('CLI.md');
+  if (name === 'get_sdk_reference') return readSkill('SDK.md');
 
   if (name === 'search_symbols_docs') {
     const query = args.query || '';
@@ -405,13 +828,10 @@ async function callTool(name, args = {}) {
       .split(/\s+/)
       .filter((w) => w.length > 2);
     if (!keywords.length) keywords.push(query.toLowerCase());
-
     const results = [];
     for (const fname of listSkillFiles()) {
       const content = readSkill(fname);
-      const contentLower = content.toLowerCase();
-      if (!keywords.some((kw) => contentLower.includes(kw))) continue;
-
+      if (!keywords.some((kw) => content.toLowerCase().includes(kw))) continue;
       const lines = content.split('\n');
       for (let i = 0; i < lines.length; i++) {
         if (keywords.some((kw) => lines[i].toLowerCase().includes(kw))) {
@@ -424,41 +844,37 @@ async function callTool(name, args = {}) {
       }
       if (results.length >= maxResults) break;
     }
-
-    return results.length
-      ? JSON.stringify(results, null, 2)
-      : `No results found for '${query}'. Try a different search term.`;
+    return results.length ? JSON.stringify(results, null, 2) : `No results found for '${query}'.`;
   }
 
   if (name === 'generate_component') {
-    const desc = args.description || '';
     const compName = args.component_name || 'MyComponent';
     const context = readSkills(
       'RULES.md',
+      'COMMON_MISTAKES.md',
       'COMPONENTS.md',
       'SYNTAX.md',
       'COOKBOOK.md',
       'DEFAULT_LIBRARY.md',
     );
-    return `# Generate Component: ${compName}\n\n## Description\n${desc}\n\n## Requirements\n- Named export: \`export const ${compName} = { ... }\`\n- DOMQL v3 syntax only (extends, childExtends, flattened props, onX events)\n- Use design tokens for spacing (A, B, C), colors from theme\n- NO imports between files — PascalCase keys auto-extend registered components\n- Include responsive breakpoints where appropriate (@tabletS, @mobileL)\n- Use the default library components (Button, Avatar, Icon, Field, etc.) via extends\n- Follow modern UI/UX: visual hierarchy, confident typography, minimal cognitive load\n\n## Context — Rules, Syntax & Examples\n\n${context}`;
+    return `# Generate Component: ${compName}\n\n## Description\n${args.description}\n\n## Requirements\n- Named export: \`export const ${compName} = { ... }\`\n- DOMQL v3 syntax only (extends, childExtends, flattened props, onX events)\n${MANDATORY_REQUIREMENTS}\n- NO imports between files — PascalCase keys auto-extend registered components\n- Include responsive breakpoints where appropriate (@tabletS, @mobileL)\n- Use the default library components (Button, Avatar, Icon, Field, etc.) via extends\n- Follow modern UI/UX: visual hierarchy, confident typography, minimal cognitive load\n\n## Context — Rules, Syntax & Examples\n\n${context}`;
   }
 
   if (name === 'generate_page') {
-    const desc = args.description || '';
     const pageName = args.page_name || 'home';
     const context = readSkills(
       'RULES.md',
+      'COMMON_MISTAKES.md',
       'PROJECT_STRUCTURE.md',
       'PATTERNS.md',
       'SNIPPETS.md',
       'DEFAULT_LIBRARY.md',
       'COMPONENTS.md',
     );
-    return `# Generate Page: ${pageName}\n\n## Description\n${desc}\n\n## Requirements\n- Export as: \`export const ${pageName} = { ... }\`\n- Page is a plain object composing components\n- Add to pages/index.js route map: \`'/${pageName}': ${pageName}\`\n- Use components by PascalCase key (Header, Footer, Hero, etc.)\n- Use design tokens — no hardcoded pixels\n- Include responsive layout adjustments\n\n## Context — Rules, Structure, Patterns & Snippets\n\n${context}`;
+    return `# Generate Page: ${pageName}\n\n## Description\n${args.description}\n\n## Requirements\n- Export as: \`export const ${pageName} = { ... }\`\n- Page is a plain object composing components\n- Add to pages/index.js route map: \`'/${pageName}': ${pageName}\`\n- Use components by PascalCase key (Header, Footer, Hero, etc.)\n${MANDATORY_REQUIREMENTS}\n- Include responsive layout adjustments\n\n## Context — Rules, Structure, Patterns & Snippets\n\n${context}`;
   }
 
   if (name === 'convert_react') {
-    const source = args.source_code || '';
     const context = readSkills(
       'RULES.md',
       'MIGRATION.md',
@@ -466,11 +882,10 @@ async function callTool(name, args = {}) {
       'COMPONENTS.md',
       'LEARNINGS.md',
     );
-    return `# Convert React → Symbols DOMQL v3\n\n## Source Code to Convert\n\`\`\`jsx\n${source}\n\`\`\`\n\n## Conversion Rules\n- Function/class components → plain object exports\n- JSX → nested object children (PascalCase keys auto-extend)\n- import/export between files → REMOVE (reference by key name)\n- useState → state: { key: val } + s.update({ key: newVal })\n- useEffect → onRender (mount), onStateUpdate (deps)\n- props → flattened directly on component (no props wrapper)\n- onClick={handler} → onClick: (event, el, state) => {}\n- className → use design tokens and theme directly\n- map() → children: (el, s) => s.items, childExtends, childProps\n- conditional rendering → if: (el, s) => boolean\n- CSS modules/styled → CSS-in-props with design tokens\n- React.Fragment → not needed, just nest children\n\n## Context — Migration Guide, Syntax & Rules\n\n${context}`;
+    return `# Convert React → Symbols DOMQL v3\n\n## Source Code to Convert\n\`\`\`jsx\n${args.source_code}\n\`\`\`\n\n## Conversion Rules\n- Function/class components → plain object exports\n- JSX → nested object children (PascalCase keys auto-extend)\n- import/export between files → REMOVE (reference by key name)\n- useState → state: { key: val } + s.update({ key: newVal })\n- useEffect → onRender (mount), onStateUpdate (deps)\n- props → flattened directly on component (no props wrapper)\n- onClick={handler} → onClick: (event, el, state) => {}\n- className → use design tokens and theme directly\n- map() → children: (el, s) => s.items, childExtends, childProps\n- conditional rendering → if: (el, s) => boolean\n- CSS modules/styled → CSS-in-props with design tokens\n- React.Fragment → not needed, just nest children\n${MANDATORY_REQUIREMENTS}\n\n## Context — Migration Guide, Syntax & Rules\n\n${context}`;
   }
 
   if (name === 'convert_html') {
-    const source = args.source_code || '';
     const context = readSkills(
       'RULES.md',
       'SYNTAX.md',
@@ -479,43 +894,97 @@ async function callTool(name, args = {}) {
       'SNIPPETS.md',
       'LEARNINGS.md',
     );
-    return `# Convert HTML → Symbols DOMQL v3\n\n## Source Code to Convert\n\`\`\`html\n${source}\n\`\`\`\n\n## Conversion Rules\n- <div> → Box, Flex, or Grid (based on layout purpose)\n- <span>, <p>, <h1>-<h6> → Text, P, H with tag property\n- <a> → Link (has built-in SPA router)\n- <button> → Button (has icon/text support)\n- <input> → Input, Radio, Checkbox (based on type)\n- <img> → Img\n- <form> → Form (extends Box with tag: 'form')\n- <ul>/<ol> + <li> → children array with childExtends\n- CSS classes → flatten as CSS-in-props on the component\n- CSS px values → design tokens (16px → 'A', 26px → 'B', 42px → 'C')\n- CSS colors → theme color tokens\n- media queries → @tabletS, @mobileL, @screenS breakpoints\n- id/class attributes → not needed (use key names and themes)\n- inline styles → flatten as component properties\n- <style> blocks → distribute to component-level properties\n\n## Context — Syntax, Components & Design System\n\n${context}`;
+    return `# Convert HTML → Symbols DOMQL v3\n\n## Source Code to Convert\n\`\`\`html\n${args.source_code}\n\`\`\`\n\n## Conversion Rules\n- <div> → Box, Flex, or Grid (based on layout purpose)\n- <span>, <p>, <h1>-<h6> → Text, P, H with tag property\n- <a> → Link (has built-in SPA router)\n- <button> → Button (has icon/text support)\n- <input> → Input, Radio, Checkbox (based on type)\n- <img> → Img\n- <form> → Form (extends Box with tag: 'form')\n- <ul>/<ol> + <li> → children array with childExtends\n- CSS classes → flatten as CSS-in-props on the component\n- CSS px values → design tokens (16px → 'A', 26px → 'B', 42px → 'C')\n- CSS colors → theme color tokens\n- media queries → @tabletS, @mobileL, @screenS breakpoints\n${MANDATORY_REQUIREMENTS}\n\n## Context — Syntax, Components & Design System\n\n${context}`;
+  }
+
+  if (name === 'convert_to_json') {
+    const section = args.section || 'components';
+    const parsed = parseJsToJson(args.source_code);
+    if (!Object.keys(parsed).length) return 'Could not parse any exports from the source code.';
+    const result = {};
+    for (const [exportName, rawValue] of Object.entries(parsed)) {
+      const converted = typeof rawValue === 'string' ? jsObjToJson(rawValue) : rawValue;
+      if (exportName === '__default__') {
+        if (['designSystem', 'state', 'dependencies', 'config'].includes(section))
+          result[section] = converted;
+        else {
+          if (!result[section]) result[section] = {};
+          result[section]['default'] = converted;
+        }
+      } else {
+        if (!result[section]) result[section] = {};
+        result[section][exportName] = converted;
+      }
+    }
+    const output = JSON.stringify(result, null, 2);
+    const sections = Object.keys(result);
+    const items = [];
+    for (const sec of sections)
+      if (typeof result[sec] === 'object' && result[sec]) items.push(...Object.keys(result[sec]));
+    return `# Converted to Platform JSON\n\n**Section:** ${sections.join(', ')}\n**Items:** ${items.join(', ') || 'default export'}\n\n\`\`\`json\n${output}\n\`\`\`\n\nThis JSON is ready to use with \`save_to_project\`.`;
   }
 
   if (name === 'audit_component') {
-    const code = args.component_code || '';
-    const result = auditCode(code);
+    const result = auditCode(args.component_code || '');
     const rulesContext = readSkill('AUDIT.md');
-
     let output = `# Audit Report\n\n## Summary\n${result.summary}\nPassed: ${result.passed ? 'Yes' : 'No'}\n\n## Violations (Errors)\n`;
     if (result.violations.length) {
-      for (const v of result.violations) {
-        output += `- **Line ${v.line}**: ${v.message}\n`;
-      }
-    } else {
-      output += 'No violations found.\n';
-    }
-
+      for (const v of result.violations) output += `- **Line ${v.line}**: ${v.message}\n`;
+    } else output += 'No violations found.\n';
     output += '\n## Warnings\n';
     if (result.warnings.length) {
-      for (const w of result.warnings) {
-        output += `- **Line ${w.line}**: ${w.message}\n`;
-      }
-    } else {
-      output += 'No warnings.\n';
+      for (const w of result.warnings) output += `- **Line ${w.line}**: ${w.message}\n`;
+    } else output += 'No warnings.\n';
+    if (result.violations.length) {
+      output +=
+        '\n## MANDATORY ACTION\n\n**Every violation above MUST be fixed. There is NO concept of "known debt" or "accepted violations" in Symbols. Do NOT label any violation as "known debt" or defer it. Rewrite the code using proper DOMQL syntax.**\n\n';
     }
-
     output += `\n## Detailed Rules Reference\n\n${rulesContext}`;
     return output;
   }
 
+  if (name === 'detect_environment') {
+    let envType = 'unknown',
+      confidence = 'low';
+    if (args.has_mermaid_config) {
+      envType = 'remote_server';
+      confidence = 'high';
+    } else if (args.has_json_data) {
+      envType = 'json_runtime';
+      confidence = 'high';
+    } else if (args.has_symbols_json && args.has_symbols_dir) {
+      envType = 'local_project';
+      confidence = 'high';
+    } else if (args.has_symbols_dir || (args.has_package_json && args.has_symbols_json)) {
+      envType = 'local_project';
+      confidence = 'medium';
+    } else if (args.has_cdn_import || args.has_iife_script) {
+      envType = 'cdn';
+      confidence = 'high';
+    } else if (args.has_package_json) {
+      envType = 'local_project';
+      confidence = 'low';
+    } else if (args.file_list) {
+      const files = args.file_list.toLowerCase();
+      if (
+        files.includes('index.html') &&
+        !files.includes('package.json') &&
+        !files.includes('symbols.json')
+      ) {
+        envType = 'cdn';
+        confidence = 'medium';
+      }
+    }
+    const guide = readSkill('RUNNING_APPS.md');
+    return `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n${guide}`;
+  }
+
   if (name === 'login') {
-    const { email, password } = args;
-    if (!email || !password) return 'Error: email and password are required.';
+    if (!args.email || !args.password) return 'Error: email and password are required.';
     const resp = await fetch(`${API_BASE}/core/auth/login`, {
       method: 'POST',
       headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email, password }),
+      body: JSON.stringify({ email: args.email, password: args.password }),
     });
     let result;
     try {
@@ -524,169 +993,161 @@ async function callTool(name, args = {}) {
       return `Login failed: HTTP ${resp.status}`;
     }
     if (result.success) {
-      const data = result.data || {};
-      const tokens = data.tokens || {};
-      const user = data.user || {};
-      return `Logged in as ${user.name || user.email || 'unknown'}.\nToken: ${tokens.accessToken || ''}\nExpires: ${(tokens.accessTokenExp || {}).expiresAt || 'unknown'}\n\nUse this token with the \`publish\` and \`push\` tools.`;
+      const { tokens = {}, user = {} } = result.data || {};
+      return `Logged in as ${user.name || user.email || 'unknown'}.\nToken: ${tokens.accessToken || ''}\nExpires: ${tokens.accessTokenExp?.expiresAt || 'unknown'}\n\nUse this token with project, save, publish and push tools.`;
     }
     return `Login failed: ${result.error || result.message || 'Unknown error'}`;
   }
 
-  if (name === 'publish') {
-    const { project, token, api_key, version, branch = 'main' } = args;
-    if (!project) return 'Error: project (ID or key) is required.';
-    if (!token && !api_key) return `Authentication required.\n\n${AUTH_HELP}`;
-    const body = { branch };
-    if (version) body.version = version;
-    const result = await apiRequest('POST', `/${project}/publish`, { token, api_key, body });
+  if (name === 'list_projects') {
+    if (!args.token && !args.api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const result = await apiRequest('GET', '/core/projects', {
+      token: args.token,
+      api_key: args.api_key,
+    });
     if (result.success) {
-      const data = result.data || {};
-      return `Published successfully.\nVersion: ${data.value || data.id || 'unknown'}`;
+      const projects = result.data || [];
+      if (!projects.length) return 'No projects found. Use `create_project` to create one.';
+      return (
+        '# Your Projects\n\n' +
+        projects
+          .map(
+            (p) =>
+              `- **${p.name || 'Untitled'}** — key: \`${p.key || '—'}\`, id: \`${p._id || ''}\``,
+          )
+          .join('\n')
+      );
     }
-    return `Publish failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
+    return `Failed to list projects: ${result.error || 'Unknown error'}`;
   }
 
-  if (name === 'push') {
-    const {
-      project,
-      token,
-      api_key,
-      environment = 'production',
-      mode = 'published',
-      version,
-      branch = 'main',
-    } = args;
-    if (!project) return 'Error: project (ID or key) is required.';
-    if (!token && !api_key) return `Authentication required.\n\n${AUTH_HELP}`;
-    const body = { mode, branch };
-    if (version) body.version = version;
-    const result = await apiRequest('POST', `/${project}/environments/${environment}/publish`, {
-      token,
-      api_key,
+  if (name === 'create_project') {
+    if (!args.token && !args.api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const body = {
+      name: args.name,
+      visibility: args.visibility || 'private',
+      language: 'javascript',
+    };
+    if (args.key) body.key = args.key;
+    const result = await apiRequest('POST', '/core/projects', {
+      token: args.token,
+      api_key: args.api_key,
       body,
     });
     if (result.success) {
-      const data = result.data || {};
-      const config = data.config || {};
-      return `Pushed to ${data.key || environment} successfully.\nMode: ${config.mode || mode}\nVersion: ${config.version || 'latest'}\nBranch: ${config.branch || branch}`;
+      const d = result.data || {};
+      return `Project created.\nName: ${d.name}\nKey: \`${d.key}\`\nID: \`${d._id}\`\n\nUse with \`save_to_project\` to push components.`;
     }
-    return `Push failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
+    return `Create failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
   }
 
-  if (name === 'detect_environment') {
-    const {
-      has_symbols_json,
-      has_symbols_dir,
-      has_package_json,
-      has_cdn_import,
-      has_iife_script,
-      has_json_data,
-      has_mermaid_config,
-      file_list,
-    } = args;
-
-    // Detect environment type
-    let envType = 'unknown';
-    let confidence = 'low';
-
-    if (has_mermaid_config) {
-      envType = 'remote_server';
-      confidence = 'high';
-    } else if (has_json_data) {
-      envType = 'json_runtime';
-      confidence = 'high';
-    } else if (has_symbols_json && has_symbols_dir) {
-      envType = 'local_project';
-      confidence = 'high';
-    } else if (has_symbols_dir || (has_package_json && has_symbols_json)) {
-      envType = 'local_project';
-      confidence = 'medium';
-    } else if (has_cdn_import || has_iife_script) {
-      envType = 'cdn';
-      confidence = 'high';
-    } else if (has_package_json) {
-      envType = 'local_project';
-      confidence = 'low';
-    } else if (file_list) {
-      const files = file_list.toLowerCase();
-      if (
-        files.includes('index.html') &&
-        !files.includes('package.json') &&
-        !files.includes('symbols.json')
-      ) {
-        envType = 'cdn';
-        confidence = 'medium';
-      }
+  if (name === 'get_project') {
+    if (!args.token && !args.api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const branch = args.branch || 'main';
+    const isKey = args.project.startsWith('pr_') || !/^[0-9a-f]+$/.test(args.project);
+    const path = isKey
+      ? `/core/projects/key/${args.project}/data?branch=${branch}&version=latest`
+      : `/core/projects/${args.project}/data?branch=${branch}&version=latest`;
+    const result = await apiRequest('GET', path, { token: args.token, api_key: args.api_key });
+    if (result.success) {
+      const data = result.data || {};
+      return `# Project Data (branch: ${branch})\n\n**Components (${Object.keys(data.components || {}).length}):** ${
+        Object.keys(data.components || {})
+          .slice(0, 20)
+          .join(', ') || 'none'
+      }\n**Pages (${Object.keys(data.pages || {}).length}):** ${
+        Object.keys(data.pages || {})
+          .slice(0, 20)
+          .join(', ') || 'none'
+      }\n\n\`\`\`json\n${JSON.stringify(data, null, 2).slice(0, 8000)}\n\`\`\``;
     }
+    return `Failed to get project: ${result.error || 'Unknown error'}`;
+  }
 
-    // Build response with appropriate guide
-    const fullGuide = readSkill('RUNNING_APPS.md');
-    let output = `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n`;
-
-    if (envType === 'local_project') {
-      output += `## Your Environment: Local Project\n\n`;
-      output += `You're working in a standard Symbols project with file-based structure.\n\n`;
-      output += `### Code Format\n`;
-      output += `- Components: \`export const Name = { extends: 'Flex', ... }\` in \`components/\`\n`;
-      output += `- Pages: \`export const pageName = { extends: 'Page', ... }\` in \`pages/\`\n`;
-      output += `- State: \`export default { key: value }\` in \`state.js\`\n`;
-      output += `- Functions: \`export const fn = function() {}\` in \`functions/\`\n`;
-      output += `- No imports between files (except pages/index.js)\n\n`;
-      output += `### Commands\n`;
-      output += `\`\`\`bash\nnpm start          # dev server\nsmbls build        # production build\nsmbls push         # deploy to platform\nsmbls deploy       # deploy to provider\n\`\`\`\n\n`;
-      const structureGuide = readSkill('PROJECT_STRUCTURE.md');
-      output += `### Full Project Structure Reference\n\n${structureGuide}`;
-    } else if (envType === 'cdn') {
-      output += `## Your Environment: CDN (Browser-Only)\n\n`;
-      output += `You're running Symbols directly in the browser via CDN import.\n\n`;
-      output += `### Code Format\n`;
-      output += `- Single HTML file with \`<script type="module">\`\n`;
-      output += `- Import: \`import { create } from 'https://esm.sh/smbls'\`\n`;
-      output += `- Define app as inline object tree\n`;
-      output += `- Mount: \`create(App, { designSystem, components, functions, state })\`\n`;
-      output += `- Components defined as JS variables (no file-based registry)\n\n`;
-      output += `### Limitations\n`;
-      output += `- No file-based routing (use tab/view switching)\n`;
-      output += `- No SSR\n`;
-      output += `- \`childExtends: 'Name'\` needs components passed to \`create()\`\n\n`;
-      const cdnGuide = readSkill('RUNNING_APPS.md');
-      output += `### Full CDN Reference\n\n${cdnGuide}`;
-    } else if (envType === 'json_runtime') {
-      output += `## Your Environment: JSON Runtime (Frank)\n\n`;
-      output += `You're running Symbols from serialized JSON project data.\n\n`;
-      output += `### Code Format\n`;
-      output += `- Project data is a JSON object with components, pages, designSystem, state, functions\n`;
-      output += `- Functions are serialized as strings\n`;
-      output += `- Convert with: \`smbls frank to-json ./symbols\` or \`toJSON({ entry: './symbols' })\`\n`;
-      output += `- Reverse with: \`smbls frank to-fs data.json -o ./output\` or \`toFS(data, './output')\`\n`;
-      output += `- Can be loaded by Mermaid server via JSON_PATH env var\n\n`;
-      output += `### Full Reference\n\n${fullGuide}`;
-    } else if (envType === 'remote_server') {
-      output += `## Your Environment: Remote Symbols Server (Mermaid)\n\n`;
-      output += `You're working with the Mermaid rendering server for hosted Symbols apps.\n\n`;
-      output += `### URL Patterns\n`;
-      output += `- Production: \`https://app.user.preview.symbols.app/\`\n`;
-      output += `- Development: \`https://app.user.preview.dev.symbols.app/\`\n`;
-      output += `- Staging: \`https://app.user.preview.staging.symbols.app/\`\n`;
-      output += `- Legacy: \`https://app.symbo.ls/\`\n`;
-      output += `- Custom domains supported\n\n`;
-      output += `### Deployment\n`;
-      output += `\`\`\`bash\nsmbls push    # deploy to Symbols platform\n\`\`\`\n\n`;
-      output += `### Full Reference\n\n${fullGuide}`;
-    } else {
-      output += `## Could Not Determine Environment\n\n`;
-      output += `Provide more details about your project files to get specific guidance.\n\n`;
-      output += `### All 4 Ways to Run Symbols Apps\n\n${fullGuide}`;
+  if (name === 'save_to_project') {
+    if (!args.token && !args.api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    let changesData;
+    try {
+      changesData = JSON.parse(args.changes);
+    } catch (e) {
+      return `Invalid JSON: ${e.message}`;
     }
+    const { id: projectId, error: resolveErr } = await resolveProjectId(
+      args.project,
+      args.token,
+      args.api_key,
+    );
+    if (resolveErr) return resolveErr;
+    const { changes, granular, orders } = buildChangesAndSchema(changesData);
+    if (!changes.length) return 'No valid changes found.';
+    const branch = args.branch || 'main';
+    const result = await apiRequest('POST', `/core/projects/${projectId}/changes`, {
+      token: args.token,
+      api_key: args.api_key,
+      body: {
+        changes,
+        granularChanges: granular,
+        orders,
+        message: args.message || 'Updated via Symbols MCP',
+        branch,
+        type: 'patch',
+      },
+    });
+    if (result.success) {
+      const d = result.data || {};
+      return `Saved to \`${args.project}\`.\nVersion: ${d.value || d.version || d.id || 'unknown'}\nBranch: ${branch}\nSections: ${Object.keys(changesData).join(', ')}\n\nUse \`publish\` then \`push\` to deploy.`;
+    }
+    return `Save failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
+  }
 
-    return output;
+  if (name === 'publish') {
+    if (!args.token && !args.api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const { id: projectId, error: resolveErr } = await resolveProjectId(
+      args.project,
+      args.token,
+      args.api_key,
+    );
+    if (resolveErr) return resolveErr;
+    const body = { branch: args.branch || 'main' };
+    if (args.version) body.version = args.version;
+    const result = await apiRequest('POST', `/core/projects/${projectId}/publish`, {
+      token: args.token,
+      api_key: args.api_key,
+      body,
+    });
+    if (result.success)
+      return `Published.\nVersion: ${result.data?.value || result.data?.id || 'unknown'}`;
+    return `Publish failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
+  }
+
+  if (name === 'push') {
+    if (!args.token && !args.api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const { id: projectId, error: resolveErr } = await resolveProjectId(
+      args.project,
+      args.token,
+      args.api_key,
+    );
+    if (resolveErr) return resolveErr;
+    const env = args.environment || 'production';
+    const body = { mode: args.mode || 'published', branch: args.branch || 'main' };
+    if (args.version) body.version = args.version;
+    const result = await apiRequest(
+      'POST',
+      `/core/projects/${projectId}/environments/${env}/publish`,
+      { token: args.token, api_key: args.api_key, body },
+    );
+    if (result.success) {
+      const config = result.data?.config || {};
+      return `Pushed to ${result.data?.key || env}.\nMode: ${config.mode || body.mode}\nVersion: ${config.version || 'latest'}`;
+    }
+    return `Push failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
   }
 
   throw new Error(`Unknown tool: ${name}`);
 }
 
 // ---------------------------------------------------------------------------
-// Resources — skill files exposed as MCP resources
+// Resources
 // ---------------------------------------------------------------------------
 
 const SKILL_RESOURCES = {
@@ -708,6 +1169,9 @@ const SKILL_RESOURCES = {
   'symbols://skills/default-components': 'DEFAULT_COMPONENTS.md',
   'symbols://skills/learnings': 'LEARNINGS.md',
   'symbols://skills/running-apps': 'RUNNING_APPS.md',
+  'symbols://skills/cli': 'CLI.md',
+  'symbols://skills/sdk': 'SDK.md',
+  'symbols://skills/common-mistakes': 'COMMON_MISTAKES.md',
   'symbols://skills/brand-identity': 'BRAND_IDENTITY.md',
   'symbols://skills/design-critique': 'DESIGN_CRITIQUE.md',
   'symbols://skills/design-system-architect': 'DESIGN_SYSTEM_ARCHITECT.md',
@@ -718,21 +1182,14 @@ const SKILL_RESOURCES = {
 };
 
 function listResources() {
-  const resources = [];
-  for (const [uri, filename] of Object.entries(SKILL_RESOURCES)) {
-    if (skills[filename]) {
-      resources.push({ uri, name: filename.replace('.md', ''), mimeType: 'text/markdown' });
-    }
-  }
-  return resources;
+  return Object.entries(SKILL_RESOURCES)
+    .filter(([, f]) => skills[f])
+    .map(([uri, f]) => ({ uri, name: f.replace('.md', ''), mimeType: 'text/markdown' }));
 }
 
 function readResource(uri) {
-  const filename = SKILL_RESOURCES[uri];
-  if (filename && skills[filename]) {
-    return readSkill(filename);
-  }
-  return null;
+  const f = SKILL_RESOURCES[uri];
+  return f && skills[f] ? readSkill(f) : null;
 }
 
 // ---------------------------------------------------------------------------
@@ -742,41 +1199,35 @@ function readResource(uri) {
 const PROMPTS = [
   {
     name: 'symbols_component_prompt',
-    description: 'Prompt template for generating a Symbols.app component.',
+    description: 'Generate a Symbols.app component.',
     arguments: [
-      { name: 'description', description: 'Component description', required: true },
-      { name: 'component_name', description: 'Component name', required: false },
+      { name: 'description', required: true },
+      { name: 'component_name', required: false },
     ],
   },
   {
     name: 'symbols_migration_prompt',
-    description: 'Prompt template for migrating code to Symbols.app.',
-    arguments: [
-      {
-        name: 'source_framework',
-        description: 'Source framework (React, Vue, etc.)',
-        required: false,
-      },
-    ],
+    description: 'Migrate code to Symbols.app.',
+    arguments: [{ name: 'source_framework', required: false }],
   },
   {
     name: 'symbols_project_prompt',
-    description: 'Prompt template for scaffolding a complete Symbols project.',
-    arguments: [{ name: 'description', description: 'Project description', required: true }],
+    description: 'Scaffold a complete Symbols project.',
+    arguments: [{ name: 'description', required: true }],
   },
   {
     name: 'symbols_review_prompt',
-    description: 'Prompt template for reviewing Symbols/DOMQL code.',
+    description: 'Review Symbols/DOMQL code for v3 compliance.',
     arguments: [],
   },
   {
     name: 'symbols_convert_html_prompt',
-    description: 'Prompt template for converting HTML to Symbols.app components.',
+    description: 'Convert HTML to Symbols.app components.',
     arguments: [],
   },
   {
     name: 'symbols_design_review_prompt',
-    description: 'Prompt template for visual/design audit against the design system.',
+    description: 'Visual/design audit against the design system.',
     arguments: [],
   },
 ];
@@ -785,12 +1236,11 @@ const PROMPTS = [
 // MCP JSON-RPC handler
 // ---------------------------------------------------------------------------
 
-const SERVER_INFO = { name: 'Symbols MCP', version: '1.1.1' };
+const SERVER_INFO = { name: 'Symbols MCP', version: '1.0.15' };
 
 export async function handleJsonRpc(req) {
   const { method, params, id } = req;
-
-  if (method === 'initialize') {
+  if (method === 'initialize')
     return {
       jsonrpc: '2.0',
       id,
@@ -800,15 +1250,9 @@ export async function handleJsonRpc(req) {
         serverInfo: SERVER_INFO,
       },
     };
-  }
-
   if (method === 'notifications/initialized') return null;
   if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };
-
-  if (method === 'tools/list') {
-    return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
-  }
-
+  if (method === 'tools/list') return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
   if (method === 'tools/call') {
     const { name, arguments: args = {} } = params || {};
     try {
@@ -822,32 +1266,25 @@ export async function handleJsonRpc(req) {
       };
     }
   }
-
-  if (method === 'resources/list') {
+  if (method === 'resources/list')
     return { jsonrpc: '2.0', id, result: { resources: listResources() } };
-  }
-
   if (method === 'resources/read') {
-    const uri = params?.uri;
-    const content = readResource(uri);
-    if (content === null) {
-      return { jsonrpc: '2.0', id, error: { code: -32602, message: `Resource not found: ${uri}` } };
-    }
+    const content = readResource(params?.uri);
+    if (content === null)
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32602, message: `Resource not found: ${params?.uri}` },
+      };
     return {
       jsonrpc: '2.0',
       id,
-      result: { contents: [{ uri, mimeType: 'text/markdown', text: content }] },
+      result: { contents: [{ uri: params.uri, mimeType: 'text/markdown', text: content }] },
     };
   }
-
-  if (method === 'prompts/list') {
-    return { jsonrpc: '2.0', id, result: { prompts: PROMPTS } };
-  }
-
-  if (id !== undefined) {
+  if (method === 'prompts/list') return { jsonrpc: '2.0', id, result: { prompts: PROMPTS } };
+  if (id !== undefined)
     return { jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } };
-  }
-
   return null;
 }