@chaprola/mcp-server 1.4.3 → 1.6.0

package/dist/index.js

@@ -164,6 +164,40 @@ server.resource("endpoints", "chaprola://endpoints", { description: "Chaprola AP
 server.resource("auth", "chaprola://auth", { description: "Chaprola authentication reference — API key model, BAA flow, credential recovery", mimeType: "text/markdown" }, async () => ({
     contents: [{ uri: "chaprola://auth", mimeType: "text/markdown", text: readRef("auth.md") }],
 }));
+// --- Modular Resources (Tier 1 + Tier 2) ---
+server.resource("quickstart", "chaprola://quickstart", { description: "Chaprola quickstart — auth, base URL, core workflow, and index of all feature references. READ THIS FIRST.", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://quickstart", mimeType: "text/markdown", text: readRef("quickstart.md") }],
+}));
+server.resource("ref-import", "chaprola://ref/import", { description: "Import, export, list, download — all data I/O endpoints", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/import", mimeType: "text/markdown", text: readRef("ref-import.md") }],
+}));
+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-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") }],
+}));
+server.resource("ref-mercury", "chaprola://ref/mercury", { description: "Mercury weighted scoring — rank records by multiple criteria", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/mercury", mimeType: "text/markdown", text: readRef("ref-mercury.md") }],
+}));
+server.resource("ref-programs", "chaprola://ref/programs", { description: "Chaprola .CS language — MOVE, LET, GET, PUT, SEEK, IF, GOTO, PRINT, secondary files, params", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/programs", mimeType: "text/markdown", text: readRef("ref-programs.md") }],
+}));
+server.resource("ref-huldra", "chaprola://ref/huldra", { description: "HULDRA nonlinear optimization — parameter fitting, model catalog", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/huldra", mimeType: "text/markdown", text: readRef("ref-huldra.md") }],
+}));
+server.resource("ref-deploy", "chaprola://ref/deploy", { description: "Static app deployment to chaprola.org/apps/", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/deploy", mimeType: "text/markdown", text: readRef("ref-deploy.md") }],
+}));
+server.resource("ref-email", "chaprola://ref/email", { description: "Email system — inbox, read, send, forward, attachments", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://ref/email", mimeType: "text/markdown", text: readRef("ref-email.md") }],
+}));
+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 () => ({
+    contents: [{ uri: "chaprola://ref/auth", mimeType: "text/markdown", text: readRef("ref-auth.md") }],
+}));
 // --- MCP Prompts ---
 server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read this before writing any Chaprola source code.", async () => ({
     messages: [{
@@ -695,6 +729,14 @@ server.tool("chaprola_email_delete", "Delete a specific email from your mailbox"
     const res = await authedFetch("/email/delete", { address: username, message_id });
     return textResult(res);
 }));
+server.tool("chaprola_email_forward", "Forward an email (with attachments) to another address. Reads the original email from your mailbox, includes all attachments, and sends via Resend.", {
+    message_id: z.string().describe("Message ID of the email to forward"),
+    to: z.string().describe("Destination email address"),
+}, async ({ message_id, to }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/email/forward", { from: username, message_id, to });
+    return textResult(res);
+}));
 // --- Search ---
 server.tool("chaprola_search", "Search the web via Brave Search API. Returns titles, URLs, and snippets. Optional AI-grounded summary. Rate limit: 10/day per user", {
     query: z.string().describe("Search query string"),
@@ -784,6 +826,57 @@ server.tool("chaprola_consolidate", "Merge a .MRG file into its parent .DA, prod
     const res = await authedFetch("/consolidate", { userid: username, project, file });
     return textResult(res);
 }));
