ALWAYS call this first before any generate_* tool.

Returns the mandatory Symbols.app rules that MUST be followed:

• FRAMEWORK.md (authoritative — project structure, plugins, theming, SSR, publish)

• DESIGN_SYSTEM.md (authoritative — design-system contract + token catalog)

• RULES.md (62 strict rules — flat API, signal reactivity, design tokens, polyglot, fetch, helmet, theme, reusability, icons)

• COMPONENTS.md (built-in component catalog from @symbo.ls/default-config — REUSE these via bare PascalCase keys; do NOT redefine)

• DEFAULT_COMPONENTS.md (full source/structure of every built-in — what they look like, what props they expose, how to compose them)

• SYNTAX.md (DOMQL v3.14 syntax reference — flat element API, signal reactivity, factory patterns)

• PATTERNS.md (canonical compositional patterns)

• SNIPPETS.md (project-level snippet patterns)

• SHARED_LIBRARIES.md (when to read/never edit cross-package code)

• WORKSPACE.md (multi-app monorepo topology — two project shapes, two-file contract, no-transitive-resolution, onboarding checklist)

• FRANKABILITY.md (every @symbo.ls/frank-audit rule with wrong vs canonical examples — patterns that survive frank.toJSON serialization, so generated code is provably frankable from the start)

• FRANK_FIX_WORKFLOW.md (LLM reference card for the prescription → edit-op flow — the strict 8-kind contract for apply_frankability_edit_ops)

• COMMON_MISTAKES.md + LEARNINGS.md (hard-won failure cases — read these to avoid replaying them)

• DEFAULT_PROJECT.md (recommended baseline design-system values + the default-library catalog)

Violations cause silent failures — black page, nothing renders, or a working app with degraded UX you'll later have to rebuild.

Call this before: generate_component, generate_page, convert_react, convert_html, or any code generation task.

READ ALL SECTIONS — do NOT skim past COMPONENTS.md / DEFAULT_COMPONENTS.md / PATTERNS.md. The single most-violated rule is reusing built-in components. Skipping the catalog leads to redefining Avatar, Button, Dialog, etc. from scratch when a bare Avatar: {} would have rendered the canonical built-in.

Search the Symbols documentation knowledge base for relevant information.

Args: query: Natural language search query about Symbols/DOMQL. max_results: Maximum number of results to return (1-5).

Generate a Symbols.app DOMQL component from a description.

Returns the rules, syntax reference, component catalog, cookbook examples, and default library reference as context. The calling LLM uses this context to generate a correct, compliant component.

Args: description: What the component should do and look like. component_name: PascalCase name for the component.

Generate a Symbols.app DOMQL page with routing + helmet metadata + fetch integration.

Returns rules, project structure, patterns, snippets, and default library reference as context for page generation.

Args: description: What the page should contain and do. page_name: camelCase name for the page (used in route map).

Convert React/JSX code to Symbols.app DOMQL.

Provide React component code and receive the conversion context including migration rules, syntax reference, and examples.

Args: source_code: The React/JSX source code to convert.

Convert raw HTML/CSS to Symbols.app DOMQL components.

Provide HTML code and receive the conversion context including component catalog, syntax reference, and design system tokens.

Args: source_code: The HTML/CSS source code to convert.

Inline VALIDATOR for a single Symbols/DOMQL component string.

Runs the deterministic ruleset (flat element API, signal reactivity, design system tokens, declarative fetch/polyglot/helmet/router, no DOM manipulation, Rule 62 icon ban) against an in-memory string of code. Returns a tight report with violations + warnings.

Use this:

• During generation, to verify a freshly-generated component before saving

• In any client without shell access (claude.ai web, hosted MCP) where the CLI is unreachable

• On a single file's contents, not a whole project

Adjacent tools — call these for different scopes:

• audit_project() — returns the MULTI-PHASE PROJECT AUDIT PLAYBOOK (instructions for the agent to follow). Use when the user asks for a full project audit.

• bin/symbols-audit <symbols-dir> (CLI, ships with this package) — filesystem regex sweep across an entire project. Use during the playbook's static-audit phase.

By default returns ONLY the findings (≈1–2K chars). Pass include_playbook=True to also dump the AUDIT.md playbook in the same response when you don't already have it.

