create-questpie 2.0.2 → 2.0.4

package/skills/questpie/SKILL.md

@@ -14,68 +14,143 @@ Server-first TypeScript application framework. Define your data schema once usin
 ## When to Apply
 
 Reference these guidelines when:
+
 - Creating or modifying collections, globals, routes, jobs, services, emails, blocks
 - Working with file conventions or codegen pipeline
 - Configuring adapters (queue, search, storage, realtime, email, KV)
 - Setting up access control, hooks, or validation
 - Building typed client SDK queries or TanStack Query integrations
 - Writing modules or plugins for QUESTPIE
+- Exposing QUESTPIE through MCP tools or resources
 - Scaffolding a new project or onboarding
 
 ## Import Paths — Critical
 
-| Factory | Import From | Needs Codegen? |
-|---|---|---|
-| `collection(name)` | `#questpie/factories` | Yes |
-| `global(name)` | `#questpie/factories` | Yes |
-| `block(name)` | `#questpie/factories` | Yes |
-| `adminConfig({...})` | `#questpie/factories` | Yes |
-| `route()` | `"questpie"` | No |
-| `job({...})` | `"questpie"` | No |
-| `service()` | `"questpie"` | No |
-| `email({...})` | `"questpie"` | No |
-| `migration({...})` | `"questpie"` | No |
-| `seed({...})` | `"questpie"` | No |
-| `runtimeConfig({...})` | `"questpie"` | No |
-| `appConfig({...})` | `"questpie"` | No |
-| `authConfig({...})` | `"questpie"` | No |
-| `createClient<AppConfig>()` | `"questpie/client"` | No |
-| `createQuestpieQueryOptions()` | `"@questpie/tanstack-query"` | No |
+| Factory                        | Import From                  | Needs Codegen? |
+| ------------------------------ | ---------------------------- | -------------- |
+| `collection(name)`             | `#questpie/factories`        | Yes            |
+| `global(name)`                 | `#questpie/factories`        | Yes            |
+| `block(name)`                  | `#questpie/factories`        | Yes            |
+| `adminConfig({...})`           | `#questpie/factories`        | Yes            |
+| `route()`                      | `"questpie"`                 | No             |
+| `job({...})`                   | `"questpie"`                 | No             |
+| `service()`                    | `"questpie"`                 | No             |
+| `email({...})`                 | `"questpie"`                 | No             |
+| `migration({...})`             | `"questpie"`                 | No             |
+| `seed({...})`                  | `"questpie"`                 | No             |
+| `runtimeConfig({...})`         | `"questpie"`                 | No             |
+| `appConfig({...})`             | `"questpie"`                 | No             |
+| `authConfig({...})`            | `"questpie"`                 | No             |
+| `env({...})`                   | `"questpie/env"`             | No             |
+| `clientEnv({...})`             | `"questpie/env"`             | No             |
+| `createClient<AppConfig>()`    | `"questpie/client"`          | No             |
+| `createQuestpieQueryOptions()` | `"@questpie/tanstack-query"` | No             |
+
+## Module And Plugin Configuration - Critical
+
+Codegen imports `modules.ts` before runtime app creation to extract module-contributed plugins. Any module that contributes a `plugin`, discover patterns, generated factories, categories, views, components, fields, or config factories must be statically discoverable from `modules.ts`.
+
+### DO THIS
+
+Use a static module and a plugin-discovered config file for runtime options:
+
+```ts title="modules.ts"
+import { observabilityModule } from "@questpie/observability/server";
+
+export default [observabilityModule] as const;
+```
+
+```ts title="config/observability.ts"
+import { observabilityConfig } from "@questpie/observability/server";
+
+export default observabilityConfig({
+	serviceName: "barbershop",
+	enabled: process.env.NODE_ENV === "production",
+});
+```
+
+The module reads config at runtime from `app.state.config.observability`:
+
+```ts
+export const observabilityModule = module({
+	name: "questpie-observability",
+	plugin: observabilityPlugin(),
+	services: {
+		observability: service({
+			namespace: null,
+			lifecycle: "singleton",
+			create: ({ app, logger }) =>
+				createObservabilityService(app.state.config?.observability, logger),
+		}),
+	},
+});
+```
+
+### DON'T DO THIS
+
+Do not make runtime options the primary API for codegen-aware modules:
+
+```ts title="modules.ts"
+export default [
+	observabilityModule({
+		serviceName: "barbershop",
+	}),
+] as const;
+```
+
+Do not conditionally hide codegen-aware modules or plugins behind env/runtime checks:
+
+```ts title="modules.ts"
+export default [
+	process.env.OTEL_ENABLED ? observabilityModule : undefined,
+].filter(Boolean);
+```
+
+Factory modules are acceptable only for simple runtime-only modules whose plugin identity and codegen contributions do not change. For reusable packages that ship a `CodegenPlugin`, prefer **static module + `config/*.ts` singleton factory**.
+
+## Admin Auth Contract - Critical
+
+`adminModule` includes the starter auth model and owns the canonical Better Auth `user` collection shape used by admin setup and login guards. That contract includes `user.role` with at least `admin` and `user` values. Do not replace `collection("user")` from scratch in apps that use `adminModule`; merge `starterModule.collections.user` and extend it when custom user fields or layout are needed.
 
 ## Reference Topics
 
 ### Core
 