+// --- Site Keys ---
+server.tool("chaprola_create_site_key", "Create an origin-locked site key for frontend JavaScript. Site keys are restricted to specific origins and endpoints, safe to embed in public code.", {
+    label: z.string().describe("Human-readable label for this key (e.g., 'poll-frontend')"),
+    allowed_origins: z.array(z.string()).describe("HTTPS URL patterns where this key works (e.g., ['https://chaprola.org/apps/poll/*']). Wildcards allowed at end."),
+    allowed_endpoints: z.array(z.string()).describe("API endpoints this key can call (e.g., ['/query', '/insert-record', '/report']). Security-sensitive endpoints like /export, /import, /compile are always denied."),
+}, async ({ label, allowed_origins, allowed_endpoints }) => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/create-site-key", {
+        userid: username,
+        label,
+        allowed_origins,
+        allowed_endpoints,
+    });
+    return textResult(res);
+});
+server.tool("chaprola_list_site_keys", "List all site keys for the authenticated user. Shows label, allowed origins/endpoints, and creation date.", {}, async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/list-site-keys", { userid: username });
+    return textResult(res);
+});
+server.tool("chaprola_delete_site_key", "Delete a site key. Requires the full site key value (site_...).", {
+    site_key: z.string().describe("The full site key to delete (starts with site_)"),
+}, async ({ site_key }) => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/delete-site-key", { userid: username, site_key });
+    return textResult(res);
+});
+// --- App Hosting tools ---
+server.tool("chaprola_app_deploy", "Deploy a static web app (HTML/JS/CSS) to chaprola.org/apps/{userid}/{project}/. Returns a presigned upload URL for a .zip or .tar.gz archive.", {
+    project: z.string().describe("Project name for the app"),
+}, async ({ project }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/app/deploy", { userid: username, project });
+    return textResult(res);
+}));
+server.tool("chaprola_app_deploy_process", "Process a staged app archive and deploy files to chaprola.org/apps/{userid}/{project}/", {
+    project: z.string().describe("Project name for the app"),
+    staging_key: z.string().describe("Staging key returned by chaprola_app_deploy"),
+}, async ({ project, staging_key }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/app/deploy/process", { userid: username, project, staging_key });
+    return textResult(res);
+}));
+server.tool("chaprola_app_upload", "Get a presigned URL to upload a single file to a deployed app at chaprola.org/apps/{userid}/{project}/{path}", {
+    project: z.string().describe("Project name for the app"),
+    path: z.string().describe("File path within the app (e.g. 'css/app.css', 'index.html')"),
+}, async ({ project, path }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/app/upload", { userid: username, project, path });
+    return textResult(res);
+}));
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chaprola/mcp-server",
-  "version": "1.4.3",
+  "version": "1.6.0",
   "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.",
   "type": "module",
   "main": "dist/index.js",

package/references/cookbook.md

@@ -13,6 +13,30 @@ POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "
 POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1}
 ```
 
+## R-Variable Ranges
+
+| Range | Purpose | Safe for DEFINE VARIABLE? |
+|-------|---------|--------------------------|
+| 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** |
+
+For non-HULDRA programs, R1–R40 are technically available but using R41–R50 is a good habit.
+
+## PRINT: Output from U Buffer
+
+```
+PRINT 0   — output the ENTIRE U buffer contents, then clear it
+PRINT N   — output exactly N characters from U buffer (no clear)
+```
+
+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.
+
+```chaprola
+MOVE "Hello" U.1 5
+PRINT 5    // Outputs "Hello" — exactly 5 chars, no trailing spaces
+```
+
 ## Hello World (no data file)
 
 ```chaprola
@@ -58,7 +82,25 @@ READ match                   // load matched secondary record
 MOVE S.dept_name U.12 15    // now accessible
 ```
 
-Compile with: `primary_format: "EMPLOYEES", secondary_format: "DEPARTMENTS"`
+Compile with both formats so the compiler resolves fields from both files:
+```bash
+POST /compile {
+  userid, project, name: "REPORT",
+  source: "...",
+  primary_format: "EMPLOYEES",
+  secondary_format: "DEPARTMENTS"
+}
+```
+
+## Comparing Two Memory Locations
+
+IF EQUAL compares a literal to a location. To compare two memory locations, copy both to U buffer:
+
+```chaprola
+MOVE PARAM.poll_id U.200 12
+MOVE P.poll_id U.180 12
+IF EQUAL U.200 U.180 12 GOTO 200   // match — jump to handler
+```
 
 ## Read-Modify-Write (UPDATE)
 
@@ -152,6 +194,19 @@ POST /query {
 }
 ```
 
