@chaprola/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,144 @@
+# @chaprola/mcp-server
+
+MCP server for [Chaprola](https://chaprola.org) — the agent-first data platform.
+
+Gives AI agents 35 tools for structured data storage, querying, compilation, and execution through the [Model Context Protocol](https://modelcontextprotocol.io).
+
+## Quick Start
+
+### Claude Code
+
+```bash
+claude mcp add chaprola-mcp -e CHAPROLA_USERNAME=yourusername -e CHAPROLA_API_KEY=chp_yourkey -- npx @chaprola/mcp-server
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "chaprola": {
+      "command": "npx",
+      "args": ["@chaprola/mcp-server"],
+      "env": {
+        "CHAPROLA_USERNAME": "yourusername",
+        "CHAPROLA_API_KEY": "chp_yourkey"
+      }
+    }
+  }
+}
+```
+
+### VS Code / Copilot
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "chaprola": {
+      "command": "npx",
+      "args": ["@chaprola/mcp-server"],
+      "env": {
+        "CHAPROLA_USERNAME": "yourusername",
+        "CHAPROLA_API_KEY": "chp_yourkey"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "chaprola": {
+      "command": "npx",
+      "args": ["@chaprola/mcp-server"],
+      "env": {
+        "CHAPROLA_USERNAME": "yourusername",
+        "CHAPROLA_API_KEY": "chp_yourkey"
+      }
+    }
+  }
+}
+```
+
+## Getting Credentials
+
+```bash
+# Register (returns your API key — save it immediately)
+curl -X POST https://api.chaprola.org/register \
+  -H "Content-Type: application/json" \
+  -d '{"username": "myname", "passcode": "my-secure-passcode-16chars"}'
+```
+
+Or use the `chaprola_register` tool after connecting.
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `chaprola_hello` | Health check |
+| `chaprola_register` | Create account |
+| `chaprola_login` | Login (get new API key) |
+| `chaprola_check_username` | Check username availability |
+| `chaprola_delete_account` | Delete account + all data |
+| `chaprola_sign_baa` | Sign Business Associate Agreement (PHI only) |
+| `chaprola_baa_status` | Check BAA status |
+| `chaprola_baa_text` | Get BAA text |
+| `chaprola_import` | Import JSON to Chaprola format |
+| `chaprola_import_url` | Get presigned upload URL |
+| `chaprola_import_process` | Process uploaded file |
+| `chaprola_import_download` | Import from URL (CSV/Excel/JSON/Parquet) |
+| `chaprola_export` | Export to JSON |
+| `chaprola_list` | List files |
+| `chaprola_compile` | Compile .CS source to .PR bytecode |
+| `chaprola_run` | Execute .PR program |
+| `chaprola_run_status` | Check async job status |
+| `chaprola_publish` | Publish program for public access |
+| `chaprola_unpublish` | Remove public access |
+| `chaprola_report` | Run published program (no auth) |
+| `chaprola_export_report` | Run program and save output |
+| `chaprola_download` | Get presigned download URL |
+| `chaprola_query` | Filter, aggregate, join data |
+| `chaprola_sort` | Sort data file |
+| `chaprola_index` | Build index on field |
+| `chaprola_merge` | Merge two sorted files |
+| `chaprola_optimize` | HULDRA nonlinear optimization |
+| `chaprola_optimize_status` | Check optimization status |
+| `chaprola_email_inbox` | List emails |
+| `chaprola_email_read` | Read email |
+| `chaprola_email_send` | Send email |
+| `chaprola_email_delete` | Delete email |
+
+## Resources
+
+The server exposes reference documentation as MCP resources:
+
+- `chaprola://cookbook` — Language cookbook with complete examples
+- `chaprola://endpoints` — All 35 API endpoints
+- `chaprola://auth` — Authentication reference
+- `chaprola://gotchas` — Common mistakes to avoid
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CHAPROLA_USERNAME` | Yes | Your registered username |
+| `CHAPROLA_API_KEY` | Yes | Your API key (format: `chp_` + 64 hex chars) |
+
+## HIPAA / BAA
+
+Non-PHI data works without a signed BAA. If handling Protected Health Information (PHI), a human must review and sign the BAA first. The server includes guardrails that warn agents when the BAA is not signed.
+
+## Links
+
+- Website: [chaprola.org](https://chaprola.org)
+- API: [api.chaprola.org](https://api.chaprola.org/hello)
+- Status: [UptimeRobot](https://stats.uptimerobot.com/1gkN4Tx0RX)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,587 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const BASE_URL = "https://api.chaprola.org";
+// --- Auth helper ---
+function getCredentials() {
+    const username = process.env.CHAPROLA_USERNAME;
+    const apiKey = process.env.CHAPROLA_API_KEY;
+    if (!username || !apiKey) {
+        throw new Error("CHAPROLA_USERNAME and CHAPROLA_API_KEY environment variables are required. " +
+            "Register at POST https://api.chaprola.org/register to get an API key.");
+    }
+    return { username, apiKey };
+}
+async function authedFetch(path, body) {
+    const { apiKey } = getCredentials();
+    return fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "Authorization": `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(body),
+    });
+}
+async function publicFetch(method, path, body) {
+    const opts = {
+        method,
+        headers: { "Content-Type": "application/json" },
+    };
+    if (body && method === "POST") {
+        opts.body = JSON.stringify(body);
+    }
+    return fetch(`${BASE_URL}${path}`, opts);
+}
+async function textResult(res) {
+    const text = await res.text();
+    return { content: [{ type: "text", text }] };
+}
+// --- BAA guardrail ---
+let baaStatusCache = null;
+const BAA_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+async function checkBaaStatus() {
+    const now = Date.now();
+    if (baaStatusCache && (now - baaStatusCache.checkedAt) < BAA_CACHE_TTL_MS) {
+        return baaStatusCache.signed;
+    }
+    try {
+        const { username } = getCredentials();
+        const res = await authedFetch("/baa-status", { userid: username });
+        const data = await res.json();
+        const signed = data.signed === true;
+        baaStatusCache = { signed, checkedAt: now };
+        return signed;
+    }
+    catch {
+        // Fail open — let the server enforce
+        return true;
+    }
+}
+async function baaGuard() {
+    const signed = await checkBaaStatus();
+    if (!signed) {
+        return ("NOTE: BAA not signed. Non-PHI data operations will work normally without a BAA.\n" +
+            "If this data contains Protected Health Information (PHI), a human MUST review and\n" +
+            "approve the BAA before proceeding. DO NOT sign the BAA automatically — a human\n" +
+            "must explicitly confirm after reading the full BAA text.\n" +
+            "To sign: call chaprola_baa_text, show the full text to the human, and only call\n" +
+            "chaprola_sign_baa after they explicitly approve.");
+    }
+    return null;
+}
+async function withBaaCheck(fn) {
+    const warning = await baaGuard();
+    const result = await fn();
+    if (warning) {
+        // Prepend warning to the result
+        const existingText = result.content[0]?.text || "";
+        return { content: [{ type: "text", text: warning + "\n\n---\n\n" + existingText }] };
+    }
+    return result;
+}
+// --- Server setup ---
+const server = new McpServer({
+    name: "chaprola",
+    version: "1.0.0",
+});
+// --- MCP Resources (language reference for agents) ---
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Try multiple paths: installed package (dist/references/), dev mode (../../references/)
+function findRefsDir() {
+    const candidates = [
+        join(__dirname, "..", "references"), // installed: dist/../references/
+        join(__dirname, "..", "..", "references"), // dev (tsx): src/../../references/
+    ];
+    for (const dir of candidates) {
+        try {
+            readFileSync(join(dir, "cookbook.md"), "utf-8");
+            return dir;
+        }
+        catch { /* try next */ }
+    }
+    return candidates[0]; // fallback
+}
+const refsDir = findRefsDir();
+function readRef(filename) {
+    try {
+        return readFileSync(join(refsDir, filename), "utf-8");
+    }
+    catch {
+        return `(Could not load ${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 () => ({
+    contents: [{ uri: "chaprola://gotchas", mimeType: "text/markdown", text: readRef("gotchas.md") }],
+}));
+server.resource("endpoints", "chaprola://endpoints", { description: "Chaprola API endpoint reference — all 35 endpoints with request/response shapes", mimeType: "text/markdown" }, async () => ({
+    contents: [{ uri: "chaprola://endpoints", mimeType: "text/markdown", text: readRef("endpoints.md") }],
+}));
+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") }],
+}));
+// --- MCP Prompts ---
+server.prompt("chaprola-guide", "Essential guide for working with Chaprola. Read this before writing any Chaprola source code.", async () => ({
+    messages: [{
+            role: "user",
+            content: {
+                type: "text",
+                text: "# Chaprola Quick Reference\n\n" +
+                    "Chaprola is NOT a general-purpose language. Key differences:\n\n" +
+                    "## Syntax Rules\n" +
+                    "- 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" +
+                    "- 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" +
+                    "```\n" +
+                    "DEFINE VARIABLE rec R1\n" +
+                    "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" +
+                    "    LET rec = rec + 1\n" +
+                    "    GOTO 100\n" +
+                    "900 END\n" +
+                    "```\n\n" +
+                    "## BAA Policy\n" +
+                    "- Non-PHI data works WITHOUT a signed BAA\n" +
+                    "- NEVER sign the BAA automatically — a human must read and explicitly approve\n" +
+                    "- Only needed when handling Protected Health Information (PHI)\n\n" +
+                    "Read chaprola://cookbook and chaprola://gotchas for full reference.",
+            },
+        }],
+}));
+// ============================================================
+// PUBLIC ENDPOINTS (no auth required)
+// ============================================================
+server.tool("chaprola_hello", "Health check — verify the Chaprola API is running", { name: z.string().optional().describe("Name to greet (default: world)") }, async ({ name }) => {
+    const url = name ? `${BASE_URL}/hello?name=${encodeURIComponent(name)}` : `${BASE_URL}/hello`;
+    const res = await fetch(url);
+    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"),
+}, async ({ username, passcode }) => {
+    const res = await publicFetch("POST", "/register", { username, passcode });
+    return textResult(res);
+});
+server.tool("chaprola_login", "Login and get a new API key. WARNING: invalidates the previous API key", {
+    username: z.string().describe("Your registered username"),
+    passcode: z.string().describe("Your passcode"),
+}, async ({ username, passcode }) => {
+    const res = await publicFetch("POST", "/login", { username, passcode });
+    return textResult(res);
+});
+server.tool("chaprola_check_username", "Check if a username is available before registering", { username: z.string().describe("Username to check") }, async ({ username }) => {
+    const res = await publicFetch("POST", "/check-username", { username });
+    return textResult(res);
+});
+server.tool("chaprola_delete_account", "Delete an account and all associated data. Requires passcode confirmation", {
+    username: z.string().describe("Account username to delete"),
+    passcode: z.string().describe("Account passcode for confirmation"),
+}, async ({ username, passcode }) => {
+    const res = await publicFetch("POST", "/delete-account", { username, passcode });
+    return textResult(res);
+});
+server.tool("chaprola_baa_text", "Get the current Business Associate Agreement text and version. Present to human for review before signing", {}, async () => {
+    const res = await publicFetch("POST", "/baa-text", {});
+    return textResult(res);
+});
+server.tool("chaprola_report", "Run a published program and return output. No auth required — program must be published first", {
+    userid: z.string().describe("Owner of the published program"),
+    project: z.string().describe("Project containing the program"),
+    name: z.string().describe("Name of the published .PR file"),
+    primary_file: z.string().optional().describe("Data file to load"),
+}, async ({ userid, project, name, primary_file }) => {
+    const body = { userid, project, name };
+    if (primary_file)
+        body.primary_file = primary_file;
+    const res = await publicFetch("POST", "/report", body);
+    return textResult(res);
+});
+// ============================================================
+// AUTHENTICATED ENDPOINTS
+// ============================================================
+// --- BAA ---
+server.tool("chaprola_sign_baa", "Sign the BAA. STOP: You MUST call chaprola_baa_text first, show the FULL text to the human, and get their EXPLICIT typed approval before calling this. Never sign automatically. Only needed for PHI — non-PHI data works without a BAA.", {
+    signatory_name: z.string().describe("Full name of the person agreeing to the BAA"),
+    signatory_title: z.string().optional().describe("Title of the signatory"),
+    organization: z.string().optional().describe("Organization name (the Covered Entity)"),
+}, async ({ signatory_name, signatory_title, organization }) => {
+    const { username } = getCredentials();
+    const body = { userid: username, signatory_name };
+    if (signatory_title)
+        body.signatory_title = signatory_title;
+    if (organization)
+        body.organization = organization;
+    const res = await authedFetch("/sign-baa", body);
+    return textResult(res);
+});
+server.tool("chaprola_baa_status", "Check whether the authenticated user has signed the BAA", {}, async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/baa-status", { userid: username });
+    return textResult(res);
+});
+// --- Import ---
+server.tool("chaprola_import", "Import JSON data into Chaprola format files (.F + .DA). 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"),
+    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 () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name, data };
+    if (format)
+        body.format = format;
+    if (expires_in_days)
+        body.expires_in_days = expires_in_days;
+    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)", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("File name (without extension)"),
+}, async ({ project, name }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    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", {
+    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"),
+}, async ({ project, name, format }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name };
+    if (format)
+        body.format = format;
+    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", {
+    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)"),
+    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 () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name, url };
+    if (instructions)
+        body.instructions = instructions;
+    if (max_rows)
+        body.max_rows = max_rows;
+    const res = await authedFetch("/import-download", body);
+    return textResult(res);
+}));
+// --- Export ---
+server.tool("chaprola_export", "Export Chaprola .DA + .F files back to JSON", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("File name (without extension)"),
+}, async ({ project, name }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/export", { userid: username, project, name });
+    return textResult(res);
+}));
+// --- List ---
+server.tool("chaprola_list", "List files in a project with optional wildcard pattern", {
+    project: z.string().describe("Project name (use * for all projects)"),
+    pattern: z.string().optional().describe("Wildcard pattern to filter files (e.g., EMP*)"),
+}, async ({ project, pattern }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project };
+    if (pattern)
+        body.pattern = pattern;
+    const res = await authedFetch("/list", body);
+    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_formats params.", {
+    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_formats: z.array(z.string()).optional().describe("Secondary format file names (enables S.fieldname addressing)"),
+}, async ({ project, name, source, primary_format, secondary_formats }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name, source };
+    if (primary_format)
+        body.primary_format = primary_format;
+    if (secondary_formats)
+        body.secondary_formats = secondary_formats;
+    const res = await authedFetch("/compile", body);
+    return textResult(res);
+}));
+// --- Run ---
+server.tool("chaprola_run", "Execute a compiled .PR program. Use async:true for large datasets (>100K records)", {
+    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"),
+    record: z.number().optional().describe("Starting record number"),
+    async_exec: z.boolean().optional().describe("If true, run asynchronously and return job_id for polling"),
+    secondary_files: z.array(z.string()).optional().describe("Secondary files to make available"),
+    nophi: z.boolean().optional().describe("If true, obfuscate PHI-flagged fields during execution"),
+}, async ({ project, name, primary_file, record, async_exec, secondary_files, nophi }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name };
+    if (primary_file)
+        body.primary_file = primary_file;
+    if (record !== undefined)
+        body.record = record;
+    if (async_exec !== undefined)
+        body.async = async_exec;
+    if (secondary_files)
+        body.secondary_files = secondary_files;
+    if (nophi !== undefined)
+        body.nophi = nophi;
+    const res = await authedFetch("/run", body);
+    return textResult(res);
+}));
+server.tool("chaprola_run_status", "Check status of an async job. Returns full output when done", {
+    project: z.string().describe("Project name"),
+    job_id: z.string().describe("Job ID from async /run response"),
+}, async ({ project, job_id }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/run/status", { userid: username, project, job_id });
+    return textResult(res);
+}));
+// --- Publish ---
+server.tool("chaprola_publish", "Publish a compiled program for public access via /report", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("Program name to publish"),
+    primary_file: z.string().optional().describe("Data file to load when running the report"),
+    record: z.number().optional().describe("Starting record number"),
+}, async ({ project, name, primary_file, record }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name };
+    if (primary_file)
+        body.primary_file = primary_file;
+    if (record !== undefined)
+        body.record = record;
+    const res = await authedFetch("/publish", body);
+    return textResult(res);
+}));
+server.tool("chaprola_unpublish", "Remove public access from a published program", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("Program name to unpublish"),
+}, async ({ project, name }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/unpublish", { userid: username, project, name });
+    return textResult(res);
+}));
+// --- Export Report ---
+server.tool("chaprola_export_report", "Run a .PR program and save output as a persistent .R file in S3", {
+    project: z.string().describe("Project name"),
+    name: z.string().describe("Program name"),
+    primary_file: z.string().optional().describe("Primary data file to load"),
+    report_name: z.string().optional().describe("Custom output file name"),
+    format: z.enum(["text", "pdf", "csv", "json", "xlsx"]).optional().describe("Output format (default: text)"),
+    title: z.string().optional().describe("Report title (used in PDF header)"),
+    nophi: z.boolean().optional().describe("If true, obfuscate PHI-flagged fields"),
+}, async ({ project, name, primary_file, report_name, format, title, nophi }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, name };
+    if (primary_file)
+        body.primary_file = primary_file;
+    if (report_name)
+        body.report_name = report_name;
+    if (format)
+        body.format = format;
+    if (title)
+        body.title = title;
+    if (nophi !== undefined)
+        body.nophi = nophi;
+    const res = await authedFetch("/export-report", body);
+    return textResult(res);
+}));
+// --- Download ---
+server.tool("chaprola_download", "Get a presigned S3 URL to download any file you own (1-hour expiry)", {
+    project: z.string().describe("Project name"),
+    file: z.string().describe("File name with extension (e.g., REPORT.R)"),
+    type: z.enum(["data", "format", "source", "proc", "output"]).describe("File type directory"),
+}, async ({ project, file, type }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/download", { userid: username, project, file, type });
+    return textResult(res);
+}));
+// --- Query ---
+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"),
+    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}]"),
+    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 () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, file };
+    if (where)
+        body.where = where;
+    if (select)
+        body.select = select;
+    if (aggregate)
+        body.aggregate = aggregate;
+    if (order_by)
+        body.order_by = order_by;
+    if (limit !== undefined)
+        body.limit = limit;
+    if (offset !== undefined)
+        body.offset = offset;
+    if (join)
+        body.join = join;
+    if (pivot)
+        body.pivot = pivot;
+    if (mercury)
+        body.mercury = mercury;
+    const res = await authedFetch("/query", body);
+    return textResult(res);
+}));
+// --- Sort ---
+server.tool("chaprola_sort", "Sort a data file by one or more fields. Modifies the file in place", {
+    project: z.string().describe("Project name"),
+    file: z.string().describe("Data file to sort"),
+    sort_by: z.array(z.object({
+        field: z.string(),
+        dir: z.enum(["asc", "desc"]).optional(),
+        type: z.enum(["text", "numeric"]).optional(),
+    })).describe("Sort specification: [{field, dir?, type?}]"),
+}, async ({ project, file, sort_by }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/sort", { userid: username, project, file, sort_by });
+    return textResult(res);
+}));
+// --- Index ---
+server.tool("chaprola_index", "Build an index file (.IDX) for fast lookups on a field", {
+    project: z.string().describe("Project name"),
+    file: z.string().describe("Data file to index"),
+    field: z.string().describe("Field name to index"),
+}, async ({ project, file, field }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/index", { userid: username, project, file, field });
+    return textResult(res);
+}));
+// --- Merge ---
+server.tool("chaprola_merge", "Merge two sorted data files into one. Both must share the same format (.F)", {
+    project: z.string().describe("Project name"),
+    file_a: z.string().describe("First data file"),
+    file_b: z.string().describe("Second data file"),
+    output: z.string().describe("Output file name"),
+    key: z.string().describe("Merge key field"),
+}, async ({ project, file_a, file_b, output, key }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/merge", { userid: username, project, file_a, file_b, output, key });
+    return textResult(res);
+}));
+// --- Optimize (HULDRA) ---
+server.tool("chaprola_optimize", "Run HULDRA nonlinear optimization using a compiled .PR as the objective evaluator", {
+    project: z.string().describe("Project name"),
+    program: z.string().describe("Compiled .PR program name (the VALUE program)"),
+    primary_file: z.string().describe("Data file to pass to the VALUE program"),
+    elements: z.array(z.object({
+        index: z.number().describe("R-variable index (1-20)"),
+        label: z.string(),
+        start: z.number(),
+        min: z.number(),
+        max: z.number(),
+        delta: z.number(),
+    })).describe("Parameters to optimize"),
+    objectives: z.array(z.object({
+        index: z.number().describe("R-variable index (1-20) — maps to R(20+index)"),
+        label: z.string(),
+        goal: z.number(),
+        weight: z.number(),
+    })).describe("Objective values to minimize"),
+    max_iterations: z.number().optional().describe("Max iterations (default: 100)"),
+    h_initial: z.number().optional().describe("Initial step fraction (default: 0.125)"),
+    async_exec: z.boolean().optional().describe("If true, return job_id for long optimizations"),
+}, async ({ project, program, primary_file, elements, objectives, max_iterations, h_initial, async_exec }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { userid: username, project, program, primary_file, elements, objectives };
+    if (max_iterations !== undefined)
+        body.max_iterations = max_iterations;
+    if (h_initial !== undefined)
+        body.h_initial = h_initial;
+    if (async_exec !== undefined)
+        body.async = async_exec;
+    const res = await authedFetch("/optimize", body);
+    return textResult(res);
+}));
+server.tool("chaprola_optimize_status", "Check status of an async optimization job", {
+    project: z.string().describe("Project name"),
+    job_id: z.string().describe("Job ID from async /optimize response"),
+}, async ({ project, job_id }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/optimize/status", { userid: username, project, job_id });
+    return textResult(res);
+}));
+// --- Email ---
+server.tool("chaprola_email_inbox", "List emails in the authenticated user's mailbox", {
+    limit: z.number().optional().describe("Max emails to return (default 20, max 100)"),
+    before: z.string().optional().describe("ISO 8601 timestamp — return emails before this time"),
+}, async ({ limit, before }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { address: username };
+    if (limit !== undefined)
+        body.limit = limit;
+    if (before)
+        body.before = before;
+    const res = await authedFetch("/email/inbox", body);
+    return textResult(res);
+}));
+server.tool("chaprola_email_read", "Read a specific email by message_id", {
+    message_id: z.string().describe("Message ID from inbox listing"),
+}, async ({ message_id }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/email/read", { address: username, message_id });
+    return textResult(res);
+}));
+server.tool("chaprola_email_send", "Send an email from your @chaprola.org address. Subject to content moderation", {
+    to: z.string().describe("Recipient email address"),
+    subject: z.string().describe("Email subject"),
+    text: z.string().describe("Plain text body"),
+    html: z.string().optional().describe("HTML body"),
+    from: z.string().optional().describe("Sender local part (default: your username)"),
+}, async ({ to, subject, text, html, from }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const body = { from: from || username, to, subject, text };
+    if (html)
+        body.html = html;
+    const res = await authedFetch("/email/send", body);
+    return textResult(res);
+}));
+server.tool("chaprola_email_delete", "Delete a specific email from your mailbox", {
+    message_id: z.string().describe("Message ID to delete"),
+}, async ({ message_id }) => withBaaCheck(async () => {
+    const { username } = getCredentials();
+    const res = await authedFetch("/email/delete", { address: username, message_id });
+    return textResult(res);
+}));
+// --- Start server ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@chaprola/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for Chaprola — agent-first data platform. Gives AI agents 35 tools for structured data storage, querying, compilation, and execution via plain HTTP.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "chaprola-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "references"
+  ],
+  "scripts": {
+    "start": "node dist/index.js",
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chaprola",
+    "data-platform",
+    "ai-agent",
+    "serverless",
+    "healthcare",
+    "hipaa"
+  ],
+  "author": "Charles Letcher",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cletcher/chaprola"
+  },
+  "homepage": "https://chaprola.org",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3"
+  }
+}

