railcode 0.1.27 → 0.1.28

package/README.md

@@ -34,6 +34,10 @@ railcode roles <list|create|update|delete|add-member|remove-member|grants|grant|
                                    Org roles + the granular grants table (admin)
 railcode apps <list|show|access|set-access|transfer|delete> ...
                                    Apps + access policy (owner/admin)
+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
 railcode logs <connector|service-connector|llm|email|agent> [filters]
                                    Org observability logs (admin)
@@ -131,6 +135,33 @@ API URL resolution: `--api-url` > `RAILCODE_API_URL` > saved config > prompt.
 Set `RAILCODE_API_TOKEN` to override the saved token in CI. On a `401`, the saved
 token is cleared and you're prompted to `railcode login` again.
 
+## Staying up to date
+
+The CLI keeps itself current. When you run a command in an interactive terminal it
+checks the npm registry — at most once every 6 hours — for a newer `railcode`
+release **within your current major** and, if there is one, installs it globally
+(with whichever package manager it detects: npm/pnpm/yarn/bun) and tells you:
+
+```
+railcode: a new version is available — 0.1.26 → 0.1.27. Updating…
+railcode: updated to 0.1.27. It takes effect on your next command.
+```
+
+It never jumps across a major version (a breaking `2.0.0` is left for you to
+install deliberately), the check is best-effort (a registry/network hiccup is
+silently ignored — it never blocks your command), and it's skipped in
+non-interactive/CI runs so automation never self-mutates a global install. The
+`last_checked_for_updates` timestamp lives in `~/.railcode/update-check.json`, and
+all of the above is printed to **stderr** so `--json` output stays clean.
+
+Environment overrides:
+
+- `RAILCODE_NO_UPDATE=1` — turn auto-update off entirely.
+- `RAILCODE_UPDATE_DRY_RUN=1` — check and print the command it *would* run, without
+  installing (also forces the check even off-TTY; handy for scripts and testing).
+- `RAILCODE_REGISTRY_URL` (falls back to `npm_config_registry`) — point the check
+  at a different npm-compatible registry.
+
 ## `railcode.json`
 
 ```json

package/dist/app-storage.js

@@ -0,0 +1,154 @@
+// Pure helpers behind `railcode app kv ...` / `railcode app files ...`. Kept free
+// of I/O and process state so they unit-test directly (see test/app-storage.test.mjs);
+// the command layer in index.ts does the HTTP, file reads, and printing.
+export class StorageError extends Error {
+}
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Parse + validate the shared scope flags. `allowAll` gates the cross-scope `all`
+// selector to the listing commands (a record/file mutation must name one namespace).
+export function parseScopeSelector(scope, user, role, opts) {
+    const kind = (scope ?? "shared").toLowerCase();
+    const allowed = opts.allowAll ? "shared, user, role, all" : "shared, user, role";
+    if (!["shared", "user", "role", "all"].includes(kind)) {
+        throw new StorageError(`Unknown --scope "${scope}". Use one of: ${allowed}.`);
+    }
+    if (kind === "all") {
+        if (!opts.allowAll) {
+            throw new StorageError("--scope all only lists (kv collections, kv list, files list); a record/file " +
+                "operation must target one scope.");
+        }
+        if (user || role)
+            throw new StorageError("--scope all takes no --user or --role.");
+        return { scope: "all" };
+    }
+    if (kind === "shared") {
+        if (user || role)
+            throw new StorageError("--scope shared takes no --user or --role.");
+        return { scope: "shared" };
+    }
+    if (kind === "user") {
+        if (role)
+            throw new StorageError("--scope user takes no --role.");
+        if (!user)
+            throw new StorageError("--scope user requires --user <member-uuid>.");
+        if (!UUID_RE.test(user))
+            throw new StorageError("--user must be a member UUID.");
+        return { scope: "user", user };
+    }
+    // role
+    if (user)
+        throw new StorageError("--scope role takes no --user.");
+    if (!role)
+        throw new StorageError("--scope role requires --role <role-uuid>.");
+    if (!UUID_RE.test(role))
+        throw new StorageError("--role must be a role UUID.");
+    return { scope: "role", role };
+}
+// The scope selectors as a query string, echoed onto every storage request.
+export function scopeQuery(sel) {
+    const params = new URLSearchParams();
+    params.set("scope", sel.scope);
+    if (sel.user)
+        params.set("user", sel.user);
+    if (sel.role)
+        params.set("role", sel.role);
+    return params.toString();
+}
+// The value for `kv set` — inline JSON or from --file, never both, never neither.
+// A KV value is JSON of any shape: an object, array, string, number, or bool.
+export function parseKvValue(positional, fileText) {
+    const hasPos = typeof positional === "string" && positional.length > 0;
+    const hasFile = typeof fileText === "string";
+    if (hasPos && hasFile) {
+        throw new StorageError("Pass the value inline OR with --file, not both.");
+    }
+    if (!hasPos && !hasFile) {
+        throw new StorageError('Provide a JSON value: railcode app kv set <collection> <key> \'{"n":1}\'  (or --file v.json).');
+    }
+    const raw = hasFile ? fileText : positional;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new StorageError("Value must be valid JSON — an object, array, string, number, or bool " +
+            "(e.g. '{\"n\":1}', '\"hello\"', 42, true).");
+    }
+}
+// --query is a KV `where` clause: a JSON array of [field, op, value] triples, passed
+// through to the same query engine the data plane exposes. Validated here for a clean
+// local error; the server re-validates authoritatively.
+export function parseWhere(raw) {
+    if (raw === undefined)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new StorageError('--query must be JSON, e.g. --query \'[["n","gt",1]]\'.');
+    }
+    if (!Array.isArray(parsed)) {
+        throw new StorageError('--query must be a JSON array of [field, op, value] clauses.');
+    }
+    return raw;
+}
+// --limit/--offset → the API's page/size. offset must be a whole number of pages so
+// the translation is exact (the API pages, it doesn't offset).
+export function pageParams(limit, offset) {
+    const out = {};
+    if (limit !== undefined) {
+        if (!Number.isInteger(limit) || limit <= 0) {
+            throw new StorageError("--limit must be a positive integer.");
+        }
+        out.size = limit;
+    }
+    if (offset !== undefined) {
+        if (!Number.isInteger(offset) || offset < 0) {
+            throw new StorageError("--offset must be a non-negative integer.");
+        }
+        if (limit === undefined)
+            throw new StorageError("--offset requires --limit.");
+        if (offset % limit !== 0) {
+            throw new StorageError("--offset must be a whole multiple of --limit.");
+        }
+        out.page = Math.floor(offset / limit) + 1;
+    }
+    return out;
+}
+// A best-effort content type from a filename extension (upload default:
+// application/octet-stream). The backend forces download on serve regardless.
+export function guessContentType(name) {
+    const ext = name.toLowerCase().split(".").pop() ?? "";
+    const map = {
+        txt: "text/plain",
+        md: "text/markdown",
+        csv: "text/csv",
+        json: "application/json",
+        html: "text/html",
+        css: "text/css",
+        js: "text/javascript",
+        svg: "image/svg+xml",
+        png: "image/png",
+        jpg: "image/jpeg",
+        jpeg: "image/jpeg",
+        gif: "image/gif",
+        webp: "image/webp",
+        pdf: "application/pdf",
+        zip: "application/zip",
+    };
+    return map[ext] ?? "application/octet-stream";
+}
+// Percent-encode each segment of a file name while keeping the `/` separators the
+// scope-aware `{name:path}` route expects.
+export function encodeFilePath(name) {
+    return name
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+// The owner label (member email / role name) for a listing row, or a dash.
+export function ownerCell(scope, ownerLabel) {
+    if (scope === "shared")
+        return "-";
+    return ownerLabel ?? "-";
+}

package/dist/index.js

@@ -6,13 +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";
@@ -27,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;
@@ -59,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)
@@ -74,6 +82,11 @@ the default (${DEFAULT_API_URL}) — never prompted.
 // ---------------------------------------------------------------------------
 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":
@@ -206,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
 // ---------------------------------------------------------------------------
@@ -5447,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"));
@@ -5821,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 {
@@ -5858,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);
@@ -5871,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];
@@ -5910,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)));
 }
@@ -6276,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
 // ---------------------------------------------------------------------------
@@ -6441,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;
@@ -6475,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,
@@ -6484,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.
@@ -6989,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" ||
@@ -7322,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;
@@ -7337,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
@@ -7347,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) {
@@ -7492,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()/
@@ -7508,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);
@@ -7759,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.");

package/dist/orgadmin.js

@@ -178,14 +178,26 @@ export function renderEffective(eff, who) {
     return lines.join("\n");
 }
 export function appTable(apps) {
-    return formatTable(["slug", "name", "status", "access", "your_role", "manage"], apps.map((a) => [
-        a.app_slug,
-        a.name,
-        a.status,
-        a.access_mode,
-        a.your_role ?? "-",
-        a.can_manage ? "yes" : "no",
-    ]));
+    // The `archived` column only appears when something in the list actually IS
+    // archived (i.e. `apps list --archived/--all`), so the default listing is
+    // unchanged for the many people who never archive anything.
+    const showArchived = apps.some((a) => a.archived_at);
+    const columns = ["slug", "name", "status", "access", "your_role", "manage"];
+    if (showArchived)
+        columns.push("archived");
+    return formatTable(columns, apps.map((a) => {
+        const row = [
+            a.app_slug,
+            a.name,
+            a.status,
+            a.access_mode,
+            a.your_role ?? "-",
+            a.can_manage ? "yes" : "no",
+        ];
+        if (showArchived)
+            row.push(a.archived_at ? "yes" : "-");
+        return row;
+    }));
 }
 // Resolve an app reference — a slug (preferred) or a UUID — against a fetched app
 // list.

package/dist/update.js

@@ -0,0 +1,112 @@
+// Self-update support for the `railcode` CLI.
+//
+// Every command run (for a human at an interactive terminal) checks — at most
+// once every 6 hours — whether a newer version is published on the npm registry
+// *within the current major* and, if so, installs it globally and tells the
+// user. The throttle timestamp lives in `~/.railcode/update-check.json`.
+//
+// This file holds only the pure, side-effect-free helpers (version math, the
+// throttle predicate, installer detection) plus the registry fetch, so they can
+// be unit-tested in isolation. The orchestration that reads/writes the state
+// file and spawns the installer lives in `index.ts`.
+export const UPDATE_CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000; // 6 hours
+// Parse a `MAJOR.MINOR.PATCH[-prerelease][+build]` string (a leading `v` is
+// tolerated). Returns null for anything that isn't a plain release triple.
+export function parseSemver(input) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(input.trim());
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] ?? null,
+    };
+}
+// Compare release precedence by (major, minor, patch). Prerelease ordering is
+// intentionally ignored — we exclude prereleases from update candidates.
+export function compareSemver(a, b) {
+    if (a.major !== b.major)
+        return a.major - b.major;
+    if (a.minor !== b.minor)
+        return a.minor - b.minor;
+    return a.patch - b.patch;
+}
+// From all published versions, pick the highest stable release that shares the
+// current major and is strictly newer than it. Prereleases and other majors are
+// skipped, so we never auto-jump across a breaking major boundary. Returns the
+// raw version string to install, or null when already up to date.
+export function pickLatestSameMajor(current, versions) {
+    const cur = parseSemver(current);
+    if (!cur)
+        return null;
+    let best = null;
+    for (const raw of versions) {
+        const sv = parseSemver(raw);
+        if (!sv)
+            continue;
+        if (sv.prerelease)
+            continue; // stable releases only
+        if (sv.major !== cur.major)
+            continue; // stay within the current major
+        if (compareSemver(sv, cur) <= 0)
+            continue; // must be strictly newer
+        if (!best || compareSemver(sv, best.sv) > 0)
+            best = { raw, sv };
+    }
+    return best ? best.raw : null;
+}
+// Decide whether enough time has passed to check again. Missing or unparseable
+// timestamps always check (and get rewritten with a valid one).
+export function shouldCheckForUpdate(lastCheckedIso, nowMs, intervalMs = UPDATE_CHECK_INTERVAL_MS) {
+    if (!lastCheckedIso)
+        return true;
+    const last = Date.parse(lastCheckedIso);
+    if (Number.isNaN(last))
+        return true;
+    return nowMs - last >= intervalMs;
+}
+// Best-effort detection of the global package manager that owns this install, so
+// the self-update uses the same tool the user installed with. We look at the
+// install path first, then the `npm_config_user_agent` a manager sets when it
+// spawns a script. Defaults to npm (the documented install path).
+export function detectGlobalInstaller(installPath, userAgent) {
+    const path = installPath.replace(/\\/g, "/").toLowerCase();
+    const ua = (userAgent ?? "").toLowerCase();
+    if (ua.startsWith("pnpm") || /\/\.?pnpm\//.test(path)) {
+        return { manager: "pnpm", command: "pnpm", args: (spec) => ["add", "-g", spec] };
+    }
+    if (ua.startsWith("yarn") || /\/\.?yarn\//.test(path)) {
+        return { manager: "yarn", command: "yarn", args: (spec) => ["global", "add", spec] };
+    }
+    if (ua.startsWith("bun") || /\/\.bun\//.test(path)) {
+        return { manager: "bun", command: "bun", args: (spec) => ["add", "-g", spec] };
+    }
+    return { manager: "npm", command: "npm", args: (spec) => ["install", "-g", spec] };
+}
+// Fetch every published version of `pkg` from an npm-compatible registry. Uses
+// the abbreviated packument (much smaller than the full doc) and a hard timeout,
+// and returns [] on any failure — the caller treats "couldn't check" as "no
+// update", never an error.
+export async function fetchPackageVersions(registryBase, pkg, timeoutMs = 4000) {
+    const base = registryBase.replace(/\/+$/, "");
+    const url = `${base}/${encodeURIComponent(pkg).replace(/^%40/, "@")}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(url, {
+            headers: { accept: "application/vnd.npm.install-v1+json" },
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return [];
+        const body = (await res.json());
+        return body.versions ? Object.keys(body.versions) : [];
+    }
+    catch {
+        return [];
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "railcode",
-  "version": "0.1.27",
+  "version": "0.1.28",
   "description": "Developer CLI for the multi-tenant Railcode platform: log in, scaffold, and deploy static apps.",
   "license": "MIT",
   "type": "module",