@symbo.ls/mcp 1.0.10 → 1.0.11

package/symbols_mcp/skills/OPTIMIZATIONS_FOR_AGENT.md

@@ -1,253 +0,0 @@
-# Optimize Your Symbols Site for AI Agents
-
-## A Practical Guide to Accessibility, ARIA, and Emerging Standards
-
-### AI Skill Instruction for Coding Assistants
-
-This document is the definitive guide for generating Symbols (DOMQL v3) code fully interpretable by AI agents, accessibility tools, and automated systems. All output must comply with the following rules and standards.
-
----
-
-# 1. Semantic-First Architecture
-
-Always generate semantic components instead of generic containers. Use these mappings:
-
-| Intent                               | Required Component    |
-| ------------------------------------ | --------------------- |
-| Page header                          | Header                |
-| Navigation                           | Nav                   |
-| Primary content                      | Main                  |
-| Standalone entity (product, article) | Article               |
-| Thematic grouping                    | Section               |
-| Sidebar                              | Aside                 |
-| Footer                               | Footer                |
-| H1–H6                                | Headings              |
-| P                                    | Paragraphs            |
-| Button                               | Actions               |
-| Link                                 | Navigation            |
-| Form                                 | Transactional surface |
-| Input / Select                       | User input            |
-
-Do not simulate meaning with generic divs or spans.
-
----
-
-# 2. DOMQL v3 Compliance
-
-- Use DOMQL v3 syntax exclusively.
-- Set HTML attributes via `attr`.
-- Prefix event handlers with `on`.
-- Ensure all critical content is server-rendered and visible in the initial HTML.
-
----
-
-# 3. Heading Discipline
-
-- One H1 per page defining primary subject.
-- Logical hierarchy: H1 → H2 → H3, etc.
-- Nested headings should not skip levels.
-
-Heading hierarchy is used by AI agents to determine page structure.
-
----
-
-# 4. Interactive Elements
-
-- Use native elements: Button, Link, Form, Input, Select.
-- If non-native interactive elements are unavoidable, declare:
-
-```javascript
-attr: {
-  role: 'button',
-  tabindex: '0'
-}
-```
-
-- Do not rely on visual styling to indicate interactivity.
-
----
-
-# 5. Accessibility as Machine Interface
-
-ARIA attributes define machine-readable state:
-
-- `aria-busy`: reflects loading.
-- `aria-label`: accessible name when visible text is insufficient.
-- `aria-live`: indicates dynamic content.
-- `autocomplete`: guides expected input format.
-
-ARIA values must match actual runtime state.
-
----
-
-# 6. AI-Specific Markup (aid-\*)
-
-Include aid-\* attributes to optimize machine parsing:
-
-- `aid-type`: structural role (header, nav, main, content, complementary, interactive, modal, alert, search)
-- `aid-desc`: concise machine-readable description
-- `aid-state`: idle, loading, processing, done, error
-- `aid-cnt-type`: product, service, info
-
-State must accurately reflect dynamic changes.
-
----
-
-# 7. Structured Data (JSON-LD)
-
-Include JSON-LD for entity representation:
-
-- Organization
-- Product / Service
-- Article
-- FAQPage
-- BreadcrumbList
-
-Structured data must match server-rendered content exactly.
-
-```javascript
-export const StructuredData = {
-  tag: "script",
-  attr: { type: "application/ld+json" },
-  html: (el, s) =>
-    JSON.stringify({
-      "@context": "https://schema.org",
-      "@type": "Product",
-      name: s.name,
-      description: s.description,
-      offers: {
-        "@type": "Offer",
-        price: s.price,
-        priceCurrency: s.currency,
-      },
-    }),
-};
-```
-
----
-
-# 8. Form Construction Protocol
-
-- Associate labels using `for` + `id` or nest input inside label.
-- Define `name` and `type` attributes.
-- Use `autocomplete` when relevant.
-- Reflect submission state via `aria-busy` or `aid-state`.
-
-Forms must be machine-submittable without heuristic inference.
-
----
-
-# 9. Explicit Identifiers
-
-Use deterministic IDs and class names for reliable referencing:
-
-```javascript
-attr: {
-  id: `entity-${s.id}`,
-  class: 'entity-card'
-}
-```
-
----
-
-# 10. llms.txt Support
-
-Provide `/llms.txt` for AI guidance:
-
-```text
-# Organization Name
-# Purpose: Platform description
-
-## Key pages
-- /products
-- /api/docs
-- /support
-
-## Preferred interactions
-- /api/v2/ programmatic access
-- /search?q= for search
-
-## Data accuracy
-- Prices, shipping, inventory levels
-```
-
-AI agents must use llms.txt for programmatic routing and content interpretation.
-
----
-
-# 11. Testing Instructions
-
-### Manual Testing
-
-- Ask AI agents to describe page content, locate products, report prices, and identify support channels.
-
-### Automated Testing
-
-```javascript
-export const testAgentComprehension = async function (url, prompt) {
-  const response = await fetch("https://api.agent-simulator.com/ask", {
-    method: "POST",
-    body: JSON.stringify({ url, prompt }),
-  });
-  return response.json();
-};
-```
-
----
-
-# 12. Chrome WebMCP / Tool Exposure
-
-Use descriptive attributes for AI-accessible tools:
-
-```javascript
-export const CheckOrderTool = {
-  extends: "Form",
-  attr: {
-    "data-mcp-tool": "checkOrderStatus",
-    "data-mcp-description": "Check the status of an order by ID",
-  },
-  Input: { attr: { type: "text", name: "orderId", placeholder: "Order ID" } },
-  Button: { type: "submit", text: "Check" },
-};
-```
-
----
-
-# 13. Infrastructure Awareness
-
-- Expect bursty agent traffic.
-- Horizontal scaling preferred.
-- Sub-200ms response targets.
-- Intelligent rate limiting for abusive requests.
-
----
-
-# 14. Failure Pattern Recognition
-
-- Excessive divs without semantics
-- Non-descriptive links
-- Missing headings
-- Critical content rendered client-side only
-- Conflicting metadata
-
----
-
-# 15. Output Verification Checklist
-
-Ensure all generated code meets these requirements:
-
-- Semantic components only
-- One H1 per page
-- Buttons for actions, Links for navigation
-- Labeled and named forms
-- Dynamic regions declare state
-- JSON-LD matches content
-- Server-rendered critical content
-
-Any violation requires regeneration.
-
----
-
-# Operational Principle
-
-Generate Symbols code assuming AI agents parse and act on it before human consumption. Structure, semantics, and state define AI comprehension, safety, and interoperability. Accessibility and aid-\* attributes are part of the machine contract.

