create-feltkit 0.3.1 → 0.3.2

package/README.md

@@ -7,8 +7,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.2",
+  "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`, `-v ${appName}-data:/data`)
+          .replaceAll(`--env-file prod.env ${starterName}`, `--env-file prod.env ${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,251 @@
+# 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 |
+| `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.assigned", title: "Review the plan" });
+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`.
+
+## 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:
+
+```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 an artifact you run on any Node 20+ host or
+container.
+
+1. **Check what production needs.**
+
+   ```bash
+   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.**
+
+   ```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`.
+
+3. **Run it.** From the artifact directory:
+
+   ```bash
+   npm install --omit=dev
+   PORT=3000 npm start
+   ```
+
+   Or with Docker:
+
+   ```bash
+   docker build -t tasks . && docker run -p 3000:3000 -v tasks-data:/data --env-file prod.env tasks
+   ```
+
+**Production settings** (set them from your secret manager, never in the repository):
+
+| 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 |
+| `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_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
+```
+
+**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/app.ts

@@ -12,15 +12,16 @@ 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.
+    member: ["projects.*", "tasks.*", "files.*", "notifications.*", "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.*"],
+    // 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.*"],
   },
   // Development-only identities. Sign in as them from the app or the dashboard.
   dev: {
@@ -29,9 +30,21 @@ 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,
+    notifications: true,
+    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,
+    schedules: true,
+    intelligence: true,
+  },
 });
 
 export const projects = app.collection("projects", {

package/template/package.json

@@ -13,7 +13,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@feltdb/feltkit": "0.3.1",
+    "@feltdb/feltkit": "0.3.2",
     "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.0"
+    }
   }
 }

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"]