create-questpie 2.0.3 → 2.0.4

package/skills/questpie/SKILL.md

@@ -21,6 +21,7 @@ Reference these guidelines when:
 - 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
@@ -40,6 +41,8 @@ Reference these guidelines when:
 | `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             |
 
@@ -105,27 +108,36 @@ export default [
 
 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    |
+| 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
 
@@ -133,7 +145,7 @@ Factory modules are acceptable only for simple runtime-only modules whose plugin
 | ------------------ | ---------------------------------- | ------------------------------------------------------------ |
 | 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          |
+| Multi-Tenancy      | `references/multi-tenancy.md`      | `appConfig({ context })` resolver, scope isolation, ScopeProvider |
 
 ### Client
 
@@ -152,12 +164,13 @@ export default collection("posts")
 	.fields(({ f }) => ({
 		title: f.text().required(),
 		status: f.select([{ value: "draft", label: "Draft" }]),
-		author: f.relation("users").required(),
+		author: f.relation("user").required(),
 	}))
 	.access({
 		read: true,
 		create: ({ session }) => !!session,
-		update: ({ session, doc }) => doc.authorId === session?.user?.id,
+		// update rules get the existing row as `data` (typed, non-optional)
+		update: ({ session, data }) => data.author === session?.user?.id,
 	})
 	.hooks({
 		beforeChange: async ({ data, operation }) => {
@@ -168,10 +181,25 @@ export default collection("posts")
 	.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()
@@ -185,7 +213,7 @@ export default route()
 ### Job
 
 ```ts
-import { job } from "questpie";
+import { job } from "questpie/services";
 import z from "zod";
 
 export default job({
@@ -206,12 +234,11 @@ 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,
+		typeof window !== "undefined" ? window.location.origin : env.APP_URL,
 	basePath: "/api",
 });
 
@@ -237,11 +264,17 @@ await queue.sendReminder.publish({ userId: "abc" });
 | 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` |
+| 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`                                               |
 

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"] }
+	]
+}

package/skills/questpie/references/auth.md

@@ -8,8 +8,7 @@ Auth is configured via `config/auth.ts` using the `authConfig()` factory:
 
 ```ts
 // src/questpie/server/config/auth.ts
-import { authConfig } from "questpie";
-
+import { authConfig } from "questpie/app";
 export default authConfig({
 	emailAndPassword: {
 		enabled: true,
@@ -38,7 +37,7 @@ Codegen discovers this file automatically. No manual registration needed.
 ### In Routes
 
 ```ts
-import { route } from "questpie";
+import { route } from "questpie/services";
 import z from "zod";
 
 export default route()
@@ -95,16 +94,132 @@ export default route()
 
 ## User Collection
 
-The `adminModule` provides a built-in `user` collection. It stores:
+The `adminModule` includes the starter auth model and provides the canonical Better Auth `user` collection. It stores:
 
 - `id` -- unique identifier
 - `email` -- email address
 - `name` -- display name
 - `image` -- avatar URL
 - `emailVerified` -- verification status
+- `role` -- admin access role (`admin` or `user`)
+- `avatar`, `banned`, `banReason`, `banExpires` -- admin-managed profile and access fields
 
 This collection is automatically created when you add the admin module to your config.
 
