@fabrika/app 0.3.3 → 0.4.0

package/README.md

@@ -1,11 +1,13 @@
 # `@fabrika/app`
 
-The server framework for Fabrika applications: Fetch-based HTTP routing,
-middleware, typed RPC, object-level authorization, and a typed browser client.
+The server framework for Fabrika applications: the contract, the runtime that
+serves it, typed RPC, structural errors, and a typed browser client.
 
-Proxy gates remain the application's structural front door. The app receives a
-verified Fabrika authorization context and uses `.require(action, scope)` for
-checks that depend on application-owned objects.
+An application declares its whole access surface in `fabrika.contract.ts` and
+serves it through `implement`. The platform builds the proxy's endpoint table from
+the same contract, and the proxy is the only enforcement point. The application
+receives a verified Fabrika token and checks application-owned objects through the
+access form of each endpoint.
 
 ## Installation
 
@@ -13,72 +15,79 @@ checks that depend on application-owned objects.
 bun add @fabrika/app
 ```
 
-## Example
+## Entrypoints
 
-```ts
-import {
-	type AuthContext,
-	createRpcClient,
-	defineApp,
-	initRpc,
-	type Middleware,
-	route,
-} from '@fabrika/app'
-import { z } from 'zod'
-
-interface Env {
-	ASSETS: { fetch(request: Request): Promise<Response> }
-}
+| Entrypoint                | What it is                                                                          |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `@fabrika/app`            | Typed RPC (`initRpc`, `createRpcClient`), structural errors, `FetchService` type.   |
+| `@fabrika/app/contract`   | `defineContract` and the `c.*` kit; browser-safe.                                   |
+| `@fabrika/app/implement`  | `implement`: the handlers of a contract.                                            |
+| `@fabrika/app/client`     | `createClient`: the typed browser client of a contract mount.                       |
+| `@fabrika/app/build`      | The generated entrypoint `fabrika app build` writes.                                |
+| `@fabrika/app/bun`        | `createBunHandler`, `serveContract`.                                                |
+| `@fabrika/app/cloudflare` | `createCloudflareWorker`, `createContractWorker`.                                   |
+| `@fabrika/app/service`    | The installation's own services only: `defineServiceContract`, `serveService`.      |
+| `@fabrika/app/testing`    | `testKit`: the application behind the production proxy decision and a stand-in IAM. |
 
-interface Ctx {
-	env: Env
-	auth: AuthContext
-}
+## A contract application
 
-const rpc = initRpc<Ctx>()
+```ts
+// fabrika.contract.ts
+import { defineContract } from '@fabrika/app/contract'
+import { z } from 'zod/v4'
 
-const appRouter = rpc.router({
-	projects: rpc.router({
-		rename: rpc.procedure
-			.input(z.object({ id: z.string(), name: z.string() }))
-			.require('project:write', (input) => ({
-				type: 'project',
-				value: input.id,
-			}))
-			.mutation(async ({ ctx, input }) => {
-				await renameProject(ctx.env, input.id, input.name)
-				return { ok: true }
-			}),
-	}),
+export const NoteList = z.strictObject({
+	items: z.array(z.strictObject({ id: z.uuid(), title: z.string() })),
 })
 
-export type AppRouter = typeof appRouter
-
-const auth: Middleware<Ctx> = async (_request, ctx, next) => {
-	ctx.auth = await readFabrikaAuth(ctx.env)
-	return next()
-}
+export const contract = defineContract({
+	app: 'notes',
+	dimensions: { workspace: {} },
+	actions: { 'notes.read': 'Read notes' },
+	roles: { reader: { grants: ['notes.read'] } },
+}, (c) => ({
+	api: c.rpc('/api', { callers: ['human', 'machine'] }, {
+		notes: {
+			list: c.query({
+				output: NoteList,
+				access: { action: 'notes.read', over: 'workspace' },
+			}),
+		},
+	}),
+	health: c.health('/healthz'),
+}))
+```
 
