@xano/developer-mcp 1.0.32 → 1.0.34

package/README.md

@@ -198,7 +198,7 @@ console.log(overview.documentation);
 const syntaxDocs = xanoscriptDocs({ topic: 'syntax' });
 
 // Get context-aware docs for a file path
-const apiDocs = xanoscriptDocs({ file_path: 'apis/users/create.xs' });
+const apiDocs = xanoscriptDocs({ file_path: 'api/users/create_post.xs' });
 
 // Get compact quick reference
 const quickRef = xanoscriptDocs({ topic: 'database', mode: 'quick_reference' });
@@ -326,7 +326,7 @@ Retrieves XanoScript programming language documentation with context-aware suppo
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `topic` | string | No | Specific documentation topic to retrieve |
-| `file_path` | string | No | File path being edited for context-aware docs (e.g., `apis/users/create.xs`) |
+| `file_path` | string | No | File path being edited for context-aware docs (e.g., `api/users/create_post.xs`) |
 | `mode` | string | No | `full` (default) or `quick_reference` for compact syntax cheatsheet |
 
 **Available Topics:**
@@ -366,7 +366,7 @@ xanoscript_docs()
 xanoscript_docs({ topic: "functions" })
 
 // Context-aware: get all docs relevant to file being edited
-xanoscript_docs({ file_path: "apis/users/create.xs" })
+xanoscript_docs({ file_path: "api/users/create_post.xs" })
 
 // Compact quick reference (uses less context)
 xanoscript_docs({ topic: "database", mode: "quick_reference" })
@@ -667,7 +667,7 @@ Compiles TypeScript to JavaScript in the `dist/` directory.
 - Markdown files for XanoScript language reference
 - Configured in `src/index.ts` via `XANOSCRIPT_DOCS_V2` with:
   - **file**: The markdown file containing the documentation
-  - **applyTo**: Glob patterns for context-aware matching (e.g., `apis/**/*.xs`)
+  - **applyTo**: Glob patterns for context-aware matching (e.g., `api/**/*.xs`)
   - **description**: Human-readable description of the topic
 
 **Meta API Documentation** (`src/meta_api_docs/`):

package/dist/cli_docs/topics/workspace.js

@@ -17,16 +17,59 @@ function: refresh_token
 ...
 \`\`\`
 
-When you pull, the CLI splits these into individual \`.xs\` files organized by type.`,
+When you pull, the CLI splits these into individual \`.xs\` files organized by type.
+
+## Directory Structure
+
+After \`workspace:pull\`, files are organized using snake_case naming:
+
+\`\`\`
+./xano-code/
+├── workspace/
+│   ├── my_workspace.xs           # Workspace configuration
+│   └── trigger/
+│       └── on_deploy.xs          # Workspace triggers
+├── api/
+│   └── users/                    # API group folder (snake_case)
+│       ├── api_group.xs          # API group definition
+│       ├── get_all.xs            # GET /users
+│       ├── get_one_get.xs        # GET /users/:id
+│       ├── create_post.xs        # POST /users
+│       └── nested/
+│           └── profile_get.xs    # GET /users/nested/profile
+├── function/
+│   └── validate_token.xs         # Reusable functions
+├── task/
+│   └── daily_cleanup.xs          # Scheduled tasks
+├── table/
+│   ├── users.xs                  # Table schema
+│   └── trigger/
+│       └── on_user_create.xs     # Table triggers
+├── agent/
+│   ├── support_bot.xs            # AI agents
+│   └── trigger/
+│       └── on_message.xs         # Agent triggers
+└── mcp_server/
+    ├── my_server.xs              # MCP server definitions
+    └── trigger/
+        └── on_connect.xs         # MCP server triggers
+\`\`\``,
     ai_hints: `**Key concepts:**
 - \`pull\` downloads workspace code and splits into organized .xs files
 - \`push\` combines .xs files and uploads to Xano
-- Files are organized by type: functions/, apis/, tasks/, etc.
+- Files use snake_case naming for folders and filenames
+- API endpoints are nested under their API group folder
 
 **Typical workflow:**
 1. \`xano workspace:pull ./xano-code\` - download
-2. Edit .xs files with your editor/IDE
-3. \`xano workspace:push ./xano-code\` - deploy
+2. Navigate to \`api/{group}/\` for API endpoints, \`function/\` for functions, etc.
+3. Edit .xs files with your editor/IDE
+4. \`xano workspace:push ./xano-code\` - deploy
+
+**File naming:**
+- All folders and files use snake_case (e.g., \`my_function.xs\`, \`user_profile/\`)
+- API endpoints include verb suffix (e.g., \`create_post.xs\`, \`get_one_get.xs\`)
+- Triggers are nested under \`{type}/trigger/\` folders
 
 **Version control:**
 - The pulled directory structure is git-friendly
@@ -159,13 +202,14 @@ When you pull, the CLI splits these into individual \`.xs\` files organized by t
             description: "Edit Xano code locally with your preferred tools",
             steps: [
                 "Pull workspace: `xano workspace:pull ./code`",
-                "Edit .xs files in your IDE",
+                "Navigate to organized folders: `api/{group}/`, `function/`, `table/`, etc.",
+                "Edit .xs files in your IDE (files use snake_case naming)",
                 "Validate changes: Use xanoscript_docs MCP tool",
                 "Push changes: `xano workspace:push ./code`",
                 "Test in Xano dashboard or via API"
             ],
             example: `xano workspace:pull ./my-app
