create-relkit 0.7.4 → 0.7.6

package/dist/templates/default/v1/api/.agents/skills/relkit/references/testing-apis.md

@@ -0,0 +1,71 @@
+# Testing a RELKIT application
+
+Generated projects use Bun's test runner and `@relkit/testing`. Start with the existing `tests/unit` and `tests/integration` examples, then test the boundary that owns the behavior. Keep external providers and test state explicit; `RELKIT_ENV=test` alone does not select fakes.
+
+## Direct function tests
+
+`invokeFunction` runs a function descriptor through RELKIT's input/output validation and handler path without an HTTP server. Import a service's public function through its `service.ts` when testing the public member:
+
+```ts
+import { expect, test } from "bun:test";
+import { invokeFunction } from "@relkit/testing";
+import orders from "@app/services/orders/service.js";
+
+test("createOrder calculates its total", async () => {
+  await expect(
+    invokeFunction(orders.createOrder, { orderId: "order-1", sku: "book", quantity: 3 }),
+  ).resolves.toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
+});
+```
+
+Pass explicit `env`, `context`, `clients`, or other `InvokeFunctionOptions` when the function needs them. Test invalid input and declared errors as well as success. Direct invocation does not test route mapping or middleware.
+
+For several invocations that share a deterministic clock or provider state, use `createTestRuntime({ app, env, providers, startTimeMs })` and `runtime.invoke(target, input)`. `runtime.clock.advance(ms)` controls its test clock. Always `await runtime.close()` in `finally` or `afterAll`.
+
+## Application and HTTP tests
+
+`createTestApplication` discovers the generated project's routes and services. Pass its existing `relkit.config.ts`; `resourceProviders: "fake"` explicitly replaces graph-required resource providers for local tests:
+
+```ts
+import { afterAll, expect, test } from "bun:test";
+import { createTestApplication } from "@relkit/testing";
+import config from "../../relkit.config.js";
+
+const app = await createTestApplication(config, { resourceProviders: "fake" });
+afterAll(() => app.close());
+
+test("POST /orders maps and validates input", async () => {
+  const response = await app.http.request("/orders", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ orderId: "order-1", sku: "book", quantity: 3 }),
+  });
+  expect(response.status).toBe(201);
+  expect(await response.json()).toEqual({ orderId: "order-1", sku: "book", totalCents: 300 });
+});
+```
+
+Use `app.http.request`, `get`, or other client methods to assert status, body, and headers. Add requests for invalid input, anonymous callers, and unauthorized resource access where relevant. The harness has `runtime`, `clock`, `fakes`, and `observability` for controlled state and inspection. Options include `env`, `environment`, `bindingValues`, `providers`, and `projectRoot`; use explicit values for test-only configuration. This in-process HTTP boundary does not prove the full production middleware, cookie/origin policy, OpenAPI, or network transport. Verify those against a running backend when relevant.
+
+## Provider and feature tests
+
+- `createTestCacheFake`, `createTestBucketFake`, `createTestJobFake`, and `createTestEventFake` provide owned, inspectable test dependencies. `createTestFakes` groups native clients. Close any separately created fake after use. Replace every configured provider profile the graph needs, not only the one under direct assertion.
+- `createTestHttpClient` exercises a standalone in-memory HTTP application. Use `createTestApplication` when route discovery and service wiring matter. `createTestRealtimeProvider` and `createTestAgentStateProvider` supply local stateful provider replacements.
+- `createTestModel`, `createTestAgent`, and `assertAgentTrace` support deterministic agent execution. Use scripted responses and inspect tool calls or traces instead of live model calls or sleeps.
+- For jobs, assert behavior beyond the descriptor shape: input/output, accepted run handle, progress, retry or cancellation policy, and idempotency where applicable. Use the test job adapter or fake appropriate to the contract.
+- For database and auth integration, migrate an isolated temporary database before starting the application. Supply both parsed RELKIT environment and any native auth process environment required by the provider; close the app before removing test-owned files. Test public and protected requests with real cookies and separate users. A direct function mock does not verify migrations, sessions, or route protection.
+- For realtime, streaming, and observability, test the exposed route or channel contract and recorded events/spans as applicable. Use a running backend for actual transport, connection, and browser behavior.
+
+## Run the generated project checks
+
+```sh
+bun test tests/unit/hello.function.test.ts
+bun run test:unit
+bun run test:integration
+bun run test
+bun run check
+bun run typecheck
+bun run build
+```
+
+Run only scripts present in the generated `package.json`; the task template may have a different test layout. Keep Docker, external providers, and cloud acceptance as explicit integration gates. The installed `@relkit/testing` declarations and the project's existing tests are the source for exact helper options.

