create-relkit 0.7.7 → 0.7.9

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/SKILL.md

@@ -7,6 +7,30 @@ description: Build or extend a RELKIT CLI-generated application using its instal
 
 Run commands from the generated application's root, where `relkit.config.ts` and `package.json` live. Use `bun run relkit` to invoke the project's installed CLI. Check `bun run relkit <command> --help` before relying on an option, especially after a dependency upgrade.
 
+## Understand the requested work
+
+Infer the intent from the request; do not ask the user to classify it.
+
+- For a feature, establish the problem, scope, expected behavior and acceptance criteria. Explain a short implementation and verification plan before editing, then proceed with the authorized work.
+- For a bug, establish expected versus actual behavior, attempt reproduction, and trace the affected execution path. Distinguish a confirmed cause from a hypothesis, and explain the proposed fix and verification before editing. Report unavailable reproduction honestly.
+- For a discussion, explain options, tradeoffs and a recommendation without changing files. For mixed requests, keep the discussion portion read-only and implement only the requested work.
+
+Before scaffolding a new app, establish the database engine and driver (or an explicit no-database choice) and whether authentication is needed. Ask missing choices together before writing files. Reuse supplied choices and existing project decisions; do not restart onboarding for an unrelated bug or small change. If requested auth needs persistence but the user chose no database, explain and resolve that conflict before scaffolding. Use supported create/add options; do not invent database/auth creation flags or change headless defaults.
+
+Recommend optional modules only when they solve a concrete part of this task: for example, realtime for live order status or a bucket for uploads. Explain the benefit and ask for a selection when the capability was not requested. For an explicitly requested capability, resolve only missing provider/configuration decisions. Check installed CLI help and declarations for support; explain unavailable options before editing. A plan is not another permission gate for work already authorized.
+
+Default to backend work. Do not introduce frontend pages, app.js, assets.css or demo interfaces unless requested. Preserve existing frontend files, explicitly selected fullstack functionality and the framework Inspector. For users and orders, define separate resource endpoints with explicit input/output contracts, validation and applicable authorization; avoid a public table dispatcher controlled by an entity parameter. Internal tables and infrastructure services need no public endpoint. Preserve intentional protocol handlers such as the Better Auth mount and shared internal helpers.
+
+## Design domain ownership
+
+Before scaffolding business behavior, identify its owning domain. For a request spanning multiple business capabilities, include a compact ownership map in the implementation plan: service name, owned rules/state, public operations/events, dependencies, and any transaction spanning capabilities. Then proceed with authorized implementation; the map is not another approval gate.
+
+A domain service owns one cohesive business responsibility and its invariants. Separate capabilities with distinct rules, lifecycles, or public contracts. Keep closely related entities together when they share those rules; do not create a service per table, endpoint, or noun. Shared authentication, database, tenant ID, or deployment does not make the entire application one domain. Avoid a product-named catch-all service containing unrelated capabilities.
+
+For existing apps, reuse the service that owns the behavior. Do not reorganize unrelated domains or move existing code without task scope. A small single-domain feature needs only its existing owner, not a new architecture exercise.
+
+Read [domain design and public contracts](references/domain-apis.md) when choosing boundaries or coordinating services. Name the owner of each invariant that spans domains and explain how atomic updates remain atomic. Do not assume a nested service invocation shares the caller's database transaction. Keep the shared database/auth singletons and one migration history; business boundaries do not require separate databases or deployments.
+
 ## Source placement
 
 New projects place every generic, database, and auth boundary at `src/services/<name>/service.ts`. Keep its functions, events, tasks, jobs, tools, agents, channels, schemas, resources, helpers, and assets under that service. Routes live at `src/routes`; configuration support and environment contracts live at `src/platform`. Application descriptors use plain TypeScript and supported public APIs; Effect imports are not required.
@@ -45,4 +69,8 @@ Read only the reference relevant to the requested change. These examples describ
 
 ## Verify the result
 
-Review the CLI's created and updated files, warnings, and next steps. Run `bun run check`, `bun run typecheck`, and focused tests after editing. For HTTP work, exercise the route itself; a direct function test does not cover request mapping. Database and auth work also needs the reported environment and migration steps before runtime verification.
+Compare the final services and route targets with the ownership map. Confirm each capability has real operations under its owner, cross-service imports use public contracts, and no catch-all implementation hides behind empty services. Explain deliberate boundary changes and verify cross-domain consistency/failure behavior. A passing graph check validates structure, not domain cohesion.
+
+Review the CLI's created and updated files, warnings, next steps and final diff. Run focused checks after logical changes. Before completion, run applicable check, typecheck, build, unit/integration tests and existing relevant end-to-end coverage. Inspect package.json for actual script names. For HTTP work, test the route's status/body, valid and invalid input, and denied and allowed access where relevant; a direct function test does not cover request mapping or the complete flow. Replay the original bug through the boundary that failed. Backend/API tests do not require an unsolicited frontend.
+
+Database/auth changes also need explicit environment setup and migration steps from [the data reference](references/data-apis.md), followed by persistence/session/authorization verification. Stop all test-owned servers and clients. Report what changed, exact verification performed, and every failed, skipped or blocked check with its effect on confidence. Written code or passing unit tests alone is not fully verified delivery when affected runtime behavior remains untested.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/cli.md