-# Edit files...
+# Files organized: api/users/create_post.xs, function/validate_token.xs, etc.
 xano workspace:push ./my-app`
         },
         {

package/dist/xanoscript.js

@@ -21,6 +21,11 @@ export const XANOSCRIPT_DOCS_V2 = {
         applyTo: ["**/*.xs"],
         description: "Expressions, operators, and filters for all XanoScript code",
     },
+    quickstart: {
+        file: "quickstart.md",
+        applyTo: ["**/*.xs"],
+        description: "Common patterns, quick reference, and common mistakes to avoid",
+    },
     types: {
         file: "types.md",
         applyTo: ["functions/**/*.xs", "apis/**/*.xs", "tools/**/*.xs", "agents/**/*.xs"],

package/dist/xanoscript.test.js

@@ -11,6 +11,7 @@ describe("xanoscript module", () => {
             const expectedTopics = [
                 "readme",
                 "syntax",
+                "quickstart",
                 "types",
                 "tables",
                 "functions",
@@ -135,9 +136,10 @@ describe("xanoscript module", () => {
             const result = getDocsForFilePath("apis/test.xs");
             expect(result).not.toContain("readme");
         });
-        it("should put syntax first if not already matched", () => {
+        it("should include syntax and quickstart for .xs files", () => {
             const result = getDocsForFilePath("some/random/file.xs");
-            expect(result[0]).toBe("syntax");
+            expect(result).toContain("syntax");
+            expect(result).toContain("quickstart");
         });
     });
     describe("extractQuickReference", () => {

package/dist/xanoscript_docs/README.md

@@ -4,45 +4,81 @@ XanoScript is the declarative scripting language for [Xano](https://xano.com), a
 
 ## Quick Reference
 
-| Construct          | File Location         | Purpose                       |
-| ------------------ | --------------------- | ----------------------------- |
-| `table`            | `tables/*.xs`         | Database schema definition    |
-| `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        |
-| `addon`            | `addons/*.xs`         | Subqueries for related data   |
-| `middleware`       | `middleware/**/*.xs`  | Request/response interceptors |
-| `branch`           | `branch.xs`           | Branch-level configuration    |
-| `workspace`        | `workspace.xs`        | Workspace-level configuration |
-| `realtime_channel` | Configuration         | Realtime channel settings     |
+| Construct           | File Location                        | Purpose                       |
+| ------------------- | ------------------------------------ | ----------------------------- |
+| `workspace`         | `workspace/{name}.xs`                | Workspace-level configuration |
+| `workspace_trigger` | `workspace/trigger/{name}.xs`        | Workspace event handlers      |
+| `table`             | `table/{name}.xs`                    | Database schema definition    |
+| `table_trigger`     | `table/trigger/{name}.xs`            | Table event handlers          |
+| `api_group`         | `api/{group}/api_group.xs`           | API group definition          |
+| `query`             | `api/{group}/{endpoint}_{verb}.xs`   | HTTP API endpoints            |
+| `function`          | `function/{name}.xs`                 | Reusable logic blocks         |
+| `task`              | `task/{name}.xs`                     | Scheduled/cron jobs           |
+| `agent`             | `agent/{name}.xs`                    | AI-powered agents             |
+| `agent_trigger`     | `agent/trigger/{name}.xs`            | Agent event handlers          |
+| `tool`              | `tool/{name}.xs`                     | Tools for AI agents           |
+| `mcp_server`        | `mcp_server/{name}.xs`               | MCP server definitions        |
+| `mcp_server_trigger`| `mcp_server/trigger/{name}.xs`       | MCP server event handlers     |
+| `addon`             | `addon/{name}.xs`                    | Subqueries for related data   |
+| `middleware`        | `middleware/{name}.xs`               | Request/response interceptors |
+| `branch`            | `branch.xs`                          | Branch-level configuration    |
+| `realtime_channel`  | Configuration                        | Realtime channel settings     |
+
+**Naming convention:** All folder and file names use `snake_case` (e.g., `user_profile.xs`, `get_all_users_get.xs`).
 
 **Important:** Each `.xs` file must contain exactly one definition. You cannot define multiple tables, functions, queries, or other constructs in a single file.
 
 ## Workspace Structure
 
+After pulling from Xano, files are organized using `snake_case` naming:
+
 ```
 project/
