@beignet/cli 0.0.3 → 0.0.4

package/README.md

@@ -1,25 +1,57 @@
 # @beignet/cli
 
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
 Command-line tools for creating and maintaining Beignet apps.
 
-## Create an app
+The package ships a single `beignet` bin. Generated apps install
+`@beignet/cli` as a dev dependency and add a `beignet` package script, so the
+day-to-day form inside an app is:
 
 ```bash
-bunx -p @beignet/cli beignet create my-app
+bun beignet doctor --strict
 ```
 
-Or use the package binary directly:
+With npm use `npm run beignet -- doctor --strict`, with pnpm
+`pnpm beignet doctor --strict`, and with yarn `yarn beignet doctor --strict`.
+For one-off runs outside an app, invoke the scoped package directly:
+
+```bash
+bunx @beignet/cli routes
+```
+
+Never run the unscoped `beignet` name through bunx or npx; that npm name
+belongs to an unrelated package.
+
+## Create an app
+
+App scaffolding lives in the `create-beignet` package:
 
 ```bash
-bunx -p @beignet/cli create-beignet my-app
+npm create beignet@latest my-app
+# or
+bun create beignet my-app
 ```
 
+Both delegate to `beignet create`, so `bunx @beignet/cli create my-app` is
+equivalent.
+
+Running create in an interactive terminal without selection flags opens a
+prompt-based setup that asks for the project directory, preset, features,
+integrations, and package manager. Passing any selection flag
+(`--preset`, `--features`, `--integrations`, or `--package-manager`) skips the
+prompts, and `--yes` forces the non-interactive defaults (the `standard`
+preset with `bun`) even on a terminal. Non-interactive runs in scripts and CI
+behave exactly as before.
+
 By default the CLI creates a Next.js app with:
 
 - Contract-first todos API routes
 - Better Auth routes and Beignet auth provider wiring
 - Drizzle/libSQL persistence with a local SQLite default and Turso-ready config
-- UOW, audit logging, and a durable outbox drain route
+- UOW, audit logging, durable idempotency, and a durable outbox drain route
 - Jobs, events, listeners, schedules, mail-backed notifications, and uploads
 - App-owned ports with provider-backed infra adapters
 - Validated application use cases
@@ -30,31 +62,52 @@ By default the CLI creates a Next.js app with:
 - React Hook Form
 - OpenAPI output
 
+Preview the planned files without writing anything:
+
+```bash
+bunx @beignet/cli create my-app --dry-run
+bunx @beignet/cli create my-app --dry-run --json
+```
+
 The CLI writes files only. After creation:
 
 ```bash
 cd my-app
 bun install
 cp .env.example .env.local
+bun beignet db generate
+bun beignet db migrate
 bun run dev
 ```
 