+For simple aggregation without a cross-tabulation column, set `column` to empty string:
+```bash
+# Count records per department (no cross-tab)
+POST /query {
+  userid, project, file: "STAFF",
+  pivot: {
+    row: "department",
+    column: "",
+    values: [{field: "department", function: "count"}]
+  }
+}
+```
+
 Supported aggregate functions: `count`, `sum`, `avg`, `min`, `max`, `stddev`.
 
 ## PUT Format Codes
@@ -165,6 +220,19 @@ Supported aggregate functions: `count`, `sum`, `avg`, `min`, `max`, `stddev`.
 
 Syntax: `PUT R1 INTO U.30 10 D 2` (R-var, location, width, format, decimals)
 
+## Common Field Widths
+
+| Data type | Chars | Example |
+|-----------|-------|---------|
+| ISO datetime | 20 | `2026-03-28T14:30:00Z` |
+| UUID | 36 | `550e8400-e29b-41d4-a716-446655440000` |
+| Email | 50 | `user@example.com` |
+| Short ID | 8–12 | `poll_001` |
+| Dollar amount | 10 | `$1,234.56` |
+| Phone | 15 | `+1-555-123-4567` |
+
+Use these when sizing MOVE lengths and U buffer positions.
+
 ## Memory Regions
 
 | Prefix | Description |

package/references/endpoints.md

@@ -48,9 +48,9 @@ Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
 ### Query & Data Operations
 | Endpoint | Body | Response |
 |----------|------|----------|
-| `POST /query` | `{userid, project, file, where?, select?, aggregate?, order_by?, limit?, join?, pivot?, mercury?}` | `{records, total}` |
+| `POST /query` | `{userid, project, file, where?: [{field, op, value}], select?, aggregate?, order_by?, limit?, join?, pivot?, mercury?}` | `{records, total}` |
 | `POST /sort` | `{userid, project, file, sort_by}` | `{status: "ok"}` |
-| `POST /index` | `{userid, project, file, field}` | `{status: "ok"}` |
+| `POST /index` | `{userid, project, file, key_fields: ["field1", "field2"], output: "INDEXNAME"}` | `{status: "ok"}` |
 | `POST /merge` | `{userid, project, file_a, file_b, output, key}` | `{status: "ok"}` |
 
 ### Optimization (HULDRA)
@@ -82,6 +82,6 @@ Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
 ## Key Rules
 
 - `userid` in every request body must match the authenticated user (403 if not)
-- API keys never expire. Login generates a new key and invalidates the old one
+- API keys expire after 90 days. Login generates a new key (old keys remain valid until expiration)
 - BAA only required for PHI data. Non-PHI data works without signing a BAA
 - All `.DA` files expire after 90 days by default. Set `expires_in_days` on import to override (up to 36500 days)

package/references/gotchas.md

@@ -109,3 +109,32 @@ All outbound emails are AI-screened. Blocked emails return 403.
 
 ### PHI in email
 Emails containing PHI identifiers (names, SSNs, dates of birth, etc.) are blocked by the content moderator.
