create-relkit 0.7.2 → 0.7.6

package/dist/templates/default/v1/tasks/.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/tasks/.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/tasks/.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.

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

@@ -0,0 +1,92 @@
+# Functions, services, events, and errors
+
+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.
+
+## `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:
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+const greet = defineFunction({
+  id: "hello.greet",
+  input: z.object({ name: z.string().min(1) }),
+  output: z.object({ message: z.string() }),
+  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
+});
+
+export default greet;
+```
+
+Expose selected functions from `src/services/<domain>/service.ts`:
+
+```ts
+import { defineService } from "@relkit/app/services";
+import greet from "@app/services/hello/functions/greet.function.js";
+
+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.
+
+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`
+
+Declare an event payload in `src/services/<domain>/events/*.event.ts`:
+
+```ts
+import { defineEvent } from "@relkit/app/events";
+import { z } from "@relkit/app/schema";
+
+const orderCreated = defineEvent({
+  id: "orders.created",
+  version: 1,
+  input: z.object({ orderId: z.string() }),
+});
+
+declare global {
+  namespace Relkit {
+    interface EventRegistry {
+      readonly "orders.created": typeof orderCreated;
+    }
+  }
+}
+
+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:
+
+```ts
+import { defineEventFunction } from "@relkit/app/events";
+
+export default defineEventFunction({
+  id: "orders.confirmation",
+  event: "orders.created",
+  handler: async ({ orderId }, context) => {
+    context.log.info("Order created", { orderId });
+  },
+});
+```
+
+## `defineError`
+
+```ts
+import { defineError } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+export default defineError({
+  id: "orders.not-found",
+  data: z.object({ orderId: z.string() }),
+  message: ({ orderId }) => `Order ${orderId} was not found`,
+  http: { status: 404 },
+  retry: { kind: "later", afterMs: 1_000 },
+});
+```
+
+Declare only expected failures callers should handle on a function. Use the route layer for HTTP-specific request mapping and middleware.

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

@@ -0,0 +1,70 @@
+# HTTP routes and request policy
+
+Routes live under `src/routes/**/route.ts`. The file path supplies the URL, and named exports supply methods. Import route APIs from `@relkit/app/routes`. Use a public service function as the target for ordinary application endpoints.
+
+## `defineRoute`: one function-backed method
+
+In `src/routes/hello/route.ts`, this exposes the service's public `hello` function as `GET /hello`:
+
+```ts
+import { defineRoute } from "@relkit/app/routes";
+import hello from "@app/services/hello/service.js";
+
+export const GET = defineRoute({ target: hello.hello });
+```
+
+A function-backed route can also set `successStatus`, `request`, `responses`, `rateLimit`, and `timeoutMs` when needed. The target must be a public callable function; jobs, events, agents, and tools are not route targets. Ordinary JSON request and response schemas are inferred from the target unless you supply explicit mapping.
+
+## `defineRoute`: raw Web handler
+
+Use `handler` instead of `target` for a standalone Web `Request`/`Response` handler:
+
+```ts
+import { defineRoute } from "@relkit/app/routes";
+
+export const GET = defineRoute({
+  handler: async () => Response.json({ ok: true }),
+});
+```
+
+A raw handler has a generic OpenAPI response. The recognized Better Auth mount also uses a raw route:
+
+```ts
+import { defineRoute } from "@relkit/app/routes";
+import auth from "@app/services/auth/service.js";
+
+export const ALL = defineRoute({ handler: auth.handler });
+```
+
+## `defineServiceRoutes`: methods on one service
+
+```ts
+import { defineServiceRoutes } from "@relkit/app/routes";
+import orders from "@app/services/orders/service.js";
+
+export const { GET, POST } = defineServiceRoutes(orders, {
+  GET: "listOrders",
+  POST: { member: "createOrder", successStatus: 201 },
+});
+```
+
+`GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, and `OPTIONS` are supported service-route exports. `ALL` is for raw handlers. Do not add a `path` or `method` option to `defineRoute`; the filesystem and export determine both. The CLI can scaffold either form through `add route --mode route` or `--mode service-route`. It will not overwrite an existing route file; edit it directly to add a method.
+
+Use `request` mapping only when inference cannot express headers, cookies, names, or nesting; it replaces the inferred mapping. Use `responses` only when you need an explicit response contract. `defineMiddleware(path, handler)` is for HTTP policy, and `defineTransform({ schema })` is for request transforms:
+
+```ts
+import { defineMiddleware } from "@relkit/app/routes";
+
+export default defineMiddleware("/orders/*", async (_context, next) => {
+  await next();
+});
+```
+
+```ts
+import { defineTransform } from "@relkit/app/routes";
+import { z } from "@relkit/app/schema";
+
+export default defineTransform({ schema: z.string() });
+```
+
+Application authorization must be enforced in the relevant route or function logic. After changing a route, run `bun run check` and `bun run typecheck`, exercise the HTTP endpoint, and inspect `/_relkit/v1/api-reference` while `bun run dev` is running.

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