-Common follow-up commands:
+Open `http://localhost:3000` for the starter UI. The generated homepage links
+to the todo feature, health check, OpenAPI document, devtools, and Beignet
+docs.
+
+Inspect the app, then generate the next feature:
 
 ```bash
 # in another terminal, from my-app
-bunx -p @beignet/cli beignet make feature projects
-bunx -p @beignet/cli beignet db generate
-bunx -p @beignet/cli beignet db migrate
-bunx -p @beignet/cli beignet routes
-bunx -p @beignet/cli beignet lint
-bunx -p @beignet/cli beignet doctor
+bun beignet routes
+bun beignet lint
+bun beignet doctor
+bun beignet make feature projects
+bun beignet db generate
+bun beignet db migrate
+bun run test
+bun run typecheck
+bun beignet lint
+bun beignet doctor
 ```
 
 ## Options
 
 ```bash
-beignet create <directory> [options]
+beignet create [directory] [options]
+beignet task run <name> [options]
+beignet outbox drain [options]
+beignet schedule run <name> [options]
+beignet make task <feature>/<name> [options]
 beignet make contract <name> [options]
 beignet make event <feature>/<name> [options]
 beignet make factory <feature>/<name> [options]
@@ -74,32 +127,104 @@ beignet db generate [--dry-run] [--json]
 beignet db migrate [--dry-run] [--json]
 beignet db seed [--dry-run] [--json]
 beignet db reset [--dry-run] [--json]
-beignet routes [--json]
-beignet lint [--json]
-beignet doctor [--json] [--strict] [--fix]
+beignet routes [--json] [--cwd <dir>]
+beignet lint [--json] [--cwd <dir>] [--format human|json|github]
+beignet doctor [--json] [--strict] [--fix] [--cwd <dir>] [--format human|json|github]
+beignet completion install [--shell bash|zsh]
+beignet completion uninstall [--shell bash|zsh]
+beignet --version
 
 Options:
   --template next              Template to use. Currently only `next`.
-  --preset standard           `minimal` or `standard`.
+  --preset standard           `minimal` or `standard`. Defaults to `standard`.
   --package-manager bun       Package manager shown in next steps.
-  --feature react-query        Add a starter feature. Repeatable.
-  --features client,openapi    Add features from a comma-separated list.
-  --integration inngest        Add an integration. Repeatable.
-  --integrations inngest,pino  Add integrations from a comma-separated list.
+  --features client,openapi    Add starter features. Accepts one value or a comma-separated list.
+  --integrations inngest,pino  Add integrations. Accepts one value or a comma-separated list.
+  --yes                       Skip interactive create prompts and use the defaults.
   --force                     Write into a non-empty directory.
-  --dry-run                   Preview make writes without changing files.
+  --dry-run                   Preview create/make writes without changing files.
   --json                      Print machine-readable output.
-  --with policy,events        Add optional artifacts to `make feature`; also supports jobs, notifications, uploads.
+  --cwd path/to/app           Run routes, lint, or doctor against another app directory.
+  --format github             Output format for lint and doctor: human, json, or github.
+  --input '{"dryRun":true}'   JSON input for `beignet task run`.
+  --payload '{"date":"..."}'  JSON payload for `beignet schedule run`.
+  --module server/tasks.ts    Override the task, outbox, or schedule registry path.
+  --batch-size 100            Maximum outbox messages to claim in one drain pass.
+  --scheduled-at 2026-01-01   Provider scheduled timestamp for schedule runs.
+  --triggered-at 2026-01-01   Trigger timestamp for schedule runs.
+  --attempt 1                 One-based provider attempt number for schedule runs.
+  --source manual             Provider or app source label for schedule runs.
+  --with policy,events        Add optional artifacts to `make feature`; also supports tasks, jobs, notifications, ui, uploads.
+  --auth                      Add authorization metadata, policy wiring, policy tests, and use-case gate checks to `make resource`.
+  --tenant                    Add tenant-scoped schemas, repository filters, and use-case tenant checks to `make resource`.
+  --events                    Add created, updated, and deleted domain events to `make resource`.
+  --soft-delete               Archive resource rows with deletedAt instead of hard-deleting them.
   --event posts/published     Event for `make listener`.
   --cron "0 9 * * *"          Cron expression for `make schedule`.
   --timezone America/Chicago  Timezone for `make schedule`.
   --route                     Add a Next.js cron route for `make schedule`.
   --strict                    Include CI-oriented doctor warnings and fail on warnings.
   --fix                       Apply low-risk doctor fixes before reporting.
+  --shell zsh                 Shell for `completion install`/`uninstall`. Defaults to $SHELL.
   -h, --help                  Show help.
+  -v, --version               Print the CLI version.
+```
+
+## Exit codes
+
+Every command uses the same exit-code matrix:
+
+| Code | Meaning                                                                  |
+| ---- | ------------------------------------------------------------------------ |
+| 0    | Success.                                                                  |
+| 1    | Findings: lint diagnostics, doctor errors, or strict-mode doctor warnings. |
+| 2    | Usage or internal errors: unknown commands, bad flags, missing arguments, runtime failures, or running `beignet` with no arguments. |
+
+`--format` never changes the exit code; `lint --format github` still exits 1
+when it finds diagnostics.
+
+## Output formats
+
+`lint` and `doctor` support three output formats. `--json` stays the
+canonical machine-readable flag; `--format` adds GitHub Actions annotations:
+
+```bash
+beignet lint --format github
+beignet doctor --strict --format github
+```
+
+The github format emits one `::error`, `::warning`, or `::notice` workflow
+command per diagnostic, with `file`, `line`, and `col` properties when known.
+When `GITHUB_ACTIONS=true` is set and no format is passed, lint and doctor
+default to the github format; otherwise they default to human output.
+Combining `--json` with a conflicting `--format` is an error. Human output
+groups doctor diagnostics by severity, colors severity labels on TTYs, and
+respects `NO_COLOR`.
+
+All `--json` results begin with `schemaVersion: 1` so other tools can detect
+output-shape changes.
+
+## Shell completions
+
+Install tab completions for the `beignet` bin into your shell rc file:
+
+```bash
+beignet completion install
+beignet completion install --shell zsh
+beignet completion uninstall
 ```
 