+
+## Concurrency Model
+
+### Last-write-wins is intentional, not a missing feature
+
+Chaprola uses **last-write-wins** instead of ACID transactions. This is a deliberate architectural choice, not a gap.
+
+**Why last-write-wins is often the right model:**
+
+ACID transactions solve one problem: what happens when two writers hit the same record simultaneously? Record locking, deadlock detection, lock wait queues, transaction logs, and rollback mechanisms all exist to answer that question.
+
+For most real-world data, the answer is: they don't. Application data is typically **partitioned by owner** — a user's settings, a user's records, a user's event history. One writer per partition. No contention. In these workloads, transaction machinery is pure overhead solving a problem that doesn't exist.
+
+Last-write-wins eliminates that overhead entirely. No lock acquisition. No lock wait. No deadlock detection. Every write goes straight through.
+
+**What Chaprola does provide:**
+
+- **Single-object atomicity**: Each S3 `put_object` either completes or fails — no partial writes within a single data file.
+- **Consolidation dirty-bit checks**: The `/consolidate` endpoint verifies the merge file wasn't modified during the operation. If it was, consolidation aborts.
+- **11-nines durability**: S3's 99.999999999% durability guarantee means your data survives once written.
+
+**What Chaprola does not provide:**
+
+- **Multi-object atomicity**: If you need "write record A and record B or neither," keep that logic in a relational database. Chaprola writes each object independently.
+- **Read-modify-write isolation**: Two agents reading the same record, modifying it, and writing back will result in last-write-wins. If you need compare-and-swap semantics, Chaprola is not the right tool for that specific operation.
+
+**When to use a relational database instead:**
+
+When multiple concurrent writers update the same record — financial ledgers, inventory counters, auction bidding. If your application has true multi-writer contention on shared records, use PostgreSQL or similar for that workload. But most application data is owner-partitioned, and for that, last-write-wins is the lighter, faster, correct choice.

package/references/quickstart.md

@@ -0,0 +1,30 @@
+# Chaprola Quickstart
+
+Base URL: `https://api.chaprola.org`
+Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
+Every request body's `userid` must match the authenticated username.
+
+## Core Workflow
+
+```bash
+POST /import {userid, project, name: "STAFF", data: [{name: "Alice", salary: 95000}, ...]}
+POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "STAFF"}
+POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1}
+```
+
+## Available References
+
+Read only what your app needs:
+
+| Resource | When to read |
+|----------|-------------|
+| `chaprola://ref/import` | Importing data, exporting, listing files |
+| `chaprola://ref/query` | Filtering, sorting, indexing, joining data |
+| `chaprola://ref/pivot` | GROUP BY / pivot tables |
+| `chaprola://ref/mercury` | Weighted scoring / ranking |
+| `chaprola://ref/programs` | Writing .CS source code (MOVE, LET, GET, PUT, SEEK, IF, GOTO, PRINT) |
+| `chaprola://ref/huldra` | Nonlinear optimization / parameter fitting |
+| `chaprola://ref/deploy` | Deploying static web apps to chaprola.org/apps/ |
+| `chaprola://ref/email` | Sending/receiving email via @chaprola.org |
+| `chaprola://ref/gotchas` | Common mistakes to avoid |
+| `chaprola://ref/auth` | Registration, login, BAA, credentials |

package/references/ref-auth.md

@@ -0,0 +1,25 @@
+# Authentication
+
+## API Key Model
+All protected requests: `Authorization: Bearer chp_your_api_key`
+Keys: `chp_` + 64 hex chars. Expire after 90 days.
+
+## Registration & Login
+```bash
+POST /register {"username": "my-agent", "passcode": "16-chars-minimum-passcode"}
+→ {"api_key": "chp_..."}
+
+POST /login {"username": "my-agent", "passcode": "..."}
+→ {"api_key": "chp_..."}  # old keys remain valid until expiration
+```
+- Passcode: 16-128 chars. Username: 3-40 chars, alphanumeric + hyphens/underscores.
+- Rate limits: auth 5 rps, data 20 rps.
+
+## BAA
+Only needed for PHI. Sign once: `POST /baa-text` → human reviews → `POST /sign-baa {userid, signatory_name}`.
+
+## MCP Environment Variables
+| Variable | Description |
+|----------|-------------|
+| `CHAPROLA_USERNAME` | Your registered username |
+| `CHAPROLA_API_KEY` | Your API key (`chp_...`) |

package/references/ref-deploy.md

