railcode 0.1.13 → 0.1.16

package/dist/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { cpSync, createReadStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, } from "node:fs";
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { createServer, request as httpRequest, } from "node:http";
@@ -12,7 +12,10 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { KvQueryError, kvCount, kvQuery, } from "./dev/kv-query.js";
 import { DbError, formatTable, inferEngine, parseEngine, parseSqlParams, pickSqlSource, } from "./db.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";
+import { llmModelTable, llmProviderTable } from "./llm.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -30,12 +33,16 @@ Developer CLI for the multi-tenant Railcode platform.
 
 Usage:
   railcode login [--api-url <url>]   Sign in and mint a personal API token
-  railcode deploy                    Build (if configured) and deploy the app here
+  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 static|react]
+  railcode init <app> [--template react|static]
   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)
   railcode connector <list|docs|fetch> ...  List connectors / show API docs / proxy a call
+  railcode llm <providers|models>      List the LLM providers/models apps can call
+  railcode manifest <validate|show> ...  Validate ${APP_MANIFEST_NAME} locally / show an app's ratified manifest
   railcode --version
   railcode --help
 
@@ -76,10 +83,20 @@ async function main() {
         case "db":
             await commandDb(args);
             return;
+        case "query":
+        case "queries":
+            await commandQuery(args);
+            return;
         case "connector":
         case "connectors":
             await commandConnector(args);
             return;
+        case "llm":
+            await commandLlm(args);
+            return;
+        case "manifest":
+            await commandManifest(args);
+            return;
         default:
             throw new CliError(`Unknown command: ${args.command}\n\n${HELP}`, 2);
     }
@@ -101,13 +118,13 @@ function parseArgs(argv) {
         const withoutPrefix = item.slice(2);
         const eq = withoutPrefix.indexOf("=");
         if (eq !== -1) {
-            options[toCamel(withoutPrefix.slice(0, eq))] = withoutPrefix.slice(eq + 1);
+            setOption(options, toCamel(withoutPrefix.slice(0, eq)), withoutPrefix.slice(eq + 1));
             continue;
         }
         const key = toCamel(withoutPrefix);
         const next = tail[i + 1];
         if (next && !next.startsWith("--")) {
-            options[key] = next;
+            setOption(options, key, next);
             i += 1;
         }
         else {
@@ -116,6 +133,20 @@ function parseArgs(argv) {
     }
     return { command, rest, options };
 }
+// A string option given twice accumulates into an array (optionString then
+// rejects it with "can only be given once"); a repeated flag just stays true.
+function setOption(options, key, value) {
+    const existing = options[key];
+    if (typeof existing === "string") {
+        options[key] = [existing, value];
+    }
+    else if (Array.isArray(existing)) {
+        existing.push(value);
+    }
+    else {
+        options[key] = value;
+    }
+}
 function toCamel(input) {
     return input.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
 }
@@ -128,6 +159,11 @@ function readCliPackageVersion() {
 // ---------------------------------------------------------------------------
 async function commandLogin(args) {
     const saved = loadConfig();
+    const setupToken = optionString(args, "setupToken");
+    if (setupToken) {
+        await loginWithSetupToken(args, saved, setupToken);
+        return;
+    }
     const apiUrl = await resolveLoginApiUrl(args, saved);
     const serverConfig = (await readJsonOrThrow(await apiFetch(apiUrl, "/api/config", {}), "Server config"));
     const minted = await authorizeCliWithBrowser(apiUrl);
@@ -163,6 +199,41 @@ async function commandLogin(args) {
     }
     console.log(`Token ${minted.token_prefix}... saved to ${CONFIG_PATH}.`);
 }
+// Onboarding path: exchange a short-lived, one-time setup token (minted by the
+// user's browser session) for a personal API token — no TTY or browser needed, so
+// a coding agent can run it. Writes the same config.json as browser login.
+async function loginWithSetupToken(args, saved, setupToken) {
+    const apiUrl = normalizeApiOrigin(optionApiUrl(args) || process.env.RAILCODE_API_URL || saved.apiUrl || DEFAULT_API_URL);
+    const response = await apiFetch(apiUrl, "/api/auth/setup-token/redeem", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ setup_token: setupToken }),
+    });
+    if (response.status === 400 || response.status === 401) {
+        throw new CliError(`Setup token was rejected (${await errorDetail(response)}). Setup tokens are ` +
+            "one-time and expire after ~10 minutes — generate a fresh prompt from the " +
+            "Railcode dashboard and try again.", 1);
+    }
+    const redeemed = (await readJsonOrThrow(response, "Setup token exchange"));
+    if (!redeemed.email || !redeemed.token || !redeemed.token_prefix) {
+        throw new CliError("Setup token exchange did not include an API token.", 1);
+    }
+    saveConfig({
+        ...saved,
+        apiUrl,
+        email: redeemed.email,
+        apiToken: redeemed.token,
+        tokenPrefix: redeemed.token_prefix,
+        orgUuid: redeemed.organization_uuid,
+        orgSlug: redeemed.organization_slug,
+        appHostStrategy: redeemed.app_host_strategy || "two_label",
+    });
+    console.log(`Logged in as ${redeemed.email} (${apiUrl}).`);
+    if (redeemed.organization_slug) {
+        console.log(`Organization: ${redeemed.organization_slug}`);
+    }
+    console.log(`Token ${redeemed.token_prefix}... saved to ${CONFIG_PATH}.`);
+}
 async function authorizeCliWithBrowser(apiUrl) {
     if (!process.stdin.isTTY) {
         throw new CliError("Browser login requires a TTY. Set RAILCODE_API_TOKEN in non-interactive environments.", 2);
@@ -174,9 +245,15 @@ async function authorizeCliWithBrowser(apiUrl) {
             redirect_uri: callback.redirectUri,
             state,
         })}`;
-        console.log("Open this link to authorize the Railcode CLI:");
-        console.log(authorizeUrl);
         console.log("");
+        printUrlBox("Railcode login", authorizeUrl);
+        console.log("");
+        if (openBrowser(authorizeUrl)) {
+            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("Waiting for browser authorization...");
         const code = await callback.code;
         return await exchangeCliAuthCode(apiUrl, code);
@@ -267,6 +344,25 @@ async function startCliAuthCallback(expectedState) {
         },
     };
 }
+function openBrowser(url) {
+    const opener = process.platform === "darwin"
+        ? { command: "open", args: [url] }
+        : process.platform === "win32"
+            ? { command: "cmd", args: ["/c", "start", "", url] }
+            : { command: "xdg-open", args: [url] };
+    try {
+        const child = spawn(opener.command, opener.args, {
+            detached: true,
+            stdio: "ignore",
+        });
+        child.on("error", () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function sendBrowserCallback(response, status, message) {
     response.writeHead(status, { "Content-Type": "text/html" });
     response.end(`<!doctype html><title>Railcode CLI</title><p>${escapeHtml(message)}</p>`);
@@ -324,36 +420,90 @@ async function commandDeploy(args) {
         await runShell(deployPlan.build, cwd);
     }
     const files = collectDeployFiles(deployPlan.root, { appRoot: cwd });
-    // Create-or-resolve the app by slug within the saved org.
-    const app = await resolveOrCreateApp(config, manifest.app);
+    includeAppManifest(files, cwd);
+    validateBundledManifest(files);
     console.log(`Deploying ${files.length} file(s) to ${manifest.app}...`);
-    let response = await postDeploy(config, app.uuid, files);
+    let response = await postDeployBySlug(config, manifest.app, files);
     if (response.status === 401) {
         config = await reLoginOrThrow();
-        const fresh = await resolveOrCreateApp(config, manifest.app);
-        response = await postDeploy(config, fresh.uuid, files);
+        response = await postDeployBySlug(config, manifest.app, files);
     }
     if (!response.ok) {
         throw new CliError(`Deploy failed (${response.status}): ${await errorDetail(response)}`, 1);
     }
+    const result = (await response.json().catch(() => ({})));
+    // One-shot: --private only sets access at this deploy, never persisted —
+    // access is otherwise managed entirely in the dashboard ("Manage access"),
+    // so a plain `railcode deploy` must never silently re-assert a stale mode.
+    const wantsPrivate = Boolean(args.options.private);
+    if (wantsPrivate) {
+        const appUuid = result.app_uuid ?? (await resolveExistingApp(config, manifest.app))?.uuid;
+        if (!appUuid) {
+            throw new CliError("Deployed, but could not resolve the app to set private access.", 1);
+        }
+        await setAppAccessPrivate(config, appUuid);
+    }
     const liveUrl = appLiveUrl(config, manifest.app);
     console.log(`Deployed ${manifest.app}.`);
+    if (result.manifest) {
+        for (const line of renderManifestDeployOutcome(result.manifest))
+            console.log(line);
+    }
+    if (wantsPrivate) {
+        console.log("Access: private (only you can open it).");
+    }
     console.log(liveUrl);
 }
-async function resolveOrCreateApp(config, slug) {
-    const orgPath = `/api/organizations/${config.orgUuid}/apps`;
-    const list = (await readJsonOrThrow(await authedFetch(config, orgPath), "List apps"));
-    const existing = list.find((app) => app.app_slug === slug);
-    if (existing)
-        return existing;
-    const created = await authedFetch(config, orgPath, {
-        method: "POST",
+// Apps are created with organization-wide access; privacy is a separate
+// access-control call (`PUT .../apps/{uuid}/access`), same one the "Manage
+// access" dashboard button uses.
+async function setAppAccessPrivate(config, appUuid) {
+    const response = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/access`, {
+        method: "PUT",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ name: slug, app_slug: slug }),
+        body: JSON.stringify({ mode: "private", members: [] }),
     });
-    return (await readJsonOrThrow(created, "Create app"));
+    if (!response.ok) {
+        throw new CliError(`Deployed, but failed to set private access (${response.status}): ${await errorDetail(response)}`, 1);
+    }
+}
+// The app manifest lives at the APP root (next to railcode.json), but built
+// apps upload their dist tree — carry manifest.yaml into the bundle root so
+// the server sees it either way. An explicit dist copy wins.
+function includeAppManifest(files, appRoot) {
+    if (files.some((file) => file.path === APP_MANIFEST_NAME))
+        return;
+    const source = join(appRoot, APP_MANIFEST_NAME);
+    if (!existsSync(source) || !statSync(source).isFile())
+        return;
+    files.push({
+        path: APP_MANIFEST_NAME,
+        contentType: "application/yaml",
+        data: readFileSync(source),
+    });
+}
+// Fast local failure with the named line — the server re-validates
+// authoritatively (full YAML + org-resource existence).
+function validateBundledManifest(files) {
+    const bundled = files.find((file) => file.path === APP_MANIFEST_NAME);
+    if (!bundled)
+        return;
+    try {
+        parseManifestYaml(bundled.data.toString("utf8"));
+    }
+    catch (error) {
+        if (error instanceof ManifestParseError) {
+            throw new CliError(`Invalid ${APP_MANIFEST_NAME}: ${error.message}`, 2);
+        }
+        throw error;
+    }
+}
+async function resolveExistingApp(config, slug) {
+    const orgPath = `/api/organizations/${config.orgUuid}/apps`;
+    const list = (await readJsonOrThrow(await authedFetch(config, orgPath), "List apps"));
+    return list.find((app) => app.app_slug === slug) ?? null;
 }