@@ -0,0 +1,49 @@
+# Tasks and jobs
+
+Use a task for work that must outlive its initiating request; a function remains a request- or event-scoped operation.
+
+## `defineTask`
+
+```ts
+import { defineTask } from "@relkit/app/tasks";
+import { z } from "@relkit/app/schema";
+
+export default defineTask({
+  id: "orders.export-orders",
+  version: "1",
+  execution: "durable",
+  input: z.object({ orderIds: z.array(z.string()) }),
+  output: z.object({ exported: z.number().int().nonnegative() }),
+  progress: z.object({ completed: z.number().int().nonnegative() }),
+  handler: async ({ orderIds }, context) => {
+    await context.progress.emit({ completed: orderIds.length });
+    return { exported: orderIds.length };
+  },
+});
+```
+
+## `defineJob`
+
+Bind the task to a public job name and an explicit client policy in `src/services/orders/jobs/export-orders.job.ts`:
+
+```ts
+import { defineJob } from "@relkit/app/jobs";
+import exportOrders from "@app/services/orders/tasks/export-orders.task.js";
+
+export default defineJob({
+  id: "orders.export-orders-job",
+  name: "exportOrders",
+  task: exportOrders,
+  client: {
+    public: true,
+    operations: ["trigger", "get", "list", "watch"],
+    fields: ["status", "progress", "output"],
+  },
+});
+```
+
+Expose the task and job through the owning service's `tasks` and `jobs` maps. Keep the task ID and version stable; change the version for an intentional incompatible task contract. Make side effects idempotent because work may retry or resume.
+
+The app's `relkit.config.ts` selects a compatible jobs provider. Run `bun run relkit jobs capabilities` to inspect its actual guarantees; a durable task needs a binding that supports durable execution. `relkit add task` and `relkit add job --target <task-id>` scaffold the pair without running a worker or provisioning a provider.
+
+A trigger admits work and returns a run handle, not the task's output. Keep its `runId` and `operationId`, then read or watch the run; a typed client alone does not authorize a caller. A raw HTTP trigger can return the accepted handle with status `202`. Use `bun run relkit local status` to inspect local provider state before exercising a Docker-backed job.

package/dist/templates/default/v1/tasks/.agents/skills/relkit/references/layout-migration.md