@@ -0,0 +1,24 @@
+# App Deployment
+
+Deploy static web apps (HTML/JS/CSS) to `https://chaprola.org/apps/{userid}/{project}/`.
+
+## Flow
+```bash
+# 1. Get presigned upload URL
+POST /app/deploy {userid, project} → {upload_url, staging_key, max_size_mb: 50}
+
+# 2. Upload .zip or .tar.gz to upload_url
+PUT upload_url --data-binary @app.zip
+
+# 3. Extract and deploy
+POST /app/deploy/process {userid, project, staging_key} → {url, files_deployed}
+```
+
+## Single file upload
+```bash
+POST /app/upload {userid, project, path: "css/app.css"} → {upload_url, content_type}
+PUT upload_url --data-binary @app.css
+```
+
+Max 500 files per app. Blocked extensions: .php, .py, .sh, .exe.
+Content-Type set automatically from extension.

package/references/ref-email.md

@@ -0,0 +1,20 @@
+# Email (@chaprola.org)
+
+Every account gets `{username}@chaprola.org`.
+
+## Endpoints
+- `POST /email/inbox {address, limit?, before?}` → `{emails: [...], total}`
+- `POST /email/read {address, message_id}` → `{email: {from, to, subject, text, html, attachments}}`
+- `POST /email/send {from, to, subject, text, html?}` → `{status, message_id}`
+- `POST /email/delete {address, message_id}` → `{status}`
+- `POST /email/forward {from, message_id, to}` → `{status, resend_message_id}`
+
+## Attachments
+`/email/read` returns presigned download URLs (1hr expiry) for each attachment.
+`/email/forward` re-attaches stored attachments automatically.
+
+## Rate limits
+20 emails/day per user, 3 emails/minute. Outbound emails are AI content-moderated (blocks spam/PHI).
+
+## Delegates
+Agents can send as another user if listed in their delegate file. E.g., tawni can send `"from": "charles"`.

package/references/ref-gotchas.md

@@ -0,0 +1,23 @@
+# Gotchas
+
+## Language
+- **No parentheses in LET.** `LET result = price * qty` only. For `price * (qty + bonus)`: use `LET temp = qty + bonus` then `LET result = price * temp`.
+- **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.
+
+## API
+- **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).
+- **secondary_format is a string**, not an array.
+- **Data files expire.** Default 90 days. Override with `expires_in_days` on import.
+- **API keys expire after 90 days.** Re-login to get a new key.
+
+## Secondary Files
+- **One at a time.** CLOSE before opening another.
+- **CLOSE flushes writes.** Always CLOSE before END if you wrote to the secondary file.

package/references/ref-huldra.md

@@ -0,0 +1,78 @@
+# HULDRA — Nonlinear Optimization
+
+HULDRA finds optimal parameter values for a mathematical model by minimizing the difference between predictions and observed data.
+
+## R-Variable Interface
+
+| Range | Purpose | Who sets it |
+|-------|---------|-------------|
+| 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 |
+
+## POST /optimize
+```json
+{
+  "userid": "...", "project": "fit", "program": "SALFIT", "primary_file": "EMP",
+  "elements": [
+    {"index": 1, "label": "slope", "start": 5000, "min": 0, "max": 20000, "delta": 10},
+    {"index": 2, "label": "base", "start": 40000, "min": 0, "max": 100000, "delta": 100}
+  ],
+  "objectives": [
+    {"index": 1, "label": "SSR", "goal": 0.0, "weight": 1.0}
+  ],
+  "max_iterations": 100,
+  "async_exec": true
+}
+```
+
+Async: `POST /optimize/status {userid, project, job_id}`
+
+## Delta Guidance
+- Dollar amounts: `0.01` to `1.0`
+- Rates/percentages: `0.001` to `0.01`
+- Counts: `0.1` to `1.0`
+
+## Performance
+HULDRA runs your program `1 + 2 × N_elements` times per iteration. Lambda timeout: 900s. Sample large datasets (200-500 records) before optimizing.
+
+## Complete Example: Linear Fit
+`salary = R1 × years_exp + R2`
+
+```chaprola
+DEFINE VARIABLE REC R41
+DEFINE VARIABLE YRS R42
+DEFINE VARIABLE SAL R43
+DEFINE VARIABLE PRED R44
+DEFINE VARIABLE RESID R45
+DEFINE VARIABLE SSR R46
+
+LET SSR = 0          // MUST initialize to 0
+LET REC = 1
+100 SEEK REC
+    IF EOF GOTO 200
+    GET YRS FROM P.years_exp
+    GET SAL FROM P.salary
+    LET PRED = R1 * YRS
+    LET PRED = PRED + R2
+    LET RESID = PRED - SAL
+    LET RESID = RESID * RESID
+    LET SSR = SSR + RESID
+    LET REC = REC + 1
+    GOTO 100
+200 LET R21 = SSR
+    END
+```
+
+## Model Catalog
+
+| Model | Formula | When to use |
+|-------|---------|-------------|
+| Linear | `y = R1*x + R2` | Proportional relationships |
+| Multi-linear | `y = R1*x1 + R2*x2 + R3` | Multiple factors |
+| Quadratic | `y = R1*x^2 + R2*x + R3` | Accelerating curves |
+| Exponential | `y = R1 * EXP(R2*x)` | Compound growth |
+| Exp. decay | `y = R1 * EXP(-R2*x) + R3` | Decay, cooling |
+| Power law | `y = R1 * POW(x, R2)` | Scaling laws |
+| Logarithmic | `y = R1 * LOG(x) + R2` | Diminishing returns |
+| Logistic | `y = R1 / (1 + EXP(-R2*(x-R3)))` | S-curves, saturation |

