create-feltkit 0.3.2 → 0.3.3

package/README.md

@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/rkendel1/feltkit/main/docs/assets/feltkit-logo-dark.png">
+    <img src="https://raw.githubusercontent.com/rkendel1/feltkit/main/docs/assets/feltkit-logo.png" alt="FeltKit" width="160">
+  </picture>
+</p>
+
 # create-feltkit
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-feltkit",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Create a FeltKit application: npm create feltkit@latest my-app (add -- --template managed for Managed FeltDB)",
   "license": "MIT",
   "type": "module",

package/scaffold.js

@@ -86,9 +86,9 @@ export function scaffold({ target, name, sdkSpec, template = "tasks" }) {
         readmePath,
         readme
           .replace(`# ${starterName}\n`, `# ${appName}\n`)
-          .replaceAll(`docker build -t ${starterName} .`, `docker build -t ${appName} .`)
-          .replaceAll(`-v ${starterName}-data:/data`, `-v ${appName}-data:/data`)
-          .replaceAll(`--env-file prod.env ${starterName}`, `--env-file prod.env ${appName}`),
+          .replaceAll(`docker build -t ${starterName} `, `docker build -t ${appName} `)
+          .replaceAll(`-v ${starterName}-data:/data ${starterName}`, `-v ${appName}-data:/data ${appName}`)
+          .replaceAll(`--name ${starterName} --namespace ${starterName} `, `--name ${appName} --namespace ${appName} `),
       );
     }
   }

package/template/README.md

@@ -39,7 +39,7 @@ start over.
 | `feltkit/app.ts` | The application: its name, roles and permissions, dev users, enabled services, collections |
 | `feltkit/projects.ts`, `feltkit/tasks.ts` | Functions: queries (read) and mutations (write). A function is `<module>:<export>`, e.g. `tasks:create` |
 | `feltkit/_generated/api.ts` | Typed references to every function. Regenerated by `feltkit dev` and `feltkit codegen`; don't edit it |
-| `src/` | The React frontend |
+| `src/` | The React frontend. Colors are tokens in `src/styles.css`, each `light-dark(light, dark)`; the top bar's switch (`src/theme.tsx`) picks light, dark, or the system setting, remembered per browser and applied before first paint by `public/theme.js` |
 | `tests/` | Tests, each against a fresh FeltDB instance |
 | `.feltkit/` | Local state, keys and builds, per environment. Never commit it |
 
@@ -92,19 +92,44 @@ operation there is authorized as the dev user you choose with **Act as**. From a
 
 ```ts
 await ctx.services.files.upload({ name: "notes.txt", content: text });
-await ctx.services.notifications.send({ recipient: "grace", type: "task.assigned", title: "Review the plan" });
+await ctx.services.notifications.send({ recipient: "grace", type: "task.completed", title: "Done" });
+await ctx.services.webhooks?.emit("task.created", { id });       // mutations only
+await ctx.services.jobs?.enqueue("projects.clear-completed", {}); // mutations only
 const greeting = await ctx.services.configuration.get("GREETING");
-await ctx.services.jobs?.enqueue("report.build", { week });   // mutations only
 ```
 
-A job type runs the function you name in `services.jobs.handlers`
-(`jobs: { handlers: { "report.build": "reports:build" } }`), as the user who queued it.
-To turn a service off, remove it from `services`.
+The starter already uses them: creating and completing a task emits `task.created` and
+`task.completed` to any registered webhook endpoint; completing someone else's task notifies
+its creator; and the job `projects.clear-completed` runs `projects:clearCompleted`.
+
+Declare what your app sends in `feltkit/app.ts`, so Studio's forms offer it in dropdowns:
+
+```ts
+services: {
+  notifications: { types: ["task.completed"] },
+  webhooks: { events: ["task.created", "task.completed"] },
+  jobs: { handlers: { "projects.clear-completed": "projects:clearCompleted" } },
+  // …
+}
+```
+
+A job type runs the mutation you name, as the user who queued it, with retries. To turn a
+service off, remove it from `services`.
+
+## Connecting an API
+
+**Studio → Integrations → Connect an API** reads an OpenAPI document (JSON) or lets you
+describe the operations yourself, then writes `feltkit/<name>.ts` and grants `<name>.*` to the
+roles you choose. Each operation becomes a capability your functions, the agent and other apps
+can call (`<name>.<operation>`), with its permission, and every call recorded. The API key is
+stored in FeltKit's custody; in production set `<NAME>_URL` and `FELTKIT_CREDENTIAL_<NAME>`.
+Then narrow each operation's `output` schema in that file to what the API returns.
 
 ## Choosing a model for the agent
 