-├── workspace.xs         // Workspace configuration (env vars, preferences)
-├── branch.xs            // Branch configuration (middleware, history)
-├── tables/              // Database table schemas
-├── functions/           // Reusable functions (supports subfolders)
-├── 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
-├── middleware/          // Request/response interceptors
-├── addons/              // Query addons
-├── static/              // Frontend files (HTML, CSS, JS)
-└── run/                 // Job and service configurations
+├── branch.xs                        # Branch configuration
+├── workspace/
+│   ├── my_workspace.xs              # Workspace configuration
+│   └── trigger/
+│       └── on_deploy.xs             # Workspace triggers
+├── api/
+│   └── users/                       # API group folder
+│       ├── api_group.xs             # API group definition
+│       ├── get_all_get.xs           # GET /users
+│       ├── get_one_get.xs           # GET /users/:id
+│       ├── create_post.xs           # POST /users
+│       └── nested/
+│           └── profile_get.xs       # Nested endpoint: GET /users/nested/profile
+├── function/
+│   └── validate_token.xs            # Reusable functions
+├── task/
+│   └── daily_cleanup.xs             # Scheduled jobs
+├── table/
+│   ├── users.xs                     # Table schema
+│   └── trigger/
+│       └── on_user_create.xs        # Table triggers
+├── agent/
+│   ├── support_bot.xs               # AI agents
+│   └── trigger/
+│       └── on_message.xs            # Agent triggers
+├── tool/
+│   └── search_docs.xs               # AI tools
+├── mcp_server/
+│   ├── my_server.xs                 # MCP server definitions
+│   └── trigger/
+│       └── on_connect.xs            # MCP server triggers
+├── middleware/
+│   └── auth_check.xs                # Request/response interceptors
+├── addon/
+│   └── user_posts.xs                # Query addons
+├── static/                          # Frontend files (HTML, CSS, JS)
+└── run/                             # Job and service configurations
 ```
 
+**Key conventions:**
+- All folders and files use `snake_case` naming
+- API endpoints include the HTTP verb suffix (e.g., `create_post.xs`, `get_one_get.xs`)
+- Triggers are nested under `{type}/trigger/` folders
+- Nested API paths become nested folders (e.g., `/users/nested/profile` → `api/users/nested/profile_get.xs`)
+
 ## Environment Variables
 
 Access with `$env.<name>`. Common built-in variables include `$env.$remote_ip`, `$env.$http_headers`, `$env.$request_method`, `$env.$datasource`, and `$env.$branch`. Custom environment variables are set in the Xano dashboard and accessed as `$env.MY_VAR`.
@@ -100,24 +136,41 @@ Documentation files use frontmatter to specify which file patterns they apply to
 
 ```markdown
 ---
-applyTo: "functions/**/*.xs"
+applyTo: "function/**/*.xs"
 ---
 ```
 
 This helps AI tools apply the correct documentation based on the file being edited.
 
+## Getting Started
+
+For common patterns and quick examples, use:
+```
+xanoscript_docs({ topic: "quickstart" })
+```
+
+This includes:
+- Variable declaration patterns
+- Conditional logic (if/elseif/else)
+- API requests with error handling
+- Database CRUD operations
+- Common mistakes to avoid
+
+---
+
 ## Documentation Index
 
 Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 
 ### Core Language
 
-| Topic       | Description                                       |
-| ----------- | ------------------------------------------------- |
-| `syntax`    | Expressions, operators, filters, system variables |
-| `types`     | Data types, validation, input blocks              |
-| `functions` | Reusable function stacks, async, loops            |
-| `schema`    | Runtime schema parsing and validation             |
+| Topic        | Description                                          |
+| ------------ | ---------------------------------------------------- |
+| `quickstart` | Common patterns, quick examples, mistakes to avoid   |
+| `syntax`     | Expressions, operators, filters, system variables    |
+| `types`      | Data types, validation, input blocks                 |
+| `functions`  | Reusable function stacks, async, loops               |
+| `schema`     | Runtime schema parsing and validation                |
 
 ### Data
 
@@ -174,3 +227,47 @@ Use `xanoscript_docs({ topic: "<topic>" })` to retrieve documentation.
 | ------------- | ------------------------------------------------------------ |
 | `performance` | Performance optimization best practices                      |
 | `security`    | Security best practices for authentication and authorization |
+
+---
+
+## Example Implementations
+
+Common integration patterns you can reference:
+
+### External API Integrations
+- **OpenAI/ChatGPT**: Use `api.request` with POST to `/v1/chat/completions`
+- **Stripe**: Use `api.request` with form-encoded params for payments
+- **SendGrid/Resend**: Use `api.request` or `util.send_email` for emails
+- **Slack/Discord**: Use `api.request` with webhook URLs
+- **Twilio**: Use `api.request` with Basic auth for SMS
+
+### Common Pattern: API Integration Function
+
+```xs
+function "call_external_api" {
+  input {
+    text endpoint
+    object payload
+  }
+  stack {
+    api.request {
+      url = $env.API_BASE_URL ~ $input.endpoint
+      method = "POST"
+      params = $input.payload
+      headers = [
+        "Content-Type: application/json",
+        "Authorization: Bearer " ~ $env.API_KEY
+      ]
+      timeout = 30
+    } as $api_result
+
+    precondition ($api_result.response.status >= 200 && $api_result.response.status < 300) {
+      error_type = "standard"
+      error = "API error: " ~ ($api_result.response.status|to_text)
+    }
+  }
+  response = $api_result.response.result
+}
+```
+
+For more patterns, see `xanoscript_docs({ topic: "quickstart" })` or `xanoscript_docs({ topic: "integrations" })`.

package/dist/xanoscript_docs/addons.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "addons/*.xs, functions/**/*.xs, apis/**/*.xs"
+applyTo: "addon/**/*.xs, function/**/*.xs, api/**/*.xs"
 ---
 
 # Addons
@@ -231,7 +231,7 @@ db.query product {
 ### File Structure
 
 ```