package/references/ref-import.md

@@ -0,0 +1,34 @@
+# Import / Export / Files
+
+## POST /import
+`{userid, project, name, data: [{...}, ...], format?, expires_in_days?, force?}`
+Returns: `{records, fields, record_length, format_file, data_file}`
+
+```bash
+POST /import {userid, project, name: "STAFF", data: [{"name": "Alice", "salary": 95000}]}
+```
+
+Field widths auto-sized from longest value. Default expiry: 90 days. Override with `expires_in_days`.
+
+## Large File Upload (presigned URL)
+```bash
+POST /import-url {userid, project, name} → {upload_url, staging_key}
+# PUT your JSON to upload_url
+POST /import-process {userid, project, name, staging_key} → same as /import
+```
+
+## 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.
+
+## POST /export
+`{userid, project, name, format?}` → `{data: [...records]}`
+Optional `format: "fhir"` for FHIR JSON reconstruction.
+
+## POST /list
+`{userid, project, pattern?}` → `{files: [...], total}`
+
+## POST /download
+`{userid, project, file, type}` → `{download_url, expires_in, size_bytes}`
+Type: `data`, `format`, `source`, `proc`, `output`.

package/references/ref-mercury.md

@@ -0,0 +1,23 @@
+# Mercury (Weighted Scoring)
+
+Add `mercury` to `/query` to score and rank records by weighted criteria.
+
+```json
+POST /query {
+  "userid": "...", "project": "...", "file": "CANDIDATES",
+  "mercury": {
+    "scores": [
+      {"field": "experience_years", "weight": 0.4, "direction": "higher_better"},
+      {"field": "interview_score", "weight": 0.35, "direction": "higher_better"},
+      {"field": "salary_ask", "weight": 0.25, "direction": "lower_better"}
+    ]
+  },
+  "limit": 10
+}
+```
+
+Returns records ranked by composite score (0-100). Each record includes `_mercury_score` and per-field `_mercury_{field}` component scores.
+
+Fields are normalized min-max within the dataset. `direction` controls whether higher or lower raw values score better. Weights must sum to 1.0.
+
+Combine with `where` to pre-filter before scoring.

package/references/ref-pivot.md

@@ -0,0 +1,32 @@
+# Pivot (GROUP BY)
+
+Chaprola's pivot IS GROUP BY. Add `pivot` to `/query`.
+
+## Simple aggregation (no cross-tab)
+```json
+POST /query {
+  "userid": "...", "project": "...", "file": "STAFF",
+  "pivot": {
+    "row": "department",
+    "column": "",
+    "values": [
+      {"field": "department", "function": "count"},
+      {"field": "salary", "function": "avg"}
+    ]
+  }
+}
+```
+SQL equivalent: `SELECT department, COUNT(*), AVG(salary) FROM staff GROUP BY department`
+
+## Cross-tabulation
+```json
+"pivot": {
+  "row": "department",
+  "column": "year",
+  "values": [{"field": "revenue", "function": "sum"}],
+  "totals": true
+}
+```
+SQL equivalent: `SELECT department, year, SUM(revenue) FROM sales GROUP BY department, year`
+
+Supported functions: `count`, `sum`, `avg`, `min`, `max`, `stddev`.

