railcode 0.1.26 → 0.1.28

package/dist/index.js

@@ -6,12 +6,15 @@ import { createServer, request as httpRequest, } from "node:http";
 import { createServer as createNetServer, connect as netConnect } from "node:net";
 import { homedir } from "node:os";
 import { Readable } from "node:stream";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import process from "node:process";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
 import { KvQueryError, kvCount, kvQuery, } from "./dev/kv-query.js";
+import { detectGlobalInstaller, fetchPackageVersions, pickLatestSameMajor, shouldCheckForUpdate, } from "./update.js";
 import { DbError, formatTable, inferEngine, parseEngine, parseSqlParams, pickSqlSource, } from "./db.js";
+import { StorageError, encodeFilePath, guessContentType, ownerCell, pageParams, parseKvValue, parseScopeSelector, parseWhere, scopeQuery, } from "./app-storage.js";
 import { QueryCmdError, paramSignature, parseParamDecls, parseRunParams, pickAuthoringSql, } from "./query.js";
 import { APP_MANIFEST_NAME, ManifestParseError, documentOperations, parseManifestYaml, renderManifestDeployOutcome, renderManifestSummary, } from "./manifest.js";
 import { ConnectorError, buildConnectorRequest, connectorOpenapiOutput, connectorTable, parseConnectorOption, parseMethodOption, pickConnectorBody, proxyExitCode, renderConnectorDocs, renderProxyResponse, } from "./connectors.js";
@@ -26,7 +29,11 @@ const RAILCODE_HOME = process.env.RAILCODE_HOME || join(homedir(), ".railcode");
 const CONFIG_PATH = join(RAILCODE_HOME, "config.json");
 const CLI_PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const VERSION = readCliPackageVersion();
+const PACKAGE_NAME = readCliPackageName();
 const DEFAULT_API_URL = "https://api.railcode.app";
+// Where the auto-update throttle records its last check (see maybeAutoUpdate).
+const UPDATE_STATE_PATH = join(RAILCODE_HOME, "update-check.json");
+const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
 const MANIFEST_NAME = "railcode.json";
 const CLI_AUTH_CALLBACK_PATH = "/railcode-cli/callback";
 const CLI_AUTH_TIMEOUT_MS = 5 * 60 * 1000;
