cvx-kit 0.1.3 → 0.1.5

package/docs/llms.md

@@ -9,6 +9,9 @@
 > authoritative. Restructuring an existing raw project → `migration.md`.
 > Upgrading from 0.0.x → `upgrading.md`. New 0.1.0 helpers: `crud.md`,
 > `webhooks.md`, `agent-tools.md`; pagination in `zod-table.md`/`auth.md`.
+> Consumer lint configuration and coverage → `oxlint.md`. The optional
+> `cvx-kit/oxlint` plugin checks the statically detectable conventions;
+> behavioral guarantees still need architecture and runtime tests.
 
 > **Placeholders.** Names like `documents`, `users`, `history`, `title`,
 > `ownerId`, and `documentPublish` in the examples below are illustrative
@@ -33,7 +36,7 @@ function constructors, a trigger registry, an audited command protocol
 3. **Every public query returns DTOs** via `<table>.toPublicDto(row)` —
    runtime redaction, not just types.
 4. **Every read is bounded**: `ctx.include(ctx.db.query('t')).matching(...)
-   .execute(limit)` with `1 ≤ limit ≤ 100`. `.resolve()` falls back to a full
+.execute(limit)` with `1 ≤ limit ≤ 100`. `.resolve()` falls back to a full
    table scan — avoid it.
 5. **State changes are commands**: an operations registry with mandatory
    `classification` and `audit()` per operation, executed via
@@ -60,31 +63,31 @@ function constructors, a trigger registry, an audited command protocol
 9. **Operation names are `domain.verb` lowercase-dotted; error codes are
    UPPER_SNAKE** — otherwise observability silently drops the events.
 10. **Row-level security is configured, not hand-rolled**: the optional
-   `security` config on `createAuthFunctions` takes role-level `rules`
-   (works standalone) and/or `tenancy` (a table registry; adds
-   `ctx.tenant`, deny-default isolation, and pairs with `tenantTable` +
-   `tenantOwnership`). Multi-tenant apps stamp inserts with
-   `tenant: ctx.tenant` and re-verify client ids with
-   `requireTenantReference`. See `tenancy.md`.
+    `security` config on `createAuthFunctions` takes role-level `rules`
+    (works standalone) and/or `tenancy` (a table registry; adds
+    `ctx.tenant`, deny-default isolation, and pairs with `tenantTable` +
+    `tenantOwnership`). Multi-tenant apps stamp inserts with
+    `tenant: ctx.tenant` and re-verify client ids with
+    `requireTenantReference`. See `tenancy.md`.
 
 ## Exports map
 
-| Import | Provides |
-|---|---|
-| `cvx-kit` | everything below re-exported (except components' defaults) |
-| `cvx-kit/zod-table` | `zodTable`, `tenantTable`, `createModule`, `paginated`, `zodVariantTable`, `jsonSafeZid`, `TIMESTAMP_FIELDS` |
-| `cvx-kit/auth` | `createAuthFunctions` (incl. optional `security` RLS config), `createInclude`, `defaultRoleMap` |
-| `cvx-kit/tenancy` | `createTenantRules`, `composeRules`, `requireTenantReference`, `assertTenantOwned`, `TENANT_FIELD` |
-| `cvx-kit/crud` | `createCrudCommands` — create/update/archive from a zodTable, inside the command pipeline; `enrich` REQUIRED for tenantTables |
-| `cvx-kit/state-machine` | `createStateMachine` — typed transitions from constants tuples; `assert` drops into command guards |
-| `cvx-kit/middleware` | `rateLimit` — packaged middleware over an injected rate-limiter instance; keyed by `ctx.tenant`, missing key = config error |
-| `cvx-kit/webhooks` | `createWebhookBoundary`, `recordWebhookEvent`, `webhookEventsTable` — raw-body verify, natural-key dedup in the mutation |
-| `cvx-kit/agent-tools` | `createAgentTools` — tool records from table masks; mutation handlers route through command executors |
-| `cvx-kit/triggers` | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `tenantOwnership`, `Triggers` |
-| `cvx-kit/errors` | `KitError`, `defaultErrors`, `ErrorFactory` |
+| Import                          | Provides                                                                                                                                                                                                                                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cvx-kit`                       | everything below re-exported (except components' defaults)                                                                                                                                                                                                              |
+| `cvx-kit/zod-table`             | `zodTable`, `tenantTable`, `createModule`, `paginated`, `zodVariantTable`, `jsonSafeZid`, `TIMESTAMP_FIELDS`                                                                                                                                                            |
+| `cvx-kit/auth`                  | `createAuthFunctions` (incl. optional `security` RLS config), `createInclude`, `defaultRoleMap`                                                                                                                                                                         |
+| `cvx-kit/tenancy`               | `createTenantRules`, `composeRules`, `requireTenantReference`, `assertTenantOwned`, `TENANT_FIELD`                                                                                                                                                                      |
+| `cvx-kit/crud`                  | `createCrudCommands` — create/update/archive from a zodTable, inside the command pipeline; `enrich` REQUIRED for tenantTables                                                                                                                                           |
+| `cvx-kit/state-machine`         | `createStateMachine` — typed transitions from constants tuples; `assert` drops into command guards                                                                                                                                                                      |
+| `cvx-kit/middleware`            | `rateLimit` — packaged middleware over an injected rate-limiter instance; keyed by `ctx.tenant`, missing key = config error                                                                                                                                             |
+| `cvx-kit/webhooks`              | `createWebhookBoundary`, `recordWebhookEvent`, `webhookEventsTable` — raw-body verify, natural-key dedup in the mutation                                                                                                                                                |
+| `cvx-kit/agent-tools`           | `createAgentTools` — tool records from table masks; mutation handlers route through command executors                                                                                                                                                                   |
+| `cvx-kit/triggers`              | `createTriggers`, `timestamps`, `appendOnly`, `noDelete`, `tenantOwnership`, `Triggers`                                                                                                                                                                                 |
+| `cvx-kit/errors`                | `KitError`, `defaultErrors`, `ErrorFactory`                                                                                                                                                                                                                             |
 | `cvx-kit/components/foundation` | `Foundation` — the ONLY runtime export besides the default component config for `app.use`. Everything (`Command`, `Query`, `observability`, `executeResultBoundary`, `projectResult`, `emitSemanticEvent`) destructures from the instance; nothing is importable loose. |
-| `cvx-kit/components/approvals` | `Approvals` client; default export = component config for `app.use` |
-| `cvx-kit/test` | `registerFoundation(t)`, `registerApprovals(t)` for convex-test |
+| `cvx-kit/components/approvals`  | `Approvals` client; default export = component config for `app.use`                                                                                                                                                                                                     |
+| `cvx-kit/test`                  | `registerFoundation(t)`, `registerApprovals(t)` for convex-test                                                                                                                                                                                                         |
 
 ## Minimal app wiring (the five root files)
 
@@ -105,27 +108,47 @@ timestamps(triggers, 'documents')
 appendOnly(triggers, 'history')
 
 // convex/functions.ts
-export const { authQuery, authMutation, authAction, adminQuery, adminMutation,
-  adminAction, roleQuery, roleMutation, roleAction, systemQuery, systemMutation,
-  systemAction, include } = createAuthFunctions<DataModel>({
-  query, mutation, action, internalQuery, internalMutation, internalAction,   // from ./_generated/server
-  getAuthUser: (ctx) => authKit.getAuthUser(ctx),
-  mapRole: defaultRoleMap,          // 'member'→'writer'; reader|writer|admin pass
-  adminRoles: ['admin'],
-  triggers,
-  verifyMembership: async ({ userId, organizationId }) => { /* live check; actions only */ },
-  resolveOrganization: async ({ ctx, identity, user }) => { /* org+role from app tables; overrides claims; null/throw ⇒ FORBIDDEN */ },
+export const {
+	authQuery,
+	authMutation,
+	authAction,
+	adminQuery,
+	adminMutation,
+	adminAction,
+	roleQuery,
+	roleMutation,
+	roleAction,
+	systemQuery,
+	systemMutation,
+	systemAction,
+	include,
+} = createAuthFunctions<DataModel>({
+	query,
+	mutation,
+	action,
+	internalQuery,
+	internalMutation,
+	internalAction, // from ./_generated/server
+	getAuthUser: (ctx) => authKit.getAuthUser(ctx),
+	mapRole: defaultRoleMap, // 'member'→'writer'; reader|writer|admin pass
+	adminRoles: ['admin'],
+	triggers,
+	verifyMembership: async ({ userId, organizationId }) => {
+		/* live check; actions only */
+	},
+	resolveOrganization: async ({ ctx, identity, user }) => {
+		/* org+role from app tables; overrides claims; null/throw ⇒ FORBIDDEN */
+	},
 })
 
 // convex/foundation.ts
-export const { Command, Query, observability } = new Foundation(
-  components.foundation,
-  { observability: {
-      enabled: () => process.env.OBS === 'true',
-      classifyError,                                  // → { outcome: 'denied'|'failed', errorCode }
-      writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
-  } },
-)
+export const { Command, Query, observability } = new Foundation(components.foundation, {
+	observability: {
+		enabled: () => process.env.OBS === 'true',
+		classifyError, // → { outcome: 'denied'|'failed', errorCode }
+		writeAudit: (ctx, entry) => writeAuditEntry(ctx, entry),
+	},
+})
 
 // convex/approvals.ts
 export const approvals = new Approvals(components.approvals)
@@ -135,43 +158,58 @@ export const approvals = new Approvals(components.approvals)
 
 ```ts
 // domain/documents/schema.ts
-export const documents = zodTable('documents', (id) => ({
-  title: z.string(), ownerId: id('users'), secretNote: z.string(),
-}), {
-  commandFields: ['title'],            // what a command may say
-  publicFields: ['title', 'ownerId'],  // the DTO allowlist
-})
+export const documents = zodTable(
+	'documents',
+	(id) => ({
+		title: z.string(),
+		ownerId: id('users'),
+		secretNote: z.string(),
+	}),
+	{
+		commandFields: ['title'], // what a command may say
+		publicFields: ['title', 'ownerId'], // the DTO allowlist
+	},
+)
 
 // convex/schema.ts (via domain/table.ts)
 defineSchema({ documents: documents.table.index('by_owner', ['ownerId']) })
 
 // domain/documents/commands.ts
 const operations = {
-  'documents.rename': Command.operation({
-    command: documents.commandInput.extend({ id: zid('documents'), actorId: z.string() }),
-    result: z.object({ ok: z.literal(true) }).strict(),
-    classification: 'business',
-    audit: ({ command }) => ({ operation: 'documents.rename', actorId: command.actorId,
-      aggregate: { type: 'document', id: command.id } }),
-  }),
+	'documents.rename': Command.operation({
+		command: documents.commandInput.extend({ id: zid('documents'), actorId: z.string() }),
+		result: z.object({ ok: z.literal(true) }).strict(),
+		classification: 'business',
+		audit: ({ command }) => ({
+			operation: 'documents.rename',
+			actorId: command.actorId,
+			aggregate: { type: 'document', id: command.id },
+		}),
+	}),
 } as const
 const commands = new Command<MutationCtx, typeof operations>(operations)
-export const executeRename = commands.exec({ operation: 'documents.rename',
-  handler: async (ctx, cmd) => { await ctx.db.patch(cmd.id, { title: cmd.title }); return { ok: true } } })
+export const executeRename = commands.exec({
+	operation: 'documents.rename',
+	handler: async (ctx, cmd) => {
+		await ctx.db.patch(cmd.id, { title: cmd.title })
+		return { ok: true }
+	},
+})
 
 // api/documents.ts — thin public adapter
 export const rename = authMutation({
-  args: documents.commandInput.extend({ id: zid('documents') }),
-  returns: z.object({ ok: z.literal(true) }).strict(),
-  handler: (ctx, args) => executeRename(ctx, { ...args, actorId: ctx.actor.userId }),
+	args: documents.commandInput.extend({ id: zid('documents') }),
+	returns: z.object({ ok: z.literal(true) }).strict(),
+	handler: (ctx, args) => executeRename(ctx, { ...args, actorId: ctx.actor.userId }),
 })
 export const list = authQuery({
-  args: { limit: z.number() },
-  returns: z.array(documents.publicDto),
-  handler: (ctx, { limit }) =>
-    ctx.include(ctx.db.query('documents'))
-      .matching('by_owner', (ix) => ix.eq('ownerId', ctx.actor.userId))
-      .execute(limit, (rows) => rows.map(documents.toPublicDto)),
+	args: { limit: z.number() },
+	returns: z.array(documents.publicDto),
+	handler: (ctx, { limit }) =>
+		ctx
+			.include(ctx.db.query('documents'))
+			.matching('by_owner', (ix) => ix.eq('ownerId', ctx.actor.userId))
+			.execute(limit, (rows) => rows.map(documents.toPublicDto)),
 })
 ```
 
@@ -186,13 +224,24 @@ canonical actor for audits/approvals.
 ## Approvals in one block
 
 ```ts
-export const publishApproval = approvals.define({ name: 'documentPublish', steps: [
-  approvals.decision('managerDecision', { decisions: ['approved','rejected'],
-    quorum: { kind: 'count', approvals: 1 }, makerChecker: true, expiresAfterMs: 604_800_000 }),
-  approvals.branch('applyDecision', { approvedStepKey: 'publish', rejectedStepKey: 'notify' }),
-  approvals.mutation('publish', { handler: internal.domain.documents.approval_functions.applyDecision }),
-  approvals.notify('notify', { handler: internal.domain.documents.approval_functions.notifyRejected }),
-]})
+export const publishApproval = approvals.define({
+	name: 'documentPublish',
+	steps: [
+		approvals.decision('managerDecision', {
+			decisions: ['approved', 'rejected'],
+			quorum: { kind: 'count', approvals: 1 },
+			makerChecker: true,
+			expiresAfterMs: 604_800_000,
+		}),
+		approvals.branch('applyDecision', { approvedStepKey: 'publish', rejectedStepKey: 'notify' }),
+		approvals.mutation('publish', {
+			handler: internal.domain.documents.approval_functions.applyDecision,
+		}),
+		approvals.notify('notify', {
+			handler: internal.domain.documents.approval_functions.notifyRejected,
+		}),
+	],
+})
 // start(ctx, { scopeRef, resourceType, resourceRef, requester: ctx.actor, metadata? })
 // decide(ctx, { runId, decision, reason? }, ctx.actor) · status/evidence/list/cancel/restart
 ```

package/docs/maintainability.md

@@ -1,8 +1,8 @@
 # Maintaining a Convex application built on cvx-kit
 
 Practices that keep a cvx-kit backend maintainable over years, taken from the
-origin application. The theme throughout: make every rule either *structural*
-(the code can't be written any other way) or *executable* (a test fails when
+origin application. The theme throughout: make every rule either _structural_
+(the code can't be written any other way) or _executable_ (a test fails when
 it's violated). Conventions that live only in documentation decay.
 
 ## Schema and indexes
@@ -14,7 +14,7 @@ it's violated). Conventions that live only in documentation decay.
 - **Index naming**: `by_<field>_and_<field>...`, camelCase field names in
   declaration order, nested paths flattened with `_`
   (`by_assignedToUserId_and_state_status` for `['assignedToUserId',
-  'state.status']`). A reader should reconstruct the index definition from its
+'state.status']`). A reader should reconstruct the index definition from its
   name.
 - Every read goes through `ctx.include(...)` with an explicit limit ≤ 100.
   If a query can't be served by an index, that's a schema problem, not a
@@ -119,6 +119,6 @@ test modules the same way (`@convex-dev/workflow/test`,
    any `appendOnly`/`noDelete` discipline.
 4. `constants.ts` — vocabularies as readonly tuples.
 5. `commands.ts` — operation registry (`domain.verb`, classification, audit)
-   + executors.
+   - executors.
 6. `api/<entity>.ts` — thin `auth*` adapters, DTO projection.
 7. Tests: behavior + add the entity to the architecture globs.

package/docs/migration.md

@@ -65,7 +65,7 @@ convex/
 ### The root rule
 
 **The root of `convex/` contains configuration and facades only.** Every root
-file is a *declaration point* — the single place one piece of infrastructure
+file is a _declaration point_ — the single place one piece of infrastructure
 is configured — and none of them exports a public function or contains
 business logic. If a client can call it, it lives in `api/`. If it decides
 anything about the business, it lives in `domain/`. If `ls convex/*.ts` shows
@@ -76,19 +76,19 @@ anything else, the migration is not done.
 These patterns must not exist anywhere after migration — each one is a hole in
 a structural guarantee:
 
-| Forbidden | Where it's allowed instead | What it breaks otherwise |
-|---|---|---|
-| `query(`, `mutation(`, `action(`, `internalMutation(`, `internalAction(` from `_generated/server` | `functions.ts` only | auth, triggers, bounded reads |
-| `defineTable(` | `domain/<entity>/table.ts` via `<zodTable>.table` | single source of truth per entity |
-| `defineSchema(` | root `schema.ts` only | schema assembly |
-| inline `z.enum([...])` / repeated literal unions | tuple in `constants.ts` | vocabulary ownership |
-| `.collect()` / unbounded reads in public paths | `ctx.include(...).execute(limit)` | read bounds |
-| `makeFunctionReference` | generated `internal` / `api` | refactoring safety |
-| deep imports of a component's internals | the component's client facade | component boundary |
-| sibling-domain imports (`domain/a` → `domain/b`) | `domain/shared/` or the public API | ownership |
-| `ctx.db.insert/patch/delete` on a mounted component's tables | the component's client methods | component persistence |
-| vendor SDK instantiation inside a domain | one shared client in `domain/shared/<provider>.ts` | connection discipline |
-| `new Date().toISOString()` / hand-written timestamp fields | the `timestamps` trigger | server-owned lifecycle |
+| Forbidden                                                                                         | Where it's allowed instead                         | What it breaks otherwise          |
+| ------------------------------------------------------------------------------------------------- | -------------------------------------------------- | --------------------------------- |
+| `query(`, `mutation(`, `action(`, `internalMutation(`, `internalAction(` from `_generated/server` | `functions.ts` only                                | auth, triggers, bounded reads     |
+| `defineTable(`                                                                                    | `domain/<entity>/table.ts` via `<zodTable>.table`  | single source of truth per entity |
+| `defineSchema(`                                                                                   | root `schema.ts` only                              | schema assembly                   |
+| inline `z.enum([...])` / repeated literal unions                                                  | tuple in `constants.ts`                            | vocabulary ownership              |
+| `.collect()` / unbounded reads in public paths                                                    | `ctx.include(...).execute(limit)`                  | read bounds                       |
+| `makeFunctionReference`                                                                           | generated `internal` / `api`                       | refactoring safety                |
+| deep imports of a component's internals                                                           | the component's client facade                      | component boundary                |
+| sibling-domain imports (`domain/a` → `domain/b`)                                                  | `domain/shared/` or the public API                 | ownership                         |
+| `ctx.db.insert/patch/delete` on a mounted component's tables                                      | the component's client methods                     | component persistence             |
+| vendor SDK instantiation inside a domain                                                          | one shared client in `domain/shared/<provider>.ts` | connection discipline             |
+| `new Date().toISOString()` / hand-written timestamp fields                                        | the `timestamps` trigger                           | server-owned lifecycle            |
 
 ---
 
@@ -96,19 +96,19 @@ a structural guarantee:
 
 A raw project's root files usually mix several kinds of code. Pull them apart:
 
-| You have today | It becomes |
-|---|---|
-| `export const get/list = query({...})` at root | adapter in `api/<entity>.ts` + read logic in `domain/<entity>/queries.ts` |
-| `export const create/update = mutation({...})` at root | adapter in `api/<entity>.ts` + operation in `domain/<entity>/commands.ts` |
-| `internalMutation`/`internalAction` helpers | `system*` functions in `domain/<entity>/<purpose>_functions.ts` |
-| inline `defineTable({...})` in `schema.ts` | `zodTable` in `domain/<entity>/schema.ts` + indexes in `domain/<entity>/table.ts` |
-| `v.union(v.literal(...))` / inline `z.enum` repeated around | one `UPPER_SNAKE` tuple in `domain/<entity>/constants.ts` |
-| validation/business `if`-chains inside handlers | pure predicates in `domain/<entity>/rules.ts` |
-| shared grab-bag (`helpers.ts`, `utils.ts`, `lib.ts`) | split by owner into `domain/<entity>/shared.ts`; only genuinely cross-entity code into `domain/shared/` |
-| ad-hoc vendor clients (HTTP SDKs, caches, SQL) | one configured client per provider in `domain/shared/<provider>.ts` |
-| webhook handlers with logic in `http.ts` | route in `http.ts`, logic in `domain/<entity>/actions.ts` |
-| cron handlers with logic in `crons.ts` | declaration in `crons.ts`, target `system*` function in the domain |
-| audit/log/history tables mirroring component state | the component's own persistence via its facade |
+| You have today                                              | It becomes                                                                                              |
+| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `export const get/list = query({...})` at root              | adapter in `api/<entity>.ts` + read logic in `domain/<entity>/queries.ts`                               |
+| `export const create/update = mutation({...})` at root      | adapter in `api/<entity>.ts` + operation in `domain/<entity>/commands.ts`                               |
+| `internalMutation`/`internalAction` helpers                 | `system*` functions in `domain/<entity>/<purpose>_functions.ts`                                         |
+| inline `defineTable({...})` in `schema.ts`                  | `zodTable` in `domain/<entity>/schema.ts` + indexes in `domain/<entity>/table.ts`                       |
+| `v.union(v.literal(...))` / inline `z.enum` repeated around | one `UPPER_SNAKE` tuple in `domain/<entity>/constants.ts`                                               |
+| validation/business `if`-chains inside handlers             | pure predicates in `domain/<entity>/rules.ts`                                                           |
+| shared grab-bag (`helpers.ts`, `utils.ts`, `lib.ts`)        | split by owner into `domain/<entity>/shared.ts`; only genuinely cross-entity code into `domain/shared/` |
+| ad-hoc vendor clients (HTTP SDKs, caches, SQL)              | one configured client per provider in `domain/shared/<provider>.ts`                                     |
+| webhook handlers with logic in `http.ts`                    | route in `http.ts`, logic in `domain/<entity>/actions.ts`                                               |
+| cron handlers with logic in `crons.ts`                      | declaration in `crons.ts`, target `system*` function in the domain                                      |
+| audit/log/history tables mirroring component state          | the component's own persistence via its facade                                                          |
 
 ---
 
@@ -132,7 +132,7 @@ codebase greppable.
   the full set once (one owner), not per callsite.
 - **Vocabulary tuples**: `UPPER_SNAKE_CASE` exported `as const`; derived type
   `PascalCase` singular (`const <ENTITY>_STATES = [...] as const;
-  type <Entity>State = (typeof <ENTITY>_STATES)[number]`).
+type <Entity>State = (typeof <ENTITY>_STATES)[number]`).
 - **Domain executors**: `execute<Verb><Entity>` (`executeApproveInvoice`) —
   the grep-able seam between adapters and domain.
 - **Internal callback files**: `<purpose>_functions.ts` next to the
@@ -199,8 +199,8 @@ For each public function at the root:
 
 1. **Extract the domain logic.** Reads → `domain/<entity>/queries.ts`.
    Writes → an operation in the entity's command registry with
-   classification and audit derivation (see `commands.md`) — deciding *what
-   gets audited and as what* is a product decision; make it explicitly, not
+   classification and audit derivation (see `commands.md`) — deciding _what
+   gets audited and as what_ is a product decision; make it explicitly, not
    as an afterthought. Pure conditions the handler checks
    (state-transition legality, permission-beyond-role predicates) →
    `rules.ts`, so they're unit-testable without a ctx.
@@ -225,7 +225,7 @@ in the domain.
   `<purpose>_functions.ts`. Scheduled and callback writes now run under the
   same trigger regime as user writes.
 - `crons.ts` becomes declarations only, targeting `internal.domain.<entity>.
-  <purpose>_functions.*`.
+<purpose>_functions.*`.
 - `http.ts` becomes routing only: verify the webhook signature, parse the
   payload at the boundary, delegate to a domain action/function.
 
@@ -267,11 +267,11 @@ substantially changed; don't mechanically rewrite untouched files.
 import { parseInput } from './schema'
 
 export async function createProjection(input: unknown) {
-  return buildProjection(parseInput(input))
+	return buildProjection(parseInput(input))
 }
 
 function buildProjection(input: ProjectionInput) {
-  // implementation
+	// implementation
 }
 ```
 

package/docs/oxlint.md

@@ -0,0 +1,98 @@
+# Oxlint rules for cvx-kit applications
+
+`cvx-kit/oxlint` is a TypeScript-authored plugin bundled with the package. It
+checks applications using the kit against `conventions.md`, the authoritative
+source for folder structure and file anatomy. The package repository has a
+separate, unpublished plugin for its own `src/` layout.
+
+These consumer rules are available from 0.1.5; the initial 0.1.4 plugin targeted
+library authoring. See `upgrading.md` when migrating that configuration.
+
+## Configuration
+
+Install Oxlint as a development dependency and load the plugin in
+`.oxlintrc.json`. The root README includes a configuration enabling all rules.
+Loading a plugin does not enable its rules. For example:
+
+```json
+{
+	"jsPlugins": [{ "name": "cvx", "specifier": "cvx-kit/oxlint" }],
+	"rules": {
+		"cvx/no-raw-builders": "error",
+		"cvx/domain-import-boundaries": "error",
+		"cvx/thin-api-adapters": "error"
+	}
+}
+```
+
+With Vite+, place those fields under `lint` in `vite.config.ts`. The plugin
+exports a default plugin object, named `rules`, and the `RuleName` type. It is
+tested with Oxlint 1.79.0 and Vite+ 0.3.0.
+
+All rules default to `convex/` relative to the linter's working directory.
+For another location, set `convexDir` on **each enabled rule**:
+
+```json
+{ "cvx/no-raw-builders": ["error", { "convexDir": "src/server/convex" }] }
+```
+
+Rules ignore files outside that directory, `_generated/`, `__tests__/`, and
+files ending in `.test` or `.spec` before their JS/TS extension. They do not
+offer automatic fixes for architectural moves.
+
+## Coverage
+
+Every name below has the `cvx/` prefix in lint configuration.
+
+| Rule                        | Detects                                                                                                                                          | Documentation                                   |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| `root-facade-ownership`     | `createAuthFunctions`, `createTriggers`, and `new Foundation` outside their root files, or repeated in one file.                                 | `conventions.md`, Root files                    |
+| `no-raw-builders`           | Runtime imports of raw Convex builders outside `functions.ts`; namespace calls to raw generic builders.                                          | `auth.md`; `llms.md`, Non-negotiable rules      |
+| `no-handwritten-references` | Calls to Convex `makeFunctionReference`, including import aliases.                                                                               | `conventions.md`, Import rules                  |
+| `domain-import-boundaries`  | Reverse dependencies into `api/`, domain imports of `application/`, forbidden sibling imports, and API adapters importing another domain module. | `conventions.md`, Module grain and Import rules |
+| `public-functions-in-api`   | Calls to root `auth*`, `role*`, or `admin*` constructors outside `api/`.                                                                         | `conventions.md`, Folder structure              |
+| `thin-api-adapters`         | `if`, `switch`, ternary branches, top-level private helpers, and direct `ctx.db` writes in `api/`.                                               | `conventions.md`, The adapter file              |
+| `no-inline-enums`           | Literal arrays passed to imported Zod `enum`. Use named vocabulary tuples.                                                                       | `conventions.md`, Vocabularies                  |
+| `no-unbounded-reads`        | Direct `ctx.db.query(...).collect()` chains and `ctx.include(...).resolve()` chains in host code.                                                | `llms.md`, Bounded reads; `zod-table.md`        |
+| `no-manual-timestamps`      | Explicit `createdAt`/`updatedAt` fields in object literals passed to direct `ctx.db` writes.                                                     | `triggers.md`                                   |
+| `component-boundaries`      | Local portable components importing host/sibling files; host imports bypassing component client facades; private package component subpaths.     | `architecture.md`, Injection, not import        |
+| `no-component-env`          | Direct `process.env` access, process import aliases, environment destructuring, and named env imports inside local portable components.          | `conventions.md`, Import rules                  |
+| `schema-file-boundaries`    | Host `defineTable`, misplaced `defineSchema` or kit table constructors, and misplaced `.table.index/searchIndex/vectorIndex` chains.             | `conventions.md`, Shapes and topology           |
+| `no-internal-reexports`     | Re-exports and import-then-export aliases inside `convex/`.                                                                                      | `conventions.md`, Universal file order          |
+| `public-api-first`          | Private function declarations before the last export.                                                                                            | `conventions.md`, Universal file order          |
+| `named-private-helpers`     | Top-level private arrow/function-expression variables.                                                                                           | `conventions.md`, Universal file order          |
+
+## Allowed patterns
+
+- `functions.ts` imports raw builders to configure `createAuthFunctions`.
+  Type-only imports such as `MutationCtx` from `_generated/server` are valid
+  elsewhere. `httpAction` remains available for HTTP routing.
+- Domain modules may import sibling `rules.ts` and `queries.ts`, as explicitly
+  allowed by the module-grain section. Cross-module writes go through the
+  optional `application/` layer. `domain/table.ts` combines module table maps.
+- API adapters may delegate and perform the documented bounded inline query
+  and DTO projection. `system*` constructors may live in domain modules.
+- Authored components under `convex/components/<name>/` may use their own raw
+  builders and raw tables. Host-specific facade, timestamp, and bounded-read
+  rules do not apply there. Configuration imports for mounting components are
+  allowed from root `convex.config.ts`.
+- Host schemas use kit table constructors in `domain/<module>/schema.ts` and
+  attach indexes in `domain/<module>/table.ts`. `schema.ts` assembles them.
+- `archivedAt` remains application-controlled. Singular `db.get` reads and
+  bounded `execute`/`paginate` calls are allowed.
+
+## What still needs review and tests
+
+These are syntax and lexical-binding checks, not whole-program validation.
+They resolve relative import paths, not tsconfig aliases, symlinks, or computed
+paths. Named import aliases and namespaces are recognized where documented;
+arbitrary variable reassignment, wrapper functions, destructured database
+methods, and calls split across variables are not traced. Database checks
+recognize the documented `ctx.db` member shape, not its runtime type.
+
+The plugin does not prove DTO redaction, complete command/audit coverage,
+tenant/RLS correctness, unique table ownership across files, required facade
+existence, exactly one component mount, numeric read limits, or vocabulary
+tuple ownership. Keep the architecture tests from `conventions.md` and the
+behavioral tests described in `maintainability.md`. A clean lint run is not
+evidence of those runtime guarantees.

package/docs/tenancy.md

@@ -126,11 +126,10 @@ security: {
 
 ```ts
 rules: (bundle) => ({
-  '<entities>': {
-    modify: async (_ctx, doc) =>
-      bundle.role === 'admin' || doc.ownerId === bundle.actor.userId,
-  },
-  '<evidence>': { modify: async () => false },   // frozen via RLS as well as trigger
+	'<entities>': {
+		modify: async (_ctx, doc) => bundle.role === 'admin' || doc.ownerId === bundle.actor.userId,
+	},
+	'<evidence>': { modify: async () => false }, // frozen via RLS as well as trigger
 })
 ```
 
@@ -171,9 +170,7 @@ the schema and rejects a table declared by two modules:
 
 ```ts
 // convex/domain/table.ts
-export const domainTables = createModule(
-  <moduleA>Tables, <moduleB>Tables, <moduleC>Tables,
-)
+export const domainTables = createModule(<moduleA>Tables, <moduleB>Tables, <moduleC>Tables)
 // convex/schema.ts
 export default defineSchema(domainTables)
 ```

package/docs/triggers.md

@@ -27,7 +27,9 @@ noDelete(triggers, 'documents')
 
 // Domain triggers register on the same instance
 triggers.register('documents', async (ctx, change) => {
-  if (change.operation === 'insert') { /* denormalize, validate, cascade */ }
+	if (change.operation === 'insert') {
+		/* denormalize, validate, cascade */
+	}
 })
 ```
 
@@ -65,7 +67,7 @@ createAuthFunctions<DataModel>({ ..., triggers })
    (useful for seeding, dangerous for assertions about trigger behavior).
 2. **Wrapper spread order matters** if you compose ctx manually:
    `{ ...wrapDB(ctx), ...otherStuff }` — `wrapDB` returns a full ctx, so
-   spreading it *after* anything that carries `db` restores the raw database.
+   spreading it _after_ anything that carries `db` restores the raw database.
    The kit's constructors already order this correctly
    (`{ ...wrapDB(ctx), include, ...authBundle }`).
 3. **A throwing trigger aborts the transaction.** That is the point for