+Critical: the built-in admin setup route and admin `AuthGuard` depend on `user.role`. Setup checks whether any user has `role = "admin"`, and the admin UI expects `session.user.role === "admin"`. Do not replace `collection("user")` from scratch in an app that uses `adminModule`; merge `starterModule.collections.user` and extend it if custom user fields or admin layout are needed.
+
+```ts
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		internalNotes: f.textarea(),
+	}));
+```
+
+`.fields()` is cumulative -- it adds to the merged starter fields and overrides them by key, never wipes them, so this recipe keeps the full starter user model.
+
+### Anonymous Users (Better Auth plugin)
+
+Better Auth plugins that extend the user model follow the same recipe. For the anonymous plugin, register it in `auth.ts` (merged after the built-in plugins) and extend the starter user with the `isAnonymous` field the plugin expects:
+
+```ts
+// auth.ts
+import { anonymous } from "better-auth/plugins";
+import type { AuthConfig } from "questpie/app";
+
+export default {
+	plugins: [anonymous()],
+} satisfies AuthConfig;
+```
+
+```ts
+// collections/user.ts
+import { starterModule } from "questpie/app";
+import { collection } from "#questpie/factories";
+
+export default collection("user")
+	.merge(starterModule.collections.user)
+	.fields(({ f }) => ({
+		isAnonymous: f.boolean().default(false),
+	}));
+```
+
+Run `questpie generate` and apply migrations to add the column. Anonymous sign-in (`authClient.signIn.anonymous()` on the client) creates throwaway users that Better Auth can later link to real accounts.
+
+## Reaching the App from Better Auth Callbacks
+
+The `/auth/*` catch-all is a plain **raw route**, and raw routes execute their handler inside `runWithContext()` (the request's AsyncLocalStorage scope). That means every Better Auth callback — `onLinkAccount`, `databaseHooks`, `sendMagicLink`, plugin hooks — already runs inside the request scope, and `getContext<App>()` returns the live app, session, db, and locale.
+
+**Never build a module-level app singleton or a hand-rolled context bridge for auth callbacks.** The `App` import stays type-only, so there is no circular import:
+
+```ts
+// config/auth.ts
+import { anonymous } from "better-auth/plugins";
+import { getContext } from "questpie";
+import { authConfig } from "questpie/app";
+import type { App } from "#questpie"; // type-only — no runtime cycle
+
+export default authConfig({
+	plugins: [
+		anonymous({
+			// Fires when an anonymous user signs in with a real account —
+			// re-point the guest's rows onto the new user before the plugin
+			// deletes the anonymous user.
+			onLinkAccount: async ({ anonymousUser, newUser }) => {
+				const { app } = getContext<App>();
+				// Bare { accessMode: "system" } elevates ONLY the mode —
+				// session, db, and locale inherit from the request scope (ALS).
+				await app.collections.memberships.updateMany(
+					{
+						where: { user: anonymousUser.user.id },
+						data: { user: newUser.user.id },
+					},
+					{ accessMode: "system" },
+				);
+			},
+		}),
+	],
+});
+```
+
+### Partial Context Overrides
+
+CRUD context normalization merges what you pass with the ambient request scope — priority: explicit param → ALS scope → defaults (`accessMode: "system"`, `locale: "en"`). Passing only `{ accessMode: "system" }` elevates the mode while the request's session/db/locale ride along. The inverse also holds: `{ accessMode: "user" }` inside system-scoped code re-enables access rules against the inherited session without re-threading it:
+
+```ts
+// Inside any handler — session comes from the request ALS scope
+await app.collections.posts.find({}, { accessMode: "user" }); // rules enforced for the current user
+await app.collections.posts.find({}, { accessMode: "system" }); // rules bypassed, same session/locale
+```
+
+## Client-Side Auth (authClient)
+
+For session state and sign-in/out on the frontend, create a typed Better Auth client. In admin-equipped apps use the typed wrapper (session includes your merged user fields):
+
+```ts
+// src/lib/auth-client.ts
+import { createAdminAuthClient } from "@questpie/admin/client";
+import type { AppConfig } from "#questpie";
+import { env } from "#questpie/env.client.vite"; // generated from env.client.ts
+
+export const authClient = createAdminAuthClient<AppConfig>({
+	baseURL: typeof window !== "undefined" ? window.location.origin : env.APP_URL,
+	basePath: "/api/auth",
+});
+```
+
+```tsx
+const { data: session, isPending } = authClient.useSession();
+await authClient.signIn.email({ email, password });
+await authClient.signIn.anonymous(); // with the anonymous plugin
+await authClient.signOut();
+```
+
+Apps without `@questpie/admin` use Better Auth's own `createAuthClient` from `better-auth/react` pointed at `${APP_URL}/api/auth` — same call surface, without the app-inferred session typing.
+
 ## Environment Variables
 
 | Variable             | Required   | Description                                               |