package/symbols_mcp/skills/PROJECT_SETUP.md

@@ -1,217 +0,0 @@
-# Project Setup — LLM Instructions
-
-These are step-by-step instructions for LLMs to follow when helping a user create, configure, and manage a Symbols project using the CLI.
-
----
-
-## Step 1: Check CLI Installation
-
-Before anything else, verify the CLI is installed:
-
-```bash
-smbls --help
-```
-
-If the command is not found, install it globally:
-
-```bash
-npm i -g @symbo.ls/cli
-```
-
----
-
-## Step 2: Check Authentication
-
-Run the following to check if the user is signed in:
-
-```bash
-smbls login --check
-```
-
-If the user is **not signed in**, prompt them:
-
-> You're not signed in to Symbols. Would you like to sign in now? Signing in unlocks collaboration, platform syncing, remote preview, and project management.
-
-If they agree, run:
-
-```bash
-smbls login
-```
-
-If they have multiple environments/servers configured, they can list or switch:
-
-```bash
-smbls servers
-smbls servers --select
-```
-
----
-
-## Step 3: Create a New Project
-
-Ask the user for a project name. Then decide between local-only or platform-linked creation.
-
-### Option A: Local-only project (fastest)
-
-```bash
-smbls create <project-name>
-cd <project-name>
-npm start
-```
-
-This scaffolds a DOMQL starter project with dependencies installed.
-
-### Option B: Platform-linked project (unlocks collaboration + remote preview)
-
-Requires authentication (Step 2). Creates both a local project and a linked platform project:
-
-```bash
-smbls project create <project-name> --create-new
-cd <project-name>
-npm start
-```
-
-This writes:
-- `symbols.json` — project key and config
-- `.symbols/config.json` — platform link (`projectKey`, `projectId`, `apiBaseUrl`, `branch`)
-
-### CLI Options
-
-**Package manager:**
-
-```bash
-smbls project create <project-name> --package-manager npm
-smbls project create <project-name> --package-manager yarn
-```
-
-**Skip dependency install:**
-
-```bash
-smbls project create <project-name> --no-dependencies
-cd <project-name>
-npm i
-```
-
----
-
-## Step 4: Link an Existing Platform Project (optional)
-
-If the user already has a platform project and wants to link it to a local folder:
-
-```bash
-# Interactive picker
-smbls project link .
-
-# Non-interactive
-smbls project link . --key <project-key>.symbo.ls
-smbls project link . --id <projectId>
-```
-
----
-
-## Step 5: Inform About Sync & Collaboration
-
-After the project is created, explain the core sync commands:
-
-> Your project supports syncing with the Symbols platform. Here's what's available:
->
-> - **`smbls push`** — Upload local changes to the platform
-> - **`smbls fetch --update`** — Download the latest platform snapshot into local files
-> - **`smbls sync`** — Two-way sync with interactive conflict handling
-> - **`smbls collab`** — Watch mode for live collaboration (run in a separate terminal)
-
-### File asset management:
-
-```bash
-smbls files list       # List project files
-smbls files upload     # Upload files
-smbls files download   # Download files
-smbls files rm         # Remove files
-```
-
----
-
-## Step 6: Ask About Pushing First Changes
-
-After making initial edits or scaffolding, ask the user:
-
-> Would you like to push your initial changes to the Symbols platform now?
-
-If **yes**, run:
-
-```bash
-smbls push
-```
-
-Then ask:
-
-> Would you like me to automatically push changes to the platform after each edit I make?
-
-If they agree, run `smbls push` after every file edit session. If they decline, only push when explicitly asked.
-
----
-
-## Step 7: Show Remote Preview Links
-
-After a successful push (or if the project is already linked to the platform), provide the user with their project links using the following patterns:
-
-### Canvas / Editor Link
-
-```
-https://<app>.<user>.preview.symbo.ls/
-```
-
-### With environment (dev, stage, etc.)
-
-```
-https://<env>.<app>.<user>.preview.symbo.ls/
-```
-
-### With subpath
-
-```
-https://<app>.<user>.preview.symbo.ls/<subpath>
-```
-
-Where:
-- `<user>` — the namespace owner identifier (their Symbols username or org)
-- `<app>` — the application/project identifier
-- `<env>` — optional deployment environment (`dev`, `stage`, etc.)
-- `<subpath>` — optional path forwarded to the app
-
-**Example:** For user `nikoloza` with project `my-app`:
-
-```
-Preview:  https://my-app.nikoloza.preview.symbo.ls/
-Dev env:  https://dev.my-app.nikoloza.preview.symbo.ls/
-```
-
-Tell the user:
-
-> Your project is live! Here are your links:
-> - **Preview:** https://<app>.<user>.preview.symbo.ls/
-> - **Canvas:** Available on the Symbols platform at your project page
->
-> These update automatically when you push changes.
-
----
-
-## Troubleshooting
-
-- **Auth required / access denied** — run `smbls login` again
-- **Missing project key** — ensure `symbols.json` has a `key` or link via `smbls project link .`
-- **More detail needed** — add `--verbose` to commands that support it
-- **Shell auto-completion** — run `smbls completion zsh --install` or `smbls completion bash --install`
-
----
-
-## Summary of LLM Behavior
-
-1. Ensure CLI is installed
-2. Check sign-in status; prompt login if needed
-3. Create the project (local-only or platform-linked based on user preference)
-4. Start the dev server with `npm start`
-5. Explain push, fetch, sync, and collab capabilities
-6. Ask if the user wants to push initial changes
-7. Ask if the user wants auto-push after each edit
-8. Display preview and canvas links using the host pattern