package/dist/templates/default/v1/api/README.md

@@ -1,5 +1,8 @@
 # my-app
 
+This maintained API candidate is exercised internally. Public API creation remains
+disabled until its exact native and readiness certification passes.
+
 A RelKit TypeScript/Bun API project with greeting, echo, and order routes.
 Functions own the application handlers; routes describe transport mapping and
 responses. Source-scoped IDs are inferred where safe, the order route targets a
@@ -21,3 +24,10 @@ The example routes are `GET /hello?name=RelKit`, `POST /echo` with a JSON
 
 The default project needs no Docker daemon, cloud account, or deployment
 credentials.
+
+Each service owns `src/services/<name>/service.ts` and its local implementations.
+Routes live in `src/routes/`, and configuration support lives in `src/platform/`.
+Keep public descriptors and async handlers in ordinary TypeScript. When installation
+is skipped, install dependencies and run `bunx --no-install relkit dev --prepare`
+before development. Use `relkit migrate layout` to preview a move of an existing
+flat application; additions otherwise preserve its detected root.

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

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

package/dist/templates/default/v1/api/src/routes/echo/route.ts

@@ -1,5 +1,6 @@
+/** Maps the HTTP endpoint to its owning service's public member. */
 import { defineRoute } from "@relkit/app/routes";