package/references/auth.md

@@ -0,0 +1,63 @@
+# Chaprola Authentication — Agent Reference
+
+## API Key Model
+
+Chaprola uses API key authentication. Every protected request requires:
+
+```
+Authorization: Bearer chp_a1b2c3d4...
+```
+
+API keys have the format `chp_` + 64 hex characters (256 bits entropy, total 68 chars).
+
+## Getting an API Key
+
+```bash
+# Register (one-time)
+POST /register {"username": "my-agent", "passcode": "a-long-secure-passcode-16-chars-min"}
+# Response: {"status": "registered", "username": "my-agent", "api_key": "chp_..."}
+
+# Login (generates new key, INVALIDATES previous key)
+POST /login {"username": "my-agent", "passcode": "a-long-secure-passcode-16-chars-min"}
+# Response: {"status": "authenticated", "username": "my-agent", "api_key": "chp_..."}
+```
+
+## Key Facts
+
+- **API keys never expire.** Only invalidated by re-login or account deletion.
+- **Login replaces the key.** Old key stops working immediately. Save the new one.
+- **Passcode requirements:** 16-128 characters.
+- **Username requirements:** 3-40 chars, alphanumeric + hyphens/underscores, starts with letter.
+- **Userid must match.** Every request body's `userid` field must match the authenticated username (403 if not).
+- **Rate limits:** Auth endpoints: 5 req/sec (burst 10). All others: 20 req/sec (burst 50).
+
+## BAA (Business Associate Agreement)
+
+All data endpoints require a signed BAA. Without it, requests return 403.
+
+**Flow:**
+1. `POST /baa-text` → get BAA text (show to human)
+2. Human reviews and agrees
+3. `POST /sign-baa` → sign it (one-time per account)
+4. `POST /baa-status` → verify signing status
+
+**Exempt endpoints** (no BAA required): /hello, /register, /login, /check-username, /delete-account, /sign-baa, /baa-status, /baa-text, /report, /email/inbound
+
+## MCP Server Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `CHAPROLA_USERNAME` | Your registered username |
+| `CHAPROLA_API_KEY` | Your API key (`chp_...`) |
+
+These are read by the MCP server and injected into every authenticated request automatically.
+
+## Credential Recovery
+
+If your API key stops working (403):
+1. Re-login with your passcode → get new API key
+2. If passcode lost → admin must create `s3://chaprola-2026/admin/reset/{username}.reset`, then login with any new passcode
+
+## Account Cleanup
+
+Accounts inactive for 90 days (no authenticated API calls) are automatically deleted with all files.

