@dboio/cli 0.11.3 → 0.13.2

package/plugins/claude/dbo/docs/_audit_required/dbo-api-syntax.md

@@ -0,0 +1,1487 @@
+# dbo.io API Reference
+------------
+
+DBO.io is a database-driven application framework where all content, configuration, and assets are stored in a relational database and accessed via REST API endpoints. This document provides a comprehensive reference for interacting with the DBO.io API.
+
+## Token Architecture
+
+**System Template Tokens**: DBO uses `<#_` prefix for built-in template tokens in the re-architected system.
+
+- ✅ **Preferred (system tokens)**: `<#_embed>`, `<#_header>`, `<#_footer>`, `<#_row>`, `<#_empty>`, `<#_cell>`, `<#_prompt>`, `<#_shared>`, `<#_noresult>`, `<#_rowdelimiter>`, `<#_celldelimiter>`, `<#_value>`
+- ⚠️ **Alternative (still supported)**: `<#embed>`, `<#header>`, `<#footer>`, `<#row>`, `<#cell>`, `<#shared>`, `<#empty>`, `<#summary>`, etc.
+- ❌ **Legacy**: `<EmbedToken>` (demoted, but still works)
+
+**Complete list of standard output template tags**: `html`, `prompt`, `shared`, `header`, `row`, `cell`, `summary`, `footer`, `noresult`, `empty`, `rowdelimiter`, `celldelimiter`, `value`
+
+**User-Defined Tokens**: Custom tokens do NOT use the underscore prefix.
+
+- ✅ **User-defined**: `<#reference>`, `<#myCustomToken>`, `<#anything>`
+- These use `<#name>` syntax (without underscore)
+
+**Best Practice**:
+- Use `<#_` prefix for DBO system tokens (embed, header, footer, row, cell, etc.)
+- Use `<#` prefix (no underscore) for your custom user-defined tokens
+- Both `#` and `#_` prefixes are supported by output, input, and email template parsers
+- Message templates only support the `#_` prefix
+- Legacy syntax continues to work for backward compatibility
+
+## Core Concepts
+
+### Identifiers
+
+Every record in DBO has two types of identifiers:
+
+- **RowID** - Numeric database primary key (e.g., `10296`)
+  - Sequential integer assigned by the database
+  - May change across environment migrations
+  - Used interchangeably with RowUID in API calls
+
+- **RowUID** - Universal unique identifier (e.g., `albain3dwkofbhnd1qtd1q`)
+  - Alphanumeric string (22 characters)
+  - **Stable across environments** - does not change during migrations
+  - Preferred for deployment scripts and cross-environment references
+
+**Important**: `RowID:` and `RowUID:` syntax are **freely interchangeable** in API calls. Use `RowUID:` with alphanumeric UIDs for stable cross-environment deployments.
+
+### Entity-Column Structure
+
+All data operations use the `entity.ColumnName` format:
+
+```
+column:entity.ColumnName
+       ↑      ↑
+       |      └─ Physical column name in the database table
+       └─ Entity (table) name
+```
+
+**Common Entities:**
+- `content` - Text/code content (CSS, JS, HTML, JSON)
+- `media` - File references and binary data
+- `extension` - Extension/module code and documentation
+- `user` - User accounts and authentication
+- `app` - Application definitions
+- `site` - Site/domain configuration
+- `output` - Query definitions and data views
+- `entity_column` - Database schema definitions
+
+---
+
+## Authentication
+_______________________________________________________
+
+### URL
+`/api/authenticate`
+
+Authentication URL for obtaining a session. Authentication parameters can also be submitted with any request - this URL is optional but provides a direct response from the server.
+
+### Identity Parameters
+
+Users can authenticate using username, email, or phone number as their identity.
+
+- #### `_username` or `_un` [string]
+  - Username from `user.Username` column
+  - Can be passed at URL level
+  - Example: `?_username=john` or `?_un=john`
+
+- #### `_email` or `_em` [string]
+  - Email from `user.Email` column
+  - Alternative identity method to username
+  - Example: `?_email=john@example.com` or `?_em=john@example.com`
+
+- #### `_phonenumber` or `_pn` [string]
+  - Phone number from `user.PhoneNumber` column
+  - Alternative identity method to username/email
+  - Example: `?_phonenumber=+15551234567` or `?_pn=+15551234567`
+
+### Credential Parameters
+
+- #### `_password` or `_pw` [string]
+  - Password from `user.Password` column
+  - Can be passed at URL level
+  - Example: `?_password=mySecurePassword` or `?_pw=mySecurePassword`
+
+- #### `_passkey` or `_pk` [string]
+  - Alternative authentication using `user.PassKey`
+  - Username/email/phone and PassKey can be used together for sign in
+  - PassKey value automatically updates after each use
+  - More secure than password for API access
+
+### Session Parameters
+
+- #### `_logout` or `_lo` [boolean]
+  - Set to `true` to log out through URL bar
+  - Logout is processed first when combined with other parameters
+  - Example: `?_logout=true` or `?_lo=true`
+
+- #### `_security_log` [boolean]
+  - Enable security logging for debugging
+  - Used with development tools like Glimpse
+
+### SSO (Single Sign-On)
+
+DBO.io supports SSO via HTTP Headers. When configured:
+- The `SSO_IntegrationMethod` app setting is set to `HTTPHeaders`
+- `SSO_AuthenticationPathRegex` defines which request paths trigger SSO
+- `SSO_UsernameField` and `SSO_EmailField` specify which HTTP headers contain the identity
+- If the user does not exist in the system, they are auto-created on first SSO login
+
+### Impersonation
+
+- #### `_as` [integer]
+  - Impersonate another user by `user.UserID`
+  - Requires corresponding access record in security table
+  - Example: `?_as=12345`
+
+- #### `_as_cookie` [boolean]
+  - Used with impersonation to retain UserID in cookies
+  - Preserves impersonation across subsequent requests
+  - Example: `?_as=12345&_as_cookie=true`
+
+### Sample Code (cURL)
+
+```bash
+# Authenticate and save session cookie
+curl --cookie-jar .cookies \
+  --data-urlencode "_username=user@example.com" \
+  --data-urlencode "_password=myPassword" \
+  https://example.dbo.io/api/authenticate
+
+# Use session cookie for subsequent requests
+curl -b .cookies https://example.dbo.io/api/content/myContentUID
+```
+
+---
+
+## Input API (CRUD Operations)
+_______________________________________________________
+
+### URL
+`/api/input/submit`
+
+Main endpoint for creating, updating, and deleting records.
+
+### Request Format
+
+All input operations follow this pattern:
+
+```
+[RowUID|RowID]:identifier;column:entity.ColumnName[@file|=value]
+```
+
+**Components:**
+- `RowUID:` or `RowID:` - Record identifier type (interchangeable)
+- `identifier` - Alphanumeric UID or numeric ID
+- `;` - Separator between identifier and column specification
+- `column:entity.ColumnName` - Target column in entity table
+- `@file` - Use file contents as value (for deploying code/content)
+- `=value` - Direct value assignment (for metadata/simple values)
+
+### Add (Create New Record)
+
+```
+RowID:addkey;column:entity.Column=value
+```
+
+**Sample Code:**
+
+```bash
+# Add new user
+curl -K config.curl \
+  --data-urlencode "RowID:add1;column:user.FirstName=John" \
+  --data-urlencode "RowID:add1;column:user.LastName=Doe" \
+  --data-urlencode "RowID:add1;column:user.Email=john@example.com" \
+  --data-urlencode "_confirm=true" \
+  https://example.dbo.io/api/input/submit
+```
+
+- #### `addkey` [string]
+  - Unique key for this add operation
+  - Multiple columns can share the same addkey to create a single record
+  - Example: `RowID:add1`, `RowID:add2`, `RowID:addUser123`
+
+### Edit (Update Existing Record)
+
+```
+RowID:identifier;column:entity.Column=value
+RowUID:uid;column:entity.Column=value
+```
+
+**Sample Code:**
+
+```bash
+# Update user by numeric ID
+curl -K config.curl \
+  --data-urlencode "RowID:10065;column:user.FirstName=Jane" \
+  --data-urlencode "_confirm=true" \
+  https://example.dbo.io/api/input/submit
+
+# Update content by UID (from file)
+curl -K config.curl \
+  --data-urlencode "RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/colors.css" \
+  --data-urlencode "_confirm=true" \
+  https://example.dbo.io/api/input/submit
+```
+
+- #### File Upload Syntax `@filepath`
+  - Prefix with `@` to upload file contents as column value
+  - Used for text content (CSS, JS, HTML, markdown)
+  - File path is relative to curl execution directory
+  - Example: `column:content.Content@local/file.css`
+
+- #### Direct Value Syntax `=value`
+  - Use `=` for direct value assignment
+  - Used for simple strings, numbers, metadata
+  - Example: `column:user.FirstName=Jane`
+
+### Delete (Remove Record)
+
+```
+RowID:delidentifier;entity:entity=true
+```
+
+**Sample Code:**
+
+```bash
+# Delete user by ID
+curl -K config.curl \
+  --data-urlencode "RowID:del10062;entity:user=true" \
+  --data-urlencode "_confirm=true" \
+  https://example.dbo.io/api/input/submit
+```
+
+- #### `delidentifier` [string]
+  - Prefix identifier with `del` to indicate deletion
+  - Example: `RowID:del123`, `RowUID:delmyUIDstring`
+
+- #### `entity:entity=true` [boolean]
+  - Specifies which entity the record belongs to
+  - Must be set to `true` for deletion to execute
+  - Example: `entity:user=true`
+
+### Global Parameters
+
+- #### `_confirm` [boolean]
+  - Default is `false` (validation only)
+  - Set to `true` for changes to persist in database
+  - Without `_confirm=true`, DBO only validates the request
+  - Example: `_confirm=true`
+
+- #### `_transactional` [boolean]
+  - Controls transaction behavior
+  - Default behavior varies by operation
+  - Set to `false` to disable transactional processing
+
+- #### `_input_field_delimiter` [string]
+  - Allows adaptation for different languages/environments
+  - Changes the field delimiter from default
+  - Used for database compatibility across regions
+
+- #### `_input_descriptor_delimiter` [string]
+  - Allows adaptation for different languages/environments
+  - Changes the descriptor delimiter from default
+  - Used for database compatibility across regions
+
+- #### `_login` [boolean]
+  - Auto-login a user that is created through input submission
+  - Only triggers when exactly one user entity is being added in the submission
+  - Example: `_login=true`
+
+- #### `_pk_override` [boolean]
+  - Allow explicit primary key values on insert operations
+  - Bypasses auto-increment behavior
+  - Example: `_pk_override=1`
+
+### Sample Code (Operator Deployment)
+
+```javascript
+// From package.json - Deploy CSS
+"css:colors": "npm run minify:colors.css && curl -K config-data.curl --data-urlencode RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@assets/css/colors.css"
+
+// From package.json - Deploy JavaScript
+"js:app": "npm run minify:app.js && curl -K config-data.curl --data-urlencode RowUID:rncjivlghu65bmkbjnxynq;column:content.Content@assets/js/app.js"
+
+// From package.json - Deploy Documentation
+"doc:colors": "curl -K config-data.curl --data-urlencode RowUID:l2uv2gu8gu6ziyluuncv0w;column:extension.Text@docs/colors.md"
+```
+
+---
+
+## Output API (Query Data)
+_______________________________________________________
+
+DBO provides three types of output methods for querying data:
+
+1. **Custom Output** - Complex queries with custom SQL and filtering
+2. **Simple Output (Output by Entity)** - Direct entity queries
+3. **SQL Output** - Outputs with CustomSQL
+
+### Custom Output
+
+#### URL
+```
+/api/output/{output.UID}
+/api/o/{output.UID}              (short form)
+```
+
+Access predefined output queries by their UID.
+
+#### Target Reference
+- `output.UID` - The UID of the output definition
+
+#### Column References
+- `output_value.UID` - Column identifier by UID
+- `output_value.Shortname` - Column identifier by shortname
+
+#### Sample Code
+
+```bash
+# Fetch custom output as HTML
+curl -b .cookies \
+  "https://example.dbo.io/api/output/qfkyyp2vxeaggdeo7dwbig?_format=html"
+
+# Fetch with filter
+curl -b .cookies \
+  "https://example.dbo.io/api/output/myOutputUID?_filter@FirstName=John&_format=json"
+```
+
+### Simple Output (Output by Entity)
+
+#### URL
+```
+/api/output/entity/{entity.UID}
+/api/output/entity/{entity.UID}/{RowID}
+/api/o/e/{entity.UID}                    (short form)
+/api/o/e/{entity.UID}/{RowID}            (short form)
+/api/output/e/{entity.UID}               (medium form)
+/api/o/entity/{entity.UID}               (medium form)
+```
+
+Query data directly from an entity without a predefined output.
+
+#### Sample Code
+
+```bash
+# Get all users as HTML
+curl -b .cookies \
+  "https://example.dbo.io/api/output/entity/user?_format=html"
+
+# Get specific user record
+curl -b .cookies \
+  "https://example.dbo.io/api/output/entity/user/10296?_format=json"
+
+# Filter users by first name
+curl -b .cookies \
+  "https://example.dbo.io/api/output/entity/user?_filter@FirstName=John&_format=json"
+```
+
+### Embed Tokens
+
+Outputs can be embedded in content using special tokens:
+
+```html
+<!-- Preferred syntax (new architecture) -->
+<#_embed url="/api/output/target" hide="true" preload="true" >
+
+<!-- Alternative syntax (still supported) -->
+<#embed url="/api/output/target" hide="true" preload="true" >
+
+<!-- Legacy syntax (demoted, but still works) -->
+<EmbedToken url="/api/output/myOutputUID" hide="true" preload="true" column="reference"/>
+```
+
+**Note**: The `<#_` prefix is the preferred architecture. While `<#embed` and `<EmbedToken>` continue to work for legacy support, new implementations should use `<#_embed>`.
+
+- #### `hide` [boolean]
+  - When `true`, output is hidden but data is still available for token references
+  - Allows using embedded data without displaying the table
+  - Default is `false`
+
+- #### `preload` [boolean]
+  - When `true`, loads data before master template tokens are processed
+  - Allows using embedded data in master template
+  - Default is `false`
+
+- #### `column` [string]
+  - Comma-separated list of columns to display
+  - Limits output to specified columns only
+  - Example: `column="FirstName,LastName,Email"`
+
+- #### `payload` [boolean]
+  - When `true`, embed result is included in the API response payload
+  - Example: `payload="true"`
+
+- #### `secure` [boolean]
+  - When `true`, security checks are applied to the embedded output
+  - Example: `secure="true"`
+
+- #### `execute` [boolean]
+  - Controls whether the embed is executed
+  - Set to `false` to skip execution
+  - Example: `execute="false"`
+
+### Meta Output
+
+#### URL
+```
+/api/output/meta/entity/{entity.UID}
+/api/output/meta/column/{entityColumn.UID}
+```
+
+Retrieve metadata about entities and columns.
+
+```bash
+# Get entity metadata
+curl -b .cookies \
+  "https://example.dbo.io/api/output/meta/entity/userEntityUID"
+
+# Get column metadata
+curl -b .cookies \
+  "https://example.dbo.io/api/output/meta/column/firstNameColumnUID"
+```
+
+---
+
+## Data Tokens
+_______________________________________________________
+
+DBO uses a token system in templates for dynamic content. Tokens follow this format:
+
+```
+#{tokenType$target@reference:modifiers!default;comment}
+```
+
+### Value Tokens
+
+- #### `#{value@reference}` [token]
+  - Get value from a column
+  - Reference can be column UID, shortname, or physical name
+  - Example: `#{value@FirstName}`, `#{value@user.Email}`
+
+### ID/UID Tokens
+
+- #### `#{id@table}` [token]
+  - Primary key ID token for row
+  - If output contains multiple tables, multiple IDs returned
+  - Reference not required if only one ID column present
+  - Example: `#{id}`, `#{id@user}`
+
+- #### `#{uid@table}` [token]
+  - UID token for row
+  - Based on entity_column.PhysicalName of UID
+  - Example: `#{uid}`, `#{uid@content}`
+
+- #### `#{title@reference}` [token]
+  - Title/label token for columns
+  - Returns the display title of a column
+  - Example: `#{title@FirstName}` returns "First Name"
+
+- #### `#{entity@reference}` [token]
+  - Entity UID token for referenced table columns
+  - Example: `#{entity@user}`
+
+- #### `#{column@reference}` [token]
+  - Column UID token for referenced table columns
+  - Example: `#{column@FirstName}`
+
+### Row Count Tokens
+
+- #### `#{RowCount}` [token]
+  - Total number of rows in query
+  - Ignores paging, maxrows, and rows parameters
+  - Example: `#{RowCount}` returns `150`
+
+- #### `#{RowNumber}` [token]
+  - Row number in output
+  - Can only be used at template level
+  - Sequential numbering of rows
+  - Example: `#{RowNumber}` returns `1`, `2`, `3`...
+
+- #### `#{ReturnedRowCount}` [token]
+  - Total rows returned to client
+  - Considers paging, maxrows, and rows parameters
+  - Example: With pagination showing 10 per page, returns `10`
+
+- #### `#{ReturnedRowNumber}` [token]
+  - Row number within returned set
+  - Similar to RowNumber but for paginated results
+
+### Meta Tokens
+
+- #### `#{output@column}` [token]
+  - Meta token for gathering information about an output
+  - Currently accepts UID and Name columns
+  - Example: `#{output@Name}` returns output name
+
+### Request Tokens
+
+- #### `#{request@key}` [token]
+  - Access request parameters
+  - Example: `#{request@EntityUID}`, `#{request@Domain}`
+
+- #### `#{CurrentUser@reference}` [token]
+  - Current user information
+  - Affected by impersonation (`_as` parameter)
+  - Example: `#{CurrentUser@UserID}`, `#{CurrentUser@FirstName}`
+
+- #### `#{LoggedInUser@reference}` [token]
+  - Original logged-in user information
+  - Not affected by impersonation
+  - Example: `#{LoggedInUser@UserID}`
+
+- #### `#{site@reference}` [token]
+  - Current site information
+  - Example: `#{site@SiteID}`, `#{site@Domain}`
+
+- #### `#{request_meta@reference}` [token]
+  - Request metadata
+  - Available references: Domain, Protocol, Referrer, Port, Method, UserAgent
+  - Example: `#{request_meta@Domain}`, `#{request_meta@Protocol}`
+
+### Session Tokens
+
+- #### `#{session@variable}` [token]
+  - Access session-stored values
+  - Example: `#{session@userid}`, `#{session@uid}`
+
+### Data Source & Connection Tokens (v.9.47+)
+
+- #### `#{data_source@physicalname}` [token]
+  - Physical name of the current data source
+  - Example: `#{data_source@physicalname}`
+
+- #### `#{instance_connectionstring@reference}` [token]
+  - Instance connection string components
+  - Available references: `server`, `port`
+  - Example: `#{instance_connectionstring@server}`
+
+- #### `#{control_connectionstring@reference}` [token]
+  - Control connection string components
+  - Available references: `server`, `port`
+  - Example: `#{control_connectionstring@server}`
+
+### Token Modifiers
+
+Modifiers change how token values are processed:
+
+- #### `:cached` [modifier]
+  - Uses cached value
+  - Example: `#{value@RequestPathSecondary:cached}`
+
+- #### `:raw` [modifier]
+  - Returns unprocessed value
+  - Example: `#{value@Description:raw}`
+
+- #### `:decrypt` [modifier]
+  - Decrypts encrypted value
+  - Example: `#{value@Password:decrypt}`
+
+- #### `:email_decrypt` [modifier]
+  - Decrypts email-encrypted value
+  - Example: `#{value@Email:email_decrypt}`
+
+- #### `:truncate` [modifier]
+  - Truncates long text
+  - Example: `#{value@Description:truncate}`
+
+- #### `:escape_json` [modifier] (v.9.49+)
+  - Escapes value for safe inclusion in JSON strings
+  - Example: `#{value@Description:escape_json}`
+
+- #### `:format` [modifier]
+  - Apply format string to value (e.g., datetime formats)
+  - Example: `#{value@_CreatedOn:c1}` (custom datetime format)
+
+- #### `:escape_html` [modifier]
+  - Escapes HTML characters for safe display
+  - Example: `#{value@UserInput:escape_html}`
+
+### Token Processing Order
+
+Tokens are processed in this order (important for nested tokens):
+
+1. User Tokens
+2. Request Tokens (at embeds first)
+3. Request Meta Tokens
+4. Site Tokens
+5. Cached Value Tokens (at embeds first)
+6. Display Tokens
+
+**Example:**
+```
+This works:
+#{value@RequestPathSecondary:cached!#{request@EntityUID!}}
+
+This doesn't:
+#{request@EntityUID!#{value@RequestPathPrimary:cached}}
+```
+
+---
+
+## URL Parameters & Modifiers
+_______________________________________________________
+
+### Filter Parameters
+
+- #### `_filter` [parameter]
+  - Filter output results
+  - Syntax: `_filter$target@reference:modifiers=value`
+  - Multiple filters can be combined with `&`
+  - Example: `?_filter@FirstName=John&_filter@LastName=Doe`
+
+#### Filter Modifiers
+
+**Logic Operators:**
+- `and` - All conditions must match
+- `or` - Any condition can match (default)
+
+**Inclusion:**
+- `include` - Include matching records (default)
+- `exclude` - Exclude matching records
+
+**Matching:**
+- `exact` - Exact match (default)
+- `contains` - Contains substring
+- `startswith` - Starts with value
+- `endswith` - Ends with value
+
+**Comparison:**
+- `GreaterThan` - Value greater than filter
+- `GreaterThanOrEqualTo` - Value >= filter
+- `LessThan` - Value less than filter
+- `LessThanOrEqualTo` - Value <= filter
+
+**Shorthand Syntax:**
+- `*=` - Contains (e.g., `_filter@FirstName*=ohn`)
+- `^=` - Starts with (e.g., `_filter@FirstName^=Jo`)
+- `$=` - Ends with (e.g., `_filter@FirstName$=hn`)
+- `!=` - NOT / negation (e.g., `_filter@FirstName!=John`)
+
+**Special Values:**
+- `Null` - Filter for null values
+- `_any` - Ignore filter default value (treat as no filter)
+- `CurrentUserID` - Use current user's ID
+- `LoggedInUserID` - Use the logged-in user's ID (not affected by impersonation)
+- `CurrentSiteID` - Use current site's ID
+- `IpAddress` - Use the client's IP address
+- `SessionUID` - Use the current session UID
+- `RequestPath` - Use current request path
+- `Now`, `Today`, `Yesterday` - Date-based filters
+- `ThisWeek`, `LastWeek`, `ThisMonth`, `LastMonth` - Relative dates
+- `ThisQuarter`, `LastQuarter`, `ThisYear`, `LastYear` - Relative dates
+
+**Sample Code:**
+
+```bash
+# Filter users by first name containing "John"
+curl "https://example.dbo.io/api/output/entity/user?_filter@FirstName:contains=John"
+
+# Filter by multiple conditions (OR)
+curl "https://example.dbo.io/api/output/entity/user?_filter@FirstName=John&_filter@FirstName=Jane"
+
+# Filter with AND logic
+curl "https://example.dbo.io/api/output/entity/user?_filter@FirstName:and=John&_filter@Active:and=true"
+
+# Filter for current user's records
+curl "https://example.dbo.io/api/output/entity/content?_filter@UserID=CurrentUserID"
+```
+
+### Format Parameters
+
+- #### `_format` [parameter]
+  - Specify output format
+  - Syntax: `_format$target=format`
+  - URL level overrides all other format settings
+  - Example: `?_format=json`
+
+#### Available Formats
+
+- `html` - HTML output (default for browser requests)
+- `json` - JSON output
+- `json_raw` - Raw JSON output (no template rendering, returns data rows directly)
+- `json_indented` - Indented/pretty-printed JSON output
+- `xml` - XML output
+- `csv` - CSV output
+- `txt` - Plain text output
+- `pdf` - PDF output (requires size modifier, e.g., `pdf,letter`)
+
+**Sample Code:**
+
+```bash
+# Get users as JSON
+curl "https://example.dbo.io/api/output/entity/user?_format=json"
+
+# Get raw JSON data (no template)
+curl "https://example.dbo.io/api/output/myOutputUID?_template=json_raw"
+
+# Get as CSV
+curl "https://example.dbo.io/api/output/entity/user?_format=csv"
+
+# Get as PDF (letter size)
+curl "https://example.dbo.io/api/output/entity/user?_format=pdf,letter"
+```
+
+- #### `_format_values` [boolean]
+  - Enable value formatting in `json_raw` output
+  - When `true`, values are formatted according to their column format settings
+  - Example: `?_format_values=true`
+
+- #### `_escape_html` [boolean]
+  - Control HTML escaping of data values
+  - Set to `false` to disable HTML escaping
+  - Example: `?_escape_html=false`
+
+- #### `_mime` [string]
+  - Override the MIME/content type of the response
+  - Example: `?_mime=application/json`
+
+### Template Parameters
+
+- #### `_template` [parameter]
+  - Assign custom template to output
+  - Syntax: `_template$target=value`
+  - URL level (targeted) overrides all other template settings
+  - Example: `?_template=myCustomTemplate`
+
+#### Template Structure
+
+```html
+<#html>
+  <#UserDefined></#UserDefined>
+  <#header></#header>
+  <#shared></#shared>
+  <#row></#row>
+  <#footer></#footer>
+  <#empty></#empty>
+</#html>
+```
+
+**Preferred template architecture** uses `<#_` prefix:
+
+```html
+<#_html>
+  <#_prompt></#_prompt>
+  <#_header>
+    <#_cell>#{title@FirstName}</#_cell>
+    <#_cell>#{title@LastName}</#_cell>
+  </#_header>
+  <#_shared></#_shared>
+  <#_row>
+    <#_cell>#{value@FirstName}</#_cell>
+    <#_cell>#{value@LastName}</#_cell>
+  </#_row>
+  <#_rowdelimiter><br/></#_rowdelimiter>
+  <#_footer></#_footer>
+  <#_empty></#_empty>
+  <#_noresult></#_noresult>
+  <#UserDefined></#UserDefined>
+</#_html>
+```
+
+- #### `<#_header>` or `<#header>` [template section]
+  - Rendered once at the beginning of output
+  - Use for table headers, titles, etc.
+
+- #### `<#_row>` or `<#row>` [template section]
+  - Rendered for each record in output
+  - Use data tokens here: `#{value@FirstName}`
+
+- #### `<#_row.reference>` [template section] (v.9.47+)
+  - Row template with a reference qualifier for conditional rendering
+  - Example: `<#_row.active>` renders only for rows matching the reference
+
+- #### `<#_cell>` or `<#cell>` [template section]
+  - Cell-level rendering within rows and headers
+  - Use for per-column formatting
+
+- #### `<#_footer>` or `<#footer>` [template section]
+  - Rendered once after all rows
+  - Use for totals, summaries, etc.
+  - **Note**: `<#summary>` is demoted but still works (use `<#_footer>` instead)
+
+- #### `<#_empty>` or `<#empty>` [template section]
+  - Rendered when no records found
+  - Use for "No results" messages
+
+- #### `<#_noresult>` or `<#noresult>` [template section]
+  - Rendered when query returns no results
+  - Similar to empty but specifically for query result sets
+
+- #### `<#_prompt>` or `<#prompt>` [template section]
+  - Prompt/input section rendered before the output data
+
+- #### `<#_shared>` or `<#shared>` [template section]
+  - Shared content accessible across sections
+  - Values are shared if they have the same value for all rows
+
+- #### `<#_rowdelimiter>` or `<#rowdelimiter>` [template section]
+  - Content rendered between rows as a delimiter/separator
+
+- #### `<#_celldelimiter>` or `<#celldelimiter>` [template section]
+  - Content rendered between cells as a delimiter/separator
+
+- #### `<#_value>` or `<#value>` [template section] (v.9.47+)
+  - Value template tag for output rendering
+  - Supports column targeting: `<#_value.column_name>`
+
+### User-Defined Template Tokens
+
+```html
+<!-- User-defined tokens do NOT use underscore prefix -->
+<#reference></#reference>
+<#reference|value></#reference>
+<#reference|notnull></#reference>
+```
+
+- User-defined tokens use `<#name>` syntax (no underscore)
+- System tokens use `<#_name>` syntax (with underscore)
+- Conditional rendering based on value presence
+- `|value` renders if value exists
+- `|notnull` renders if value is not null
+
+### Paging Parameters
+
+- #### `_limit` [parameter]
+  - Maximum rows to return (preferred over `_maxrows`)
+  - Supports range syntax: `_limit=start-end`
+  - Works with `_page` for pagination: `_limit=10&_page=3`
+  - Example: `?_limit=30`, `?_limit=10-30`
+
+- #### `_rowcount` [boolean]
+  - Include total row count in response
+  - Default is `true`
+  - Set to `false` for improved performance on large datasets
+  - Example: `?_rowcount=false`
+
+- #### `_rows` [parameter]
+  - Display range of rows
+  - Syntax: `_rows=start-end`
+  - Deprecated: prefer `_limit` with range syntax
+  - Example: `?_rows=1-10` (first 10 rows), `?_rows=11-20` (next 10)
+
+- #### `_page` [parameter]
+  - Page number for pagination
+  - Works with `_limit` or `_RowsPerPage`
+  - Example: `?_limit=10&_page=3`, `?_page=2&_RowsPerPage=25`
+
+- #### `_RowsPerPage` [parameter]
+  - Number of rows per page
+  - Works with `_page` parameter
+  - Overrides `_maxrows` setting
+  - Deprecated: prefer `_limit` with `_page`
+  - Example: `?_RowsPerPage=50`
+
+- #### `_maxrows` [parameter]
+  - Maximum rows to display
+  - Syntax: `_maxrows=count`
+  - Deprecated: prefer `_limit`
+  - Example: `?_maxrows=100`
+
+**Sample Code:**
+
+```bash
+# Limit to 30 rows
+curl "https://example.dbo.io/api/output/entity/user?_limit=30"
+
+# Range: rows 10 through 30
+curl "https://example.dbo.io/api/output/entity/user?_limit=10-30"
+
+# Page 3 with 10 rows per page
+curl "https://example.dbo.io/api/output/entity/user?_limit=10&_page=3"
+
+# Disable row count for performance
+curl "https://example.dbo.io/api/output/entity/user?_limit=50&_rowcount=false"
+
+# Legacy: get first 10 rows
+curl "https://example.dbo.io/api/output/entity/user?_rows=1-10"
+
+# Legacy: limit to 50 rows maximum
+curl "https://example.dbo.io/api/output/entity/user?_maxrows=50"
+```
+
+### Sort Parameters
+
+- #### `_sort` [parameter]
+  - Sort output by column
+  - Syntax: `_sort=ColumnName:direction` or `_sort$target@reference:modifier`
+  - Multiple sorts: comma-separated `_sort=Col1:ASC,Col2:DESC` or multiple `_sort` parameters
+  - Direction defaults to ascending when omitted
+  - Example: `?_sort=LastName:ASC`, `?_sort=LastName:ASC,FirstName:ASC`
+
+#### Sort Modifiers
+
+- `ASC` / `asc` - Ascending order (default)
+- `DESC` / `desc` - Descending order
+
+**Sample Code:**
+
+```bash
+# Sort by last name ascending
+curl "https://example.dbo.io/api/output/entity/user?_sort=LastName:ASC"
+
+# Sort by creation date descending (newest first)
+curl "https://example.dbo.io/api/output/entity/content?_sort=_Created:DESC"
+
+# Multiple sort columns (comma-separated)
+curl "https://example.dbo.io/api/output/entity/user?_sort=LastName:ASC,FirstName:ASC"
+
+# Multiple sort columns (separate parameters)
+curl "https://example.dbo.io/api/output/entity/user?_sort=LastName:ASC&_sort=FirstName:ASC"
+
+# Targeted sort (scoped to specific output)
+curl "https://example.dbo.io/api/output/myUID?_sort$outputTarget@LastName:asc"
+```
+
+### Search Parameters
+
+- #### `_search` [parameter]
+  - Full-text search across output columns
+  - Syntax: `_search$target@reference=value`
+  - Example: `?_search@FirstName,LastName=John`
+
+### Debug & Profiling Parameters
+
+- #### `_debug` [boolean]
+  - Show debug information in output
+  - Displays embed tokens and parameters in HTML comments
+  - Example: `?_debug=true`
+
+- #### `_debug:sql` or `_debug_sql` [boolean]
+  - Show SQL queries in output without executing them
+  - Useful for troubleshooting custom outputs
+  - Example: `?_debug:sql=true`
+
+- #### `_debug:verbose` [boolean]
+  - Verbose debug output with additional detail
+  - Example: `?_debug:verbose=true`
+
+- #### `_debug:analysis` [boolean]
+  - Analysis debug output
+  - Example: `?_debug:analysis=true`
+
+#### Additional Debug Sub-Keys
+
+The `_debug` parameter supports many sub-keys for targeted debugging:
+
+`http_modules`, `instance`, `rewrites`, `cache`, `executable_contents`, `security`, `controllers`, `embeds`, `includes`, `contents`, `template_render`, `tokens`, `messages`, `media`, `request_stack`, `query_execution`, `query_building`
+
+Example: `?_debug:cache=true`, `?_debug:security=true`
+
+- #### `_profile` [boolean]
+  - Enable MiniProfiler output for performance profiling
+  - Example: `?_profile=true`
+
+### Display Control Parameters
+
+- #### `_display@key` [parameter]
+  - Control element display by showing or hiding template content tags
+  - Syntax: `_display@tagName=show|hide`
+  - Example: `?_display@sidebar=hide`, `?_display@filters=show`
+
+- #### `_empty_response_code` [integer]
+  - HTTP status code to return when output produces no results
+  - Example: `?_empty_response_code=404`
+
+- #### `_fallback_content` [parameter]
+  - Render a different content record when a specific HTTP status code is returned
+  - Syntax: `_fallback_content:statusCode=contentUID`
+  - Example: `?_fallback_content:404=myNotFoundContentUID`
+
+### Control Flags
+
+- #### `_strict` [boolean]
+  - Enable strict error mode
+  - Example: `?_strict=true`
+
+- #### `_confirm` [boolean]
+  - Confirmation flag for operations
+  - Example: `?_confirm=true`
+
+- #### `_no_transaction` [boolean]
+  - Disable transaction wrapping for the query
+  - Example: `?_no_transaction=true`
+
+- #### `_skip` [string]
+  - Skip execution phases (admin-only)
+  - Example: `?_skip=all`
+
+- #### `_include` [string]
+  - Include token for additional content inclusion
+  - Example: `?_include=value`
+
+- #### `_security` [string]
+  - Security filter enforcement
+  - Example: `?_security=value`
+
+---
+
+## Content API
+_______________________________________________________
+
+### URL
+```
+/api/content/{content.UID}
+/api/c/{content.UID}                                        (short form)
+/app/{app.Shortname}/{site.Shortname}/{content.Path}
+{control.domain.Domain}/{content.Path}
+```
+
+Access content records (HTML, CSS, JS, text) by UID or path. Also supports OPTIONS method for CORS preflight requests.
+
+### Sample Code
+
+```bash
+# Get content by UID
+curl -b .cookies \
+  "https://example.dbo.io/api/content/ykqucv0eb0ggjqgcncj6dq"
+
+# Get content by app path
+curl -b .cookies \
+  "https://example.dbo.io/app/operator/ui/master.html"
+```
+
+### Embed Content
+
+```html
+<!-- Preferred syntax -->
+<#_embed url="/api/content/target" hide="true" preload="true" >
+
+<!-- Alternative syntax (still supported) -->
+<#embed url="/api/content/target" hide="true" preload="true" >
+
+<!-- Legacy syntax (demoted) -->
+<EmbedToken url="/api/content/myContentUID" />
+```
+
+### Content Parameters
+
+- #### `_minify` [boolean]
+  - Enable/disable minification
+  - Default is `true` for CSS/JS content
+  - Example: `?_minify=false`
+
+- #### `_no_minify` [boolean]
+  - Alternative to disable minification
+  - Example: `?_no_minify=true`
+
+- #### `_format` [parameter]
+  - Specify content format
+  - Available: txt, json, html, xml, csv, pdf
+  - Example: `?_format=txt`
+
+### Content Tokens
+
+- #### `#{content@ColumnPhysicalName}` [token]
+  - Access content record columns
+  - Example: `#{content@Title}`, `#{content@Path}`
+
+### Display Modifiers
+
+```html
+<!-- User-defined display keys (no underscore) -->
+<@key:modifier;comment></@key>
+<@key></@key>
+```
+
+**Note**: Display modifiers use `<@key>` syntax where `key` is user-defined (no underscore prefix).
+
+- #### `_display@key` [parameter]
+  - Control element display
+  - Syntax: `_display@key:modifier=boolean`
+  - Available modifiers: `show` (default), `hide`
+
+---
+
+## Media API
+_______________________________________________________
+
+### URL
+```
+/api/media/{media.UID}                                               (by UID)
+/api/media/id/{media.MediaID}                                        (by numeric ID)
+/dir/{*path}                                                         (by directory path)
+/ext/{mediaServer.UID}/{rowId}                                       (external media server)
+/media/{app.Shortname}/{media.Ownership}/{media.Path}/{media.Filename}
+```
+
+Access and upload media files (images, fonts, documents, binaries).
+
+### Access Parameters
+
+- #### `_download` [boolean]
+  - When `true`, serves the file as a download attachment instead of inline
+  - Sets `Content-Disposition: attachment` header
+  - Example: `?_download=true`
+
+### Security
+
+- Media records with `Public=true` bypass security checks and are accessible without authentication
+- All other media requires `Execute` permission on the media entity
+
+### Sample Code (Access)
+
+```bash
+# Get media by UID
+curl -b .cookies \
+  "https://example.dbo.io/api/media/albain3dwkofbhnd1qtd1q"
+
+# Get media by path
+curl -b .cookies \
+  "https://example.dbo.io/media/operator/app/assets/gfx/logo.png"
+```
+
+### Sample Code (Upload)
+
+```bash
+# Upload new media file
+curl -K config-form.curl \
+  -F file=@local/path/image.jpg \
+  -F "RowID:add1;column:media.BinID=12345" \
+  -F "RowID:add1;column:media.AppID=67890" \
+  -F "RowID:add1;column:media.Ownership=app" \
+  -F "RowID:add1;column:media.Path=assets/images" \
+  -F "_confirm=true" \
+  https://example.dbo.io/api/input/submit
+
+# Update existing media file
+curl -K config-form.curl \
+  -F file=@local/path/updated-image.jpg \
+  -F "RowID:19782;column:media.Filename=image.jpg" \
+  -F "_confirm=true" \
+  https://example.dbo.io/api/input/submit
+```
+
+### Upload Parameters
+
+- #### `file` [File]
+  - The actual file being uploaded
+  - Use `-F file=@path` syntax for curl
+  - Example: `-F file=@assets/logo.png`
+
+- #### Media Columns
+
+All media uploads should specify these columns:
+
+- `media.BinID` - Binary container ID (required)
+- `media.AppID` - Application ID (required)
+- `media.Ownership` - Ownership type: `'app'`, `'user'`, or `'system'` (required)
+- `media.Path` - File path within ownership (required)
+- `media.Filename` - File name (auto-detected from file, optional)
+- `media.Extension` - File extension (auto-detected, optional)
+
+### Upload API
+
+#### URL
+```
+/api/upload/submit
+```
+
+Dedicated file upload endpoint (POST only). Requires `_confirm=true`.
+
+```bash
+# Upload via dedicated endpoint
+curl -X POST -K config-form.curl \
+  -F file=@local/path/image.jpg \
+  -F "AppID=67890" \
+  -F "Ownership=app" \
+  -F "Name=logo" \
+  -F "Path=assets/images" \
+  -F "_confirm=true" \
+  https://example.dbo.io/api/upload/submit
+```
+
+---
+
+## Message API
+_______________________________________________________
+
+### URL
+```
+/api/message/content/{content.UID}        (send message)
+/api/m/c/{content.UID}                    (short form)
+/api/message/c/{content.UID}              (medium form)
+/api/content/email/{content.UID}          (legacy email endpoint)
+/api/c/email/{content.UID}               (legacy email short form)
+/api/message/receive/{messageServer.UID}  (receive inbound messages)
+/api/m/r/{messageServer.UID}             (short form)
+```
+
+Send messages (email, SMS/MMS, chatbot) by referencing a content record that contains the message template. Requires `_confirm=true` to execute.
+
+### Message Types
+
+- **Email (SMTP)** - Traditional email with To, Cc, Bcc recipients via `ExternalMessage_Email`
+- **SMS/MMS (Twilio)** - Text messaging via Twilio integration via `ExternalMessage_Twilio`
+- **ChatBot** - AI chatbot conversations via `ExternalMessage_ChatBot` with OpenAI integration
+
+### Parameters
+
+- #### `_confirm` [boolean]
+  - Required. Must be `true` for message to be sent
+  - Without confirmation, message is validated but not sent
+
+- #### `ThreadID` [string]
+  - For chatbot messages, specifies the conversation thread
+  - Enables multi-turn conversations with history preservation
+  - Stored in `message_log` table
+
+- #### `security` [string]
+  - Embed attribute to control security checks
+  - Set to `"false"` to bypass security on message embeds
+  - Example: `<#_embed url="/api/message/content/uid" security="false" >`
+
+### ChatBot Features (v.9.49+)
+
+- **Function Calling**: Define tools in the message template for the chatbot to invoke. Functions are executed via content includes or output/content API calls.
+- **Conversation Threading**: Multi-turn conversations tracked by `ThreadID` in `message_log`
+- **Iteration Limits**: Configurable maximum conversation iterations (default 10)
+- **Halt Functions**: Functions marked with `chatbot_halt` attribute stop the conversation loop
+
+### Sample Code
+
+```bash
+# Send email message
+curl -b .cookies \
+  --data-urlencode "_confirm=true" \
+  "https://example.dbo.io/api/message/content/emailTemplateUID"
+
+# Send chatbot message with thread
+curl -b .cookies \
+  --data-urlencode "_confirm=true" \
+  --data-urlencode "ThreadID=conversation123" \
+  "https://example.dbo.io/api/m/c/chatbotTemplateUID"
+```
+
+### Email Template Syntax
+
+```html
+<#_email>
+  <#_from>sender@example.com</#_from>
+  <#_to>recipient@example.com</#_to>
+  <#_cc>cc@example.com</#_cc>
+  <#_bcc>bcc@example.com</#_bcc>
+  <#_subject>Email Subject</#_subject>
+  <#_html>
+    <p>HTML content with #{tokens}</p>
+  </#_html>
+  <#_plain>Plain text version</#_plain>
+</#_email>
+```
+
+### Receiving Messages
+
+```bash
+# Receive inbound message (e.g., Twilio webhook)
+curl -X POST \
+  "https://example.dbo.io/api/message/receive/twilioServerUID"
+```
+
+---
+
+## Cache API
+_______________________________________________________
+
+### URL
+```
+/api/cache/list       (list cached items)
+/api/cache/refresh    (refresh cache by key)
+```
+
+Manage the DBO.io cache. Used for debugging and cache invalidation.
+
+### Parameters
+
+- #### `_key` [string]
+  - Cache key to refresh (case-insensitive)
+  - Example: `?_key=content:myContentUID`
+
+- #### `_part` [string]
+  - Target specific cache partition
+
+- #### `_metadata` [boolean]
+  - When `true`, includes cache provider metadata in response
+  - Example: `?_metadata=true`
+
+### Sample Code
+
+```bash
+# List all cached items
+curl -b .cookies "https://example.dbo.io/api/cache/list"
+
+# Refresh a specific content cache
+curl -b .cookies "https://example.dbo.io/api/cache/refresh?_key=content:myContentUID"
+```
+
+---
+
+## Instance API
+_______________________________________________________
+
+### URL
+```
+/api/instance/export                    (export instance)
+/api/instance/build/{instance.UID}      (build instance)
+/api/instance/build?_instance_uid=UID   (alternative form)
+```
+
+Manage DBO.io instances. Requires `_confirm=true`. Supports offline/asynchronous execution.
+
+### Parameters
+
+- #### `_confirm` [boolean]
+  - Required for execution
+
+- #### `_instance_uid` [string]
+  - Alternative to URL parameter for specifying instance UID
+
+- #### `_callback_url` [string]
+  - URL to call when async operation completes
+
+### Sample Code
+
+```bash
+# Export instance
+curl -b .cookies \
+  --data-urlencode "_confirm=true" \
+  "https://example.dbo.io/api/instance/export"
+
+# Build instance
+curl -b .cookies \
+  --data-urlencode "_confirm=true" \
+  "https://example.dbo.io/api/instance/build/instanceUID"
+```
+
+---
+
+## Custom SQL Tokens
+_______________________________________________________
+
+For outputs with CustomSQL, special tokens are available:
+
+### Filter Value Tokens
+
+- #### `#{filter_value@output_value_filter.UID}` [token]
+  - Access filter values in CustomSQL
+  - Used in `output_value.CustomSQL` field
+  - Example: `#{filter_value@myFilterUID}`
+
+- #### `#{filter_value@output_value_filter.Shortname}` [token]
+  - Access filter by shortname
+  - Alternative to UID reference
+  - Example: `#{filter_value@userFilter}`
+
+### Join Tokens
+
+- #### `#{join@entity_column.UID}` [token]
+  - Define custom joins in SQL
+  - Used in `output_value_entity_column_rel.CustomSQL`
+  - Example: `#{join@userTableUID}`
+
+---
+
+## Aggregate Modifiers
+_______________________________________________________
+
+Available for token-based aggregation:
+
+- `Min` - Minimum value
+- `Max` - Maximum value
+- `Count` - Count of records
+- `Average` - Average value
+- `Sum` - Sum of values
+- `default` - Default aggregation
+
+**Example:**
+```
+#{value@Price:Sum}
+#{value@OrderID:Count}
+```
+
+---
+
+## Best Practices
+
+### For Deployment Scripts
+
+1. **Always use RowUID with alphanumeric UIDs** for cross-environment stability
+2. **Include `_confirm=true`** for changes to persist
+3. **Use `@filepath` syntax** for content uploads (CSS, JS, HTML)
+4. **Use `-F file=@` syntax** for media/binary uploads
+5. **Test in development** before deploying to production
+
+### For API Queries
+
+1. **Use filters** to limit result sets: `_filter@column=value`
+2. **Specify format** explicitly: `_format=json`
+3. **Implement pagination** for large datasets: `_page` and `_RowsPerPage`
+4. **Cache frequently accessed** content when possible
+5. **Use debug parameters** during development: `_debug=true`
+
+### For Templates
+
+1. **Escape user input** with `:escape_html` modifier
+2. **Check for null values** with conditional tokens
+3. **Use token processing order** correctly for nested tokens
+4. **Cache expensive operations** with `:cached` modifier
+5. **Provide empty state** templates with `<#empty>` section
+
+---
+
+## Error Handling
+
+### Common Error Responses
+
+- **401 Unauthorized** - Authentication required or failed
+- **403 Forbidden** - Insufficient permissions
+- **404 Not Found** - Record or endpoint not found
+- **422 Unprocessable Entity** - Validation failed (without `_confirm=true`)
+- **500 Internal Server Error** - Server-side error
+
+### Validation vs. Execution
+
+**Without `_confirm=true`:**
+- Request is validated only
+- No changes are made to database
+- Returns success if validation passes
+- Returns error details if validation fails
+
+**With `_confirm=true`:**
+- Request is validated and executed
+- Changes are committed to database
+- Returns success with updated record data
+- Returns error if execution fails
+
+---
+
+## URL Encoding Reference
+
+When using curl with `--data-urlencode`:
+
+```
+:  becomes  %3A    (colon)
+;  becomes  %3B    (semicolon)
+=  becomes  %3D    (equals)
+@  becomes  %40    (at symbol)
+!  becomes  %21    (exclamation)
+#  becomes  %23    (hash)
+```
+
+**Example:**
+```bash
+# Raw parameter:
+RowUID:albain3dwkofbhnd1qtd1q;column:content.Content@file.css
+
+# URL encoded:
+RowUID%3Aalbain3dwkofbhnd1qtd1q%3Bcolumn%3Acontent.Content%40file.css
+```
+
+---
+
+## Additional Resources
+
+- **Architecture Guide**: See [CLAUDE.md](../CLAUDE.md) for codebase architecture and development guidance
+- **Version History**: See [version.txt](../src/webapp-framework/version.txt) for release notes
+- **Context Migration**: See [README_ContextMigration.md](../src/dboioStandard/Web/README_ContextMigration.md) for .NET Core migration guide
+
+---
+
+*Current version: 0.9.51.0*