@xano/developer-mcp 1.0.5 → 1.0.6

package/dist/index.js

@@ -47,6 +47,11 @@ const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["tasks/*.xs"],
         description: "Scheduled and cron jobs",
     },
+    triggers: {
+        file: "triggers.md",
+        applyTo: ["triggers/**/*.xs"],
+        description: "Event-driven handlers (table, realtime, workspace, agent, MCP)",
+    },
     database: {
         file: "database.md",
         applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tasks/*.xs", "tools/**/*.xs"],

package/dist/templates/xanoscript-index.js

@@ -22,6 +22,7 @@ ${formatRow("function", "Custom reusable functions in `functions/`")}
 ${formatRow("api_query", "HTTP API endpoints in `apis/`")}
 ${formatRow("table", "Database table schemas in `tables/`")}
 ${formatRow("task", "Scheduled background tasks in `tasks/`")}
+${formatRow("triggers", "Event-driven handlers in `triggers/`")}
 ${formatRow("tool", "AI-callable tools in `tools/`")}
 ${formatRow("agent", "AI agents in `agents/`")}
 ${formatRow("mcp_server", "MCP servers in `mcp_servers/`")}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "MCP server for Xano Headless API documentation and XanoScript code validation",
   "type": "module",
   "main": "dist/index.js",

package/xanoscript_docs/README.md

@@ -10,6 +10,7 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 | `function` | `functions/**/*.xs` | Reusable logic blocks |
 | `query` | `apis/<group>/*.xs` | HTTP API endpoints |
 | `task` | `tasks/*.xs` | Scheduled/cron jobs |
+| `*_trigger` | `triggers/**/*.xs` | Event-driven handlers |
 | `agent` | `agents/**/*.xs` | AI-powered agents |
 | `tool` | `tools/**/*.xs` | Tools for AI agents |
 | `mcp_server` | `mcp_servers/**/*.xs` | MCP server definitions |
@@ -24,6 +25,7 @@ project/
 ├── apis/
 │   └── <api-group>/     # API endpoints grouped by domain
 ├── tasks/               # Scheduled jobs
+├── triggers/            # Event-driven handlers
 ├── agents/              # AI agents
 ├── tools/               # AI tools
 ├── mcp_servers/         # MCP server definitions
@@ -91,17 +93,21 @@ This helps AI tools apply the correct documentation based on the file being edit
 
 ## Documentation Index
 
-1. [Syntax Reference](syntax.md) - Expressions, operators, filters
-2. [Types & Inputs](types.md) - Data types, validation, input blocks
-3. [Tables](tables.md) - Database schema definitions
-4. [Functions](functions.md) - Reusable function stacks
-5. [APIs](apis.md) - HTTP endpoint definitions
-6. [Tasks](tasks.md) - Scheduled jobs
-7. [Database Operations](database.md) - Query, add, edit, delete
-8. [Agents](agents.md) - AI agent configuration
-9. [Tools](tools.md) - AI tools for agents
-10. [MCP Servers](mcp-servers.md) - Model Context Protocol servers
-11. [Testing](testing.md) - Unit tests and mocking
-12. [Integrations](integrations.md) - Cloud services, Redis, security
-13. [Frontend](frontend.md) - Static frontend development
-14. [Ephemeral](ephemeral.md) - Temporary environments
+Use `xanoscript_docs({ keyword: "<keyword>" })` to retrieve documentation.
+
+| Topic | Keyword | Description |
+|-------|---------|-------------|
+| Syntax Reference | `syntax` | Expressions, operators, filters |
+| Types & Inputs | `input` | Data types, validation, input blocks |
+| Tables | `table` | Database schema definitions |
+| Functions | `function` | Reusable function stacks |
+| APIs | `api_query` | HTTP endpoint definitions |
+| Tasks | `task` | Scheduled jobs |
+| Triggers | `trigger` | Event-driven handlers (table, realtime, workspace, agent, MCP) |
+| Database Operations | `db_query` | Query, add, edit, delete |
+| Agents | `agent` | AI agent configuration |
+| Tools | `tool` | AI tools for agents |
+| MCP Servers | `mcp_server` | Model Context Protocol servers |
+| Testing | `testing` | Unit tests and mocking |
+| Frontend | `frontend` | Static frontend development |
+| Ephemeral | `ephemeral` | Temporary environments

package/xanoscript_docs/agents.md

@@ -324,6 +324,4 @@ agent "Research Assistant" {
 3. **Limit max_steps** - Prevent infinite loops (3-10 typical)
 4. **Don't repeat tool descriptions** - They're auto-injected
 5. **Use environment variables** - Never hardcode API keys
-6. **Keep prompts focused** - One task per agent
-7. **Test with xano-free first** - Free for development
-8. **Use structured outputs** - When you need consistent JSON
+6. **Test with xano-free first** - Free for development

package/xanoscript_docs/apis.md

@@ -38,61 +38,28 @@ The query name can include slashes for nested paths:
 
 ### API Groups (Required)
 
-Every API endpoint **must** belong to an API group. API groups organize related endpoints together.
-
-**Two requirements for API groups:**
-1. Each `query` definition **must** include an `api_group` property specifying which group it belongs to
-2. API groups are organized as folders within `apis/`, each with an `api_group.xs` file
-
-- API groups appear as top-level folders under `apis/`
-- Each group **must** have an `api_group.xs` file that defines the group
-- The group contains `.xs` files defining individual endpoints
-- The group name becomes part of the endpoint URL path
-- You cannot create endpoints directly in the `apis/` root folder
-
-#### Defining an API Group
-
-Create an `api_group.xs` file in the group folder:
+Every endpoint must belong to an API group. Each group is a folder with an `api_group.xs` file:
 
 ```xs
 api_group "users" {
-  canonical = "users"                # Required: the URL path segment
-  description = "User management endpoints"
+  canonical = "users"                # Required: URL path segment
+  description = "User management"    # Optional
 }
 ```
 
-#### API Group Properties
-
-| Property | Required | Description |
-|----------|----------|-------------|
-| `canonical` | **Yes** | The URL path segment for this group. You cannot access a Xano API without it. |
-| `description` | No | What this API group contains |
-
-```xs
-api_group "events" {
-  canonical = "events-api"           # Required: URL will use /events-api
-  description = "Event management"
-}
-```
-
-> **Important:** The `canonical` property is required. It defines the base path for all endpoints in this group.
-
 ### File Structure
 ```
 apis/
-├── users/                      # API group folder
-│   ├── api_group.xs            # Required: defines the group (canonical = "users")
+├── users/
+│   ├── api_group.xs            # Defines group (canonical = "users")
 │   ├── list.xs                 # GET /users/list
-│   ├── create.xs               # POST /users/create
 │   └── by-id.xs                # GET/PATCH/DELETE /users/{id}
-└── products/                   # Another API group
-    ├── api_group.xs            # Required: defines the group (canonical = "products")
+└── products/
+    ├── api_group.xs            # Defines group (canonical = "products")
     └── search.xs               # GET /products/search
 ```
 
-> **URL Path:** The full endpoint URL is always `/<canonical>/<query name>`. For example, if `api_group.xs` has `canonical = "users"` and a query has `query "profile" verb=GET`, the endpoint URL is `/users/profile`.
-
-> **Note:** Files placed directly in `apis/` without a group folder are invalid. Each API group folder must contain an `api_group.xs` file.
+Full URL: `/<canonical>/<query name>` (e.g., `/users/profile`)
 
 ---
 
@@ -354,33 +321,11 @@ stack {
 
 ## Error Handling
 
-### Preconditions
-```xs
-stack {
-  precondition ($input.amount > 0) {
-    error_type = "inputerror"
-    error = "Amount must be positive"
-  }
-
-  precondition ($user != null) {
-    error_type = "notfound"
-    error = "User not found"
-  }
-
-  precondition ($user.id == $auth.id) {
-    error_type = "accessdenied"
-    error = "Not authorized"
-  }
-}
-```
+For complete error handling reference, use `xanoscript_docs({ keyword: "syntax" })`.
 
-### Error Types
 | Type | HTTP Status |
 |------|-------------|
-| `inputerror` | 400 Bad Request |
-| `accessdenied` | 403 Forbidden |
-| `notfound` | 404 Not Found |
-| `standard` | 500 Internal Server Error |
+| `inputerror` | 400 | `accessdenied` | 403 | `notfound` | 404 | `standard` | 500 |
 
 ---
 
@@ -404,13 +349,8 @@ When using `return = { type: "list", paging: {...} }`:
 
 ## Best Practices
 
-1. **Always set canonical** - Every `api_group` requires a `canonical` property
-2. **Always name queries** - Every `query` requires a non-empty name
-3. **RESTful design** - Use appropriate HTTP methods
-4. **Consistent naming** - Use lowercase, hyphens for multi-word paths
-5. **Authenticate sensitive operations** - Always auth for writes
-6. **Validate inputs** - Use filters and preconditions
-7. **Return appropriate errors** - Use correct error types
-8. **Paginate lists** - Never return unbounded lists
-9. **Document with description** - Explain what endpoint does
-10. **Group related endpoints** - Organize by resource in api groups
+1. **RESTful design** - Use appropriate HTTP methods for operations
+2. **Consistent naming** - Use lowercase, hyphens for multi-word paths
+3. **Authenticate writes** - Always require auth for POST/PATCH/DELETE
+4. **Paginate lists** - Never return unbounded result sets
+5. **Group by resource** - Organize endpoints in logical api groups

package/xanoscript_docs/database.md

@@ -411,7 +411,4 @@ db.external.oracle.direct_query { ... }
 2. **Use db.get for single lookups** - Simpler than db.query with single return
 3. **Use db.patch for dynamic updates** - Accepts variable data
 4. **Use transactions for atomicity** - Ensure all-or-nothing operations
-5. **Add indexes** - Index fields used in where clauses
-6. **Use null-safe operators** - `==?` for optional filters
-7. **Paginate results** - Never return unbounded lists
-8. **Validate before delete** - Check ownership/permissions
+5. **Use null-safe operators** - `==?` for optional filters

package/xanoscript_docs/ephemeral.md

@@ -325,9 +325,6 @@ publish_ephemeral_service name="migration" directory="ephemeral/my-job" mode="jo
 
 1. **Keep isolated** - Self-contained with own tables/functions
 2. **Seed test data** - Use `items` in table definitions
-3. **Use environment variables** - Store config in workspace `env`
-4. **Handle cleanup** - Use `$post` for notifications/cleanup
-5. **Validate in $pre** - Check preconditions before main logic
-6. **Use preconditions** - Verify expected outcomes in jobs
-7. **Name clearly** - Indicate purpose: `auth-test`, `data-migration`
-8. **Set end dates** - Use `ends_on` for temporary schedules
+3. **Handle cleanup** - Use `$post` for notifications/cleanup
+4. **Validate in $pre** - Check preconditions before main logic
+5. **Name clearly** - Indicate purpose: `auth-test`, `data-migration`

package/xanoscript_docs/frontend.md

@@ -284,8 +284,5 @@ The tool will:
 
 1. **Get API specs first** - Use `get_xano_api_specifications` before coding
 2. **Centralize API calls** - Single `api.js` file
-3. **Handle errors** - Show user-friendly messages
-4. **Store tokens securely** - localStorage for web, secure storage for mobile
-5. **Validate before submit** - Client-side validation before API calls
-6. **Use loading states** - Show progress during API calls
-7. **Test incrementally** - Migrate one feature at a time
+3. **Store tokens securely** - localStorage for web, secure storage for mobile
+4. **Test incrementally** - Migrate one feature at a time

package/xanoscript_docs/functions.md

@@ -63,20 +63,13 @@ Reference with path: `function.run "math/add" { ... }`
 
 ## Input Block
 
-See [types.md](types.md) for complete type reference.
+For complete type and filter reference, use `xanoscript_docs({ keyword: "input" })`.
 
 ```xs
 input {
   text name filters=trim
   int age? filters=min:0
   email contact filters=lower { sensitive = true }
-  object address? {
-    schema {
-      text street
-      text city
-      text zip
-    }
-  }
 }
 ```
 
@@ -158,49 +151,8 @@ stack {
 ```
 
 ### Error Handling
-```xs
-stack {
-  try_catch {
-    try {
-      function.run "risky_operation" { input = {} } as $result
-    }
-    catch {
-      debug.log { value = "Operation failed" }
-      var $result { value = null }
-    }
-    finally {
-      debug.log { value = "Cleanup complete" }
-    }
-  }
-}
-```
 
-### Throwing Errors
-```xs
-stack {
-  precondition ($input.amount > 0) {
-    error_type = "inputerror"
-    error = "Amount must be positive"
-  }
-
-  throw {
-    name = "ValidationError"
-    value = "Custom error message"
-  }
-}
-```
-
-### Early Return
-```xs
-stack {
-  conditional {
-    if ($input.skip) {
-      return { value = null }
-    }
-  }
-  # Continue processing...
-}
-```
+For complete error handling reference (preconditions, try-catch, throw, early return), use `xanoscript_docs({ keyword: "syntax" })`.
 
 ---
 
@@ -345,8 +297,5 @@ function "validate_email_unique" {
 1. **Single responsibility** - Each function does one thing well
 2. **Descriptive names** - Use verb_noun format: `calculate_total`, `validate_user`
 3. **Organize in folders** - Group related functions: `utils/`, `auth/`, `orders/`
-4. **Validate inputs** - Use filters and preconditions
-5. **Handle errors** - Use try_catch for external calls
-6. **Document purpose** - Add description field
-7. **Return early** - Use return for guard clauses
-8. **Keep stacks shallow** - Avoid deeply nested conditionals
+4. **Return early** - Use return for guard clauses
+5. **Keep stacks shallow** - Avoid deeply nested conditionals

package/xanoscript_docs/mcp-servers.md

@@ -182,9 +182,6 @@ The MCP protocol handles:
 ## Best Practices
 
 1. **Clear naming** - Server name should indicate its purpose
-2. **Memorable canonical IDs** - Use descriptive, stable identifiers
-3. **Comprehensive instructions** - Guide AI on server's overall purpose
-4. **Logical tool grouping** - Group related tools in one server
-5. **Use tags** - Organize servers by category
-6. **Keep focused** - One domain per server (support, analytics, etc.)
-7. **Document internally** - Use description for team documentation
+2. **Comprehensive instructions** - Guide AI on server's overall purpose
+3. **Logical tool grouping** - Group related tools in one server
+4. **Keep focused** - One domain per server (support, analytics, etc.)

package/xanoscript_docs/syntax.md

@@ -312,3 +312,73 @@ Used in `db.query` where clauses:
 $db.created_at|timestamp_add_days:7
 $db.created_at|timestamp_subtract_hours:24
 ```
+
+---
+
+## Error Handling
+
+### Preconditions
+
+Validate conditions and throw typed errors:
+
+```xs
+precondition ($input.amount > 0) {
+  error_type = "inputerror"
+  error = "Amount must be positive"
+}
+
+precondition ($user != null) {
+  error_type = "notfound"
+  error = "User not found"
+}
+
+precondition ($user.id == $auth.id) {
+  error_type = "accessdenied"
+  error = "Not authorized"
+}
+```
+
+### Error Types
+
+| Type | HTTP Status | Use Case |
+|------|-------------|----------|
+| `inputerror` | 400 Bad Request | Invalid input data |
+| `accessdenied` | 403 Forbidden | Authorization failure |
+| `notfound` | 404 Not Found | Resource doesn't exist |
+| `standard` | 500 Internal Server Error | General errors |
+
+### Throwing Errors
+
+```xs
+throw {
+  name = "ValidationError"
+  value = "Custom error message"
+}
+```
+
+### Try-Catch
+
+```xs
+try_catch {
+  try {
+    function.run "risky_operation" { input = {} } as $result
+  }
+  catch {
+    debug.log { value = "Operation failed" }
+    var $result { value = null }
+  }
+  finally {
+    debug.log { value = "Cleanup complete" }
+  }
+}
+```
+
+### Early Return
+
+```xs
+conditional {
+  if ($input.skip) {
+    return { value = null }
+  }
+}
+```

package/xanoscript_docs/tables.md

@@ -264,7 +264,4 @@ table "order" {
 2. **Use `auth = true`** only for authentication tables (typically just `user`)
 3. **Add indexes** for fields used in WHERE clauses and JOINs
 4. **Use appropriate types** - `email` for emails, `password` for credentials
-5. **Mark sensitive fields** - Set `sensitive = true` for PII
-6. **Use filters** - Apply `trim`, `lower` for consistency
-7. **Default timestamps** - Use `?=now` for created_at fields
-8. **Document with descriptions** - Add descriptions for non-obvious fields
+5. **Default timestamps** - Use `?=now` for created_at fields

package/xanoscript_docs/tasks.md

@@ -244,11 +244,8 @@ task "risky_sync" {
 
 ## Best Practices
 
-1. **Use descriptive names** - Indicate what and when: `daily_cleanup`, `hourly_sync`
-2. **Add descriptions** - Explain the purpose and schedule
-3. **Handle errors** - Use try_catch for external dependencies
-4. **Log important events** - Use debug.log for tracking
-5. **Use appropriate frequency** - Don't run more often than needed
-6. **Consider timezone** - Schedule uses UTC (+0000)
-7. **Batch operations** - Process in chunks for large datasets
-8. **Set end dates** - Use ends_on for temporary schedules
+1. **Descriptive names** - Indicate what and when: `daily_cleanup`, `hourly_sync`
+2. **Handle errors** - Use try_catch for external dependencies
+3. **Consider timezone** - Schedule uses UTC (+0000)
+4. **Batch operations** - Process in chunks for large datasets
+5. **Set end dates** - Use ends_on for temporary schedules

package/xanoscript_docs/testing.md

@@ -325,11 +325,8 @@ function "calculate_discount" {
 
 ## Best Practices
 
-1. **Test happy paths** - Verify expected behavior works
-2. **Test edge cases** - Empty arrays, null values, boundaries
-3. **Test error cases** - Invalid inputs, missing data
-4. **Use mocks** - Isolate from external dependencies
-5. **Descriptive test names** - Explain what's being tested
-6. **One assertion focus** - Each test verifies one behavior
-7. **Keep tests independent** - No shared state between tests
-8. **Test at boundaries** - Min/max values, length limits
+1. **Test happy paths, edge cases, and errors** - Cover expected, boundary, and failure scenarios
+2. **Use mocks** - Isolate from external dependencies
+3. **Descriptive test names** - Explain what's being tested
+4. **One assertion focus** - Each test verifies one behavior
+5. **Keep tests independent** - No shared state between tests

package/xanoscript_docs/tools.md

@@ -62,20 +62,15 @@ tool "get_user_by_email" {
 
 ## Input Block
 
-Same as functions, but descriptions are especially important:
+For complete type reference, use `xanoscript_docs({ keyword: "input" })`. For tools, input `description` fields are sent to the AI, so write them clearly:
 
 ```xs
 input {
-  int order_id {
-    description = "The unique order ID to look up"
-  }
+  int order_id { description = "The unique order ID to look up" }
   enum status {
     description = "New status to set"
     values = ["pending", "processing", "shipped", "delivered"]
   }
-  text reason? {
-    description = "Optional reason for the status change"
-  }
 }
 ```
 
@@ -299,7 +294,4 @@ tool "cancel_order" {
 2. **Describe all inputs** - Help AI construct valid requests
 3. **Use enums for fixed options** - Reduces AI errors
 4. **Keep tools focused** - One task per tool
-5. **Handle errors gracefully** - Return clear error messages
-6. **Validate inputs** - Use filters and preconditions
-7. **Limit response size** - Don't return huge datasets
-8. **Use composition** - Call other tools for complex operations
+5. **Limit response size** - Don't return huge datasets

package/xanoscript_docs/triggers.md

@@ -0,0 +1,532 @@
+---
+applyTo: "triggers/**/*.xs"
+---
+
+# Triggers
+
+Event-driven handlers that execute in response to system events. Triggers allow you to react to database changes, real-time messages, workspace events, agent connections, and MCP server tool calls.
+
+## Quick Reference
+
+| Trigger Type | Purpose | Required Clauses |
+|--------------|---------|------------------|
+| `table_trigger` | React to database table changes | `table`, `input`, `stack` |
+| `realtime_trigger` | Handle real-time channel events | `channel`, `input`, `stack`, `response` |
+| `workspace_trigger` | React to branch lifecycle events | `input`, `stack` |
+| `agent_trigger` | Handle AI agent connections | `agent`, `input`, `stack`, `response` |
+| `mcp_server_trigger` | Handle MCP server tool calls | `mcp_server`, `input`, `stack`, `response` |
+
+---
+
+## Table Trigger
+
+Executes when database table records are inserted, updated, deleted, or truncated.
+
+### Syntax
+
+```xs
+table_trigger "<name>" {
+  table = "<table_name>"
+  actions = {insert: true, update: true, delete: true, truncate: false}
+  datasources = ["datasource1", "datasource2"]
+  active = true
+  description = "Description of this trigger"
+  tags = ["tag1", "tag2"]
+
+  input {
+    # Define input parameters
+  }
+
+  stack {
+    # Logic to execute when triggered
+  }
+
+  history = 100
+}
+```
+
+### Required Clauses
+
+| Clause | Description |
+|--------|-------------|
+| `table` | The database table name to monitor |
+| `input` | Input parameter definitions |
+| `stack` | Logic to execute when triggered |
+
+### Optional Clauses
+
+| Clause | Type | Description |
+|--------|------|-------------|
+| `actions` | object | Which operations trigger execution |
+| `active` | boolean | Enable/disable the trigger |
+| `datasources` | array | List of datasources to apply trigger to |
+| `description` | string | Human-readable description |
+| `history` | integer/string | History retention setting |
+| `tags` | array | Tags for organization |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `insert` | Trigger on new record creation |
+| `update` | Trigger on record modification |
+| `delete` | Trigger on record deletion |
+| `truncate` | Trigger when table is truncated |
+
+### Example
+
+```xs
+table_trigger "audit_user_changes" {
+  table = "user"
+  actions = {insert: true, update: true, delete: true, truncate: false}
+  active = true
+  description = "Log all changes to user records"
+  datasources = ["main_db"]
+
+  input {
+  }
+
+  stack {
+    db.add "audit_log" {
+      data = {
+        table_name: "user",
+        action: $trigger.action,
+        record_id: $trigger.record.id,
+        timestamp: now
+      }
+    }
+  }
+
+  history = 100
+}
+```
+
+---
+
+## Realtime Trigger
+
+Handles events from real-time channels, such as client joins or messages.
+
+### Syntax
+
+```xs
+realtime_trigger "<name>" {
+  channel = "<channel_name>"
+  actions = {join: true, message: true}
+  active = true
+  description = "Description of this trigger"
+  tags = ["tag1", "tag2"]
+
+  input {
+    # Define input parameters
+  }
+
+  stack {
+    # Logic to execute when triggered
+  }
+
+  response = $result
+
+  history = 100
+}
+```
+
+### Required Clauses
+
+| Clause | Description |
+|--------|-------------|
+| `channel` | The real-time channel to monitor |
+| `input` | Input parameter definitions |
+| `stack` | Logic to execute when triggered |
+| `response` | Value to return to the client |
+
+### Optional Clauses
+
+| Clause | Type | Description |
+|--------|------|-------------|
+| `actions` | object | Which events trigger execution |
+| `active` | boolean | Enable/disable the trigger |
+| `description` | string | Human-readable description |
+| `history` | integer/string | History retention setting |
+| `tags` | array | Tags for organization |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `join` | Trigger when a client joins the channel |
+| `message` | Trigger when a message is received |
+
+### Example
+
+```xs
+realtime_trigger "chat_message_handler" {
+  channel = "chat_room"
+  actions = {join: true, message: true}
+  active = true
+  description = "Handle chat room messages and joins"
+
+  input {
+    text message filters=trim
+  }
+
+  stack {
+    conditional {
+      if ($trigger.action == "join") {
+        var $welcome { value = "Welcome to the chat!" }
+      }
+      else {
+        db.add "chat_message" {
+          data = {
+            channel: "chat_room",
+            user_id: $auth.id,
+            message: $input.message,
+            timestamp: now
+          }
+        }
+        var $welcome { value = null }
+      }
+    }
+  }
+
+  response = {status: "ok", welcome: $welcome}
+
+  history = false
+}
+```
+
+---
+
+## Workspace Trigger
+
+Executes in response to workspace branch lifecycle events.
+
+### Syntax
+
+```xs
+workspace_trigger "<name>" {
+  actions = {branch_new: true, branch_merge: true, branch_live: true}
+  active = true
+  description = "Description of this trigger"
+  tags = ["tag1", "tag2"]
+
+  input {
+    # Define input parameters
+  }
+
+  stack {
+    # Logic to execute when triggered
+  }
+
+  history = 100
+}
+```
+
+### Required Clauses
+
+| Clause | Description |
+|--------|-------------|
+| `input` | Input parameter definitions |
+| `stack` | Logic to execute when triggered |
+
+### Optional Clauses
+
+| Clause | Type | Description |
+|--------|------|-------------|
+| `actions` | object | Which branch events trigger execution |
+| `active` | boolean | Enable/disable the trigger |
+| `description` | string | Human-readable description |
+| `history` | integer/string | History retention setting |
+| `tags` | array | Tags for organization |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `branch_new` | Trigger when a new branch is created |
+| `branch_merge` | Trigger when a branch is merged |
+| `branch_live` | Trigger when a branch goes live |
+
+### Example
+
+```xs
+workspace_trigger "branch_notification" {
+  actions = {branch_new: true, branch_merge: true, branch_live: true}
+  active = true
+  description = "Send notifications on branch events"
+  tags = ["devops", "notifications"]
+
+  input {
+  }
+
+  stack {
+    util.send_email {
+      service_provider = "resend"
+      api_key = $env.RESEND_API_KEY
+      to = "team@example.com"
+      from = "system@example.com"
+      subject = "Branch Event: " ~ $trigger.action
+      message = "Branch '" ~ $trigger.branch_name ~ "' event: " ~ $trigger.action
+    }
+  }
+
+  history = false
+}
+```
+
+---
+
+## Agent Trigger
+
+Handles connections and interactions with AI agents.
+
+### Syntax
+
+```xs
+agent_trigger "<name>" {
+  agent = "<agent_name>"
+  actions = {connection: true}
+  active = true
+  description = "Description of this trigger"
+  docs = "Extended documentation for the trigger"
+  tags = ["tag1", "tag2"]
+
+  input {
+    # Define input parameters
+  }
+
+  stack {
+    # Logic to execute when triggered
+  }
+
+  response = $result
+
+  history = "inherit"
+}
+```
+
+### Required Clauses
+
+| Clause | Description |
+|--------|-------------|
+| `agent` | The AI agent name this trigger handles |
+| `input` | Input parameter definitions |
+| `stack` | Logic to execute when triggered |
+| `response` | Value to return |
+
+### Optional Clauses
+
+| Clause | Type | Description |
+|--------|------|-------------|
+| `actions` | object | Which agent events trigger execution |
+| `active` | boolean | Enable/disable the trigger |
+| `description` | string | Short description |
+| `docs` | string | Extended documentation |
+| `history` | integer/string/boolean | History retention setting |
+| `tags` | array | Tags for organization |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `connection` | Trigger on agent connection events |
+
+### Example
+
+```xs
+agent_trigger "assistant_handler" {
+  agent = "customer_assistant"
+  actions = {connection: true}
+  active = true
+  description = "Handle customer assistant agent connections"
+  docs = "This trigger initializes the customer context when the agent connects"
+
+  input {
+    text session_id filters=trim
+  }
+
+  stack {
+    db.get "customer" {
+      field_name = "session_id"
+      field_value = $input.session_id
+    } as $customer
+
+    var $context {
+      value = {
+        customer_name: $customer.name,
+        customer_tier: $customer.tier,
+        history: $customer.support_history
+      }
+    }
+  }
+
+  response = $context
+
+  history = "inherit"
+}
+```
+
+---
+
+## MCP Server Trigger
+
+Handles tool calls from MCP (Model Context Protocol) servers.
+
+### Syntax
+
+```xs
+mcp_server_trigger "<name>" {
+  mcp_server = "<server_name>"
+  actions = {connection: true}
+  active = true
+  description = "Description of this trigger"
+  tags = ["tag1", "tag2"]
+
+  input {
+    # Define input parameters
+  }
+
+  stack {
+    # Logic to execute when triggered
+  }
+
+  response = $result
+
+  history = false
+}
+```
+
+### Required Clauses
+
+| Clause | Description |
+|--------|-------------|
+| `mcp_server` | The MCP server name this trigger handles |
+| `input` | Input parameter definitions |
+| `stack` | Logic to execute when triggered |
+| `response` | Value to return to the MCP client |
+
+### Optional Clauses
+
+| Clause | Type | Description |
+|--------|------|-------------|
+| `actions` | object | Which MCP events trigger execution |
+| `active` | boolean | Enable/disable the trigger |
+| `description` | string | Human-readable description |
+| `history` | integer/string/boolean | History retention setting |
+| `tags` | array | Tags for organization |
+
+### Actions
+
+| Action | Description |
+|--------|-------------|
+| `connection` | Trigger on MCP connection events (required) |
+
+### Example
+
+```xs
+mcp_server_trigger "database_tool_handler" {
+  mcp_server = "database_tools"
+  actions = {connection: true}
+  active = true
+  description = "Handle database tool calls from MCP clients"
+  tags = ["mcp", "database"]
+
+  input {
+    text operation filters=trim
+    object params
+  }
+
+  stack {
+    conditional {
+      if ($input.operation == "query") {
+        db.query $input.params.table {
+          where = $input.params.where
+        } as $result
+      }
+      elseif ($input.operation == "insert") {
+        db.add $input.params.table {
+          data = $input.params.data
+        } as $result
+      }
+      else {
+        var $result { value = {error: "Unknown operation"} }
+      }
+    }
+  }
+
+  response = $result
+
+  history = false
+}
+```
+
+---
+
+## Common Patterns
+
+### Error Handling in Triggers
+
+```xs
+table_trigger "safe_audit" {
+  table = "sensitive_data"
+  actions = {insert: true, update: true, delete: true, truncate: false}
+
+  input {
+  }
+
+  stack {
+    try_catch {
+      try {
+        db.add "audit_log" {
+          data = {
+            action: $trigger.action,
+            timestamp: now
+          }
+        }
+      }
+      catch {
+        debug.log { value = "Audit logging failed" }
+      }
+    }
+  }
+}
+```
+
+### Conditional Trigger Logic
+
+```xs
+table_trigger "conditional_notification" {
+  table = "order"
+  actions = {insert: true, update: false, delete: false, truncate: false}
+
+  input {
+  }
+
+  stack {
+    conditional {
+      if ($trigger.record.total > 1000) {
+        util.send_email {
+          service_provider = "resend"
+          api_key = $env.RESEND_API_KEY
+          to = "sales@example.com"
+          from = "system@example.com"
+          subject = "High Value Order"
+          message = "Order #" ~ $trigger.record.id ~ " for $" ~ $trigger.record.total
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Use descriptive names** - Indicate the event and action: `user_audit_log`, `chat_message_handler`
+2. **Handle errors gracefully** - Use try_catch to prevent trigger failures from affecting the main operation
+3. **Keep triggers lightweight** - Offload heavy processing to functions or tasks
+4. **Set appropriate history** - Use `history = false` for high-frequency triggers to save storage
+5. **Use tags** - Organize triggers with meaningful tags for easier management
+6. **Document with description** - Always provide a description explaining the trigger's purpose
+7. **Test thoroughly** - Triggers execute automatically, so ensure they handle edge cases

package/xanoscript_docs/types.md

@@ -268,19 +268,12 @@ input {
 
 ## Validation with Preconditions
 
-For complex validation beyond filters:
+For complex validation beyond filters, use preconditions. For complete error handling reference, use `xanoscript_docs({ keyword: "syntax" })`.
 
 ```xs
-stack {
-  precondition ($input.start_date < $input.end_date) {
-    error_type = "inputerror"
-    error = "Start date must be before end date"
-  }
-
-  precondition ($input.password == $input.confirm_password) {
-    error_type = "inputerror"
-    error = "Passwords must match"
-  }
+precondition ($input.start_date < $input.end_date) {
+  error_type = "inputerror"
+  error = "Start date must be before end date"
 }
 ```
 
@@ -290,8 +283,5 @@ stack {
 
 1. **Always specify types** - Never leave inputs untyped
 2. **Use filters first** - Prefer declarative filters over stack validation
-3. **Add descriptions** - Document every field's purpose
-4. **Mark sensitive data** - Use `sensitive = true` for PII/credentials
-5. **Use defaults sparingly** - Make requirements explicit
-6. **Validate at boundaries** - Validate user input, trust internal calls
-7. **Limit nesting depth** - Keep object schemas 2-3 levels max
+3. **Mark sensitive data** - Use `sensitive = true` for PII/credentials
+4. **Validate at boundaries** - Validate user input, trust internal calls

package/xanoscript_docs/plan.md

@@ -1,192 +0,0 @@
-# XanoScript AI Documentation v2 - Implementation Plan
-
-## Design Principles
-
-### AI-First Documentation Goals
-1. **Scannable** - AI can quickly locate relevant syntax/patterns
-2. **Self-contained** - Each doc has everything needed for its topic
-3. **Pattern-consistent** - Identical structure across all docs
-4. **Minimal but complete** - Not verbose, but covers all cases
-5. **Examples inline** - Code immediately follows syntax it demonstrates
-
-### Document Structure Template
-Every doc follows this structure:
-```
----
-applyTo: "<glob pattern>"
----
-
-# <Topic>
-
-## Quick Reference
-<Table or code block with syntax summary>
-
-## Overview
-<1-2 paragraph explanation>
-
-## <Concept 1>
-### Syntax
-### Example
-### Notes
-
-## <Concept 2>
-...
-
-## Best Practices
-<Bullet list>
-
-## Common Patterns
-<Real-world usage patterns>
-```
-
----
-
-## Proposed File Structure
-
-### Core (Required for any XanoScript work)
-| File | Purpose | Source Files |
-|------|---------|--------------|
-| `README.md` | Overview, workspace structure, getting started | README.md, workspace.md |
-| `syntax.md` | Expressions, operators, filters | expression_guideline.md, query_filter.md |
-| `types.md` | Data types, input blocks, validation | input_guideline.md, functions.md (input section) |
-
-### Primary Constructs
-| File | Purpose | Source Files |
-|------|---------|--------------|
-| `tables.md` | Database schemas, indexes, relationships | table_guideline.md, table_examples.md |
-| `functions.md` | Reusable function stacks | function_guideline.md, function_examples.md |
-| `apis.md` | HTTP API endpoints | api_query_guideline.md, api_query_examples.md |
-| `tasks.md` | Scheduled jobs | task_guideline.md, task_examples.md |
-| `database.md` | All db.* operations | db_query_guideline.md, functions.md (db section) |
-
-### AI Integration
-| File | Purpose | Source Files |
-|------|---------|--------------|
-| `agents.md` | AI agents, LLM providers | agent_guideline.md, agent_examples.md |
-| `tools.md` | AI tools for agents/MCP | tool_guideline.md, tool_examples.md |
-| `mcp-servers.md` | MCP server configuration | mcp_server_guideline.md, mcp_server_examples.md |
-
-### Advanced Features
-| File | Purpose | Source Files |
-|------|---------|--------------|
-| `testing.md` | Unit tests, mocks, assertions | unit_testing_guideline.md |
-| `integrations.md` | Cloud, Redis, storage, security | functions.md (cloud/redis/security sections) |
-| `frontend.md` | Static frontend, Lovable migration | frontend_guideline.md, build_from_lovable.md |
-| `ephemeral.md` | Ephemeral services and jobs | ephemeral_environment_guideline.md |
-
-### Reference (Optional)
-| File | Purpose | Source Files |
-|------|---------|--------------|
-| `tips.md` | Tips, tricks, gotchas | tips_and_tricks.md |
-
----
-
-## Content Reduction Strategy
-
-### V1 Verbosity Issues
-1. **Redundant examples** - Multiple examples showing same pattern
-2. **Explanation repetition** - Same concept explained in guideline AND examples
-3. **Over-commented code** - Examples have excessive inline comments
-4. **Separate files** - guideline.md + examples.md = duplication
-
-### V2 Approach
-1. **One canonical example** per feature (not 3-5)
-2. **Table-based syntax reference** - Quick scan, no prose
-3. **Inline examples** - Example immediately after syntax
-4. **Comments only for non-obvious** - Trust the reader
-
-### Example Transformation
-
-**V1 Style (verbose):**
-```xs
-// This function calculates the total cost
-// by multiplying quantity by price per item
-// and returns the result
-function "maths/calculate_total" {
-  description = "Calculate the total cost based on quantity and price per item"
-
-  input {
-    int quantity filters=min:0 {
-      description = "Number of items"
-    }
-
-    decimal price_per_item filters=min:0.01 {
-      description = "Price for each item"
-    }
-  }
-
-  stack {
-    var $total {
-      value = 0
-      description = "Initialize total"
-    }
-
-    math.add $total {
-      value = $input.quantity * $input.price_per_item
-      description = "Calculate total"
-    }
-  }
-
-  response = $total
-}
-```
-
-**V2 Style (minimal):**
-```xs
-function "calculate_total" {
-  input {
-    int quantity filters=min:0
-    decimal price filters=min:0.01
-  }
-  stack {
-    var $total { value = $input.quantity * $input.price }
-  }
-  response = $total
-}
-```
-
----
-
-## Estimated Reduction
-
-| Metric | V1 | V2 Target | Reduction |
-|--------|-----|-----------|-----------|
-| Files | 27 | 14 | ~48% |
-| Total Lines | ~5000 | ~2000 | ~60% |
-| Avg File Size | 185 lines | 140 lines | ~25% |
-
----
-
-## Implementation Order
-
-### Phase 1: Foundation
-1. README.md - Workspace overview
-2. syntax.md - All expressions and filters
-3. types.md - Data types and inputs
-
-### Phase 2: Core Constructs
-4. tables.md - Database tables
-5. functions.md - Functions
-6. apis.md - API endpoints
-7. tasks.md - Scheduled tasks
-8. database.md - DB operations
-
-### Phase 3: AI Features
-9. agents.md - AI agents
-10. tools.md - AI tools
-11. mcp-servers.md - MCP servers
-
-### Phase 4: Advanced
-12. testing.md - Unit testing
-13. integrations.md - Cloud/Redis/Security
-14. frontend.md - Frontend + Lovable
-15. ephemeral.md - Ephemeral environments
-
----
-
-## Questions Resolved
-
-- [x] Structure: Consolidated (single file per concept)
-- [x] Examples: Minimal (just enough to demonstrate)
-- [x] Quick Reference: Yes (syntax cheatsheets at top)
-- [x] Scope: Complete coverage (all features)