-| Topic | File | Covers |
-|---|---|---|
-| Quickstart | `references/quickstart.md` | Scaffold, configure, codegen, migrate, serve — zero to running app |
-| Data Modeling | `references/data-modeling.md` | Collections, globals, fields, relations, options, localization |
-| Field Types | `references/field-types.md` | All built-in field types with options and operators |
-| Rules | `references/rules.md` | Access control (row/field level), hooks lifecycle, validation |
-| Business Logic | `references/business-logic.md` | Routes, jobs, services, email templates, context injection |
-| CRUD API | `references/crud-api.md` | Server-side `find`, `create`, `update`, `delete`, globals API |
-| Query Operators | `references/query-operators.md` | `where` clause operators by field type |
+| Topic             | File                            | Covers                                                             |
+| ----------------- | ------------------------------- | ------------------------------------------------------------------ |
+| Quickstart        | `references/quickstart.md`      | Scaffold, configure, codegen, migrate, serve — zero to running app |
+| Data Modeling     | `references/data-modeling.md`   | Collections, globals, fields, relations, options, localization     |
+| Field Types       | `references/field-types.md`     | All built-in field types with options and operators                |
+| Type Inference    | `references/type-inference.md`  | The infer-first map: `CollectionDoc`, `AccessContext` helpers, per-op rule typing, cycle rules |
+| Rules             | `references/rules.md`           | Access control (row/field level), hooks lifecycle, validation, derived request context |
+| Business Logic    | `references/business-logic.md`  | Routes, jobs, services, email templates, context injection         |
+| Durable Workflows | `references/workflows.md`       | Long-running workflows, steps, events, cron, admin UI              |
+| Sandboxed Code    | `references/sandbox.md`         | `ctx.executor.run()`, isolation modes, capability model, Deno engine deployment |
+| CRUD API          | `references/crud-api.md`        | `find`, `create`, `updateById`/`updateMany`, `deleteById`/`deleteMany`, atomic conditional updates, globals API |
+| Query Operators   | `references/query-operators.md` | `where` clause operators by field type                             |
 
 ### Infrastructure
 
-| Topic | File | Covers |
-|---|---|---|
-| Production | `references/production.md` | Queue, search, realtime, storage, email, KV adapter setup |
-| Auth | `references/auth.md` | Better Auth integration, session, providers, access patterns |
-| Adapters | `references/infrastructure-adapters.md` | All adapter configs: pg-boss, S3, SMTP, pgNotify, Redis |
+| Topic      | File                                    | Covers                                                       |
+| ---------- | --------------------------------------- | ------------------------------------------------------------ |
+| Production | `references/production.md`              | Queue, search, realtime, storage, email, KV adapter setup    |
+| Environment | `references/env.md`                    | `env.ts` + `env.client.ts`: boot-validated, typed env, generated client modules |
+| Auth       | `references/auth.md`                    | Better Auth integration, session, providers, access patterns |
+| Adapters   | `references/infrastructure-adapters.md` | All adapter configs: pg-boss, S3, SMTP, pgNotify, Redis      |
+| MCP        | `references/mcp.md`                     | MCP setup, CRUD tools, route tools, custom tools, security   |
 
 ### Extend
 