package/symbols_mcp/skills/QUICKSTART.md

@@ -1,79 +0,0 @@
-# Symbols CLI Setup & Usage Guide
-
-## Getting Started
-
-You can start using Symbols in your local environment using the CLI tool.
-
-### Installation
-
-```bash
-npm i @symbo.ls/cli -g
-```
-
-### Create a New Project
-
-```bash
-smbls create projectName
-```
-
-This will scaffold the project and setup npm dependencies.
-
-## AI Integration
-
-To prompt AI, you can point to the documentation in the first line:
-
-```
-Use instructions from all .md files from /docs folder
-```
-
-### What It Works Well With
-
-- **Extend existing symbols apps** (best)
-- **Migrating existing projects**
-- **Scaffold something new**
-
-It also works with screenshots and Figma MCP that you can try out with uploads or connects. This will give you an initial config that should be good at a basic level. Once @Ha Le provides the update, we can test it on a more professional/fine-tuned stack.
-
-## Recommended AI Coding Tools
-
-- **Claude Code** - best
-- **Cursor and Antigravity** - very good
-- **Copilot / Codex** - good but not sure
-
-## Platform Upload
-
-If you need to upload your project to the platform, part of the process is outlined in the documentation. @Thomas Zhang has additional features that are not yet documented, but you can navigate with:
-
-```bash
-smbls --help
-```
-
-## Advanced CLI Commands
-
-### Project Management
-
-```bash
-smbls project <sub-commands>
-```
-
-Future additions planned:
-
-- `smbls project <member management>`
-- `smbls project <libs management>`
-- `smbls organization <sub-commands>`
-
-### Shell Auto-Completion
-
-Setup auto-completion for your shell:
-
-```bash
-# For Zsh
-smbls completion zsh --install
-
-# For Bash
-smbls completion bash --install
-```
-
----
-
-_Documentation compiled from community discussions. For the latest updates, refer to the official Symbols documentation or use `smbls --help`._