-## App conventions
+`install` writes a managed block to `~/.bashrc` or `~/.zshrc` (detected from
+`$SHELL` when `--shell` is omitted) and `uninstall` removes it. Restart your
+shell or source the rc file to activate completions. Zsh completions require
+`compinit` to be loaded, which most zsh setups already do.
+
+Completions cover commands, subcommands, flags, and enum flag values such as
+`--preset` and `--features`. The shell scripts call the
+`beignet completion propose` helper, which prints one proposal per line for a
+partial command line; it exists for the shell integration and is safe to
+ignore otherwise. Completions complete whatever `beignet` resolves to on your
+`PATH`, such as the app-local bin installed by generated apps.
 
 Beignet CLI commands are convention-aware. `routes`, `lint`, `doctor`, and
 generators work best in the Next.js layout created by `beignet create`:
@@ -107,12 +232,17 @@ generators work best in the Next.js layout created by `beignet create`:
 ```txt
 features/
 app/api/
+server/context.ts
 server/index.ts
 server/routes.ts
 ```
 
+`server/context.ts` declares the app's context blueprint with
+`defineServerContext(...)`; `server/index.ts` passes it to the server and
+generated route tests pass the same value to `createTestApp(...)`.
+
 Route inspection supports contract-group definitions and direct
-`createContract({ method, path })` exports.
+`defineContract({ method, path })` exports.
 
 The standard app layout includes the files feature generators expect:
 
@@ -123,6 +253,11 @@ ports/index.ts
 lib/use-case.ts
 ```
 
+Standard apps also include context-bound capability builders in `lib/`
+(`lib/listeners.ts`, `lib/jobs.ts`, `lib/schedules.ts`, and
+`lib/notifications.ts`); generators create missing builder files on demand,
+including `lib/tasks.ts`.
+
 Generated apps include these files by default. The CLI uses this shape to
 inspect routes, wire generated features, and report drift safely. `beignet
 doctor` reports when a directory does not match the app layout.
@@ -141,6 +276,9 @@ export default defineConfig({
 		features: "src/features",
 		routes: "src/app/api",
 		server: "src/core/server/index.ts",
+		tasks: "src/core/server/tasks.ts",
+		outbox: "src/core/server/outbox.ts",
+		schedules: "src/core/server/schedules.ts",
 	},
 });
 ```
@@ -168,7 +306,8 @@ divergent files unless you pass `--force`.
 
 ## Generate a feature
 
-Inside a Beignet app, scaffold the standard contract-first vertical slice with:
+Inside a Beignet app, scaffold the standard contract-first vertical slice for a
+product capability or workflow with:
 
 ```bash
 beignet make feature projects
@@ -193,7 +332,7 @@ around the feature's real workflow.
 Add common feature-owned artifacts with `--with`:
 
 ```bash