package/references/cookbook.md

@@ -0,0 +1,152 @@
+# Chaprola Cookbook — Quick Reference
+
+## Workflow: Import → Compile → Run
+
+```bash
+# 1. Import JSON data
+POST /import {userid, project, name: "STAFF", data: [{name: "Alice", salary: 95000}, ...]}
+
+# 2. Compile source (pass primary_format for field-name addressing)
+POST /compile {userid, project, name: "REPORT", source: "...", primary_format: "STAFF"}
+
+# 3. Run program
+POST /run {userid, project, name: "REPORT", primary_file: "STAFF", record: 1}
+```
+
+## Hello World (no data file)
+
+```chaprola
+MOVE "Hello from Chaprola!" U.1 20
+PRINT 0
+END
+```
+
+## Loop Through All Records
+
+```chaprola
+DEFINE VARIABLE rec R1
+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
+    LET rec = rec + 1
+    GOTO 100
+900 END
+```
+
+## Filtered Report
+
+```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
+200 LET rec = rec + 1
+```
+
+## JOIN Two Files (FIND)
+
+```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
+```
+
+Compile with: `primary_format: "EMPLOYEES", secondary_formats: ["DEPARTMENTS"]`
+
+## 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
+```
+
+## Async for Large Datasets
+
+```bash
+# Start async job
+POST /run {userid, project, name, primary_file, async: true}
+# Response: {status: "running", job_id: "..."}
+
+# Poll until done
+POST /run/status {userid, project, job_id}
+# Response: {status: "done", output: "..."}
+```
+
+## 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 R1 INTO U.30 10 D 2` (R-var, location, width, format, decimals)
+
+## Memory Regions
+
+| Prefix | Description |
+|--------|-------------|
+| `P` | Primary data file (current record) |
+| `S` | Secondary data file (current record) |
+| `U` | User buffer (scratch for output) |
+| `X` | System text (date, time, filenames) |
+
+## 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
+```
+
+## Import-Download: URL → Dataset (Parquet, Excel, CSV, JSON)
+
+```bash
+# Import Parquet from a cloud data lake
+POST /import-download {
+  userid, project, name: "TRIPS",
+  url: "https://example.com/data.parquet",
+  instructions: "Extract date, passenger_count, fare (2 decimals). Skip null fares.",
+  max_rows: 100000
+}
+
+# Import Excel spreadsheet
+POST /import-download {
+  userid, project, name: "SALES",
+  url: "https://example.com/report.xlsx",
+  instructions: "Extract Country, Product, Units_Sold (integer), Profit (2 decimals)."
+}
+```
+
+Supports: CSV, TSV, JSON, NDJSON, Parquet (zstd/snappy/lz4), Excel (.xlsx/.xls).
+AI instructions are optional — omit to import all columns as-is.
+Lambda: 10 GB /tmp, 900s timeout, 500 MB download limit.
+
+## HULDRA Optimization Pattern
+
+R1–R20 = elements (HULDRA sets before each run)
+R21–R40 = objectives (your program computes, HULDRA reads after)
+R41–R50 = scratch space
+
+```bash
+POST /optimize {
+  userid, project, program: "FITMODEL", primary_file: "DATA",
+  elements: [{index: 1, label: "slope", start: 0.0, min: -100, max: 100, delta: 0.01}],
+  objectives: [{index: 1, label: "SSR", goal: 0.0, weight: 1.0}],
+  max_iterations: 100
+}
+```

package/references/endpoints.md

@@ -0,0 +1,87 @@
+# Chaprola API — Endpoint Reference
+
+Base URL: `https://api.chaprola.org`
+
+Auth: `Authorization: Bearer chp_your_api_key` on all protected endpoints.
+
+## Public Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /hello` | Health check. Optional `?name=X` query param |
+| `POST /register` | `{username, passcode}` → `{api_key}`. Passcode: 16-128 chars |
+| `POST /login` | `{username, passcode}` → `{api_key}`. **Invalidates previous key** |
+| `POST /check-username` | `{username}` → `{available: bool}` |
+| `POST /delete-account` | `{username, passcode}` → deletes account + all data |
+| `POST /baa-text` | `{}` → `{baa_version, text}`. Get BAA for human review |
+| `POST /report` | `{userid, project, name}` → program output. Program must be published |
+
+## Protected Endpoints (auth required)
+
+### BAA
+| Endpoint | Body | Response |
+|----------|------|----------|
+| `POST /sign-baa` | `{userid, signatory_name, signatory_title?, organization?}` | `{status: "signed", baa_version, signed_at}` |
+| `POST /baa-status` | `{userid}` | `{signed: bool, ...details}` |
+
+### Data Import/Export
+| Endpoint | Body | Response |
+|----------|------|----------|
+| `POST /import` | `{userid, project, name, data, format?, expires_in_days?}` | `{records, fields, record_length}` |
+| `POST /import-url` | `{userid, project, name}` | `{upload_url, staging_key, expires_in}` |
+| `POST /import-process` | `{userid, project, name, format?}` | Same as /import |
+| `POST /import-download` | `{userid, project, name, url, instructions?, max_rows?}` | Same as /import |
+| `POST /export` | `{userid, project, name}` | `{data: [...records]}` |
+| `POST /list` | `{userid, project, pattern?}` | `{files: [...], total}` |
+| `POST /download` | `{userid, project, file, type}` | `{download_url, expires_in, size_bytes}` |
+
+### Compile & Run
+| Endpoint | Body | Response |
+|----------|------|----------|
+| `POST /compile` | `{userid, project, name, source, primary_format?, secondary_formats?}` | `{instructions, bytes}` |
+| `POST /run` | `{userid, project, name, primary_file?, record?, async?, nophi?}` | `{output, registers}` or `{job_id}` |
+| `POST /run/status` | `{userid, project, job_id}` | `{status: "running"/"done", output?}` |
+| `POST /publish` | `{userid, project, name, primary_file?, record?}` | `{report_url}` |
+| `POST /unpublish` | `{userid, project, name}` | `{status: "ok"}` |
+| `POST /export-report` | `{userid, project, name, primary_file?, format?, title?, nophi?}` | `{output, files_written}` |
+
+### Query & Data Operations
+| Endpoint | Body | Response |
+|----------|------|----------|
+| `POST /query` | `{userid, project, file, where?, 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 /merge` | `{userid, project, file_a, file_b, output, key}` | `{status: "ok"}` |
+
+### Optimization (HULDRA)
+| Endpoint | Body | Response |
+|----------|------|----------|
+| `POST /optimize` | `{userid, project, program, primary_file, elements, objectives, max_iterations?, async?}` | `{status, iterations, final_q, elements, objectives}` |
+| `POST /optimize/status` | `{userid, project, job_id}` | `{status: "running"/"converged"}` |
+
+### Email
+| Endpoint | Body | Response |
+|----------|------|----------|
+| `POST /email/inbox` | `{address, limit?, before?}` | `{emails: [...], total}` |
+| `POST /email/read` | `{address, message_id}` | `{email: {from, to, subject, text, html}}` |
+| `POST /email/send` | `{from, to, subject, text, html?}` | `{status: "sent", message_id}` |
+| `POST /email/delete` | `{address, message_id}` | `{status: "deleted"}` |
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| 400 | Invalid input |
+| 401 | Invalid or missing API key. Re-login with `/login` |
+| 403 | BAA not signed, or userid mismatch |
+| 404 | Resource not found |
+| 409 | Username taken (registration) or BAA already signed |
+| 429 | Rate limited. Auth: 5 rps. Others: 20 rps |
+| 500 | Server error |
+
+## 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
+- Data endpoints require a signed BAA (403 if unsigned)
+- All `.DA` files expire after 90 days by default