package/references/ref-programs.md

@@ -0,0 +1,85 @@
+# Chaprola Programs (.CS Source)
+
+## Compile & Run
+```bash
+POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "STAFF", secondary_format?: "DEPTS"}
+POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1, async?: true, nophi?: true}
+POST /run/status {userid, project, job_id}  # poll async jobs
+POST /publish {userid, project, name, primary_file, acl?: "public|authenticated|owner|token"}
+```
+
+## Memory Regions
+
+| 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) |
+
+## Language Essentials
+
+```chaprola
+// Loop through records
+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
+    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).
+
+## PUT Format Codes
+
+| Code | Description | Example |
+|------|-------------|---------|
+| `D` | Dollar with commas | `$1,234.56` |
+| `F` | Fixed decimal | `1234.56` |
+| `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)
+
+## Math
+
+```chaprola
+LET R42 = R41 + 1       // one operation per LET
+LET R43 = EXP R41       // also: LOG, SQRT, ABS
+LET R44 = POW R41 R42   // R41^R42
+```
+
+## Secondary Files (FIND/JOIN)
+
+```chaprola
+OPEN "DEPARTMENTS" 0              // open secondary file
+FIND match FROM S.dept_code 3 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
+WRITE match                       // write back if modified
+CLOSE                             // flush + close
+```
+
+Compile with: `secondary_format: "DEPARTMENTS"`
+
+## Parameterized Reports (PARAM.name)
+```chaprola
+MOVE PARAM.deck U.1 20           // string param → U buffer
+LET lvl = PARAM.level            // numeric param → R variable
+```
+Publish, then call: `POST /report?userid=X&project=Y&name=Z&deck=kanji&level=3`
+Discover params: `POST /report/params {userid, project, name}`
+
+## Common Field Widths
+ISO datetime: 20, UUID: 36, email: 50, short ID: 8-12, dollar: 10, phone: 15.

package/references/ref-query.md

@@ -0,0 +1,40 @@
+# Query / Sort / Index / Merge
+
+## POST /query
+```json
+{
+  "userid": "...", "project": "...", "file": "STAFF",
+  "where": [{"field": "salary", "op": "gt", "value": 80000}],
+  "where_logic": "and",
+  "select": ["name", "salary"],
+  "aggregate": [{"field": "salary", "function": "avg"}],
+  "order_by": "salary desc",
+  "limit": 100,
+  "offset": 0
+}
+```
+Returns: `{records: [...], total, fields}`
+
+WHERE operators: `eq`, `ne`, `gt`, `ge`, `lt`, `le`, `between`, `contains`, `starts_with`, `ends_with`
+
+## JOIN
+Add `join` to /query:
+```json
+"join": {"file": "DEPARTMENTS", "on": {"left": "dept_id", "right": "dept_id"}, "type": "inner"}
+```
+Types: `inner`, `left`, `right`, `full`. Optional `pre_sorted: true` for merge join.
+
+## POST /sort
+`{userid, project, file, sort_by: "salary desc"}`
+
+## POST /index
+`{userid, project, file, key_fields: ["dept_id"], output: "STAFF_BY_DEPT"}`
+
+## POST /merge
+`{userid, project, file_a, file_b, output, key}`
+
+## Record CRUD
+- `POST /insert-record {userid, project, file, record: {field: "value"}}`
+- `POST /update-record {userid, project, file, where: [...], set: {field: "value"}}`
+- `POST /delete-record {userid, project, file, where: [...]}`
+- `POST /consolidate {userid, project, file}` — merge .MRG into .DA