-beignet make feature projects --with policy,events,jobs,uploads
+beignet make feature projects --with policy,events,jobs,notifications,ui,uploads
 ```
 
 The optional artifacts use predictable starter names:
@@ -201,10 +340,20 @@ The optional artifacts use predictable starter names:
 - `features/projects/policy.ts`
 - `features/projects/domain/events/created.ts`
 - `features/projects/jobs/process.ts`
+- `features/projects/notifications/created.ts`
+- `features/projects/components/projects-panel.tsx`
 - `features/projects/uploads/attachment.ts`
 
-Event, job, and upload registries are created or updated in the matching
-folder `index.ts` files.
+Event, job, notification, and upload registries are created or updated in the
+matching folder `index.ts` files. The UI addon is opt-in:
+
+```bash
+beignet make feature projects --with ui
+```
+
+It writes a feature-colocated React component that uses the generated
+contracts through `client/index.ts` and TanStack Query, with error messages
+from `contractErrorMessage` in `@beignet/core/client`.
 
 ## Generate a use case
 
@@ -223,7 +372,10 @@ The name uses `feature/action` format. The command writes
 
 ## Generate a test
 
-Use `make test` after generating a use case:
+Use `make test` after generating a focused use case. Generated features and
+resources already include their baseline contract, use-case, route, policy, and
+repository-oriented tests; `make test` is for adding coverage around an
+additional workflow that does not need a whole new resource slice.
 
 ```bash
 beignet make use-case projects/archive-project
@@ -231,7 +383,8 @@ beignet make test projects/archive-project
 ```
 
 The command writes `features/projects/tests/archive-project.test.ts`, builds the
-app context through `createUseCaseTester`, and asserts the starter
+app context through `createTestPorts(...)`, `createTestContextFactory(...)`, and
+`createUseCaseTester(...)`, and asserts the starter
 `{ ok: true }` response. It also adds a `test` script when the app does not
 already define one. Treat the output as a compiling starting point: replace the
 input, context setup, and assertion with behavior-specific coverage as the use
@@ -284,27 +437,52 @@ was already customized, the command stops instead of guessing.
 
 ## Generate a resource
 
-Use `make resource` when the feature you are building is CRUD-shaped and you
-prefer resource language:
+Use `make resource` when the feature you are building is CRUD-shaped and the
+main concept is an entity with repository-backed persistence:
 
 ```bash
 beignet make resource projects
+beignet make resource projects --auth --tenant --events --soft-delete
 ```
 
-Today `make resource` and `make feature` generate the same contract-to-test
-slice. The feature command is the recommended default because not every Beignet
-feature maps cleanly to a REST resource.
+`make resource` generates a CRUD-shaped slice with list, create, get, update,
+and delete contracts, use cases, route handlers, repository methods, a policy
+starter, tests, and feature-specific not-found and conflict catalog errors. Use
+`make feature` for workflows and capabilities that do not map cleanly to a REST
+resource.
+
+Generated list routes use cursor pagination with `limit`, `cursor`, `name`,
+`sortBy`, and `sortDirection` query parameters. The generated use case
+normalizes cursor pages, validates opaque base64url cursors against the selected
+sort, and passes one repository query object into memory and Drizzle adapters.
+Adapters filter `name` with case-insensitive contains matching, sort only by
+`createdAt` or `name` plus `id`, and fetch `limit + 1` records to derive
+`nextCursor` without a count query.
+
+Generated resources also include optimistic concurrency by default. Responses
+include a numeric `version`; update request bodies must send that version back;
+memory and Drizzle repositories include the version in the update check and
+increment it on success. Stale updates become the generated
+`<Resource>Conflict` catalog error.
+
+Use `--auth` to generate authorization metadata, policy wiring, and use-case
+`ctx.gate.authorize(...)` calls. Use `--tenant` to scope repository reads and
+writes by `ctx.tenant`. Use `--events` to generate created, updated, and
+deleted domain events and publish them through `ctx.ports.eventBus`. Use
+`--soft-delete` when delete routes should archive rows with `deletedAt` while
+list, get, and update operations continue to read only active records.
 
 In standard apps, the command also creates
 `infra/db/schema/projects.ts`,
 `infra/projects/drizzle-project-repository.ts`, and registers the repository in
 `infra/db/repositories.ts`.
 
-## Generate events, jobs, notifications, listeners, schedules, and uploads
+## Generate tasks, events, jobs, notifications, listeners, schedules, and uploads
 
 Use feature artifact generators when a workflow grows beyond a single use case:
 
 ```bash