Args: component_code: The JavaScript/DOMQL source string to validate. include_playbook: Append the full audit playbook to the response. Default False to keep responses small. Default agents should NOT set this — call audit_project() separately if the playbook is needed.

Run frank-audit and optionally apply fixes — supports a sampling-driven LLM loop that resolves findings the mechanical fixer can't safely handle.

Modes: 'report' — run audit, list findings, do not modify files 'safe-fix' — apply mechanical fixes with verify-or-rollback safety (every applied fix is verified against frank.toJSON; regressions roll back) 'full' — run safe-fix first, THEN drive an LLM loop via MCP sampling over the remaining prescriptions: 1. prescribe_frankability_fixes(dir) → JSON prescriptions 2. for each prescription (capped by max_iterations): a. ctx.session.create_message() with the strict edit-op contract prompt b. parse the LLM's JSON response c. apply_frankability_edit_ops with verify-or-rollback d. one retry on malformed JSON 3. report aggregate (mechanical + LLM fixes) Requires the host to support MCP sampling (Claude Code does; some hosts don't — falls back gracefully to safe-fix mode with a warning when ctx.session is unavailable).

Args: symbols_dir: Absolute path to the symbols/ directory. mode: 'report' | 'safe-fix' | 'full' aggressive: With safe-fix or full, also apply medium-confidence fixes. max_iterations: Cap on LLM-driven prescriptions in 'full' mode (default 20).

Returns: JSON-stringified result with schema, opId, findings, applied/skipped, rolledBack, baseline, finalState, and (in 'full' mode) llmRounds[].

Generate LLM-ready prescriptions for frank-audit findings that can't be auto-fixed.

Each prescription contains:

• finding (rule, file, line, refusal reason)

• sourceContext (~30 lines around the finding)

• relatedFiles (other places that mention the same symbol)

• proposedOps — array of edit ops the rule's helper logic produced (e.g. FA304 already mapped 36px → 'C2' from the project's spacing scale; FA301 already matched the closest palette token). The agent can submit these verbatim to apply_frankability_edit_ops, or modify before submitting.

