@chaprola/mcp-server 1.6.4 → 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 — NON-DESTRUCTIVE. Use this, NOT chaprola_import, to modify schemas on existing data.)
+- **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 () => ({
@@ -198,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: [{
@@ -213,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" +
@@ -222,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" +
@@ -246,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"),
@@ -334,7 +338,7 @@ 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). DESTRUCTIVE: This REPLACES both the format (.F) and data (.DA) files if they already exist. All existing data will be lost. Use chaprola_alter to modify field widths/schema on existing data. Use chaprola_import only for new data or when replacing entire datasets. 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.string().describe("JSON array of record objects to import"),
@@ -351,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). DESTRUCTIVE: The subsequent chaprola_import_process will replace existing data. Use chaprola_alter to modify schemas on existing data.", {
+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 () => {
@@ -359,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. DESTRUCTIVE: Replaces existing data if the file already exists. Use chaprola_alter to modify schemas on existing data.", {
+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"),
@@ -371,7 +375,7 @@ 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. DESTRUCTIVE: Replaces existing data if the file already exists. Use chaprola_alter to modify schemas on existing data.", {
+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().describe("Public URL to download (http/https only)"),
@@ -409,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 };
@@ -426,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"),
@@ -478,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"),
@@ -620,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 () => {
@@ -628,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. NON-DESTRUCTIVE: Transforms existing data to match the new schema. This is the ONLY safe way to change field widths or schema on existing data files. Unlike chaprola_import which replaces all data, chaprola_alter preserves and reformats existing records.", {
+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({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.6.4",
-  "description": "MCP server for Chaprola — agent-first data platform. Gives AI agents 47 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,13 +2,18 @@
 
 ## 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`.

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-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
 ```