+beignet make task posts/backfill-search
 beignet make event posts/published
 beignet make job posts/send-published-email
 beignet make notification posts/published
@@ -315,6 +493,7 @@ beignet make upload posts/attachment
 
 These commands use `feature/name` format and write colocated feature files:
 
+- `features/posts/tasks/backfill-search.ts`
 - `features/posts/domain/events/published.ts`
 - `features/posts/jobs/send-published-email.ts`
 - `features/posts/notifications/published.ts`
@@ -323,17 +502,73 @@ These commands use `feature/name` format and write colocated feature files:
 - `features/posts/uploads/attachment.ts`
 
 Each command creates or updates the folder's `index.ts` with an exported
-registry such as `postJobs`, `postNotifications`, `postListeners`,
-`postSchedules`, or `postUploads`. Event and listener generators add
-`@beignet/core/events`, job generators use `@beignet/core/jobs`, notification
-generators use `@beignet/core/notifications`, schedule generators use
-`@beignet/core/schedules`, and upload generators use `@beignet/core/uploads`.
+registry such as `postTasks`, `postJobs`, `postNotifications`,
+`postListeners`, `postSchedules`, or `postUploads`. Task generators also
+create or update `server/tasks.ts`, which is the registry and lifecycle
+boundary used by `beignet task run <name> --input '{"dryRun":true}'`.
+New task registries include `createTaskContext(...)` and
+`stopTaskContext(...)` placeholders so provider startup and teardown stay
+out of task definitions.
+
+Task, job, listener, schedule, and notification generators define artifacts
+through app-owned context-bound builders in `lib/`. Each generator creates the
+builder file when it is missing:
+
+- `lib/tasks.ts` exports `defineTask` from `createTasks<AppContext>()`
+  (`@beignet/core/tasks`)
+- `lib/jobs.ts` exports `defineJob` from `createJobs<AppContext>()`
+  (`@beignet/core/jobs`)
+- `lib/listeners.ts` exports `defineListener` from
+  `createListeners<AppContext>()` (`@beignet/core/events`)
+- `lib/schedules.ts` exports `defineSchedule` from
+  `createSchedules<AppContext>()` (`@beignet/core/schedules`)
+- `lib/notifications.ts` exports `defineNotification` from
+  `createNotifications<AppContext>()` (`@beignet/core/notifications`)
+
+Event generators use `@beignet/core/events` directly and upload generators use
+`@beignet/core/uploads`.
 `--route` also writes a Next.js cron
 route under `app/api/cron/<feature>/<name>/route.ts`. Generated cron routes
 require `CRON_SECRET` and record schedule start, completion, and failure events
 in devtools. Generated uploads include starter metadata, constraints,
 authorization, storage key, storage metadata, and completion hooks.
 