@@ -0,0 +1,35 @@
+# Optional flat layout migration
+
+Flat `src/<name>/service.ts` applications remain supported. Migrate only when grouped placement helps the app. Preview from the application root:
+
+```sh
+bun run relkit migrate layout
+bun run relkit --json migrate layout
+```
+
+The deterministic plan moves complete service roots to `src/services/<name>`, including helpers and assets. It reports import, test, tooling, documentation, and local guidance rewrites, conflicts, and references needing manual action. Preview leaves authored files, lockfiles, generated output, persistent state, migration history, and credentials unchanged.
+
+Stop the app's active development session and resolve touched tracked changes, occupied destinations, mixed boundaries, symlinks, and ambiguous/computed references before applying:
+
+```sh
+bun run relkit migrate layout --write
+```
+
+Write stages the candidate with installed dependencies and requires baseline/candidate check, typecheck, logical graph, and offline deployment compatibility before publication. It does not install packages, run database migrations or seeds, provision providers, or edit global skills. Publication is coordinated across files; the restricted local receipt retains exact before/after bytes and permissions for failure or crash recovery. Keep that receipt private.
+
+Rollback with the exact path returned by the write result:
+
+```sh
+bun run relkit migrate layout --rollback .relkit/migrations/RECEIPT_ID/receipt.json
+```
+
+Rollback refuses later edits or occupied original locations instead of overwriting them. Recovery conflicts preserve user bytes and require inspection of the retained receipt. Successful migration or restoration needs fresh preparation:
+
+```sh
+bun run check
+bun run typecheck
+bun run relkit dev --prepare
+bun run dev
+```
+
+Compare actual application responses and durable runs after the move. Logical service/function/task/job/channel/agent IDs and versions remain unchanged; diagnostic and editor paths point at their real grouped sources.

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

@@ -0,0 +1,53 @@
+# Observability and tracing
+
+RELKIT records HTTP requests and invocation spans automatically. Use `context.log` for structured application records and `context.trace` for application work inside an existing function that needs more detail.
+
+## Log and trace inside a function
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+
+export default defineFunction({
+  id: "orders.total",
+  input: z.object({ quantity: z.number().int().positive() }),
+  output: z.object({ totalCents: z.number().int().nonnegative() }),
+  handler: async ({ quantity }, context) => {
+    const totalCents = await context.trace.span(
+      "pricing.calculate",
+      { attributes: { "pricing.strategy": "catalog" } },
+      async () => quantity * 1_000,
+    );
+    context.trace.event("pricing.calculated", { "pricing.total_cents": totalCents });
+    context.trace.setAttributes({ "pricing.quantity": quantity });
+    context.log.info("orders.total.calculated", { quantity, totalCents });
+    return { totalCents };
+  },
+});
+```
+
+`span(name, callback)` creates an internal child span; `span(name, { attributes, kind }, callback)` adds attributes and an `internal` or `client` kind. `event(name, attributes?)` adds an event to the active span, and `setAttributes` annotates it. RELKIT ends child spans on success or failure. Attribute values must be strings, finite numbers, or booleans. Do not log secrets or put payloads or random IDs in span attributes.
+
+## Configure capture and export
+
+Edit the existing `relkit.config.ts` and preserve its environment and provider 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 },
+    localRetention: { maxRecords: 2_000, maxAgeMs: 3_600_000, maxBytes: 16_777_216 },
+    exportSampling: { traceRate: 0.25, minimumLogLevel: "info" },
+  },
+  server: { port: 3000 },
+  inspector: { port: 3210 },
+});
+```
+
+The template already supplies redaction. `localRetention` bounds development history; `exportSampling` controls remote export independently of local capture. Add named Sentry or OTLP exporters only when those integrations and their secret environment bindings are configured. Redact before storage or export. No `relkit add observability` kind exists; configure `telemetry` in `defineApp`.
+
+Run `bun run dev`, make one identifiable HTTP request, then inspect Requests, Traces, and Logs in the Inspector. Use `bun run dev -- --verbose` for DEBUG terminal output or `--json` for structured terminal records. Development history is stored in `.relkit/observability/observability.duckdb`; this is diagnostic history, not business storage.

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

