bunderstack 0.17.0-beta.8 → 0.17.0

package/dist/cli-skills.d.ts

@@ -0,0 +1,16 @@
+/** The skills this package ships, copied from `.agents/skills` at build time. */
+export declare const SHIPPED_SKILLS: readonly ["creating-bunderstack-apps", "migrating-to-bunderstack"];
+export type SkillsOptions = {
+    /** Project root the skills are installed into. */
+    cwd: string;
+    /** Destination, relative to `cwd`. */
+    directory?: string;
+    /** Report drift instead of writing. Exits non-zero when anything differs. */
+    check?: boolean;
+};
+export type SkillsIo = {
+    stdout(message: string): void;
+    stderr(message: string): void;
+};
+export declare function installSkills(options: SkillsOptions, io: SkillsIo): Promise<number>;
+//# sourceMappingURL=cli-skills.d.ts.map

package/dist/cli-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-skills.d.ts","sourceRoot":"","sources":["../src/cli-skills.ts"],"names":[],"mappings":"AAIA,iFAAiF;AACjF,eAAO,MAAM,cAAc,oEAGjB,CAAA;AAwBV,MAAM,MAAM,aAAa,GAAG;IAC1B,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,sCAAsC;IACtC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB,CAAA;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAuDD,wBAAsB,aAAa,CACjC,OAAO,EAAE,aAAa,EACtB,EAAE,EAAE,QAAQ,GACX,OAAO,CAAC,MAAM,CAAC,CAiDjB"}