-async function postDeploy(config, appUuid, files) {
+async function postDeployBySlug(config, appSlug, files) {
     // The deploy API is multipart: one part named "files" per file, with the
     // relative path carried as the part filename.
     const form = new FormData();
@@ -361,7 +511,7 @@ async function postDeploy(config, appUuid, files) {
         const bytes = new Uint8Array(file.data);
         form.append("files", new Blob([bytes], { type: file.contentType }), file.path);
     }
-    return authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${appUuid}/deploy`, { method: "POST", body: form });
+    return authedFetch(config, `/api/organizations/${config.orgUuid}/apps/by-slug/${encodeURIComponent(appSlug)}/deploy`, { method: "POST", body: form });
 }
 function collectDeployFiles(root, options) {
     if (!existsSync(root) || !statSync(root).isDirectory()) {
@@ -492,7 +642,7 @@ async function commandInit(args) {
 function initTemplate(args) {
     const value = args.options.template;
     if (value === undefined)
-        return "static";
+        return "react";
     if (value === true)
         throw new CliError("--template requires static or react.", 2);
     if (value === "static" || value === "react")
@@ -511,8 +661,14 @@ function writeReactStarter(target, app) {
     writeFileSync(join(target, "vite.config.ts"), reactViteConfig());
     mkdirSync(join(target, "src"), { recursive: true });
     writeFileSync(join(target, "src", "main.tsx"), reactMainTsx());
+    writeFileSync(join(target, "src", "railcode.d.ts"), reactRailcodeTypes());
+    writeFileSync(join(target, "src", "vite-env.d.ts"), reactViteEnvTypes());
     writeFileSync(join(target, "src", "App.tsx"), reactAppTsx(app));
     writeFileSync(join(target, "src", "styles.css"), reactStylesCss());
+    const assetsDir = resolveReactTemplateAssetsDir();
+    if (assetsDir) {
+        cpSync(assetsDir, join(target, "src", "assets"), { recursive: true });
+    }
 }
 function starterIndexHtml(app) {
     // Plain HTML/JS starter — no build step. It loads the data-plane SDK and
@@ -563,16 +719,16 @@ function reactPackageJson(app) {
             preview: "vite preview",
         },
         dependencies: {
-            react: "^19.0.0",
-            "react-dom": "^19.0.0",
+            react: "^19.2.0",
+            "react-dom": "^19.2.0",
             zustand: "^5.0.0",
         },
         devDependencies: {
-            "@vitejs/plugin-react": "^5.0.0",
+            "@vitejs/plugin-react": "^6.0.0",
             "@types/react": "^19.0.0",
             "@types/react-dom": "^19.0.0",
-            typescript: "^5.9.0",
-            vite: "^7.0.0",
+            typescript: "^6.0.0",
+            vite: "^8.0.0",
         },
     }, null, 2)}\n`;
 }
@@ -595,9 +751,9 @@ function reactIndexHtml(app) {
 function reactTsConfig() {
     return `${JSON.stringify({
         compilerOptions: {
-            target: "ES2020",
+            target: "ES2022",
             useDefineForClassFields: true,
-            lib: ["DOM", "DOM.Iterable", "ES2020"],
+            lib: ["DOM", "DOM.Iterable", "ES2022"],
             allowJs: false,
             skipLibCheck: true,
             esModuleInterop: true,
@@ -605,7 +761,7 @@ function reactTsConfig() {
             strict: true,
             forceConsistentCasingInFileNames: true,
             module: "ESNext",
-            moduleResolution: "Node",
+            moduleResolution: "Bundler",
             resolveJsonModule: true,
             isolatedModules: true,
             noEmit: true,
@@ -615,114 +771,2569 @@ function reactTsConfig() {
         references: [],
     }, null, 2)}\n`;
 }
-function reactViteConfig() {
-    return `import { defineConfig } from "vite";
-import react from "@vitejs/plugin-react";
+function reactViteConfig() {
+    return `import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    outDir: "dist",
+  },
+});
+`;
+}
+function reactRailcodeTypes() {
+    return `type Me = {
+  user: { uuid: string; name: string; email: string };
+  app: { uuid: string; slug: string; name: string };
+  org: { uuid: string; slug: string; name: string };
+};
+
+type AppUser = {
+  uuid: string;
+  name: string;
+  email: string;
+  role: string | null;
+};
+
+type KvRecord<T = unknown> = {
+  key: string;
+  value: T;
+  updated_at: string;
+};
+
+type WhereOp = "eq" | "ne" | "gt" | "gte" | "lt" | "lte" | "in";
+
+type KvQuery<T = unknown> = {
+  where(field: string, op: WhereOp, value: unknown): KvQuery<T>;
+  prefix(value: string): KvQuery<T>;
+  updatedSince(value: string | Date): KvQuery<T>;
+  updatedBefore(value: string | Date): KvQuery<T>;
+  orderBy(field: string, direction?: "asc" | "desc"): KvQuery<T>;
+  page(page?: number, size?: number): Promise<KvRecord<T>[]>;
+  first(): Promise<KvRecord<T> | null>;
+  count(): Promise<number>;
+};
+
+type Collection<T = unknown> = {
+  get(key: string): Promise<T | null>;
+  put(key: string, value: T): Promise<T>;
+  delete(key: string): Promise<void>;
+  list(): Promise<KvRecord<T>[]>;
+  query(): KvQuery<T>;
+  where(field: string, op: WhereOp, value: unknown): KvQuery<T>;
+  prefix(value: string): KvQuery<T>;
+};
+
+type FileMeta = {
+  name: string;
+  content_type: string;
+  size: number;
+  updated_at: string;
+};
+
+type SqlRows = Array<Record<string, unknown>> & {
+  columns?: string[];
+  rowcount?: number;
+  truncated?: boolean;
+};
+
+type DataConnectorInfo = {
+  engine: "postgres" | "bigquery" | "snowflake" | string;
+  name: string;
+};
+
+type DatabaseHandle = {
+  runSQL(query: string, params?: unknown[]): Promise<SqlRows>;
+};
+
+type DatabaseNamespace = ((connection: string) => DatabaseHandle) & DatabaseHandle;
+
+type SavedQueryInfo = {
+  name: string;
+  description: string;
+  params: { name: string; type: string }[];
+  version: number;
+};
+
+type ServiceConnectorInfo = {
+  name: string;
+  description: string | null;
+  auth_type: string;
+  allowed_methods: string[];
+};
+
+type ServiceConnectorResponse = {
+  status: number;
+  ok: boolean;
+  headers: Record<string, string>;
+  truncated: boolean;
+  text(): Promise<string>;
+  json<T = unknown>(): Promise<T>;
+};
+
+type LlmMessage = { role: "system" | "user" | "assistant"; content: string };
+
+type LlmOutputSpec = { type?: "text" } | { type: "json"; schema: Record<string, unknown> };
+
+type LlmOptions = {
+  /** A catalog model name (see llmProviders()); its provider is implied. */
+  model?: string;
+  /** A provider name; without a model, routes to that provider's default model. */
+  provider?: string;
+  system?: string;
+  output?: LlmOutputSpec;
+  temperature?: number;
+  maxOutputTokens?: number;
+  metadata?: Record<string, unknown>;
+};
+
+type LlmUsage = { inputTokens: number; outputTokens: number; totalTokens: number };
+
+type LlmResult = {
+  text: string;
+  output: unknown | null;
+  usage: LlmUsage;
+  cost: string | null;
+  provider: string;
+  model: string;
+  finishReason: string | null;
+  requestId: string;
+};
+
+type LlmStreamEvent =
+  | { type: "text"; text: string }
+  | {
+      type: "done";
+      usage: LlmUsage;
+      cost: string | null;
+      provider: string;
+      model: string;
+      finishReason: string | null;
+      requestId: string;
+    }
+  | { type: "error"; error: string; message: string; requestId: string };
+
+type LlmModelInfo = { model: string; default: boolean };
+
+type LlmProviderInfo = { provider: string; default: boolean; models: LlmModelInfo[] };
+
+declare const me: () => Promise<Me>;
+declare const appUsers: () => Promise<AppUser[]>;
+declare const designSystem: () => Promise<string>;
+declare const db: { collection<T = unknown>(name: string): Collection<T> };
+declare const files: {
+  upload(name: string, data: Blob | ArrayBuffer | ArrayBufferView, contentType?: string): Promise<FileMeta>;
+  url(name: string): string;
+  list(): Promise<FileMeta[]>;
+  delete(name: string): Promise<void>;
+};
+declare const data: DatabaseNamespace;
+declare const postgres: DatabaseNamespace;
+declare const bigquery: DatabaseNamespace;
+declare const snowflake: DatabaseNamespace;
+declare const dataConnectors: () => Promise<DataConnectorInfo[]>;
+declare const savedQueries: () => Promise<SavedQueryInfo[]>;
+declare const query: (name: string, params?: Record<string, unknown>) => Promise<SqlRows>;
+declare const serviceConnectors: () => Promise<ServiceConnectorInfo[]>;
+declare const connector: (name: string) => {
+  fetch(path: string, opts?: { method?: string; body?: string }): Promise<ServiceConnectorResponse>;
+};
+declare const llm: {
+  generate(input: string | LlmMessage[], opts?: LlmOptions): Promise<LlmResult>;
+  stream(input: string | LlmMessage[], opts?: LlmOptions): AsyncIterable<LlmStreamEvent>;
+};
+declare const llmProviders: () => Promise<LlmProviderInfo[]>;
+`;
+}
+function reactViteEnvTypes() {
+    return `/// <reference types="vite/client" />
+`;
+}
+function reactMainTsx() {
+    return `import React from "react";
+import ReactDOM from "react-dom/client";
+import { App } from "./App";
+import "./styles.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);
+`;
+}
+function reactAppTsx(app) {
+    return `import {
+  useEffect,
+  useRef,
+  useState,
+  type ChangeEvent,
+  type FormEvent,
+  type ReactNode,
+} from "react";
+import { create } from "zustand";
+import postgresLogo from "./assets/postgres.svg";
+import bigqueryLogo from "./assets/bigquery.png";
+import stripeLogo from "./assets/connectors/stripe.png";
+import posthogLogo from "./assets/connectors/posthog.svg";
+import mixpanelLogo from "./assets/connectors/mixpanel.png";
+import resendLogo from "./assets/connectors/resend.svg";
+import clerkLogo from "./assets/connectors/clerk.png";
+import openaiLogo from "./assets/llm/openai.svg";
+import anthropicLogo from "./assets/llm/anthropic.png";
+import geminiLogo from "./assets/llm/gemini.png";
+import bedrockLogo from "./assets/llm/bedrock.png";
+
+const APP_SLUG = "${app}";
+
+type TodoValue = {
+  text: string;
+  done: boolean;
+  authorName: string;
+  authorEmail: string;
+  updatedAt: string;
+};
+
+type AppState = {
+  loading: boolean;
+  error: string | null;
+  identity: Me | null;
+  users: AppUser[];
+  todos: KvRecord<TodoValue>[];
+  fileList: FileMeta[];
+  dataConnectorList: DataConnectorInfo[];
+  savedQueryList: SavedQueryInfo[];
+  serviceConnectorList: ServiceConnectorInfo[];
+  load: () => Promise<void>;
+  addTodo: (text: string) => Promise<void>;
+  toggleTodo: (row: KvRecord<TodoValue>) => Promise<void>;
+  deleteTodo: (key: string) => Promise<void>;
+  uploadFile: (file: File) => Promise<void>;
+  deleteFile: (name: string) => Promise<void>;
+  clearError: () => void;
+};
+
+function message(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? value.slice(0, max - 1) + "…" : value;
+}
+
+function formatBytes(value: number | undefined): string {
+  if (!value) return "0 B";
+  if (value < 1024) return value + " B";
+  if (value < 1024 * 1024) return (value / 1024).toFixed(1) + " KB";
+  return (value / (1024 * 1024)).toFixed(1) + " MB";
+}
+
+function firstName(name: string): string {
+  const trimmed = name.trim();
+  const space = trimmed.indexOf(" ");
+  return space === -1 ? trimmed : trimmed.slice(0, space);
+}
+
+function initials(name: string): string {
+  const parts = name.trim().split(/\\s+/);
+  const first = parts[0]?.[0] || "";
+  const last = parts.length > 1 ? parts[parts.length - 1][0] : "";
+  return (first + last).toUpperCase();
+}
+
+function relativeTime(iso: string): string {
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) return "";
+  const diffMs = Date.now() - then;
+  const minute = 60000;
+  const hour = 60 * minute;
+  const day = 24 * hour;
+  if (diffMs < minute) return "just now";
+  if (diffMs < hour) return Math.round(diffMs / minute) + "m ago";
+  if (diffMs < day) return Math.round(diffMs / hour) + "h ago";
+  return Math.round(diffMs / day) + "d ago";
+}
+
+function refreshTodos() {
+  return db.collection<TodoValue>("todos").query().orderBy("updatedAt", "desc").page(1, 20);
+}
+
+const useAppStore = create<AppState>((set, get) => ({
+  loading: false,
+  error: null,
+  identity: null,
+  users: [],
+  todos: [],
+  fileList: [],
+  dataConnectorList: [],
+  savedQueryList: [],
+  serviceConnectorList: [],
+
+  async load() {
+    set({ loading: true, error: null });
+    const results = await Promise.allSettled([
+      me(),
+      appUsers(),
+      refreshTodos(),
+      files.list(),
+      dataConnectors(),
+      savedQueries(),
+      serviceConnectors(),
+    ]);
+
+    const failures = results
+      .filter((result): result is PromiseRejectedResult => result.status === "rejected")
+      .map((result) => message(result.reason));
+
+    set({
+      loading: false,
+      error: failures[0] || null,
+      identity: results[0].status === "fulfilled" ? results[0].value : get().identity,
+      users: results[1].status === "fulfilled" ? results[1].value : get().users,
+      todos: results[2].status === "fulfilled" ? results[2].value : get().todos,
+      fileList: results[3].status === "fulfilled" ? results[3].value : get().fileList,
+      dataConnectorList:
+        results[4].status === "fulfilled" ? results[4].value : get().dataConnectorList,
+      savedQueryList: results[5].status === "fulfilled" ? results[5].value : get().savedQueryList,
+      serviceConnectorList:
+        results[6].status === "fulfilled" ? results[6].value : get().serviceConnectorList,
+    });
+  },
+
+  async addTodo(text) {
+    try {
+      const identity = get().identity || (await me());
+      const id = crypto.randomUUID();
+      const value: TodoValue = {
+        text,
+        done: false,
+        authorName: identity.user.name,
+        authorEmail: identity.user.email,
+        updatedAt: new Date().toISOString(),
+      };
+      await db.collection<TodoValue>("todos").put(id, value);
+      set({ todos: await refreshTodos(), identity, error: null });
+    } catch (error) {
+      set({ error: message(error) });
+    }
+  },
+
+  async toggleTodo(row) {
+    try {
+      const next: TodoValue = { ...row.value, done: !row.value.done, updatedAt: new Date().toISOString() };
+      await db.collection<TodoValue>("todos").put(row.key, next);
+      set({ todos: await refreshTodos(), error: null });
+    } catch (error) {
+      set({ error: message(error) });
+    }
+  },
+
+  async deleteTodo(key) {
+    try {
+      await db.collection<TodoValue>("todos").delete(key);
+      set({ todos: await refreshTodos(), error: null });
+    } catch (error) {
+      set({ error: message(error) });
+    }
+  },
+
+  async uploadFile(file) {
+    try {
+      const contentType = file.type || "application/octet-stream";
+      await files.upload(file.name, file, contentType);
+      set({ fileList: await files.list(), error: null });
+    } catch (error) {
+      set({ error: message(error) });
+    }
+  },
+
+  async deleteFile(name) {
+    try {
+      await files.delete(name);
+      set({ fileList: await files.list(), error: null });
+    } catch (error) {
+      set({ error: message(error) });
+    }
+  },
+
+  clearError() {
+    set({ error: null });
+  },
+}));
+
+function usePrefersReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    const mql = window.matchMedia("(prefers-reduced-motion: reduce)");
+    setReduced(mql.matches);
+    const handler = () => setReduced(mql.matches);
+    mql.addEventListener("change", handler);
+    return () => mql.removeEventListener("change", handler);
+  }, []);
+  return reduced;
+}
+
+function Icon({ name, className }: { name: string; className?: string }) {
+  return (
+    <svg className={className ? "icon " + className : "icon"}>
+      <use href={"#i-" + name}></use>
+    </svg>
+  );
+}
+
+type CodeLanguage = "js" | "sql";
+type CodeTokenType = "string" | "keyword" | "number" | "call" | "punct" | "comment";
+
+const CODE_TOKEN_RE =
+  /('[^']*')|(\\bawait\\b)|(\\b\\d+\\b)|([A-Za-z_$][\\w$]*(?=\\())|([^\\s'A-Za-z0-9_$]+)|(\\s+)|([A-Za-z_$][\\w$]*)/g;
+const SQL_TOKEN_RE =
+  /(--[^\\n]*)|('[^']*')|(\\b\\d+\\b)|(\\b(?:select|from|where|order|by|limit|group|having|join|left|right|inner|outer|on|as|and|or|desc|asc|insert|update|delete|values|set|create|table|view)\\b)|([A-Za-z_][\\w$]*)|([^\\s'A-Za-z0-9_]+)|(\\s+)/gi;
+
+function tokenizeCode(code: string): { type: CodeTokenType | null; text: string }[] {
+  const tokens: { type: CodeTokenType | null; text: string }[] = [];
+  const types: (CodeTokenType | null)[] = ["string", "keyword", "number", "call", "punct", null, null];
+  let match: RegExpExecArray | null;
+  CODE_TOKEN_RE.lastIndex = 0;
+  while ((match = CODE_TOKEN_RE.exec(code))) {
+    const groupIndex = match.slice(1).findIndex((group) => group !== undefined);
+    tokens.push({ type: types[groupIndex], text: match[groupIndex + 1] });
+  }
+  return tokens;
+}
+
+function tokenizeSql(code: string): { type: CodeTokenType | null; text: string }[] {
+  const tokens: { type: CodeTokenType | null; text: string }[] = [];
+  const types: (CodeTokenType | null)[] = [
+    "comment",
+    "string",
+    "number",
+    "keyword",
+    null,
+    "punct",
+    null,
+  ];
+  let match: RegExpExecArray | null;
+  SQL_TOKEN_RE.lastIndex = 0;
+  while ((match = SQL_TOKEN_RE.exec(code))) {
+    const groupIndex = match.slice(1).findIndex((group) => group !== undefined);
+    tokens.push({ type: types[groupIndex], text: match[groupIndex + 1] });
+  }
+  return tokens;
+}
+
+function CodeHighlight({ code, language = "js" }: { code: string; language?: CodeLanguage }) {
+  const tokens = language === "sql" ? tokenizeSql(code) : tokenizeCode(code);
+  return (
+    <>
+      {tokens.map((token, index) =>
+        token.type ? (
+          <span className={"code-" + token.type} key={index}>
+            {token.text}
+          </span>
+        ) : (
+          token.text
+        ),
+      )}
+    </>
+  );
+}
+
+function Reveal({ code, below, children }: { code: string; below?: boolean; children: ReactNode }) {
+  return (
+    <span className="reveal" tabIndex={0} aria-label={"SDK call: " + code}>
+      {children}
+      <span className={below ? "reveal-tip is-below" : "reveal-tip"}>
+        <CodeHighlight code={code} />
+      </span>
+    </span>
+  );
+}
+
+function ActionTip({
+  code,
+  className,
+  children,
+}: {
+  code: string;
+  className?: string;
+  children: ReactNode;
+}) {
+  return (
+    <span className={className ? "action-tip " + className : "action-tip"}>
+      {children}
+      <span className="action-tip-pop">
+        <CodeHighlight code={code} />
+      </span>
+    </span>
+  );
+}
+
+function ThemeToggle() {
+  const [theme, setTheme] = useState<"light" | "dark" | null>(null);
+
+  useEffect(() => {
+    const stored = localStorage.getItem("theme");
+    if (stored === "light" || stored === "dark") {
+      setTheme(stored);
+      document.documentElement.setAttribute("data-theme", stored);
+    }
+  }, []);
+
+  function toggle() {
+    const mql = window.matchMedia("(prefers-color-scheme: dark)");
+    const current = theme || (mql.matches ? "dark" : "light");
+    const next = current === "dark" ? "light" : "dark";
+    setTheme(next);
+    document.documentElement.setAttribute("data-theme", next);
+    localStorage.setItem("theme", next);
+  }
+
+  return (
+    <button className="theme-toggle" type="button" onClick={toggle} aria-label="Toggle color theme">
+      <Icon name="sun" className="icon-sun" />
+      <Icon name="moon" className="icon-moon" />
+    </button>
+  );
+}
+
+function Hero() {
+  const { identity, users } = useAppStore();
+  const name = identity ? firstName(identity.user.name) : "…";
+  const teammates = users.filter((user) => user.uuid !== identity?.user.uuid);
+
+  return (
+    <section className="hero">
+      <h1>
+        Welcome to Railcode, <Reveal code="await me()" below>{name}</Reveal>!
+      </h1>
+      <p className="hero-sub">
+        This is an interactive guide showing a little bit of what Railcode apps can do. But
+        don&apos;t worry about memorizing anything, your coding agent will know what to do.
+      </p>
+      <div className="team-row">
+        <div className="avatar-stack">
+          {identity ? (
+            <div className="avatar is-you" title={identity.user.name + " · you"}>
+              {initials(identity.user.name)}
+            </div>
+          ) : null}
+          {teammates.slice(0, 4).map((user) => (
+            <div className="avatar" key={user.uuid} title={user.name + (user.role ? " · " + user.role : "")}>
+              {initials(user.name)}
+            </div>
+          ))}
+        </div>
+        <Reveal code="await appUsers()" below>
+          <span className="team-caption">
+            {users.length || 1} teammate{users.length === 1 ? "" : "s"} in {identity?.org.name || "your org"}
+          </span>
+        </Reveal>
+      </div>
+    </section>
+  );
+}
+
+function GuideSection({
+  title,
+  body,
+  children,
+}: {
+  title: string;
+  body: string;
+  children: ReactNode;
+}) {
+  return (
+    <section className="guide-section">
+      <div className="guide-copy">
+        <h2>{title}</h2>
+        <p>{body}</p>
+      </div>
+      <div className="guide-demo">{children}</div>
+    </section>
+  );
+}
+
+function TodosCard() {
+  const { todos, addTodo, toggleTodo, deleteTodo } = useAppStore();
+  const [text, setText] = useState("");
+
+  function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    const value = text.trim();
+    if (!value) return;
+    setText("");
+    void addTodo(value);
+  }
+
+  return (
+    <article className="card">
+      <div className="card-head">
+        <div>
+          <div className="card-title-row">
+            <Icon name="checklist" />
+            <span className="card-title">
+              <Reveal
+                code={\`await db
+  .collection('todos')
+  .query()
+  .orderBy('updatedAt', 'desc')
+  .page(1, 20)\`}
+              >
+                To-dos
+              </Reveal>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <form className="add-row" onSubmit={submit}>
+        <input
+          className="field"
+          type="text"
+          placeholder="Add a to-do…"
+          maxLength={80}
+          autoComplete="off"
+          value={text}
+          onChange={(event) => setText(event.target.value)}
+        />
+        <ActionTip code={\`await db.collection('todos').put(id, {
+  text,
+  done: false
+})\`}
+        >
+          <button className="btn btn-primary" type="submit">
+            <Icon name="plus" />
+            Add
+          </button>
+        </ActionTip>
+      </form>
+
+      <div className="todo-list" aria-live="polite">
+        {todos.length ? (
+          todos.map((row) => (
+            <div className={row.value.done ? "todo-row is-done" : "todo-row"} key={row.key}>
+              <ActionTip code={\`await db.collection('todos').put(key, {
+  ...todo,
+  done: \${!row.value.done}
+})\`}
+              >
+                <button
+                  className="checkbox"
+                  type="button"
+                  aria-label={row.value.done ? "Mark not done" : "Mark done"}
+                  aria-pressed={row.value.done}
+                  onClick={() => void toggleTodo(row)}
+                >
+                  <Icon name="check" />
+                </button>
+              </ActionTip>
+              <div className="todo-body">
+                <div className="todo-text">{row.value.text}</div>
+                <div className="todo-meta">
+                  Added by {row.value.authorName} &middot; {relativeTime(row.updated_at)}
+                </div>
+              </div>
+              <ActionTip code="await db.collection('todos').delete(key)">
+                <button
+                  className="row-delete"
+                  type="button"
+                  aria-label="Delete to-do"
+                  onClick={() => void deleteTodo(row.key)}
+                >
+                  <Icon name="x" />
+                </button>
+              </ActionTip>
+            </div>
+          ))
+        ) : (
+          <p className="empty-note">No to-dos yet &mdash; add the first one.</p>
+        )}
+      </div>
+    </article>
+  );
+}
+
+function FilesCard() {
+  const { fileList, uploadFile, deleteFile } = useAppStore();
+  const inputRef = useRef<HTMLInputElement | null>(null);
+  const [uploading, setUploading] = useState(false);
+
+  async function handleFile(event: ChangeEvent<HTMLInputElement>) {
+    const file = event.target.files?.[0];
+    event.target.value = "";
+    if (!file) return;
+    setUploading(true);
+    await uploadFile(file);
+    setUploading(false);
+  }
+
+  return (
+    <article className="card">
+      <div className="card-head">
+        <div>
+          <div className="card-title-row">
+            <Icon name="file" />
+            <span className="card-title">
+              <Reveal code="await files.list()">Files</Reveal>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <div className="file-list" aria-live="polite">
+        {fileList.length ? (
+          fileList.map((file) => (
+            <div className="file-row" key={file.name}>
+              <div className="file-icon">
+                <Icon name="file" />
+              </div>
+              <div className="file-body">
+                <a className="file-name" href={files.url(file.name)} target="_blank" rel="noreferrer">
+                  {file.name}
+                </a>
+                <div className="file-meta tabular">
+                  {formatBytes(file.size)} &middot; {file.content_type}
+                </div>
+              </div>
+              <ActionTip code="await files.delete(file.name)">
+                <button
+                  className="row-delete"
+                  type="button"
+                  aria-label="Delete file"
+                  onClick={() => void deleteFile(file.name)}
+                >
+                  <Icon name="x" />
+                </button>
+              </ActionTip>
+            </div>
+          ))
+        ) : (
+          <p className="empty-note">No files uploaded yet.</p>
+        )}
+      </div>
+
+      <input ref={inputRef} type="file" className="file-input-hidden" onChange={handleFile} />
+      <ActionTip code="await files.upload(file.name, file, file.type)" className="upload-tip">
+        <button
+          className="btn btn-ghost upload-btn"
+          type="button"
+          disabled={uploading}
+          onClick={() => inputRef.current?.click()}
+        >
+          {uploading ? <span className="spinner" /> : <Icon name="upload" />}
+          {uploading ? "Uploading…" : "Upload a file"}
+        </button>
+      </ActionTip>
+    </article>
+  );
+}
+
+function ResultTable({ columns, rows, caption }: { columns: string[]; rows: string[][]; caption: string }) {
+  return (
+    <>
+      <div className="result-status">
+        <span>{caption}</span>
+        <span className="tabular">{rows.length} rows</span>
+      </div>
+      <div className="table-wrap">
+        <table>
+          <thead>
+            <tr>
+              {columns.map((column) => (
+                <th key={column}>{column}</th>
+              ))}
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((row, index) => (
+              <tr key={index}>
+                {row.map((cell, cellIndex) => (
+                  <td className="tabular" key={cellIndex}>
+                    {cell}
+                  </td>
+                ))}
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+    </>
+  );
+}
+
+const MOCK_EVENTS = {
+  columns: ["id", "event", "created_at"],
+  rows: [
+    ["1042", "app.viewed", "2026-07-03 14:02"],
+    ["1041", "note.created", "2026-07-03 11:47"],
+    ["1040", "file.uploaded", "2026-07-02 19:03"],
+    ["1039", "note.created", "2026-07-02 16:21"],
+    ["1038", "session.started", "2026-07-02 09:14"],
+  ],
+};
+
+const MOCK_CUSTOMERS = {
+  columns: ["customer", "region", "lifetime_spend"],
+  rows: [
+    ["Meridian Foods", "emea", "$84,200"],
+    ["Nordic Rail Co.", "emea", "$61,750"],
+    ["Atlas Freight", "emea", "$58,900"],
+    ["Solvane Group", "emea", "$52,100"],
+  ],
+};
+
+type LogoItem = {
+  name: string;
+  src?: string;
+};
+
+function titleCase(value: string): string {
+  return value
+    .replace(/[-_]+/g, " ")
+    .replace(/\\b\\w/g, (char) => char.toUpperCase())
+    .trim();
+}
+
+const LLM_LOGOS: LogoItem[] = [
+  { name: "OpenAI", src: openaiLogo },
+  { name: "Anthropic", src: anthropicLogo },
+  { name: "Gemini", src: geminiLogo },
+  { name: "Bedrock", src: bedrockLogo },
+];
+
+const DATA_LOGO_ITEMS: LogoItem[] = [
+  { name: "postgres", src: postgresLogo },
+  { name: "bigquery", src: bigqueryLogo },
+  { name: "snowflake" },
+  { name: "saved queries" },
+];
+
+const CONNECTOR_LOGO_ITEMS: LogoItem[] = [
+  { name: "stripe", src: stripeLogo },
+  { name: "posthog", src: posthogLogo },
+  { name: "mixpanel", src: mixpanelLogo },
+  { name: "resend", src: resendLogo },
+  { name: "clerk", src: clerkLogo },
+];
+
+function logoInitials(name: string): string {
+  const normalized = titleCase(name);
+  const words = normalized.split(/\\s+/).filter(Boolean);
+  if (words.length > 1) return (words[0][0] + words[1][0]).toUpperCase();
+  return normalized.slice(0, 2).toUpperCase();
+}
+
+function LogoMark({ item }: { item: LogoItem }) {
+  return (
+    <div className={item.src ? "logo-mark has-image" : "logo-mark"} title={titleCase(item.name)}>
+      {item.src ? <img src={item.src} alt="" aria-hidden="true" /> : logoInitials(item.name)}
+    </div>
+  );
+}
+
+function LogoStrip({ items, logoOnly }: { items: LogoItem[]; logoOnly?: boolean }) {
+  return (
+    <div className={logoOnly ? "logo-strip is-logo-only" : "logo-strip"} aria-label="Available services">
+      {items.map((item, index) => (
+        <div className="logo-chip" key={item.name + "-" + index}>
+          <LogoMark item={item} />
+          {logoOnly ? null : <span>{titleCase(item.name)}</span>}
+        </div>
+      ))}
+    </div>
+  );
+}
+
+function DataCard() {
+  return (
+    <article className="card">
+      <div className="card-head">
+        <div>
+          <div className="card-title-row">
+            <Icon name="database" />
+            <span className="card-title">
+              <Reveal code="dataConnectors() · savedQueries()">Data</Reveal>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <LogoStrip items={DATA_LOGO_ITEMS} logoOnly />
+
+      <pre className="sql-preview">
+        <CodeHighlight
+          language="sql"
+          code={\`-- Mock SQL preview
+select id, event, created_at
+from app_events
+order by created_at desc
+limit 5;\`}
+        />
+      </pre>
+      <p className="mock-note">
+        This is mock data. A coding agent can swap this for <code>data('name').runSQL(...)</code>
+        once an admin connects a source.
+      </p>
+
+      <ResultTable columns={MOCK_EVENTS.columns} rows={MOCK_EVENTS.rows} caption="mock response" />
+    </article>
+  );
+}
+
+type ConnResult = { status: string; text: string } | null;
+
+const DEFAULT_CONNECTOR_REQUEST = \`{
+  "path": "/",
+  "body": {}
+}\`;
+
+function ConnectorsCard() {
+  const { serviceConnectorList } = useAppStore();
+  const [active, setActive] = useState(serviceConnectorList[0]?.name || "");
+  const [method, setMethod] = useState("GET");
+  const [requestJson, setRequestJson] = useState(DEFAULT_CONNECTOR_REQUEST);
+  const [result, setResult] = useState<ConnResult>(null);
+  const [busy, setBusy] = useState(false);
+  const [requestError, setRequestError] = useState<string | null>(null);
+
+  const activeConnector = serviceConnectorList.find((item) => item.name === active);
+  const methods = activeConnector?.allowed_methods?.length ? activeConnector.allowed_methods : ["GET", "POST"];
+
+  useEffect(() => {
+    const next = serviceConnectorList[0]?.name || "";
+    setActive(next);
+    setMethod(serviceConnectorList[0]?.allowed_methods?.[0] || "GET");
+    setResult(null);
+    setRequestError(null);
+  }, [serviceConnectorList]);
+
+  async function fetchActive() {
+    if (!activeConnector) return;
+    setBusy(true);
+    setRequestError(null);
+    try {
+      const request = JSON.parse(requestJson) as { path?: unknown; body?: unknown };
+      const path = typeof request.path === "string" && request.path.trim() ? request.path : "/";
+      const body =
+        method === "GET" || method === "HEAD"
+          ? undefined
+          : JSON.stringify(request.body ?? {});
+      const response = await connector(active).fetch(path, { method, body });
+      const text = await response.text();
+      setResult({
+        status: response.status + (response.ok ? " OK" : ""),
+        text: truncate(text, 900) || "[empty response]",
+      });
+    } catch (error) {
+      if (error instanceof SyntaxError) {
+        setRequestError("Request JSON is not valid.");
+      } else {
+        setRequestError(message(error));
+      }
+      setResult(null);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <article className="card">
+      <div className="card-head">
+        <div>
+          <div className="card-title-row">
+            <Icon name="link" />
+            <span className="card-title">
+              <Reveal code="await serviceConnectors()">Connectors</Reveal>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <LogoStrip items={CONNECTOR_LOGO_ITEMS} logoOnly />
+
+      {serviceConnectorList.length ? (
+        <>
+          <div className="request-grid">
+            <label className="control-field">
+              <span>Connector</span>
+              <select
+                value={active}
+                onChange={(event) => {
+                  const next = serviceConnectorList.find((item) => item.name === event.target.value);
+                  setActive(event.target.value);
+                  setMethod(next?.allowed_methods?.[0] || "GET");
+                  setResult(null);
+                  setRequestError(null);
+                }}
+              >
+                {serviceConnectorList.map((item) => (
+                  <option value={item.name} key={item.name}>
+                    {item.name}
+                  </option>
+                ))}
+              </select>
+            </label>
+            <label className="control-field">
+              <span>Request type</span>
+              <select value={method} onChange={(event) => setMethod(event.target.value)}>
+                {methods.map((item) => (
+                  <option value={item} key={item}>
+                    {item}
+                  </option>
+                ))}
+              </select>
+            </label>
+          </div>
+
+          <label className="json-editor">
+            <span>Request JSON</span>
+            <textarea
+              className="field"
+              rows={5}
+              spellCheck={false}
+              value={requestJson}
+              onChange={(event) => {
+                setRequestJson(event.target.value);
+                setRequestError(null);
+              }}
+            />
+          </label>
+
+          {requestError ? <p className="field-error">{requestError}</p> : null}
+
+          <ActionTip code={\`await connector(name).fetch(path, {
+  method,
+  body
+})\`} className="upload-tip">
+            <button className="btn btn-primary" type="button" disabled={busy} onClick={() => void fetchActive()}>
+              {busy ? <span className="spinner" /> : <Icon name="link" />}
+              {busy ? "Sending..." : "Send request"}
+            </button>
+          </ActionTip>
+
+          <div className="response-panel">
+            <div className="result-status">
+              <span>Response</span>
+              <span>{result?.status || "Waiting"}</span>
+            </div>
+            <pre className="preview">{result?.text || "Send a request to see the connector response."}</pre>
+          </div>
+        </>
+      ) : (
+        <p className="empty-note admin-empty">Connect a service in the Admin dashboard to try connectors.</p>
+      )}
+    </article>
+  );
+}
+
+const AI_SAMPLE_PROMPT = "Summarize what this Railcode template demonstrates in one sentence.";
+const AI_SAMPLE_RESPONSE =
+  "This template shows a live Railcode app reading identity, storing notes in KV, uploading files, querying Postgres, invoking a saved query, calling Stripe through a service connector, and generating text — all without handling a single credential in the browser.";
+
+function AiCard() {
+  const [prompt, setPrompt] = useState(AI_SAMPLE_PROMPT);
+  const [response, setResponse] = useState("");
+  const [live, setLive] = useState<boolean | null>(null);
+  const [busy, setBusy] = useState(false);
+  const reduceMotion = usePrefersReducedMotion();
+
+  function revealText(text: string) {
+    if (reduceMotion) {
+      setResponse(text);
+      return;
+    }
+    let i = 0;
+    const interval = setInterval(() => {
+      i += 3;
+      setResponse(text.slice(0, i));
+      if (i >= text.length) clearInterval(interval);
+    }, 12);
+  }
+
+  async function generate() {
+    if (live === false) return;
+    const value = prompt.trim();
+    if (!value) return;
+    setBusy(true);
+    setResponse("");
+    try {
+      const result = await llm.generate(value, { metadata: { feature: "starter-home" } });
+      setLive(true);
+      revealText(result.text || AI_SAMPLE_RESPONSE);
+    } catch {
+      setLive(false);
+      revealText(AI_SAMPLE_RESPONSE);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const note =
+    live === true
+      ? " "
+      : live === false
+        ? "No LLM connected yet — showing a sample response."
+        : "Falls back to a sample response if no LLM is connected.";
+
+  return (
+    <article className="card">
+      <div className="card-head">
+        <div>
+          <div className="card-title-row">
+            <Icon name="chat" />
+            <span className="card-title">
+              <Reveal code="await llm.generate(prompt, opts)">AI</Reveal>
+            </span>
+          </div>
+        </div>
+      </div>
+
+      <div className="ai-body">
+        <LogoStrip items={LLM_LOGOS} logoOnly />
+        <textarea
+          className="field"
+          rows={2}
+          disabled={live === false}
+          value={prompt}
+          onChange={(event) => setPrompt(event.target.value)}
+        />
+        <div className="ai-foot-row">
+          <span className="ai-note">{note}</span>
+          <ActionTip code="await llm.generate(prompt, opts)">
+            <button className="btn btn-primary" type="button" disabled={busy || live === false} onClick={() => void generate()}>
+              {busy ? "Generating…" : "Generate"}
+            </button>
+          </ActionTip>
+        </div>
+        {response ? (
+          <div className="ai-response is-visible">
+            {response}
+            {busy ? <span className="cursor" /> : null}
+          </div>
+        ) : null}
+      </div>
+    </article>
+  );
+}
+
+function IconSprite() {
+  return (
+    <svg width="0" height="0" style={{ position: "absolute" }} aria-hidden="true">
+      <symbol id="i-sun" viewBox="0 0 24 24">
+        <circle cx="12" cy="12" r="5" />
+        <line x1="12" y1="1" x2="12" y2="3" />
+        <line x1="12" y1="21" x2="12" y2="23" />
+        <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
+        <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
+        <line x1="1" y1="12" x2="3" y2="12" />
+        <line x1="21" y1="12" x2="23" y2="12" />
+        <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
+        <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
+      </symbol>
+      <symbol id="i-moon" viewBox="0 0 24 24">
+        <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
+      </symbol>
+      <symbol id="i-plus" viewBox="0 0 24 24">
+        <line x1="12" y1="5" x2="12" y2="19" />
+        <line x1="5" y1="12" x2="19" y2="12" />
+      </symbol>
+      <symbol id="i-x" viewBox="0 0 24 24">
+        <line x1="18" y1="6" x2="6" y2="18" />
+        <line x1="6" y1="6" x2="18" y2="18" />
+      </symbol>
+      <symbol id="i-check" viewBox="0 0 24 24">
+        <polyline points="20 6 9 17 4 12" />
+      </symbol>
+      <symbol id="i-checklist" viewBox="0 0 24 24">
+        <polyline points="9 11 12 14 22 4" />
+        <path d="M21 12v7a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h11" />
+      </symbol>
+      <symbol id="i-upload" viewBox="0 0 24 24">
+        <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+        <polyline points="17 8 12 3 7 8" />
+        <line x1="12" y1="3" x2="12" y2="15" />
+      </symbol>
+      <symbol id="i-file" viewBox="0 0 24 24">
+        <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z" />
+        <polyline points="14 2 14 8 20 8" />
+      </symbol>
+      <symbol id="i-database" viewBox="0 0 24 24">
+        <ellipse cx="12" cy="5" rx="9" ry="3" />
+        <path d="M21 12c0 1.66-4 3-9 3s-9-1.34-9-3" />
+        <path d="M3 5v14c0 1.66 4 3 9 3s9-1.34 9-3V5" />
+      </symbol>
+      <symbol id="i-link" viewBox="0 0 24 24">
+        <path d="M15 7h3a5 5 0 0 1 5 5 5 5 0 0 1-5 5h-3m-6 0H6a5 5 0 0 1-5-5 5 5 0 0 1 5-5h3" />
+        <line x1="8" y1="12" x2="16" y2="12" />
+      </symbol>
+      <symbol id="i-chat" viewBox="0 0 24 24">
+        <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" />
+      </symbol>
+      <symbol id="i-code" viewBox="0 0 24 24">
+        <polyline points="16 18 22 12 16 6" />
+        <polyline points="8 6 2 12 8 18" />
+      </symbol>
+    </svg>
+  );
+}
+
+export function App() {
+  const state = useAppStore();
+
+  useEffect(() => {
+    void state.load();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return (
+    <>
+      <IconSprite />
+      <header className="topbar">
+        <div className="topbar-inner">
+          <div className="brand">
+            <div className="brand-text">
+              <span className="brand-app">{APP_SLUG}</span>
+            </div>
+          </div>
+          <ThemeToggle />
+        </div>
+      </header>
+
+      <div className="shell">
+        {state.error ? (
+          <div className="error-banner">
+            <span>{state.error}</span>
+            <button type="button" onClick={state.clearError}>
+              Dismiss
+            </button>
+          </div>
+        ) : null}
+
+        <Hero />
+
+        <div className="guide-flow">
+          <GuideSection
+            title="Railcode apps can store data"
+            body="A data store is available for every Railcode app. Store data that everyone in the team can see and use, or make the data private to each app user."
+          >
+            <TodosCard />
+          </GuideSection>
+
+          <GuideSection
+            title="They can store files too"
+            body="Uploads are scoped to the app and served back through Railcode, so teams can attach docs, exports, screenshots, and other working files without wiring storage."
+          >
+            <FilesCard />
+          </GuideSection>
+
+          <GuideSection
+            title="They can query data sources"
+            body="Connect all your data sources and build interactive visualizations, run integrated analyses, or build tools to manage operations."
+          >
+            <DataCard />
+          </GuideSection>
+
+          <GuideSection
+            title="They can connect to external services"
+            body="Railcode apps can securely connect to your SaaS services so you can manage refunds, send emails, view data, and anything else you need."
+          >
+            <ConnectorsCard />
+          </GuideSection>
+
+          <GuideSection
+            title="They can use AI"
+            body="Build AI-native apps that use LLMs to enable powerful workflows."
+          >
+            <AiCard />
+          </GuideSection>
+
+        </div>
+
+        <footer>
+          <span>
+            Scaffolded with <code>railcode init --template react</code>
+          </span>
+        </footer>
+      </div>
+    </>
+  );
+}
+`;
+}
+function reactStylesCss() {
+    return `:root {
+  --bg: #ffffff;
+  --bg-inset: #f5f6f8;
+  --card: #ffffff;
+  --ink-1: #1a1f36;
+  --ink-2: #4b5563;
+  --ink-3: #687385;
+  --ink-4: #9aa3b2;
+  --line-quiet: rgba(26, 31, 54, 0.05);
+  --line: rgba(26, 31, 54, 0.1);
+  --line-strong: rgba(26, 31, 54, 0.2);
+  --primary: #2563eb;
+  --primary-ink: #ffffff;
+  --primary-wash: rgba(37, 99, 235, 0.08);
+  --solid: #1a1f36;
+  --solid-ink: #ffffff;
+  --ring: #2563eb;
+  --code-bg: #161b2c;
+  --code-ink: #d7deed;
+  --code-keyword: #c4b5fd;
+  --code-call: #7dd3fc;
+  --code-string: #86efac;
+  --code-number: #fbbf67;
+  --code-punct: rgba(215, 222, 237, 0.5);
+  --radius-sm: 4px;
+  --radius-md: 6px;
+  --radius-lg: 8px;
+  --radius-xl: 12px;
+  --space-2: 8px;
+  --space-3: 12px;
+  --space-4: 16px;
+  --space-5: 20px;
+  --space-6: 24px;
+  --space-10: 40px;
+  --space-12: 48px;
+  --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  --font-mono: ui-monospace, "SFMono-Regular", Menlo, Consolas, "Liberation Mono", monospace;
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #18181b;
+    --bg-inset: #232327;
+    --card: #1f1f23;
+    --ink-1: #ededee;
+    --ink-2: #c2c2c8;
+    --ink-3: #9b9ba3;
+    --ink-4: #6b6b73;
+    --line-quiet: rgba(255, 255, 255, 0.05);
+    --line: rgba(255, 255, 255, 0.09);
+    --line-strong: rgba(255, 255, 255, 0.16);
+    --primary: #60a5fa;
+    --primary-ink: #0f1115;
+    --primary-wash: rgba(96, 165, 250, 0.12);
+    --solid: #ededee;
+    --solid-ink: #18181b;
+    --ring: #60a5fa;
+    color-scheme: dark;
+  }
+}
+
+:root[data-theme="dark"] {
+  --bg: #18181b;
+  --bg-inset: #232327;
+  --card: #1f1f23;
+  --ink-1: #ededee;
+  --ink-2: #c2c2c8;
+  --ink-3: #9b9ba3;
+  --ink-4: #6b6b73;
+  --line-quiet: rgba(255, 255, 255, 0.05);
+  --line: rgba(255, 255, 255, 0.09);
+  --line-strong: rgba(255, 255, 255, 0.16);
+  --primary: #60a5fa;
+  --primary-ink: #0f1115;
+  --primary-wash: rgba(96, 165, 250, 0.12);
+  --solid: #ededee;
+  --solid-ink: #18181b;
+  --ring: #60a5fa;
+  color-scheme: dark;
+}
+
+:root[data-theme="light"] {
+  --bg: #ffffff;
+  --bg-inset: #f5f6f8;
+  --card: #ffffff;
+  --ink-1: #1a1f36;
+  --ink-2: #4b5563;
+  --ink-3: #687385;
+  --ink-4: #9aa3b2;
+  --line-quiet: rgba(26, 31, 54, 0.05);
+  --line: rgba(26, 31, 54, 0.1);
+  --line-strong: rgba(26, 31, 54, 0.2);
+  --primary: #2563eb;
+  --primary-ink: #ffffff;
+  --primary-wash: rgba(37, 99, 235, 0.08);
+  --solid: #1a1f36;
+  --solid-ink: #ffffff;
+  --ring: #2563eb;
+  color-scheme: light;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  min-width: 320px;
+  background: var(--bg);
+  color: var(--ink-1);
+  font-family: var(--font-sans);
+  font-size: 14px;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+h1,
+h2,
+h3,
+p {
+  margin: 0;
+}
+
+button,
+input,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+button {
+  cursor: pointer;
+  border: 0;
+  background: transparent;
+  padding: 0;
+}
+
+button:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+
+:focus-visible {
+  outline: 2px solid var(--ring);
+  outline-offset: 2px;
+}
+
+.tabular {
+  font-variant-numeric: tabular-nums;
+}
+
+.icon {
+  width: 16px;
+  height: 16px;
+  stroke: currentColor;
+  fill: none;
+  stroke-width: 1.8;
+  stroke-linecap: round;
+  stroke-linejoin: round;
+  flex-shrink: 0;
+}
+
+.shell {
+  max-width: 1180px;
+  margin: 0 auto;
+  padding: 0 24px 96px;
+}
+
+/* ---------- topbar ---------- */
+
+.topbar {
+  border-bottom: 1px solid var(--line);
+  margin-bottom: var(--space-10);
+}
+
+.topbar-inner {
+  max-width: 1180px;
+  margin: 0 auto;
+  padding: 18px 24px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: var(--space-4);
+}
+
+.brand {
+  min-width: 0;
+}
+
+.brand-text {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  min-width: 0;
+  font-size: 13px;
+}
+
+.brand-app {
+  font-weight: 600;
+  color: var(--ink-1);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.theme-toggle {
+  width: 32px;
+  height: 32px;
+  border-radius: var(--radius-md);
+  border: 1px solid var(--line);
+  background: transparent;
+  display: grid;
+  place-items: center;
+  color: var(--ink-3);
+  transition:
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+.theme-toggle:hover {
+  background: var(--bg-inset);
+  color: var(--ink-1);
+}
+
+.theme-toggle .icon-moon {
+  display: none;
+}
+:root[data-theme="dark"] .theme-toggle .icon-sun {
+  display: none;
+}
+:root[data-theme="dark"] .theme-toggle .icon-moon {
+  display: block;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) .theme-toggle .icon-sun {
+    display: none;
+  }
+  :root:not([data-theme="light"]) .theme-toggle .icon-moon {
+    display: block;
+  }
+}
+
+/* ---------- hero ---------- */
+
+.hero {
+  margin-bottom: var(--space-12);
+}
+
+.hero h1 {
+  font-size: 30px;
+  font-weight: 650;
+  letter-spacing: -0.01em;
+  line-height: 1.2;
+  text-wrap: balance;
+}
+
+.hero-sub {
+  margin-top: var(--space-2);
+  color: var(--ink-3);
+  font-size: 15px;
+  max-width: 72ch;
+}
+
+.team-row {
+  margin-top: var(--space-6);
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+}
+
+.avatar-stack {
+  display: flex;
+}
+
+.avatar {
+  width: 28px;
+  height: 28px;
+  border-radius: 50%;
+  border: 2px solid var(--bg);
+  background: var(--bg-inset);
+  color: var(--ink-2);
+  display: grid;
+  place-items: center;
+  font-size: 11px;
+  font-weight: 650;
+  margin-left: -6px;
+}
+
+.avatar:first-child {
+  margin-left: 0;
+}
+
+.avatar.is-you {
+  background: var(--primary-wash);
+  color: var(--primary);
+  box-shadow: 0 0 0 1px var(--primary) inset;
+}
+
+.team-caption {
+  color: var(--ink-4);
+  font-size: 13px;
+}
+
+/* ---------- guide flow ---------- */
+
+.guide-flow {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12);
+}
+
+.guide-section {
+  display: grid;
+  grid-template-columns: minmax(0, 0.72fr) minmax(420px, 1fr);
+  gap: var(--space-10);
+  align-items: start;
+  padding-top: var(--space-10);
+  border-top: 1px solid var(--line);
+}
+
+.guide-section:first-child {
+  padding-top: 0;
+  border-top: 0;
+}
+
+.guide-copy {
+  position: sticky;
+  top: 24px;
+}
+
+.guide-copy h2 {
+  font-size: 22px;
+  font-weight: 650;
+  line-height: 1.25;
+  text-wrap: balance;
+}
+
+.guide-copy p {
+  margin-top: var(--space-3);
+  color: var(--ink-3);
+  font-size: 14px;
+  line-height: 1.65;
+  max-width: 42ch;
+}
+
+.guide-demo {
+  min-width: 0;
+}
+
+/* ---------- card ---------- */
+
+.card {
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-xl);
+  padding: var(--space-5);
+  display: flex;
+  flex-direction: column;
+  opacity: 0;
+  transform: translateY(6px);
+  animation: rise 420ms cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+
+.card:nth-of-type(1) {
+  animation-delay: 40ms;
+}
+.card:nth-of-type(2) {
+  animation-delay: 80ms;
+}
+.card:nth-of-type(3) {
+  animation-delay: 120ms;
+}
+
+@keyframes rise {
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.card-head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: var(--space-3);
+  margin-bottom: var(--space-4);
+}
+
+.card-title-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.card-title-row .icon {
+  color: var(--ink-3);
+}
+
+.card-title {
+  font-size: 14px;
+  font-weight: 650;
+}
+
+.pill {
+  flex: none;
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  padding: 3px 9px;
+  border-radius: 100px;
+  font-size: 11px;
+  font-weight: 650;
+  letter-spacing: 0.01em;
+  white-space: nowrap;
+}
+
+/* ---------- buttons & inputs ---------- */
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: 6px;
+  border-radius: var(--radius-md);
+  border: 1px solid transparent;
+  padding: 8px 13px;
+  font-size: 13px;
+  font-weight: 600;
+  transition:
+    background-color 120ms ease,
+    border-color 120ms ease,
+    color 120ms ease,
+    transform 80ms ease;
+  white-space: nowrap;
+}
+
+.btn:active {
+  transform: scale(0.98);
+}
+
+.btn-primary {
+  background: var(--primary);
+  color: var(--primary-ink);
+}
+
+.btn-primary:hover {
+  filter: brightness(1.06);
+}
+
+.btn-ghost {
+  background: transparent;
+  border-color: var(--line);
+  color: var(--ink-2);
+}
+
+.btn-ghost:hover {
+  background: var(--bg-inset);
+  border-color: var(--line-strong);
+}
+
+.btn-ghost.is-active {
+  background: var(--primary-wash);
+  border-color: var(--primary);
+  color: var(--primary);
+}
+
+.field {
+  flex: 1;
+  background: var(--bg-inset);
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
+  padding: 8px 11px;
+  font-size: 13px;
+  color: var(--ink-1);
+}
+
+.field::placeholder {
+  color: var(--ink-4);
+}
+
+.field:focus {
+  background: var(--card);
+  border-color: var(--primary);
+}
+
+textarea.field {
+  resize: vertical;
+  min-height: 64px;
+  line-height: 1.5;
+  width: 100%;
+}
+
+.chip-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+/* ---------- logos ---------- */
+
+.logo-strip {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+  margin-bottom: var(--space-4);
+}
+
+.logo-chip {
+  min-width: 0;
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  padding: 5px 9px 5px 6px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-md);
+  color: var(--ink-2);
+  background: var(--bg);
+  font-size: 12px;
+  font-weight: 600;
+}
+
+.logo-chip span {
+  white-space: nowrap;
+}
+
+.logo-strip.is-logo-only {
+  gap: 10px;
+}
+
+.logo-strip.is-logo-only .logo-chip {
+  padding: 0;
+  border: 0;
+  background: transparent;
+}
+
+.logo-strip.is-logo-only .logo-mark {
+  width: 30px;
+  height: 30px;
+}
+
+.logo-strip.is-logo-only .logo-mark.has-image {
+  border: 0;
+  padding: 3px;
+}
+
+.logo-mark {
+  width: 24px;
+  height: 24px;
+  border-radius: var(--radius-sm);
+  display: grid;
+  place-items: center;
+  background: var(--solid);
+  color: var(--solid-ink);
+  font-family: var(--font-mono);
+  font-size: 9px;
+  font-weight: 750;
+  letter-spacing: 0;
+  overflow: hidden;
+}
+
+.logo-mark.has-image {
+  background: #fff;
+  border: 1px solid var(--line);
+  padding: 4px;
+}
+
+.logo-mark img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+/* ---------- to-dos ---------- */
+
+.add-row {
+  display: flex;
+  gap: 8px;
+  margin-bottom: var(--space-4);
+}
+
+.todo-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+}
+
+.todo-row {
+  display: flex;
+  align-items: flex-start;
+  gap: 10px;
+  padding: 9px 6px;
+  border-radius: var(--radius-md);
+}
+
+.todo-row:hover {
+  background: var(--bg-inset);
+}
+
+.checkbox {
+  padding: 0;
+  margin-top: 1px;
+  width: 17px;
+  height: 17px;
+  border-radius: 5px;
+  border: 1.5px solid var(--line-strong);
+  background: var(--card);
+  display: grid;
+  place-items: center;
+  flex: none;
+  color: transparent;
+  transition:
+    background-color 120ms ease,
+    border-color 120ms ease;
+}
+
+.checkbox .icon {
+  width: 11px;
+  height: 11px;
+  stroke-width: 3;
+  pointer-events: none;
+}
+
+.todo-row.is-done .checkbox {
+  background: var(--solid);
+  border-color: var(--solid);
+  color: var(--solid-ink);
+}
+
+.todo-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.todo-text {
+  font-size: 13.5px;
+  word-break: break-word;
+}
+
+.todo-row.is-done .todo-text {
+  color: var(--ink-4);
+  text-decoration: line-through;
+}
+
+.todo-meta {
+  margin-top: 2px;
+  color: var(--ink-4);
+  font-size: 12px;
+}
+
+.row-delete {
+  flex: none;
+  width: 24px;
+  height: 24px;
+  border-radius: var(--radius-sm);
+  display: grid;
+  place-items: center;
+  color: var(--ink-4);
+  opacity: 0.55;
+  transition:
+    opacity 120ms ease,
+    background-color 120ms ease,
+    color 120ms ease;
+}
+
+.todo-row:hover .row-delete,
+.todo-row:focus-within .row-delete,
+.file-row:hover .row-delete,
+.file-row:focus-within .row-delete {
+  opacity: 1;
+}
+
+.row-delete:hover {
+  background: var(--bg-inset);
+  color: var(--ink-1);
+}
+
+.row-delete .icon {
+  width: 14px;
+  height: 14px;
+  pointer-events: none;
+}
+
+.empty-note {
+  color: var(--ink-4);
+  font-size: 12.5px;
+  padding: 10px 6px;
+}
+
+/* ---------- files ---------- */
+
+.file-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  margin-bottom: var(--space-4);
+}
+
+.file-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 8px 6px;
+  border-radius: var(--radius-md);
+}
+
+.file-row:hover {
+  background: var(--bg-inset);
+}
+
+.file-icon {
+  width: 28px;
+  height: 28px;
+  border-radius: var(--radius-sm);
+  background: var(--bg-inset);
+  display: grid;
+  place-items: center;
+  color: var(--ink-3);
+  flex: none;
+}
+
+.file-icon .icon {
+  width: 14px;
+  height: 14px;
+}
+
+.file-body {
+  flex: 1;
+  min-width: 0;
+}
+
+.file-name {
+  display: block;
+  font-size: 13px;
+  font-weight: 550;
+  color: var(--ink-1);
+  text-decoration: none;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.file-name:hover {
+  text-decoration: underline;
+}
+
+.file-meta {
+  color: var(--ink-4);
+  font-size: 11.5px;
+  font-family: var(--font-mono);
+}
+
+.file-input-hidden {
+  display: none;
+}
+
+.upload-btn {
+  margin-top: auto;
+  align-self: flex-start;
+}
+
+/* ---------- data / connectors result areas ---------- */
+
+.result-area {
+  margin-top: var(--space-4);
+  min-height: 22px;
+}
+
+.result-placeholder {
+  color: var(--ink-4);
+  font-size: 12.5px;
+  padding-top: 2px;
+}
+
+.sql-preview {
+  margin: 0 0 var(--space-3);
+  background: var(--bg-inset);
+  border-radius: var(--radius-md);
+  padding: 11px 12px;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.55;
+  color: var(--ink-2);
+  white-space: pre-wrap;
+  overflow-x: auto;
+}
+
+.mock-note {
+  color: var(--ink-4);
+  font-size: 12.5px;
+  line-height: 1.55;
+  margin-bottom: var(--space-4);
+}
+
+.mock-note code {
+  font-family: var(--font-mono);
+  color: var(--ink-2);
+}
+
+.request-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(120px, 0.42fr);
+  gap: var(--space-3);
+  margin-bottom: var(--space-3);
+}
+
+.control-field,
+.json-editor {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  min-width: 0;
+}
+
+.control-field span,
+.json-editor span {
+  color: var(--ink-4);
+  font-size: 11.5px;
+  font-weight: 650;
+}
+
+.control-field select {
+  width: 100%;
+  min-height: 36px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-md);
+  background: var(--bg-inset);
+  color: var(--ink-1);
+  padding: 7px 10px;
+  font: inherit;
+  font-size: 13px;
+}
+
+.json-editor {
+  margin-bottom: var(--space-3);
+}
+
+.json-editor textarea {
+  font-family: var(--font-mono);
+  font-size: 12px;
+  min-height: 124px;
+}
+
+.field-error {
+  color: #b42318;
+  font-size: 12.5px;
+  margin-bottom: var(--space-3);
+}
+
+.response-panel {
+  margin-top: var(--space-4);
+}
+
+.admin-empty {
+  padding: var(--space-4);
+  border: 1px solid var(--line);
+  border-radius: var(--radius-md);
+  background: var(--bg-inset);
+}
+
+.table-wrap {
+  overflow-x: auto;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-md);
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 12.5px;
+}
+
+th,
+td {
+  text-align: left;
+  padding: 7px 10px;
+  white-space: nowrap;
+}
+
+th {
+  background: var(--bg-inset);
+  color: var(--ink-4);
+  font-weight: 650;
+  font-size: 10.5px;
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+td {
+  color: var(--ink-2);
+  font-family: var(--font-mono);
+  border-top: 1px solid var(--line);
+}
+td:first-child,
+th:first-child {
+  color: var(--ink-1);
+}
+
+.result-status {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  margin-bottom: 8px;
+  font-size: 11.5px;
+  color: var(--ink-4);
+}
+
+.conn-list {
+  display: flex;
+  flex-direction: column;
+  gap: 2px;
+  border: 1px solid var(--line);
+  border-radius: var(--radius-md);
+  overflow: hidden;
+}
+
+.conn-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  padding: 8px 10px;
+  border-top: 1px solid var(--line);
+}
+
+.conn-row:first-child {
+  border-top: none;
+}
+
+.conn-row-main {
+  min-width: 0;
+}
+
+.conn-row-title {
+  font-size: 12.5px;
+  font-weight: 600;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.conn-row-sub {
+  font-size: 11.5px;
+  color: var(--ink-4);
+  font-family: var(--font-mono);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.conn-row-tag {
+  flex: none;
+  font-size: 11px;
+  color: var(--ink-3);
+  font-family: var(--font-mono);
+}
+
+.preview {
+  margin-top: 4px;
+  background: var(--bg-inset);
+  border-radius: var(--radius-md);
+  padding: 10px 12px;
+  font-family: var(--font-mono);
+  font-size: 12px;
+  line-height: 1.55;
+  white-space: pre-wrap;
+  word-break: break-word;
+  max-height: 200px;
+  overflow: auto;
+  color: var(--ink-2);
+}
+
+.loading-row {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  color: var(--ink-4);
+  font-size: 12.5px;
+  padding: 4px 0;
+}
+
+.spinner {
+  width: 12px;
+  height: 12px;
+  border-radius: 50%;
+  border: 1.6px solid var(--line-strong);
+  border-top-color: var(--ink-3);
+  animation: spin 700ms linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* ---------- reveal + action tooltips ---------- */
+
+.reveal {
+  position: relative;
+  display: inline;
+  background: var(--primary-wash);
+  border-radius: var(--radius-sm);
+  padding: 1px 6px;
+  margin: 0 -2px;
+  cursor: help;
+  -webkit-tap-highlight-color: transparent;
+  transition: background-color 120ms ease;
+}
+
+.reveal:hover,
+.reveal:focus-visible {
+  background: color-mix(in srgb, var(--primary-wash) 55%, var(--primary) 22%);
+}
+
+.reveal-tip {
+  position: absolute;
+  left: 50%;
+  bottom: calc(100% + 9px);
+  transform: translateX(-50%) translateY(4px);
+  background: var(--code-bg);
+  color: var(--code-ink);
+  font-family: var(--font-mono);
+  font-size: 11.5px;
+  white-space: pre-wrap;
+  text-align: left;
+  max-width: min(420px, calc(100vw - 24px));
+  width: max-content;
+  line-height: 1.5;
+  padding: 7px 10px;
+  border-radius: var(--radius-md);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.28);
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transition:
+    opacity 140ms ease,
+    transform 140ms ease;
+  z-index: 20;
+}
+
+.reveal-tip::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 5px solid transparent;
+  border-top-color: var(--code-bg);
+}
+
+.reveal-tip.is-below {
+  bottom: auto;
+  top: calc(100% + 9px);
+  transform: translateX(-50%) translateY(-4px);
+}
+
+.reveal-tip.is-below::after {
+  top: auto;
+  bottom: 100%;
+  border-top-color: transparent;
+  border-bottom-color: var(--code-bg);
+}
+
+.code-string {
+  color: var(--code-string);
+}
+
+.code-keyword {
+  color: var(--code-keyword);
+  font-weight: 600;
+}
+
+.code-number {
+  color: var(--code-number);
+}
+
+.code-call {
+  color: var(--code-call);
+}
+
+.code-punct {
+  color: var(--code-punct);
+}
+
+.code-comment {
+  color: var(--ink-4);
+}
 
-export default defineConfig({
-  plugins: [react()],
-  build: {
-    outDir: "dist",
-  },
-});
-`;
+.reveal:hover .reveal-tip,
+.reveal:focus-visible .reveal-tip {
+  opacity: 1;
+  visibility: visible;
+  transform: translateX(-50%) translateY(0);
 }
-function reactMainTsx() {
-    return `import React from "react";
-import ReactDOM from "react-dom/client";
-import { App } from "./App";
-import "./styles.css";
 
-ReactDOM.createRoot(document.getElementById("root")!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>,
-);
-`;
+.action-tip {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  flex: none;
 }
-function reactAppTsx(app) {
-    return `import { useEffect } from "react";
-import { create } from "zustand";
 
-declare const me: () => Promise<{ user: { email: string; name: string } }>;
-declare const db: {
-  collection: (name: string) => {
-    put: (key: string, value: unknown) => Promise<void>;
-    get: (key: string) => Promise<unknown>;
-  };
-};
+.upload-tip {
+  margin-top: auto;
+  align-self: flex-start;
+}
 
-type AppState = {
-  status: string;
-  saved: string;
-  setStatus: (status: string) => void;
-  setSaved: (saved: string) => void;
-};
+.action-tip-pop {
+  position: absolute;
+  left: 50%;
+  bottom: calc(100% + 9px);
+  transform: translateX(-50%) translateY(4px);
+  background: var(--code-bg);
+  color: var(--code-ink);
+  font-family: var(--font-mono);
+  font-size: 11.5px;
+  white-space: pre-wrap;
+  text-align: left;
+  max-width: min(360px, calc(100vw - 24px));
+  width: max-content;
+  line-height: 1.5;
+  padding: 7px 10px;
+  border-radius: var(--radius-md);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.28);
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transition:
+    opacity 140ms ease,
+    transform 140ms ease;
+  z-index: 25;
+}
 
-const useAppStore = create<AppState>((set) => ({
-  status: "Loading your identity...",
-  saved: "Loading saved data...",
-  setStatus: (status) => set({ status }),
-  setSaved: (saved) => set({ saved }),
-}));
+.action-tip-pop::after {
+  content: "";
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 5px solid transparent;
+  border-top-color: var(--code-bg);
+}
 
-export function App() {
-  const { status, saved, setStatus, setSaved } = useAppStore();
+.action-tip:hover .action-tip-pop,
+.action-tip:focus-within .action-tip-pop {
+  opacity: 1;
+  visibility: visible;
+  transform: translateX(-50%) translateY(0);
+}
 
-  useEffect(() => {
-    async function load() {
-      const identity = await me();
-      setStatus("Signed in as " + (identity.user?.email || "unknown"));
+/* ---------- AI card ---------- */
 
-      const docs = db.collection("greetings");
-      await docs.put("hello", { text: "Hello from ${app}!", at: new Date().toISOString() });
-      const value = await docs.get("hello");
-      setSaved(JSON.stringify(value));
-    }
+.ai-body {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-3);
+}
 
-    load().catch((error: unknown) => {
-      setStatus("SDK error: " + (error instanceof Error ? error.message : String(error)));
-    });
-  }, [setSaved, setStatus]);
+.ai-response {
+  margin-top: var(--space-2);
+  padding: 12px 14px;
+  background: var(--bg-inset);
+  border-radius: var(--radius-md);
+  font-size: 13px;
+  line-height: 1.6;
+  color: var(--ink-1);
+}
 
-  return (
-    <main>
-      <h1>${titleCase(app)}</h1>
-      <p>{status}</p>
-      <p>{saved}</p>
-    </main>
-  );
+.cursor {
+  display: inline-block;
+  width: 2px;
+  height: 14px;
+  background: var(--ink-2);
+  vertical-align: -2px;
+  margin-left: 1px;
+  animation: blink 900ms step-end infinite;
 }
-`;
+
+@keyframes blink {
+  50% {
+    opacity: 0;
+  }
 }
-function reactStylesCss() {
-    return `:root {
-  color: #172033;
-  background: #f8fafc;
-  font-family:
-    Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+
+.ai-foot-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
 }
 
-body {
-  margin: 0;
+.ai-note {
+  color: var(--ink-4);
+  font-size: 12px;
 }
 
-main {
-  display: grid;
-  min-height: 100vh;
-  align-content: center;
+/* ---------- error banner ---------- */
+
+.error-banner {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
   gap: 12px;
-  padding: 48px;
+  margin-bottom: var(--space-6);
+  padding: 12px 14px;
+  border: 1px solid var(--line-strong);
+  border-radius: var(--radius-lg);
+  background: var(--bg-inset);
+  color: var(--ink-1);
+  font-size: 13px;
 }
 
-h1,
-p {
-  margin: 0;
+.error-banner button {
+  border: 0;
+  background: transparent;
+  color: var(--ink-3);
+  font-weight: 600;
+  font-size: 12.5px;
+}
+
+.error-banner button:hover {
+  color: var(--ink-1);
+}
+
+footer {
+  max-width: 1180px;
+  margin: var(--space-12) auto 0;
+  padding: var(--space-6) 24px 0;
+  border-top: 1px solid var(--line);
+  color: var(--ink-4);
+  font-size: 12px;
+  display: flex;
+  justify-content: flex-start;
+  gap: var(--space-4);
+}
+
+footer code {
+  font-family: var(--font-mono);
+  color: var(--ink-3);
+}
+
+@media (max-width: 760px) {
+  .guide-section {
+    grid-template-columns: 1fr;
+    gap: var(--space-5);
+  }
+  .guide-copy {
+    position: static;
+  }
+  .hero h1 {
+    font-size: 26px;
+  }
 }
 
-h1 {
-  font-size: 40px;
-  line-height: 1.1;
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    animation: none !important;
+    opacity: 1 !important;
+    transform: none !important;
+  }
+  .cursor {
+    animation: none;
+    opacity: 1;
+  }
+  .spinner {
+    animation-duration: 1400ms;
+  }
 }
 `;
 }
@@ -779,11 +3390,121 @@ async function commandDesignSystem(args) {
     process.stdout.write(markdown.endsWith("\n") || markdown === "" ? markdown : `${markdown}\n`);
 }
 // ---------------------------------------------------------------------------
+// manifest — validate manifest.yaml locally / show an app's manifest state
+// ---------------------------------------------------------------------------
+const MANIFEST_HELP = `railcode manifest — the app authority manifest (${APP_MANIFEST_NAME})
+
+Usage:
+  railcode manifest validate [path]      Strict local parse (default ./${APP_MANIFEST_NAME})
+  railcode manifest show <app>           Ratified doc + pending diff for an app (by slug)
+
+Show options:
+  --json                                 Print the raw manifest envelope
+
+The manifest declares the operations an app performs (saved queries, connector
+endpoints, llm, ad-hoc SQL) and whose authority they run under (run_as). The
+server-side RATIFIED copy is authoritative; a deploy whose manifest adds
+operations the deployer doesn't hold lands as a pending diff awaiting approval.
+No ${APP_MANIFEST_NAME} = run_as: user (pass-through, exactly the pre-manifest
+behavior).
+`;
+async function commandManifest(args) {
+    const sub = args.rest[0] ?? "";
+    switch (sub) {
+        case "validate":
+            await commandManifestValidate(args);
+            return;
+        case "show":
+            await commandManifestShow(args);
+            return;
+        case "":
+        case "help":
+            console.log(MANIFEST_HELP);
+            return;
+        default:
+            throw new CliError(`Unknown manifest subcommand: ${sub}\n\n${MANIFEST_HELP}`, 2);
+    }
+}
+async function commandManifestValidate(args) {
+    const path = resolve(process.cwd(), args.rest[1] ?? APP_MANIFEST_NAME);
+    if (!existsSync(path)) {
+        throw new CliError(`No manifest at ${path}. Without a ${APP_MANIFEST_NAME} the app deploys as run_as: user (pass-through).`, 2);
+    }
+    let doc;
+    try {
+        doc = parseManifestYaml(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error instanceof ManifestParseError) {
+            throw new CliError(`Invalid ${APP_MANIFEST_NAME}: ${error.message}`, 1);
+        }
+        throw error;
+    }
+    console.log(`${relativeLabel(process.cwd(), path)} is valid.`);
+    console.log(renderManifestSummary(doc));
+    console.log("Note: resource names (saved queries, connectors, connections) are checked against your org at deploy.");
+}
+async function commandManifestShow(args) {
+    const slug = args.rest[1];
+    if (!slug)
+        throw new CliError("Usage: railcode manifest show <app> [--json]", 2);
+    const config = requireLogin(args);
+    const list = (await readJsonOrThrow(await authedFetch(config, `/api/organizations/${config.orgUuid}/apps`), "List apps"));
+    const app = list.find((a) => a.app_slug === slug);
+    if (!app)
+        throw new CliError(`No app "${slug}" in your org.`, 1);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/apps/${app.uuid}/manifest`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (resp.status === 403) {
+        throw new CliError("You don't have access to view this app's manifest.", 1);
+    }
+    if (!resp.ok) {
+        throw new CliError(`Could not fetch the manifest (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+    const manifest = (await resp.json());
+    if (args.options.json === true) {
+        console.log(JSON.stringify(manifest, null, 2));
+        return;
+    }
+    console.log(`Manifest for ${slug}`);
+    if (!manifest.ratified && !manifest.pending) {
+        console.log("No manifest — pass-through (runs as each caller, run_as: user).");
+        return;
+    }
+    if (manifest.ratified) {
+        const r = manifest.ratified;
+        const by = r.ratified_by_email ?? "unknown";
+        const when = r.ratified_at ? ` on ${r.ratified_at.slice(0, 10)}` : "";
+        console.log(`Ratified by ${by}${when} (sha256 ${r.content_hash.slice(0, 12)}…)`);
+        console.log(renderManifestSummary(r.document));
+    }
+    else {
+        console.log("Nothing ratified yet — the app runs pass-through until approval.");
+    }
+    if (manifest.pending) {
+        const p = manifest.pending;
+        console.log(`Pending approval (deployed by ${p.created_by_email ?? "unknown"} on ${p.created_at.slice(0, 10)}):`);
+        if (manifest.pending_added.length > 0) {
+            for (const op of manifest.pending_added) {
+                const label = documentOperations(p.document).find((o) => o.type === op.resource_type && o.id === op.resource_id)
+                    ?.label ?? `${op.resource_type} ${op.resource_id}`;
+                console.log(`  + ${label}`);
+            }
+        }
+        else {
+            console.log("  (no new operations)");
+        }
+        console.log(manifest.can_approve
+            ? "You hold these operations — approve/reject from the app's Manifest panel."
+            : "Approval needs an org admin (or any member holding these operations).");
+    }
+}
+// ---------------------------------------------------------------------------
 // db — list data connectors + run read-only SQL (`railcode db list|query`)
 //
-// Data connectors are org-wide; the app is only the scoping/attribution context
-// for the SQL route, so we reuse resolveOrCreateApp (same as deploy/dev) and the
-// bearer, app-scoped endpoints `railcode dev` already forwards to.
+// Data connectors are org-wide, so these commands use the app-less org data
+// plane. They never resolve or create an app.
 // ---------------------------------------------------------------------------
 const DB_HELP = `railcode db — data connectors
 
@@ -856,9 +3577,9 @@ async function commandDbQuery(args) {
     if (args.rest.length > 2) {
         throw new CliError('railcode db query takes a single SQL string — quote it: railcode db query "select 1".', 2);
     }
-    const source = pickSqlSource(args.rest[1], args.options.file);
+    const source = pickSqlSource(args.rest[1], singleOption(args, "file"));
     const params = parseSqlParams(optionString(args, "params"));
-    const engineOption = parseEngine(args.options.engine);
+    const engineOption = parseEngine(singleOption(args, "engine"));
     const connection = optionString(args, "connection") ?? "default";
     const query = source.kind === "file" ? readSqlFile(source.path) : source.sql;
     const config = requireLogin(args);
@@ -905,8 +3626,20 @@ function optionString(args, key) {
     const value = args.options[key];
     if (value === true)
         throw new CliError(`--${camelToKebab(key)} requires a value.`, 2);
+    if (Array.isArray(value)) {
+        throw new CliError(`--${camelToKebab(key)} can only be given once.`, 2);
+    }
     return typeof value === "string" ? value : undefined;
 }
+// A single-valued option that may legitimately be a bare flag (the db/connector
+// parsers handle `true` themselves) — only a REPEATED option is rejected here.
+function singleOption(args, key) {
+    const value = args.options[key];
+    if (Array.isArray(value)) {
+        throw new CliError(`--${camelToKebab(key)} can only be given once.`, 2);
+    }
+    return value;
+}
 function assertKnownDbOptions(args, allowed) {
     for (const key of Object.keys(args.options)) {
         if (!allowed.includes(key)) {
@@ -918,6 +3651,254 @@ function camelToKebab(value) {
     return value.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
 }
 // ---------------------------------------------------------------------------
+// query — saved queries (`railcode query list|run|create|delete`)
+//
+// list/run hit the org-scoped `/data/queries` plane with the personal token
+// (subject to `saved_query` grants; `_ctx_*` binds resolve to YOU). create/delete
+// hit the admin management API (`/saved-queries`, connection:manage required).
+// ---------------------------------------------------------------------------
+const QUERY_HELP = `railcode query — saved queries
+
+Usage:
+  railcode query list                          List this org's saved queries
+  railcode query run <name> [--params <json>]  Invoke a saved query by name
+  railcode query create --name <n> --connection <c> (--sql <sql> | --sql-file <f>)
+                        [--params <json>] [--description <d>]
+                                               Author a saved query (admin)
+  railcode query update <name> [--sql <sql> | --sql-file <f>] [--params <json>]
+                        [--clear-params] [--connection <c>] [--description <d>]
+                                               Edit a saved query in place (admin;
+                                               omitted fields keep their value)
+  railcode query delete <name>                 Delete a saved query (admin)
+
+Aliases: query = queries; list = ls; run = invoke.
+
+Run options:
+  --params '<json-object>'               Caller params, exactly as the API takes
+                                         them: '{"region":"emea","limit":5}'.
+                                         Params declared with a default may be
+                                         omitted (the server binds the default).
+  --json                                 Print the raw { columns, rows, ... } envelope
+
+Create / update options:
+  --name <name>                          Invoke handle ([a-z0-9_], unique per org)
+  --connection <name>                    Data connection the query runs against
+  --sql <sql>                            The SQL template inline (:param style);
+                                         quote it, or use --sql="..." if it starts
+                                         with a -- comment
+  --sql-file <path>                      File holding the SQL template
+  --params '<json-array>'                Declared params in the API shape:
+                                         '[{"name":"region","type":"string","default":"emea"},
+                                           {"name":"limit","type":"int"}]'
+                                         Types: string, int, float, bool. A "default"
+                                         makes the param optional at invoke time.
+                                         On update the array REPLACES the params
+  --clear-params                         (update only) declare no params
+  --description <text>                   Shown to members next to the name
+
+Editing the SQL or params bumps the query's version; grants naming the query are
+untouched (unlike delete + recreate, which removes them).
+
+Templates may reference :_ctx_user_id, :_ctx_user_email and :_ctx_org — the server
+injects those from whoever invokes (they can never be passed as params), so a
+query like "where rep_email = :_ctx_user_email" is row-scoped per caller.
+`;
+async function commandQuery(args) {
+    try {
+        const sub = args.rest[0] ?? "";
+        switch (sub) {
+            case "list":
+            case "ls":
+                await commandQueryList(args);
+                return;
+            case "run":
+            case "invoke":
+                await commandQueryRun(args);
+                return;
+            case "create":
+                await commandQueryCreate(args);
+                return;
+            case "update":
+                await commandQueryUpdate(args);
+                return;
+            case "delete":
+                await commandQueryDelete(args);
+                return;
+            case "":
+            case "help":
+                console.log(QUERY_HELP);
+                return;
+            default:
+                throw new CliError(`Unknown query command: ${sub}\n\n${QUERY_HELP}`, 2);
+        }
+    }
+    catch (error) {
+        if (error instanceof QueryCmdError)
+            throw new CliError(error.message, 2);
+        throw error;
+    }
+}
+async function commandQueryList(args) {
+    assertKnownQueryOptions(args, ["json", "apiUrl"]);
+    if (args.rest.length > 1) {
+        throw new CliError(`railcode query list takes no arguments (got "${args.rest[1]}").`, 2);
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/queries`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const queries = (await readJsonOrThrow(resp, "List saved queries"));
+    if (args.options.json) {
+        console.log(JSON.stringify(queries, null, 2));
+        return;
+    }
+    if (queries.length === 0) {
+        console.log("No saved queries in this organization.");
+        return;
+    }
+    console.log(formatTable(["name", "params", "version", "description"], queries.map((query) => [
+        query.name,
+        paramSignature(query.params),
+        `v${query.version}`,
+        query.description || "-",
+    ])));
+}
+async function commandQueryRun(args) {
+    assertKnownQueryOptions(args, ["params", "json", "apiUrl"]);
+    const name = args.rest[1];
+    if (!name || args.rest.length > 2) {
+        throw new CliError(`Usage: railcode query run <name> [--params '{"k":"v"}']`, 2);
+    }
+    const params = parseRunParams(optionString(args, "params"));
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/data/queries/${encodeURIComponent(name)}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ params }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const result = (await readJsonOrThrow(resp, `Run saved query "${name}"`));
+    if (args.options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(formatTable(result.columns, result.rows));
+    console.log("");
+    console.log(`(${result.rowcount} row${result.rowcount === 1 ? "" : "s"})`);
+    if (result.truncated) {
+        console.log("Note: results were truncated by the server.");
+    }
+}
+async function commandQueryCreate(args) {
+    assertKnownQueryOptions(args, [
+        "name",
+        "connection",
+        "sql",
+        "sqlFile",
+        "params",
+        "description",
+        "apiUrl",
+    ]);
+    const name = optionString(args, "name");
+    const connection = optionString(args, "connection");
+    if (!name || !connection) {
+        throw new CliError("railcode query create requires --name and --connection.\n\n" + QUERY_HELP, 2);
+    }
+    // required=true: pickAuthoringSql throws rather than return null here.
+    const source = pickAuthoringSql(optionString(args, "sql"), optionString(args, "sqlFile"), true);
+    const params = parseParamDecls(optionString(args, "params"));
+    const sql = source.kind === "file" ? readSqlFile(source.path) : source.sql;
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/saved-queries`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            name,
+            connection,
+            sql,
+            params,
+            description: optionString(args, "description") ?? "",
+        }),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const created = (await readJsonOrThrow(resp, `Create saved query "${name}"`));
+    console.log(`Saved query "${created.name}" created (v${created.version}).`);
+    console.log(`Invoke it: railcode query run ${created.name}`);
+}
+async function commandQueryUpdate(args) {
+    assertKnownQueryOptions(args, [
+        "sql",
+        "sqlFile",
+        "params",
+        "clearParams",
+        "connection",
+        "description",
+        "apiUrl",
+    ]);
+    const name = args.rest[1];
+    if (!name || args.rest.length > 2) {
+        throw new CliError("Usage: railcode query update <name> [--sql ... | --sql-file ...]", 2);
+    }
+    const source = pickAuthoringSql(optionString(args, "sql"), optionString(args, "sqlFile"), false);
+    const sql = source ? (source.kind === "file" ? readSqlFile(source.path) : source.sql) : undefined;
+    const paramsJson = optionString(args, "params");
+    const clearParams = args.options.clearParams === true;
+    if (clearParams && paramsJson !== undefined) {
+        throw new CliError("--clear-params cannot be combined with --params.", 2);
+    }
+    const params = clearParams ? [] : paramsJson !== undefined ? parseParamDecls(paramsJson) : undefined;
+    const connection = optionString(args, "connection");
+    const description = optionString(args, "description");
+    // PATCH semantics: only the fields present in the body change; params replace
+    // the whole declared list (the backend re-validates them against the SQL).
+    const body = {};
+    if (connection !== undefined)
+        body.connection = connection;
+    if (sql !== undefined)
+        body.sql = sql;
+    if (params !== undefined)
+        body.params = params;
+    if (description !== undefined)
+        body.description = description;
+    if (Object.keys(body).length === 0) {
+        throw new CliError("Nothing to update. Pass --sql/--sql-file, --params/--clear-params, --connection or --description.", 2);
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/saved-queries/${encodeURIComponent(name)}`, {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    const updated = (await readJsonOrThrow(resp, `Update saved query "${name}"`));
+    console.log(`Saved query "${updated.name}" updated (v${updated.version}).`);
+}
+async function commandQueryDelete(args) {
+    assertKnownQueryOptions(args, ["apiUrl"]);
+    const name = args.rest[1];
+    if (!name || args.rest.length > 2) {
+        throw new CliError("Usage: railcode query delete <name>", 2);
+    }
+    const config = requireLogin(args);
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/saved-queries/${encodeURIComponent(name)}`, { method: "DELETE" });
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    if (!resp.ok) {
+        throw new CliError(`Delete saved query "${name}" failed (${resp.status}): ${await errorDetail(resp)}`, 1);
+    }
+    console.log(`Saved query "${name}" deleted (its grants were removed too).`);
+}
+function assertKnownQueryOptions(args, allowed) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode query\`.\n\n${QUERY_HELP}`, 2);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // connector — list service connectors + proxy one call
 // (`railcode connector list|fetch`)
 //
@@ -1007,9 +3988,9 @@ async function commandConnectorFetch(args) {
     if (args.rest.length > 2) {
         throw new CliError('railcode connector fetch takes a single path — quote it: railcode connector fetch "/v1/charges".', 2);
     }
-    const connector = parseConnectorOption(args.options.connector);
-    const method = parseMethodOption(args.options.method);
-    const bodySource = pickConnectorBody(args.options.body, args.options.file);
+    const connector = parseConnectorOption(singleOption(args, "connector"));
+    const method = parseMethodOption(singleOption(args, "method"));
+    const bodySource = pickConnectorBody(singleOption(args, "body"), singleOption(args, "file"));
     const body = bodySource.kind === "file"
         ? readConnectorBodyFile(bodySource.path)
         : bodySource.kind === "inline"
@@ -1122,6 +4103,71 @@ async function errorDetail(response) {
     return text || response.statusText;
 }
 // ---------------------------------------------------------------------------
+// llm — list the LLM providers/models apps can call (`railcode llm`)
+// ---------------------------------------------------------------------------
+const LLM_HELP = `railcode llm — the org's LLM gateway, as apps see it
+
+Usage:
+  railcode llm providers                 List configured providers with their models
+  railcode llm models                    Flat list of every callable model
+
+Every configured provider is live; calls route by (provider, model). Pass either
+to \`llm.generate()\` / \`llm.stream()\` in app code — or neither to use the org
+default marked in the listing. Keys and provider internals are never shown.
+
+Options:
+  --json                                 Print the raw provider array
+`;
+async function commandLlm(args) {
+    const sub = args.rest[0] ?? "";
+    switch (sub) {
+        case "providers":
+        case "provider":
+            await commandLlmProviders(args, "providers");
+            return;
+        case "models":
+        case "model":
+            await commandLlmProviders(args, "models");
+            return;
+        case "":
+        case "help":
+            console.log(LLM_HELP);
+            return;
+        default:
+            throw new CliError(`Unknown llm command: ${sub}\n\n${LLM_HELP}`, 2);
+    }
+}
+async function commandLlmProviders(args, view) {
+    assertKnownLlmOptions(args, ["json", "apiUrl"]);
+    if (args.rest.length > 1) {
+        throw new CliError(`railcode llm ${view} takes no arguments (got "${args.rest[1]}").`, 2);
+    }
+    const config = requireLogin(args);
+    const providers = await fetchLlmProviders(config);
+    if (args.options.json) {
+        console.log(JSON.stringify(providers, null, 2));
+        return;
+    }
+    if (providers.length === 0) {
+        console.log("No LLM providers configured for this organization.");
+        return;
+    }
+    console.log(view === "providers" ? llmProviderTable(providers) : llmModelTable(providers));
+}
+async function fetchLlmProviders(config) {
+    const resp = await authedFetch(config, `/api/organizations/${config.orgUuid}/llm/providers`);
+    if (resp.status === 401)
+        await reLoginOrThrow();
+    return (await readJsonOrThrow(resp, "List LLM providers"));
+}
+function assertKnownLlmOptions(args, allowed) {
+    for (const key of Object.keys(args.options)) {
+        if (!allowed.includes(key)) {
+            throw new CliError(`Unknown option --${camelToKebab(key)} for \`railcode llm\`.\n\n${LLM_HELP}`, 2);
+        }
+    }
+}
+// ---------------------------------------------------------------------------
 // Config persistence
 // ---------------------------------------------------------------------------
 function loadConfig() {
@@ -1670,6 +4716,16 @@ function resolveDevSdkPath() {
     ];
     return candidates.find((p) => existsSync(p)) ?? null;
 }
+// Logo assets bundled into the React template's src/assets/. Packaged builds
+// copy cli/assets/react-template -> cli/static/react-template-assets (see
+// package.json build:sdk); running in-repo falls back to the source dir.
+function resolveReactTemplateAssetsDir() {
+    const candidates = [
+        join(CLI_PACKAGE_ROOT, "static", "react-template-assets"), // packaged CLI
+        join(CLI_PACKAGE_ROOT, "assets", "react-template"), // in-repo source
+    ];
+    return candidates.find((p) => existsSync(p)) ?? null;
+}
 // The dev analog of resolveDeployPlan: custom command | dev script (Vite) | serve
 // static files straight from the root when there's no package.json.
 function resolveDevPlan(cwd, manifest) {
@@ -1824,9 +4880,12 @@ async function handleLocalApi(ctx, req, res, url) {
     }
     // Proxied surfaces → forward to the real instance with the saved token.
     if (path === "/connections" ||
+        path === "/queries" ||
+        path.startsWith("/queries/") ||
         path === "/sql" ||
         path === "/llm/generate" ||
         path === "/llm/stream" ||
+        path === "/llm/providers" ||
         path === "/service-connectors" ||
         path === "/service-connectors/request") {
         await forwardCompute(ctx, req, res, path, url);
@@ -2018,12 +5077,10 @@ function devCreds(config) {
         return null;
     return { apiUrl: normalizeApiOrigin(apiUrl), token, orgUuid };
 }
-// Resolve the server-side app for proxying — lazily and memoized, so we don't
-// pollute org state on a typo'd `railcode dev`. The app is **created only on the
-// first actual call** (llm/sql/service-connectors request, allowCreate); a
-// load-time list (`GET /connections`, `/service-connectors`) resolves an existing
-// app but never creates one.
-function resolveDevAppUuid(ctx, creds, allowCreate) {
+// Resolve the server-side app for proxying — lazily and memoized. Local dev must
+// not create product apps: an app becomes real on first successful deploy, not on
+// a dev-time SQL/LLM/connector call.
+function resolveDevAppUuid(ctx, creds) {
     const base = `${creds.apiUrl}/api/organizations/${creds.orgUuid}/apps`;
     const authed = { Authorization: `Bearer ${creds.token}` };
     if (!ctx.appUuidPromise) {
@@ -2033,45 +5090,38 @@ function resolveDevAppUuid(ctx, creds, allowCreate) {
                 if (!resp.ok)
                     return null;
                 const apps = (await resp.json());
-                return apps.find((a) => a.app_slug === ctx.app)?.uuid ?? null;
+                return apps.find((a) => a.app_slug === ctx.app && a.status === "active")?.uuid ?? null;
             }
             catch {
                 return null;
             }
         })();
     }
-    return ctx.appUuidPromise.then((existing) => {
-        if (existing || !allowCreate)
-            return existing;
-        if (!ctx.appCreatePromise) {
-            ctx.appCreatePromise = (async () => {
-                try {
-                    const created = await fetch(base, {
-                        method: "POST",
-                        headers: { ...authed, "Content-Type": "application/json" },
-                        body: JSON.stringify({ name: ctx.app, app_slug: ctx.app }),
-                    });
-                    if (!created.ok)
-                        return null;
-                    const app = (await created.json());
-                    console.log(`  created app "${ctx.app}" on ${creds.apiUrl} (first llm/sql/connector call)`);
-                    ctx.appUuidPromise = Promise.resolve(app.uuid); // later resolves skip the list
-                    return app.uuid;
-                }
-                catch {
-                    return null;
-                }
-            })();
-        }
-        return ctx.appCreatePromise;
-    });
+    return ctx.appUuidPromise;
+}
+export function devUpstreamAuthFallback(status, degradeOk) {
+    if (status !== 401)
+        return null;
+    if (degradeOk)
+        return { status: 200, body: [] };
+    return {
+        status: 503,
+        body: {
+            error: "auth",
+            message: "Saved token was rejected. Run `railcode login` again.",
+        },
+    };
 }
 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()/serviceConnectors() at
-    // load don't break; the actual call surfaces (/sql, /llm, /service-connectors/request)
-    // return 503 instead.
-    const degradeOk = path === "/connections" || path === "/service-connectors";
+    // Load-time list calls degrade to [] so dataConnectors()/savedQueries()/
+    // serviceConnectors() at load don't break when the saved token is bad; actual
+    // calls (/queries/{name}, /sql, /llm, /service-connectors/request) return 503.
+    // A 403 is a real authorization denial and must be forwarded with its body.
+    const degradeOk = path === "/connections" ||
+        path === "/queries" ||
+        path === "/service-connectors" ||
+        path === "/llm/providers";
     const creds = devCreds(ctx.config);
     if (!creds) {
         if (degradeOk)
@@ -2081,15 +5131,13 @@ async function forwardCompute(ctx, req, res, path, url) {
             message: "Run `railcode login` to use LLM and connectors in dev.",
         });
     }
-    // Only the actual call surfaces (llm/sql/service-connectors/request) may create
-    // the app server-side; a load-time list (GET /connections, /service-connectors) won't.
-    const appUuid = await resolveDevAppUuid(ctx, creds, !degradeOk);
+    const appUuid = await resolveDevAppUuid(ctx, creds);
     if (!appUuid) {
         if (degradeOk)
             return sendJson(res, 200, []);
         return sendJson(res, 503, {
             error: "app_unavailable",
-            message: "Could not resolve this app on the server.",
+            message: "Deploy this app once before using LLM, SQL, saved queries, or connectors in dev.",
         });
     }
     const target = `${creds.apiUrl}/api/organizations/${creds.orgUuid}/apps/${appUuid}${path}${url.search}`;
@@ -2120,13 +5168,9 @@ async function forwardCompute(ctx, req, res, path, url) {
             return sendJson(res, 200, []);
         return sendJson(res, 503, { error: "unreachable", message: `Could not reach ${creds.apiUrl}.` });
     }
-    if (upstream.status === 401 || upstream.status === 403) {
-        if (degradeOk)
-            return sendJson(res, 200, []);
-        return sendJson(res, 503, {
-            error: "auth",
-            message: "Saved token was rejected. Run `railcode login` again.",
-        });
+    const authFallback = devUpstreamAuthFallback(upstream.status, degradeOk);
+    if (authFallback) {
+        return sendJson(res, authFallback.status, authFallback.body);
     }
     if (path === "/llm/stream" && upstream.body) {
         res.writeHead(upstream.status, {