@@ -24,6 +24,13 @@ These examples use the local binary through `bun run relkit`. The installed CLI'
 
 Database `--dialect` and auth `--database-dialect` also accept `postgresql` and `mysql`. Auth's `--base-path` changes the default `/api/auth` mount. The CLI adds dependencies and an environment example as needed, but it does not apply database migrations or populate secrets. Follow the scaffold's reported next steps after reviewing the schema and environment values.
 
+Run `bun run db:generate`, review tracked SQL/metadata under the database service's
+`migrations` directory, then explicitly run `bun run db:migrate`. The latter uses
+installed `relkit db migrate`, defaulting to root `drizzle.config.ts`; select another
+with `bun run relkit db migrate --config <path>`. Configuration owns the target,
+history and supported log settings; relative paths use the app root. No copied
+runner is needed. See [database tooling](data-apis.md) for environment and failure behavior.
+
 ## Other add kinds
 
 Run `bun run relkit add <kind> --help` for each kind's flags and requirements:

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/data-apis.md

@@ -30,6 +30,22 @@ export default defineDrizzleService({
 
 Open the native connection in the `client({ env })` factory and close it with `dispose` when needed. Discovery does not run the factory. Generate and review migrations with the installed Drizzle tooling; service creation does not create tables or apply migrations. After `bun run check`, generated context declarations provide typed `context.database`.
 
+## Version and apply migration source
+
+New grouped scaffolds configure `src/services/database/migrations` beside the database service and schema. Keep SQL and required Drizzle metadata in Git, outside ignored `.relkit/`. One shared database has one ordered history, including authentication tables; do not create separate histories for business services. Existing flat apps retain their selected database service directory.
+
+Set the required environment in the application root's `.env` or shell, then run:
+
+```sh
+bun run db:generate
+# Review the generated SQL and metadata before applying them.
+bun run db:migrate
+```
+
+`db:generate` uses the installed Drizzle Kit. `db:migrate` invokes installed RELKIT tooling, `relkit db migrate`, without copying a runner into the app. Root `drizzle.config.ts` explicitly owns dialect, schema, migration output, connection and supported log options. To select another config, use `bun run relkit db migrate --config configs/database.ts`; relative output/database paths still use the application root. Keep delegated PostgreSQL/MySQL config deterministic because Kit loads it again. Existing shell variables take precedence over Bun's normal dotenv loading; `.env.example` is documentation only.
+
+Migration applies pending SQL only when explicitly invoked; scaffolding and service startup do not apply it, generate secrets or open the database. SQLite uses the Bun-native driver. PostgreSQL/MySQL delegate to the app's installed Kit under Bun. Missing/empty/incompatible history requires generation or a compatible ORM/Kit pair, not a reset or fallback directory. Review failures before another manual run: SQL is not automatically retried, and dialect-specific partial DDL is not guaranteed to roll back. Keep the generated dependency patch and registration while required by the installed release.
+
 ## `defineBetterAuthService`
 
 ```ts

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/domain-apis.md

@@ -2,6 +2,60 @@
 
 Generated projects map `@app/*` to `src/*`; keep the `.js` suffix on source imports. Use the installed package types when an exact signature matters, and run `bun run check` to validate the discovered graph.
 
+## Choose a domain before choosing a folder
+
+For work spanning business capabilities, map responsibility to services before adding artifacts. Record the rules/state each service owns, the operations/events it exposes, its dependencies, and who coordinates invariants that cross boundaries. Service names should describe those responsibilities, not merely repeat the application name.
+
+For example, a commerce backend could use:
+
+| Service         | Owns                                      | Public contract                      |
+| --------------- | ----------------------------------------- | ------------------------------------ |
+| `orders`        | Order lifecycle and accepted order totals | Place/cancel order, `orders.created` |
+| `pricing`       | Price calculation and discount rules      | Calculate a quote                    |
+| `notifications` | Notification delivery and deduplication   | React to an order event              |
+
+This is an example, not a required taxonomy. Related entities such as cars and car models may belong to one fleet service. Split by distinct rules and lifecycles, not by table count. One coherent capability can remain one service. A shared database, auth service, or tenant identifier is infrastructure reuse, not a reason to collect all business operations under one service.
+
+### Public collaboration
+
+Each service selects its own operations; another service must not act as a barrel for its neighbor's internals:
+
+```ts
+// src/services/pricing/service.ts
+import { defineService } from "@relkit/app/services";
+import calculateQuote from "./functions/calculate-quote.function.js";
+
+export default defineService({ functions: { calculateQuote } });
+```
+
+An orders function can call the public pricing contract. For a pure calculation that needs no provider state:
+
+```ts
+import pricing from "@app/services/pricing/service.js";
+
+// Inside an orders function handler:
+const quote = await pricing.calculateQuote.invoke({ sku, quantity });
+// Apply the order's acceptance rules to the validated quote.
+```
+
+Use the installed declarations for the calculation's actual input/output. Do not import `pricing/functions/*`, call a foreign handler, or expose the same function as a member of two services. A route for orders targets the orders service; separate URLs alone do not establish domain boundaries.
+
+For an asynchronous reaction, orders owns and exposes `orders.created`; a consumer under `src/services/notifications/functions/` uses `defineEventFunction({ id: "notifications.order-created", event: "orders.created", ... })`. Event-only consumers are discovered in their owning domain and are not added to its callable functions map. The event examples below show publication and subscription.
+
+### Invariants and transactions
+
+Name one owner for a command's consistency rules. For example, accepting an order and reserving stock may require one atomic decision. A service call followed by a second write is not proof of an atomic transaction, and `.invoke()` must not be assumed to inherit the caller's transaction or resources.
+
+Inspect installed transaction/invocation behavior before composing provider-backed commands. Choose a supported transaction coordinator or keep tightly coupled invariants within one cohesive owner. Define narrow public operations for other domains; do not duplicate another domain's rules or silently write its owned state from arbitrary helpers. Use events for reactions that can occur after commit, with an outbox when publication must survive a crash. Events alone do not preserve synchronous atomicity.
+
+Keep one shared database service and its ordered migration history when the app uses one database. Do not create a database, auth service, or migration history per business domain.
+
+Changing an existing operation's domain ownership is a redesign, not just a grouped/flat layout move. Review IDs, durable versions, policies, callers, and stored history explicitly; do not promise that a folder move between domains preserves identity.
+
+### Review the resulting boundaries
+
+Compare the actual service graph and routes with the ownership map. Check that each planned capability has real operations under its owner, imports use public service boundaries, business rules live with their owner, and no catch-all service still contains the implementation behind empty facades. Review any merged or split responsibility and verify cross-domain failure/rollback behavior. A passing graph check proves structural validity, not semantic cohesion.
+
 ## `defineFunction` and `defineService`
 
 Put domain behavior in `src/services/<domain>/functions/*.function.ts`. A function validates input before its handler and validates the returned output:
@@ -31,6 +85,8 @@ export default defineService({ functions: { greet } });
 
 The service also accepts `events`, `tasks`, and `jobs` maps. Its members appear directly as `service.greet`; there is no `service.functions.greet` namespace. Membership makes a function available across domains, but does not create an HTTP route or grant authorization.
 
+Each `service.ts` constructs and exports exactly one runtime service value. Keep ordinary helpers and error descriptors inside their owning domain; expose callable operations through the service's `functions` map. Do not re-export helpers or descriptors from a specialized database or auth `service.ts`.
+
 Within a domain, import a sibling function directly. Across domains and from routes, import the other domain's `service.ts`. Invoke a function descriptor with `await service.greet.invoke(input)`; do not call its handler directly. Leave an internal function out of the service map. Tools, agents, caches, buckets, and event-only functions are not service members.
 
 ## `defineEvent` and `defineEventFunction`
@@ -60,13 +116,13 @@ export default orderCreated;
 
 Expose it through `defineService({ events: { orderCreated } })` when other domains need it. A publisher declares the exact ID in `publishes: ["orders.created"]` and calls `await context.events["orders.created"].publish({ orderId })`.
 
-An event-only consumer reacts without returning a result to its publisher:
+An event-only consumer in `src/services/notifications/functions/` reacts without returning a result to its publisher:
 
 ```ts
 import { defineEventFunction } from "@relkit/app/events";
 
 export default defineEventFunction({
-  id: "orders.confirmation",
+  id: "notifications.order-created",
   event: "orders.created",
   handler: async ({ orderId }, context) => {
     context.log.info("Order created", { orderId });
@@ -89,4 +145,21 @@ export default defineError({
 });
 ```
 
-Declare only expected failures callers should handle on a function. Use the route layer for HTTP-specific request mapping and middleware.
+Declare only expected failures callers should handle on a function. Return each declared error through the public `fail` helper so it appears in the inferred handler result; throwing a declared error from an ordinary helper does not satisfy that contract. Use the route layer for HTTP-specific request mapping and middleware.
+
+```ts
+import { defineFunction, fail } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+import AuthenticationRequired from "../errors/authentication-required.error.js";
+
+export default defineFunction({
+  input: z.object({}),
+  output: z.object({ id: z.string() }),
+  errors: [AuthenticationRequired],
+  handler: async (_input, context) => {
+    const session = await context.auth.getSession();
+    if (session === null) return fail(AuthenticationRequired, {});
+    return { id: session.user.id };
+  },
+});
+```

package/dist/templates/default/v1/fullstack/gitignore

@@ -1,4 +1,6 @@
 node_modules
 .next
-.relkit
+.relkit/
 .env
+.env.*
+!.env.example

package/dist/templates/default/v1/fullstack/package.json

@@ -15,9 +15,9 @@
   },
   "dependencies": {
     "@langchain/langgraph": "1.4.14",
-    "@relkit/app": "0.7.7",
-    "@relkit/client": "0.7.7",
-    "@relkit/local": "0.7.7",
+    "@relkit/app": "0.7.9",
+    "@relkit/client": "0.7.9",
+    "@relkit/local": "0.7.9",
     "@tanstack/react-query": "5.102.3",
     "effect": "4.0.1",
     "langchain": "1.5.10",
@@ -26,8 +26,8 @@
     "react-dom": "19.2.8"
   },
   "devDependencies": {
-    "@relkit/cli": "0.7.7",
-    "@relkit/testing": "0.7.7",
+    "@relkit/cli": "0.7.9",
+    "@relkit/testing": "0.7.9",
     "@types/bun": "1.3.10",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.7",

package/dist/templates/default/v1/minimal/.agents/skills/relkit/SKILL.md

@@ -7,6 +7,30 @@ description: Build or extend a RELKIT CLI-generated application using its instal
 
 Run commands from the generated application's root, where `relkit.config.ts` and `package.json` live. Use `bun run relkit` to invoke the project's installed CLI. Check `bun run relkit <command> --help` before relying on an option, especially after a dependency upgrade.
 
+## Understand the requested work
+
+Infer the intent from the request; do not ask the user to classify it.
+
+- For a feature, establish the problem, scope, expected behavior and acceptance criteria. Explain a short implementation and verification plan before editing, then proceed with the authorized work.
+- For a bug, establish expected versus actual behavior, attempt reproduction, and trace the affected execution path. Distinguish a confirmed cause from a hypothesis, and explain the proposed fix and verification before editing. Report unavailable reproduction honestly.
+- For a discussion, explain options, tradeoffs and a recommendation without changing files. For mixed requests, keep the discussion portion read-only and implement only the requested work.
+
+Before scaffolding a new app, establish the database engine and driver (or an explicit no-database choice) and whether authentication is needed. Ask missing choices together before writing files. Reuse supplied choices and existing project decisions; do not restart onboarding for an unrelated bug or small change. If requested auth needs persistence but the user chose no database, explain and resolve that conflict before scaffolding. Use supported create/add options; do not invent database/auth creation flags or change headless defaults.
+
+Recommend optional modules only when they solve a concrete part of this task: for example, realtime for live order status or a bucket for uploads. Explain the benefit and ask for a selection when the capability was not requested. For an explicitly requested capability, resolve only missing provider/configuration decisions. Check installed CLI help and declarations for support; explain unavailable options before editing. A plan is not another permission gate for work already authorized.
+
+Default to backend work. Do not introduce frontend pages, app.js, assets.css or demo interfaces unless requested. Preserve existing frontend files, explicitly selected fullstack functionality and the framework Inspector. For users and orders, define separate resource endpoints with explicit input/output contracts, validation and applicable authorization; avoid a public table dispatcher controlled by an entity parameter. Internal tables and infrastructure services need no public endpoint. Preserve intentional protocol handlers such as the Better Auth mount and shared internal helpers.
+
+## Design domain ownership
+
+Before scaffolding business behavior, identify its owning domain. For a request spanning multiple business capabilities, include a compact ownership map in the implementation plan: service name, owned rules/state, public operations/events, dependencies, and any transaction spanning capabilities. Then proceed with authorized implementation; the map is not another approval gate.
+
+A domain service owns one cohesive business responsibility and its invariants. Separate capabilities with distinct rules, lifecycles, or public contracts. Keep closely related entities together when they share those rules; do not create a service per table, endpoint, or noun. Shared authentication, database, tenant ID, or deployment does not make the entire application one domain. Avoid a product-named catch-all service containing unrelated capabilities.
+
+For existing apps, reuse the service that owns the behavior. Do not reorganize unrelated domains or move existing code without task scope. A small single-domain feature needs only its existing owner, not a new architecture exercise.
+
+Read [domain design and public contracts](references/domain-apis.md) when choosing boundaries or coordinating services. Name the owner of each invariant that spans domains and explain how atomic updates remain atomic. Do not assume a nested service invocation shares the caller's database transaction. Keep the shared database/auth singletons and one migration history; business boundaries do not require separate databases or deployments.
+
 ## Source placement
 
 New projects place every generic, database, and auth boundary at `src/services/<name>/service.ts`. Keep its functions, events, tasks, jobs, tools, agents, channels, schemas, resources, helpers, and assets under that service. Routes live at `src/routes`; configuration support and environment contracts live at `src/platform`. Application descriptors use plain TypeScript and supported public APIs; Effect imports are not required.
@@ -45,4 +69,8 @@ Read only the reference relevant to the requested change. These examples describ
 
 ## Verify the result
 
-Review the CLI's created and updated files, warnings, and next steps. Run `bun run check`, `bun run typecheck`, and focused tests after editing. For HTTP work, exercise the route itself; a direct function test does not cover request mapping. Database and auth work also needs the reported environment and migration steps before runtime verification.
+Compare the final services and route targets with the ownership map. Confirm each capability has real operations under its owner, cross-service imports use public contracts, and no catch-all implementation hides behind empty services. Explain deliberate boundary changes and verify cross-domain consistency/failure behavior. A passing graph check validates structure, not domain cohesion.
+
+Review the CLI's created and updated files, warnings, next steps and final diff. Run focused checks after logical changes. Before completion, run applicable check, typecheck, build, unit/integration tests and existing relevant end-to-end coverage. Inspect package.json for actual script names. For HTTP work, test the route's status/body, valid and invalid input, and denied and allowed access where relevant; a direct function test does not cover request mapping or the complete flow. Replay the original bug through the boundary that failed. Backend/API tests do not require an unsolicited frontend.
+
+Database/auth changes also need explicit environment setup and migration steps from [the data reference](references/data-apis.md), followed by persistence/session/authorization verification. Stop all test-owned servers and clients. Report what changed, exact verification performed, and every failed, skipped or blocked check with its effect on confidence. Written code or passing unit tests alone is not fully verified delivery when affected runtime behavior remains untested.

package/dist/templates/default/v1/minimal/.agents/skills/relkit/references/cli.md

@@ -24,6 +24,13 @@ These examples use the local binary through `bun run relkit`. The installed CLI'
 
 Database `--dialect` and auth `--database-dialect` also accept `postgresql` and `mysql`. Auth's `--base-path` changes the default `/api/auth` mount. The CLI adds dependencies and an environment example as needed, but it does not apply database migrations or populate secrets. Follow the scaffold's reported next steps after reviewing the schema and environment values.
 
+Run `bun run db:generate`, review tracked SQL/metadata under the database service's
+`migrations` directory, then explicitly run `bun run db:migrate`. The latter uses
+installed `relkit db migrate`, defaulting to root `drizzle.config.ts`; select another
+with `bun run relkit db migrate --config <path>`. Configuration owns the target,
+history and supported log settings; relative paths use the app root. No copied
+runner is needed. See [database tooling](data-apis.md) for environment and failure behavior.
+
 ## Other add kinds
 
 Run `bun run relkit add <kind> --help` for each kind's flags and requirements:

package/dist/templates/default/v1/minimal/.agents/skills/relkit/references/data-apis.md

@@ -30,6 +30,22 @@ export default defineDrizzleService({
 
 Open the native connection in the `client({ env })` factory and close it with `dispose` when needed. Discovery does not run the factory. Generate and review migrations with the installed Drizzle tooling; service creation does not create tables or apply migrations. After `bun run check`, generated context declarations provide typed `context.database`.
 
+## Version and apply migration source
+
+New grouped scaffolds configure `src/services/database/migrations` beside the database service and schema. Keep SQL and required Drizzle metadata in Git, outside ignored `.relkit/`. One shared database has one ordered history, including authentication tables; do not create separate histories for business services. Existing flat apps retain their selected database service directory.
+
+Set the required environment in the application root's `.env` or shell, then run:
+
+```sh
+bun run db:generate
+# Review the generated SQL and metadata before applying them.
+bun run db:migrate
+```
+
+`db:generate` uses the installed Drizzle Kit. `db:migrate` invokes installed RELKIT tooling, `relkit db migrate`, without copying a runner into the app. Root `drizzle.config.ts` explicitly owns dialect, schema, migration output, connection and supported log options. To select another config, use `bun run relkit db migrate --config configs/database.ts`; relative output/database paths still use the application root. Keep delegated PostgreSQL/MySQL config deterministic because Kit loads it again. Existing shell variables take precedence over Bun's normal dotenv loading; `.env.example` is documentation only.
+
+Migration applies pending SQL only when explicitly invoked; scaffolding and service startup do not apply it, generate secrets or open the database. SQLite uses the Bun-native driver. PostgreSQL/MySQL delegate to the app's installed Kit under Bun. Missing/empty/incompatible history requires generation or a compatible ORM/Kit pair, not a reset or fallback directory. Review failures before another manual run: SQL is not automatically retried, and dialect-specific partial DDL is not guaranteed to roll back. Keep the generated dependency patch and registration while required by the installed release.
+
 ## `defineBetterAuthService`
 
 ```ts

package/dist/templates/default/v1/minimal/.agents/skills/relkit/references/domain-apis.md

@@ -2,6 +2,60 @@
 
 Generated projects map `@app/*` to `src/*`; keep the `.js` suffix on source imports. Use the installed package types when an exact signature matters, and run `bun run check` to validate the discovered graph.
 
+## Choose a domain before choosing a folder
+
+For work spanning business capabilities, map responsibility to services before adding artifacts. Record the rules/state each service owns, the operations/events it exposes, its dependencies, and who coordinates invariants that cross boundaries. Service names should describe those responsibilities, not merely repeat the application name.
+
+For example, a commerce backend could use:
+
+| Service         | Owns                                      | Public contract                      |
+| --------------- | ----------------------------------------- | ------------------------------------ |
+| `orders`        | Order lifecycle and accepted order totals | Place/cancel order, `orders.created` |
+| `pricing`       | Price calculation and discount rules      | Calculate a quote                    |
+| `notifications` | Notification delivery and deduplication   | React to an order event              |
+
+This is an example, not a required taxonomy. Related entities such as cars and car models may belong to one fleet service. Split by distinct rules and lifecycles, not by table count. One coherent capability can remain one service. A shared database, auth service, or tenant identifier is infrastructure reuse, not a reason to collect all business operations under one service.
+
+### Public collaboration
+
+Each service selects its own operations; another service must not act as a barrel for its neighbor's internals:
+
+```ts
+// src/services/pricing/service.ts
+import { defineService } from "@relkit/app/services";
+import calculateQuote from "./functions/calculate-quote.function.js";
+
+export default defineService({ functions: { calculateQuote } });
+```
+
+An orders function can call the public pricing contract. For a pure calculation that needs no provider state:
+
+```ts
+import pricing from "@app/services/pricing/service.js";
+
+// Inside an orders function handler:
+const quote = await pricing.calculateQuote.invoke({ sku, quantity });
+// Apply the order's acceptance rules to the validated quote.
+```
+
+Use the installed declarations for the calculation's actual input/output. Do not import `pricing/functions/*`, call a foreign handler, or expose the same function as a member of two services. A route for orders targets the orders service; separate URLs alone do not establish domain boundaries.
+
+For an asynchronous reaction, orders owns and exposes `orders.created`; a consumer under `src/services/notifications/functions/` uses `defineEventFunction({ id: "notifications.order-created", event: "orders.created", ... })`. Event-only consumers are discovered in their owning domain and are not added to its callable functions map. The event examples below show publication and subscription.
+
+### Invariants and transactions
+
+Name one owner for a command's consistency rules. For example, accepting an order and reserving stock may require one atomic decision. A service call followed by a second write is not proof of an atomic transaction, and `.invoke()` must not be assumed to inherit the caller's transaction or resources.
+
+Inspect installed transaction/invocation behavior before composing provider-backed commands. Choose a supported transaction coordinator or keep tightly coupled invariants within one cohesive owner. Define narrow public operations for other domains; do not duplicate another domain's rules or silently write its owned state from arbitrary helpers. Use events for reactions that can occur after commit, with an outbox when publication must survive a crash. Events alone do not preserve synchronous atomicity.
+
+Keep one shared database service and its ordered migration history when the app uses one database. Do not create a database, auth service, or migration history per business domain.
+
+Changing an existing operation's domain ownership is a redesign, not just a grouped/flat layout move. Review IDs, durable versions, policies, callers, and stored history explicitly; do not promise that a folder move between domains preserves identity.
+
+### Review the resulting boundaries
+
+Compare the actual service graph and routes with the ownership map. Check that each planned capability has real operations under its owner, imports use public service boundaries, business rules live with their owner, and no catch-all service still contains the implementation behind empty facades. Review any merged or split responsibility and verify cross-domain failure/rollback behavior. A passing graph check proves structural validity, not semantic cohesion.
+
 ## `defineFunction` and `defineService`
 
 Put domain behavior in `src/services/<domain>/functions/*.function.ts`. A function validates input before its handler and validates the returned output:
@@ -31,6 +85,8 @@ export default defineService({ functions: { greet } });
 
 The service also accepts `events`, `tasks`, and `jobs` maps. Its members appear directly as `service.greet`; there is no `service.functions.greet` namespace. Membership makes a function available across domains, but does not create an HTTP route or grant authorization.
 
+Each `service.ts` constructs and exports exactly one runtime service value. Keep ordinary helpers and error descriptors inside their owning domain; expose callable operations through the service's `functions` map. Do not re-export helpers or descriptors from a specialized database or auth `service.ts`.
+
 Within a domain, import a sibling function directly. Across domains and from routes, import the other domain's `service.ts`. Invoke a function descriptor with `await service.greet.invoke(input)`; do not call its handler directly. Leave an internal function out of the service map. Tools, agents, caches, buckets, and event-only functions are not service members.
 
 ## `defineEvent` and `defineEventFunction`
@@ -60,13 +116,13 @@ export default orderCreated;
 
 Expose it through `defineService({ events: { orderCreated } })` when other domains need it. A publisher declares the exact ID in `publishes: ["orders.created"]` and calls `await context.events["orders.created"].publish({ orderId })`.
 
-An event-only consumer reacts without returning a result to its publisher:
+An event-only consumer in `src/services/notifications/functions/` reacts without returning a result to its publisher:
 
 ```ts
 import { defineEventFunction } from "@relkit/app/events";
 
 export default defineEventFunction({
-  id: "orders.confirmation",
+  id: "notifications.order-created",
   event: "orders.created",
   handler: async ({ orderId }, context) => {
     context.log.info("Order created", { orderId });
@@ -89,4 +145,21 @@ export default defineError({
 });
 ```
 
-Declare only expected failures callers should handle on a function. Use the route layer for HTTP-specific request mapping and middleware.
+Declare only expected failures callers should handle on a function. Return each declared error through the public `fail` helper so it appears in the inferred handler result; throwing a declared error from an ordinary helper does not satisfy that contract. Use the route layer for HTTP-specific request mapping and middleware.
+
+```ts
+import { defineFunction, fail } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+import AuthenticationRequired from "../errors/authentication-required.error.js";
+
+export default defineFunction({
+  input: z.object({}),
+  output: z.object({ id: z.string() }),
+  errors: [AuthenticationRequired],
+  handler: async (_input, context) => {
+    const session = await context.auth.getSession();
+    if (session === null) return fail(AuthenticationRequired, {});
+    return { id: session.user.id };
+  },
+});
+```

package/dist/templates/default/v1/minimal/gitignore

@@ -2,9 +2,6 @@ node_modules/
 .env
 .env.*
 !.env.example
-.relkit/generated/
-.relkit/build/
-.relkit/state/
-.relkit/observability/
+.relkit/
 coverage/
 dist/

package/dist/templates/default/v1/minimal/package.json

@@ -15,13 +15,13 @@
     "graph": "relkit graph print"
   },
   "dependencies": {
-    "@relkit/app": "0.7.7",
+    "@relkit/app": "0.7.9",
     "effect": "4.0.1"
   },
   "devDependencies": {
     "@types/bun": "1.3.10",
-    "@relkit/cli": "0.7.7",
-    "@relkit/testing": "0.7.7",
+    "@relkit/cli": "0.7.9",
+    "@relkit/testing": "0.7.9",
     "typescript": "5.9.3"
   }
 }

package/dist/templates/default/v1/tasks/.agents/skills/relkit/SKILL.md

@@ -7,6 +7,30 @@ description: Build or extend a RELKIT CLI-generated application using its instal
 
 Run commands from the generated application's root, where `relkit.config.ts` and `package.json` live. Use `bun run relkit` to invoke the project's installed CLI. Check `bun run relkit <command> --help` before relying on an option, especially after a dependency upgrade.
 
+## Understand the requested work
+
+Infer the intent from the request; do not ask the user to classify it.
+
+- For a feature, establish the problem, scope, expected behavior and acceptance criteria. Explain a short implementation and verification plan before editing, then proceed with the authorized work.
+- For a bug, establish expected versus actual behavior, attempt reproduction, and trace the affected execution path. Distinguish a confirmed cause from a hypothesis, and explain the proposed fix and verification before editing. Report unavailable reproduction honestly.
+- For a discussion, explain options, tradeoffs and a recommendation without changing files. For mixed requests, keep the discussion portion read-only and implement only the requested work.
+
+Before scaffolding a new app, establish the database engine and driver (or an explicit no-database choice) and whether authentication is needed. Ask missing choices together before writing files. Reuse supplied choices and existing project decisions; do not restart onboarding for an unrelated bug or small change. If requested auth needs persistence but the user chose no database, explain and resolve that conflict before scaffolding. Use supported create/add options; do not invent database/auth creation flags or change headless defaults.
+
+Recommend optional modules only when they solve a concrete part of this task: for example, realtime for live order status or a bucket for uploads. Explain the benefit and ask for a selection when the capability was not requested. For an explicitly requested capability, resolve only missing provider/configuration decisions. Check installed CLI help and declarations for support; explain unavailable options before editing. A plan is not another permission gate for work already authorized.
+
+Default to backend work. Do not introduce frontend pages, app.js, assets.css or demo interfaces unless requested. Preserve existing frontend files, explicitly selected fullstack functionality and the framework Inspector. For users and orders, define separate resource endpoints with explicit input/output contracts, validation and applicable authorization; avoid a public table dispatcher controlled by an entity parameter. Internal tables and infrastructure services need no public endpoint. Preserve intentional protocol handlers such as the Better Auth mount and shared internal helpers.
+
+## Design domain ownership
+
+Before scaffolding business behavior, identify its owning domain. For a request spanning multiple business capabilities, include a compact ownership map in the implementation plan: service name, owned rules/state, public operations/events, dependencies, and any transaction spanning capabilities. Then proceed with authorized implementation; the map is not another approval gate.
+
+A domain service owns one cohesive business responsibility and its invariants. Separate capabilities with distinct rules, lifecycles, or public contracts. Keep closely related entities together when they share those rules; do not create a service per table, endpoint, or noun. Shared authentication, database, tenant ID, or deployment does not make the entire application one domain. Avoid a product-named catch-all service containing unrelated capabilities.
+
+For existing apps, reuse the service that owns the behavior. Do not reorganize unrelated domains or move existing code without task scope. A small single-domain feature needs only its existing owner, not a new architecture exercise.
+
+Read [domain design and public contracts](references/domain-apis.md) when choosing boundaries or coordinating services. Name the owner of each invariant that spans domains and explain how atomic updates remain atomic. Do not assume a nested service invocation shares the caller's database transaction. Keep the shared database/auth singletons and one migration history; business boundaries do not require separate databases or deployments.
+
 ## Source placement
 
 New projects place every generic, database, and auth boundary at `src/services/<name>/service.ts`. Keep its functions, events, tasks, jobs, tools, agents, channels, schemas, resources, helpers, and assets under that service. Routes live at `src/routes`; configuration support and environment contracts live at `src/platform`. Application descriptors use plain TypeScript and supported public APIs; Effect imports are not required.
@@ -45,4 +69,8 @@ Read only the reference relevant to the requested change. These examples describ
 
 ## Verify the result
 
-Review the CLI's created and updated files, warnings, and next steps. Run `bun run check`, `bun run typecheck`, and focused tests after editing. For HTTP work, exercise the route itself; a direct function test does not cover request mapping. Database and auth work also needs the reported environment and migration steps before runtime verification.
+Compare the final services and route targets with the ownership map. Confirm each capability has real operations under its owner, cross-service imports use public contracts, and no catch-all implementation hides behind empty services. Explain deliberate boundary changes and verify cross-domain consistency/failure behavior. A passing graph check validates structure, not domain cohesion.
+
+Review the CLI's created and updated files, warnings, next steps and final diff. Run focused checks after logical changes. Before completion, run applicable check, typecheck, build, unit/integration tests and existing relevant end-to-end coverage. Inspect package.json for actual script names. For HTTP work, test the route's status/body, valid and invalid input, and denied and allowed access where relevant; a direct function test does not cover request mapping or the complete flow. Replay the original bug through the boundary that failed. Backend/API tests do not require an unsolicited frontend.
+
+Database/auth changes also need explicit environment setup and migration steps from [the data reference](references/data-apis.md), followed by persistence/session/authorization verification. Stop all test-owned servers and clients. Report what changed, exact verification performed, and every failed, skipped or blocked check with its effect on confidence. Written code or passing unit tests alone is not fully verified delivery when affected runtime behavior remains untested.

package/dist/templates/default/v1/tasks/.agents/skills/relkit/references/cli.md

@@ -24,6 +24,13 @@ These examples use the local binary through `bun run relkit`. The installed CLI'
 
 Database `--dialect` and auth `--database-dialect` also accept `postgresql` and `mysql`. Auth's `--base-path` changes the default `/api/auth` mount. The CLI adds dependencies and an environment example as needed, but it does not apply database migrations or populate secrets. Follow the scaffold's reported next steps after reviewing the schema and environment values.
 
+Run `bun run db:generate`, review tracked SQL/metadata under the database service's
+`migrations` directory, then explicitly run `bun run db:migrate`. The latter uses
+installed `relkit db migrate`, defaulting to root `drizzle.config.ts`; select another
+with `bun run relkit db migrate --config <path>`. Configuration owns the target,
+history and supported log settings; relative paths use the app root. No copied
+runner is needed. See [database tooling](data-apis.md) for environment and failure behavior.
+
 ## Other add kinds
 
 Run `bun run relkit add <kind> --help` for each kind's flags and requirements:

package/dist/templates/default/v1/tasks/.agents/skills/relkit/references/data-apis.md

@@ -30,6 +30,22 @@ export default defineDrizzleService({
 
 Open the native connection in the `client({ env })` factory and close it with `dispose` when needed. Discovery does not run the factory. Generate and review migrations with the installed Drizzle tooling; service creation does not create tables or apply migrations. After `bun run check`, generated context declarations provide typed `context.database`.
 
+## Version and apply migration source
+
+New grouped scaffolds configure `src/services/database/migrations` beside the database service and schema. Keep SQL and required Drizzle metadata in Git, outside ignored `.relkit/`. One shared database has one ordered history, including authentication tables; do not create separate histories for business services. Existing flat apps retain their selected database service directory.
+
+Set the required environment in the application root's `.env` or shell, then run:
+
+```sh
+bun run db:generate
+# Review the generated SQL and metadata before applying them.
+bun run db:migrate
+```
+
+`db:generate` uses the installed Drizzle Kit. `db:migrate` invokes installed RELKIT tooling, `relkit db migrate`, without copying a runner into the app. Root `drizzle.config.ts` explicitly owns dialect, schema, migration output, connection and supported log options. To select another config, use `bun run relkit db migrate --config configs/database.ts`; relative output/database paths still use the application root. Keep delegated PostgreSQL/MySQL config deterministic because Kit loads it again. Existing shell variables take precedence over Bun's normal dotenv loading; `.env.example` is documentation only.
+
+Migration applies pending SQL only when explicitly invoked; scaffolding and service startup do not apply it, generate secrets or open the database. SQLite uses the Bun-native driver. PostgreSQL/MySQL delegate to the app's installed Kit under Bun. Missing/empty/incompatible history requires generation or a compatible ORM/Kit pair, not a reset or fallback directory. Review failures before another manual run: SQL is not automatically retried, and dialect-specific partial DDL is not guaranteed to roll back. Keep the generated dependency patch and registration while required by the installed release.
+
 ## `defineBetterAuthService`
 
 ```ts