create-feltkit 0.3.1 → 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
@@ -7,8 +14,19 @@ npm install
 npm run dev
 ```
 
-Creates a FeltKit application: a small task manager with projects, tasks, notes
-(AppPort Services Files), three roles, live queries, AppPort capabilities, and tests.
-Refuses to write into a non-empty directory. Has no dependencies.
+Creates a FeltKit application. Refuses to write into a non-empty directory. Has no dependencies.
+
+| Starter | |
+|---|---|
+| `tasks` (default) | A small task manager with projects, tasks, notes (AppPort Services Files), three roles, live queries, AppPort capabilities, and tests. State in local FeltDB. |
+| `managed` | An inventory API whose state lives in **Managed FeltDB**: the FeltDB contract checked in, keys and contract publication through FeltDB's CLI, a Dockerfile, compose file and Fly.io configuration, and tests. |
+
+```bash
+npm create feltkit@latest inventory -- --template managed   # or: -- --managed
+cd inventory && npm install && npm test
+npm run managed:setup
+```
+
+The managed starter's README walks through setup, deployment and verification.
 
 Documentation: https://github.com/rkendel1/concave#readme

package/bin/create.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-// npm create feltkit@latest <dir>
+// npm create feltkit@latest <dir> [-- --template managed]
 import { resolve } from "node:path";
-import { scaffold, VERSION } from "../scaffold.js";
+import { scaffold, TEMPLATES, VERSION } from "../scaffold.js";
 
 const args = process.argv.slice(2);
 const color = process.stdout.isTTY && !process.env.NO_COLOR;
@@ -11,24 +11,44 @@ const green = (s) => (color ? `\u001b[32m${s}\u001b[39m` : s);
 const red = (s) => (color ? `\u001b[31m${s}\u001b[39m` : s);
 
 if (args.includes("--help") || args.includes("-h")) {
-  console.log(`npm create feltkit@latest <directory> [-- --name <app-name>]\n\nCreates a FeltKit application (a small task manager you can run immediately).`);
+  console.log(`npm create feltkit@latest <directory> [-- --name <app-name>] [-- --template <starter>]
+
+Creates a FeltKit application you can run immediately.
+
+Starters (--template):
+${Object.entries(TEMPLATES).map(([name, { description }]) => `  ${name.padEnd(9)}${description}`).join("\n")}
+
+--managed is short for --template managed.`);
   process.exit(0);
 }
 if (args.includes("--version")) {
   console.log(VERSION);
   process.exit(0);
 }
-const nameIndex = args.indexOf("--name");
-const name = nameIndex >= 0 ? args[nameIndex + 1] : undefined;
-const dir = args.find((a, i) => !a.startsWith("-") && (nameIndex < 0 || i !== nameIndex + 1)) ?? "my-feltkit-app";
+const VALUE_FLAGS = ["--name", "--template"];
+const valueOf = (flag) => {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : undefined;
+};
+const name = valueOf("--name");
+const template = args.includes("--managed") ? "managed" : (valueOf("--template") ?? "tasks");
+const dir = args.find((a, i) => !a.startsWith("-") && !VALUE_FLAGS.includes(args[i - 1])) ?? "my-feltkit-app";
 
 try {
-  const result = scaffold({ target: resolve(process.cwd(), dir), ...(name ? { name } : {}) });
-  console.log(`${green("✓")} Created ${bold(result.name)} in ${result.dir}\n`);
+  const result = scaffold({ target: resolve(process.cwd(), dir), template, ...(name ? { name } : {}) });
+  console.log(`${green("✓")} Created ${bold(result.name)} in ${result.dir}${template === "tasks" ? "" : ` (${template} starter)`}\n`);
   console.log(`  cd ${dir}`);
   console.log("  npm install");
-  console.log("  npm run dev\n");
-  console.log(dim("The dev server prints your app URL and a dashboard link. State lives in .feltkit/development/state."));
+  if (template === "managed") {
+    console.log("  npm test                 # local FeltDB, no account needed");
+    console.log("  npm run managed:setup    # Managed FeltDB: your account, a least-privilege key, the contract\n");
+    console.log(dim("State lives in Managed FeltDB once set up (README.md walks through setup, deploy and verification)."));
+    console.log(dim("Keys are written to .env.local and never committed; deploy with Docker or `npm run deploy:fly`."));
+  } else {
+    console.log("  npm run dev\n");
+    console.log(dim("The dev server prints your app URL and a dashboard link. State lives in .feltkit/development/state."));
+    console.log(dim("README.md covers running, testing, deploying, and every feltkit command."));
+  }
   console.log(dim("Using a coding agent? `npx feltkit skills install` (after npm install) adds the FeltKit skills for Claude Code."));
 } catch (error) {
   console.error(`${red("✗")} ${error.message}`);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-feltkit",
-  "version": "0.3.1",
-  "description": "Create a FeltKit application: npm create feltkit@latest my-app",
+  "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",
   "repository": {
@@ -26,6 +26,7 @@
     "scaffold.js",
     "scaffold.d.ts",
     "template",
+    "template-managed",
     "README.md"
   ],
   "scripts": {

package/scaffold.d.ts

@@ -1,3 +1,4 @@
+export type TemplateName = "tasks" | "managed";
 export interface ScaffoldOptions {
   /** Directory to create. Must not exist or be empty. */
   target: string;
@@ -5,17 +6,21 @@ export interface ScaffoldOptions {
   name?: string;
   /** Version spec for feltkit; defaults to this package's version (released in lockstep). */
   sdkSpec?: string;
+  /** Which starter: `tasks` (default, local FeltDB) or `managed` (Managed FeltDB). */
+  template?: TemplateName;
 }
 export interface ScaffoldResult {
   dir: string;
   name: string;
   sdkSpec: string;
+  template: TemplateName;
 }
 export class ScaffoldError extends Error {
-  readonly code: "TARGET_NOT_EMPTY" | "TEMPLATE_MISSING" | "TEMPLATE_OUT_OF_SYNC";
+  readonly code: "TARGET_NOT_EMPTY" | "TEMPLATE_MISSING" | "TEMPLATE_OUT_OF_SYNC" | "TEMPLATE_UNKNOWN";
   readonly hint?: string;
 }
 export declare const VERSION: string;
+export declare const TEMPLATES: Readonly<Record<TemplateName, { dir: string; description: string }>>;
 export declare function toAppName(input: string): string;
-export declare function templateDir(): string;
+export declare function templateDir(template?: TemplateName): string;
 export declare function scaffold(options: ScaffoldOptions): ScaffoldResult;

package/scaffold.js

@@ -1,10 +1,23 @@
-// Scaffold a FeltKit application from the starter template. No dependencies, so `npm create` is fast.
+// Scaffold a FeltKit application from a starter template. No dependencies, so `npm create` is fast.
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { basename, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 export const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
 
+/**
+ * The starters. Both are the same FeltKit; they differ in where state lives and how it is deployed.
+ *   tasks    a task manager with a React frontend, AppPort Services (files, intelligence) and an agent;
+ *            state in local FeltDB (`.feltkit/<env>/state`), or a FeltDB server you run.
+ *   managed  an inventory API whose state lives in Managed FeltDB: no AppPort Services (Managed FeltDB
+ *            stores only what the application's contract declares), the contract checked in, keys from
+ *            the FeltDB CLI, and a Dockerfile, compose file and Fly.io configuration.
+ */
+export const TEMPLATES = Object.freeze({
+  tasks: { dir: "template", description: "Task manager with a frontend; local FeltDB (default)" },
+  managed: { dir: "template-managed", description: "Inventory API on Managed FeltDB; contract, keys and deployment as code" },
+});
+
 export class ScaffoldError extends Error {
   constructor(code, message, hint) {
     super(message);
@@ -14,10 +27,14 @@ export class ScaffoldError extends Error {
   }
 }
 
-export function templateDir() {
-  const dir = fileURLToPath(new URL("./template/", import.meta.url));
+export function templateDir(template = "tasks") {
+  const entry = TEMPLATES[template];
+  if (!entry) {
+    throw new ScaffoldError("TEMPLATE_UNKNOWN", `There is no "${template}" starter.`, `Choose one of: ${Object.keys(TEMPLATES).join(", ")}.`);
+  }
+  const dir = fileURLToPath(new URL(`./${entry.dir}/`, import.meta.url));
   if (!existsSync(join(dir, "package.json"))) {
-    throw new ScaffoldError("TEMPLATE_MISSING", "The starter template is missing from this installation of create-feltkit.", "Reinstall it: npm create feltkit@latest");
+    throw new ScaffoldError("TEMPLATE_MISSING", `The ${template} starter is missing from this installation of create-feltkit.`, "Reinstall it: npm create feltkit@latest");
   }
   return dir;
 }
@@ -33,13 +50,13 @@ export function toAppName(input) {
   return name || "my-app";
 }
 
-export function scaffold({ target, name, sdkSpec }) {
+export function scaffold({ target, name, sdkSpec, template = "tasks" }) {
+  const source = templateDir(template);
   if (existsSync(target) && readdirSync(target).filter((f) => f !== ".git" && f !== ".DS_Store").length > 0) {
     throw new ScaffoldError("TARGET_NOT_EMPTY", `${target} already exists and is not empty. FeltKit will not write over existing files.`, "Choose a new directory name.");
   }
   const appName = toAppName(name ?? basename(target));
   const spec = sdkSpec ?? process.env.FELTKIT_SDK_SPEC ?? `^${VERSION}`;
-  const source = templateDir();
   mkdirSync(target, { recursive: true });
   cpSync(source, target, { recursive: true });
   if (existsSync(join(target, "_gitignore"))) renameSync(join(target, "_gitignore"), join(target, ".gitignore"));
@@ -52,11 +69,30 @@ export function scaffold({ target, name, sdkSpec }) {
   pkg.dependencies["@feltdb/feltkit"] = spec;
   writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
 
+  // The starter's own name, wherever it names the application.
   const appPath = join(target, "feltkit", "app.ts");
   const app = readFileSync(appPath, "utf8");
-  if (!app.includes('name: "tasks"')) {
+  const starterName = /feltkit\(\{\s*name: "([a-z][a-z0-9-]*)"/.exec(app)?.[1];
+  if (!starterName) {
     throw new ScaffoldError("TEMPLATE_OUT_OF_SYNC", "The starter's feltkit/app.ts no longer declares its name; the template is out of sync.");
   }
-  writeFileSync(appPath, app.replace('name: "tasks"', `name: ${JSON.stringify(appName)}`));
-  return { dir: target, name: appName, sdkSpec: spec };
+  writeFileSync(appPath, app.replace(`name: "${starterName}"`, `name: ${JSON.stringify(appName)}`));
+  // The default starter's README is titled with the starter's name and names its Docker image after it.
+  const readmePath = join(target, "README.md");
+  if (existsSync(readmePath)) {
+    const readme = readFileSync(readmePath, "utf8");
+    if (readme.startsWith(`# ${starterName}\n`)) {
+      writeFileSync(
+        readmePath,
+        readme
+          .replace(`# ${starterName}\n`, `# ${appName}\n`)
+          .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} `),
+      );
+    }
+  }
+  const flyPath = join(target, "fly.toml");
+  if (existsSync(flyPath)) writeFileSync(flyPath, readFileSync(flyPath, "utf8").replace(/^app = ".*"$/m, `app = ${JSON.stringify(appName)}`));
+  return { dir: target, name: appName, sdkSpec: spec, template };
 }

package/template/README.md

@@ -0,0 +1,318 @@
+# tasks
+
+A FeltKit application: a small task manager with projects, tasks and notes, roles, live
+queries, AppPort Services, an agent, and a development dashboard (Studio). Each
+environment keeps all of its state in one FeltDB instance.
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+`npm run dev` prints:
+
+```
+  App        http://localhost:3000
+  Dashboard  http://localhost:3000/_feltkit/#token=…
+  AppPort    http://localhost:3000/appport
+  MCP        http://localhost:3000/mcp
+  State      …/.feltkit/development/state
+```
+
+- **App**: you are signed in as a development user. **Ada** (`member`, `admin`) can do
+  everything; **Grace** (`viewer`) can only read. Switch between them from the app's header.
+- **Dashboard** (Studio): your data, functions, capabilities, services, agent, models and
+  every operation that ran. Keep the link private: the token in it is this environment's
+  admin token.
+- Edit anything in `feltkit/`. The backend reloads in place and keeps its state, sessions and
+  history. The frontend in `src/` hot-reloads.
+
+Development state lives in `.feltkit/development/` (ignored by git). Delete that folder to
+start over.
+
+## What's in the project
+
+| Path | What it is |
+|---|---|
+| `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. 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 |
+
+## How it works
+
+**Data.** Collections are declared in `feltkit/app.ts` with a schema; every write is
+validated against it.
+
+```ts
+export const tasks = app.collection("tasks", {
+  projectId: s.string(),
+  title: s.string({ minLength: 1, maxLength: 200 }),
+  done: s.boolean(),
+});
+```
+
+**Functions.** A query reads, a mutation writes. Writes in one mutation commit together, or
+not at all. `access` is the permission the caller needs; `capability` publishes the
+function through AppPort, so agents can use it too.
+
+```ts
+export const create = app.mutation({
+  access: "tasks.write",
+  args: { projectId: s.string(), title: s.string({ minLength: 1 }) },
+  capability: { name: "tasks.create", description: "Add a task to a project." },
+  handler: async (ctx, { projectId, title }) =>
+    ctx.db.insert(tasks, { projectId, title, done: false, createdAt: Date.now(), createdBy: ctx.auth.requirePrincipal().id }),
+});
+```
+
+**Roles.** `roles` in `feltkit/app.ts` grant permissions; `"tasks.*"` grants every
+`tasks.<x>`. The server checks them on every call, whatever the frontend shows.
+
+**Frontend.** Queries are live: they update when the data changes.
+
+```tsx
+import { useMutation, useQueryState } from "@feltdb/feltkit/react";
+import { api } from "../feltkit/_generated/api";
+
+const tasks = useQueryState(api.tasks.list, { projectId });
+const create = useMutation(api.tasks.create);
+```
+
+## Services
+
+Every AppPort Service is enabled in `feltkit/app.ts` and stored in the same FeltDB instance:
+Files, Notifications, Configuration, API keys, Webhooks, Jobs, Schedules and Intelligence.
+Configure each one in **Studio → Services**: every service has its own screen, and each
+operation there is authorized as the dev user you choose with **Act as**. From a function:
+
+```ts
+await ctx.services.files.upload({ name: "notes.txt", content: text });
+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");
+```
+
+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, 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
+```
+
+The key is stored encrypted outside FeltDB (`.feltkit/development/credentials.vault`) and is
+never shown again. Never put a key in `feltkit/`, `src/`, tests or a committed file.
+
+## Testing
+
+```bash
+npm test
+```
+
+runs `tests/**/*.test.ts`. Each `createTestApp()` gets its own temporary FeltDB instance,
+and `t.as("ada")` calls functions as a dev user:
+
+```ts
+const t = await createTestApp();
+const projectId = await t.as("ada").mutation(api.projects.create, { name: "Launch" });
+await assert.rejects(t.as("grace").mutation(api.tasks.create, { projectId, title: "x" }), { code: "FORBIDDEN" });
+await t.close();
+```
+
+## Deploying
+
+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.**
+
+   ```bash
+   npx feltkit readiness --env production
+   ```
+
+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 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
+   ```
+
+   Or with Node, from the artifact (data in its `.feltkit/production`):
+
+   ```bash
+   cd .feltkit/deploy
+   ```
+
+   ```bash
+   npm ci --omit=dev
+   ```
+
+   ```bash
+   npm start
+   ```
+
+   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 |
+|---|---|
+| `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 (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
+(`npx feltkit operator grant --id <id> --role <role> --env production`). Production Studio
+is for operating the app; data edits and service configuration stay development tools.
+To move non-secret configuration between environments, use
+`npx feltkit config export` and `npx feltkit config import <file> --env production --dry-run`.
+
+To deploy on Managed FeltDB, where no host keeps state, start from
+`npm create feltkit@latest <dir> -- --template managed`; its README walks through setup.
+
+## Commands
+
+npm scripts:
+
+| Script | Runs |
+|---|---|
+| `npm run dev` | `feltkit dev`: backend, frontend, Studio and hot reload |
+| `npm test` | `feltkit test`: the tests, against isolated test environments |
+| `npm run build` | `feltkit build`: bundle the backend, build the frontend, verify the bundle |
+| `npm start` | `feltkit start`: run the production build |
+| `npm run deploy` | `feltkit deploy`: build a verified deployment artifact |
+| `npm run inspect` | `feltkit inspect`: status, state location, functions, services, recent activity |
+| `npm run typecheck` | `tsc --noEmit` |
+
+Every `feltkit` command (run as `npx feltkit <command>`; `--help` on any of them for its options):
+
+| Command | What it does |
+|---|---|
+| `dev [--port 3000]` | Development environment: backend, frontend, Studio, hot reload |
+| `build` | Bundle the backend, build the frontend, load the bundle to verify it |
+| `start [--port $PORT]` | Run the production build (the `production` environment) |
+| `test [files…]` | Run `tests/**/*.test.ts` against isolated test environments |
+| `deploy [--out <dir>]` | Build, verify the production build boots, write a Node/Docker artifact |
+| `inspect [--json]` | What the app is, where its state lives, and what it's doing |
+| `readiness [--env production]` | What an environment has and lacks before production, with fixes |
+| `model show` / `model set` | Show or choose the model that makes agent decisions |
+| `credential set` / `status` / `remove` | Store an API key (from a hidden prompt or stdin, never an argument), see where each credential comes from, or erase one |
+| `config export` / `import` | Move non-secret configuration (variables, webhook endpoints, …) between environments |
+| `session create` / `list` / `revoke` | Sessions for agents and service accounts |
+| `operator grant` | A one-time production Studio sign-in for an operator |
+| `codegen` | Regenerate `feltkit/_generated/api.ts` |
+| `contract` | Write the FeltDB application contract (Managed FeltDB) |
+| `doctor` | Check Node, dependencies and running servers for problems |
+| `skills install` / `check` | Add or validate the FeltKit skills for coding agents (Claude Code) |
+
+## Using a coding agent
+
+```bash
+npx feltkit skills install
+```
+
+adds the FeltKit skills to `.claude/skills/`, so Claude Code knows how to build, test and
+operate this app.
+
+## When something's wrong
+
+- `npx feltkit doctor` checks Node, dependencies and running servers.
+- `npx feltkit inspect` shows the environment's state, functions and recent errors.
+- Studio → **Activity** shows every operation: who ran it, what was decided, and what FeltDB
+  committed.
+- Errors carry a code (`FORBIDDEN`, `INVALID_ARGUMENT`, `NOT_FOUND`, …) and usually a hint with
+  the fix.
+
+FeltKit documentation: <https://github.com/rkendel1/feltkit#readme>

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

@@ -12,15 +12,19 @@ export const app = feltkit({
   // Roles grant AppPort permissions. "tasks.*" grants every tasks.<x> permission.
   roles: {
     // Members use the app and Studio's agent (feltkit.agent.*: create, approve, and follow agent tasks).
-    member: ["projects.*", "tasks.*", "files.*", "feltkit.agent.*"],
+    // notifications.*: a principal reads, marks, and dismisses only its own notifications.
+    // 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", "feltkit.agent.read"],
+    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"],
-    // Admins configure the app: choose the model (intelligence.*), store API keys
-    // (credential.*), and change configuration. Keys are stored by reference; the value
-    // never enters FeltDB.
-    admin: ["intelligence.*", "credential.*", "configuration.*"],
+    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.
+    // 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: {
@@ -29,9 +33,22 @@ export const app = feltkit({
       { id: "grace", name: "Grace Hopper", roles: ["viewer"] },
     ],
   },
-  // AppPort Services, stored in this app's FeltDB instance: Files, and Intelligence (which
-  // model the agent decides with; choose one and enter its API key in Studio → Models).
-  services: { files: true, intelligence: true },
+  // AppPort Services, stored in this app's FeltDB instance, each configured in Studio →
+  // Services. Intelligence is the model the agent decides with (Studio → Models).
+  services: {
+    files: 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"] },
+    // 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,
+  },
 });
 
 export const projects = app.collection("projects", {

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);
+  },
+});