package/symbols_mcp/skills/REMOTE_PREVIEW.md

@@ -1,144 +0,0 @@
-# Redirect Pattern --- Quick Documentation
-
-## Purpose
-
-Edge redirect rule mapping path-based preview routes into host-based
-preview domains.
-
-Transforms:
-
-    /:user/:app/(optional subpath)?env=ENV
-
-into:
-
-    https://{env.}app.user.preview.symbo.ls/(optional subpath)
-
----
-
-## Route Contract
-
-### Input Path Structure
-
-    /:user/:app/:subpath*
-
-Segment Required Description
-
----
-
-`user` yes Namespace owner identifier
-`app` yes Application identifier
-`subpath` no Forwarded unchanged
-
-Requests with fewer than two segments are passed through without
-modification.
-
----
-
-### Query Parameters
-
-Param Behavior
-
----
-
-`env` Optional deployment environment selector
-others Forwarded unchanged
-
-`env` is removed from query before redirect.
-
----
-
-## Host Resolution
-
-### Without Environment
-
-    {app}.{user}.preview.symbo.ls
-
-### With Environment
-
-    {env}.{app}.{user}.preview.symbo.ls
-
----
-
-## Redirect Construction
-
-Final URL:
-
-    https://TARGET_HOST/
-    + subpath
-    + remaining query string
-
-Status code:
-
-    302 Temporary Redirect
-
----
-
-## Processing Flow
-
-1.  Parse URL.
-2.  Split pathname segments.
-3.  Validate segment count ≥ 2.
-4.  Extract:
-    - user
-    - app
-    - subpath
-5.  Read `env`.
-6.  Remove `env` from query.
-7.  Construct target host.
-8.  Assemble redirect URL.
-9.  Issue redirect response.
-
----
-
-## Examples
-
-### Basic
-
-    Input:
-    https://domain/x/alfa
-
-    Output:
-    https://alfa.x.preview.symbo.ls/
-
-### With Subpath
-
-    Input:
-    https://domain/x/alfa/api/v1
-
-    Output:
-    https://alfa.x.preview.symbo.ls/api/v1
-
-### With Environment
-
-    Input:
-    https://domain/x/alfa/editor?env=dev
-
-    Output:
-    https://dev.alfa.x.preview.symbo.ls/editor
-
-### With Additional Query
-
-    Input:
-    https://domain/x/alfa/view?id=4&env=stage
-
-    Output:
-    https://stage.alfa.x.preview.symbo.ls/view?id=4
-
----
-
-## Edge Considerations
-
-- No validation of segment encoding
-- No sanitization of host fragments
-- Relies on client redirect follow
-- Temporary status avoids cache locking
-- Does not normalize trailing slash
-- Does not preserve fragments (`#hash`)
-- Assumes HTTPS termination upstream
-
----
-
-## Intended Use
-
-Preview routing layer for multi-tenant namespace virtualization
-resolving path entrypoints into isolated host environments.