@dboio/cli 0.20.4 → 0.20.6

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

@@ -1,1487 +0,0 @@
-# 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*