package/dist/cli-skills.js

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { cp, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The skills this package ships, copied from `.agents/skills` at build time. */
+export const SHIPPED_SKILLS = [
+    'creating-bunderstack-apps',
+    'migrating-to-bunderstack',
+];
+const MARKER_START = '<!-- bunderstack:skills -->';
+const MARKER_END = '<!-- /bunderstack:skills -->';
+/**
+ * Agents read AGENTS.md before they search for anything, so the pointer is
+ * what actually gets the skills into context. The markers let a later
+ * `bunderstack skills` run replace the block without touching the rest.
+ */
+function agentsBlock(directory) {
+    return `${MARKER_START}
+## Bunderstack
+
+This project uses Bunderstack. Before changing the server API, access rules,
+jobs, storage, or realtime, read \`${directory}/creating-bunderstack-apps/SKILL.md\`.
+When replacing existing infrastructure, read
+\`${directory}/migrating-to-bunderstack/SKILL.md\` instead.
+
+\`node_modules/bunderstack/llms.txt\` is a dense plain-text reference for the
+whole framework.
+${MARKER_END}`;
+}
+/** Where this build keeps its copy of the skills. */
+function packagedSkillsDir() {
+    return join(new URL('..', import.meta.url).pathname, 'skills');
+}
+async function filesUnder(dir) {
+    const entries = await readdir(dir, { withFileTypes: true, recursive: true });
+    return entries
+        .filter((entry) => entry.isFile())
+        .map((entry) => join(entry.parentPath, entry.name));
+}
+async function differs(from, to) {
+    if (!existsSync(to))
+        return true;
+    const sources = await filesUnder(from);
+    for (const source of sources) {
+        const target = join(to, source.slice(from.length + 1));
+        if (!existsSync(target))
+            return true;
+        if ((await readFile(source, 'utf8')) !== (await readFile(target, 'utf8'))) {
+            return true;
+        }
+    }
+    return false;
+}
+async function writeAgentsPointer(cwd, directory) {
+    const path = join(cwd, 'AGENTS.md');
+    const block = agentsBlock(directory);
+    if (!existsSync(path)) {
+        await writeFile(path, `# Agent guide\n\n${block}\n`);
+        return 'created';
+    }
+    const current = await readFile(path, 'utf8');
+    const start = current.indexOf(MARKER_START);
+    const end = current.indexOf(MARKER_END);
+    if (start !== -1 && end !== -1) {
+        const replaced = current.slice(0, start) + block + current.slice(end + MARKER_END.length);
+        if (replaced === current)
+            return 'current';
+        await writeFile(path, replaced);
+        return 'updated';
+    }
+    await writeFile(path, `${current.trimEnd()}\n\n${block}\n`);
+    return 'updated';
+}
+export async function installSkills(options, io) {
+    const source = packagedSkillsDir();
+    if (!existsSync(source)) {
+        io.stderr('[bunderstack] this build ships no skills; reinstall the package or run bun run build');
+        return 1;
+    }
+    const directory = options.directory ?? '.agents/skills';
+    const destination = join(options.cwd, directory);
+    const stale = [];
+    for (const skill of SHIPPED_SKILLS) {
+        const from = join(source, skill);
+        const to = join(destination, skill);
+        if (!(await differs(from, to)))
+            continue;
+        stale.push(skill);
+        if (options.check)
+            continue;
+        await mkdir(destination, { recursive: true });
+        await cp(from, to, { recursive: true });
+    }
+    if (options.check) {
+        const pointer = await readFile(join(options.cwd, 'AGENTS.md'), 'utf8').catch(() => '');
+        const pointerStale = !pointer.includes(MARKER_START);
+        if (stale.length === 0 && !pointerStale) {
+            io.stdout(`${directory} is current`);
+            return 0;
+        }
+        for (const skill of stale) {
+            io.stderr(`[bunderstack] ${directory}/${skill} is missing or outdated`);
+        }
+        if (pointerStale)
+            io.stderr('[bunderstack] AGENTS.md has no Bunderstack block');
+        io.stderr('[bunderstack] run: bunx bunderstack skills');
+        return 1;
+    }
+    const pointer = await writeAgentsPointer(options.cwd, directory);
+    io.stdout(stale.length === 0
+        ? `${directory} is current`
+        : `Installed ${stale.length} skill(s) into ${directory}: ${stale.join(', ')}`);
+    if (pointer !== 'current')
+        io.stdout(`AGENTS.md ${pointer}`);
+    return 0;
+}
+//# sourceMappingURL=cli-skills.js.map

package/dist/cli-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-skills.js","sourceRoot":"","sources":["../src/cli-skills.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAEL,iBAAiB,EAElB,MAAM,uBAAuB,CAAA;AAE9B,MAAM,MAAM,KAAK,GAAG;IAClB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAOD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,KAAK,EACT,QAAQ,GAAE,OAAO,iBAAqC,GACrD,OAAO,CAAC,MAAM,CAAC,CA4DjB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAEL,iBAAiB,EAElB,MAAM,uBAAuB,CAAA;AAG9B,MAAM,MAAM,KAAK,GAAG;IAClB,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IAC7B,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B,CAAA;AAcD,wBAAsB,MAAM,CAC1B,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,EAAE,KAAK,EACT,QAAQ,GAAE,OAAO,iBAAqC,GACrD,OAAO,CAAC,MAAM,CAAC,CAmFjB"}

package/dist/cli.js

@@ -1,9 +1,17 @@
 #!/usr/bin/env bun
 import { BlueprintCheckError, generateBlueprint, } from './blueprint-generator.js';
-const help = `Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]
+import { installSkills } from './cli-skills.js';
+const help = `Usage:
+  bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]
+  bunderstack skills [--dir <path>] [--check]
 
