@chaprola/mcp-server 1.6.3 → 1.7.0

package/dist/index.js

@@ -102,11 +102,11 @@ const server = new McpServer({
 - **Run programs:** chaprola_run (single execution), chaprola_run_each (per-record batch), chaprola_report (published reports)
 - **Email:** chaprola_email_send, chaprola_email_inbox, chaprola_email_read
 - **Web:** chaprola_search (Brave API), chaprola_fetch (URL → markdown)
-- **Schema:** chaprola_format (inspect fields), chaprola_alter (add/widen/rename/drop fields)
+- **Schema:** chaprola_format (inspect fields), chaprola_alter (add/widen/rename/drop fields — NON-DESTRUCTIVE for in-place schema edits). Re-imports now preserve and widen existing schemas automatically when targeting an existing file.
 - **Export:** chaprola_export (JSON or FHIR — full round-trip: FHIR in, process, FHIR out)
 - **Schedule:** chaprola_schedule (cron jobs for any endpoint)
 
-**The programming language** is small and focused — about 15 commands. Read chaprola://cookbook before writing source code. Common patterns: aggregation, filtering, scoring, report formatting. Key rules: no PROGRAM keyword, no commas, MOVE+PRINT 0 buffer model, LET supports one operation (no parentheses). Named parameters: PARAM.name reads URL query params as strings; LET x = PARAM.name converts to numeric. Named output positions: U.name instead of U1-U20.
+**The programming language** is small and focused — about 15 commands. Read chaprola://cookbook before writing source code. Common patterns: aggregation, filtering, scoring, report formatting. Key rules: no PROGRAM keyword, no commas, reports can use either the classic MOVE-to-U-buffer then PRINT 0 pattern or one-line PRINT concatenation, and LET supports one operation (no parentheses). Named parameters: PARAM.name reads URL query params as strings; LET x = PARAM.name converts to numeric. Named output positions: U.name instead of U1-U20.
 
 **Common misconceptions:**
 - "No JOINs" → Wrong. chaprola_query supports JOIN with hash and merge methods across files. Use chaprola_index to build indexes for fast lookups on join fields.
@@ -155,7 +155,7 @@ function readRef(filename) {
 server.resource("cookbook", "chaprola://cookbook", { description: "Chaprola language cookbook — syntax patterns, complete examples, and the import→compile→run workflow. READ THIS before writing any Chaprola source code.", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://cookbook", mimeType: "text/markdown", text: readRef("cookbook.md") }],
 }));
-server.resource("gotchas", "chaprola://gotchas", { description: "Common Chaprola mistakes — no parentheses in LET, no commas in PRINT, MOVE length must match field width, DEFINE names must not collide with fields. READ THIS before writing code.", mimeType: "text/markdown" }, async () => ({
+server.resource("gotchas", "chaprola://gotchas", { description: "Common Chaprola mistakes — no parentheses in LET, no commas in PRINT, DEFINE names must not collide with fields, always pass primary_format to compile. READ THIS before writing code.", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://gotchas", mimeType: "text/markdown", text: readRef("gotchas.md") }],
 }));
 server.resource("endpoints", "chaprola://endpoints", { description: "Chaprola API endpoint reference — all 40 endpoints with request/response shapes", mimeType: "text/markdown" }, async () => ({
@@ -174,6 +174,9 @@ server.resource("ref-import", "chaprola://ref/import", { description: "Import, e
 server.resource("ref-query", "chaprola://ref/query", { description: "Query, sort, index, merge, record CRUD — data operations", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/query", mimeType: "text/markdown", text: readRef("ref-query.md") }],
 }));
+server.resource("ref-schema", "chaprola://ref/schema", { description: "Schema operations — /format (inspect), /alter (widen/rename/add/drop fields). CRITICAL: Use /alter for schema changes, NOT /import.", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/schema", mimeType: "text/markdown", text: readRef("ref-schema.md") }],
+}));
 server.resource("ref-pivot", "chaprola://ref/pivot", { description: "Pivot tables (GROUP BY) — row, column, aggregate functions", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/pivot", mimeType: "text/markdown", text: readRef("ref-pivot.md") }],
 }));
@@ -195,9 +198,12 @@ server.resource("ref-email", "chaprola://ref/email", { description: "Email syste
 server.resource("ref-gotchas", "chaprola://ref/gotchas", { description: "Common Chaprola mistakes — language, API, and secondary file pitfalls", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/gotchas", mimeType: "text/markdown", text: readRef("ref-gotchas.md") }],
 }));
-server.resource("ref-auth", "chaprola://ref/auth", { description: "Authentication details — registration, login, BAA, MCP env vars", mimeType: "text/markdown" }, async () => ({
+server.resource("ref-auth", "chaprola://ref/auth", { description: "Authentication details — registration, login, BAA, cross-user sharing, MCP env vars", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://ref/auth", mimeType: "text/markdown", text: readRef("ref-auth.md") }],
 }));
+server.resource("ref-apps", "chaprola://ref/apps", { description: "Building apps on Chaprola — React/frontend architecture, site keys, single-owner vs multi-user, enterprise proxy pattern", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/apps", mimeType: "text/markdown", text: readRef("ref-apps.md") }],
+}));
 // --- MCP Prompts ---
 server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read this before writing any Chaprola source code.", async () => ({
     messages: [{
@@ -210,7 +216,7 @@ server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read
                     "- NO `PROGRAM` keyword — programs start directly with commands\n" +
                     "- NO commas anywhere — all arguments are space-separated\n" +
                     "- NO parentheses in LET — only `LET var = a OP b` (one operation)\n" +
-                    "- Output uses MOVE + PRINT 0 buffer model, NOT `PRINT field`\n" +
+                    "- Output can use classic MOVE + PRINT 0 buffers or one-line PRINT concatenation (`PRINT \"label\" + P.field + rec`)\n" +
                     "- Field addressing: P.fieldname (primary), S.fieldname (secondary)\n" +
                     "- Loop pattern: `LET rec = 1` → `SEEK rec` → `IF EOF GOTO end` → process → `LET rec = rec + 1` → `GOTO loop`\n\n" +
                     "## Minimal Example\n" +
@@ -219,10 +225,7 @@ server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read
                     "LET rec = 1\n" +
                     "100 SEEK rec\n" +
                     "    IF EOF GOTO 900\n" +
-                    "    MOVE BLANKS U.1 40\n" +
-                    "    MOVE P.name U.1 8\n" +
-                    "    MOVE P.value U.12 6\n" +
-                    "    PRINT 0\n" +
+                    "    PRINT P.name + \" — \" + P.value\n" +
                     "    LET rec = rec + 1\n" +
                     "    GOTO 100\n" +
                     "900 END\n" +
@@ -243,6 +246,10 @@ server.tool("chaprola_hello", "Health check — verify the Chaprola API is runni
     const res = await fetch(url);
     return textResult(res);
 });
+server.tool("chaprola_help", "Get the full Chaprola documentation bundle from POST /help. Call this before guessing when compile or run fails. No auth required.", {}, async () => {
+    const res = await publicFetch("POST", "/help", {});
+    return textResult(res);
+});
 server.tool("chaprola_register", "Register a new Chaprola account. Returns an API key — save it immediately", {
     username: z.string().describe("3-40 chars, alphanumeric + hyphens/underscores, starts with letter"),
     passcode: z.string().describe("16-128 characters. Use a long, unique passcode"),
@@ -277,8 +284,9 @@ server.tool("chaprola_report", "Run a published program and return output. No au
     project: z.string().describe("Project containing the program"),
     name: z.string().describe("Name of the published .PR file"),
     token: z.string().optional().describe("Action token (act_...) for writable reports. Required to persist WRITE/DELETE/QUERY operations. Provided when program was published with writable=true."),
-    params: z.record(z.union([z.string(), z.number()])).optional().describe("Parameters to inject before execution. Named params (e.g., {deck: \"kanji\", level: 3}) are read in programs via PARAM.name. Legacy R-variables (r1-r20) also supported. Use chaprola_report_params to discover what params a report accepts."),
-}, async ({ userid, project, name, token, params }) => {
+    params: z.string().optional().describe("JSON object of named params, e.g. {\"deck\": \"kanji\", \"level\": 3}. Named params are read in programs via PARAM.name. Legacy R-variables (r1-r20) also supported. Use chaprola_report_params to discover what params a report accepts."),
+}, async ({ userid, project, name, token, params: paramsStr }) => {
+    const params = typeof paramsStr === 'string' ? JSON.parse(paramsStr) : paramsStr;
     const urlParams = new URLSearchParams();
     urlParams.set("userid", userid);
     urlParams.set("project", project);
@@ -330,13 +338,14 @@ server.tool("chaprola_baa_status", "Check whether the authenticated user has sig
     return textResult(res);
 });
 // --- Import ---
-server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F + .DA). Sign BAA first if handling PHI", {
+server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F + .DA). If the target file already exists, Chaprola preserves the existing schema, widens matching fields as needed, keeps legacy fields as blanks, and appends new fields at the end. Use chaprola_alter for explicit in-place schema surgery. Sign BAA first if handling PHI", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
-    data: z.array(z.record(z.any())).describe("Array of flat JSON objects to import"),
+    data: z.string().describe("JSON array of record objects to import"),
     format: z.enum(["json", "fhir"]).optional().describe("Data format: json (default) or fhir"),
     expires_in_days: z.number().optional().describe("Days until data expires (default: 90)"),
-}, async ({ project, name, data, format, expires_in_days }) => withBaaCheck(async () => {
+}, async ({ project, name, data: dataStr, format, expires_in_days }) => withBaaCheck(async () => {
+    const data = typeof dataStr === 'string' ? JSON.parse(dataStr) : dataStr;
     const { username } = getCredentials();
     const body = { userid: username, project, name, data };
     if (format)
@@ -346,7 +355,7 @@ server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F
     const res = await authedFetch("/import", body);
     return textResult(res);
 }));
-server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large files (bypasses 6MB API Gateway limit)", {
+server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large files (bypasses 6MB API Gateway limit). The subsequent chaprola_import_process preserves and widens an existing schema automatically when importing into an existing file.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
 }, async ({ project, name }) => withBaaCheck(async () => {
@@ -354,7 +363,7 @@ server.tool("chaprola_import_url", "Get a presigned S3 upload URL for large file
     const res = await authedFetch("/import-url", { userid: username, project, name });
     return textResult(res);
 }));
-server.tool("chaprola_import_process", "Process a file previously uploaded to S3 via presigned URL. Generates .F + .DA files", {
+server.tool("chaprola_import_process", "Process a file previously uploaded to S3 via presigned URL. Generates .F + .DA files. If the target file already exists, the existing schema is preserved and widened automatically as needed.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("File name (without extension)"),
     format: z.enum(["json", "fhir"]).optional().describe("Data format: json (default) or fhir"),
@@ -366,10 +375,10 @@ server.tool("chaprola_import_process", "Process a file previously uploaded to S3
     const res = await authedFetch("/import-process", body);
     return textResult(res);
 }));
-server.tool("chaprola_import_download", "Import data directly from a public URL (CSV, TSV, JSON, NDJSON, Parquet, Excel). Optional AI-powered schema inference", {
+server.tool("chaprola_import_download", "Import data directly from a public URL (CSV, TSV, JSON, NDJSON, Parquet, Excel). Optional AI-powered schema inference.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Output file name (without extension)"),
-    url: z.string().url().describe("Public URL to download (http/https only)"),
+    url: z.string().describe("Public URL to download (http/https only)"),
     instructions: z.string().optional().describe("Natural language instructions for AI-powered field selection and transforms"),
     max_rows: z.number().optional().describe("Maximum rows to import (default: 5,000,000)"),
 }, async ({ project, name, url, instructions, max_rows }) => withBaaCheck(async () => {
@@ -404,12 +413,12 @@ server.tool("chaprola_list", "List files in a project with optional wildcard pat
     return textResult(res);
 }));
 // --- Compile ---
-server.tool("chaprola_compile", "Compile Chaprola source (.CS) to bytecode (.PR). READ chaprola://cookbook BEFORE writing source. Key syntax: no PROGRAM keyword (start with commands), no commas, MOVE+PRINT 0 buffer model (not PRINT field), SEEK for primary records, OPEN/READ/WRITE/CLOSE for secondary files, LET supports one operation (no parentheses), field addressing via P.field/S.field requires primary_format/secondary_format params.", {
+server.tool("chaprola_compile", "Compile Chaprola source (.CS) to bytecode (.PR). READ chaprola://cookbook BEFORE writing source. Key syntax: no PROGRAM keyword (start with commands), no commas, reports can use MOVE+PRINT 0 buffers or one-line PRINT concatenation, SEEK for primary records, OPEN/READ/WRITE/CLOSE for secondary files, LET supports one operation (no parentheses). Use primary_format to enable P.fieldname addressing (recommended) — the compiler resolves field names to positions and lengths from the format file. If compile fails, call chaprola_help before retrying.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Program name (without extension)"),
     source: z.string().describe("Chaprola source code"),
-    primary_format: z.string().optional().describe("Primary data file name (enables P.fieldname addressing)"),
-    secondary_format: z.string().optional().describe("Secondary format file name (enables S.fieldname addressing)"),
+    primary_format: z.string().optional().describe("Primary data file name — enables P.fieldname addressing (recommended for all programs that reference data fields)"),
+    secondary_format: z.string().optional().describe("Secondary data file name — enables S.fieldname addressing (required if using S.fieldname references)"),
 }, async ({ project, name, source, primary_format, secondary_format }) => withBaaCheck(async () => {
     const { username } = getCredentials();
     const body = { userid: username, project, name, source };
@@ -421,7 +430,7 @@ server.tool("chaprola_compile", "Compile Chaprola source (.CS) to bytecode (.PR)
     return textResult(res);
 }));
 // --- Run ---
-server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for large datasets (>100K records)", {
+server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for large datasets (>100K records). If runtime errors occur, call chaprola_help before retrying.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Program name (without extension)"),
     primary_file: z.string().optional().describe("Primary data file to load"),
@@ -473,6 +482,20 @@ server.tool("chaprola_run_each", "Run a compiled .PR program against every recor
     const res = await authedFetch("/run-each", body);
     return textResult(res);
 }));
+// --- Systemhelp ---
+server.tool("chaprola_systemhelp", "Send your program name and error message. Chaprola will read your source, intent file, and data schema to diagnose and fix the problem. See POST /help for examples.", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("Program name (without extension)"),
+    error: z.string().optional().describe("Error message from compile or runtime (copy verbatim if available)"),
+    request: z.string().describe("Plain-language description of the problem. Include context: what changed, what you expected, what happened instead."),
+}, async ({ project, name, error, request }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name, request };
+    if (error)
+        body.error = error;
+    const res = await authedFetch("/systemhelp", body);
+    return textResult(res);
+}));
 // --- Publish ---
 server.tool("chaprola_publish", "Publish a compiled program for public access via /report", {
     project: z.string().describe("Project name"),
@@ -539,16 +562,22 @@ server.tool("chaprola_download", "Get a presigned S3 URL to download any file yo
 server.tool("chaprola_query", "SQL-free data query with WHERE, SELECT, aggregation, ORDER BY, JOIN, pivot, and Mercury scoring", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file to query"),
-    where: z.record(z.any()).optional().describe("Filter: {field, op, value}. Ops: eq, ne, gt, ge, lt, le, between, contains, starts_with"),
+    where: z.string().optional().describe("JSON object of filter conditions, e.g. {\"field\": \"status\", \"op\": \"eq\", \"value\": \"active\"}. Ops: eq, ne, gt, ge, lt, le, between, contains, starts_with"),
     select: z.array(z.string()).optional().describe("Fields to include in output"),
-    aggregate: z.array(z.record(z.any())).optional().describe("Aggregation: [{field, func}]. Funcs: count, sum, avg, min, max, stddev"),
-    order_by: z.array(z.record(z.any())).optional().describe("Sort: [{field, dir}]"),
+    aggregate: z.string().optional().describe("JSON array of aggregation specs, e.g. [{\"field\": \"amount\", \"func\": \"sum\"}]. Funcs: count, sum, avg, min, max, stddev"),
+    order_by: z.string().optional().describe("JSON array of sort specs, e.g. [{\"field\": \"name\", \"dir\": \"asc\"}]"),
     limit: z.number().optional().describe("Max results to return"),
     offset: z.number().optional().describe("Skip this many results"),
-    join: z.record(z.any()).optional().describe("Join: {file, on, type, method}"),
-    pivot: z.record(z.any()).optional().describe("Pivot: {row, column, values, totals, grand_total}"),
-    mercury: z.record(z.any()).optional().describe("Mercury scoring: {fields: [{field, target, weight}]}"),
-}, async ({ project, file, where, select, aggregate, order_by, limit, offset, join, pivot, mercury }) => withBaaCheck(async () => {
+    join: z.string().optional().describe("JSON object of join config, e.g. {\"file\": \"other\", \"on\": \"id\", \"type\": \"inner\"}"),
+    pivot: z.string().optional().describe("JSON object of pivot config, e.g. {\"row\": \"category\", \"column\": \"month\", \"values\": \"sales\"}"),
+    mercury: z.string().optional().describe("JSON object of mercury scoring config, e.g. {\"fields\": [{\"field\": \"score\", \"target\": 100, \"weight\": 1.0}]}"),
+}, async ({ project, file, where: whereStr, select, aggregate: aggregateStr, order_by: orderByStr, limit, offset, join: joinStr, pivot: pivotStr, mercury: mercuryStr }) => withBaaCheck(async () => {
+    const where = typeof whereStr === 'string' ? JSON.parse(whereStr) : whereStr;
+    const aggregate = typeof aggregateStr === 'string' ? JSON.parse(aggregateStr) : aggregateStr;
+    const order_by = typeof orderByStr === 'string' ? JSON.parse(orderByStr) : orderByStr;
+    const join = typeof joinStr === 'string' ? JSON.parse(joinStr) : joinStr;
+    const pivot = typeof pivotStr === 'string' ? JSON.parse(pivotStr) : pivotStr;
+    const mercury = typeof mercuryStr === 'string' ? JSON.parse(mercuryStr) : mercuryStr;
     const { username } = getCredentials();
     const body = { userid: username, project, file };
     if (where)
@@ -609,7 +638,7 @@ server.tool("chaprola_merge", "Merge two sorted data files into one. Both must s
     return textResult(res);
 }));
 // --- Schema: Format + Alter ---
-server.tool("chaprola_format", "Inspect a data file's schema — returns field names, positions, lengths, types, and PHI flags", {
+server.tool("chaprola_format", "Inspect a data file's schema — returns field names, types, and PHI flags. Use this to understand the data structure before writing programs.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Data file name (without .F extension)"),
 }, async ({ project, name }) => withBaaCheck(async () => {
@@ -617,7 +646,7 @@ server.tool("chaprola_format", "Inspect a data file's schema — returns field n
     const res = await authedFetch("/format", { userid: username, project, name });
     return textResult(res);
 }));
-server.tool("chaprola_alter", "Modify a data file's schema: widen/narrow/rename fields, add new fields, drop fields. Transforms existing data to match the new schema.", {
+server.tool("chaprola_alter", "Modify a data file's schema: widen/narrow/rename fields, add new fields, drop fields. NON-DESTRUCTIVE: Transforms existing data to match the new schema. Use this for explicit schema surgery on existing data files; re-imports now preserve and widen existing schemas automatically, but chaprola_alter still handles rename/drop/narrow operations.", {
     project: z.string().describe("Project name"),
     name: z.string().describe("Data file name (without extension)"),
     alter: z.array(z.object({
@@ -756,7 +785,7 @@ server.tool("chaprola_search", "Search the web via Brave Search API. Returns tit
 }));
 // --- Fetch ---
 server.tool("chaprola_fetch", "Fetch any URL and return clean content. HTML pages converted to markdown. SSRF-protected. Rate limit: 20/day per user", {
-    url: z.string().url().describe("URL to fetch (http:// or https://)"),
+    url: z.string().describe("URL to fetch (http:// or https://)"),
     format: z.enum(["markdown", "text", "html", "json"]).optional().describe("Output format (default: markdown)"),
     max_length: z.number().optional().describe("Max output characters (default: 50000, max: 200000)"),
 }, async ({ url, format, max_length }) => withBaaCheck(async () => {
@@ -773,9 +802,10 @@ server.tool("chaprola_schedule", "Create a scheduled job that runs a Chaprola en
     name: z.string().describe("Unique name for this schedule (alphanumeric + hyphens/underscores)"),
     cron: z.string().describe("Standard 5-field cron expression (min hour day month weekday). Minimum interval: 15 minutes"),
     endpoint: z.enum(["/import-download", "/run", "/export-report", "/search", "/fetch", "/query", "/email/send", "/export", "/report", "/list"]).describe("Target endpoint to call"),
-    body: z.record(z.any()).describe("Request body for the target endpoint. userid is injected automatically"),
+    body: z.string().describe("JSON object of the schedule request body. userid is injected automatically"),
     skip_if_unchanged: z.boolean().optional().describe("Skip when response matches previous run (SHA-256 hash). Default: false"),
-}, async ({ name, cron, endpoint, body, skip_if_unchanged }) => withBaaCheck(async () => {
+}, async ({ name, cron, endpoint, body: bodyStr, skip_if_unchanged }) => withBaaCheck(async () => {
+    const body = typeof bodyStr === 'string' ? JSON.parse(bodyStr) : bodyStr;
     const reqBody = { name, cron, endpoint, body };
     if (skip_if_unchanged !== undefined)
         reqBody.skip_if_unchanged = skip_if_unchanged;
@@ -796,8 +826,9 @@ server.tool("chaprola_schedule_delete", "Delete a scheduled job by name", {
 server.tool("chaprola_insert_record", "Insert a new record into a data file's merge file (.MRG). The record appears at the end of the file until consolidation.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
-    record: z.record(z.string()).describe("Field name → value pairs. Unspecified fields default to blanks."),
-}, async ({ project, file, record }) => withBaaCheck(async () => {
+    record: z.string().describe("JSON object of the record to insert, e.g. {\"name\": \"foo\", \"status\": \"active\"}. Unspecified fields default to blanks."),
+}, async ({ project, file, record: recordStr }) => withBaaCheck(async () => {
+    const record = typeof recordStr === 'string' ? JSON.parse(recordStr) : recordStr;
     const { username } = getCredentials();
     const res = await authedFetch("/insert-record", { userid: username, project, file, record });
     return textResult(res);
@@ -805,9 +836,11 @@ server.tool("chaprola_insert_record", "Insert a new record into a data file's me
 server.tool("chaprola_update_record", "Update fields in a single record matched by a where clause. If no sort-key changes, updates in place; otherwise marks old record ignored and appends to merge file.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
-    where: z.record(z.string()).describe("Field name → value pairs to identify exactly one record"),
-    set: z.record(z.string()).describe("Field name → new value pairs to update"),
-}, async ({ project, file, where: whereClause, set }) => withBaaCheck(async () => {
+    where: z.string().describe("JSON object of filter conditions for which records to update, e.g. {\"id\": \"123\"}"),
+    set: z.string().describe("JSON object of fields to update, e.g. {\"status\": \"done\"}"),
+}, async ({ project, file, where: whereStr, set: setStr }) => withBaaCheck(async () => {
+    const whereClause = typeof whereStr === 'string' ? JSON.parse(whereStr) : whereStr;
+    const set = typeof setStr === 'string' ? JSON.parse(setStr) : setStr;
     const { username } = getCredentials();
     const res = await authedFetch("/update-record", { userid: username, project, file, where: whereClause, set });
     return textResult(res);
@@ -815,8 +848,9 @@ server.tool("chaprola_update_record", "Update fields in a single record matched
 server.tool("chaprola_delete_record", "Delete a single record matched by a where clause. Marks the record as ignored (.IGN). Physically removed on consolidation.", {
     project: z.string().describe("Project name"),
     file: z.string().describe("Data file name (without extension)"),
-    where: z.record(z.string()).describe("Field name → value pairs to identify exactly one record"),
-}, async ({ project, file, where: whereClause }) => withBaaCheck(async () => {
+    where: z.string().describe("JSON object of filter conditions for which records to delete, e.g. {\"id\": \"123\"}"),
+}, async ({ project, file, where: whereStr }) => withBaaCheck(async () => {
+    const whereClause = typeof whereStr === 'string' ? JSON.parse(whereStr) : whereStr;
     const { username } = getCredentials();
     const res = await authedFetch("/delete-record", { userid: username, project, file, where: whereClause });
     return textResult(res);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.6.3",
-  "description": "MCP server for Chaprola — agent-first data platform. Gives AI agents 46 tools for structured data storage, record CRUD, querying, schema inspection, web search, URL fetching, scheduled jobs, and execution via plain HTTP.",
+  "version": "1.7.0",
+  "description": "MCP server for Chaprola — agent-first data platform. Gives AI agents tools for structured data storage, record CRUD, querying, schema inspection, documentation lookup, web search, URL fetching, scheduled jobs, scoped site keys, and execution via plain HTTP.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {

package/references/auth.md

@@ -51,6 +51,39 @@ If you do handle PHI, sign the BAA once per account:
 
 These are read by the MCP server and injected into every authenticated request automatically.
 
+## Cross-User Project Sharing
+
+By default, only the project owner can read and write their data. To grant another user access, create an `access.json` file in the project root:
+
+```
+s3://chaprola-2026/{owner}/{project}/access.json
+```
+
+**Format:**
+```json
+{
+  "owner": "tawni",
+  "project": "social",
+  "discoverable": false,
+  "description": "Content calendar and social media",
+  "writers": [
+    {"username": "cal", "granted_at": "2026-04-06T17:25:16Z"},
+    {"username": "nora", "granted_at": "2026-04-06T17:25:16Z"}
+  ]
+}
+```
+
+**How it works:**
+- Any user in the `writers` list gets full read+write access to that project through all API endpoints (query, update-record, insert-record, delete-record, export, compile, run, run-each, etc.)
+- The shared user passes the **owner's** userid in requests: `{"userid": "tawni", "project": "social", ...}` — authenticated with their own API key
+- Every protected endpoint checks: (1) does the API key's username match the `userid`? If not, (2) is the user listed as a writer in `access.json`?
+- No `access.json` = no shared access (owner-only)
+- `discoverable` is reserved for future use (project discovery/listing)
+
+**To set up sharing:** Create or update the `access.json` file via S3 directly or through the `/sv` admin interface.
+
+**To revoke access:** Remove the user from the `writers` array, or delete `access.json` entirely.
+
 ## Credential Recovery
 
 If your API key stops working (403):

package/references/cookbook.md

@@ -19,43 +19,48 @@ POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1}
 |-------|---------|--------------------------|
 | R1–R20 | HULDRA elements (parameters) | No — HULDRA overwrites these |
 | R21–R40 | HULDRA objectives (error metrics) | No — HULDRA reads these |
-| R41–R50 | Scratch space | **Yes — always use R41–R50 for DEFINE VARIABLE** |
+| R41–R99 | Scratch space | **Yes — always use R41–R99 for DEFINE VARIABLE** |
 
-For non-HULDRA programs, R1–R40 are technically available but using R41–R50 is a good habit.
+For non-HULDRA programs, R1–R40 are technically available but using R41–R99 is a good habit.
 
-## PRINT: Output from U Buffer
+## PRINT: Preferred Output Methods
 
-```
-PRINT 0   — output the ENTIRE U buffer contents, then clear it
-PRINT N   — output exactly N characters from U buffer (no clear)
+**Concatenation (preferred):**
+```chaprola
+PRINT P.name + " — " + P.department + " — $" + R41
+PRINT "Total: " + R42
+PRINT P.last_name                  // single field, auto-trimmed
+PRINT "Hello from Chaprola!"      // literal string
 ```
 
-Use `PRINT N` when you've placed data at specific positions and want clean output without trailing garbage. Use `PRINT 0` for quick output of everything.
+- String literals are copied as-is.
+- P./S./U./X. fields are auto-trimmed (trailing spaces removed).
+- R-variables print as integers when no fractional part, otherwise as floats.
+- Concatenation auto-flushes the line.
 
+**U buffer output (for fixed-width columnar reports only):**
 ```chaprola
-MOVE "Hello" U.1 5
-PRINT 5    // Outputs "Hello" — exactly 5 chars, no trailing spaces
+CLEAR U
+MOVE P.name U.1 20
+PUT sal INTO U.22 10 D 2
+PRINT 0                            // output entire U buffer, then clear
 ```
 
 ## Hello World (no data file)
 
 ```chaprola
-MOVE "Hello from Chaprola!" U.1 20
-PRINT 0
+PRINT "Hello from Chaprola!"
 END
 ```
 
 ## Loop Through All Records
 
 ```chaprola
-DEFINE VARIABLE rec R1
+DEFINE VARIABLE rec R41
 LET rec = 1
 100 SEEK rec
     IF EOF GOTO 900
-    MOVE BLANKS U.1 40
-    MOVE P.name U.1 8
-    MOVE P.salary U.12 6
-    PRINT 0
+    PRINT P.name + " — " + P.salary
     LET rec = rec + 1
     GOTO 100
 900 END
@@ -65,10 +70,8 @@ LET rec = 1
 
 ```chaprola
 GET sal FROM P.salary
-IF sal LT 80000 GOTO 200    // skip low earners
-MOVE P.name U.1 8
-PUT sal INTO U.12 10 D 0    // D=dollar format
-PRINT 0
+IF sal LT 80000 GOTO 200           // skip low earners
+PRINT P.name + " — " + R41
 200 LET rec = rec + 1
 ```
 
@@ -76,10 +79,10 @@ PRINT 0
 
 ```chaprola
 OPEN "DEPARTMENTS" 0
-FIND match FROM S.dept_code 3 USING P.dept_code
-IF match EQ 0 GOTO 200      // no match
-READ match                   // load matched secondary record
-MOVE S.dept_name U.12 15    // now accessible
+FIND match FROM S.dept_code USING P.dept_code
+IF match EQ 0 GOTO 200             // no match
+READ match                          // load matched secondary record
+PRINT P.name + " — " + S.dept_name
 ```
 
 Compile with both formats so the compiler resolves fields from both files:
@@ -105,14 +108,47 @@ IF EQUAL U.200 U.180 12 GOTO 200   // match — jump to handler
 ## Read-Modify-Write (UPDATE)
 
 ```chaprola
-READ match                   // load record
-GET bal FROM S.balance       // read current value
-LET bal = bal + amt          // modify
-PUT bal INTO S.balance 8 F 0 // write back to S memory
-WRITE match                  // flush to disk
-CLOSE                        // flush all at end
+READ match                          // load record
+GET bal FROM S.balance              // read current value
+LET bal = bal + amt                 // modify
+PUT bal INTO S.balance F 0          // write back to S memory (length auto-filled)
+WRITE match                         // flush to disk
+CLOSE                               // flush all at end
+```
+
+## Date Arithmetic
+
+```chaprola
+GET DATE R41 FROM X.primary_modified   // when was file last changed?
+GET DATE R42 FROM X.utc_time           // what time is it now?
+LET R43 = R42 - R41                    // difference in seconds
+LET R43 = R43 / 86400                  // convert to days
+IF R43 GT 30 PRINT "WARNING: file is over 30 days old" ;
 ```
 
+## Get Current User
+
+```chaprola
+PRINT "Logged in as: " + X.username
+```
+
+## System Text Properties (X.)
+
+Access system metadata by property name — no numeric positions needed:
+
+| Property | Description |
+|----------|-------------|
+| `X.year` | Year (four digits) |
+| `X.julian` | Julian date (1–366) |
+| `X.hour` | Hour (military time) |
+| `X.minute` | Minute (0–59) |
+| `X.username` | Authenticated user |
+| `X.record_num` | Primary file record number |
+| `X.utc_time` | UTC datetime (ISO 8601) |
+| `X.elapsed` | Elapsed execution time |
+| `X.primary_modified` | Primary file Last-Modified |
+| `X.secondary_modified` | Secondary file Last-Modified |
+
 ## Async for Large Datasets
 
 ```bash
@@ -140,9 +176,7 @@ SEEK 1
     GOTO 300
 200 GET cardlvl FROM P.level
     IF cardlvl NE lvl GOTO 300           // filter by level param
-    MOVE P.kanji U.1 4
-    MOVE P.reading U.6 10
-    PRINT 0
+    PRINT P.kanji + " — " + P.reading
 300 LET rec = rec + 1
     SEEK rec
     GOTO 100
@@ -208,7 +242,7 @@ POST /query {
 | `I` | Integer (right-justified) | `  1234` |
 | `E` | Scientific notation | `1.23E+03` |
 
-Syntax: `PUT R1 INTO U.30 10 D 2` (R-var, location, width, format, decimals)
+Syntax: `PUT R41 INTO P.salary D 2` (R-var, field name, format, decimals — length auto-filled)
 
 ## Common Field Widths
 
@@ -227,19 +261,19 @@ Use these when sizing MOVE lengths and U buffer positions.
 
 | Prefix | Description |
 |--------|-------------|
-| `P` | Primary data file (current record) |
-| `S` | Secondary data file (current record) |
+| `P` | Primary data file — use field names: `P.salary`, `P.name` |
+| `S` | Secondary data file — use field names: `S.dept`, `S.emp_id` |
 | `U` | User buffer (scratch for output) |
-| `X` | System text (date, time, filenames) |
+| `X` | System text — use property names: `X.username`, `X.utc_time` |
 
 ## Math Intrinsics
 
 ```chaprola
-LET R2 = EXP R1      // e^R1
-LET R2 = LOG R1      // ln(R1)
-LET R2 = SQRT R1     // √R1
-LET R2 = ABS R1      // |R1|
-LET R3 = POW R1 R2   // R1^R2
+LET R42 = EXP R41      // e^R41
+LET R42 = LOG R41      // ln(R41)
+LET R42 = SQRT R41     // √R41
+LET R42 = ABS R41      // |R41|
+LET R43 = POW R41 R42  // R41^R42
 ```
 
 ## Import-Download: URL → Dataset (Parquet, Excel, CSV, JSON)
@@ -281,7 +315,7 @@ HULDRA finds the best parameter values for a mathematical model by minimizing th
 |-------|---------|-------------|
 | R1–R20 | **Elements** (parameters to optimize) | HULDRA sets these before each VM run |
 | R21–R40 | **Objectives** (error metrics) | Your program computes and stores these |
-| R41–R50 | **Scratch space** | Your program uses these for temp variables |
+| R41–R99 | **Scratch space** | Your program uses these for temp variables |
 
 ### Complete Example: Fit a Linear Model
 

package/references/gotchas.md

@@ -11,21 +11,60 @@ LET temp = qty + bonus
 LET result = price * temp
 ```
 
+### No built-in functions
+There are NO functions with parentheses. No STR(), INT(), ABS(), LEN(), TRIM(), SUBSTR(), CONCAT(), FORMAT(), TOSTRING(), etc.
+- To convert number to text for output: `PRINT "Total: " + R41`
+- To write number to a field: `PUT R41 INTO P.salary D 2`
+- To convert text to number: `GET R41 FROM P.salary`
+- To clear a field: `MOVE BLANKS P.notes` or `CLEAR U`
+
+### Use field names, not numeric positions
+Always use `P.salary`, `S.dept`, `X.username` — not `P.63 10`, `S.30 4`, `X.28 8`. The compiler auto-fills positions and lengths from the format file.
+```chaprola
+// PREFERRED: field names — readable, resilient to format changes
+GET R41 FROM P.salary
+PRINT P.name + " — " + P.department
+MOVE X.username U.1
+
+// AVOID: numeric positions — fragile, unreadable
+GET R41 FROM P.63 10
+```
+
+### Use PRINT concatenation, not MOVE + PRINT 0
+```chaprola
+// PREFERRED: direct concatenation
+PRINT P.name + " earns $" + R41
+
+// AVOID: old MOVE-to-buffer pattern
+MOVE BLANKS U.1 80
+MOVE P.name U.1 20
+PUT R41 INTO U.22 10 D 2
+PRINT 0
+```
+
+### Use CLEAR, not MOVE BLANKS for full regions
+```chaprola
+CLEAR U                             // clear entire user buffer
+CLEAR P                             // clear entire primary region
+CLEAR S                             // clear entire secondary region
+MOVE BLANKS P.notes                 // clear a single field (length auto-filled)
+```
+
 ### IF EQUAL compares a literal to a location
-Cannot compare two memory locations. Copy to U buffer first.
+Cannot compare two memory locations directly. Copy to U buffer first.
 ```chaprola
 MOVE P.txn_type U.76 6
 IF EQUAL "CREDIT" U.76 GOTO 200
 ```
 
-### MOVE length must match field width
-`MOVE P.name U.1 20` copies 20 chars starting at the field — if `name` is 8 chars wide, the extra 12 bleed into adjacent fields. Always match the format file width.
+### MOVE literal auto-pads to field width
+`MOVE "Jones" P.name` auto-fills the rest of the field with blanks. No need to clear first.
 
 ### DEFINE VARIABLE names must not collide with field names
-If the format has a `balance` field, don't `DEFINE VARIABLE balance R3`. Use `bal` instead. The compiler confuses the alias with the field name.
+If the format has a `balance` field, don't `DEFINE VARIABLE balance R41`. Use `bal` instead. The compiler confuses the alias with the field name.
 
 ### R-variables are floating point
-All R1–R50 are 64-bit floats. `7 / 2 = 3.5`. Use PUT with `I` format to display as integer.
+All R1–R99 are 64-bit floats. `7 / 2 = 3.5`. Use PUT with `I` format to display as integer.
 
 ### Statement numbers are labels, not line numbers
 Only number lines that are GOTO/CALL targets. Don't number every line.
@@ -36,6 +75,13 @@ Always check `IF match EQ 0` after FIND before calling READ.
 ### PRINT 0 clears the U buffer
 After PRINT 0, the buffer is empty. No need to manually clear between prints unless reusing specific positions.
 
+### GET DATE / PUT DATE — no FOR keyword needed with property names
+```chaprola
+GET DATE R41 FROM X.utc_time           // correct — length auto-filled
+GET DATE R42 FROM X.primary_modified   // correct — length auto-filled
+PUT DATE R41 INTO U.1 20              // U buffer needs explicit length
+```
+
 ## Import
 
 ### Field widths come from the longest value
@@ -74,8 +120,8 @@ Always CLOSE before END if you wrote to the secondary file. Unflushed writes are
 
 ## HULDRA Optimization
 
-### Use R41–R50 for scratch variables, not R1–R20
-R1–R20 are reserved for HULDRA elements. R21–R40 are reserved for objectives. Your VALUE program's DEFINE VARIABLE declarations must use R41–R50 only.
+### Use R41–R99 for scratch variables, not R1–R20
+R1–R20 are reserved for HULDRA elements. R21–R40 are reserved for objectives. Your VALUE program's DEFINE VARIABLE declarations must use R41–R99 only.
 ```chaprola
 // WRONG: DEFINE VARIABLE counter R1  (HULDRA will overwrite this)
 // RIGHT: DEFINE VARIABLE counter R41

package/references/ref-apps.md

@@ -0,0 +1,193 @@
+# Building Apps on Chaprola — Architecture Reference
+
+## Overview
+
+Chaprola is a backend for frontend apps. Your React, Vue, Svelte, or Laravel app calls `api.chaprola.org` directly from the browser. No proxy server, no middleware, no infrastructure to manage.
+
+## Two Architectures
+
+### 1. Single-Owner App (simplest)
+
+One Chaprola account owns all the data. The app uses a **site key** locked to its domain. All users see the same data.
+
+**Use cases:** dashboards, public reports, internal tools, data viewers, portfolio sites.
+
+```
+Browser → React App → api.chaprola.org (site key in Authorization header)
+```
+
+**Setup:**
+1. Register a Chaprola account: `POST /register`
+2. Sign the BAA if handling health data: `POST /sign-baa`
+3. Create a site key locked to your domain:
+   ```json
+   POST /create-site-key
+   {"userid": "myapp", "origin": "https://myapp.example.com", "label": "production"}
+   ```
+   Response: `{"site_key": "site_a1b2c3..."}`
+4. Use the site key in your frontend:
+   ```javascript
+   const resp = await fetch('https://api.chaprola.org/query', {
+     method: 'POST',
+     headers: {
+       'Authorization': 'Bearer site_a1b2c3...',
+       'Content-Type': 'application/json'
+     },
+     body: JSON.stringify({ userid: 'myapp', project: 'main', file: 'products', where: [] })
+   })
+   ```
+
+**Security model:** The site key is checked against the `Origin` HTTP header, which browsers set automatically. This prevents other websites from using your key (CORS-level protection). However, Origin headers are trivially spoofable from non-browser clients (curl, Postman, scripts). Anyone who extracts the site key from your JavaScript has full access to the account's data. **Use this pattern only for public or semi-public data** — dashboards, product catalogs, published reports. For private data, use the multi-user pattern (each user authenticates individually) or the enterprise proxy pattern.
+
+### 2. Multi-User App (each user has their own account)
+
+Each app user registers their own Chaprola account. The app stores their API key in the browser session. Each user has their own data silo.
+
+**Use cases:** SaaS apps, multi-tenant platforms, apps where users own their data.
+
+```
+Browser → React App → api.chaprola.org (user's own API key)
+```
+
+**Setup:**
+1. Your app's registration form calls Chaprola directly:
+   ```javascript
+   // User signs up
+   const resp = await fetch('https://api.chaprola.org/register', {
+     method: 'POST',
+     headers: { 'Content-Type': 'application/json' },
+     body: JSON.stringify({ username: 'alice', passcode: 'their-secure-passcode' })
+   })
+   const { api_key } = await resp.json()
+   sessionStorage.setItem('chaprola_key', api_key)
+   ```
+
+2. Your app's login form:
+   ```javascript
+   const resp = await fetch('https://api.chaprola.org/login', {
+     method: 'POST',
+     headers: { 'Content-Type': 'application/json' },
+     body: JSON.stringify({ username: 'alice', passcode: 'their-secure-passcode' })
+   })
+   const { api_key } = await resp.json()
+   sessionStorage.setItem('chaprola_key', api_key)
+   ```
+
+3. All subsequent API calls use the user's key:
+   ```javascript
+   const key = sessionStorage.getItem('chaprola_key')
+   const resp = await fetch('https://api.chaprola.org/query', {
+     method: 'POST',
+     headers: {
+       'Authorization': `Bearer ${key}`,
+       'Content-Type': 'application/json'
+     },
+     body: JSON.stringify({ userid: 'alice', project: 'mydata', file: 'tasks', where: [] })
+   })
+   ```
+
+**Security model:** Each user authenticates individually. User A cannot access User B's data (userid enforcement). No shared secrets in the frontend. API keys are per-user, stored in the browser session.
+
+**Team data sharing:** If users need to share a project, the project owner creates an `access.json` file listing writers. See the auth reference for details.
+
+## Which Architecture Should I Use?
+
+| Question | Single-Owner | Multi-User |
+|----------|:---:|:---:|
+| One person/org owns all the data? | Yes | |
+| Users create accounts and own their data? | | Yes |
+| Public dashboard or report viewer? | Yes | |
+| SaaS with multiple tenants? | | Yes |
+| Internal tool for a small team? | Yes | |
+| App where privacy between users matters? | | Yes |
+| Data is sensitive or private? | No — use Multi-User or Enterprise | Yes |
+
+**Rule of thumb:** If you'd be uncomfortable with someone viewing all the data in that Chaprola account, don't use the single-owner pattern. The site key will be in your JavaScript source — assume it's public.
+
+## Enterprise Customers
+
+If your enterprise requires that API keys never touch the browser:
+
+Run your own backend proxy. Your React/Laravel frontend authenticates users through your own auth system (OAuth, SSO, SAML). Your backend holds the Chaprola API key server-side and proxies requests.
+
+```
+User → Enterprise App → Enterprise Backend (holds API key) → api.chaprola.org
+```
+
+This is the same pattern used with Stripe, Twilio, and other APIs. Chaprola does not provide a managed proxy — your infrastructure team owns this layer.
+
+**Most apps do not need this.** The site key + per-user auth model handles the vast majority of use cases without any backend infrastructure.
+
+## Site Keys Reference
+
+Site keys are API keys locked to a specific browser origin. They prevent your key from being used on other websites.
+
+```json
+// Create
+POST /create-site-key
+{"userid": "myapp", "origin": "https://myapp.example.com", "label": "production"}
+// Response: {"site_key": "site_...", "origin": "https://myapp.example.com"}
+
+// List
+POST /list-site-keys
+{"userid": "myapp"}
+
+// Delete
+POST /delete-site-key
+{"userid": "myapp", "site_key": "site_..."}
+```
+
+**Key facts:**
+- Format: `site_` prefix + 64 hex chars
+- Locked to one origin (exact match on the `Origin` HTTP header)
+- Never expire — persist until explicitly deleted
+- Not affected by `/login` (login rotates the main API key, not site keys)
+- Same permissions as the main API key for that account
+- Create multiple site keys for different environments (dev, staging, production)
+
+## Deploying Your App
+
+For static React/Vue/Svelte apps, Chaprola can host them:
+
+```json
+POST /app/deploy
+{"userid": "myapp", "project": "main", "app_name": "myapp"}
+```
+
+Your app is served at `https://chaprola.org/apps/{userid}/{app_name}/`. Or deploy anywhere (Vercel, Netlify, S3) and use a site key locked to that domain.
+
+## Common Patterns
+
+### Import data, then query it
+```javascript
+// Import
+await fetch('https://api.chaprola.org/import', {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ userid: 'myapp', project: 'main', name: 'products', data: [...] })
+})
+
+// Query
+const resp = await fetch('https://api.chaprola.org/query', {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ userid: 'myapp', project: 'main', file: 'products', where: [{ field: 'category', op: 'eq', value: 'electronics' }] })
+})
+const { records } = await resp.json()
+```
+
+### Insert a record
+```javascript
+await fetch('https://api.chaprola.org/insert-record', {
+  method: 'POST',
+  headers: { 'Authorization': `Bearer ${key}`, 'Content-Type': 'application/json' },
+  body: JSON.stringify({ userid: 'myapp', project: 'main', file: 'tasks', record: { title: 'New task', status: 'open', due: '2026-04-15' } })
+})
+```
+
+### Run a published report
+```javascript
+// No auth needed for public reports
+const resp = await fetch('https://api.chaprola.org/report?userid=myapp&project=main&name=DASHBOARD&format=html')
+const html = await resp.text()
+```

package/references/ref-gotchas.md

@@ -2,15 +2,21 @@
 
 ## Language
 - **No parentheses in LET.** `LET result = price * qty` only. For `price * (qty + bonus)`: use `LET temp = qty + bonus` then `LET result = price * temp`.
+- **No built-in functions.** No STR(), INT(), ABS(), LEN(), TRIM(), SUBSTR(), etc. Use PUT/GET/MOVE/PRINT concatenation instead.
+- **Use field names, not numeric positions.** `P.salary` not `P.63 10`. `X.username` not `X.15 10`. The compiler auto-fills positions and lengths.
+- **Use PRINT concatenation for output.** `PRINT P.name + " — " + R41` instead of MOVE-to-U-buffer + PRINT 0.
+- **Use CLEAR for full regions.** `CLEAR U` instead of `MOVE BLANKS U.1 65536`. Also `CLEAR P`, `CLEAR S`.
+- **MOVE literal auto-pads.** `MOVE "Jones" P.name` fills the rest of the field with blanks. No need to clear first.
 - **IF EQUAL compares literal to location.** To compare two locations, copy both to U buffer first.
-- **MOVE length must match field width.** If `name` is 8 chars wide, `MOVE P.name U.1 20` bleeds into adjacent fields.
 - **DEFINE VARIABLE names must not collide with field names.** If format has `balance`, don't `DEFINE VARIABLE balance R41`.
 - **R-variables are 64-bit floats.** `7 / 2 = 3.5`. Use PUT with `I` format for integer display.
 - **FIND returns 0 on no match.** Always check `IF match EQ 0` before READ.
 - **PRINT 0 clears the U buffer.** No need to manually clear between prints.
 - **Statement numbers are labels, not line numbers.** Only number GOTO/CALL targets.
+- **GET DATE / PUT DATE need no FOR keyword** with property names: `GET DATE R41 FROM X.utc_time`
 
 ## API
+- **NEVER use `/import` to change field widths.** `/import` REPLACES existing data. Use `/alter` to widen/narrow fields while preserving data. See `chaprola://ref/schema`.
 - **userid must match authenticated user.** 403 on mismatch.
 - **Login invalidates the old key.** Save the new one immediately.
 - **Async for large datasets.** `/run` with `async: true` for >100K records (API Gateway 30s timeout).

package/references/ref-huldra.md

@@ -8,7 +8,7 @@ HULDRA finds optimal parameter values for a mathematical model by minimizing the
 |-------|---------|-------------|
 | R1–R20 | Elements (parameters to optimize) | HULDRA sets before each run |
 | R21–R40 | Objectives (error metrics) | Your program computes these |
-| R41–R50 | Scratch space | Your program's temp variables |
+| R41–R99 | Scratch space | Your program's temp variables |
 
 ## POST /optimize
 ```json

package/references/ref-import.md

@@ -10,6 +10,14 @@ POST /import {userid, project, name: "STAFF", data: [{"name": "Alice", "salary":
 
 Field widths auto-sized from longest value. Default expiry: 90 days. Override with `expires_in_days`.
 
+### ⚠️ DESTRUCTIVE WARNING
+
+**`/import` REPLACES both the format (.F) and data (.DA) files if they already exist. All existing data will be lost.**
+
+- **Use `/import` ONLY for:** Creating brand new data files or intentionally replacing entire datasets
+- **DO NOT use `/import` to:** Change field widths or modify schema on existing data
+- **Use `/alter` instead** to modify field widths/schema while preserving existing data (see `chaprola://ref/schema`)
+
 ## Large File Upload (presigned URL)
 ```bash
 POST /import-url {userid, project, name} → {upload_url, staging_key}
@@ -17,11 +25,15 @@ POST /import-url {userid, project, name} → {upload_url, staging_key}
 POST /import-process {userid, project, name, staging_key} → same as /import
 ```
 
+**WARNING:** `/import-process` is also DESTRUCTIVE and replaces existing data. Use `/alter` for schema changes.
+
 ## POST /import-download
 `{userid, project, name, url, instructions?, max_rows?}`
 Imports directly from URL. Supports: CSV, TSV, JSON, NDJSON, Parquet, Excel (.xlsx/.xls).
 Optional `instructions` for AI schema inference. Max 1M records.
 
+**WARNING:** `/import-download` is also DESTRUCTIVE and replaces existing data. Use `/alter` for schema changes.
+
 ## POST /export
 `{userid, project, name, format?}` → `{data: [...records]}`
 Optional `format: "fhir"` for FHIR JSON reconstruction.

package/references/ref-programs.md

@@ -12,33 +12,53 @@ POST /publish {userid, project, name, primary_file, acl?: "public|authenticated|
 
 | Prefix | Description |
 |--------|-------------|
-| `P` | Primary data file (current record) |
-| `S` | Secondary data file (current record) |
-| `U` | User buffer (output scratch) |
-| `X` | System text (date, time, filenames) |
+| `P` | Primary data file — access fields by name: `P.salary`, `P.last_name` |
+| `S` | Secondary data file — access fields by name: `S.dept`, `S.emp_id` |
+| `U` | User buffer (scratch for intermediate data) |
+| `X` | System text — access by property name: `X.username`, `X.utc_time`, `X.record_num` |
+
+### System Text Properties (X.)
+
+| Property | Description |
+|----------|-------------|
+| `X.year` | Year (four digits) |
+| `X.julian` | Julian date (1–366) |
+| `X.hour` | Hour (military time, 0–23) |
+| `X.minute` | Minute (0–59) |
+| `X.username` | Authenticated user (first 10 chars) |
+| `X.record_num` | Record number of primary file |
+| `X.display_file` | Display filename |
+| `X.data_file` | Data filename |
+| `X.proc_file` | Procedure filename |
+| `X.utc_time` | UTC datetime (ISO 8601, 20 chars) |
+| `X.elapsed` | Elapsed execution time (SSSSS.CC, 9 chars) |
+| `X.primary_modified` | Primary file Last-Modified (ISO 8601, 20 chars) |
+| `X.secondary_modified` | Secondary file Last-Modified (ISO 8601, 20 chars) |
 
 ## Language Essentials
 
 ```chaprola
-// Loop through records
+// Loop through records and print with concatenation
 DEFINE VARIABLE rec R41
 LET rec = 1
 100 SEEK rec
     IF EOF GOTO 900
-    MOVE P.name U.1 20          // copy field to output buffer
-    GET sal FROM P.salary        // numeric field → R variable
-    PUT sal INTO U.22 10 D 2     // R variable → formatted output
-    PRINT 0                      // output full U buffer, clear it
+    GET sal FROM P.salary
+    PRINT P.name + " — " + P.department + " — $" + sal
     LET rec = rec + 1
     GOTO 100
 900 END
 ```
 
-- `PRINT 0` — output entire U buffer and clear. `PRINT N` — output exactly N chars.
-- `MOVE BLANKS U.1 80` — clear a region. `MOVE "literal" U.1 7` — move literal.
-- `IF EQUAL "text" U.50 4 GOTO 200` — compare literal to memory location.
-- `U.name` — named positions (auto-allocated by compiler): `MOVE P.name U.name 20`
-- `DEFINE VARIABLE counter R41` — alias R-variable. **Use R41-R50** (R1-R40 reserved for HULDRA).
+- **PRINT concatenation (preferred):** `PRINT P.name + " earns " + R41` — auto-trims fields, auto-formats numbers, auto-flushes.
+- `PRINT P.fieldname` — output a single field (auto-flush, auto-trim).
+- `PRINT "literal"` — output a literal string (auto-flush).
+- `PRINT 0` — output entire U buffer (less common, for columnar reports).
+- `CLEAR U` — clear entire user buffer. `CLEAR P` / `CLEAR S` — clear primary/secondary region.
+- `MOVE BLANKS P.notes` — clear a single field (length auto-filled).
+- `MOVE "Active" P.status` — write literal to field (auto-padded to field width).
+- `IF EQUAL "text" P.status GOTO 200` — compare literal to field.
+- `DEFINE VARIABLE counter R41` — alias R-variable. **Use R41-R99** (R1-R40 reserved for HULDRA).
 
 ## PUT Format Codes
 
@@ -49,7 +69,7 @@ LET rec = 1
 | `I` | Integer (right-justified) | `  1234` |
 | `E` | Scientific notation | `1.23E+03` |
 
-Syntax: `PUT R41 INTO U.30 10 D 2` — (R-var, location, width, format, decimals)
+Syntax: `PUT R41 INTO P.salary D 2` — (R-var, location, width auto-filled from field name, format, decimals)
 
 ## Math
 
@@ -59,14 +79,24 @@ LET R43 = EXP R41       // also: LOG, SQRT, ABS
 LET R44 = POW R41 R42   // R41^R42
 ```
 
+## Date Arithmetic
+
+```chaprola
+GET DATE R41 FROM X.primary_modified   // parse timestamp → epoch seconds
+GET DATE R42 FROM X.utc_time           // current UTC time
+LET R43 = R42 - R41                    // difference in seconds
+LET R43 = R43 / 86400                  // convert to days
+PUT DATE R42 INTO U.1 20               // write epoch as ISO 8601 string
+```
+
 ## Secondary Files (FIND/JOIN)
 
 ```chaprola
 OPEN "DEPARTMENTS" 0              // open secondary file
-FIND match FROM S.dept_code 3 USING P.dept_code
+FIND match FROM S.dept_code USING P.dept_code
 IF match EQ 0 GOTO 200           // 0 = no match
 READ match                        // load matched record
-MOVE S.dept_name U.30 15
+PRINT P.name + " — " + S.dept_name
 WRITE match                       // write back if modified
 CLOSE                             // flush + close
 ```

package/references/ref-schema.md

@@ -0,0 +1,166 @@
+# Schema Inspection & Modification
+
+## POST /format
+Inspect a data file's schema — returns field names, positions, lengths, types, and PHI flags.
+
+```bash
+POST /format {userid, project, name: "STAFF"}
+```
+
+Returns:
+```json
+{
+  "format_file": "s3://chaprola-2026/userid/project/format/STAFF.F",
+  "fields": [
+    {"name": "name", "position": 1, "length": 50, "type": "text", "phi": false},
+    {"name": "salary", "position": 51, "length": 10, "type": "numeric", "phi": false}
+  ],
+  "record_length": 60
+}
+```
+
+Use this to inspect the current schema before making changes with `/alter`.
+
+---
+
+## POST /alter
+**NON-DESTRUCTIVE schema modification.** Modifies field widths, renames fields, adds new fields, or drops fields. Existing data is preserved and reformatted to match the new schema.
+
+### ⚠️ CRITICAL: Use /alter for schema changes, NOT /import
+
+**DO NOT use `/import` to change field widths or schema on existing data files.** `/import` REPLACES both the format (.F) and data (.DA) files, destroying all existing data.
+
+**Use `/alter` when you need to:**
+- Widen or narrow field widths
+- Rename fields
+- Add new fields to existing data
+- Drop unused fields
+- Change field types
+
+**Use `/import` only when:**
+- Creating a brand new data file
+- Intentionally replacing an entire dataset
+
+---
+
+## /alter Request Format
+
+```json
+{
+  "userid": "...",
+  "project": "...",
+  "name": "STAFF",
+  "alter": [
+    {"field": "name", "width": 100},        // widen from 50 to 100
+    {"field": "dept", "rename": "department"}
+  ],
+  "add": [
+    {"name": "email", "width": 80, "type": "text", "after": "name"}
+  ],
+  "drop": ["old_field"],
+  "output": "STAFF_V2"  // optional: create new file instead of in-place
+}
+```
+
+### Parameters
+
+**`alter`** (optional): Array of field modifications
+- `field` (required): Field name to modify
+- `width` (optional): New width (can widen or narrow)
+- `rename` (optional): New field name
+- `type` (optional): Change type (`"text"` or `"numeric"`)
+
+**`add`** (optional): Array of new fields to add
+- `name` (required): New field name
+- `width` (required): Field width
+- `type` (optional): `"text"` (default) or `"numeric"`
+- `after` (optional): Insert after this field (default: end of record)
+
+**`drop`** (optional): Array of field names to remove
+
+**`output`** (optional): Output file name. If not specified, modifies in-place.
+
+---
+
+## Examples
+
+### Widen a field (most common case)
+```bash
+# Widen 'description' field from 100 to 500 characters
+POST /alter {
+  userid, project, name: "ITEMS",
+  alter: [{"field": "description", "width": 500}]
+}
+```
+
+### Add a new field
+```bash
+# Add 'created_at' field after 'id'
+POST /alter {
+  userid, project, name: "RECORDS",
+  add: [{"name": "created_at", "width": 24, "after": "id"}]
+}
+```
+
+### Rename and widen
+```bash
+# Rename 'dept' to 'department' and widen to 50
+POST /alter {
+  userid, project, name: "STAFF",
+  alter: [{"field": "dept", "rename": "department", "width": 50}]
+}
+```
+
+### Complex schema change
+```bash
+# Multiple operations in one call
+POST /alter {
+  userid, project, name: "EMPLOYEES",
+  alter: [
+    {"field": "name", "width": 100},
+    {"field": "dept_id", "rename": "department_id"}
+  ],
+  add: [
+    {"name": "email", "width": 80, "after": "name"},
+    {"name": "hire_date", "width": 10, "type": "text"}
+  ],
+  drop: ["legacy_field", "unused_column"]
+}
+```
+
+---
+
+## How /alter Works Internally
+
+1. **Reads the old format (.F)** to understand current field positions
+2. **Creates a new format (.F)** with your requested changes
+3. **Reads all records from the old data (.DA)**
+4. **Reformats each record** to match the new schema:
+   - Widened fields: existing data left-aligned, space-padded
+   - Narrowed fields: truncated to new width
+   - New fields: filled with spaces
+   - Dropped fields: removed from record
+5. **Writes reformatted records** to the new data file
+6. **Replaces the old files** (if in-place) or creates new files (if `output` specified)
+
+This is a **safe, non-destructive transformation** of existing data. No data is lost unless you explicitly narrow fields or drop them.
+
+---
+
+## Common Gotchas
+
+1. **Narrowing fields truncates data** — if you narrow a field from 100 to 50, any values longer than 50 characters will be truncated. Use `/format` first to check max field lengths.
+
+2. **Field order matters for `after`** — when adding multiple fields, they're processed in order. If you add field B after field A, and also add field C after field A, field B will come first (because it was added first).
+
+3. **Cannot rename and drop the same field** — if you rename a field, don't also include it in the `drop` array.
+
+4. **Output file must not exist** — if you specify an `output` name and that file already exists, the operation will fail.
+
+---
+
+## See Also
+
+- `/format` — inspect current schema before making changes
+- `/import` — create NEW data files (DESTRUCTIVE if file exists)
+- `/query` — query data after schema changes