@symbo.ls/mcp 1.0.0 → 1.0.5

package/symbols_mcp/skills/PROJECT_SETUP.md

@@ -0,0 +1,217 @@
+# 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/REMOTE_PREVIEW.md

@@ -0,0 +1,144 @@
+# 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.

package/symbols_mcp/skills/SEO-METADATA.md

@@ -0,0 +1,110 @@
+# SEO Metadata
+
+DOMQL provides comprehensive SEO metadata support through a declarative `metadata` object. All SEO, social, structured data, and platform-specific properties are configured in a single, unified, type-safe structure.
+
+The system automatically:
+
+- Generates correct `<title>`, `<meta>`, and `<link>` elements
+- Expands array values into multiple tags
+- Handles namespace prefixes (`og:`, `twitter:`, `article:`, `product:`, `DC:`, `itemprop:`, `http-equiv:`)
+- Outputs valid HTML head markup
+
+---
+
+# Complete Unified Example
+
+```js
+export default {
+  metadata: {
+    // Basic metadata
+    title: "My Awesome Website",
+    description: "This is an awesome website with great content",
+    keywords: "awesome, website, content",
+    author: "John Doe",
+    robots: "index, follow",
+    canonical: "https://example.com/page",
+
+    // Open Graph
+    "og:title": "My Awesome Website",
+    "og:description": "This is an awesome website with great content",
+    "og:type": "website",
+    "og:url": "https://example.com",
+    "og:image": [
+      "https://example.com/image1.jpg",
+      "https://example.com/image2.jpg",
+    ],
+    "og:site_name": "Example Site",
+    "og:locale": "en_US",
+
+    // Twitter Cards
+    "twitter:card": "summary_large_image",
+    "twitter:site": "@example",
+    "twitter:creator": "@johndoe",
+    "twitter:title": "My Awesome Website",
+    "twitter:description": "This is an awesome website with great content",
+    "twitter:image": "https://example.com/twitter-image.jpg",
+
+    // Article metadata
+    "article:published_time": "2023-01-01T00:00:00Z",
+    "article:modified_time": "2023-01-02T00:00:00Z",
+    "article:author": ["John Doe", "Jane Smith"],
+    "article:section": "Technology",
+    "article:tag": ["web", "development", "javascript"],
+
+    // Product metadata
+    "product:price:amount": "29.99",
+    "product:price:currency": "USD",
+    "product:availability": "in stock",
+    "product:condition": "new",
+    "product:brand": "Example Brand",
+    "product:category": "Electronics",
+
+    // Dublin Core
+    "DC:title": "My Awesome Website",
+    "DC:creator": ["John Doe", "Jane Smith"],
+    "DC:subject": ["web development", "javascript"],
+    "DC:description": "This is an awesome website with great content",
+    "DC:publisher": "Example Publisher",
+    "DC:date": "2023-01-01",
+    "DC:type": "Text",
+    "DC:language": "en",
+
+    // Mobile app metadata
+    "apple:mobile-web-app-capable": "yes",
+    "apple:mobile-web-app-status-bar-style": "black-translucent",
+    "apple:mobile-web-app-title": "My App",
+    "msapplication:TileColor": "#ffffff",
+    "msapplication:TileImage": "/mstile-144x144.png",
+    "msapplication:task": [
+      "name=Task 1;action-uri=/task1;icon-uri=/task1.ico",
+      "name=Task 2;action-uri=/task2;icon-uri=/task2.ico",
+    ],
+
+    // HTTP-Equiv directives
+    "http-equiv:cache-control": "no-cache",
+    "http-equiv:expires": "Tue, 01 Jan 1980 1:00:00 GMT",
+
+    // Structured data & verification
+    "itemprop:name": "My Awesome Website",
+    "itemprop:description": "This is an awesome website with great content",
+    "google-site-verification": "abc123def456",
+    "fb:app_id": "123456789",
+    "geo.region": "US-NY",
+    "geo.placename": "New York City",
+    "geo.position": "40.7128;-74.0060",
+
+    // Alternate language links
+    alternate: [
+      { hreflang: "es", href: "https://example.com/es/" },
+      { hreflang: "fr", href: "https://example.com/fr/" },
+    ],
+
+    // Custom metadata
+    customMeta: {
+      name: "custom-property",
+      content: "custom-value",
+      "data-custom": "additional-data",
+    },
+  },
+};
+```