-| Topic | File | Covers |
-|---|---|---|
-| Extend | `references/extend.md` | Custom modules, fields, operators, adapters, codegen plugins |
-| Codegen Plugin API | `references/codegen-plugin-api.md` | Plugin architecture, category declarations, templates |
-| Multi-Tenancy | `references/multi-tenancy.md` | Scope isolation, workspace filtering, ScopeProvider |
+| Topic              | File                               | Covers                                                       |
+| ------------------ | ---------------------------------- | ------------------------------------------------------------ |
+| Extend             | `references/extend.md`             | Custom modules, fields, operators, adapters, codegen plugins |
+| Codegen Plugin API | `references/codegen-plugin-api.md` | Plugin architecture, category declarations, templates        |
+| Multi-Tenancy      | `references/multi-tenancy.md`      | `appConfig({ context })` resolver, scope isolation, ScopeProvider |
 
 ### Client
 
-| Topic | File | Covers |
-|---|---|---|
+| Topic          | File                           | Covers                                                           |
+| -------------- | ------------------------------ | ---------------------------------------------------------------- |
 | TanStack Query | `references/tanstack-query.md` | `q.collections.*`, `q.globals.*`, `q.routes.*`, realtime queries |
 
 ## Key Patterns — Quick Reference
@@ -86,53 +161,71 @@ Reference these guidelines when:
 import { collection } from "#questpie/factories";
 
 export default collection("posts")
-  .fields(({ f }) => ({
-    title: f.text().required(),
-    status: f.select([{ value: "draft", label: "Draft" }]),
-    author: f.relation("users").required(),
-  }))
-  .access({
-    read: true,
-    create: ({ session }) => !!session,
-    update: ({ session, doc }) => doc.authorId === session?.user?.id,
-  })
-  .hooks({
-    beforeChange: async ({ data, operation }) => {
-      if (operation === "create") data.slug = slugify(data.title);
-      return data;
-    },
-  })
-  .options({ versioning: true, timestamps: true });
+	.fields(({ f }) => ({
+		title: f.text().required(),
+		status: f.select([{ value: "draft", label: "Draft" }]),
+		author: f.relation("user").required(),
+	}))
+	.access({
+		read: true,
+		create: ({ session }) => !!session,
+		// update rules get the existing row as `data` (typed, non-optional)
+		update: ({ session, data }) => data.author === session?.user?.id,
+	})
+	.hooks({
+		beforeChange: async ({ data, operation }) => {
+			if (operation === "create") data.slug = slugify(data.title);
+			return data;
+		},
+	})
+	.options({ versioning: true, timestamps: true });
+```
+
+### Extend a Module Collection (don't redefine!)
+
+```ts
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+// Registering the same key from scratch REPLACES the module's collection
+// (drops its fields/hooks/auth wiring). Merge instead — fully typed:
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		isAnonymous: f.boolean().default(false),
+	}));
 ```
 
 ### Route
 
 ```ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
-  .post()
-  .schema(z.object({ period: z.enum(["day", "week", "month"]) }))
-  .handler(async ({ input, collections }) => {
-    return collections.posts.find({ where: { status: "published" } });
-  });
+	.post()
+	.schema(z.object({ period: z.enum(["day", "week", "month"]) }))
+	.handler(async ({ input, collections }) => {
+		return collections.posts.find({ where: { status: "published" } });
+	});
 ```
 
 ### Job
 
 ```ts
-import { job } from "questpie";
+import { job } from "questpie/services";
 import z from "zod";
 
 export default job({
-  name: "sendReminder",
-  schema: z.object({ userId: z.string() }),
-  retryDelay: 5,  // seconds (not ms!)
-  handler: async ({ payload, email, collections }) => {
-    const user = await collections.users.findOne({ where: { id: payload.userId } });
-    await email.send("reminder", { to: user.email, data: { name: user.name } });
-  },
+	name: "sendReminder",
+	schema: z.object({ userId: z.string() }),
+	retryDelay: 5, // seconds (not ms!)
+	handler: async ({ payload, email, collections }) => {
+		const user = await collections.users.findOne({
+			where: { id: payload.userId },
+		});
+		await email.send("reminder", { to: user.email, data: { name: user.name } });
+	},
 });
 ```
 
@@ -141,16 +234,18 @@ export default job({
 ```ts
 import { createClient } from "questpie/client";
 import type { AppConfig } from "#questpie";