-import echo from "@app/echo/service.js";
+import echo from "@app/services/echo/service.js";
 
 export const POST = defineRoute({
   target: echo.echo,

package/dist/templates/default/v1/api/src/routes/hello/route.ts

@@ -1,5 +1,6 @@
+/** Maps the HTTP endpoint to its owning service's public member. */
 import { defineRoute } from "@relkit/app/routes";
-import hello from "@app/hello/service.js";
+import hello from "@app/services/hello/service.js";
 
 export const GET = defineRoute({
   target: hello.hello,

package/dist/templates/default/v1/api/src/routes/orders/route.ts

@@ -1,5 +1,6 @@
+/** Maps the HTTP endpoint to its owning service's public member. */
 import { defineServiceRoutes } from "@relkit/app/routes";
-import orders from "@app/orders/service.js";
+import orders from "@app/services/orders/service.js";
 
 export const { POST } = defineServiceRoutes(orders, {
   POST: { member: "createOrder", successStatus: 201 },

package/dist/templates/default/v1/api/src/{echo → services/echo}/functions/echo.function.ts

@@ -1,3 +1,4 @@
+/** Echoes a nonempty message through the service's validated function and inferred HTTP contract. */
 import { defineFunction } from "@relkit/app/functions";
 import { z } from "@relkit/app/schema";
 

package/dist/templates/default/v1/api/src/services/echo/service.ts

@@ -0,0 +1,5 @@
+/** Declares the echo service boundary and its public members. */
+import { defineService } from "@relkit/app/services";
+import echo from "@app/services/echo/functions/echo.function.js";
+
+export default defineService({ functions: { echo } });

package/dist/templates/default/v1/api/src/{hello → services/hello}/functions/hello.function.ts

@@ -1,9 +1,16 @@
+/** Returns a validated named greeting and logs each invocation through RELKIT's request context. */
 import { defineFunction } from "@relkit/app/functions";
 import { z } from "@relkit/app/schema";
 
 const hello = defineFunction({
   input: z.object({ name: z.string().min(1).default("world") }),
   output: z.object({ message: z.string() }),
+  /**
+   * Logs the greeting invocation and returns the validated greeting response.
+   * @param input - Validated name from the function schema.
+   * @param context - RELKIT invocation context owning structured logging.
+   * @returns Greeting response matching the output schema.
+   */
   handler: async ({ name }, context) => {
     context.log.info("hello invoked", { name });
     return { message: `Hello, ${name}!` };

package/dist/templates/default/v1/api/src/services/hello/service.ts

@@ -0,0 +1,5 @@
+/** Declares the hello service boundary and its public members. */
+import { defineService } from "@relkit/app/services";
+import hello from "@app/services/hello/functions/hello.function.js";
+
+export default defineService({ functions: { hello } });

package/dist/templates/default/v1/api/src/{orders → services/orders}/functions/create-order.function.ts

@@ -1,6 +1,7 @@
+/** Validates order input, invokes the service-local pricing function, and returns the calculated order. */
 import { defineFunction } from "@relkit/app/functions";
 import { z } from "@relkit/app/schema";
-import priceOrder from "@app/orders/functions/price-order.function.js";
+import priceOrder from "@app/services/orders/functions/price-order.function.js";
 
 const orderInput = z.object({
   orderId: z.string().min(1),

package/dist/templates/default/v1/api/src/{orders → services/orders}/functions/price-order.function.ts

@@ -1,3 +1,4 @@
+/** Calculates integer order totals at 100 cents per item for the create-order function. */
 import { defineFunction } from "@relkit/app/functions";
 import { z } from "@relkit/app/schema";
 

package/dist/templates/default/v1/api/src/services/orders/service.ts

@@ -0,0 +1,8 @@
+/** Declares the orders service boundary and its public members. */
+import { defineService } from "@relkit/app/services";
+import createOrder from "@app/services/orders/functions/create-order.function.js";
+import priceOrder from "@app/services/orders/functions/price-order.function.js";
+
+export default defineService({
+  functions: { createOrder, priceOrder },
+});

package/dist/templates/default/v1/api/tests/unit/echo.function.test.ts

@@ -1,6 +1,7 @@
+/** Checks echo.function through the supported public RELKIT APIs. */
 import { expect, test } from "bun:test";
 import { invokeFunction } from "@relkit/testing";
-import echo from "@app/echo/functions/echo.function.js";
+import echo from "@app/services/echo/functions/echo.function.js";
 
 test("echo returns its input", async () => {
   await expect(invokeFunction(echo, { message: "hello" })).resolves.toEqual({

package/dist/templates/default/v1/api/tests/unit/hello.function.test.ts

@@ -1,6 +1,7 @@
+/** Checks hello.function through the supported public RELKIT APIs. */
 import { expect, test } from "bun:test";
 import { invokeFunction } from "@relkit/testing";
-import hello from "@app/hello/functions/hello.function.js";
+import hello from "@app/services/hello/functions/hello.function.js";
 
 test("hello returns a greeting", async () => {
   await expect(invokeFunction(hello, { name: "Mustafa" })).resolves.toEqual({

package/dist/templates/default/v1/api/tests/unit/orders.function.test.ts

@@ -1,6 +1,7 @@
+/** Checks orders.function through the supported public RELKIT APIs. */
 import { expect, test } from "bun:test";
 import { invokeFunction } from "@relkit/testing";
-import orders from "@app/orders/service.js";
+import orders from "@app/services/orders/service.js";
 
 test("createOrder invokes pricing", async () => {
   const result = await invokeFunction(orders.createOrder, {

package/dist/templates/default/v1/api/tsconfig.json

@@ -8,6 +8,7 @@
     "paths": { "@app/*": ["src/*"] },
     "lib": ["ES2022"],
     "types": ["bun"],
+    "typeRoots": ["./node_modules/@types"],
     "plugins": [{ "name": "@relkit/cli/editor" }],
     "strict": true,
     "noUncheckedIndexedAccess": true,

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

@@ -0,0 +1,48 @@
+---
+name: relkit
+description: Build or extend a RELKIT CLI-generated application using its installed scaffolding and project commands. Use for application config, environments, services, functions, routes, auth, database, jobs, providers, and related app work.
+---
+
+# Work in a RELKIT application
+
+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.
+
+## 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.
+
+Existing flat projects with `src/<name>/service.ts` remain supported. `relkit add` preserves the detected layout; empty projects default to grouped. Never mix flat and grouped boundaries or add an aggregate `src/services/service.ts`. Across services and from routes, import only the destination's `service.ts`; Platform cannot import services or Routes. Ordinary helpers do not become independently discovered descriptors.
+
+Read [layout migration](references/layout-migration.md) before moving an existing app. Keep logical IDs, exposure, provider profiles, and durable contract versions stable during a source-only move.
+
+## Add application artifacts
+
+Inspect the existing `src/` tree and `relkit.config.ts` before scaffolding. Prefer `relkit add` for supported artifacts, then edit the generated source for the required behavior. An interactive terminal can prompt for missing choices; scripts and noninteractive runs should provide the kind, name, service, route mode, and mappings explicitly.
+
+Read [the CLI reference](references/cli.md) for commands and option patterns covering services, functions, routes, auth, database, and the other add kinds.
+
+## Authoring API references
+
+Read only the reference relevant to the requested change. These examples describe the template's public APIs; check the installed package's TypeScript declarations when an exact option or signature matters.
+
+- [Application configuration and environments](references/config-environments.md)
+- [Functions, services, events, and errors](references/domain-apis.md)
+- [HTTP routes and request policy](references/http-apis.md)
+- [Streaming responses](references/streaming-apis.md)
+- [Tasks and jobs](references/jobs-apis.md)
+- [Agents, tools, and prompts](references/agent-apis.md)
+- [Database, auth, cache, and storage](references/data-apis.md)
+- [Realtime channels](references/realtime-apis.md)
+- [Observability and tracing](references/observability-apis.md)
+- [Testing functions, routes, and providers](references/testing-apis.md)
+
+## Working conventions
+
+- Generic domain services own callable functions and public event contracts. Other domains and routes should import a service's public members through its `service.ts`.
+- A service route maps HTTP methods to existing public callable members. A raw route is a standalone handler. The CLI will not overwrite an existing route file.
+- Database and auth are singletons under `src/services/database` and `src/services/auth`; extend an existing one instead of creating another. Auth may create a database baseline if none exists. Scaffolding does not run migrations, create secrets, or provision cloud resources.
+- Preserve existing application configuration, environment fields, service members, routes, and user changes when specializing generated files.
+
+## 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.

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

@@ -0,0 +1,59 @@
+# Agents, tools, and prompts
+
+| API                                             | Import               | Role                                 |
+| ----------------------------------------------- | -------------------- | ------------------------------------ |
+| `defineAgent`, `defineGraph`, `defineGraphNode` | `@relkit/app/agents` | Model-driven agent or explicit graph |
+| `defineTool`                                    | `@relkit/app/tools`  | Policy-controlled view of a function |
+| `definePrompt`                                  | `@relkit/app`        | Reusable instructions                |
+| `z`                                             | `@relkit/app/schema` | Agent and tool schemas               |
+
+## `defineAgent`
+
+Use `defineAgent` when a model should choose among tools. The agent template provides an executable offline LangChain model example. This shortened form uses the same public options:
+
+```ts
+import { defineAgent } from "@relkit/app/agents";
+import { z } from "@relkit/app/schema";
+import { FakeToolCallingModel } from "langchain";
+import lookup from "@app/services/hello/tools/lookup.tool.js";
+export default defineAgent({
+  id: "hello.assistant",
+  input: z.object({ message: z.string().min(1) }),
+  output: z.object({ answer: z.string() }),
+  model: new FakeToolCallingModel({
+    toolCalls: [[{ name: "relkit_output", args: { value: { answer: "Hello!" } }, id: "output-1" }]],
+  }),
+  instructions: "Answer greeting questions with the available tools.",
+  tools: [lookup],
+  limits: { maxSteps: 4, maxToolCalls: 4, timeoutMs: 10_000 },
+});
+```
+
+Other generated projects may need a native model package and application-owned provider configuration. `limits` requires positive `maxSteps`, `maxToolCalls`, and `timeoutMs`. `instructions` can be text or a `definePrompt` descriptor. A model can call only tools listed in the agent's `tools` array. A fixed sequence can be a function; a stateful explicit workflow can use `defineGraph` and `defineGraphNode`.
+
+## `defineTool` and `definePrompt`
+
+A RELKIT tool wraps a callable function without duplicating its schemas:
+
+```ts
+import { defineTool } from "@relkit/app/tools";
+import lookup from "@app/services/orders/functions/lookup.function.js";
+export default defineTool({
+  id: "orders.lookup",
+  target: lookup,
+  description: "Look up an order by ID",
+  sideEffect: "read",
+  approval: "never",
+  timeoutMs: 2_000,
+});
+```
+
+```ts
+import { definePrompt } from "@relkit/app";
+export default definePrompt("Answer using the available tools.", {
+  id: "hello.assistant-instructions",
+});
+```
+
+`lookup.asTool({ ... })` is the alternate tool form. Choose accurate `sideEffect` (`none`, `read`, `write`, or `external`) and `approval` (`never`, `on-write`, or `always`) policies. Tools are available to MCP by default; set `mcp: false` when a tool should remain inside the app. Permission checks belong in application logic.
+If a browser client needs an agent, configure its explicit `client` contract. Keep provider credentials and native model instances on the server. A typed agent run uses a stable thread ID; resume the same thread instead of creating a replacement run.

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

@@ -0,0 +1,63 @@
+# CLI commands in a generated project
+
+These examples use the local binary through `bun run relkit`. The installed CLI's `--help` is authoritative if its version differs from the template.
+
+## Service and HTTP scaffolding
+
+| Goal                                           | Command                                                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| Create a domain with a public example function | `bun run relkit add service Billing`                                                           |
+| Select extra domain artifacts                  | `bun run relkit add service Billing --include function --include error`                        |
+| Create the full domain bundle                  | `bun run relkit add service Billing --full`                                                    |
+| Add a public callable function                 | `bun run relkit add function "Send Receipt" --service billing`                                 |
+| Add a standalone GET handler                   | `bun run relkit add route '/status' --mode route`                                              |
+| Map an existing public member to HTTP          | `bun run relkit add route '/billing' --mode service-route --service billing --map GET=example` |
+
+`--include` is repeatable and exclusive with `--full`. `--service` selects an existing generic domain; `--create-service` creates it while adding an artifact. Use `--internal` on a function or event that should stay out of the public service API. A service route needs one or more `--map METHOD=member` values in noninteractive use; the member must be a public callable function. Quote paths containing `*` or `?`.
+
+## Database and auth
+
+| Goal                                         | Command                                                                   |
+| -------------------------------------------- | ------------------------------------------------------------------------- |
+| Scaffold a SQLite Drizzle service            | `bun run relkit add database --orm drizzle --dialect sqlite`              |
+| Scaffold Better Auth and its catch-all route | `bun run relkit add auth --adapter better-auth --database-dialect sqlite` |
+
+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.
+
+## Other add kinds
+
+Run `bun run relkit add <kind> --help` for each kind's flags and requirements:
+
+| Area            | Kinds                                    |
+| --------------- | ---------------------------------------- |
+| Domain behavior | `function`, `task`, `error`, `constants` |
+| Events and work | `event`, `event-function`, `job`         |
+| Providers       | `cache`, `bucket`                        |
+| AI              | `tool`, `prompt`, `agent`                |
+| HTTP            | `middleware`, `transform`, `route`       |
+
+For example, jobs need a target task, tools need an existing or newly created function, and agents need a prompt or inline instructions. Check the existing service and profile before selecting one. `--no-install` skips installing newly required packages and may skip verification; `--project-root <directory>` targets another app. `bun run relkit --json add ...` disables prompts and emits structured results for automation.
+
+There is no `relkit add channel` or `relkit add observability` kind. Author channels with `defineChannel` and configure observability in `defineApp({ telemetry })`; see the [realtime](realtime-apis.md) and [observability](observability-apis.md) references.
+
+For streaming responses, scaffold a function and route, then edit the function's output to `streamOf(itemSchema)` and the route's `stream` option; see the [streaming reference](streaming-apis.md).
+
+## Inspect and run the app
+
+| Goal                                    | Command                             |
+| --------------------------------------- | ----------------------------------- |
+| Validate the application graph          | `bun run check`                     |
+| Typecheck and test                      | `bun run typecheck`, `bun run test` |
+| Start app, inspector, and API reference | `bun run dev`                       |
+| Inspect the graph                       | `bun run relkit graph print`        |
+| Inspect environment value status        | `bun run relkit env list`           |
+| Validate active environment values      | `bun run relkit env check`          |
+| Explain one environment declaration     | `bun run relkit env explain NAME`   |
+| Render a safe environment example       | `bun run relkit env example`        |
+| Check local prerequisites               | `bun run relkit doctor`             |
+| Inspect local service status            | `bun run relkit local status`       |
+| Build or start a built app              | `bun run build`, `bun run start`    |
+
+Use `bun run relkit --help` to discover additional `graph`, `env`, `local`, `jobs`, `client`, and deployment commands. Start Docker-backed local services with `bun run relkit local up --detach` only when the app actually declares and needs them. Deployment commands require a configured deployment target.
+
+For optional flat-to-grouped migration, use `bun run relkit migrate layout` for preview, `--write` for validated publication, and `--rollback <receipt>` for guarded restoration. See [layout migration](layout-migration.md). After `--no-install`, install dependencies and run `bun run relkit dev --prepare` before evaluating prepared-start readiness.

package/dist/templates/default/v1/fullstack/.agents/skills/relkit/references/config-environments.md

@@ -0,0 +1,96 @@
+# Application configuration and environments
+
+A generated application has two authoring files at its root: `relkit.config.ts` declares topology and runtime policy with `defineApp`, and `src/platform/env.ts` declares application environment values with `defineEnv`. Extend these existing files rather than creating a second application or environment contract.
+
+## `defineEnv`: values for handlers
+
+In `src/platform/env.ts`:
+
+```ts
+import { defineEnv, env } from "@relkit/app/config";
+
+export default defineEnv({
+  LOG_LEVEL: env.literal("debug", "info", "warn", "error").default("info"),
+  DATABASE_PATH: env.string().default(".relkit/app.sqlite"),
+  BETTER_AUTH_SECRET: env.secret().requiredIn("production"),
+  PUBLIC_ORIGIN: env.url().optional(),
+});
+```
+
+Builders include `string`, `secret`, `number`, `boolean`, `port`, `url`, `json`, and `literal(...)`. Use `.default(value)` only for intentional safe defaults, `.optional()` for absent values, `.requiredIn("production")` for environment-specific requirements, and `.description(text)` or `.example(value)` for safe metadata. A URL field resolves to a `URL`, a number field to a number, and a Boolean field to a boolean. Do not declare `PORT` or `RELKIT_ENV`; RELKIT reserves them.
+
+Pass the definition into `defineApp({ env })`. Functions read the resolved, typed values through `context.env`:
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+export default defineFunction({
+  input: z.object({}),
+  output: z.object({ level: z.string() }),
+  handler: async (_input, context) => ({ level: context.env.LOG_LEVEL }),
+});
+```
+
+Mark credentials with `env.secret()`; keep actual values outside source control. Secret metadata enables redaction in generated output, diagnostics, telemetry, and Inspector data. Avoid placeholder production secrets or logging resolved secrets.
+
+## `defineApp`: topology and policy
+
+In `relkit.config.ts`, the baseline application contains the environment contract, telemetry redaction, backend settings, and Inspector settings:
+
+```ts
+import { defineApp } from "@relkit/app/config";
+import env from "@app/platform/env.js";
+
+export default defineApp({
+  env,
+  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
+  server: { port: 3000, maxBodyBytes: 1_048_576 },
+  inspector: { port: 3210 },
+});
+```
+
+`defineApp` also accepts `id`, `defaults`, `deployment`, and provider capabilities `bucket`, `cache`, `jobs`, `event`, `model`, `realtime`, and `"agent-state"`. A capability can have one `default` profile or a named profile map. `defaults.<capability>` must name a configured profile. The `jobs` key is the public spelling for the job provider. Add only providers the app uses; the base template has none. Public creation currently certifies only the minimal starter with examples, no jobs, no cloud, and no deployment. API, agent, fullstack, jobs, and AWS/Pulumi creation tuples are internal candidates and must remain rejected until their exact release evidence is certified. Configure an existing app's optional integrations only when the installed version supports them and the task requires them.
+
+For a one-machine realtime provider and a named Docker-backed cache profile, the complete configuration shape is:
+
+```ts
+import { defineApp, env as binding } from "@relkit/app/config";
+import { docker } from "@relkit/docker";
+import { localRealtime } from "@relkit/local";
+import { redis } from "@relkit/redis";
+import env from "@app/platform/env.js";
+
+export default defineApp({
+  env,
+  cache: {
+    requests: docker(redis({ url: binding.secret("REQUESTS_REDIS_URL") })),
+  },
+  realtime: localRealtime(),
+  defaults: { cache: "requests", realtime: "default" },
+  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
+  server: { port: 3000, maxBodyBytes: 1_048_576 },
+  inspector: { port: 3210 },
+});
+```
+
+Merge only the needed capabilities into the existing `defineApp`, preserving its other settings. Install the optional integration packages before importing them. `binding.secret("REQUESTS_REDIS_URL")` is a value-free provider binding; it is not a `context.env` field unless `defineEnv` declares that name too. Stable topology belongs in source; machine, stack, and secret values belong in environment bindings.
+
+Platform fragments may explicitly export server, Inspector, telemetry, deployment, or provider settings and be imported by `relkit.config.ts`. Unimported files are not autoloaded. Keep provider acquisition in supported lazy factories and compose one `defineApp`.
+
+CLI `--environment` selects provider configuration; `RELKIT_ENV` selects the application environment. `.env` and `.env.local` supply runtime values according to existing CLI loading; `.env.example` is informational and is not loaded as credentials.
+
+## Inspect and verify environment values
+
+From the generated project root:
+
+```sh
+bun run relkit env check
+bun run relkit env list
+bun run relkit env explain BETTER_AUTH_SECRET
+bun run relkit env example
+```
+
+`check` validates active values, `list` shows presence/status without printing secrets, `explain` describes one declaration, and `example` renders a safe template. `env example --write --path .env.example` writes it when requested. Use `--environment <name>` with environment-aware CLI commands to select provider configuration; it does not define an application env field. Run `bun run check` and `bun run typecheck` after changing the contract, then exercise the affected runtime path. Run `bun run relkit local status` before using Docker-backed providers.
+
+For observability settings, see [Observability and tracing](observability-apis.md); for realtime provider behavior, see [Realtime channels](realtime-apis.md).

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

@@ -0,0 +1,74 @@
+# Database, authentication, cache, and storage
+
+For the full `defineApp`, `defineEnv`, provider profile, and environment binding workflow, read [Application configuration and environments](config-environments.md).
+
+The database and auth integrations are specialized services, separate from `defineService` domain maps. `relkit add database` creates the Drizzle baseline in `src/services/database`; `relkit add auth` creates `src/services/auth` and its recognized `ALL` handler route. There should be one of each. Extend an existing one while preserving schema exports, environment fields, and routes.
+
+## `defineEnv` and `defineDrizzleService`
+
+```ts
+import { defineEnv, env as envFactory } from "@relkit/app/config";
+
+export default defineEnv({
+  DATABASE_PATH: envFactory.string().default(".relkit/app.sqlite"),
+  BETTER_AUTH_SECRET: envFactory.secret(),
+});
+```
+
+```ts
+import { Database } from "bun:sqlite";
+import { defineDrizzleService } from "@relkit/drizzle";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import * as schema from "./schema/index.js";
+
+export default defineDrizzleService({
+  schema,
+  client: ({ env }) => drizzle({ client: new Database(env.DATABASE_PATH, { create: true }) }),
+  dispose: (database) => database.$client.close(),
+});
+```
+
+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`.
+
+## `defineBetterAuthService`
+
+```ts
+import { defineBetterAuthService } from "@relkit/better-auth";
+
+export default defineBetterAuthService({
+  baseURL: process.env.BETTER_AUTH_URL ?? "http://127.0.0.1:3000",
+  emailAndPassword: { enabled: true },
+});
+```
+
+Better Auth uses the same Drizzle connection and needs its tables in that schema. Mount `auth.handler` directly with `export const ALL = defineRoute({ handler: auth.handler })` under the auth base path. Supply a stable server-side `BETTER_AUTH_SECRET` and correct public `BETTER_AUTH_URL`; the scaffold only adds environment examples. Protect application routes and enforce ownership separately from signing in.
+
+## `defineCache` and `defineBucket`
+
+```ts
+import { defineCache } from "@relkit/app/cache";
+import { z } from "@relkit/app/schema";
+
+export default defineCache({
+  id: "orders.prices",
+  profile: "requests",
+  key: z.object({ sku: z.string() }),
+  value: z.number().int().nonnegative(),
+  defaultTtlMs: 60_000,
+  maxTtlMs: 300_000,
+});
+```
+
+```ts
+import { defineBucket } from "@relkit/app/buckets";
+
+export default defineBucket({
+  id: "assets.objects",
+  profile: "assets",
+  visibility: "private",
+  maxObjectBytes: 5_000_000,
+  allowedContentTypes: ["application/json", "image/*"],
+});
+```
+
+Configure compatible profiles in `relkit.config.ts` and declare each resource in a function's `dependencies` before using its checked context client. A profile selects a provider; the descriptor does not create Redis, S3, or credentials. Use `bun run relkit local status` to inspect Docker-backed resources.