-addons/
+addon/
 ├── comment_count.xs
 ├── like_count.xs
 ├── author_details.xs

package/dist/xanoscript_docs/agents.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "agents/**/*.xs"
+applyTo: "agent/**/*.xs"
 ---
 
 # Agents
@@ -186,7 +186,7 @@ agent "Classifier" {
 
 ## Tools
 
-Reference tools by name from `tools/` directory:
+Reference tools by name from `tool/` directory:
 
 ```xs
 tools = [

package/dist/xanoscript_docs/apis.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "apis/**/*.xs"
+applyTo: "api/**/*.xs"
 ---
 
 # APIs
@@ -77,16 +77,18 @@ api_group Authentication {
 ### File Structure
 
 ```
-apis/
+api/
 ├── users/
-│   ├── api_group.xs            // Defines group (canonical = "myapp-users")
-│   ├── list.xs                 // GET /myapp-users/list
-│   └── by-id.xs                // GET/PATCH/DELETE /myapp-users/{id}
+│   ├── api_group.xs            # Defines group (canonical = "myapp-users")
+│   ├── list_get.xs             # GET /myapp-users/list
+│   └── by_id_get.xs            # GET /myapp-users/{id}
 └── products/
-    ├── api_group.xs            // Defines group (canonical = "myapp-products")
-    └── search.xs               // GET /myapp-products/search
+    ├── api_group.xs            # Defines group (canonical = "myapp-products")
+    └── search_get.xs           # GET /myapp-products/search
 ```
 
+**Naming convention:** Endpoint files use `{name}_{verb}.xs` format (e.g., `list_get.xs`, `create_post.xs`).
+
 Full URL: `/<canonical>/<query name>` (e.g., `/myapp-users/profile`)
 
 ---

package/dist/xanoscript_docs/branch.md

@@ -222,10 +222,11 @@ Branch configuration files are typically named `branch.xs` and placed at the wor
 
 ```
 project/
-├── branch.xs              // Branch configuration
-├── tables/
-├── functions/
-└── apis/
+├── branch.xs              # Branch configuration
+├── workspace/
+├── table/
+├── function/
+└── api/
 ```
 
 ---

package/dist/xanoscript_docs/database.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs, tasks/*.xs, tools/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs, task/**/*.xs, tool/**/*.xs"
 ---
 
 # Database Operations

package/dist/xanoscript_docs/functions.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs"
+applyTo: "function/**/*.xs"
 ---
 
 # Functions
@@ -62,7 +62,7 @@ function "calculate_total" {
 Functions can be organized in subfolders:
 
 ```
-functions/
+function/
 ├── math/
 │   ├── add.xs
 │   └── multiply.xs

package/dist/xanoscript_docs/integrations.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs, tasks/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs, task/**/*.xs"
 ---
 
 # Integrations
@@ -575,22 +575,92 @@ util.send_email {
 
 ---
 
-## External APIs
+## External APIs (api.request)
 
 Make HTTP requests to external APIs.
 
+### Quick Reference
+
 ```xs
 api.request {
-  url = "https://api.example.com/data"
-  method = "POST"
-  params = { key: "value" }
+  url = "https://api.example.com/endpoint"
+  method = "POST"                    // GET, POST, PUT, PATCH, DELETE
+  params = $payload                  // Request body for POST/PUT/PATCH
   headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
-  timeout = 30
+  timeout = 30                       // Timeout in seconds
 } as $api_result
+
+// Access response
+$api_result.response.status          // HTTP status code (200, 404, etc.)
+$api_result.response.result          // Response body (auto-parsed JSON)
+$api_result.response.headers         // Response headers array
 ```
 
+> **Important:** The `params` parameter is used for the **request body** (POST/PUT/PATCH), not query parameters. This naming is counterintuitive but consistent across XanoScript.
+
 > **Note:** The `headers` parameter expects an array of text strings, where each string contains the header name and value separated by a colon (e.g., `["Content-Type: application/json", "X-Custom-Header: value"]`).
 
+### GET Request
+
+```xs
+api.request {
+  url = "https://api.example.com/users?page=1&limit=10"
+  method = "GET"
+  headers = ["Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+var $users { value = $api_result.response.result }
+```
+
+### POST Request with JSON Body
+
+```xs
+var $payload {
+  value = {
+    name: $input.name,
+    email: $input.email
+  }
+}
+
+api.request {
+  url = "https://api.example.com/users"
+  method = "POST"
+  params = $payload
+  headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+// Check for success
+precondition ($api_result.response.status == 201) {
+  error_type = "standard"
+  error = "Failed to create user: " ~ ($api_result.response.result|json_encode)
+}
+```
+
+### Error Handling Pattern
+
+```xs
+api.request {
+  url = "https://api.example.com/data"
+  method = "GET"
+  timeout = 30
+} as $api_result
+
+conditional {
+  if ($api_result.response.status >= 200 && $api_result.response.status < 300) {
+    var $data { value = $api_result.response.result }
+  }
+  elseif ($api_result.response.status == 404) {
+    throw { name = "NotFound", value = "Resource not found" }
+  }
+  else {
+    throw {
+      name = "APIError",
+      value = "API returned status " ~ ($api_result.response.status|to_text)
+    }
+  }
+}
+```
+
 ### Response Structure
 
 The `api.request` statement returns an object with both request and response details:

package/dist/xanoscript_docs/mcp-servers.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "mcp_servers/**/*.xs"
+applyTo: "mcp_server/**/*.xs"
 ---
 
 # MCP Servers
@@ -52,7 +52,7 @@ mcp_server "Customer Support" {
 
 ## Tools Block
 
-Reference tools from `tools/` directory by name:
+Reference tools from `tool/` directory by name:
 
 ```xs
 tools = [
@@ -62,7 +62,7 @@ tools = [
 ]
 ```
 
-Tool names must exactly match `.xs` file names in `tools/`.
+Tool names must exactly match `.xs` file names in `tool/`.
 
 ---
 
@@ -146,19 +146,19 @@ mcp_server "CRM" {
 
 ### By Domain
 ```
-mcp_servers/
-├── support.xs          // Customer support tools
-├── ecommerce.xs        // Store management
-├── analytics.xs        // Reporting and metrics
-└── admin.xs            // Administrative functions
+mcp_server/
+├── support.xs          # Customer support tools
+├── ecommerce.xs        # Store management
+├── analytics.xs        # Reporting and metrics
+└── admin.xs            # Administrative functions
 ```
 
 ### By Access Level
 ```
-mcp_servers/
-├── public.xs           // Public-facing tools
-├── authenticated.xs    // Requires auth
-└── admin.xs            // Admin-only tools
+mcp_server/
+├── public.xs           # Public-facing tools
+├── authenticated.xs    # Requires auth
+└── admin.xs            # Admin-only tools
 ```
 
 ---

package/dist/xanoscript_docs/performance.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs"
 ---
 
 # Performance Optimization

package/dist/xanoscript_docs/quickstart.md

@@ -0,0 +1,340 @@
+---
+applyTo: "**/*.xs"
+---
+
+# Quickstart & Common Patterns
+
+Essential patterns for XanoScript development. Use this as a quick reference for frequently-used code patterns.
+
+## Quick Reference
+
+### Variable Declaration
+```xs
+var $name { value = "initial value" }
+var $count { value = 0 }
+var $data { value = { key: "value" } }
+```
+
+### Conditional Logic
+```xs
+conditional {
+  if (`$status == "active"`) {
+    var $result { value = "Active user" }
+  }
+  elseif (`$status == "pending"`) {
+    var $result { value = "Pending approval" }
+  }
+  else {
+    var $result { value = "Unknown status" }
+  }
+}
+```
+
+### API Request with Error Handling
+```xs
+api.request {
+  url = "https://api.example.com/data"
+  method = "POST"
+  params = $payload
+  headers = ["Content-Type: application/json", "Authorization: Bearer " ~ $env.API_KEY]
+} as $api_result
+
+precondition ($api_result.response.status == 200) {
+  error_type = "standard"
+  error = "API request failed"
+}
+
+var $data { value = $api_result.response.result }
+```
+
+### String Concatenation
+```xs
+var $greeting { value = "Hello, " ~ $input.name ~ "!" }
+
+// With filters (use parentheses)
+var $message { value = "Status: " ~ ($status|to_text) ~ " - " ~ ($data|json_encode) }
+```
+
+---
+
+## Common Patterns
+
+### 1. Input Validation
+
+```xs
+// Required field check
+precondition ($input.email != null && $input.email != "") {
+  error_type = "inputerror"
+  error = "Email is required"
+}
+
+// Format validation
+precondition ($input.email|contains:"@") {
+  error_type = "inputerror"
+  error = "Invalid email format"
+}
+```
+
+### 2. Database CRUD
+
+```xs
+// Create
+db.add "user" {
+  data = { name: $input.name, email: $input.email }
+} as $new_user
+
+// Read one
+db.get "user" {
+  where = $db.user.id == $input.id
+} as $user
+
+// Read many
+db.query "user" {
+  where = $db.user.is_active == true
+  order = [{ field: created_at, direction: desc }]
+  paging = { limit: 10, offset: 0 }
+} as $users
+
+// Update
+db.edit "user" {
+  where = $db.user.id == $input.id
+  data = { name: $input.name }
+}
+
+// Delete
+db.delete "user" {
+  where = $db.user.id == $input.id
+}
+```
+
+### 3. Optional Field Handling
+
+```xs
+// Build object with optional fields
+var $data { value = { required_field: $input.required } }
+
+conditional {
+  if ($input.optional_field != null) {
+    var.update $data { value = $data|set:"optional_field":$input.optional_field }
+  }
+}
+
+// Or use set_ifnotnull
+var $data {
+  value = { required: $input.required }|set_ifnotnull:"optional":$input.optional
+}
+```
+
+### 4. Loop Through Array
+
+```xs
+// Using each
+each ($items as $item) {
+  debug.log { value = $item.name }
+}
+
+// Using map filter
+var $names { value = $items|map:$$.name }
+
+// Using filter
+var $active_items { value = $items|filter:$$.is_active == true }
+```
+
+### 5. Error Handling with Try-Catch
+
+```xs
+try_catch {
+  try {
+    api.request {
+      url = "https://api.example.com/risky"
+      method = "GET"
+    } as $result
+  }
+  catch {
+    debug.log { value = "Request failed, using fallback" }
+    var $result { value = { response: { result: null } } }
+  }
+}
+```
+
+### 6. Authentication Check
+
+```xs
+// Require authenticated user
+precondition ($auth.id != null) {
+  error_type = "accessdenied"
+  error = "Authentication required"
+}
+
+// Check user owns resource
+db.get "post" {
+  where = $db.post.id == $input.post_id
+} as $post
+
+precondition ($post.user_id == $auth.id) {
+  error_type = "accessdenied"
+  error = "You can only edit your own posts"
+}
+```
+
+### 7. Pagination
+
+```xs
+var $page { value = $input.page ?? 1 }
+var $limit { value = $input.limit ?? 20 }
+var $offset { value = ($page - 1) * $limit }
+
+db.query "item" {
+  where = $db.item.is_active == true
+  order = [{ field: created_at, direction: desc }]
+  paging = { limit: $limit, offset: $offset }
+  count = true
+} as $result
+
+response = {
+  items: $result.items,
+  total: $result.count,
+  page: $page,
+  pages: ($result.count / $limit)|ceil
+}
+```
+
+### 8. Building Complex Objects
+
+```xs
+// Step by step
+var $response { value = {} }
+var.update $response { value = $response|set:"user":$user }
+var.update $response { value = $response|set:"posts":$posts }
+var.update $response { value = $response|set:"stats":{ count: $posts|count } }
+
+// Or all at once
+var $response {
+  value = {
+    user: $user,
+    posts: $posts,
+    stats: { count: $posts|count }
+  }
+}
+```
+
+### 9. Date/Time Operations
+
+```xs
+// Current timestamp
+var $now { value = now }
+
+// Format for display
+var $formatted { value = now|format_timestamp:"Y-m-d H:i:s":"UTC" }
+
+// Relative time
+var $yesterday { value = now|transform_timestamp:"-1 day" }
+var $next_week { value = now|transform_timestamp:"+7 days" }
+
+// Compare dates
+db.query "event" {
+  where = $db.event.start_date >= now
+} as $upcoming_events
+```
+
+### 10. JSON API Response
+
+```xs
+api.request {
+  url = "https://api.openai.com/v1/chat/completions"
+  method = "POST"
+  params = {
+    model: "gpt-4",
+    messages: [{ role: "user", content: $input.prompt }]
+  }
+  headers = [
+    "Content-Type: application/json",
+    "Authorization: Bearer " ~ $env.OPENAI_API_KEY
+  ]
+} as $api_result
+
+conditional {
+  if ($api_result.response.status == 200) {
+    var $answer { value = $api_result.response.result.choices|first|get:"message"|get:"content" }
+  }
+  else {
+    throw {
+      name = "APIError",
+      value = "OpenAI API error: " ~ ($api_result.response.status|to_text)
+    }
+  }
+}
+```
+
+---
+
+## Common Mistakes
+
+### 1. Using `else if` instead of `elseif`
+```xs
+// ❌ Wrong
+conditional {
+  if (...) { }
+  else if (...) { }  // Parse error!
+}
+
+// ✅ Correct
+conditional {
+  if (...) { }
+  elseif (...) { }
+}
+```
+
+### 2. Missing parentheses in filter concatenation
+```xs
+// ❌ Wrong
+var $msg { value = $status|to_text ~ " - " ~ $data|json_encode }
+
+// ✅ Correct
+var $msg { value = ($status|to_text) ~ " - " ~ ($data|json_encode) }
+```
+
+### 3. Using `body` instead of `params` for api.request
+```xs
+// ❌ Wrong
+api.request {
+  url = "..."
+  method = "POST"
+  body = $payload  // "body" is not valid!
+}
+
+// ✅ Correct
+api.request {
+  url = "..."
+  method = "POST"
+  params = $payload  // Use "params" for request body
+}
+```
+
+### 4. Using `default` filter (doesn't exist)
+```xs
+// ❌ Wrong
+var $value { value = $input.optional|default:"fallback" }
+
+// ✅ Correct
+var $value { value = $input.optional|first_notnull:"fallback" }
+// or
+var $value { value = $input.optional ?? "fallback" }
+```
+
+### 5. Using $env in run.job input blocks
+```xs
+// ❌ Wrong - $env not allowed in input blocks
+run.job "my_job" {
+  input {
+    text api_key = $env.API_KEY
+  }
+}
+
+// ✅ Correct - use $env in the stack
+run.job "my_job" {
+  stack {
+    var $api_key { value = $env.API_KEY }
+  }
+}
+```

package/dist/xanoscript_docs/realtime.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs, triggers/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs, */trigger/**/*.xs"
 ---
 
 # Realtime

package/dist/xanoscript_docs/run.md

@@ -16,9 +16,9 @@ Define job and service configurations for the Xano Job Runner.
 ### Directory Structure
 ```
 run.xs
-tables/
-functions/
-apis/
+table/
+function/
+api/
 ```
 
 ---
@@ -216,9 +216,9 @@ function "process_data" {
 
 ```
 run.xs
-tables/
+table/
 └── users.xs
-functions/
+function/
 └── migrate_users.xs
 ```
 
@@ -235,7 +235,7 @@ run.job "Data Migration" {
 }
 ```
 
-### tables/users.xs
+### table/users.xs
 ```xs
 table users {
   auth = false
@@ -255,7 +255,7 @@ table users {
 }
 ```
 
-### functions/migrate_users.xs
+### function/migrate_users.xs
 ```xs
 function "migrate_users" {
   input {
@@ -287,12 +287,13 @@ function "migrate_users" {
 
 ```
 run.xs
-tables/
+table/
 └── event.xs
-apis/
-├── api_group.xs
-├── list.xs
-└── add.xs
+api/
+└── events/
+    ├── api_group.xs
+    ├── list_get.xs
+    └── add_post.xs
 ```
 
 ### run.xs
@@ -306,7 +307,7 @@ run.service "Event Tracker" {
 }
 ```
 
-### tables/event.xs
+### table/event.xs
 ```xs
 table event {
   auth = false
@@ -322,7 +323,7 @@ table event {
 }
 ```
 
-### apis/list.xs
+### api/events/list_get.xs
 ```xs
 query list verb=GET {
   api_group = "events"

package/dist/xanoscript_docs/schema.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs"
 ---
 
 # Schema Operations

package/dist/xanoscript_docs/security.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs"
 ---
 
 # Security

package/dist/xanoscript_docs/streaming.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs"
 ---
 
 # Streaming Operations

package/dist/xanoscript_docs/syntax.md

@@ -21,12 +21,67 @@ Complete reference for XanoScript expressions, operators, and filters.
 | Filter | Purpose | Example |
 |--------|---------|---------|
 | `trim` | Remove whitespace | `$s\|trim` |
-| `lower` / `upper` | Case conversion | `$s\|to_lower` |
+| `to_lower` / `to_upper` | Case conversion | `$s\|to_lower` |
 | `first` / `last` | Array endpoints | `$arr\|first` |
 | `count` | Array/object length | `$arr\|count` |
 | `get` | Object property | `$obj\|get:"key"` |
 | `set` | Set property | `$obj\|set:"key":"val"` |
 | `json_encode` / `json_decode` | JSON conversion | `$obj\|json_encode` |
+| `to_text` / `to_int` | Type conversion | `$num\|to_text` |
+
+> **Note:** There is no `default` filter. Use conditional blocks or `first_notnull`/`first_notempty` instead.
+
+### String Concatenation with Filters
+
+When concatenating strings that use filters, wrap each filtered expression in parentheses:
+
+```xs
+// ✅ Correct - parentheses around filtered expressions
+var $message {
+  value = ($status|to_text) ~ ": " ~ ($data|json_encode)
+}
+
+// ❌ Incorrect - missing parentheses causes parse error
+var $message {
+  value = $status|to_text ~ ": " ~ $data|json_encode
+}
+```
+
+---
+
+## Conditional Blocks
+
+Use `conditional` blocks for if/elseif/else logic:
+
+```xs
+conditional {
+  if (`$status == "success"`) {
+    var $message { value = "All good!" }
+  }
+  elseif (`$status == "pending"`) {
+    var $message { value = "Please wait..." }
+  }
+  else {
+    var $message { value = "Unknown status" }
+  }
+}
+```
+
+> **Important:** Use `elseif` (one word), not `else if` or `else { if (...) }`. Nested `if` inside `else` blocks is not supported.
+
+### Conditional as Expression
+
+Use conditional blocks inline to return values:
+
+```xs
+var $tier_limit {
+  value = conditional {
+    if ($auth.tier == "premium") { 1000 }
+    elseif ($auth.tier == "pro") { 500 }
+    else { 100 }
+  }
+}
+```
 
 ---
 
@@ -431,6 +486,32 @@ var $client_ip { value = $env.$remote_ip }
 var $method { value = $env.$request_method }
 var $headers { value = $env.$http_headers }
 var $current_branch { value = $env.$branch }
+
+// Custom environment variables (set in Xano dashboard)
+var $api_key { value = $env.MY_API_KEY }
+```
+
+### $env Limitations
+
+> **Important:** `$env` variables cannot be used in `run.job` or `run.service` input blocks. Input values must be constants.
+
+```xs
+// ❌ Invalid - $env not allowed in run.job input
+run.job "my_job" {
+  input {
+    text api_key = $env.API_KEY    // Error!
+  }
+}
+
+// ✅ Valid - access $env inside the stack instead
+run.job "my_job" {
+  input {
+    text api_key                   // No default value
+  }
+  stack {
+    var $key { value = $env.API_KEY }
+  }
+}
 ```
 
 ---

package/dist/xanoscript_docs/tables.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "tables/*.xs"
+applyTo: "table/**/*.xs"
 ---
 
 # Tables

package/dist/xanoscript_docs/tasks.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "tasks/*.xs"
+applyTo: "task/**/*.xs"
 ---
 
 # Tasks

package/dist/xanoscript_docs/testing.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs"
 ---
 
 # Testing

package/dist/xanoscript_docs/tools.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "tools/**/*.xs"
+applyTo: "tool/**/*.xs"
 ---
 
 # Tools

package/dist/xanoscript_docs/triggers.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "triggers/**/*.xs"
+applyTo: "*/trigger/**/*.xs"
 ---
 
 # Triggers

package/dist/xanoscript_docs/types.md

@@ -1,5 +1,5 @@
 ---
-applyTo: "functions/**/*.xs, apis/**/*.xs, tools/**/*.xs, agents/**/*.xs"
+applyTo: "function/**/*.xs, api/**/*.xs, tool/**/*.xs, agent/**/*.xs"
 ---
 
 # Types & Inputs

package/dist/xanoscript_docs/workspace.md

@@ -175,11 +175,12 @@ Workspace configuration is stored in `workspace.xs` at the root of your project.
 
 ```
 project/
-├── workspace.xs           // Workspace configuration
-├── branch.xs              // Branch configuration
-├── tables/
-├── functions/
-└── apis/
+├── branch.xs              # Branch configuration
+├── workspace/
+│   └── my_workspace.xs    # Workspace configuration
+├── table/
+├── function/
+└── api/
 ```
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xano/developer-mcp",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "MCP server and library for Xano development - XanoScript validation, Meta API, Run API, and CLI documentation",
   "type": "module",
   "main": "dist/lib.js",