-Open **Studio → Models**, pick a provider and model, type its API key, **Save**, then
-**Test**. Or from a terminal:
+Open **Studio → Models**, pick a provider and model, type its API key, then **Save and use**
+and **Test**. **Save for later** keeps more models (other providers too) under **Saved
+models**, each with its own key; **Use** switches the agent to one. Or from a terminal:
 
 ```bash
 npx feltkit model set --provider anthropic --model <model> --api-key-stdin
@@ -131,8 +156,18 @@ await t.close();
 
 ## Deploying
 
-FeltKit doesn't host your app. It builds an artifact you run on any Node 20+ host or
-container.
+FeltKit doesn't host your app; it builds what you run, for the way you want to run it:
+
+| Target | What runs | Data |
+|---|---|---|
+| `container` (default) | Everything in one container | FeltDB state on a volume |
+| `hosted` | A separate app container | Managed FeltDB, hosted for you, from the artifact's contract (it declares AppPort Services' collections too) |
+| `self-hosted` | A separate app container | A FeltDB server you operate (`feltdb-server`), in this app's namespace |
+
+Each target's `DEPLOY.md` spells out its contract: what to set, where state lives and how to
+recover it, what stops startup, and how to upgrade and roll back. A target never changes where
+state is stored: the container target refuses `FELTDB_URL`, and the others refuse to start
+without their FeltDB settings.
 
 1. **Check what production needs.**
 
@@ -140,50 +175,82 @@ container.
    npx feltkit readiness --env production
    ```
 
-   This lists what the environment has and lacks (state, secrets, identity, model,
-   integrations), with the fix for each. It exits with 1 while anything fails.
-
-2. **Build and verify the artifact.**
+2. **Build and verify.** It asks which target (or pass `--target container`, `hosted` or `self-hosted`):
 
    ```bash
    npm run deploy
    ```
 
-   This builds the backend and the frontend, boots the production build against throwaway
-   state to prove it serves, and writes `.feltkit/deploy/<app>-<time>/` (or `--out <dir>`)
-   with `package.json`, a `Dockerfile` and `DEPLOY.md`.
+   This builds the backend and frontend, boots the production build against throwaway state
+   to prove it serves, and writes `.feltkit/deploy/` with a `Dockerfile`, `docker-compose.yml`,
+   `fly.toml`, `.env.example` (exactly the variables it needs) and `DEPLOY.md`. Each deploy
+   replaces it, keeping production state a previous run kept inside it. It prints the commands
+   to run next.
+
+3. **Run it.** Everything in one container:
+
+   ```bash
+   docker compose -f .feltkit/deploy/docker-compose.yml up --build
+   ```
 
-3. **Run it.** From the artifact directory:
+   Or with Node, from the artifact (data in its `.feltkit/production`):
 
    ```bash
-   npm install --omit=dev
-   PORT=3000 npm start
+   cd .feltkit/deploy
    ```
 
-   Or with Docker:
+   ```bash
+   npm ci --omit=dev
+   ```
 
    ```bash
-   docker build -t tasks . && docker run -p 3000:3000 -v tasks-data:/data --env-file prod.env tasks
+   npm start
    ```
 