• explanation (the rule's docs)

• safetyCheck (verify command run after apply)

Workflow for the agent:

1. Call this tool to get prescriptions.

2. Inspect each proposedOps array. Either submit verbatim or modify. For findings with no proposedOps (structural refactors like FA2xx multifile-helpers, FA5xx DOM bans), construct your own ops from the 12 strict op kinds: removeImport | moveFile | addToIndexFile | addToGlobalScope | removeTopLevelDecl | addElementScope | replaceTokenValue | renameObjectKey | removeObjectKey | setObjectProperty | addDesignToken | skip

3. Call apply_frankability_edit_ops(symbols_dir, ops) — frank-audit validates every op, snapshots, applies, runs verify, rolls back on regression. Failed ops return structured details (E_OLDVALUE_NOT_FOUND with actualLine, E_KEY_NOT_FOUND with availableKeys, etc.) so you can retry intelligently.

4. Repeat until prescriptions are exhausted or no progress.

Args: symbols_dir: Absolute path to the symbols/ directory.

Returns: JSON with schema version, opId, list of prescriptions.

Apply LLM-generated edit ops to a Symbols project with verify-or-rollback.

Pass ops_json as a JSON string of either:

• { "ops": [...] }

• or just an array of op objects.

Each op must be one of the 8 strict kinds (see prescribe_frankability_fixes). The applier validates every op, snapshots affected files, applies, runs frank.toJSON to verify, and rolls back if the result regresses against the pre-apply state.

Args: symbols_dir: Absolute path to the symbols/ directory. ops_json: JSON string containing the edit ops.

Returns: JSON with applied/skipped/rolledBack/baseline/finalState.

Verify a Symbols project bundles cleanly via frank.toJSON.

Independent of audit/fix — runs the same round-trip that apply-edits uses after every mutation, but as a standalone check. Useful for the agent to confirm a project is in a known-good state before starting a fix loop, or after a series of manual edits.

Returns: JSON with { ok, bundleable, scanIssues, ... }.

Restore a Symbols project to its state before a specific op ran.

Every apply-edits run snapshots affected files under <symbols_dir>/.frank-audit/snapshots/<opId>/ before mutating. Use this to undo a specific op (or a chain by walking backwards through opIds listed by snapshots_frankability).

Args: symbols_dir: Absolute path to the symbols/ directory. op_id: The opId to roll back to (from a prior apply-edits result).

Returns: JSON with { ok, restored: [...filePaths], opId }.

List recent snapshotted opIds for a Symbols project.

Each entry corresponds to a frank-audit op that wrote files. Pass an opId to rollback_frankability to restore that op's pre-state.

Returns: JSON with { ok, opIds: [{ opId, timestamp, files }] }.

Tail the audit log for a Symbols project.

Returns the most recent NDJSON entries from <symbols_dir>/.frank-audit/log. Each entry records audit/fix/apply-edits/rollback events with opId, timestamp, and outcome — useful for understanding history without re-running ops.

Args: symbols_dir: Absolute path to the symbols/ directory. limit: Maximum number of entries to return (default 50).

Returns: JSON with { ok, entries: [...] }.

Return the documentation block for a specific frank-audit rule.

Each rule (FA001 through FA902) has an explain() method that returns a human-readable description, examples of the bad/good patterns, and the rationale. Use this when an agent encounters an unfamiliar finding and needs context before deciding on a fix.

Args: rule_id: The rule ID (e.g. 'FA301', 'FA806').

Returns: JSON with { ok, ruleId, name, severity, description, explanation }.

Returns the complete smbls CLI reference (@symbo.ls/cli).

Mirrors smbls/CLI_FOR_MCP.md. Covers: configuration files (symbols.json, .symbols_local/), API URL resolution order + env-var overrides, common flag conventions, full command map (project lifecycle, auth, sync, project mgmt, workspace ops, files & assets, integrations, GitHub, Frank JSON↔FS, dev/build/deploy, code transformation, SDK proxy, ask), publish flow (one-shot + granular), MCP/agent usage rules (--non-interactive + --yes

• NODE_ENV + SYMBOLS_AUTH_TOKEN), error-handling contracts (AUTH_REQUIRED, ECONNREFUSED, missing app key), source-file map, and CLI-specific anti-patterns.

Returns the complete @symbo.ls/sdk API reference (3.14.0).

Mirrors sdk/SDK_FOR_MCP.md. Covers all 24 services with full method lists: auth, collab, project, plan, subscription, file, payment, dns, branch, pullRequest, admin, screenshot, tracking, waitlist, metrics, integration, featureFlag, organization, workspace, workspaceData (typed wrapper for /workspace/*), kv, allocationRule, sharedAsset, credits. Plus: SDK class lifecycle, BaseService contract, TokenManager (singleton, auto-refresh), environment matrix (channel URLs), root event bus (sdk.rootBus with last-payload replay), validation surface, federation primitive (multi-Supabase registry), permissions reference (ROLE_PERMISSIONS, PROJECT_ROLE_PERMISSIONS, TIER_FEATURES), error handling contract, and MCP integration notes.

Returns the multi-phase PROJECT AUDIT PLAYBOOK (instructions for the agent).

Strict mode is the default. Strict means EXHAUSTIVE — the agent does not stop until every finding is resolved, framework_bug (in framework_audit_results.md), or an active 🟢 ASK USER block awaiting user input. No finding stays open.

Two CLI flags (default ON in strict mode, both opt-out via --no-...):

• --deep-fix: agent does NOT stop at first blocker (missing project key, auth-protected route, missing CLI subcommand). Surfaces ASK-USER blocks or runs documented fallbacks (e.g. publish blocked → local frank+brender preview).

• --deep-framework-audit: every framework_bug entry includes a Read+Grep trace into smbls/ source identifying the suspected function, plus a suggested patch.

Two report files the CLI emits + the agent appends to:

• audit/symbols_audit_results.md — PROJECT findings + resolutions

• audit/framework_audit_results.md — FRAMEWORK bugs + repro + smbls/ trace + suggested patch (each entry must be debuggable by someone who's never seen the code; vague "doesn't work" entries are not acceptable in strict mode)

Findings have an origin field (project | framework | shared) classified by bin/symbols-audit heuristically, then refined by the agent during Phase 2.

This tool is a playbook getter, not an executor. The agent runs the playbook itself using:

• get_project_context — call FIRST to resolve owner/key/env. Missing values surface as 🟢 ASK USER blocks (NEVER hardcoded).

• bin/symbols-audit <symbols-dir> — deterministic regex sweep + dual-report template emission. Strict + deep modes default ON.

• audit_component(code) — inline single-component validator (no filesystem).

• chrome-mcp tools — for the Phase 3c local-vs-remote UI testing protocol.

Phase summary:

• Phase 0: setup + baseline metrics + project-context resolution. Missing owner/key resolved here via ASK-USER (not deferred).

• Phase 1: static audit via bin/symbols-audit (creates findings.json + symbols_audit_results.md + framework_audit_results.md templates).

• Phase 2: fix loop with self-test. 3 failed fix attempts → finding becomes framework_bug with deep-audit trace. Continue, never stop on first bug.

• Phase 3a: build gates with fallbacks for missing CLI subcommands.

• Phase 3b: publish to staging WITH FALLBACK LADDER. If publish is blocked (missing key, AUTH_REQUIRED, env doesn't exist), agent surfaces ASK-USER AND/OR falls back to local frank to-json + brender + http.server preview so Phase 3c still has a viewable artifact. NEVER silently skip publish.

• Phase 3c: STRICT UI testing — local-vs-(remote OR localfallback) side-by-side, click every clickable, icon rendering verification per Rule 62, theme/lang/ active-nav/forms/responsive.

• Phase 4: iterate until two consecutive runs converge — zero open findings, zero pending ASK-USER, viewable artifact exists. Deep-fix loop re-visits framework_bug entries to strengthen them and retries blockers.

• Phase 5: report = record of resolutions, NOT a TODO list. Strict mode forbids "Recommended follow-up tasks" as a terminal state.

Transport awareness: this playbook assumes stdio MCP transport (filesystem access). For SSE/HTTPS/CDN, the agent surfaces filesystem-dependent steps as shell commands the user runs locally, then resumes Phase 2/3 with pasted output. audit_component and audit_project are stateless and work over any transport; get_project_context and bin/symbols-audit are stdio-only.

Output artifacts created in /audit/: findings.json, symbols_audit_results.md (framework bugs), runs/, report.md.

Use this when the user asks to audit, validate, refactor for compliance, or 'make my project publish-ready in one shot'. Returns the entire playbook so the agent has the full context. Pair with the bundled bin/symbols-audit CLI for the deterministic regex pass.

Args: phase: 'all' (full playbook — default) | '0' | '1' | '2' | '3' | '4' | '5' (just one phase's section)

Convert DOMQL JavaScript source code to platform JSON format.

Parses export statements from generated component/page code and converts them into the structured JSON the Symbols platform expects. Functions are automatically stringified (as the platform stores them as strings).

Use this after generate_component or generate_page to get JSON that can be passed directly to save_to_project.

Mirrors the @symbo.ls/frank toJSON + stringifyFunctions pipeline that the CLI uses when running smbls push.

Args: source_code: JavaScript source code with export const/default statements. section: Target section — "components", "pages", "functions", "snippets", "designSystem", "state". Determines how exports are categorized.

[Legacy] Detect Symbols environment from caller-supplied file flags.

Prefer get_project_context — it does the same classification by inspecting the filesystem directly (no caller-supplied flags needed) AND returns project owner/key/auth state in the same call.

Kept for backward compatibility with older agent prompts. New code should call get_project_context(cwd) instead — its response includes env_type, env_evidence, and env_guidance fields equivalent to this tool's output, plus owner, key, token_present, and next_step guidance.

Args: has_symbols_json: Whether symbols.json exists in the project root. has_symbols_dir: Whether a symbols/ directory exists with components/, pages/, etc. has_package_json: Whether package.json exists with smbls dependency. has_cdn_import: Whether HTML files contain CDN imports (esm.sh/smbls, etc.). has_iife_script: Whether HTML files use script src smbls (IIFE global). has_json_data: Whether the project uses frank-generated JSON data files. has_mermaid_config: Whether mermaid/wrangler config or GATEWAY_URL/JSON_PATH env vars are present. file_list: Comma-separated list of key files in the project root.

Read the current Symbols project context — START HERE for any Symbols task.

Walks up from cwd (or the MCP process's working directory) looking for symbols.json, parses it, classifies the environment from filesystem signals, and returns a single JSON payload with everything an agent needs to begin work.

Returns:

• owner, key, dir, bundler, sharedLibraries, brender — from symbols.json

• project_root — absolute path of the project root

• symbols_dir — absolute path of the symbols/ source dir (or null)

• env_type — local | cdn | json_runtime | remote_server | unknown

• env_evidence — the filesystem signals that produced the classification

• env_guidance — one-line guidance for that env type

• token_present — whether SYMBOLS_TOKEN env var or ~/.smblsrc token exists

• api_base — the Symbols API base URL (defaults to https://api.symbols.app)

• next_step — what the agent should do next (ask user / log in / proceed)

ALWAYS call this first for any Symbols-project task. It replaces the older detect_environment tool (which required the caller to pre-compute file flags).

Use this BEFORE calling any auth-required tool (save_to_project, publish, push, get_project) — combine with token_present to know whether to prompt for login.

Never hardcode owner/key/credentials. If next_step says "ask the user", ASK.

Args: cwd: Directory to start searching from. Defaults to the MCP server's process cwd. Pass an absolute path when the agent's cwd differs from the project root.

Log in to the Symbols platform and get an access token.

Use this when the user needs to authenticate before any project operation. Returns a JWT token that can be used with all project tools.

Args: email: Symbols account email address. password: Symbols account password.

List the user's Symbols projects.

Returns project names, keys, and IDs so the user can choose which project to save to or publish. Requires authentication.

Args: token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings.

Create a new Symbols project on the platform.

Use this when the user wants to save generated components to a new project. Returns the project ID and key for use with save_to_project and publish.

Args: name: Project display name. key: Project key (pr_xxxx format). Auto-generated from name if empty. token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings. visibility: Project visibility — "private", "public", or "password-protected". language: Project language (default: "javascript").

Get a Symbols project's current data (components, pages, designSystem, state).

Use this to inspect what's already in a project before saving changes.

Args: project: Project key (pr_xxxx) or project ID. token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings. branch: Branch to read from (default: "main").

Save components, pages, or design system data to a Symbols project.

This applies changes to the project and creates a new version. Use after generate_component/generate_page to persist the output.

The changes parameter is a JSON string with the data to merge into the project. Structure mirrors the project data format:

{
  "components": {
    "Header": {
      "extends": "Flex",
      "props": { "flow": "x", "gap": "B", "padding": "A B" },
      "Logo": { "extends": "Icon", "props": { "name": "logo" } },
      "Nav": { "extends": "Flex", "gap": "A" }
    }
  },
  "pages": {
    "home": {
      "extends": "Page",
      "Header": {},
      "Hero": { "extends": "Flex" }
    }
  },
  "designSystem": { ... },
  "state": { ... },
  "functions": { ... }
}

Only include the sections you want to update — omitted sections are left unchanged.

Args: project: Project key (pr_xxxx) or project ID. changes: JSON string with project data to save (components, pages, designSystem, state, functions). token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings. message: Version commit message describing the changes. branch: Branch to save to (default: "main").

Publish a version of a Symbols project to the platform.

Makes the specified version (or latest) the published/live version. Call save_to_project first to save your changes, then publish to make them live.

Requires authentication — provide either token or api_key.

Args: project: Project ID (MongoDB ObjectId) or project key (pr_xxxx). token: JWT access token from login or ~/.smblsrc. api_key: API key (sk_live_...) from project integration settings. Alternative to token. version: Version string or version ID to publish. Leave empty for latest. branch: Branch to publish from (default: "main").

Push/deploy a Symbols project to a specific environment.

Deploys the project to a target environment (production, staging, dev). Call publish first to set the live version, then push to deploy.

Requires authentication — provide either token or api_key.

Args: project: Project ID (MongoDB ObjectId) or project key (pr_xxxx). token: JWT access token from login or ~/.smblsrc. api_key: API key (sk_live_...) from project integration settings. Alternative to token. environment: Target environment key (e.g. "production", "staging", "dev"). mode: Deploy mode — "latest" (newest from branch), "published" (current published version), "version" (specific version), or "branch" (track a branch). version: Required when mode is "version" — the version string or ID to deploy. branch: Branch to deploy from when mode is "latest" or "branch" (default: "main").