+import { env } from "#questpie/env.client.vite"; // generated from env.client.ts
 
 const client = createClient<AppConfig>({
-  baseURL: typeof window !== "undefined" ? window.location.origin : process.env.APP_URL,
-  basePath: "/api",
+	baseURL:
+		typeof window !== "undefined" ? window.location.origin : env.APP_URL,
+	basePath: "/api",
 });
 
 const { docs } = await client.collections.posts.find({
-  where: { status: "published" },
-  orderBy: { createdAt: "desc" },
-  with: { author: true },
+	where: { status: "published" },
+	orderBy: { createdAt: "desc" },
+	with: { author: true },
 });
 ```
 
@@ -164,17 +259,34 @@ await queue.sendReminder.publish({ userId: "abc" });
 
 ## Common Mistakes
 
-| Severity | Mistake | Fix |
-|---|---|---|
-| CRITICAL | Files in wrong directory | Collections in `collections/`, routes in `routes/`, etc. |
-| CRITICAL | Missing `export default` on convention files | Codegen silently ignores files without default export |
+| Severity | Mistake                                                | Fix                                                                                   |
+| -------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| CRITICAL | Files in wrong directory                               | Collections in `collections/`, routes in `routes/`, etc.                              |
+| CRITICAL | Missing `export default` on convention files           | Codegen silently ignores files without default export                                 |
 | CRITICAL | Importing route/job/service from `#questpie/factories` | Use `"questpie"` — only collection/global/block/adminConfig use `#questpie/factories` |
-| HIGH | Forgetting `questpie generate` after adding files | Re-run codegen on any file add/remove in convention dirs |
-| HIGH | Job handler uses `input` instead of `payload` | Jobs destructure `{ payload }`, routes destructure `{ input }` |
-| HIGH | `queue.send("name", data)` | Use `queue.jobName.publish(data)` |
-| HIGH | `beforeCreate` / `afterCreate` hook names | Use `beforeChange` / `afterChange` with `operation === "create"` guard |
-| MEDIUM | Using npm/yarn instead of Bun | QUESTPIE requires Bun as package manager |
-| MEDIUM | Editing `.generated/` files | Never edit — re-run `questpie generate` |
+| CRITICAL | Redefining a module collection (e.g. starter `user`) from scratch | `.merge(starterModule.collections.user)` then add fields — see Extend pattern        |
+| HIGH     | Forgetting `questpie generate` after adding files      | Re-run codegen on any file add/remove in convention dirs                              |
+| HIGH     | Job handler uses `input` instead of `payload`          | Jobs destructure `{ payload }`, routes destructure `{ input }`                        |
+| HIGH     | `queue.send("name", data)`                             | Use `queue.jobName.publish(data)`                                                     |
+| HIGH     | Raw `process.env.X` / `process.env.X!` in app code     | Declare in `env.ts` with `env()` — typed, boot-validated (see `references/env.md`)    |
+| HIGH     | `beforeCreate` / `afterCreate` hook names              | Use `beforeChange` / `afterChange` with `operation === "create"` guard                |
+| HIGH     | Module-level app singleton for Better Auth callbacks   | `getContext<App>()` works inside `onLinkAccount`/`databaseHooks`/plugin hooks — see `references/auth.md` |
+| HIGH     | Hand-writing a type the schema already knows           | Use the inference one-liner (`CollectionDoc`, `AccessContext`, `ctx.data`, …) — see `references/type-inference.md` |
+| HIGH     | Runtime options in codegen-aware modules               | Use static `module({...})` + plugin-discovered `config/*.ts` factory                  |
+| HIGH     | Exposing MCP HTTP as trusted system access             | HTTP MCP is user mode only; use stdio only in trusted local/system contexts           |
+| HIGH     | Bare `Date` as where-equality (`{ createdAt: someDate }`) | Use the explicit operator: `{ createdAt: { eq: someDate } }` — see `references/crud-api.md` keyset recipe |
+| MEDIUM   | Using npm/yarn instead of Bun                          | QUESTPIE requires Bun as package manager                                              |
+| MEDIUM   | Editing `.generated/` files                            | Never edit — re-run `questpie generate`                                               |
+
+## Preview And Workflow Rules
+
+- Live Preview uses the existing admin `FormView`, Preview button, `LivePreviewMode`, and iframe. Do not introduce a separate visual-edit form API, a second default form view, or parallel preview API names.
+- Preserve save, autosave, Cmd+S, history, workflow transitions, locks, and actions in the normal form lifecycle.
+- Frontend visual editing needs `useCollectionPreview`, `PreviewProvider`, `PreviewField`, and usually `BlockRenderer`; load the `questpie-admin` skill for the full frontend preparation checklist.
+- For publishable pages with workflow enabled, workflow stage is the publication source. Public frontend reads use `stage: "published"`.
+- If public client/HTTP access is enabled, anonymous read access should require `input?.stage === "published"`; editor/preview reads can omit `stage` only when a session is present.
+- Preview/draft-mode reads may load the working stage for authorized editors.
+- Do not add duplicate `isPublished` guidance when workflow already controls publishing.
 
 ## Full Compiled Document
 