-**Production settings** (set them from your secret manager, never in the repository):
+   With Managed FeltDB (`--target hosted`), create the app and its key from the artifact's
+   contract (`npx feltdb init-managed --contract .feltkit/deploy/feltdb.contract.json
+   --runtime-scopes minimal`), put `FELTDB_URL`, `FELTDB_APPLICATION_ID` and `FELTDB_TOKEN` in
+   `.feltkit/deploy/.env`, then run the same `docker compose` command. With your own FeltDB
+   server (`--target self-hosted`), create a key for the app's namespace (`feltdb-server keys
+   create --keys <keys.json> --name tasks --namespace tasks --scope state:read,state:write`) and
+   put `FELTDB_URL` and `FELTDB_TOKEN` in `.env`. Either container refuses to start without its
+   settings, and checks the database answers, so it never keeps data on its own disk. For
+   Fly.io, plain Docker, or other hosts, follow `.feltkit/deploy/DEPLOY.md`.
+
+   Open <http://localhost:3000>.
+
+4. **Sign in.** Production has no development sign-in (Ada and Grace are for development).
+   Until you connect your own login, create a session token, *with the app stopped* (only one
+   process may open the state), and paste it into the app's sign-in screen:
+
+   ```bash
+   npx feltkit session create --env production --type user --id you --role member
+   ```
+
+   Run it in `.feltkit/deploy` for the Node run (or anywhere with the target's `FELTDB_*`
+   variables set: then the app may keep running, since its sessions are in FeltDB). For the one-container Docker run, use a one-off container on the same
+   volume while the app's container is stopped:
+
+   ```bash
+   docker run --rm -v tasks-data:/data tasks node node_modules/@feltdb/feltkit/bin/feltkit.js session create --env production --type user --id you --role member
+   ```
+
+   For real users, add `auth.authenticate` to `feltkit({ ... })` to verify requests with your
+   identity provider.
+
+**Production settings** (from your secret manager, never in the repository). With one
+container, none is required:
 
 | Variable | What it's for |
 |---|---|
-| `FELTKIT_STATE_DIR` | Where production state lives on a durable volume (the Docker image uses `/data/state`) |
-| `FELTDB_URL`, `FELTDB_TOKEN` | Use a FeltDB server instead of local state |
-| `FELTKIT_API_KEY_VERIFIER_KEY` | **Required**, because API keys are enabled: 32+ random bytes. Changing it invalidates every issued API key |
+| `FELTDB_URL`, `FELTDB_APPLICATION_ID`, `FELTDB_TOKEN` | Managed FeltDB (`--target hosted`) |
+| `FELTDB_URL`, `FELTDB_TOKEN` | Your FeltDB server (`--target self-hosted`) |
+| `FELTKIT_WEBHOOK_PRIVATE_NETWORKS` | `1` lets webhooks reach receivers on private networks (refused by default outside development) |
+| `FELTKIT_API_KEY_VERIFIER_KEY` | Hosted and self-hosted: 32+ random bytes (`openssl rand -base64 32`). In one container it is generated once and kept beside the state on the volume |
 | `FELTKIT_CREDENTIAL_<ID>` | Credential values, e.g. `FELTKIT_CREDENTIAL_ANTHROPIC` for `credential-ref:anthropic`. Keys you entered in Studio are development-only and are not deployed |
+| `FELTKIT_STATE_DIR` | Where local state lives (the container image uses `/data/state`, on the volume) |
 | `FELTKIT_OPERATOR_KEY` | Optional: signs operator sign-ins for production Studio |
-| `PORT` | The port to listen on |
-
-**Users in production.** Development sign-in (Ada, Grace) is off in production. Verify
-requests with your identity provider by adding `auth.authenticate` to `feltkit({ ... })`,
-or issue sessions to known principals:
-
-```bash
-npx feltkit session create --env production --id ops-bot --type agent --role agent
-```
+| `PORT` | The port to listen on (default 3000) |
 
 **Production Studio.** Studio isn't served in production unless `FELTKIT_DASHBOARD=1`. Then
 operators sign in with a one-time grant you create on the host

package/template/feltkit/_generated/api.ts

@@ -2,8 +2,9 @@
 /* eslint-disable */
 import { createApi } from "@feltdb/feltkit/client";
 import type * as app_module from "../app.js";
+import type * as inbox_module from "../inbox.js";
 import type * as projects_module from "../projects.js";
 import type * as tasks_module from "../tasks.js";
 
 /** Typed references to every query and mutation. Type-only imports: no backend code reaches the browser. */
-export const api = createApi<{ "app": typeof app_module; "projects": typeof projects_module; "tasks": typeof tasks_module }>();
+export const api = createApi<{ "app": typeof app_module; "inbox": typeof inbox_module; "projects": typeof projects_module; "tasks": typeof tasks_module }>();

package/template/feltkit/app.ts

@@ -13,15 +13,18 @@ export const app = feltkit({
   roles: {
     // Members use the app and Studio's agent (feltkit.agent.*: create, approve, and follow agent tasks).
     // notifications.*: a principal reads, marks, and dismisses only its own notifications.
-    member: ["projects.*", "tasks.*", "files.*", "notifications.*", "feltkit.agent.*"],
+    // webhooks.emit + webhooks.deliver: their changes notify registered endpoints (task.created,
+    // task.completed); each delivery runs as the person whose change emitted it.
+    member: ["projects.*", "tasks.*", "files.*", "notifications.*", "webhooks.emit", "webhooks.deliver", "feltkit.agent.*"],
     // Viewers read. They can see agent tasks but not start or approve them.
     viewer: ["projects.read", "tasks.read", "files.read", "notifications.read", "feltkit.agent.read"],
     // Agents can read, complete tasks, and leave notes. They cannot create or delete.
-    agent: ["projects.read", "tasks.read", "tasks.complete", "tasks.note", "files.read", "files.write"],
+    agent: ["projects.read", "tasks.read", "tasks.complete", "tasks.note", "files.read", "files.write", "notifications.send", "webhooks.emit", "webhooks.deliver"],
     // Admins configure the app in Studio → Services: the model (intelligence.*), stored
     // credentials (credential.*), configuration, API keys, webhooks, jobs, and schedules.
     // Credentials are stored by reference; the value never enters FeltDB.
-    admin: ["intelligence.*", "credential.*", "configuration.*", "apikeys.*", "webhooks.*", "jobs.*", "schedules.*"],
+    // feltkit.operations.*: in production, admins are Studio's operators (npx feltkit operator grant).
+    admin: ["intelligence.*", "credential.*", "configuration.*", "apikeys.*", "webhooks.*", "jobs.*", "schedules.*", "feltkit.operations.*"],
   },
   // Development-only identities. Sign in as them from the app or the dashboard.
   dev: {
@@ -34,14 +37,15 @@ export const app = feltkit({
   // Services. Intelligence is the model the agent decides with (Studio → Models).
   services: {
     files: true,
-    notifications: true,
+    // The types this app sends; Studio offers them when you send one by hand.
+    notifications: { types: ["task.completed"] },
     configuration: true,
     // A request authenticated by an API key holds these roles.
     apiKeys: { roles: ["member"] },
-    webhooks: true,
-    // Job type → the function that runs it, as the principal that queued it:
-    // jobs: { handlers: { "report.build": "reports:build" } }
-    jobs: true,
+    // The events this app emits (feltkit/tasks.ts); Studio offers them when you register an endpoint.
+    webhooks: { events: ["task.created", "task.completed"] },
+    // Job type → the mutation that runs it, as the principal that queued it, with retries.
+    jobs: { handlers: { "projects.clear-completed": "projects:clearCompleted" } },
     schedules: true,
     intelligence: true,
   },

package/template/feltkit/inbox.ts

@@ -0,0 +1,21 @@
+import { s } from "@feltdb/feltkit";
+import { app } from "./app.js";
+
+/**
+ * The signed-in person's notifications (AppPort Services Notifications, e.g. "task.completed"
+ * from tasks:setDone). Each principal reads and marks only its own; the service enforces it.
+ */
+export const list = app.query({
+  access: "notifications.read",
+  args: { unread: s.optional(s.boolean()) },
+  handler: async (ctx, { unread }) =>
+    (await ctx.services.notifications.list(unread ? { unread: true } : {})).map((n) => ({ id: n.id, type: n.type, title: n.title, data: n.data ?? null, createdAt: n.createdAt, read: Boolean(n.readAt) })),
+});
+
+export const markRead = app.mutation({
+  access: "notifications.update",
+  args: { id: s.string() },
+  handler: async (ctx, { id }) => {
+    await ctx.services.notifications.markRead(id);
+  },
+});

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.2",
+    "@feltdb/feltkit": "0.3.3",
     "react": "19.2.0",
     "react-dom": "19.2.0"
   },
@@ -27,7 +27,7 @@
   },
   "overrides": {
     "@appport/services": {
-      "@feltdb/core": "0.16.0"
+      "@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/package.json

@@ -20,16 +20,16 @@
     "deploy:fly": "node scripts/deploy-fly.mjs"
   },
   "dependencies": {
-    "@feltdb/feltkit": "0.3.2"
+    "@feltdb/feltkit": "0.3.3"
   },
   "devDependencies": {
-    "@feltdb/core": "0.16.0",
+    "@feltdb/core": "0.16.1",
     "@types/node": "22.19.1",
     "typescript": "5.9.3"
   },
   "overrides": {
     "@appport/services": {
-      "@feltdb/core": "0.16.0"
+      "@feltdb/core": "0.16.1"
     }
   }
 }

package/template/public/favicon.svg

@@ -1 +0,0 @@
-<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="8" fill="#14532d"/><path d="M11 7c-4 5-4 13 0 18M21 7c4 5 4 13 0 18" stroke="#ecfdf5" stroke-width="3" fill="none" stroke-linecap="round"/></svg>