@@ -35,11 +42,13 @@ const HELP = `railcode ${VERSION}
 Developer CLI for the multi-tenant Railcode platform.
 
 Usage:
-  railcode login [--api-url <url>]   Sign in and mint a personal API token
+  railcode login [--api-url <url>] [--paste]   Sign in and mint a personal API token
+                                      (--paste / --no-browser: skip the localhost
+                                      callback, paste a code instead — for SSH/headless)
   railcode login --setup-token <token>  Sign in with a one-time onboarding setup token
   railcode deploy [--private]         Build (if configured) and deploy the app here
   railcode dev [--port <n>] [--reset]  Run the app locally against an emulated /_api
-  railcode init <app> [--template react|static]
+  railcode init <app> [dir] [--template react|static] [--force]
   railcode design-system               Print your org's design-system guidance (markdown)
   railcode db <list|query> ...         List data connectors / run read-only SQL
   railcode query <list|run|create|update|delete> ...  Saved queries: invoke by name / author (admin)
@@ -56,6 +65,8 @@ Usage:
   railcode roles <list|create|update|delete|add-member|remove-member|grants|grant|revoke|materialize|effective|catalog> ...
                                       Manage org roles + the granular grants table (admin)
   railcode apps <list|show|access|set-access|transfer|delete> ...  Manage apps + access policy
+  railcode app kv <collections|list|get|set|delete|drop> ...  Manage an app's KV store (owner)
+  railcode app files <list|download|upload|delete> ...  Manage an app's files (owner)
   railcode analytics <app> [--range 1d|7d|30d|90d]  Per-app pageview analytics (admin/owner)
   railcode logs <connector|service-connector|llm|email|agent> [filters]
                                       Read org observability logs (admin)
@@ -63,13 +74,19 @@ Usage:
   railcode --help
 
 Config: ~/.railcode/config.json
-API URL resolves from --api-url, then RAILCODE_API_URL, then saved config.
+API URL resolves from --api-url, then RAILCODE_API_URL, then saved config, then
+the default (${DEFAULT_API_URL}) — never prompted.
 `;
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
 async function main() {
     const args = parseArgs(process.argv.slice(2));
+    // Self-update check runs before real work, but never for the instant meta
+    // commands (help/version) — those must stay fast and side-effect free.
+    if (!isMetaCommand(args.command)) {
+        await maybeAutoUpdate();
+    }
     switch (args.command) {
         case "":
         case "help":
@@ -202,6 +219,15 @@ function readCliPackageVersion() {
     const pkg = JSON.parse(readFileSync(join(CLI_PACKAGE_ROOT, "package.json"), "utf8"));
     return typeof pkg.version === "string" && pkg.version ? pkg.version : "0.0.0";
 }
+function readCliPackageName() {
+    try {
+        const pkg = JSON.parse(readFileSync(join(CLI_PACKAGE_ROOT, "package.json"), "utf8"));
+        return typeof pkg.name === "string" && pkg.name ? pkg.name : "railcode";
+    }
+    catch {
+        return "railcode";
+    }
+}
 // ---------------------------------------------------------------------------
 // login
 // ---------------------------------------------------------------------------
@@ -212,9 +238,12 @@ async function commandLogin(args) {
         await loginWithSetupToken(args, saved, setupToken);
         return;
     }
-    const apiUrl = await resolveLoginApiUrl(args, saved);
+    const apiUrl = resolveLoginApiUrl(args, saved);
+    // --paste / --no-browser: skip the localhost callback entirely and go straight
+    // to "open this URL, paste the code" — the right default for headless/SSH.
+    const pasteMode = args.options.paste === true || args.options.noBrowser === true;
     const serverConfig = (await readJsonOrThrow(await apiFetch(apiUrl, "/api/config", {}), "Server config"));
-    const minted = await authorizeCliWithBrowser(apiUrl);
+    const minted = await authorizeCliWithBrowser(apiUrl, pasteMode);
     // Resolve the caller's identity + organization.
     const me = (await readJsonOrThrow(await apiFetch(apiUrl, "/api/auth/me", {
         headers: { Authorization: `Bearer ${minted.token}` },
@@ -282,10 +311,16 @@ async function loginWithSetupToken(args, saved, setupToken) {
     }
     console.log(`Token ${redeemed.token_prefix}... saved to ${CONFIG_PATH}.`);
 }
-async function authorizeCliWithBrowser(apiUrl) {
+async function authorizeCliWithBrowser(apiUrl, pasteMode) {
     if (!process.stdin.isTTY) {
         throw new CliError("Browser login requires a TTY. Set RAILCODE_API_TOKEN in non-interactive environments.", 2);
     }
+    if (pasteMode) {
+        return authorizeCliByPaste(apiUrl);
+    }
+    // Happy path: a localhost callback server catches the code automatically. We
+    // also print a code-mode URL so login still completes when the browser is on a
+    // different machine and can't reach this box's localhost (the common SSH case).
     const state = randomBytes(16).toString("hex");
     const callback = await startCliAuthCallback(state);
     try {
@@ -293,23 +328,80 @@ async function authorizeCliWithBrowser(apiUrl) {
             redirect_uri: callback.redirectUri,
             state,
         })}`;
-        console.log("");
-        printUrlBox("Railcode login", authorizeUrl);
+        const manualUrl = `${apiUrl}/api/auth/cli/authorize?${new URLSearchParams({ mode: "code" })}`;
         console.log("");
         if (openBrowser(authorizeUrl)) {
-            console.log("Opening your browser. If it does not open, paste the URL above.");
+            console.log("Opening your browser to authorize Railcode.");
         }
         else {
-            console.log("Paste the URL above into your browser to continue.");
+            console.log("Open this URL in your browser to authorize Railcode:");
+            console.log(`  ${authorizeUrl}`);
         }
-        console.log("Waiting for browser authorization...");
-        const code = await callback.code;
+        console.log("");
+        console.log("On a remote/SSH box? If the browser can't reach this machine, open the");
+        console.log("URL below to get a code, then paste it here:");
+        console.log("");
+        printUrlBox("Railcode login", manualUrl);
+        console.log("");
+        const code = await waitForCallbackOrPastedCode(callback.code);
         return await exchangeCliAuthCode(apiUrl, code);
     }
     finally {
         await callback.close();
     }
 }
+// Paste-only flow (--paste / --no-browser): no localhost server, no waiting on a
+// callback. Show the code-mode URL and read the pasted code back.
+async function authorizeCliByPaste(apiUrl) {
+    const manualUrl = `${apiUrl}/api/auth/cli/authorize?${new URLSearchParams({ mode: "code" })}`;
+    console.log("");
+    printUrlBox("Railcode login", manualUrl);
+    console.log("");
+    if (openBrowser(manualUrl)) {
+        console.log("Opening your browser. If it does not open, paste the URL above.");
+    }
+    else {
+        console.log("Paste the URL above into your browser to continue.");
+    }
+    console.log("");
+    const code = (await prompt("Paste the code from your browser: ")).trim();
+    if (!code) {
+        throw new CliError("No code entered.", 1);
+    }
+    return exchangeCliAuthCode(apiUrl, code);
+}
+// Race the localhost callback against a pasted line — whichever yields a code
+// first wins. An empty line means "keep waiting", so we re-prompt. When the
+// callback wins, the abort signal cancels the pending readline question.
+async function waitForCallbackOrPastedCode(callbackCode) {
+    const controller = new AbortController();
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const fromCallback = callbackCode.then((code) => {
+        controller.abort();
+        return code;
+    }, (error) => {
+        controller.abort();
+        throw error;
+    });
+    const fromPaste = (async () => {
+        for (;;) {
+            const answer = (await rl.question("Paste the code from your browser (or press Enter to keep waiting): ", {
+                signal: controller.signal,
+            })).trim();
+            if (answer)
+                return answer;
+        }
+    })();
+    try {
+        return await Promise.race([fromCallback, fromPaste]);
+    }
+    finally {
+        controller.abort();
+        rl.close();
+        fromCallback.catch(() => { });
+        fromPaste.catch(() => { });
+    }
+}
 async function startCliAuthCallback(expectedState) {
     let resolveCode = () => { };
     let rejectCode = () => { };
@@ -443,13 +535,12 @@ function escapeHtml(value) {
         .replaceAll('"', "&quot;")
         .replaceAll("'", "&#39;");
 }
-async function resolveLoginApiUrl(args, saved) {
-    const explicit = optionApiUrl(args) || process.env.RAILCODE_API_URL;
-    if (explicit)
-        return normalizeApiOrigin(explicit);
-    const fallback = saved.apiUrl || DEFAULT_API_URL;
-    const answer = await prompt(`Server URL [${fallback}]: `);
-    return normalizeApiOrigin(answer.trim() || fallback);
+// Resolve the API URL non-interactively — no prompt. Precedence:
+//   --api-url flag → RAILCODE_API_URL env → saved config → DEFAULT_API_URL.
+// The default "just works"; override it only with --api-url (env/saved kept for
+// continuity). Mirrors the setup-token path's resolution in loginWithSetupToken.
+function resolveLoginApiUrl(args, saved) {
+    return normalizeApiOrigin(optionApiUrl(args) || process.env.RAILCODE_API_URL || saved.apiUrl || DEFAULT_API_URL);
 }
 // ---------------------------------------------------------------------------
 // deploy
@@ -700,12 +791,19 @@ function packageBuildCommand(root) {
 async function commandInit(args) {
     const app = args.rest[0];
     if (!app)
-        throw new CliError("Usage: railcode init <app>", 2);
+        throw new CliError("Usage: railcode init <app> [dir]", 2);
     assertAppName(app);
     const template = initTemplate(args);
-    const target = resolve(process.cwd(), app);
-    if (existsSync(target) && readdirSync(target).length > 0) {
-        throw new CliError(`Refusing to scaffold into a non-empty directory: ${target}`, 1);
+    // Optional second positional: the directory to scaffold into. Defaults to a
+    // new "<app>/" subdir. Passing "." scaffolds into the current directory. The
+    // target need not be empty — same-named files are overwritten.
+    const dir = args.rest[1];
+    const target = resolve(process.cwd(), dir ?? app);
+    // Light-touch guard: never clobber an existing app manifest without --force.
+    const manifestPath = join(target, MANIFEST_NAME);
+    if (existsSync(manifestPath) && !args.options.force) {
+        throw new CliError(`A ${MANIFEST_NAME} already exists in ${relativeLabel(process.cwd(), target)}/. ` +
+            "Re-run with --force to overwrite it.", 1);
     }
     mkdirSync(target, { recursive: true });
     if (template === "static") {
@@ -716,7 +814,10 @@ async function commandInit(args) {
     }
     console.log(`Created ${template} Railcode app "${app}" in ${relativeLabel(process.cwd(), target)}/`);
     console.log("Next:");
-    console.log(`  cd ${app}`);
+    // Only prompt a `cd` when the files landed somewhere other than the cwd.
+    if (resolve(target) !== resolve(process.cwd())) {
+        console.log(`  cd ${relativeLabel(process.cwd(), target)}`);
+    }
     if (template === "react") {
         console.log("  npm install");
     }
@@ -970,7 +1071,6 @@ type LlmOptions = {
   provider?: string;
   system?: string;
   output?: LlmOutputSpec;
-  temperature?: number;
   maxOutputTokens?: number;
   metadata?: Record<string, unknown>;
 };
@@ -3794,8 +3894,8 @@ Usage:
   railcode agent show <agent>                 Show one agent
   railcode agent pull <agent> [--output <path>]
                                              Write the agent manifest as JSON
-  railcode agent create --file <path>         Create an agent from a JSON manifest
-  railcode agent update <agent> --file <path> Update an agent from a JSON manifest
+  railcode agent create --file <path>         Create an agent from a JSON or YAML manifest
+  railcode agent update <agent> --file <path> Update an agent from a JSON or YAML manifest
   railcode agent delete <agent> [--yes]       Delete/archive an agent
   railcode agent test --file <path> [opts]    Run a draft manifest without saving
   railcode agent run <agent> [opts]           Trigger a saved agent and print results
@@ -3803,7 +3903,7 @@ Usage:
 
 Agent options:
   --json                                Print the raw API response
-  --file <path>                         JSON manifest file
+  --file <path>                         JSON or YAML manifest file
   --output <path>                       Output path for pull (default stdout)
   --input '<json>'                      Invoke/test input JSON (default null)
   --input-file <path>                   Read invoke/test input JSON from a file
@@ -3823,7 +3923,7 @@ Schedule options:
   --timezone <iana>                     IANA timezone (default: UTC on create)
   --enabled / --disabled                Initial or updated enabled state
 
-Manifests are JSON files in the same shape the API stores under agent.manifest.
+Manifests are JSON or YAML files in the same shape the API stores under agent.manifest.
 Schedules are currently one per agent, so "set" creates the schedule if missing
 or updates the existing one.
 `;
@@ -4185,8 +4285,9 @@ async function requireSingleSchedule(config, ref) {
 function readAgentManifest(args) {
     const path = optionString(args, "file");
     if (!path)
-        throw new CliError("Pass --file <agent-manifest.json>.", 2);
-    return readJsonObjectFile(path, "Agent manifest");
+        throw new CliError("Pass --file <agent-manifest.json|yaml|yml>.", 2);
+    const format = /\.ya?ml$/i.test(path) ? "YAML" : "JSON";
+    return readObjectFile(path, "Agent manifest", format);
 }
 // Omitted means "use the server default" on create/test (org) and "leave alone"
 // on update — never send the key unless the caller passed it explicitly.
@@ -4200,18 +4301,22 @@ function agentVisibilityOption(args) {
     return value;
 }
 function readJsonObjectFile(path, label) {
+    return readObjectFile(path, label, "JSON");
+}
+function readObjectFile(path, label, format) {
     const resolved = resolve(process.cwd(), path);
     if (!existsSync(resolved))
         throw new CliError(`${label} file not found: ${path}`, 2);
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(resolved, "utf8"));
+        const raw = readFileSync(resolved, "utf8");
+        parsed = format === "YAML" ? parseYaml(raw) : JSON.parse(raw);
     }
     catch (error) {
-        throw new CliError(`${label} file is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, 2);
+        throw new CliError(`${label} file is not valid ${format}: ${error instanceof Error ? error.message : String(error)}`, 2);
     }
     if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-        throw new CliError(`${label} file must contain a JSON object.`, 2);
+        throw new CliError(`${label} file must contain a ${format} object.`, 2);
     }
     return parsed;
 }
@@ -5148,7 +5253,9 @@ const PC_HELP = `railcode personal-connectors — your own connected accounts (G
 Usage:
   railcode personal-connectors list            Toolkits this deployment brokers + your status
   railcode personal-connectors tools <toolkit> The callable tools of a toolkit (and their inputs)
-  railcode personal-connectors connect <toolkit>  Print the OAuth URL to connect it (open in a browser)
+  railcode personal-connectors connect <toolkit>  Start connecting it: prints the OAuth URL, or
+                                                  reports if it needs a token
+  railcode personal-connectors connect <toolkit> --token '<value>'  Link a token-auth connector (e.g. a GitHub PAT)
   railcode personal-connectors call <toolkit> <tool> [--args '<json>']  Run one tool on your own account
 
 Aliases: personal-connector, pc
@@ -5159,6 +5266,7 @@ input schema, so you know what to put in an app's \`personal_connectors:\` and w
 
 Options:
   --json                                 Print raw JSON instead of a table
+  --token '<value>'                      Token/key for \`connect\` on a token-auth connector
   --args '<json>'                        Arguments object for \`call\` (default {})
 `;
 async function commandPersonalConnectors(args) {
@@ -5237,13 +5345,31 @@ async function commandPcTools(args) {
     console.log(`\n${tools.length} tool(s). Add \`--json\` to see each tool's input schema.`);
 }
 async function commandPcConnect(args) {
-    rejectUnknownOptions(args, ["json", "apiUrl"], "personal-connectors connect", PC_HELP);
+    rejectUnknownOptions(args, ["json", "token", "apiUrl"], "personal-connectors connect", PC_HELP);
     const toolkit = args.rest[1];
     if (!toolkit)
         throw new CliError("Usage: railcode personal-connectors connect <toolkit>", 2);
     const config = requireLogin(args);
-    // Connecting is browser-bound OAuth; the CLI can't complete it. It prints the
-    // URL and leaves opening it to you — the same handoff `railcode login` uses.
+    // A token-auth connector (e.g. a GitHub PAT): `--token <value>` submits it
+    // directly, otherwise we tell the caller a token is needed.
+    if (typeof args.options.token === "string") {
+        const tokResp = await authedFetch(config, `/api/personal-connections/${encodeURIComponent(toolkit)}/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ token: args.options.token }),
+        });
+        if (tokResp.status === 401)
+            await reLoginOrThrow();
+        if (pcUnavailable(tokResp.status)) {
+            console.log("Personal connectors are not enabled on this deployment.");
+            return;
+        }
+        await readJsonOrThrow(tokResp, `Connect ${toolkit}`);
+        console.log(`Connected ${toolkit}.`);
+        return;
+    }
+    // Otherwise start the flow. OAuth is browser-bound (the CLI can't complete it),
+    // so it prints the URL; a token connector reports that a token is required.
     const resp = await authedFetch(config, `/api/personal-connections/${encodeURIComponent(toolkit)}/connect`, { method: "POST" });
     if (resp.status === 401)
         await reLoginOrThrow();
@@ -5256,6 +5382,11 @@ async function commandPcConnect(args) {
         console.log(JSON.stringify(body, null, 2));
         return;
     }
+    if (body.mode === "token") {
+        console.log(`${toolkit} connects with a ${body.token_label ?? "token"}. ` +
+            `Re-run with --token '<value>' to link it:\n\n  railcode personal-connectors connect ${toolkit} --token '<value>'\n`);
+        return;
+    }
     console.log(`Open this URL to connect ${toolkit}, then re-run your command:\n\n  ${body.redirect_url}\n`);
 }
 async function commandPcCall(args) {
@@ -5338,8 +5469,14 @@ function jsonBody(body) {
 async function fetchMembers(config) {
     return (await authedJson(config, `/api/organizations/${config.orgUuid}/members`, "List members"));
 }
-async function fetchApps(config) {
-    return (await authedJson(config, `/api/organizations/${config.orgUuid}/apps`, "List apps"));
+// `archived` mirrors the API's ?archived= filter. The default is "all", NOT the
+// API's own "false": nearly every caller here is resolving a <app> reference (or
+// mapping uuid→slug), and archiving is supposed to take nothing away — an
+// archived app must still be addressable by `apps show/access/transfer/archive/
+// delete`, `analytics`, and the storage commands. `apps list` is the one caller
+// that actually filters, and it says so explicitly.
+async function fetchApps(config, archived = "all") {
+    return (await authedJson(config, `/api/organizations/${config.orgUuid}/apps?archived=${archived}`, "List apps"));
 }
 async function fetchPermissions(config) {
     return (await authedJson(config, `/api/organizations/${config.orgUuid}/permissions`, "List roles + grants"));
@@ -5712,21 +5849,84 @@ async function commandRolesCatalog(args) {
 const APPS_HELP = `railcode apps — apps + access policy
 
 Usage:
-  railcode apps list                           List apps you can see
+  railcode apps list [--archived|--all]         List apps you can see
   railcode apps show <app>                      Show one app's details
   railcode apps access <app>                    Show an app's access policy + grants
   railcode apps set-access <app> --mode organization|private|restricted
                         [--members <email,email>]  Set the policy (members: restricted only)
   railcode apps transfer <app> --to <email|uuid>  Transfer ownership
+  railcode apps archive <app>                   Hide an app from the launcher
+  railcode apps unarchive <app>                 Restore an archived app
   railcode apps delete <app> [--yes]            Delete an app (deploys + data, irreversible)
 
-<app> is an app slug or UUID. set-access/transfer/delete need manage rights
+  railcode app kv ...                           Manage an app's KV store (owner)
+  railcode app files ...                        Manage an app's files (owner)
+
+<app> is an app slug or UUID. set-access/transfer/archive/delete need manage rights
 (owner or org admin). delete prompts for confirmation on a TTY; pass --yes to skip
 (required in non-interactive sessions).
 
+Archiving is INERT and reversible, so it never prompts: an archived app keeps
+serving at its host, keeps its slug, keeps its data, and keeps running its agents
+— it just drops out of the launcher. list hides archived apps by default;
+--archived lists only those, --all lists both.
+
 Options:
+  --archived                             (list) Only archived apps
+  --all                                  (list) Archived and live apps
   --json                                 Print raw JSON
   --yes                                  Skip the delete confirmation prompt
+
+Run \`railcode app kv\` or \`railcode app files\` for the storage sub-help.
+`;
+// The storage sub-commands manage an app's stored data. They require APP OWNERSHIP
+// (owner grant, or an org admin holding app:manage_any) — a plain member with app
+// access is cleanly rejected. The app is chosen with --app <slug|uuid>, or resolved
+// from the railcode.json in the current directory (like deploy).
+const APP_KV_HELP = `railcode app kv — manage an app's KV store (owner only)
+
+Usage:
+  railcode app kv collections                   List collections + record counts
+  railcode app kv list <collection>             List/query records in a collection
+  railcode app kv get <collection> <key>        Print one record's JSON value
+  railcode app kv set <collection> <key> <json> Create/update a record (or --file)
+  railcode app kv delete <collection> <key>     Delete one record
+  railcode app kv drop <collection> [--yes]     Delete every record in a collection
+
+App:  --app <slug|uuid>   (else resolved from ./railcode.json, like deploy)
+
+Scope (default shared):
+  --scope shared|user|role|all   Namespace to act on (all = enumerate every scope,
+                                 listings only, with owner attribution)
+  --user <member-uuid>           Required for --scope user
+  --role <role-uuid>             Required for --scope role
+
+list options:
+  --query '<json>'    A where clause: [[field, op, value], ...]
+  --limit <n>         Max records; --offset <n> pages (a multiple of --limit)
+  --count             Print the matching record count instead of the rows
+
+set options:  --file <path>   Read the JSON value from a file
+Common:       --json          Print raw JSON      --yes   Skip the drop confirmation
+`;
+const APP_FILES_HELP = `railcode app files — manage an app's files (owner only)
+
+Usage:
+  railcode app files list                       List file metadata
+  railcode app files download <name> [--out p]  Download a file (default: ./<name>)
+  railcode app files upload <path> [--name n]   Upload a local file
+  railcode app files delete <name>              Delete a file
+
+App:  --app <slug|uuid>   (else resolved from ./railcode.json, like deploy)
+
+Scope (default shared): --scope shared|user|role|all, --user <uuid>, --role <uuid>
+(all lists across every scope with owner attribution; upload/download/delete target
+one scope).
+
+Options:
+  --out <path>    (download) Where to write the bytes
+  --name <name>   (upload) The remote name (default: the local basename)
+  --json          Print raw JSON (list)
 `;
 async function commandApps(args) {
     try {
@@ -5749,10 +5949,23 @@ async function commandApps(args) {
             case "transfer":
                 await commandAppsTransfer(args);
                 return;
+            case "archive":
+                await commandAppsArchive(args, true);
+                return;
+            case "unarchive":
+                await commandAppsArchive(args, false);
+                return;
             case "delete":
             case "rm":
                 await commandAppsDelete(args);
                 return;
+            case "kv":
+                await commandAppKv(args);
+                return;
+            case "files":
+            case "file":
+                await commandAppFiles(args);
+                return;
             case "":
             case "help":
                 console.log(APPS_HELP);
@@ -5762,25 +5975,396 @@ async function commandApps(args) {
         }
     }
     catch (error) {
-        if (error instanceof OrgAdminError)
+        if (error instanceof OrgAdminError || error instanceof StorageError) {
             throw new CliError(error.message, 2);
+        }
         throw error;
     }
 }
+// ── app storage: KV + files (owner only) ─────────────────────────────────────
+//
+// Both groups resolve the target app (--app or ./railcode.json) then hit the
+// owner-facing management plane at
+// `/api/organizations/{org}/apps/{app}/storage/{kv,files}/*`. Non-owners get the
+// server's plain "requires app ownership" 403.
+function storageBase(config, app) {
+    return `/api/organizations/${config.orgUuid}/apps/${app.uuid}/storage`;
+}
+async function resolveStorageApp(config, args) {
+    const ref = optionString(args, "app") ?? readManifest(process.cwd())?.app;
+    if (!ref) {
+        throw new StorageError("No app: pass --app <slug|uuid>, or run inside an app directory (railcode.json).");
+    }
+    return resolveAppRef(await fetchApps(config), ref);
+}
+// The shared scope flags, off the parsed args. `allowAll` gates `--scope all`.
+function storageScope(args, allowAll) {
+    return parseScopeSelector(optionString(args, "scope"), optionString(args, "user"), optionString(args, "role"), { allowAll });
+}
+function intOption(args, key) {
+    const raw = optionString(args, key);
+    if (raw === undefined)
+        return undefined;
+    const n = Number(raw);
+    if (!Number.isFinite(n))
+        throw new StorageError(`--${camelToKebab(key)} must be a number.`);
+    return n;
+}
+async function commandAppKv(args) {
+    const sub = args.rest[1] ?? "";
+    switch (sub) {
+        case "collections":
+        case "cols":
+            await commandAppKvCollections(args);
+            return;
+        case "list":
+        case "ls":
+            await commandAppKvList(args);
+            return;
+        case "get":
+            await commandAppKvGet(args);
+            return;
+        case "set":
+        case "put":
+            await commandAppKvSet(args);
+            return;
+        case "delete":
+        case "rm":
+            await commandAppKvDelete(args);
+            return;
+        case "drop":
+            await commandAppKvDrop(args);
+            return;
+        case "":
+        case "help":
+            console.log(APP_KV_HELP);
+            return;
+        default:
+            throw new StorageError(`Unknown \`app kv\` command: ${sub}\n\n${APP_KV_HELP}`);
+    }
+}
+async function commandAppKvCollections(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "json", "apiUrl"], "app kv", APP_KV_HELP);
+    const scope = storageScope(args, true);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const body = (await authedJson(config, `${storageBase(config, app)}/kv?${scopeQuery(scope)}`, "List collections"));
+    if (args.options.json) {
+        console.log(JSON.stringify(body.items, null, 2));
+        return;
+    }
+    if (body.items.length === 0) {
+        console.log("No KV collections in this scope.");
+        return;
+    }
+    console.log(formatTable(["scope", "owner", "collection", "count"], body.items.map((c) => [c.scope, ownerCell(c.scope, c.owner_label), c.collection, c.count])));
+}
+async function commandAppKvList(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "query", "limit", "offset", "count", "json", "apiUrl"], "app kv", APP_KV_HELP);
+    const collection = args.rest[2];
+    if (!collection)
+        throw new StorageError("Usage: railcode app kv list <collection>");
+    const scope = storageScope(args, true);
+    const where = parseWhere(optionString(args, "query"));
+    const paging = pageParams(intOption(args, "limit"), intOption(args, "offset"));
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const params = new URLSearchParams(scopeQuery(scope));
+    if (where !== undefined)
+        params.set("where", where);
+    if (paging.page !== undefined)
+        params.set("page", String(paging.page));
+    if (paging.size !== undefined)
+        params.set("size", String(paging.size));
+    if (args.options.count)
+        params.set("count", "true");
+    const path = `${storageBase(config, app)}/kv/${encodeURIComponent(collection)}?${params}`;
+    const body = (await authedJson(config, path, "List records"));
+    if (args.options.count) {
+        const count = body.count;
+        if (args.options.json) {
+            console.log(JSON.stringify({ count }, null, 2));
+            return;
+        }
+        console.log(String(count));
+        return;
+    }
+    const items = body.items;
+    if (args.options.json) {
+        console.log(JSON.stringify(items, null, 2));
+        return;
+    }
+    if (items.length === 0) {
+        console.log("No records.");
+        return;
+    }
+    const crossScope = scope.scope === "all";
+    const columns = crossScope ? ["scope", "owner", "key", "value"] : ["key", "value"];
+    console.log(formatTable(columns, items.map((r) => crossScope
+        ? [r.scope, ownerCell(r.scope, r.owner_label), r.key, JSON.stringify(r.value)]
+        : [r.key, JSON.stringify(r.value)])));
+}
+async function commandAppKvGet(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "json", "apiUrl"], "app kv", APP_KV_HELP);
+    const collection = args.rest[2];
+    const key = args.rest[3];
+    if (!collection || !key)
+        throw new StorageError("Usage: railcode app kv get <collection> <key>");
+    const scope = storageScope(args, false);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const record = (await authedJson(config, `${storageBase(config, app)}/kv/${encodeURIComponent(collection)}/${encodeFilePath(key)}?${scopeQuery(scope)}`, "Get record"));
+    if (args.options.json) {
+        console.log(JSON.stringify(record, null, 2));
+        return;
+    }
+    // The value is the payload — print it as pretty JSON so it pipes cleanly.
+    console.log(JSON.stringify(record.value, null, 2));
+}
+async function commandAppKvSet(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "file", "json", "apiUrl"], "app kv", APP_KV_HELP);
+    const collection = args.rest[2];
+    const key = args.rest[3];
+    if (!collection || !key) {
+        throw new StorageError("Usage: railcode app kv set <collection> <key> <json|--file path>");
+    }
+    const filePath = optionString(args, "file");
+    const fileText = filePath !== undefined ? readValueFile(filePath) : undefined;
+    const value = parseKvValue(args.rest[4], fileText);
+    const scope = storageScope(args, false);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const record = (await authedJson(config, `${storageBase(config, app)}/kv/${encodeURIComponent(collection)}/${encodeFilePath(key)}?${scopeQuery(scope)}`, "Set record", { method: "PUT", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ value }) }));
+    if (args.options.json) {
+        console.log(JSON.stringify(record, null, 2));
+        return;
+    }
+    console.log(`Set ${collection}/${key} (scope: ${scope.scope}).`);
+}
+async function commandAppKvDelete(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "apiUrl"], "app kv", APP_KV_HELP);
+    const collection = args.rest[2];
+    const key = args.rest[3];
+    if (!collection || !key) {
+        throw new StorageError("Usage: railcode app kv delete <collection> <key>");
+    }
+    const scope = storageScope(args, false);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    await authedNoContent(config, `${storageBase(config, app)}/kv/${encodeURIComponent(collection)}/${encodeFilePath(key)}?${scopeQuery(scope)}`, "Delete record", { method: "DELETE" });
+    console.log(`Deleted ${collection}/${key} (scope: ${scope.scope}).`);
+}
+async function commandAppKvDrop(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "yes", "json", "apiUrl"], "app kv", APP_KV_HELP);
+    const collection = args.rest[2];
+    if (!collection)
+        throw new StorageError("Usage: railcode app kv drop <collection>");
+    const scope = storageScope(args, false);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    if (args.options.yes !== true) {
+        if (!process.stdin.isTTY) {
+            throw new CliError("Pass --yes to drop a collection in a non-interactive session.", 2);
+        }
+        const answer = await prompt(`Drop every record in "${collection}" (scope: ${scope.scope}) of ${app.app_slug}? [y/N] `);
+        if (!["y", "yes"].includes(answer.trim().toLowerCase())) {
+            throw new CliError("Drop cancelled.", 1);
+        }
+    }
+    const result = (await authedJson(config, `${storageBase(config, app)}/kv/${encodeURIComponent(collection)}?${scopeQuery(scope)}`, "Drop collection", { method: "DELETE" }));
+    if (args.options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Dropped ${result.deleted} record(s) from "${collection}".`);
+}
+async function commandAppFiles(args) {
+    const sub = args.rest[1] ?? "";
+    switch (sub) {
+        case "list":
+        case "ls":
+            await commandAppFilesList(args);
+            return;
+        case "download":
+        case "get":
+            await commandAppFilesDownload(args);
+            return;
+        case "upload":
+        case "put":
+            await commandAppFilesUpload(args);
+            return;
+        case "delete":
+        case "rm":
+            await commandAppFilesDelete(args);
+            return;
+        case "":
+        case "help":
+            console.log(APP_FILES_HELP);
+            return;
+        default:
+            throw new StorageError(`Unknown \`app files\` command: ${sub}\n\n${APP_FILES_HELP}`);
+    }
+}
+async function commandAppFilesList(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "json", "apiUrl"], "app files", APP_FILES_HELP);
+    const scope = storageScope(args, true);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const body = (await authedJson(config, `${storageBase(config, app)}/files?${scopeQuery(scope)}`, "List files"));
+    if (args.options.json) {
+        console.log(JSON.stringify(body.items, null, 2));
+        return;
+    }
+    if (body.items.length === 0) {
+        console.log("No files in this scope.");
+        return;
+    }
+    const crossScope = scope.scope === "all";
+    const columns = crossScope
+        ? ["scope", "owner", "name", "size", "type", "updated"]
+        : ["name", "size", "type", "updated"];
+    console.log(formatTable(columns, body.items.map((f) => crossScope
+        ? [f.scope, ownerCell(f.scope, f.owner_label), f.name, f.size, f.content_type, f.updated_at]
+        : [f.name, f.size, f.content_type, f.updated_at])));
+}
+async function commandAppFilesDownload(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "out", "apiUrl"], "app files", APP_FILES_HELP);
+    const name = args.rest[2];
+    if (!name)
+        throw new StorageError("Usage: railcode app files download <name> [--out path]");
+    const scope = storageScope(args, false);
+    const outPath = optionString(args, "out") ?? basename(name);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const url = `${storageBase(config, app)}/files/${encodeFilePath(name)}?${scopeQuery(scope)}`;
+    const resp = await authedFetch(config, url);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    let bytes;
+    if ([301, 302, 303, 307, 308].includes(resp.status)) {
+        // S3 backend: the body lives at a short-lived presigned URL (no auth header).
+        const location = resp.headers.get("location");
+        if (!location)
+            throw new CliError("File download redirect had no location.", 1);
+        const signed = await fetch(location);
+        if (!signed.ok)
+            throw new CliError(`File download failed (${signed.status}).`, 1);
+        bytes = await signed.arrayBuffer();
+    }
+    else if (resp.ok) {
+        bytes = await resp.arrayBuffer();
+    }
+    else {
+        throw new CliError(`File download failed (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+    writeFileSync(resolve(process.cwd(), outPath), Buffer.from(bytes));
+    console.log(`Downloaded ${name} → ${outPath} (${bytes.byteLength} bytes).`);
+}
+async function commandAppFilesUpload(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "name", "json", "apiUrl"], "app files", APP_FILES_HELP);
+    const localPath = args.rest[2];
+    if (!localPath)
+        throw new StorageError("Usage: railcode app files upload <local-path> [--name n]");
+    const resolvedLocal = resolve(process.cwd(), localPath);
+    if (!existsSync(resolvedLocal) || !statSync(resolvedLocal).isFile()) {
+        throw new StorageError(`Not a file: ${localPath}`);
+    }
+    const remoteName = optionString(args, "name") ?? basename(localPath);
+    const data = readFileSync(resolvedLocal);
+    const contentType = guessContentType(remoteName);
+    const scope = storageScope(args, false);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    const base = storageBase(config, app);
+    const scopeQs = scopeQuery(scope);
+    // Negotiate the upload — the same two-mode flow the SDK uses.
+    const target = (await authedJson(config, `${base}/files?${scopeQs}`, "Negotiate upload", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name: remoteName, content_type: contentType }) }));
+    let meta;
+    if (target.mode === "presigned") {
+        // S3: PUT the bytes straight to the presigned URL, then finalize the row.
+        const put = await fetch(target.url, {
+            method: target.method,
+            headers: target.headers,
+            body: data,
+        });
+        if (!put.ok)
+            throw new CliError(`Upload to storage failed (${put.status}).`, 1);
+        meta = (await authedJson(config, `${base}/files/finalize?${scopeQs}`, "Finalize upload", { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ name: remoteName }) }));
+    }
+    else {
+        // Local: PUT the bytes to this plane's proxy blob endpoint (records the row).
+        const resp = await authedFetch(config, target.url, {
+            method: target.method,
+            headers: { "Content-Type": contentType },
+            body: data,
+        });
+        if (resp.status === 401)
+            await reLoginOrThrow();
+        meta = (await readJsonOrThrow(resp, "Upload file"));
+    }
+    if (args.options.json) {
+        console.log(JSON.stringify(meta, null, 2));
+        return;
+    }
+    console.log(`Uploaded ${remoteName} (${meta.size} bytes, scope: ${scope.scope}).`);
+}
+async function commandAppFilesDelete(args) {
+    rejectUnknownOptions(args, ["app", "scope", "user", "role", "apiUrl"], "app files", APP_FILES_HELP);
+    const name = args.rest[2];
+    if (!name)
+        throw new StorageError("Usage: railcode app files delete <name>");
+    const scope = storageScope(args, false);
+    const config = requireLogin(args);
+    const app = await resolveStorageApp(config, args);
+    await authedNoContent(config, `${storageBase(config, app)}/files/${encodeFilePath(name)}?${scopeQuery(scope)}`, "Delete file", { method: "DELETE" });
+    console.log(`Deleted ${name} (scope: ${scope.scope}).`);
+}
+function readValueFile(path) {
+    const resolved = resolve(process.cwd(), path);
+    if (!existsSync(resolved))
+        throw new StorageError(`Value file not found: ${path}`);
+    return readFileSync(resolved, "utf8");
+}
 async function commandAppsList(args) {
-    rejectUnknownOptions(args, ["json", "apiUrl"], "apps", APPS_HELP);
+    rejectUnknownOptions(args, ["json", "archived", "all", "apiUrl"], "apps", APPS_HELP);
+    if (args.options.archived === true && args.options.all === true) {
+        throw new CliError("Pass either --archived or --all, not both.", 2);
+    }
+    const archived = args.options.all === true ? "all" : args.options.archived === true ? "true" : "false";
     const config = requireLogin(args);
-    const apps = await fetchApps(config);
+    const apps = await fetchApps(config, archived);
     if (args.options.json) {
         console.log(JSON.stringify(apps, null, 2));
         return;
     }
     if (apps.length === 0) {
-        console.log("No apps yet. Scaffold one: railcode init <app>.");
+        console.log(archived === "true"
+            ? "No archived apps."
+            : "No apps yet. Scaffold one: railcode init <app>.");
         return;
     }
     console.log(appTable(apps));
 }
+// Archive / unarchive. No confirmation prompt: unlike delete this changes nothing
+// but the launcher's view of the app — it keeps serving, keeps its slug, keeps its
+// data — and it is one command to undo.
+async function commandAppsArchive(args, archive) {
+    const verb = archive ? "archive" : "unarchive";
+    rejectUnknownOptions(args, ["json", "apiUrl"], "apps", APPS_HELP);
+    const ref = args.rest[1];
+    if (!ref)
+        throw new CliError(`Usage: railcode apps ${verb} <app>`, 2);
+    const config = requireLogin(args);
+    const app = resolveAppRef(await fetchApps(config), ref);
+    const updated = (await authedJson(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}/archive`, archive ? "Archive app" : "Unarchive app", { method: archive ? "POST" : "DELETE" }));
+    if (args.options.json) {
+        console.log(JSON.stringify(updated, null, 2));
+        return;
+    }
+    console.log(archive
+        ? `App "${app.app_slug}" archived — hidden from the launcher, still serving.`
+        : `App "${app.app_slug}" restored to the launcher.`);
+}
 async function commandAppsShow(args) {
     rejectUnknownOptions(args, ["json", "apiUrl"], "apps", APPS_HELP);
     const ref = args.rest[1];
@@ -5801,6 +6385,8 @@ async function commandAppsShow(args) {
     console.log(row("your role", full.your_role ?? "-"));
     console.log(row("can manage", full.can_manage ? "yes" : "no"));
     console.log(row("has manifest", full.has_manifest ? "yes" : "no"));
+    if (full.archived_at)
+        console.log(row("archived", String(full.archived_at)));
     if (full.last_deployed_at)
         console.log(row("deployed", String(full.last_deployed_at)));
 }
@@ -6167,6 +6753,98 @@ function saveConfig(config) {
     mkdirSync(dirname(CONFIG_PATH), { recursive: true, mode: 0o700 });
     writeFileSync(CONFIG_PATH, `${JSON.stringify(clean, null, 2)}\n`, { mode: 0o600 });
 }
+function isMetaCommand(command) {
+    return (command === "" ||
+        command === "help" ||
+        command === "--help" ||
+        command === "-h" ||
+        command === "--version" ||
+        command === "-v");
+}
+// Truthy env flag: unset/empty/"0"/"false"/"no"/"off" are false, anything else true.
+function envFlag(value) {
+    if (!value)
+        return false;
+    return !["0", "false", "no", "off"].includes(value.trim().toLowerCase());
+}
+function readUpdateState() {
+    if (!existsSync(UPDATE_STATE_PATH))
+        return {};
+    try {
+        return JSON.parse(readFileSync(UPDATE_STATE_PATH, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeUpdateState(state) {
+    mkdirSync(dirname(UPDATE_STATE_PATH), { recursive: true, mode: 0o700 });
+    writeFileSync(UPDATE_STATE_PATH, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+}
+async function maybeAutoUpdate() {
+    try {
+        if (envFlag(process.env.RAILCODE_NO_UPDATE))
+            return;
+        const dryRun = envFlag(process.env.RAILCODE_UPDATE_DRY_RUN);
+        // Only self-update for a human at an interactive terminal — CI and other
+        // automation shouldn't silently mutate a global install. Dry-run forces the
+        // check so the flow is exercisable non-interactively (and in tests).
+        if (!dryRun && !process.stdout.isTTY)
+            return;
+        const now = Date.now();
+        if (!shouldCheckForUpdate(readUpdateState().last_checked_for_updates, now))
+            return;
+        // Record the attempt up front so a slow or failed check still backs off for
+        // the full interval instead of retrying on every subsequent command.
+        writeUpdateState({ last_checked_for_updates: new Date(now).toISOString() });
+        const registry = process.env.RAILCODE_REGISTRY_URL || process.env.npm_config_registry || DEFAULT_REGISTRY_URL;
+        const versions = await fetchPackageVersions(registry, PACKAGE_NAME);
+        const latest = pickLatestSameMajor(VERSION, versions);
+        if (!latest)
+            return;
+        const spec = `${PACKAGE_NAME}@${latest}`;
+        const installer = detectGlobalInstaller(CLI_PACKAGE_ROOT, process.env.npm_config_user_agent);
+        const argv = installer.args(spec);
+        const commandLine = `${installer.command} ${argv.join(" ")}`;
+        process.stderr.write(`railcode: a new version is available — ${VERSION} → ${latest}. Updating…\n`);
+        if (dryRun) {
+            process.stderr.write(`railcode: [dry-run] would run \`${commandLine}\`\n`);
+            return;
+        }
+        const code = await runGlobalInstall(installer.command, argv);
+        if (code === 0) {
+            process.stderr.write(`railcode: updated to ${latest}. It takes effect on your next command.\n`);
+        }
+        else {
+            process.stderr.write(`railcode: auto-update failed. Update manually: ${commandLine}\n`);
+        }
+    }
+    catch {
+        // Best-effort: never let an update problem break the user's actual command.
+    }
+}
+// Spawn the global install, routing all of its output to stderr so our own
+// stdout stays clean for parseable command output. Resolves with the exit code
+// (-1 if the manager binary couldn't be spawned).
+function runGlobalInstall(command, argv) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, argv, {
+                stdio: ["ignore", "pipe", "pipe"],
+                shell: process.platform === "win32",
+            });
+        }
+        catch {
+            resolve(-1);
+            return;
+        }
+        child.stdout?.on("data", (chunk) => process.stderr.write(chunk));
+        child.stderr?.on("data", (chunk) => process.stderr.write(chunk));
+        child.on("error", () => resolve(-1));
+        child.on("close", (code) => resolve(code ?? -1));
+    });
+}
 // ---------------------------------------------------------------------------
 // Manifest + misc helpers
 // ---------------------------------------------------------------------------
@@ -6332,8 +7010,9 @@ class CliError extends Error {
 // Serves the app on a single loopback origin and emulates the /_api/* data plane:
 // identity is synthetic, KV + files live on local disk (isolated per storage scope —
 // shared/user/role — so `db.user`/`files.role(uuid)` behave like prod). llm/sql/queries/
-// connectors/email proxy to the real instance as the signed-in user (their token + org
-// grants) via the org/user-scoped routes — no deploy needed. Mirrors railcode-core's dev.
+// connectors/email/agents proxy to the real instance as the signed-in user (their token
+// + org grants) via the org/user-scoped routes — no deploy needed. Mirrors
+// railcode-core's dev.
 // ---------------------------------------------------------------------------
 const DEFAULT_DEV_PORT = 7331;
 const DEFAULT_ASSET_PORT = 5173;
@@ -6366,6 +7045,7 @@ async function commandDev(args) {
         throw new CliError("SDK bundle not found. Build it with `pnpm --dir sdk build` (or `pnpm --dir cli build` once the CLI bundles it).", 1);
     }
     const plan = resolveDevPlan(cwd, manifest);
+    const manifestDoc = readLocalManifestDoc(cwd);
     const ctx = {
         app: manifest.app,
         root: plan.root,
@@ -6375,7 +7055,8 @@ async function commandDev(args) {
         fileStores: new Map(),
         port: requestedPort,
         config,
-        personalConnectors: readAppPersonalConnectors(cwd),
+        personalConnectors: manifestDoc?.personal_connectors ?? [],
+        agents: manifestDoc?.agents ?? [],
     };
     // Asset mode needs its deps before we bind anything; the check is cheap and
     // failing early avoids leaving the proxy port bound on a misconfigured app.
@@ -6880,6 +7561,10 @@ async function handleLocalApi(ctx, req, res, url) {
         await handlePersonalConnections(ctx, req, res, path, url);
         return;
     }
+    if (path.startsWith("/agents/")) {
+        await handleAgents(ctx, req, res, path, url);
+        return;
+    }
     // Proxied surfaces → forward to the real instance with the saved token.
     if (path === "/connections" ||
         path === "/queries" ||
@@ -7213,8 +7898,40 @@ export function devComputeTarget(creds, path, search) {
     if (path === "/email" || path === "/email/send") {
         return `${org}${path}${search}`;
     }
+    // Managed agents. The static `/agents/runs/` prefix is matched BEFORE the dynamic
+    // `{agent_ref}` matcher — the same order the backend declares its routes in — or an
+    // agent whose ref is `runs` would shadow the poll target. Both segments are
+    // re-encoded (see `devUrlSegment`) so the ref/request-id lands as exactly one path
+    // segment upstream.
+    if (path.startsWith("/agents/runs/")) {
+        const requestId = devUrlSegment(path.slice("/agents/runs/".length));
+        return requestId ? `${org}/agents/runs/${requestId}${search}` : null;
+    }
+    if (path.startsWith("/agents/")) {
+        const ref = devUrlSegment(path.slice("/agents/".length));
+        return ref ? `${org}/agents/${ref}/invoke${search}` : null;
+    }
     return null;
 }
+// Normalize one path segment for the upstream URL. The browser sends it already
+// percent-encoded (the SDK encodes the name/request-id), so decode-then-encode
+// leaves it encoded exactly ONCE — no `%20` → `%2520` — and a `/` or `?` smuggled
+// into a name can never rewrite the upstream path. Returns null for an empty,
+// undecodable, or multi-segment value.
+function devUrlSegment(raw) {
+    if (!raw || raw.includes("/"))
+        return null;
+    const decoded = devDecodeSegment(raw);
+    return decoded === null ? null : encodeURIComponent(decoded);
+}
+function devDecodeSegment(raw) {
+    try {
+        return decodeURIComponent(raw) || null;
+    }
+    catch {
+        return null;
+    }
+}
 export function devUpstreamAuthFallback(status, degradeOk) {
     if (status !== 401)
         return null;
@@ -7228,6 +7945,22 @@ export function devUpstreamAuthFallback(status, degradeOk) {
         },
     };
 }
+// The local manifest.yaml, parsed — dev's stand-in for the ratified manifest when
+// reproducing prod's app-plane bounds (personal connectors, agents). Missing or
+// malformed → null. A malformed manifest is caught (loudly) at deploy; dev must
+// not crash on it, and callers read null as "nothing declared", which is the safe
+// direction: the declared-only surfaces refuse instead of running unbounded.
+function readLocalManifestDoc(cwd) {
+    const path = join(cwd, APP_MANIFEST_NAME);
+    if (!existsSync(path))
+        return null;
+    try {
+        return parseManifestYaml(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
 // ── personal connectors in dev ────────────────────────────────────────────────
 //
 // The SDK's `personalConnections.*` methods hit the app plane in prod, which is
@@ -7238,20 +7971,6 @@ export function devUpstreamAuthFallback(status, degradeOk) {
 // SQL and LLM. The result: declared tools run against your real connection,
 // undeclared ones are refused exactly as they will be in prod, so a bad call
 // fails locally instead of only after deploy.
-function readAppPersonalConnectors(cwd) {
-    const path = join(cwd, APP_MANIFEST_NAME);
-    if (!existsSync(path))
-        return [];
-    try {
-        return parseManifestYaml(readFileSync(path, "utf8")).personal_connectors ?? [];
-    }
-    catch {
-        // A malformed manifest is caught (loudly) at deploy; dev must not crash on it.
-        // Treating it as "nothing declared" makes personal-connector calls 403 here,
-        // which is the safe direction.
-        return [];
-    }
-}
 // The toolkit slugs an app declared (any tool scope). Mirrors the server's
 // `manifest.personal_connector_toolkits`.
 function pcDeclaredToolkits(entries) {
@@ -7383,6 +8102,86 @@ async function handlePersonalConnections(ctx, req, res, path, url) {
     }
     sendJson(res, 404, { detail: "not found" });
 }
+// ── managed agents in dev ─────────────────────────────────────────────────────
+//
+// `agents.invoke()`/`start()`/`get()` hit the app plane in prod, bounded by the
+// app's ratified manifest. Dev has no ratified app, so it does what it already does
+// for personal connectors: reproduce that bound HERE from the local manifest.yaml
+// and forward the real work to the org/user plane as the signed-in developer. The
+// run is REAL — a real agent, real spend, real side effects — invoked under the
+// developer's own `agent:invoke` grant, so no deploy is needed first. Being the
+// developer's authority, the local gate is a DX guardrail (catch an undeclared
+// agent before deploy), not a security boundary; the bound that matters is the
+// deployed app's ratified manifest.
+const AGENT_NOT_IN_MANIFEST = (label) => ({
+    detail: `agent "${label}" was not in the manifest`,
+});
+async function handleAgents(ctx, req, res, path, url) {
+    // Poll a run — matched FIRST so an agent ref can't shadow it, and deliberately
+    // NOT manifest-gated: upstream already scopes a run to the caller who triggered
+    // it (`_run_or_404`, at the agent:read tier), which is the right bound for
+    // "read back the run you just started".
+    if (path.startsWith("/agents/runs/")) {
+        if (req.method !== "GET")
+            return sendJson(res, 405, { detail: "method not allowed" });
+        return forwardCompute(ctx, req, res, path, url);
+    }
+    // Invoke. Only the single-segment `/agents/{ref}` exists here — the app plane's
+    // artifact/KV surfaces are deliberately not proxied — so anything deeper is a 404.
+    const ref = devDecodeSegment(path.slice("/agents/".length));
+    if (!ref || ref.includes("/"))
+        return sendJson(res, 404, { detail: "not found" });
+    if (req.method !== "POST")
+        return sendJson(res, 405, { detail: "method not allowed" });
+    const refusal = await devAgentRefusal(ctx, ref);
+    if (refusal)
+        return sendJson(res, 403, refusal);
+    await forwardCompute(ctx, req, res, path, url);
+}
+// The local stand-in for prod's `_agent_for_ctx` manifest check: 403 body to send,
+// or null to forward.
+async function devAgentRefusal(ctx, ref) {
+    const declared = ctx.agents;
+    if (declared.includes(ref))
+        return null;
+    // Nothing declared (no manifest.yaml, or a malformed one) ⇒ nothing can match, so
+    // refuse without touching the network — the same "no declaration = refuse" answer
+    // prod's chokepoint gives.
+    if (declared.length === 0)
+        return AGENT_NOT_IN_MANIFEST(ref);
+    // The manifest lists agent NAMES, but a ref may be a uuid (the backend resolves
+    // either), so an opaque ref is resolved upstream and compared by name — a declared
+    // agent addressed by uuid must not 403 here. A non-uuid ref needs no lookup: it can
+    // only be a name, and it is not one of the declared ones.
+    if (!DEV_UUID_RE.test(ref))
+        return AGENT_NOT_IN_MANIFEST(ref);
+    const name = await devAgentName(ctx, ref);
+    if (name === null)
+        return null; // unresolvable — let upstream give its own answer
+    return declared.includes(name) ? null : AGENT_NOT_IN_MANIFEST(name);
+}
+// Resolve an agent ref to its name on the org plane. Null when it can't be resolved
+// (not found, denied, not logged in, unreachable); the invoke is then forwarded so
+// upstream answers authentically (404/403, or the 503 auth fallback) — mirroring the
+// prod order, which resolves the agent (404) before checking the manifest (403).
+async function devAgentName(ctx, ref) {
+    const creds = devCreds(ctx.config);
+    if (!creds)
+        return null;
+    try {
+        const resp = await fetch(`${creds.apiUrl}/api/organizations/${creds.orgUuid}/agents/${encodeURIComponent(ref)}`, {
+            headers: { Authorization: `Bearer ${creds.token}`, "X-Railcode-Source": "local-dev" },
+            redirect: "manual",
+        });
+        if (!resp.ok)
+            return null;
+        const body = (await resp.json());
+        return typeof body.name === "string" ? body.name : null;
+    }
+    catch {
+        return null;
+    }
+}
 async function forwardCompute(ctx, req, res, path, url) {
     // Never reply 401 to the browser — the SDK reloads the page on 401 (loop).
     // Load-time list calls degrade to [] so dataConnectors()/savedQueries()/
@@ -7399,7 +8198,7 @@ async function forwardCompute(ctx, req, res, path, url) {
             return sendJson(res, 200, []);
         return sendJson(res, 503, {
             error: "not_logged_in",
-            message: "Run `railcode login` to use LLM, SQL, saved queries, connectors, and email in dev.",
+            message: "Run `railcode login` to use LLM, SQL, saved queries, connectors, agents, and email in dev.",
         });
     }
     const target = devComputeTarget(creds, path, url.search);
@@ -7650,11 +8449,11 @@ function printDevBanner(ctx, config) {
     const creds = devCreds(config);
     if (creds) {
         console.log(`  account:   ${config.email ?? "?"} @ ${creds.apiUrl}`);
-        console.log(`  compute:   llm/sql/queries/connectors/email → real instance (REAL spend + data)`);
+        console.log(`  compute:   llm/sql/queries/connectors/email/agents → real instance (REAL spend + data)`);
         console.log(`  runs as:   you — your saved token + org permissions (no deploy needed)`);
     }
     else {
-        console.log(`  account:   not logged in — llm/sql/email return 503, connectors empty`);
+        console.log(`  account:   not logged in — llm/sql/email/agents return 503, connectors empty`);
     }
     console.log("");
     console.log("  Ctrl-C to stop.");