-Generate a committed deployment declaration for a TanStack Start application.
-Entry precedence: --entry, package.json#bunderstack.entry, src/bunderstack.ts.`;
+blueprint  Generate a committed deployment declaration for a TanStack Start
+           application. Entry precedence: --entry,
+           package.json#bunderstack.entry, src/bunderstack.ts.
+
+skills     Install the Bunderstack agent skills that match this version into
+           .agents/skills, and point AGENTS.md at them so an agent loads them
+           before touching the API. --check reports drift without writing.`;
 export async function runCli(args, io, generate = generateBlueprint) {
     if (args[0] === '--help' || args[0] === '-h') {
         io.stdout(help);
@@ -13,8 +21,32 @@ export async function runCli(args, io, generate = generateBlueprint) {
         io.stdout((await Bun.file(new URL('../package.json', import.meta.url)).json()).version);
         return 0;
     }
+    if (args[0] === 'skills') {
+        const options = {
+            cwd: process.cwd(),
+        };
+        for (let index = 1; index < args.length; index++) {
+            const argument = args[index];
+            if (argument === '--check') {
+                options.check = true;
+                continue;
+            }
+            if (argument === '--dir') {
+                const value = args[++index];
+                if (!value || value.startsWith('--')) {
+                    io.stderr('[bunderstack] missing value for --dir');
+                    return 2;
+                }
+                options.directory = value;
+                continue;
+            }
+            io.stderr(`[bunderstack] unknown option: ${argument}`);
+            return 2;
+        }
+        return installSkills(options, io);
+    }
     if (args[0] !== 'blueprint') {
-        io.stderr('Usage: bunderstack blueprint [directory] [--entry <path>] [--output <path>] [--check]');
+        io.stderr(help);
         return 2;
     }
     const options = { directory: process.cwd() };

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -0,0 +1,360 @@
+BUNDERSTACK
+
+A batteries-included backend framework for Bun. Version 0.17 (beta).
+Docs: https://bunderstack.dev/docs
+This file is written for coding agents. It is dense on purpose.
+
+WHAT IT IS
+
+createBunderstack() takes a Drizzle schema and returns an app whose handler is
+a single Web-Standard Request -> Response function. From the schema it
+generates secured CRUD procedures. Your own procedures, file storage, realtime
+subscriptions, and a health check live in the same oRPC graph, reachable both
+as typed RPC and as ordinary HTTP.
+
+Stack: Bun, Drizzle (+ drizzle-kit), Better Auth, oRPC v2, libSQL or Postgres,
+sharp. Validation accepts any Standard Schema library; generated schemas use
+Valibot. There is no Hono, no tRPC, and no Zod requirement.
+
+Packages: bunderstack (server), bunderstack-query (client + TanStack Query),
+bunderstack-sync (TanStack DB collections), bunderstack-start (TanStack Start
+integration).
+
+MINIMAL APP
+
+  import { createBunderstack } from 'bunderstack'
+  import { libsql } from 'bunderstack/database/libsql'
+  import * as schema from './schema'
+
+  export const app = await createBunderstack({
+    schema,
+    database: { adapter: libsql(), url: 'file:./data.db' },
+    access: { posts: { list: 'public', get: 'public' } },
+  })
+
+  export type App = typeof app
+  Bun.serve({ fetch: app.handler })
+
+Database adapters are imported from their own entry points: libsql(),
+pglite(), bunSql(), postgresJs(). Provisioning: `await provision(app)` pushes
+the schema in development and applies committed migrations once a migrations/
+folder exists.
+
+DECLARING AN API
+
+Declare the builder once at module scope. defineApi infers the types from the
+values you pass, so you never write the generic parameters yourself. It reads
+nothing at runtime.
+
+  // src/api/base.ts
+  import { defineApi } from 'bunderstack'
+  import { envSchema } from '../env'
+  import { schema } from '../schema'
+
+  export const o = defineApi({ schema, env: envSchema })
+  export const publicProcedure = o.public
+  export const protectedProcedure = o.protected
+
+Router modules are plain objects that import the base they need:
+
+  // src/api/boards.ts
+  import { protectedProcedure } from './base'
+
+  export const boardsRouter = {
+    stats: protectedProcedure
+      .route({ method: 'GET', path: '/api/board-stats' })
+      .input(v.object({ boardId: v.string() }))
+      .handler(async ({ context, input }) => countTodos(context.db, input.boardId)),
+  }
+
+  // src/api/index.ts
+  export const api = { boards: boardsRouter }
+
+  // config
+  createBunderstack({ schema, database, api })
+
+Do NOT write a factory that receives a bag of procedures. That pattern exists
+only because the api option used to be a callback. The callback form still
+works — api: (o) => ({ ... }) — for a router that must be built from the
+framework builder at configuration time, but the object form is the default.
+
+BASES
+
+  o.public     session resolved only if the handler calls context.getSession()
+  o.protected  resolves the session, narrows context.user to non-null
+  o.webhook    public, and preserves the exact raw request body
+  o.middleware(fn)  a standalone middleware typed over the request context
+
+Extend a base with .use(). Whatever you pass to next({ context }) is merged and
+typed downstream:
+
+  export const adminProcedure = o.protected.use(async ({ context, next, errors }) => {
+    if (context.user.role !== 'admin') throw errors.FORBIDDEN({ message: 'Admin only' })
+    return next()
+  })
+
+HANDLER CONTEXT
+
+  db            typed Drizzle instance for your schema
+  env           validated environment, typed from the env schema
+  storage       StorageFacade: delete, bucket, sweep, getUrl, upload
+  email         send()
+  jobs          enqueue()
+  realtime      publish()
+  auth          the Better Auth instance
+  request       the original Request
+  resHeaders    response headers you can set
+  getSession()  resolves the session, memoized per request
+  peekSession() the already-resolved session or undefined; never resolves
+  getRawBody()  the exact bytes, memoized; safe for signature checks
+
+o.protected additionally guarantees context.user and
+context.session.activeOrganizationId.
+
+MIDDLEWARE
+
+Two placements, and the difference is the thing people get wrong.
+
+.use() on a base reaches only procedures built from that base. Use it for
+rules about a group of procedures: role checks, organization scope, quotas.
+
+middleware: [...] in createBunderstack reaches EVERY procedure, including the
+generated CRUD, storage, realtime, and health. Use it for observability. A
+tracing middleware attached to a base leaves generated CRUD unmeasured,
+because the framework builds those procedures itself and they never pass
+through an application base.
+
+  export const instrumentation = o.middleware(async ({ context, next, path }) => {
+    const name = path.join('.')
+    const startedAt = performance.now()
+    try {
+      const result = await next()
+      metrics.record(name, performance.now() - startedAt)
+      return result
+    } catch (error) {
+      metrics.error(name, error)
+      throw error
+    }
+  })
+
+  createBunderstack({ schema, database, middleware: [instrumentation], api })
+
+Rules for graph-wide middleware:
+- It runs before authentication. context.user does not exist there.
+- Read the caller with context.peekSession(), after await next(). Do not call
+  getSession(): that forces resolution on every request and makes signed
+  webhooks pay for authentication they do not need.
+- peekSession() is for observability only, never for authorization. An
+  anonymous request and an unresolved session look identical.
+- A realtime subscription is one long-lived call. Code after await next() runs
+  when the stream closes, not when it starts. Filter by path[0] === 'realtime'
+  when that matters.
+- Middlewares run outermost first, in array order.
+
+TYPED ERRORS
+
+Declared codes: BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT,
+PAYLOAD_TOO_LARGE, TOO_MANY_REQUESTS. Each maps to its standard HTTP status.
+
+Inside a handler or middleware, raise from the errors argument:
+
+  throw errors.NOT_FOUND({ message: 'Board not found' })
+  throw errors.CONFLICT({ message: 'Already running', data: { details: { id } } })
+
+Outside a handler — a service function, a job — there is no errors argument.
+Throw BunderstackError; the framework maps it to the same typed error:
+
+  import { BunderstackError } from 'bunderstack'
+  throw new BunderstackError('FORBIDDEN', 'Insufficient credits')
+
+Do not construct ORPCError by hand. Clients narrow on these with the oRPC
+isDefinedError helpers.
+
+GENERATED CRUD
+
+Per exposed table: list, get, create, update, delete. HTTP equivalents are
+GET /api/:table, GET /api/:table/:id, POST /api/:table, PATCH /api/:table/:id,
+DELETE /api/:table/:id.
+
+List parameters, identical over RPC and query string: limit (default 20, capped
+at 200), offset, sort, order, q, count, cursor, filters. filters[col]=value is
+equality, filters[col][]=a&filters[col][]=b is IN, filters[col]=null is IS
+NULL. A bare ?col=value is not a filter and returns 400. cursor and offset
+cannot be combined.
+
+List response: { items, limit, offset, hasMore, total, sort, order, nextCursor }.
+total is present only with count: true.
+
+Exposure and rules come from the access option:
+
+  access: defineAccess(schema, {
+    posts: {
+      list: 'authenticated',
+      get: 'owner',
+      create: 'authenticated',
+      update: 'owner',
+      delete: 'owner',
+      filterableColumns: ['authorId'],
+      sortableColumns: ['createdAt'],
+      defaultSort: { column: 'createdAt', order: 'desc' },
+      scope: { read: (ctx) => ({ userId: ctx.user?.id ?? '' }) },
+    },
+    auditLog: { crud: false },
+  })
+
+Rules are 'public', 'authenticated', 'owner', 'deny', or a predicate. Without
+an access entry, a table with a userId column is exposed by convention. Owner
+checks use ownerColumn, detected as userId unless stated.
+
+LIST ENDPOINTS OUTSIDE CRUD
+
+listSpec gives a procedure you write the same list contract, for tables that
+are not exposed as CRUD or that need a different policy:
+
+  import { listSpec } from 'bunderstack'
+
+  const logsList = listSpec(appLogs, {
+    filterable: ['level', 'userId'],
+    sortable: ['createdAt'],
+    defaultSort: { column: 'createdAt', order: 'desc' },
+  })
+
+  export const adminRouter = {
+    logs: adminProcedure.input(logsList.input).handler(logsList.handler),
+  }
+
+It returns the schema and the handler separately, not a finished procedure.
+That is deliberate: the base procedure must stay concrete at the call site, or
+TypeScript resolves the builder through a generic constraint and the row type
+is erased. listSpec reads no access configuration; the base carries the policy.
+
+TYPING HELPERS
+
+A service function in its own module cannot use typeof app.db without an import
+cycle. Use the exported types:
+
+  import type { BunderstackDb, BunderstackTx } from 'bunderstack'
+  import type { schema } from './schema'
+
+  type Db = BunderstackDb<typeof schema>
+  type Tx = BunderstackTx<typeof schema>
+
+WEBHOOKS AND HTTP
+
+A webhook is an ordinary procedure with a route. getRawBody() returns the exact
+bytes, so signature verification is correct, and the session is never resolved
+unless the handler asks for it:
+
+  stripeWebhook: o.webhook
+    .route({ method: 'POST', path: '/webhooks/stripe' })
+    .handler(async ({ context }) => {
+      const raw = await context.getRawBody()
+      verify(raw, context.request.headers.get('stripe-signature'), context.env.STRIPE_SECRET)
+      return { received: true }
+    })
+
+For typed headers, query parameters, status codes, or response headers, use
+oRPC inputStructure: 'detailed' and outputStructure.
+
+ENV
+
+  env: { server: { STRIPE_KEY: v.string() }, client: { PUBLIC_NAME: v.string() } }
+
+Server variables must not start with PUBLIC_; client variables must. Validated
+at boot; app.env and context.env are typed from the schema. Declare the schema
+in its own module so both createBunderstack and defineApi can use it.
+
+AUTH
+
+auth takes Better Auth options directly, or defineAuth(schema, ({ db, env }) =>
+options) when database hooks need the app's own connection. Better Auth owns
+/api/auth/*. context.user carries id, email, name, and role. authResolver
+replaces session reading with your own implementation.
+
+BACKGROUND JOBS
+
+One table, one loop. A cron is a job created on a schedule.
+
+  jobs: (j) => j.define({
+    sendEmail: j.job({
+      input: v.object({ userId: v.string() }),
+      retries: 3,
+      handler: async ({ userId }, ctx) => { /* ctx.db, ctx.email, ... */ },
+    }),
+    daily: j.cron({ schedule: '0 9 * * *', handler: async (_inv, ctx) => {} }),
+  })
+
+Enqueue with app.jobs.enqueue(name, input, { dedupeKey }). The background loop
+starts on its own, gated by BUNDERSTACK_ROLE: all (default), web, or worker.
+
+STORAGE
+
+  storage: {
+    local: './uploads',
+    defaultBucket: 'files',
+    buckets: {
+      avatars: {
+        visibility: 'public',
+        access: { create: 'authenticated', get: 'public', delete: 'owner' },
+        upload: { maxSize: '2mb', accept: ['image/jpeg', 'image/png'] },
+        transforms: true,
+      },
+    },
+  }
+
+Canonical URL: /api/files/{bucket}/{+path}. transforms: true enables on-the-fly
+image derivatives through sharp. app.storage exposes delete, bucket, sweep,
+getUrl, and upload for server-generated files.
+
+REALTIME
+
+realtime: true uses an in-memory publisher; { redis: url } fans out across
+processes. Generated writes publish automatically. After a custom write,
+publish the complete returned row:
+
+  await context.realtime.publish(schema.posts, 'update', post)
+
+Clients subscribe through the same graph; there is no separate SSE transport to
+configure.
+
+CLIENT
+
+  import { createClient } from 'bunderstack-query'
+  import type { App } from './bunderstack'
+
+  export const api = createClient<App>({ queryClient, realtime: true })
+
+  await api.posts.list.call({ limit: 20 })
+  useQuery(api.posts.list.queryOptions({ input: { limit: 20 } }))
+  useMutation(api.posts.create.mutationOptions())
+  await api.files.avatars.upload.call(file)
+  api.files.avatars.url(fileId, { width: 320, format: 'webp' })
+
+App is a type-only import, so server code never enters the browser bundle.
+bunderstack-sync layers TanStack DB collections over the same procedures.
+
+CONFIG KEYS
+
+schema (required), database (required: adapter, url), access, auth,
+authResolver, storage, email, env, jobs, api, middleware, realtime, rateLimit,
+idempotency, background, openapi, processEnv.
+
+OPENAPI
+
+openapi: true serves /api/openapi.json. RPC types remain the source of truth; a
+procedure without .output() has an unspecified response body. OpenAPI failures
+never break normal boot.
+
+COMMON MISTAKES
+
+- Writing router factories that take a procedure bag. Use module-scope bases.
+- Declaring middleware with os.$context<...>(). Use o.middleware(...).
+- Attaching observability to a base and expecting it to cover generated CRUD.
+  Use the middleware config option.
+- Calling getSession() in graph-wide middleware. Use peekSession().
+- Constructing ORPCError by hand. Use errors.CODE() or BunderstackError.
+- Using any for a db parameter. Use BunderstackDb<typeof schema>.
+- Importing the app from a module the app imports. Both the api router and any
+  module it pulls in are evaluated at import time, so a cycle through the app
+  breaks initialization. Load the app lazily there instead.
+- Reading env from an imported module inside a handler. Use context.env.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bunderstack",
-  "version": "0.17.0-beta.8",
+  "version": "0.17.0",
   "description": "Batteries-included backend framework for Bun: type-safe oRPC APIs, auth, storage, realtime, jobs, email, and validated env from one config.",
   "keywords": [
     "backend",
@@ -25,6 +25,8 @@
   },
   "files": [
     "dist",
+    "skills",
+    "llms.txt",
     "CHANGELOG.md",
     "README.md",
     "LICENSE"

package/skills/creating-bunderstack-apps/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: creating-bunderstack-apps
+description: Use when working in a repository that depends on bunderstack - starting or structuring the application, adding or changing oRPC procedures, bases, middleware, access rules, jobs, storage, or realtime, choosing a runtime integration, or preparing it for production.
+---
+
+# Creating Bunderstack Apps
+
+## Workflow
+
+1. Inspect the product brief and target runtime.
+2. Choose the layout from the table below.
+3. For a full TanStack Start SaaS, copy `templates/tanstack-start-saas/`.
+4. Configure schema, access, auth, env, storage, jobs, realtime, and the oRPC API graph.
+5. Mount the single `app.handler` integration.
+6. Add committed migrations and a deployment blueprint before production.
+7. Run the verification contract.
+
+| Condition                                                                   | Layout                                                            |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Small API with short configuration                                          | `src/bunderstack.ts`                                              |
+| Auth, access, jobs, env, or custom oRPC procedures need independent modules | `src/bunderstack/`                                                |
+| Full SaaS                                                                   | Copy `templates/tanstack-start-saas/` and keep its modular layout |
+
+## Runtime decision recipe
+
+Choose the process boundary before listing files. A TanStack Start SaaS keeps
+the API mount in Start. A standalone Bun API has `src/bunderstack.ts` (or the
+modular `src/bunderstack/` entry) and a Bun process that delegates to
+`app.handler`.
+
+For a React SPA brief, use the browser-only layout: an `api/` project contains
+the Bunderstack entry and Bun API process, and a separate `frontend/` project
+contains the React build. The API process owns `app.handler`; the browser
+client receives a configured API base URL and calls that process. Include both
+processes and the configured browser-to-API path in the proposed structure.
+
+`node_modules/bunderstack/llms.txt` is a dense plain-text reference for the
+whole framework. Read it when a detail is not covered here.
+
+Read [application structure](references/application-structure.md) before placing
+the Bunderstack entry, schemas, authorization, or configuration modules, and
+before declaring procedures, bases, middleware, or errors.
+Read [runtime integrations](references/runtime-integrations.md) before mounting
+HTTP, adding a worker, or choosing a framework adapter. Read the
+[verification contract](references/verification.md) after adding the app
+scripts and again before handoff or deployment.

package/skills/creating-bunderstack-apps/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Creating Bunderstack Apps"
+  short_description: "Start production-ready Bunderstack applications"
+  default_prompt: "Use $creating-bunderstack-apps to start a new Bunderstack application."