package/skills/questpie/coverage.json

@@ -0,0 +1,213 @@
+{
+	"_readme": "Allowlist + surface map for scripts/skill-coverage.ts. Reviewed together with the skill: every public VALUE export must be mentioned in skills/questpie/** or tagged internal here (with a reason). Type-only exports are reported but never gate. Run: bun run scripts/skill-coverage.ts (--strict to gate, --json/--all for detail).",
+	"skillRoot": "skills/questpie",
+	"surfaces": [
+		{ "package": "questpie", "entries": ["packages/questpie/src/exports"] },
+		{ "package": "@questpie/tanstack-query", "entries": ["packages/tanstack-query/src/index.ts"] },
+		{ "package": "@questpie/workflows", "entries": ["packages/workflows/src/exports"] },
+		{ "package": "@questpie/mcp", "entries": ["packages/mcp/src/exports"] },
+		{ "package": "@questpie/sandbox", "entries": ["packages/sandbox/src/exports"] },
+		{ "package": "@questpie/hono", "entries": ["packages/hono/src/server.ts", "packages/hono/src/client.ts"] },
+		{ "package": "@questpie/elysia", "entries": ["packages/elysia/src/server.ts", "packages/elysia/src/client.ts"] },
+		{ "package": "@questpie/next", "entries": ["packages/next/src/server.ts"] },
+		{
+			"package": "@questpie/openapi",
+			"entries": ["packages/openapi/src/index.ts", "packages/openapi/src/server.ts", "packages/openapi/src/plugin.ts"]
+		}
+	],
+	"skippedPackages": {
+		"@questpie/admin": "covered by the separate questpie-admin skill (audit hook: map it there)",
+		"@questpie/executor-engine (packages/executor)": "engine side of the sandbox primitive; apps target ctx.sandbox",
+		"@questpie/ai": "product layer, not framework surface",
+		"create-questpie": "scaffolder CLI, not a library surface",
+		"@questpie/vite-plugin-iconify": "admin build tooling; covered by the questpie-admin skill"
+	},
+	"internal": {
+		"createContextFactory": "only consumed by generated code (.generated/index.ts)",
+		"extractAppServices": "context plumbing; apps receive services on ctx",
+		"createWorkflowClient": "service factory internal; ctx.workflows.trigger is the taught surface",
+		"introspectRoutes": "powers openapi/mcp generators",
+		"handleError": "HTTP adapter internal",
+		"RouteBuilder": "class behind route(); apps use the factory",
+		"SandboxBroker": "engine side of sandbox bindings",
+		"hostFetch": "sandbox host RPC internal",
+		"coreBackendMessages": "override path covered by generic messages merge",
+		"ExecutorService": "service class behind ctx.executor.run (the taught surface); constructed by the core service factory",
+		"InProcessExecutorAdapter": "default trusted adapter, applied automatically; override via executor.trusted",
+		"HTTP_FETCH_BODY_CAP_BYTES": "executor wire constant",
+		"parseBindingMethod": "executor broker internal",
+		"checkBindingCapability": "sandbox broker internal",
+		"knowledgePathMatches": "sandbox broker internal",
+		"normalizeKnowledgePath": "sandbox broker internal",
+		"DOCUMENT_STORE_COLLECTION": "sandbox broker internal constant",
+		"buildGuestBindings": "sandbox guest-side internal",
+		"classifyIpLiteral": "sandbox egress validation internal",
+		"parseHostEntry": "sandbox egress validation internal",
+		"validateEgressHosts": "sandbox egress validation internal",
+		"validateHostEgress": "sandbox egress validation internal",
+		"BINDINGS_TOKEN_HEADER": "sandbox wire-protocol constant",
+		"FRAME_MARKER": "sandbox wire-protocol constant",
+		"toVectorLiteral": "pgvector adapter internal util",
+		"createSearchService": "service wiring internal; ctx.search is the taught surface",
+		"SearchServiceWrapper": "see createSearchService",
+		"FilesError": "files-sdk pass-through; taught via Files SDK docs",
+		"transfer": "files-sdk pass-through; taught via Files SDK docs",
+		"RESEND_API_BASE_URL": "adapter default constant",
+		"PLUNK_API_BASE_URL": "adapter default constant",
+		"BullMQAdapter": "class form; bullMQAdapter() factory is the taught surface",
+		"CloudflareKVAdapter": "class form; cloudflareKVAdapter() factory is the taught surface",
+		"CloudflareQueuesAdapter": "class form; cloudflareQueuesAdapter() factory is the taught surface",
+		"CloudflareRealtimeAdapter": "class form; cloudflareRealtimeAdapter() factory is the taught surface",
+		"PgBossAdapter": "class form; pgBossAdapter() factory is the taught surface",
+		"PgNotifyAdapter": "class form; pgNotifyAdapter() factory is the taught surface",
+		"RedisStreamsAdapter": "class form; redisStreamsAdapter() factory is the taught surface",
+		"PlunkAdapter": "class form; plunkAdapter() factory is the taught surface",
+		"ResendAdapter": "class form; resendAdapter() factory is the taught surface",
+		"HttpSandboxAdapter": "class form; httpSandboxAdapter() factory is the taught surface",
+		"OpenAIEmbeddingProvider": "class form; createOpenAIEmbeddingProvider() factory is the taught surface",
+		"CustomEmbeddingProvider": "class form; createCustomEmbeddingProvider() factory is the taught surface",
+		"createCloudflareFetchHandler": "granular handler; createCloudflareWorkerHandlers umbrella is taught",
+		"createCloudflareQueueHandler": "granular handler; createCloudflareWorkerHandlers umbrella is taught",
+		"createCloudflareRealtimeDurableObjectHandler": "granular handler; createCloudflareWorkerHandlers umbrella is taught",
+		"createCloudflareScheduledHandler": "granular handler; createCloudflareWorkerHandlers umbrella is taught",
+		"publishScheduledJobs": "Cloudflare scheduled-handler internal",
+		"toCloudflareQueuePushBatch": "Cloudflare queue-handler internal",
+		"assertCloudflareCompatible": "boot-time compatibility check, runs automatically",
+		"getCloudflareCompatibilityIssues": "see assertCloudflareCompatible",
+		"CloudflareCompatibilityError": "see assertCloudflareCompatible",
+		"CLOUD_ENV": "QUESTPIE Cloud env detection constant",
+		"isQuestpieCloud": "QUESTPIE Cloud env detection helper",
+		"createAdapterContext": "HTTP adapter wiring internal",
+		"createAdapterRoutes": "HTTP adapter wiring internal",
+		"evaluateRouteAccess": "route dispatcher internal",
+		"executeJsonRoute": "route dispatcher internal",
+		"executeRawRoute": "route dispatcher internal",
+		"isJsonRoute": "route dispatcher internal",
+		"isRawRoute": "route dispatcher internal",
+		"executeAccessRule": "CRUD access-control engine internal",
+		"mergeAuthOptions": "auth config merge internal (createApp applies it)",
+		"guardHookRecursion": "hook engine internal",
+		"GlobalCRUDGenerator": "CRUD engine internal; ctx.globals is the taught surface",
+		"createQueueClient": "service wiring internal; ctx.queue is the taught surface",
+		"startJobWorker": "worker wiring internal; app.queue.listen() is the taught surface",
+		"runJobWorkerOnce": "worker wiring internal; app.queue.runOnce() is the taught surface",
+		"createComponentCallbackProxy": "server-driven admin UI internal",
+		"program": "CLI entry object; the questpie CLI commands are the taught surface",
+		"builtinFields": "field registry internal; f.* factories are the taught surface",
+		"createFieldBuilder": "builder engine internal",
+		"createFieldsCallbackContext": "builder engine internal",
+		"extractFieldDefinitions": "builder engine internal",
+		"wrapBuilderWithExtensions": "builder engine internal",
+		"wrapFieldComplete": "builder engine internal",
+		"createCollectionValidationSchemas": "validation engine internal",
+		"mergeFieldsForValidation": "validation engine internal",
+		"softDeleteUniqueIndex": "schema generation internal",
+		"introspectCollection": "introspection engine internal (powers /schema routes)",
+		"introspectCollections": "introspection engine internal",
+		"introspectGlobal": "introspection engine internal",
+		"introspectGlobals": "introspection engine internal",
+		"getCurrentTransaction": "transaction plumbing; withTransaction/onAfterCommit are the taught surface",
+		"getTransactionContext": "transaction plumbing",
+		"isInTransaction": "transaction plumbing",
+		"isNotNull": "internal type guard util",
+		"DrizzleMigrationGenerator": "CLI migration machinery",
+		"MigrationRunner": "CLI migration machinery",
+		"OperationSnapshotManager": "CLI migration machinery",
+		"SeedRunner": "CLI seed machinery",
+		"resolveAutoSeedCategories": "CLI seed machinery",
+		"createInsertSchema": "drizzle-to-zod internal",
+		"createUpdateSchema": "drizzle-to-zod internal",
+		"drizzleColumnsToZod": "drizzle-to-zod internal",
+		"drizzleColumnToZod": "drizzle-to-zod internal",
+		"parseDatabaseError": "error mapping internal; ApiError is the taught surface",
+		"CMS_ERROR_CODES": "raw code map; ApiError + docs reference/error-codes are the taught surface",
+		"getHTTPStatusFromCode": "error mapping internal",
+		"mergeAdminConfig": "admin config merge internal (createApp applies it)",
+		"mergeAdminSidebar": "admin config merge internal",
+		"isAuthoritativeSidebar": "admin sidebar internal",
+		"shouldAutoAppendUnlistedSidebar": "admin sidebar internal",
+		"serializeFormLayoutProps": "server-driven admin UI internal",
+		"serializeReactivePropValue": "server-driven admin UI internal",
+		"serializeReactivePropsRecord": "server-driven admin UI internal",
+		"isReactiveConfig": "server-driven admin UI internal",
+		"isReactivePropPlaceholder": "server-driven admin UI internal",
+		"trackDependencies": "reactive admin fields internal",
+		"trackDepsFunction": "reactive admin fields internal",
+		"getDebounce": "reactive admin fields internal",
+		"extractDependencies": "reactive admin fields internal",
+		"createValidationTranslator": "i18n plumbing; messages merge + ctx.t are the taught surface",
+		"createZodErrorMap": "i18n plumbing",
+		"i18nParams": "i18n plumbing",
+		"isI18nLocaleMap": "i18n plumbing",
+		"isI18nTranslationKey": "i18n plumbing",
+		"mergeValidationMessages": "i18n plumbing",
+		"resolveI18nText": "i18n plumbing",
+		"validationMessagesCS": "built-in locale pack, loaded automatically",
+		"validationMessagesDE": "built-in locale pack",
+		"validationMessagesEN": "built-in locale pack",
+		"validationMessagesES": "built-in locale pack",
+		"validationMessagesFR": "built-in locale pack",
+		"validationMessagesPL": "built-in locale pack",
+		"validationMessagesPT": "built-in locale pack",
+		"validationMessagesSK": "built-in locale pack",
+		"dedupeBy": "shared util pass-through",
+		"deepMerge": "shared util pass-through; mergeRecord & friends are the taught merge surface",
+		"isNullish": "shared util pass-through",
+		"isPlainObject": "shared util pass-through",
+		"toCamelCase": "shared util pass-through",
+		"toKebabCase": "shared util pass-through",
+		"toPascalCase": "shared util pass-through",
+		"toSnakeCase": "shared util pass-through",
+		"DEFAULT_LOCALE": "framework default constant",
+		"DEFAULT_LOCALE_CONFIG": "framework default constant",
+		"questpieSearchTable": "search infrastructure table (managed by adapter migrations)",
+		"questpieSearchFacetsTable": "search infrastructure table",
+		"questpieRealtimeLogTable": "realtime outbox table (managed by adapter migrations)",
+		"extractFacetValues": "search indexing internal",
+		"indexRecordsJob": "search reindex job, registered automatically",
+		"indexRecordsSchema": "see indexRecordsJob",
+		"categoryRecordEntry": "codegen template emission util",
+		"categoryTypeEntry": "codegen template emission util",
+		"importStatement": "codegen template emission util",
+		"safeKey": "codegen template emission util",
+		"sortedValues": "codegen template emission util",
+		"sourceBasename": "codegen template emission util",
+		"checkRetroactiveMatch": "workflow engine internal",
+		"computeMatchHash": "workflow engine internal",
+		"createCompletedStepsMap": "workflow engine internal",
+		"cronFiredInWindow": "workflow engine internal",
+		"cronMatches": "workflow engine internal",
+		"dispatchEvent": "workflow engine internal; ctx.workflows.dispatchEvent is the taught surface",
+		"defaultWorkflowAccess": "default applied automatically; override via workflowsConfig({ access })",
+		"executeWorkflowHandler": "workflow engine internal",
+		"getMatchHashesForDispatch": "workflow engine internal",
+		"matchesCriteria": "workflow engine internal",
+		"parseCron": "workflow engine internal",
+		"parseDuration": "workflow engine internal",
+		"resolveDate": "workflow engine internal",
+		"runCompensations": "workflow engine internal",
+		"WILDCARD_HASH": "workflow engine internal constant",
+		"WorkflowLoggerImpl": "workflow engine internal",
+		"StepExecutionContext": "workflow engine internal",
+		"NonDeterministicError": "engine-raised error, surfaced in run records",
+		"StepFailedError": "engine-raised error, surfaced in run records",
+		"StepRetryError": "engine-raised error, surfaced in run records",
+		"StepSuspendError": "engine-raised control-flow error",
+		"WorkflowError": "engine-raised error, surfaced in run records",
+		"WorkflowTimeoutError": "engine-raised error, surfaced in run records",
+		"WorkflowsPage": "registered via workflowsClientModule (taught)",
+		"WorkflowListPage": "registered via workflowsClientModule",
+		"WorkflowDetailPage": "registered via workflowsClientModule"
+	},
+	"concepts": [
+		{ "name": "auth-callback context (getContext in Better Auth callbacks)", "patterns": ["onLinkAccount"] },
+		{ "name": "partial context overrides ({ accessMode } inherits session/db/locale)", "patterns": ["partial context override"] },
+		{ "name": "job-level cron (options.cron)", "patterns": ["options:\\s*\\{\\s*cron"] },
+		{ "name": "raw routes (.raw())", "patterns": ["\\.raw\\(\\)"] },
+		{ "name": "signed URLs for private files", "patterns": ["generateSignedUrlToken"] },
+		{ "name": "sandboxed code execution (ctx.executor)", "patterns": ["ctx\\.executor\\.run"] },
+		{ "name": "client-side auth (authClient)", "patterns": ["createAdminAuthClient", "authClient"] },
+		{ "name": "infer-first map (type-inference reference)", "patterns": ["CollectionDoc<"] },
+		{ "name": "realtime invalidation topics", "patterns": ["buildCollectionTopic"] }
+	]
+}