create-feltkit 0.3.1 → 0.3.3

package/template/feltkit/projects.ts

@@ -45,6 +45,25 @@ export const rename = app.mutation({
   },
 });
 
+/**
+ * Removes completed tasks (and their notes) from one project, or from every project. Runs as
+ * the background job "projects.clear-completed" (services.jobs.handlers in app.ts), queued
+ * from Studio → Services → Jobs or on a schedule, as the person who queued it.
+ */
+export const clearCompleted = app.mutation({
+  access: "projects.write",
+  args: { projectId: s.optional(s.string()) },
+  returns: s.object({ removed: s.integer() }),
+  handler: async (ctx, { projectId }) => {
+    const done = await ctx.db.find(tasks, projectId ? { projectId, done: true } : { done: true });
+    for (const task of done) {
+      for (const file of await ctx.services.files.list({ metadata: { taskId: task.id } })) await ctx.services.files.remove(file.id);
+      await ctx.db.delete(tasks, task.id);
+    }
+    return { removed: done.length };
+  },
+});
+
 /** Deletes a project and all of its tasks in one atomic commit. */
 export const remove = app.mutation({
   access: "projects.write",

package/template/feltkit/tasks.ts

@@ -33,7 +33,7 @@ export const create = app.mutation({
   capability: { name: "tasks.create", description: "Add a task to a project." },
   handler: async (ctx, { projectId, title, details }) => {
     if (!(await ctx.db.get(projects, projectId))) fail("NOT_FOUND", "That project does not exist.");
-    return ctx.db.insert(tasks, {
+    const id = await ctx.db.insert(tasks, {
       projectId,
       title: title.trim(),
       ...(details?.trim() ? { details: details.trim() } : {}),
@@ -41,6 +41,9 @@ export const create = app.mutation({
       createdAt: Date.now(),
       createdBy: ctx.auth.requirePrincipal().id,
     });
+    // Delivered, signed, to every webhook endpoint registered for "task.created" (Studio → Services → Webhooks).
+    await ctx.services.webhooks?.emit("task.created", { id, projectId, title: title.trim() });
+    return id;
   },
 });
 
@@ -63,6 +66,13 @@ export const setDone = app.mutation({
   handler: async (ctx, { id, done }) => {
     const who = ctx.auth.requirePrincipal().id;
     const task = await ctx.db.patch(tasks, id, done ? { done: true, completedAt: Date.now(), completedBy: who } : { done: false, completedAt: undefined, completedBy: undefined });
+    if (done) {
+      await ctx.services.webhooks?.emit("task.completed", { id: task.id, projectId: task.projectId, completedBy: who });
+      // Tell whoever created the task, when someone else completes it.
+      if (task.createdBy !== who) {
+        await ctx.services.notifications.send({ recipient: task.createdBy, type: "task.completed", title: `${who} completed "${task.title}"`, data: { taskId: task.id }, idempotencyKey: `task.completed:${task.id}:${task.completedAt}` });
+      }
+    }
     return { id: task.id, done: task.done };
   },
 });

package/template/index.html

@@ -4,8 +4,11 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="color-scheme" content="light dark" />
-    <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
+    <link rel="icon" href="/favicon.png" type="image/png" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
     <title>Tasks · FeltKit</title>
+    <!-- The saved light/dark choice, applied before first paint (src/theme.tsx). -->
+    <script vite-ignore src="/theme.js"></script>
   </head>
   <body>
     <div id="root"></div>

package/template/package.json

@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@feltdb/feltkit": "0.3.1",
+    "@feltdb/feltkit": "0.3.3",
     "react": "19.2.0",
     "react-dom": "19.2.0"
   },
@@ -24,5 +24,10 @@
     "@vitejs/plugin-react": "5.1.0",
     "typescript": "5.9.3",
     "vite": "7.3.7"
+  },
+  "overrides": {
+    "@appport/services": {
+      "@feltdb/core": "0.16.1"
+    }
   }
 }

package/template/public/theme.js

@@ -0,0 +1,7 @@
+// Applies the saved theme before the app renders, so there is no light flash in dark mode.
+// Same key and values as src/theme.tsx. A file, not an inline script, so it also works under
+// a Content-Security-Policy that allows only same-origin scripts.
+try {
+  var theme = localStorage.getItem("app:theme");
+  if (theme === "light" || theme === "dark") document.documentElement.dataset.theme = theme;
+} catch (e) {}

package/template/src/App.tsx

@@ -1,6 +1,7 @@
 import { useEffect, useMemo, useRef, useState, type FormEvent } from "react";
-import { useConnectionState, useMutation, useQueryState, useSession, type FeltKitClientError } from "@feltdb/feltkit/react";
+import { useConnectionState, useFeltKit, useMutation, useQueryState, useSession, type FeltKitClientError } from "@feltdb/feltkit/react";
 import { api } from "../feltkit/_generated/api";
+import { ThemeToggle } from "./theme";
 
 type Notice = { tone: "error" | "info"; text: string } | null;
 
@@ -47,11 +48,7 @@ export function App() {
     <div className="shell">
       <header className="topbar">
         <div className="brand">
-          <span className="mark" aria-hidden>
-            <svg viewBox="0 0 32 32" width="22" height="22">
-              <path d="M11 7c-4 5-4 13 0 18M21 7c4 5 4 13 0 18" stroke="currentColor" strokeWidth="3" fill="none" strokeLinecap="round" />
-            </svg>
-          </span>
+          <img className="mark" src="/feltkit-mark.png" width="30" height="30" alt="" />
           <span className="brand-name">Tasks</span>
           {session && <span className={`env ${session.environment.production ? "env-prod" : ""}`}>{session.environment.name}</span>}
         </div>
@@ -76,6 +73,7 @@ export function App() {
               </select>
             </label>
           )}
+          <ThemeToggle />
           {session?.dashboard && (
             <a className="dashboard-link" href={session.dashboard} target="_blank" rel="noreferrer">
               Dashboard ↗
@@ -125,13 +123,39 @@ function SignedOut({ devUsers, onSignIn }: { devUsers: Array<{ id: string; name:
             </div>
           </>
         ) : (
-          <p className="muted">This environment has no development sign-in. Configure auth.authenticate in feltkit/app.ts.</p>
+          <TokenSignIn />
         )}
       </div>
     </div>
   );
 }
 
+/**
+ * Production has no development sign-in. Until auth.authenticate in feltkit/app.ts verifies your
+ * users with your identity provider, sign in with a session token created on the server.
+ */
+function TokenSignIn() {
+  const client = useFeltKit();
+  const [token, setToken] = useState("");
+  const submit = (e: FormEvent) => {
+    e.preventDefault();
+    if (token.trim()) client.setToken(token.trim());
+  };
+  return (
+    <form className="stack" onSubmit={submit}>
+      <p className="muted">
+        Sign in with a session token. Create one on the server (with the app stopped):
+      </p>
+      <code className="block">npx feltkit session create --env production --type user --id you --role member</code>
+      <input type="password" value={token} onChange={(e) => setToken(e.target.value)} placeholder="Session token (fks_…)" aria-label="Session token" autoComplete="off" />
+      <button type="submit" disabled={!token.trim()}>
+        Sign in
+      </button>
+      <p className="muted small-text">To sign people in with your own login, add auth.authenticate in feltkit/app.ts.</p>
+    </form>
+  );
+}
+
 function Workspace({ canWrite, canComplete, role, onError }: { canWrite: boolean; canComplete: boolean; role: string; onError: (e: unknown) => void }) {
   const projects = useQueryState(api.projects.list);
   const [selected, setSelected] = useState<string | null>(null);

package/template/src/styles.css

@@ -1,16 +1,22 @@
 :root {
-  --bg: #f7f7f5;
-  --surface: #ffffff;
-  --ink: #1b1d1c;
-  --muted: #6b706d;
-  --line: #e4e5e1;
-  --accent: #166534;
-  --accent-ink: #ffffff;
-  --accent-soft: #e8f3ec;
-  --danger: #b42318;
-  --warn: #92400e;
+  /* Light or dark: the system's setting unless the top bar's theme switch chose one
+     (data-theme on <html>). Each color is light-dark(light, dark). */
+  color-scheme: light dark;
+  --bg: light-dark(#f7f7f5, #111312);
+  --surface: light-dark(#ffffff, #181b1a);
+  --ink: light-dark(#1b1d1c, #eceeed);
+  --muted: light-dark(#6b706d, #9aa19d);
+  --line: light-dark(#e4e5e1, #2a2f2c);
+  --accent: light-dark(#166534, #4ade80);
+  --accent-ink: light-dark(#ffffff, #052e16);
+  --accent-soft: light-dark(#e8f3ec, #15301f);
+  --warn-soft: light-dark(#fef3c7, #2b2210);
+  --danger-soft: light-dark(#fef3f2, #2a1513);
+  --danger-line: light-dark(#fecdca, #55201b);
+  --danger: light-dark(#b42318, #f97066);
+  --warn: light-dark(#92400e, #fbbf24);
   --radius: 10px;
-  --shadow: 0 1px 2px rgba(16, 24, 20, 0.06), 0 2px 8px rgba(16, 24, 20, 0.04);
+  --shadow: 0 1px 2px light-dark(rgba(16, 24, 20, 0.06), transparent), 0 2px 8px light-dark(rgba(16, 24, 20, 0.04), transparent);
   font-family: Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
   color: var(--ink);
   background: var(--bg);
@@ -18,21 +24,8 @@
   line-height: 1.5;
   -webkit-font-smoothing: antialiased;
 }
-@media (prefers-color-scheme: dark) {
-  :root {
-    --bg: #111312;
-    --surface: #181b1a;
-    --ink: #eceeed;
-    --muted: #9aa19d;
-    --line: #2a2f2c;
-    --accent: #4ade80;
-    --accent-ink: #052e16;
-    --accent-soft: #15301f;
-    --danger: #f97066;
-    --warn: #fbbf24;
-    --shadow: none;
-  }
-}
+:root[data-theme="light"] { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
 * { box-sizing: border-box; }
 body { margin: 0; }
 button, input, select, textarea { font: inherit; color: inherit; }
@@ -42,9 +35,9 @@ button, input, select, textarea { font: inherit; color: inherit; }
 
 .topbar { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 12px 20px; border-bottom: 1px solid var(--line); background: var(--surface); position: sticky; top: 0; z-index: 2; }
 .brand { display: flex; align-items: center; gap: 10px; font-weight: 600; }
-.mark { display: inline-grid; place-items: center; width: 30px; height: 30px; border-radius: 8px; background: var(--accent); color: var(--accent-ink); }
+.mark { display: block; width: 30px; height: 30px; }
 .env { font-size: 12px; font-weight: 500; padding: 2px 8px; border-radius: 999px; background: var(--accent-soft); color: var(--accent); }
-.env-prod { background: #fef3c7; color: var(--warn); }
+.env-prod { background: var(--warn-soft); color: var(--warn); }
 .topbar-right { display: flex; align-items: center; gap: 14px; }
 .live { display: inline-flex; align-items: center; gap: 6px; font-size: 13px; color: var(--muted); }
 .live .dot { width: 8px; height: 8px; border-radius: 50%; background: var(--line); }
@@ -52,11 +45,15 @@ button, input, select, textarea { font: inherit; color: inherit; }
 .identity select { padding: 6px 10px; border: 1px solid var(--line); border-radius: 8px; background: var(--surface); }
 .dashboard-link { font-size: 13px; color: var(--muted); text-decoration: none; }
 .dashboard-link:hover { color: var(--ink); }
+.theme-toggle { display: inline-flex; padding: 2px; gap: 2px; border: 1px solid var(--line); border-radius: 8px; }
+.theme-toggle button { display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 24px; padding: 0; border: 0; border-radius: 6px; background: transparent; color: var(--muted); cursor: pointer; }
+.theme-toggle button:hover { color: var(--ink); }
+.theme-toggle button.on { background: var(--accent-soft); color: var(--accent); }
+.theme-toggle button:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
 
 .notice { margin: 12px 20px 0; padding: 10px 14px; border-radius: var(--radius); display: flex; justify-content: space-between; align-items: center; gap: 12px; }
-.notice.error { background: #fef3f2; color: var(--danger); border: 1px solid #fecdca; }
+.notice.error { background: var(--danger-soft); color: var(--danger); border: 1px solid var(--danger-line); }
 .notice.info { background: var(--accent-soft); color: var(--accent); }
-@media (prefers-color-scheme: dark) { .notice.error { background: #2a1513; border-color: #55201b; } }
 
 .workspace { flex: 1; display: grid; grid-template-columns: 260px 1fr; min-height: 0; }
 .sidebar { border-right: 1px solid var(--line); padding: 20px 12px; display: flex; flex-direction: column; gap: 6px; }
@@ -108,6 +105,7 @@ button.icon { color: var(--muted); font-size: 14px; opacity: 0; }
 .danger-link { background: none; border: 0; color: var(--danger); cursor: pointer; font-size: 13px; }
 .wide { width: 100%; text-align: left; }
 .stack { display: flex; flex-direction: column; gap: 8px; }
+code.block { display: block; padding: 8px 10px; border-radius: 6px; background: rgba(127, 127, 127, 0.12); font-size: 12px; word-break: break-all; }
 
 .empty { margin-top: 12vh; text-align: center; display: flex; flex-direction: column; align-items: center; gap: 4px; }
 .empty.small { margin-top: 36px; }
@@ -124,6 +122,8 @@ button.icon { color: var(--muted); font-size: 14px; opacity: 0; }
   .workspace { grid-template-columns: 1fr; }
   .sidebar { border-right: 0; border-bottom: 1px solid var(--line); }
   .main { padding: 20px 16px 48px; }
-  .topbar { flex-wrap: wrap; }
+  .topbar { flex-wrap: wrap; padding: 10px 16px; }
+  .topbar-right { flex-wrap: wrap; gap: 10px; min-width: 0; }
+  .identity, .identity select { max-width: 100%; min-width: 0; }
   .task-detail { padding-left: 16px; }
 }

package/template/src/theme.tsx

@@ -0,0 +1,58 @@
+/**
+ * Light, dark, or the system's setting. The choice is kept in this browser (localStorage) and
+ * applied as data-theme on <html>; every color in styles.css follows it. public/theme.js
+ * applies it before first paint.
+ */
+import { useEffect, useState, type ReactNode } from "react";
+
+type Theme = "system" | "light" | "dark";
+const KEY = "app:theme";
+
+function stored(): Theme {
+  try {
+    const value = localStorage.getItem(KEY);
+    return value === "light" || value === "dark" ? value : "system";
+  } catch {
+    return "system";
+  }
+}
+
+function apply(theme: Theme) {
+  if (theme === "system") delete document.documentElement.dataset.theme;
+  else document.documentElement.dataset.theme = theme;
+  try {
+    if (theme === "system") localStorage.removeItem(KEY);
+    else localStorage.setItem(KEY, theme);
+  } catch {
+    // Storage is blocked (a private window): the choice lasts until the page reloads.
+  }
+}
+
+const OPTIONS: Array<{ theme: Theme; label: string; icon: ReactNode }> = [
+  { theme: "system", label: "System", icon: <><rect x="3" y="4" width="14" height="10" rx="1.5" /><path d="M7.5 17h5M10 14v3" /></> },
+  { theme: "light", label: "Light", icon: <><circle cx="10" cy="10" r="3.2" /><path d="M10 2.5v2M10 15.5v2M2.5 10h2M15.5 10h2M4.7 4.7l1.4 1.4M13.9 13.9l1.4 1.4M4.7 15.3l1.4-1.4M13.9 6.1l1.4-1.4" /></> },
+  { theme: "dark", label: "Dark", icon: <path d="M15.5 12.2A6 6 0 0 1 7.8 4.5a6 6 0 1 0 7.7 7.7Z" /> },
+];
+
+/** The light / dark / system switch in the top bar. */
+export function ThemeToggle() {
+  const [theme, setTheme] = useState<Theme>(stored);
+  useEffect(() => apply(theme), [theme]);
+  useEffect(() => {
+    const onStorage = (e: StorageEvent) => e.key === KEY && setTheme(stored());
+    window.addEventListener("storage", onStorage);
+    return () => window.removeEventListener("storage", onStorage);
+  }, []);
+  return (
+    <div className="theme-toggle" role="radiogroup" aria-label="Theme">
+      {OPTIONS.map((o) => (
+        <button key={o.theme} type="button" role="radio" aria-checked={theme === o.theme} className={theme === o.theme ? "on" : ""} onClick={() => setTheme(o.theme)} title={`${o.label} theme`}>
+          <svg viewBox="0 0 20 20" width="15" height="15" fill="none" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" aria-hidden>
+            {o.icon}
+          </svg>
+          <span className="sr-only">{o.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}

package/template/tests/tasks.test.ts

@@ -57,6 +57,26 @@ test("notes are stored by the Files service and readable by viewers", async () =
   }
 });
 
+test("completing someone else's task notifies them, in their own inbox only", async () => {
+  const t = await createTestApp();
+  const bob = { id: "bob", type: "user" as const, roles: ["member"] };
+  try {
+    const ada = t.as("ada");
+    const projectId = await ada.mutation(api.projects.create, { name: "Inbox" });
+    const taskId = await ada.mutation(api.tasks.create, { projectId, title: "Review the draft" });
+    await t.as(bob).mutation(api.tasks.setDone, { id: taskId, done: true });
+    const [notification, ...rest] = await ada.query(api.inbox.list, { unread: true });
+    assert.equal(rest.length, 0);
+    assert.equal(notification!.type, "task.completed");
+    assert.deepEqual(notification!.data, { taskId });
+    assert.deepEqual(await t.as(bob).query(api.inbox.list, {}), [], "bob sees only his own");
+    await ada.mutation(api.inbox.markRead, { id: notification!.id });
+    assert.deepEqual(await ada.query(api.inbox.list, { unread: true }), []);
+  } finally {
+    await t.close();
+  }
+});
+
 test("deleting a project removes its tasks in one atomic commit", async () => {
   const t = await createTestApp();
   try {
@@ -99,3 +119,25 @@ test("state survives a restart", async () => {
     await t.close();
   }
 });
+
+test("completing someone else's task notifies its creator; the clear-completed job runs as whoever queued it", async () => {
+  const t = await createTestApp();
+  try {
+    const ada = t.as("ada");
+    const projectId = await ada.mutation(api.projects.create, { name: "Release" });
+    const taskId = await ada.mutation(api.tasks.create, { projectId, title: "Tag the build" });
+    await t.as({ id: "triage-bot", type: "agent", roles: ["agent"] }).mutation(api.tasks.setDone, { id: taskId, done: true });
+    const sent = await t.runtime.instance.handle("test").collection<{ recipient: string; type: string }>("notifications").find({});
+    assert.deepEqual(sent.map((n) => [n.recipient, n.type]), [["ada", "task.completed"]]);
+
+    // Studio → Services → Jobs queues this as the chosen identity; here, as Ada.
+    const principal = { id: "ada", type: "user" as const, roles: ["member", "admin"] };
+    await t.runtime.issueSession(principal, { kind: "test", via: "test" });
+    const services = t.runtime.services;
+    await services.asPrincipal(principal, (verified) => services.jobs!.enqueue({ type: "projects.clear-completed", payload: { projectId } }, verified));
+    assert.equal((await t.runtime.runServices()).jobs, 1);
+    assert.deepEqual(await ada.query(api.tasks.list, { projectId }), [], "the completed task was cleared");
+  } finally {
+    await t.close();
+  }
+});

package/template-managed/.dockerignore

@@ -0,0 +1,7 @@
+node_modules
+.feltkit
+dist
+tests
+.env
+.env.*
+.feltdb

package/template-managed/Dockerfile

@@ -0,0 +1,24 @@
+# The inventory service on Managed FeltDB. The image holds no state and no credentials:
+# FELTDB_URL, FELTDB_APPLICATION_ID and FELTDB_ENVIRONMENT come from the platform's configuration
+# and FELTDB_TOKEN from its secret store, at run time (README.md, "Deploy").
+FROM node:22-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json* ./
+RUN if [ -f package-lock.json ]; then npm ci --no-audit --no-fund; else npm install --no-audit --no-fund; fi
+COPY . .
+# The contract checked in must be the one this source declares: the managed application
+# only stores what it declares.
+RUN npx feltkit contract --check && npx feltkit build && npm prune --omit=dev --no-audit --no-fund
+
+FROM node:22-slim
+ENV NODE_ENV=production PORT=8080
+WORKDIR /app
+COPY --from=build --chown=node:node /app ./
+USER node
+EXPOSE 8080
+# Liveness: the runtime is ready only after it reached FeltDB with its key at startup.
+HEALTHCHECK --interval=15s --timeout=5s --start-period=30s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:'+process.env.PORT+'/_feltkit/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+# The launcher validates the configuration (refusing to start without it) and forwards
+# SIGTERM so FeltKit shuts down cleanly.
+CMD ["node", "scripts/managed-env.mjs", "start", "--host", "0.0.0.0"]

package/template-managed/README.md

@@ -0,0 +1,222 @@
+# Inventory on Managed FeltDB: a FeltKit example
+
+A small inventory service: items with stock levels, and a movement recorded with every stock
+change in the same FeltDB transaction. Its state lives in **Managed FeltDB**, the hosted FeltDB
+service. Nothing on the app's host holds state, so you can restart or redeploy the app and
+nothing is lost.
+
+```bash
+npm create feltkit@latest inventory -- --template managed
+```
+
+## How this differs from the default starter
+
+| | Default starter (`--template tasks`) | This starter (`--template managed`) |
+|---|---|---|
+| Where state lives | local FeltDB: `.feltkit/<env>/state`, or a FeltDB server you run (`FELTDB_URL` + `FELTDB_TOKEN`) | Managed FeltDB: one managed *application*, one *environment* (`production` by default) |
+| Development and tests | local FeltDB | local FeltDB, the same (`npm test`, `npm run dev`) |
+| What FeltDB stores | any collection | only what the promoted **contract** declares: `feltdb.contract.json`, generated by `feltkit contract` and checked in |
+| AppPort Services (files, intelligence, …) | yes | no: their collections can't be declared in a contract yet, so `feltkit contract` refuses an app that enables them |
+| Credentials | none for local state | a **runtime key** with four scopes (server-side only) and a **control key** for publishing contracts (never in the running app), both minted by the FeltDB CLI |
+| Deployment | `feltkit deploy` (a Docker artifact with a state volume) | `Dockerfile`, `docker-compose.yml`, `fly.toml`: stateless, configured by the environment |
+
+Managed FeltDB is an external service. Nothing here provisions or operates it: `feltdb
+init-managed` creates *your application* in it, using your FeltDB account.
+
+## What's here
+
+| Path | What it is |
+|---|---|
+| `feltkit/app.ts` | roles (`clerk`, `auditor`), collections `items` and `movements` |
+| `feltkit/items.ts` | `list`, `get`, `create` and `adjust` (AppPort capabilities `items.create` and `stock.adjust`), `history` |
+| `feltkit/system.ts` | `system:status`: an authenticated read through the configured backend; names the backend, never a key |
+| `feltdb.contract.json` | the FeltDB application contract: your collections, FeltKit's records, FeltDB's agent state |
+| `scripts/managed-env.mjs` | runs FeltKit with the runtime settings only; refuses missing or contradictory ones |
+| `Dockerfile`, `.dockerignore`, `docker-compose.yml` | the image, and a way to run it locally against Managed FeltDB |
+| `fly.toml`, `scripts/deploy-fly.mjs` | deployment to Fly.io |
+| `tests/` | `inventory` (persistence and refusals, local), `config` (configuration contract, deploy script), `managed.live` (against Managed FeltDB) |
+
+## Prerequisites
+
+- Node.js 20.11 or later, and npm.
+- A FeltDB account (`npm run managed:setup` creates one if the e-mail is new). The account
+  creates the application and its keys, so you need permission to manage keys for it. The
+  account service never issues a scope you don't hold.
+- To deploy: Docker, or [flyctl](https://fly.io/docs/flyctl/install/) signed in to Fly.io.
+
+## 1. Run it locally
+
+```bash
+npm install
+npm test          # local FeltDB per test: persistence, refusals, roles, configuration
+npm run dev       # http://localhost:3000, state in .feltkit/development/state
+```
+
+Development and tests always use local FeltDB, so you don't need an account for either.
+
+## 2. Set up Managed FeltDB: account, application, keys, contract
+
+```bash
+npm run managed:setup
+```
+
+This runs `feltkit contract` (writes `feltdb.contract.json`), then FeltDB's own CLI (shipped with
+`@feltdb/core`):
+
+```bash
+feltdb init-managed --contract feltdb.contract.json --runtime-scopes minimal
+```
+
+It signs you in (or signs you up), prompting for your e-mail and password. For CI, set
+`FELTDB_MANAGED_EMAIL` and `FELTDB_MANAGED_PASSWORD` instead. It then:
+
+1. creates or reuses the managed application named after `package.json`'s `name` (`--name` to choose);
+2. mints a **control key** (publish and promote contracts) and a **runtime key** with
+   `application:read`, `application:revision:read`, `state:read` and `state:write`, nothing more;
+3. writes `.env.local` (mode 600) and `.feltdb/managed.json`; both are in `.gitignore`;
+4. publishes and promotes the contract to `production`, and checks that the runtime key resolves it.
+
+| Variable (`.env.local`) | Secret? | Used by |
+|---|---|---|
+| `FELTDB_URL` | no | the app |
+| `FELTDB_APPLICATION_ID` | no | the app |
+| `FELTDB_ENVIRONMENT` | no | the app (it is also FeltKit's environment) |
+| `FELTDB_TOKEN` | **yes**: the runtime key | the app |
+| `FELTDB_MANAGED_CONTROL_API_KEY` | **yes**: the control key | `feltdb publish` only; never the app |
+
+`init-managed` also writes `FELTDB_NAMESPACE`, `FELTDB_MODE` and `VITE_FELTDB_*`, which hold no
+secrets. The app doesn't use them, and `scripts/managed-env.mjs` doesn't pass them on.
+
+## 3. Run it against Managed FeltDB from your machine
+
+```bash
+npm run managed:session -- --id ops --role clerk      # prints a session token once
+npm run managed:start                                 # http://localhost:3000, state in Managed FeltDB
+```
+
+Both go through `scripts/managed-env.mjs`, which reads `.env.local`. It passes FeltKit only the
+four runtime settings and refuses to start if one is missing. `managed:start` prints
+`State  remote https://…`.
+
+Production has no development sign-in, so callers use a session (`Authorization: Bearer <token>`)
+or your own `auth.authenticate` hook in `feltkit/app.ts`. Create sessions while the server is
+stopped (or from another machine). A running production server's admin API answers only verified
+operators.
+
+## 4. Verify reads and writes
+
+```bash
+TOKEN=fks_…   # from managed:session
+curl -s -X POST localhost:3000/api/mutation/items:create -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"args":{"sku":"BOLT-10","name":"M10 bolt","quantity":100}}'
+curl -s -X POST localhost:3000/api/mutation/items:adjust -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{"args":{"sku":"BOLT-10","delta":-30,"reason":"order 1"}}'
+curl -s -X POST localhost:3000/api/query/items:list     -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'
+curl -s -X POST localhost:3000/api/query/system:status  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' -d '{}'
+# → {"ok":true,"value":{"environment":"production","storage":{"kind":"remote","location":"https://api.feltdb.com","durable":true},"readable":true,…}}
+curl -s localhost:3000/_feltkit/health   # liveness: 200 once FeltKit reached FeltDB with its key at startup
+```
+
+## 5. Restart and check the state is still there
+
+Stop the app (Ctrl+C), run `npm run managed:start` again, and repeat `items:list`: the same items
+and quantities come back. Or run the automated check, which writes a `live-test-…` item, kills
+the app, starts a new process and reads it back:
+
+```bash
+FELTKIT_MANAGED_LIVE=1 npm run managed:test
+```
+
+## 6. Deploy
+
+The image holds no state and no keys. It is configured entirely by the environment at run
+time, so the same image runs anywhere.
+
+**Docker (any host).** Locally, with the settings from step 2:
+
+```bash
+docker compose --env-file .env.local up --build
+```
+
+The compose file passes the container only `FELTDB_URL`, `FELTDB_APPLICATION_ID`,
+`FELTDB_ENVIRONMENT` and `FELTDB_TOKEN`. On any other platform, set the first three as plain
+configuration and `FELTDB_TOKEN` from its secret store. Point health checks at
+`GET /_feltkit/health` on port 8080. The image checks that `feltdb.contract.json` matches the
+source at build time.
+
+**Fly.io.**
+
+```bash
+fly apps create <your-app-name>             # once
+npm run deploy:fly -- --app <your-app-name>
+```
+
+`scripts/deploy-fly.mjs` stages `FELTDB_TOKEN` as a Fly secret by piping it to
+`fly secrets import --stage` on stdin, so it never appears in a command line or output. It then
+runs `fly deploy` with the three non-secret settings. `fly.toml` holds the port, the health check
+and `FELTDB_ENVIRONMENT`.
+
+Then repeat steps 4 and 5 against the deployed URL. Create the session from your machine with
+`npm run managed:session`: sessions live in Managed FeltDB, so the deployed app accepts them.
+
+## Changing the data model
+
+1. Edit `feltkit/app.ts`.
+2. Run `npm run managed:publish`. This regenerates the contract and publishes it with
+   `feltdb publish --contract`. FeltDB classifies the change. A change it classifies as breaking,
+   migration-requiring or authorization-sensitive (adding a field is `MIGRATION_REQUIRED`) is
+   staged, but not activated until you rerun with `-- --approve-destructive-changes`. A refused or
+   unapproved publish leaves the active contract in place.
+3. Commit `feltdb.contract.json` with the code, then redeploy. The app that is already running needs
+   no restart. Its next request after the promotion is refused once (`CONFLICT`, `feltdbCode:
+   REVISION_NOT_ACTIVE`, nothing written, not resent), and every request after that runs under the
+   new contract. A compatible change, such as a new optional field, keeps the old code working. An
+   incompatible one refuses the old code's writes until the new code is deployed: FeltDB never
+   stores them under the old contract.
+
+## Keys: rotate, narrow, revoke
+
+```bash
+npx feltdb managed keys list                                        # ids, names, scopes; never secrets
+npx feltdb managed keys create --name inventory-runtime-2 --scopes minimal   # new FELTDB_TOKEN in .env.local
+npm run deploy:fly -- --app <your-app-name>                         # or update your platform's secret
+npx feltdb managed keys revoke inventory-runtime                    # the old key now gets AUTHENTICATION_REQUIRED
+```
+
+`--stdout` writes `FELTDB_TOKEN=…` to a pipe (for example into a secret manager) and is refused on a
+terminal. A key is bound to this application. Wildcard (`*`) keys are operator keys and are
+refused.
+
+## Troubleshooting
+
+| You see | Means | Do |
+|---|---|---|
+| `Managed FeltDB configuration is incomplete: FELTDB_… is not set` | the launcher found no value in the environment or `.env.local` | run `npm run managed:setup`, or set it on your platform |
+| startup fails with `AUTHENTICATION_REQUIRED` | the runtime key is wrong, revoked, or for another FeltDB | mint a new one (`feltdb managed keys create`) and update `FELTDB_TOKEN` |
+| `FORBIDDEN` | the key is for another application or lacks a scope | check `FELTDB_APPLICATION_ID`; mint with `--scopes minimal` |
+| `NOT_FOUND … application environment has no active contract` | nothing is promoted to `FELTDB_ENVIRONMENT` | `npm run managed:publish`, or fix `FELTDB_ENVIRONMENT` |
+| `UNKNOWN_COLLECTION` or `record contains an unknown field` | the contract is older than the code | `npm run managed:publish` (approve it) |
+| `CONFLICT` with `feltdbCode: REVISION_NOT_ACTIVE` | a contract was promoted since this process's last request; nothing was written, and FeltKit did not resend it | the request was built for the previous contract: if it still makes sense, send it again, and it runs under the new contract (once per promotion). Retrying it is the caller's decision, never automatic |
+| startup fails with `SERVICE_UNAVAILABLE` / names `FELTDB_URL` | FeltDB can't be reached | check `FELTDB_URL` and network egress. Managed FeltDB's `/health` and `/ready` are public |
+| `FELTDB_ENVIRONMENT is "…", but this is FeltKit's … environment` | the two disagree | FeltKit uses the FeltDB environment of its own name: set one of them |
+| `This application enables AppPort Services` from `feltkit contract` | services can't run on Managed FeltDB yet | remove `services`, or use local or self-hosted FeltDB |
+| `The production environment is already served by pid …` | a FeltKit server for this environment is running on this host | stop it first (or run the CLI on another machine) |
+
+## Clean up
+
+- Revoke keys you no longer use: `npx feltdb managed keys revoke <name-or-id>`.
+- `live-test-…` items written by `managed:test` stay in your application. They are ordinary
+  records, so remove them with your own mutation if you need to.
+- Delete the Fly app with `fly apps destroy <your-app-name>`. Local files: `.env.local`,
+  `.feltdb/`, `.feltkit/`.
+- The managed application itself is deleted from your FeltDB account. This repository has no
+  command that deletes it.
+
+## What's verified, and where
+
+- `npm test` (here): persistence, refusals, roles, the configuration contract, the Fly deploy
+  script with a stand-in `fly`.
+- `npm run test:managed` in the FeltKit repository: this example's full workflow, setup through
+  refusals, against a separately running, auth-on `feltdb-server` provisioned the way Managed
+  FeltDB is. It covers app and authority restarts, an idempotent retry across a restart, a
+  refused key, an unreachable authority, and no secret in any output.
+- `FELTKIT_MANAGED_LIVE=1 npm run managed:test`: the live service. It runs only with your
+  credentials.