package/references/gotchas.md

@@ -0,0 +1,84 @@
+# Chaprola Gotchas — Hard-Won Lessons
+
+## Language
+
+### No parentheses in LET
+Chaprola's LET supports one operation: `LET var = a OP b`. Use temp variables for complex math.
+```chaprola
+// WRONG: LET result = price * (qty + bonus)
+// RIGHT:
+LET temp = qty + bonus
+LET result = price * temp
+```
+
+### IF EQUAL compares a literal to a location
+Cannot compare two memory locations. 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.
+
+### 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.
+
+### 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.
+
+### Statement numbers are labels, not line numbers
+Only number lines that are GOTO/CALL targets. Don't number every line.
+
+### FIND returns 0 on no match
+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.
+
+## Import
+
+### Field widths come from the longest value
+Import auto-sizes fields to the max value length. For specific widths (e.g., 8-char balance starting at 0), import as zero-padded string: `"balance": "00000000"`.
+
+### Use explicit OPEN record length for string-imported numbers
+When numeric data is imported as strings, auto-detect (`OPEN "file" 0`) may miscalculate. Use the `record_length` from the import response: `OPEN "ACCOUNTS" 33`.
+
+## API
+
+### userid must match authenticated user
+Every request body's `userid` must equal your username. 403 on mismatch.
+
+### Login invalidates the old key
+`POST /login` generates a new API key. The old one is dead. Save the new one immediately.
+
+### BAA required for data operations
+All import/export/compile/run/query/email endpoints return 403 without a signed BAA. Check with `/baa-status` first.
+
+### Async for large datasets
+`POST /run` with `async: true` for >100K records. API Gateway has a 30-second timeout; async bypasses it. Poll `/run/status` until `status: "done"`.
+
+### secondary_formats is an array
+Pass `secondary_formats: ["DEPARTMENTS"]` (array), not `secondary_format: "DEPARTMENTS"` (string), to `/compile`.
+
+### Data files expire
+Default 90 days. Set `expires_in_days` on import to override. Expired files are deleted daily at 03:00 UTC.
+
+## Secondary Files
+
+### One at a time
+Only one secondary file can be open. CLOSE before opening another. Save any needed values in R-variables or U buffer first.
+
+### CLOSE flushes writes
+Always CLOSE before END if you wrote to the secondary file. Unflushed writes are lost.
+
+## Email
+
+### Content moderation on outbound
+All outbound emails are AI-screened. Blocked emails return 403.
+
+### Rate limits
+20 emails/day per user, 3 emails/minute. Exceeding returns 429.
+
+### PHI in email
+Emails containing PHI identifiers (names, SSNs, dates of birth, etc.) are blocked by the content moderator.