@@ -0,0 +1,98 @@
+# Realtime channels
+
+Use a channel to notify connected clients about a change. Keep the authoritative state in a route or database query; use channel events to refresh or update that state. Application events deliver backend work, while channels deliver live client updates.
+
+## `defineChannel`
+
+Create `src/services/announcements/channels/announcements.channel.ts`:
+
+```ts
+import { defineChannel } from "@relkit/app/realtime";
+import { z } from "@relkit/app/schema";
+
+const announcements = defineChannel({
+  id: "announcements.feed",
+  params: z.object({}),
+  events: { posted: z.object({ message: z.string(), postedAt: z.string() }) },
+  client: { public: true },
+  replay: { retentionMs: 300_000, maxEvents: 1_000 },
+});
+
+export default announcements;
+```
+
+`params` selects a partition, `events` validates named payloads, and `client` controls browser exposure. Omit `client` for backend-only channels. Use `client: { authorize: async (params, context) => ... }` for protected partitions and verify access to the specific resource, not merely that a session exists. `presence: "count"` adds connection counts. A channel with no events must declare presence.
+
+## Publish and subscribe
+
+After the application change succeeds, publish one validated event from a backend function:
+
+```ts
+import { defineFunction } from "@relkit/app/functions";
+import { z } from "@relkit/app/schema";
+import announcements from "@app/services/announcements/channels/announcements.channel.js";
+
+export default defineFunction({
+  id: "announcements.post",
+  input: z.object({ message: z.string().min(1) }),
+  output: z.object({ accepted: z.literal(true) }),
+  handler: async ({ message }) => {
+    await announcements.trigger({}, "posted", {
+      message,
+      postedAt: new Date().toISOString(),
+    });
+    return { accepted: true as const };
+  },
+});
+```
+
+The `trigger()` receipt confirms the provider accepted the append; it does not prove delivery to every browser. If a database write and publication must be atomic, use an outbox in the database transaction. A retryable publish can pass a RELKIT-issued `idempotencyKey` as the fourth argument.
+
+In a React client with `@relkit/client`, subscribe using the generated channel registry:
+
+```tsx
+"use client";
+
+import { useChannel, useRoute } from "@relkit/client/react";
+
+export default function Announcements() {
+  const announcements = useRoute("GET /announcements", { input: {} });
+  const channel = useChannel("announcements.feed", {
+    params: {},
+    on: { posted: () => void announcements.refetch() },
+    onCaughtUp: async () => {
+      await announcements.refetch();
+    },
+    onGap: async () => {
+      await announcements.refetch();
+    },
+  });
+
+  return <p>Channel: {channel.status}</p>;
+}
+```
+
+Load authoritative state through a route before relying on updates. `onGap` must restore it when replay cannot bridge a disconnect. `channel.status` and `channel.caughtUp` report connection and recovery state. `useRealtime()` is the lower-level subscription manager; a channel descriptor's `getPresence(params)` reads presence when declared.
+
+## Provider and verification
+
+Configure a compatible `realtime` provider and `defaults.realtime` in `relkit.config.ts`. For a one-machine app with `@relkit/local` installed, the relevant configuration is:
+
+```ts
+import { defineApp } from "@relkit/app/config";
+import { localRealtime } from "@relkit/local";
+import env from "@app/platform/env.js";
+
+export default defineApp({
+  env,
+  realtime: localRealtime(),
+  defaults: { realtime: "default" },
+  telemetry: { redaction: { mode: "development-redacted", maxBytes: 65_536 } },
+  server: { port: 3000 },
+  inspector: { port: 3210 },
+});
+```
+
+Merge these fields into an existing `defineApp` while preserving its other providers and settings. Redis supports fanout across application instances. Provider storage, retention, and Redis persistence determine recovery guarantees. Run `bun run check`, `bun run typecheck`, then test publication, browser subscription, reconnect, and gap recovery. Inspect channels in the Inspector while `bun run dev` is running.
+
+The current `relkit add` kinds do not include `channel`. Create the descriptor and provider configuration in the app source.