+Use `beignet outbox drain` when you need to drain durable events and jobs from
+an app-owned CLI, CI, or worker entrypoint:
+
+```bash
+beignet outbox drain --batch-size 100
+```
+
+The runner loads `server/outbox.ts` or `paths.outbox`. That module should export
+`outboxRegistry`, `createOutboxDrainContext(...)`, and optionally
+`stopOutboxDrainContext(...)`. The context owns app ports and provider
+lifecycle, so the CLI drain uses the same outbox, event bus, jobs,
+instrumentation, actor, and tenant decisions as the scheduled drain route.
+
+There is intentionally no separate `beignet jobs drain` command. Outbox-backed
+jobs drain through the outbox beside durable events. Direct provider jobs should
+use provider-owned worker entrypoints, such as an Inngest route built with
+`createInngestJobFunction(...)`.
+
+Use `beignet schedule run` when you need to run a schedule explicitly from a
+local shell, CI job, or worker entrypoint:
+
+```bash
+beignet schedule run posts.log-daily-summary --scheduled-at 2026-01-01T09:00:00.000Z
+```
+
+The runner loads `server/schedules.ts` or `paths.schedules`. That module should
+export a `schedules` array, `createScheduleContext(...)`, and optionally
+`stopScheduleContext(...)`. Omit `--payload` when the schedule should build its
+own payload from `createPayload(...)`; pass `--payload` when a provider or manual
+run supplies the payload.
+
+Operational CLI commands are bounded entrypoints. Use them from a local shell,
+CI job, release job, scheduler, or worker host. Do not start outbox drains,
+queue consumers, or interval polling from provider lifecycle hooks in serverless
+apps.
+
 `make listener` expects the event file to exist at the canonical generated path.
 Run `make event <feature>/<event>` first, then generate listeners for that event.
 
@@ -359,9 +594,16 @@ run Drizzle Kit and the generated `infra/db/seed.ts` / `infra/db/reset.ts`
 entrypoints. This keeps schema generation and migration behavior Drizzle-native
 while making the lifecycle discoverable through Beignet.
 
+`beignet db` checks standard prerequisites before running those scripts. If the
+script is missing, Drizzle Kit has no `drizzle.config.*`, or the standard
+seed/reset entrypoint was removed, the error points to the exact file or
+package script to restore.
+
 `db reset` is intentionally app-owned because destructive behavior depends on
 the environment. The standard starter refuses to reset non-local database URLs
-unless `BEIGNET_ALLOW_DATABASE_RESET=true` is set.
+unless `BEIGNET_ALLOW_DATABASE_RESET=true` is set. Drizzle starters also include
+`infra/db/test-database.ts`, which creates an isolated local libSQL database for
+repository and persistence tests.
 
 Generate feature-owned test factories and local/demo seeds with:
 
@@ -375,6 +617,12 @@ through app-owned repository ports. Seeds are written under
 `features/posts/seeds/`; import them from the app-owned database seed entrypoint
 and run them with `runSeeds(...)`.
 
+Generated feature and use-case tests use Beignet's test context helpers so
+request IDs, actors, tenants, and ports follow the same pattern as the testing
+docs. Generated route tests boot `createTestApp(...)` with the app's
+`server/context.ts` blueprint, so HTTP coverage exercises the same identity
+resolution as production.
+
 Preview writes without changing files:
 
 ```bash
@@ -409,22 +657,30 @@ Run `lint` when you want the CLI to enforce Beignet dependency direction:
 beignet lint
 ```
 
-The command scans static imports and fails when core feature layers reach into
-runtime or framework layers. It catches domain, use case, workflow, policy,
-port, contract, and route files importing things like `infra/`, UI components,
-client modules, provider packages, Next.js, React, or database vendors in the
-wrong direction. Workflow folders include feature-owned jobs, listeners,
-notifications, schedules, and uploads.
+The command scans static imports and fails when app layers reach into runtime
+or framework layers. It catches domain, use case, workflow, policy, port,
+contract, route, infra, and component files importing things like `infra/`, UI
+components, route handlers, server modules, client modules, provider packages,
+Next.js, React, or database vendors in the wrong direction. It also catches
+feature-specific domain files importing another feature's domain unless the
+target is `features/shared/domain`. Workflow folders include feature-owned
+jobs, listeners, notifications, schedules, and uploads.
 
-Use JSON output in CI or custom scripts:
+Import diagnostics include 1-based `line` and `column` positions. Human
+output prints clickable `file.ts:12:3` locations; runtime-boundary
+diagnostics report the chain root file and the full import chain in the
+message instead.
+
+Use JSON output in CI or custom scripts, or GitHub annotations in workflows:
 
 ```bash
 beignet lint --json
+beignet lint --format github
 ```
 
 ## Check for drift
 