-export const app = defineApp<Env, Ctx>({
-	context: (env) => ({ env, auth: anonymousAuth() }),
-	middleware: () => [auth],
-	routes: [
-		route.get('/health', () => new Response('ok')),
-		route.rpc('/api/rpc', appRouter),
-	],
-	assets: (env) => env.ASSETS,
+```ts
+// src/app.ts
+import { implement } from '@fabrika/app/implement'
+import { contract } from '../fabrika.contract'
+import { database } from './db/database'
+import { notes } from './db/stores/notes'
+
+export default implement(contract, {
+	database,
+	deps: () => ({}),
+	handlers: () => ({
+		api: {
+			notes: {
+				list: async ({ ctx }) => ({ items: await notes.list(ctx.within) }),
+			},
+		},
+	}),
 })
-
-export const api = createRpcClient<AppRouter>({ baseUrl: '/api/rpc' })
 ```
 
-Input and output validators may use any Standard Schema implementation.
+An application has no middleware, no raw routes and no custom server.
+`fabrika app build` writes the generated entrypoint, which boots the
+implementation with `serveContract` on Bun or `createContractWorker` on Cloudflare.
+See `examples/zerops-app` and the `fabrika-app` agent skill (`skill/SKILL.md`).
 
 ## Portable RPC contracts
 
-Put only DTOs and type-only procedure declarations in a browser-safe contract
-package. The browser does not need to import the server router, its validators,
-or its context:
+The RPC library serves the `{ method, input }` wire protocol. Put only DTOs and
+type-only procedure declarations in a browser-safe contract package. The browser
+does not need to import the server router, its validators, or its context:
 
 ```ts
 import type { RpcProcedureContract } from '@fabrika/app'
@@ -111,32 +120,31 @@ export const appRouter = rpc.router({
 export const api = createRpcClient<AppRpcContract>({ baseUrl: '/api/rpc' })
 ```
 
+Input and output validators may use any Standard Schema implementation. A row
+handler of an installation service serves such a router with `dispatchRpcRequest`
+from `@fabrika/app/service`.
+
 ## Runtime adapters
 
-`defineApp()` builds the runtime-neutral Fetch request pipeline. Runtime
-entrypoints adapt that application explicitly.
+Both adapters serve a `FetchService<Env>`: an object with
+`fetch(request, env, exec)`. `serveService` returns one for a service contract.
 
 A Cloudflare Worker module imports `@fabrika/app/cloudflare`:
 
 ```ts
 import { createCloudflareWorker } from '@fabrika/app/cloudflare'
-import { app } from './app'
+import { service } from './app'
 
-export default createCloudflareWorker(app)
+export default createCloudflareWorker(service)
 ```
 
-A long-running Bun process wraps the app with `createBunHandler()`:
+A long-running Bun process wraps the service with `createBunHandler()`:
 
 ```ts
-import { defineApp, route } from '@fabrika/app'
 import { createBunHandler } from '@fabrika/app/bun'
+import { service } from './app'
 
-const app = defineApp<Deps, Ctx>({
-	context: (deps, request, exec) => ({ deps, request, exec }),
-	routes: [route.get('/healthz', () => Response.json({ status: 'ok' }))],
-})
-
-const handler = createBunHandler(app, deps, {
+const handler = createBunHandler(service, env, {
 	onBackgroundError: () => console.error('background task failed'),
 })
 
@@ -152,23 +160,3 @@ const shutdown = async (): Promise<void> => {
 `drain()` waits for every task registered through the request execution context's
 `waitUntil()`. Stop accepting requests before draining, then close databases and
 other process resources.
-
-## Runtime conformance
-
-Use the test-runner-neutral `@fabrika/app/testing` entrypoint to prove that a
-portable route behaves the same through direct Fetch dispatch and both runtime
-adapters:
-
-```ts
-import { assertAppRuntimeConformance } from '@fabrika/app/testing'
-
-const response = await assertAppRuntimeConformance({
-	app,
-	createEnv: () => createIsolatedTestEnv(),
-	createRequest: () => new Request('https://app.test/healthz'),
-})
-```
-
-The helper drains registered background work and compares normalized status,
-headers, and text body. Do not use it for routes that exist in only one runtime
-composition.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/app",
-	"version": "0.3.3",
+	"version": "0.4.0",
 	"type": "module",
 	"license": "MIT",
 	"repository": {
@@ -13,6 +13,7 @@
 	},
 	"files": [
 		"src",
+		"skill",
 		"!src/**/__tests__/**"
 	],
 	"exports": {
@@ -31,17 +32,78 @@
 			"types": "./src/cloudflare.ts",
 			"default": "./src/cloudflare.ts"
 		},
+		"./contract": {
+			"bun": "./src/contract/index.ts",
+			"types": "./src/contract/index.ts",
+			"default": "./src/contract/index.ts"
+		},
+		"./client": {
+			"bun": "./src/client/index.ts",
+			"types": "./src/client/index.ts",
+			"default": "./src/client/index.ts"
+		},
+		"./react": {
+			"bun": "./src/react/index.ts",
+			"types": "./src/react/index.ts",
+			"default": "./src/react/index.ts"
+		},
+		"./implement": {
+			"bun": "./src/implement/index.ts",
+			"types": "./src/implement/index.ts",
+			"default": "./src/implement/index.ts"
+		},
+		"./service": {
+			"bun": "./src/service/index.ts",
+			"types": "./src/service/index.ts",
+			"default": "./src/service/index.ts"
+		},
+		"./build": {
+			"bun": "./src/build.ts",
+			"types": "./src/build.ts",
+			"default": "./src/build.ts"
+		},
 		"./testing": {
-			"bun": "./src/testing.ts",
-			"types": "./src/testing.ts",
-			"default": "./src/testing.ts"
+			"bun": "./src/testing/index.ts",
+			"types": "./src/testing/index.ts",
+			"default": "./src/testing/index.ts"
+		},
+		"./testing/isolation": {
+			"bun": "./src/testing/isolation.ts",
+			"types": "./src/testing/isolation.ts",
+			"default": "./src/testing/isolation.ts"
+		},
+		"./testing/preload": {
+			"bun": "./src/testing/preload.ts",
+			"types": "./src/testing/preload.ts",
+			"default": "./src/testing/preload.ts"
+		},
+		"./agent-skill": {
+			"bun": "./src/agent-skill.ts",
+			"types": "./src/agent-skill.ts",
+			"default": "./src/agent-skill.ts"
 		}
 	},
 	"scripts": {
 		"typecheck": "tsc --noEmit",
-		"test": "bun test"
+		"test": "bun test --path-ignore-patterns='src/react/**' && bun test --isolate src/react"
 	},
 	"dependencies": {
-		"@fabrika/auth": "^0.3.3"
+		"@fabrika/auth": "^0.4.0",
+		"@fabrika/auth-core": "^0.4.0",
+		"@fabrika/db": "^0.4.0",
+		"@fabrika/jwks": "^0.4.0",
+		"@fabrika/platform": "^0.4.0",
+		"@fabrika/platform-node": "^0.4.0",
+		"@fabrika/proxy-core": "^0.4.0",
+		"jose": "^5.9.0"
+	},
+	"peerDependencies": {
+		"react": "^19.0.0",
+		"zod": "^3.25.76"
+	},
+	"peerDependenciesMeta": {
+		"react": {
+			"optional": true
+		}
 	}
 }

package/skill/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: fabrika-app
+version: 0.4.0
+description: >
+  How to write and change a Fabrika application: src/vocabulary.ts, db/migrations/, src/db/tables.ts, the
+  slices' endpoints.ts with their handlers, fabrika.contract.ts, jobs, files, webhooks, share links, connectors
+  and the generated tests. Use whenever the repository has a fabrika.contract.ts, or the task adds an endpoint,
+  a table, a migration, an action or a role.
+---
+
+# Fabrika application rules
+
+The contract is the whole surface of the application: who may call what. The proxy admits only the calls it allows,
+and the data layer scopes every row to the capability that the endpoint's access form minted. Write on the paved road
+below. When it does not reach far enough, declare the step off it. A declared step is allowed, and the approver sees it.
+
+## The files, in import order
+
+| File                       | Holds                                                                                    |
+| -------------------------- | ---------------------------------------------------------------------------------------- |
+| `src/vocabulary.ts`        | `defineVocabulary({ app, dimensions, actions, roles })`: written once, typed everywhere  |
+| `db/migrations/*.sql`      | plain SQL, one new file per change (`bunx fabrika db new <slug>`)                        |
+| `src/db/tables.ts`         | `defineTables(vocabulary, columns)({ … })`: the scope and the actions of each table      |
+| `src/app-kit.ts`           | `export const app = defineApp(vocabulary, tables)`                                       |
+| `src/schemas.ts`           | the `zod/v4` schemas several slices, or a slice and the SPA, share                       |
+| `src/shared/*.ts`          | pure functions the SPA and the slices both run; they import only `zod/v4` and each other |
+| `src/<slice>/endpoints.ts` | `app.group(…)`, a `.handle(…)` beside each endpoint, and the slice's jobs and webhooks   |
+| `src/<slice>/logic.ts`     | business rules as pure functions: no `ctx`, no data access                               |
+| `src/<slice>/queries.ts`   | data access that the slice's handlers share, over a handle they pass in                  |
+| `fabrika.contract.ts`      | `app.contract((c) => ({ api: c.rpc('/api', { … }), … }))`: mounts the groups             |
+| `src/app.ts`               | `export default serve(contract, { database: scoped(tables) })` and nothing else          |
+| `web/`                     | the SPA: React over `@fabrika/app/react` and `@fabrika/ui`, never a server module        |
+
+## The paved road
+
+```ts src/tasks/endpoints.ts
+import { BadRequestError, ConflictError, fromRow } from '@fabrika/app'
+import { z } from 'zod/v4'
+import { app } from '../app-kit'
+import { ById, Cursor, Saved, TaskStatus, Versioned } from '../schemas'
+import { canClose } from './logic'
+
+const Task = z.strictObject({
+	id: z.uuid(),
+	projectId: z.uuid(),
+	title: z.string(),
+	status: TaskStatus,
+	assignee: z.nullable(z.string()),
+	assigneeLabel: z.nullable(z.string()),
+	dueOn: z.nullable(z.iso.date()),
+	overdue: z.boolean(),
+	version: z.int(),
+})
+const TaskPage = z.strictObject({
+	items: z.array(Task),
+	next: z.nullable(z.string()),
+})
+const ListTasks = z.strictObject({
+	projectId: z.uuid(),
+	status: TaskStatus.optional(),
+	title: z.string().min(1).max(200).optional(),
+	after: Cursor.optional(),
+})
+const MyTasks = z.strictObject({ after: Cursor.optional() })
+const NewTask = z.strictObject({
+	projectId: z.uuid(),
+	title: z.string().min(1).max(200),
+	dueOn: z.iso.date().optional(),
+})
+const EditTask = z.strictObject({
+	id: z.uuid(),
+	expectVersion: z.int().positive(),
+	title: z.string().min(1).max(200),
+	dueOn: z.nullable(z.iso.date()),
+})
+const AssignTask = z.strictObject({
+	id: z.uuid(),
+	expectVersion: z.int().positive(),
+	assignee: z.nullable(z.string().max(100)),
+})
+
+export const tasks = app.group({ callers: ['human'] }, (r) => ({
+	list: r.query({
+		input: ListTasks,
+		output: TaskPage,
+		access: { action: 'tasks.read', in: 'project', from: 'projectId' },
+	})
+		.handle(async ({ input, ctx }) => {
+			const page = await ctx.db.target.tasks.list({
+				where: [
+					...(input.status === undefined
+						? []
+						: [['status', '=', input.status] as const]),
+					...(input.title === undefined
+						? []
+						: [['title', 'ilike', `%${input.title}%`] as const]),
+				],
+				orderBy: [['title', 'asc']],
+				after: input.after,
+			})
+			return {
+				items: page.items.map((row) => fromRow(Task, row)),
+				next: page.next,
+			}
+		}),
+	mine: r.query({
+		input: MyTasks,
+		output: TaskPage,
+		access: { action: 'tasks.read', over: 'project' },
+	})
+		.handle(async ({ input, ctx }) => {
+			const page = await ctx.db.within.tasks.list({
+				where: [['assignee', '=', ctx.principal.id], ['status', '<>', 'done']],
+				orderBy: [['due_on', 'asc']],
+				after: input.after,
+			})
+			return {
+				items: page.items.map((row) => fromRow(Task, row)),
+				next: page.next,
+			}
+		}),
+	get: r.query({
+		input: ById,
+		output: Task,
+		access: { action: 'tasks.read', on: 'task', from: 'id' },
+	})
+		.handle(async ({ ctx }) => fromRow(Task, await ctx.db.target.get())),
+	create: r.mutation({
+		input: NewTask,
+		output: Saved,
+		access: { action: 'tasks.write', in: 'project', from: 'projectId' },
+	})
+		.handle(({ input, ctx }) =>
+			ctx.db.target.tasks.insert({
+				title: input.title,
+				due_on: input.dueOn ?? null,
+			})
+		),
+	edit: r.mutation({
+		input: EditTask,
+		output: Saved,
+		access: { action: 'tasks.write', on: 'task', from: 'id' },
+	})
+		.handle(({ input, ctx }) =>
+			ctx.db.target.update({ title: input.title, due_on: input.dueOn }, {
+				expectVersion: input.expectVersion,
+			})
+		),
+	assign: r.mutation({
+		input: AssignTask,
+		output: Saved,
+		access: { action: 'tasks.assign', on: 'task', from: 'id' },
+	})
+		.handle(async ({ input, ctx }) => {
+			const member = input.assignee === null
+				? null
+				: await ctx.members.get(input.assignee)
+			if (input.assignee !== null && (member === null || member.disabled)) {
+				throw new BadRequestError('the assignee is not a member of the org')
+			}
+			return ctx.db.target.update({
+				assignee: member?.principalId ?? null,
+				assignee_label: member?.label ?? null,
+			}, { expectVersion: input.expectVersion })
+		}),
+	start: r.mutation({
+		input: Versioned,
+		output: Saved,
+		access: { action: 'tasks.write', on: 'task', from: 'id' },
+	})
+		.handle(({ input, ctx }) =>
+			ctx.db.target.update({ status: 'doing' }, {
+				expectVersion: input.expectVersion,
+			})
+		),
+	close: r.mutation({
+		input: Versioned,
+		output: Saved,
+		access: { action: 'tasks.write', on: 'task', from: 'id' },
+	})
+		.handle(async ({ input, ctx }) => {
+			const task = await ctx.db.target.getForUpdate()
+			if (!canClose(task.status)) {
+				throw new ConflictError('only a task in progress closes')
+			}
+			return ctx.db.target.update({ status: 'done' }, {
+				expectVersion: input.expectVersion,
+			})
+		}),
+}))
+```
+
+- The access form gives the handler its data: `on` one object by id (`ctx.db.target` is its row; another scope's is
+  404), `in` a container (`ctx.db.target.<table>.list` and `.insert`), `over` lists across the caller's scopes
+  (`ctx.db.within.<table>`), named by the nearest dimension of the rows' chain (tasks lie in a project).
+  `ctx.target.value` is the id; there is no `.id`.
+- A row reaches an output through `fromRow(Schema, row)` (snake_case to camelCase), a list's page through
+  `fromPage(Schema, page)`, or comes typed from `ctx.sql(Schema)`. Never return a raw row for a camelCase output.
+- On a versioned table `insert` and `update` answer `Saved` (`{ id, version }`), and `update` and `remove` take
+  `{ expectVersion }` (a stale one is 409). `remove` answers nothing, so its endpoint answers `{ id }`. A table without
+  `version` answers `{ id }` and takes no version. `update` takes the columns it changes, at least one.
+- A precondition reads with `getForUpdate()` and throws `ConflictError`; the rule (`canClose`) is a pure function
+  of `logic.ts`. For a business error throw `ConflictError` (409), `NotFoundError` (404) or `BadRequestError` (400) of
+  `@fabrika/app`. Any thrown value with a numeric `httpStatus` below 500, a `type` and a `message` answers that status
+  (the framework's other errors are such values); any other throw is a 500.
+- One action per endpoint. A column that another action writes gets its own write action and its own endpoint
+  (`assign` above). Never check a second action inside a handler: split the endpoint.
+- Never take a user, owner or tenant id from the input, nor the caller's own address. The scope comes from the access
+  form; `ctx.principal.id` is the caller, and `ctx.principal.email` its address. A person someone picks (`assign` above) is checked with `ctx.members.get(id)`, which answers `null` for
+  anyone outside the org, and its label comes from that answer, never from the input.
+
+## The SPA
+
+The SPA is React: `FabrikaProvider` over `createClient(contract, 'api')`, `useQuery`, `useInfiniteQuery` and
+`useMutation` of `@fabrika/app/react` for every call (typed by the contract, one `FabrikaError` union for every
+refusal), and the screens built from `@fabrika/ui` (`AppShell`, `PageHeader`, `DataTable`, `Form` and `Field`,
+`Dialog`, …) with its router and theme. Never write DOM helpers, a router, a cache or a component kit of your own.
+`useCaller()` and `<Can>` show or hide a control by what the token grants; they are information for the page, never
+the access check. `references/spa.md` shows the stack.
+
+## Off the road: declare it
+
+| What the handler needs         | Declare on the endpoint         | It gets                                            |
+| ------------------------------ | ------------------------------- | -------------------------------------------------- |
+| a join, a report, a bulk write | `sql: 'read'` (or `'write'`)    | `` ctx.sql(Row)`…` ``, scoped with `ctx.sql.scope` |
+| rows outside its capability    | `unscoped: { <table>: 'read' }` | `ctx.db.unscoped.<table>`                          |
+| another application's export   | `connect: ['<import>']`         | `ctx.connect.<import>`                             |
+| a share link                   | `issues: '<link mount>'`        | `ctx.links.issue`                                  |
+| a trigger, function or view    | its migration                   | —                                                  |
+
+Scope every scoped table a raw statement reads with `${ctx.sql.scope(<capability>, '<table>', '<alias>')}`, a conjunct
+of its WHERE or JOIN … ON (`where (<filter>) and ${…}`): `ctx.target` for `on` and `in`, `ctx.within` for `over`, a
+job's minted `Ref` or `Within` with `tx.sql.scope`. It binds the capability's whole predicate, chain included, as the
+handles apply it, and on an `update` or `delete` target it needs that operation's action; a reference table needs
+none. A deviation is fine: declare it, and do not contort the code to avoid it. The approver sees every declaration
+marked "needs closer review". Do not hide reach in a helper; the runtime builds `ctx.sql` and `ctx.db.unscoped` only
+where they are declared. A query or an export declares only `'read'`.
+
+Which promise the types, the checker, boot, the runtime or the approver keeps, and which declaration lifts each:
+[who enforces each guarantee](https://github.com/contember/fabrika-platform/blob/main/docs/reference/application-runtime.md#who-enforces-each-guarantee).
+
+## Rules
+
+- Data work first, external calls after. The invocation's one transaction rolls back on a throw; IAM, object storage
+  and connector calls do not. An endpoint the generated tests cover calls no outside service (an e-mail, a provider's
+  API): it records an outbox row, and a job sends it (`references/jobs.md`).
+- No `as` (except `as const`), `any`, `@ts-ignore`, `@ts-expect-error`, `process.env` or `Bun.env`.
+- Never log an error object, a request, headers or the environment.
+- Never edit a generated file (`src/db/schema.generated.ts`, the generated tests, `fabrika/entry.generated.ts`,
+  `fabrika/connect/`) or a committed migration. Regenerate the file; write a new migration.
+
+## Ask the human first
+
+- A 401, a 403 or a failing generated test: never loosen the contract, a role, a policy or a test to pass. Tell the
+  human which action or role the caller lacks.
+- When the task does not already ask for it, before you add a role, a grant, an action, a declared deviation, an
+  anonymous endpoint (`c.form`, a webhook, a link), an export or an import, or a job, or before you drop or rename a
+  column: say in one sentence what it lets someone do, and wait for a yes. A data repair goes to the operator, not
+  into a job.
+- A file refused as protected: stop and ask. Do not move the change elsewhere.
+
+## The loop
+
+Run from the application's root (setup: `references/app-setup.md`). The application you are handed is green: a tsc or
+checker run before you have written anything proves nothing.
+
+1. Write the slice and its tests. A schema change first adds a migration and runs `migrate` and `codegen`; a
+   handler-only change needs neither.
+2. Run `test-scaffold` when an endpoint, its access or a table policy changed.
+3. Run `bun test --isolate` until it passes. Bun strips the types and runs the tests without checking them, so this is
+   the cheap loop.
+4. Then run `tsc` and `fabrika-check` once each, in that order, at the end. The checker reads the tests too (a cast, a
+   skipped or assertion-free test, a generated test's hash).
+5. After a finding, fix it and re-run only what that fix needs: the step that found it and any later one. A checker fix
+   re-runs `tsc` only when it changed a type (a removed cast does), and the tests only when it changed what code does.
+
+```bash
+bunx fabrika db new <slug>                                  # a new migration file
+export FABRIKA_APP_ID=tasks FABRIKA_APP_DATABASE_URL="$FABRIKA_TEST_POSTGRES_URL"
+bunx fabrika db migrate && bunx fabrika db codegen          # writes src/db/schema.generated.ts
+bunx fabrika db test-scaffold                               # writes the generated tests; commit them
+bun test --isolate                                          # until it passes; needs FABRIKA_TEST_POSTGRES_URL; a skip proves nothing
+bunx tsc --noEmit                                           # once, at the end
+bunx fabrika-check .                                        # once, after tsc; refusals fail; hints print below them
+```
+
+A generated file changes only through its command (`codegen`, `test-scaffold`); running it is the loop, not an edit.
+Format and lint only the files you wrote, with the repository's own tools: in the fabrika-platform repository
+`bunx dprint fmt <files>` and `bunx biome lint <files>`, never `biome check` (its formatter fights dprint), and never a
+generated file. An application outside that repository has neither configuration: use the formatter its own
+repository configures, or none, and never add a configuration unasked; tsc and `fabrika-check` are its gates. `FABRIKA_APP_ID` is lowercase letters, digits and `-`. An applied file is immutable: while you still
+change an uncommitted migration, migrate into a fresh schema with another `FABRIKA_APP_ID`. Read a refusal's
+"allowed form" and use it; fix hints too. `references/errors.md` explains the findings and the type errors.
+
+## Previewing the screens
+
+`bunx fabrika app dev` serves the application on a loopback port through its test kit, filled by `dev/seed.ts`
+through the endpoints. Pick a persona at `/__fabrika/dev`; the toolbar on every page switches it and lists the mail IAM
+sent. Write the seed and use it as `references/dev.md` says; it never replaces a test.
+
+## References
+
+Read the one you need before you write that part. Together they are one application to copy from: `app-setup.md`
+(`package.json`, `tsconfig.json`, the contract, `fabrika.config.ts`, the SPA's build), `spa.md` (the hooks, forms and
+their errors, the caller, the components, routing, theming, screen tests), `table-and-migration.md`, `endpoint.md`
+(access forms, which `over`, the caller's scopes, handles, lists and aggregates, `fromRow`, `ctx.sql`, audited CSV
+downloads, members and labels), `tests.md` (generated tests, seeds, `testKit`, a reused scope, a caller's label, confirming a file ran),
+`errors.md` (checker findings, type errors, runtime answers), `dev.md` (the seed and the preview), `jobs.md` (which dimension `ctx.within` names, the UTC
+day), `files.md` and `webhooks-links-connectors.md`, all under `references/`. Two are applications of their own:
+`start.md`, a new application before its first table (its first test, adding the first table, installing and updating
+this skill), and `public-intake.md`, a public page, a form, a job that issues links and e-mails them, a link holder's
+files, HR's review with its history.
+
+## Not built yet
+
+- The data layer runs on Bun and Postgres only (Zerops). On Cloudflare an application has no tables, jobs or files.
+- Jobs are cron only and app-wide: no `ctx.jobs.enqueue`, no job per scope. A list write is off the road (`sql`).
+- An MCP workspace has no shell, so `codegen` and `test-scaffold` cannot run there. Tell the human; never write a
+  generated file by hand.