ALWAYS call this first before any generate_* tool — the mandatory Symbols.app rules.
Call with NO arguments first. That returns the compact CORE bundle (well under
80k chars — it survives every client's tool-output cap):
- the built-in-reuse directive (Atoms/Components catalog — REUSE via bare PascalCase keys),
- RULES essentials: the RULES.md preamble (canonical-syntax table, flat API) + EVERY
STRICT rule in full + an index of all rule headings,
- the FRANKABILITY hard checklist (patterns that survive frank.toJSON),
- a SECTION INDEX (all 16 sections, sizes, parts, how to fetch),
- a NEXT STEP table telling you which sections to pull for your task.
Then fetch sections on demand, one call each:
get_project_rules(section="SYNTAX") → DOMQL v3.14 syntax reference
get_project_rules(section="COMPONENTS") → built-in component catalog
get_project_rules(section="RULES", part=2) → large sections come in parts
get_project_rules(section="FRANKABILITY_CATALOG")
Sections: FRAMEWORK, DESIGN_SYSTEM, RULES, COMPONENTS, DEFAULT_COMPONENTS, SYNTAX,
PATTERNS, SNIPPETS, SHARED_LIBRARIES, WORKSPACE, FRANKABILITY, FRANKABILITY_CATALOG,
FRANK_FIX_WORKFLOW, COMMON_MISTAKES, LEARNINGS, DEFAULT_PROJECT (case-insensitive,
`.md` optional; several small sections may be comma-separated if they fit the cap).
Unknown section names raise a clear error listing the valid names.
full=True returns the legacy one-shot concatenation of all 16 sections (~590k chars).
Use it ONLY on a client with no tool-output cap — Claude Code truncates it to a file
path and the rules never reach the model.
Minimum for any code-writing task: core + SYNTAX + COMPONENTS + FRANKABILITY.
Violations cause silent failures — black page, nothing renders, or a working app
with degraded UX you'll later have to rebuild. The single most-violated rule is
reusing built-in components: a bare `Ava
Parametersfullpartsection
Search the Symbols documentation knowledge base for relevant information.
Ranked by section: every skill file is split at its headings, and the
sections that hold the most of the query — option names (`camelCase`,
`dotted.paths`, `snake_case`) weigh most and must be present, headings
count again, words found in every file weigh little — come back first,
at most two per file. Each result: file, section heading path, line,
score, snippet.
Args:
query: Natural language search query about Symbols/DOMQL. Name the
option exactly (`prepareDesignSystem`, `fetch.early`) for the
best match.
max_results: Maximum number of results to return (1-5).
Parametersqueryrequiredmax_results
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.
Parametersdescriptionrequiredcomponent_name
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).
Parameterspage_namedescriptionrequired
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.
Parameterssource_coderequired
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.
Parameterssource_coderequired
Inline VALIDATOR for a single Symbols/DOMQL file (component, page, function, …).
Runs the @symbo.ls/frank-audit rules (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. It also warns on four STRICT shape rules: one condition
repeated across 3+ CSS props (Rule 19 — use isX + '.isX'), an interactive element
with ':hover' but no ':active' (Rule 65), a state-driven `if:` on an element in
flow beside siblings (Rule 66 — keep it mounted, toggle visibility), a built-in
Button call site overriding padding / height (Rule 68).
Pass `file_path` so the rules that depend on the file's folder apply where the file
really lives: a `functions/` file is not a component (no FA903 "exported as a
function", no FA009 file-name check), `pages/` files get the page rules, a file
outside every frank folder gets FA006. Without it the code is audited as a component,
`components/<FirstExport>.js`. Project-level checks (the folder's `index.js`
re-exports the file, `context.js` exists) need the whole project and are not reported
here — run `bin/symbols-audit <symbols-dir>` for those.
Use this:
- During generation, to verify a freshly-generated file 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) — the same rules
across an entire project. Use during the playbook's static-audit phase.
By default returns ONLY the findings (≈1–2K c
Parametersfile_pathcomponent_coderequiredinclude_playbook
audit_and_fix_frankability
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[].
Parametersmodeaggressivesymbols_dirrequiredmax_iterations
prescribe_frankability_fixes
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.
Parameterssymbols_dirrequired
apply_frankability_edit_ops
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.
Parametersops_jsonrequiredsymbols_dirrequired
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, ... }.
Parameterssymbols_dirrequired
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 }.
Parametersop_idrequiredsymbols_dirrequired
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 }] }.
Parameterssymbols_dirrequired
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: [...] }.
Parameterslimitsymbols_dirrequired
explain_frankability_rule
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 }.
Parametersrule_idrequired
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.
Takes no parameters.
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.
Takes no parameters.
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, file_path)` — inline single-file 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. M
Parametersphase
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.
Parameterssectionsource_coderequired
[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.
Parametersfile_listhas_json_datahas_cdn_importhas_iife_scripthas_symbols_dirhas_package_jsonhas_symbols_jsonhas_mermaid_config
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.
Parameterscwd
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.
Parametersemailrequiredpasswordrequired
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.
Parameterstokenapi_key
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").
Parameterskeynamerequiredtokenapi_keylanguagevisibility
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").
Parameterstokenbranchapi_keyprojectrequired
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:
```json
{
"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").
force_shared_library: Explicitly allow writing to a project flagged
isSharedLibrary when this tree's .symbols_local/lock.json does not
carry that record's id. Without it the server refuses such saves
(403 shared_library_lock_required) — shared libraries feed every
consumer project, so an accidental write is an incident.
Parameterstokenbranchapi_keychangesrequiredmessageprojectrequiredforce_shared_library
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").
Parameterstokenbranchapi_keyprojectrequiredversion
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").
Parametersmodetokenbranchapi_keyprojectrequiredversionenvironment