-Run `doctor` when you want quick feedback on contract wiring drift:
+Run `doctor` when you want a framework integrity report:
 
 ```bash
 beignet doctor
@@ -435,38 +691,85 @@ Today it detects:
 - Contracts without a matching Next.js route handler
 - Feature route groups that are not registered in the central route list
 - Next.js route handlers that do not map to known contracts
-- OpenAPI drift in direct arrays and common exported contract lists
+- OpenAPI drift in direct arrays, exported contract lists, and
+  `contractsFromRoutes(routes)` route registries
+- OpenAPI entries for contracts outside the registered route surface
+- Strict-mode canonical app conformance drift, including missing app context,
+  server route/provider registries, app ports, client helpers, typed route
+  groups, and local `AppContext` redeclarations
 - Partially wired generated feature slices
+- CRUD resource slices missing generated contracts, use cases, repository
+  methods, route entries, not-found catalog errors, or strict-mode test coverage
+- Route-owned catalog errors declared on contracts but missing from
+  `features/shared/errors.ts`
+- Feature runtime `appError(...)` calls that are not declared on the feature's
+  contracts
+- Authorization metadata whose ability is missing from feature policy coverage
+- Audit-required metadata without feature audit writes or test assertions
+- Mixed `@beignet/*` version ranges in package.json, and mixed installed
+  `@beignet/*` versions in node_modules; the packages release together, so one
+  app should use one version
+- CLI versions that differ from the app's installed `@beignet/core`, reported
+  as an informational hint that suggests the app-local `bun beignet`
+- Malformed installed provider package metadata
 - Provider packages without matching canonical app ports
+- Installed lifecycle provider packages that are not registered in
+  `server/providers.ts`, reported as an informational hint when the provider
+  declares registration as optional, such as `@beignet/devtools`
+- App database providers registered before the provider that installs `db`
 - Generated ports without test fakes
 - Drizzle repository adapters that are not wired through `infra/db/repositories.ts`
 - Repository ports whose infra folder has no repository adapter
+- Missing Drizzle config, schema index exports, database scripts, or standard seed/reset entrypoints
+- Single-file `infra/db/schema.ts` schemas that should move to the
+  `infra/db/schema/` directory form
+- Feature tests placed directly under `features/<feature>/` instead of
+  `features/<feature>/tests/`
+- Standard database reset entrypoints that no longer guard non-local resets
 - Feature seeds without a matching feature factory
 - Feature seeds without a `db:seed` package script
 - Upload definitions without an upload route
+- Upload definitions without explicit size limits
+- Devtools routes that are explicitly enabled without authorization
+- Cron routes that do not use `CRON_SECRET`
+- Installed provider packages without expected environment configuration
+- Better Auth providers without an auth route or trusted-origin configuration
+- Credentialed wildcard CORS configuration
 - Notification dispatchers that bypass `ctx.ports.notifications`
 - Feature artifacts in non-canonical folders
 
-Use `beignet doctor --strict` for CI-oriented checks that may be noisy
-locally, such as missing generated feature tests. Use
-`beignet doctor --json` in CI or custom scripts.
+Provider package diagnostics come from package-owned `beignet.provider`
+metadata in installed package manifests. The CLI does not import provider
+implementation modules to discover those facts, and it reports malformed
+metadata before using provider-derived doctor rules.
+
+Use `beignet doctor --strict` for CI-oriented checks that may be noisy locally,
+such as missing generated feature tests, canonical app conformance drift, and
+feature-owned route errors that appear unused. Strict mode fails on warnings as
+well as errors; informational hints never affect the exit code, so an
+installed-but-unregistered optional provider such as `@beignet/devtools` still
+passes `doctor --strict`. Use
+`beignet doctor --json` in CI or custom scripts. Doctor JSON includes
+`schemaVersion: 1` plus `targetDir`, `config`, `strict`, `convention`,
+`contracts`, `routes`, `diagnostics`, and `fixes`.
 
 Use `beignet doctor --fix` for low-risk maintenance fixes. Today it can add
-a missing `test` script and repair direct `createOpenAPIHandler([...])` arrays
-when the missing contracts are already imported in the OpenAPI route.
+a missing `test` script, register existing feature route groups in the central
+route list, and repair direct `createOpenAPIHandler([...])` arrays when the
+missing contracts are already imported in the OpenAPI route.
 
 Available presets:
 
 - `minimal` - choose this when you want the small contract/core/server/use-case loop without the full app conventions.
-- `standard` - choose this when you want the full app layout with Better Auth, Drizzle/libSQL, UOW, outbox, audit logging, devtools, provider wiring, health checks, typed clients, feature-owned jobs/events/schedules/uploads/notifications, and separated `ports/` + `infra/`.
+- `standard` - choose this when you want the full app layout with Better Auth, Drizzle/libSQL, UOW, durable idempotency, outbox, audit logging, devtools, provider wiring, health checks, typed clients, feature-owned jobs/events/schedules/uploads/notifications, and separated `ports/` + `infra/`.
 
 The standard preset includes the local production-shaped defaults: Better Auth,
-Drizzle/libSQL, Pino logging, local storage, devtools, UOW, outbox, audit
+Drizzle/libSQL, Pino logging, local storage, devtools, UOW, durable idempotency, outbox, audit
 logging, and feature-owned background workflow examples. Add external service
 integrations only when you want those providers:
 
 ```bash
-bunx -p @beignet/cli beignet create my-app --preset standard --integrations drizzle-turso,inngest,resend
+bun create beignet my-app --preset standard --integrations drizzle-turso,inngest,resend
 ```
 
 Available features:
@@ -485,7 +788,16 @@ Available integrations:
 - `resend`
 - `upstash-rate-limit`
 
-With `--preset standard`, Drizzle/libSQL is included by default. The starter scaffolds `infra/db/schema/`, `infra/db/repositories.ts`, a Drizzle todo repository adapter, `drizzle.config.ts`, database scripts, and `TURSO_*` env examples so the generated todo resource uses durable persistence instead of the in-memory repository. Later `make feature` or `make resource` calls in that app generate both a Drizzle table/repository and an in-memory test fake.
+With `--preset standard`, Drizzle/libSQL is included by default. The starter scaffolds `infra/db/schema/`, `infra/db/repositories.ts`, `infra/db/test-database.ts`, SQL-backed idempotency and outbox tables, a Drizzle todo repository adapter, `drizzle.config.ts`, database scripts, and `TURSO_*` env examples so the generated todo resource uses durable persistence instead of the in-memory repository. Later `make feature` or `make resource` calls in that app generate both a Drizzle table/repository and an in-memory test fake.
+
+With `--preset minimal --integrations drizzle-turso`, the starter keeps the
+small app shape and scaffolds the smallest durable wiring: `drizzle.config.ts`,
+a todos-only schema in `infra/db/schema/`, a Drizzle todo repository in
+`infra/todos/`, and an app-owned database provider in `infra/db/provider.ts`
+that contributes the deferred `todos` port and creates and seeds the starter
+table at startup. The generated `db:generate` and `db:migrate` scripts work
+with `beignet db ...`; the `db:seed` and `db:reset` scripts are
+standard-preset-only because their entrypoints are not scaffolded.
 
 With `--preset standard`, Better Auth is included by default. The starter adds
 the Better Auth Next.js route, Beignet auth provider wiring, typed
@@ -493,6 +805,12 @@ the Better Auth Next.js route, Beignet auth provider wiring, typed
 `requireUser(ctx)`. Use hooks for HTTP boundary authentication and use cases or
 policies for business authorization.
 
+With `--preset minimal --integrations better-auth`, the starter wires an
+app-owned `lib/better-auth.ts` backed by Better Auth's in-memory adapter, the
+`app/api/auth/[...all]` route, `createAuthBetterAuthProvider(...)` behind a
+deferred `auth` port, and an `auth` session on the request context. Users and
+sessions reset on restart; switch to a database adapter before production.
+
 ## License
 
 MIT