@aventara/cli 1.0.0-rc.1 → 1.0.0-rc.11

package/CHANGELOG.md

@@ -1,5 +1,266 @@
 # @aventara/cli
 
+## 1.0.0-rc.11
+
+### Patch Changes
+
+- 6d8b589: The agent skill's `reference/errors.md` (written by `aventara new`, `aventara init` and `aventara skill`) now carries
+  `@aventara/core`'s current error reference: `COMPILER_RESERVED_RESOURCE_NAME` names `all`, the member beside the
+  Resources on `serverClient` (and Next.js's `avClient`).
+- e5e98e6: The docs moved to https://aventara.razor34.dev/framework. Every `docs` link in `AvErrorCatalog` (and
+  `ERRORS.md`), and every docs link `aventara new`, `aventara init` and `aventara skill` write into the scaffold and the
+  agent skill, now point there instead of https://aventara-framework.vercel.app.
+- fb20833: The agent skill `aventara new`, `aventara init` and `aventara skill` write now teaches rc.11's features. A new
+  `reference/client.md` covers calls made together going out as one `POST /_all`, `avClient.all` (strict, or
+  `settle: true`), aborting one call or a whole `all`, `avLazy`, `grouping: false`, `all` in server code
+  (`framework.serverClient.all`, Next.js `avClient.all`), `limits.maxAll` and `limits.maxAllConcurrency`, and the
+  `/_all` body and streamed answer for a client written by hand. `reference/config.md` adds caching reads:
+  `cache({ for, maxAge })` with `for` written first, where the stage may go, which level wins, the three audiences, and
+  `avCache` beside React's `cache`. SKILL.md gains two rules and a stage row for these, and points to
+  `@aventara/access`'s own skill when that package is installed.
+- 0b2f077: The Next.js scaffold's `src/aventara/config.ts` starts with `import "server-only"`, as `src/aventara/server.ts` does, so
+  a Client Component that imports the configuration by mistake fails `next build` instead of bundling server code for the
+  browser.
+- 2dd7e44: The agent skill teaches writing only what changes behaviour: no option at its default value (a limit, `grouping: true`,
+  `agent.extends: "client"`, the root's `exposed: true`), no key or wrapper that repeats a built-in, no type annotation
+  the inference already gives. `cache({ for, maxAge })` still writes `for`, even the default `"user"`. Its examples drop
+  the root's `exposed: true` and the agent layer's `extends: "client"`.
+
+  The scaffold follows the same rule: `aventara new` and `aventara init` no longer write `exposed: true` in
+  `aventara.config.ts` (NestJS) or `src/aventara/config.ts` (Next.js). The root exposes everything by default, as the
+  comment above it says.
+
+## 1.0.0-rc.10
+
+### Patch Changes
+
+- 82afc5e: The scaffolded configuration's `diagnostics` sink logs `String(error)` when an error's `stack` is empty or missing,
+  instead of an empty `raw error` line.
+
+  `aventara` prints a defect as `String(error)` when its `stack` is empty or missing, instead of a blank or `undefined`
+  line.
+
+- 09585dd: The agent skill's configuration reference covers `managedElsewhere`: a model whose table another service owns, and
+  the Prisma 7 external-tables setup that keeps `prisma migrate` off it.
+- 04bb39a: `engines.node` is now `^22.23.4 || >=24.22.1`, the Node security releases of 2026-10-20 (CVE-2026-105481,
+  CVE-2026-105482, CVE-2026-105483, CVE-2026-106069, CVE-2026-106072, CVE-2026-106073, CVE-2026-106074,
+  CVE-2026-111497). The bins refuse an older Node in one sentence naming that range.
+- 4f0fd29: The Prisma 7 adapter's peer floor is now `^7.10.1` (`prisma`, `@prisma/client`, `@prisma/adapter-pg`,
+  `@prisma/adapter-better-sqlite3`). `prisma` 7.10.0 pins `mysql2` 3.15.3 (GHSA-3f6p-5ww8-9rcr, GHSA-rgwj-5xj2-c3m3)
+  and, through `@prisma/config`, `deepmerge-ts` 7.1.5 (GHSA-ggr8-5vv4-36mx); 7.10.1 pins `mysql2` 3.24.4 and
+  `deepmerge-ts` 8.0.2. `aventara new` and `aventara init` install Prisma at the floor, so new projects get 7.10.1, and
+  `aventara init` refuses a project whose Prisma is below it.
+- 10341d5: The Next.js scaffold's `src/prisma.ts` keeps one PrismaClient per generated schema: after `aventara:prepare` regenerates
+  the client, the next call makes a new one and disconnects the old one, so `next dev` needs no restart.
+- 88263a1: Startup checks, tightened:
+
+  - An `mcp.authorization.servers` entry with a query or a fragment is refused for https URLs too, not only for loopback
+    http ones: an authorization server's issuer has neither (RFC 8414).
+  - A `client.resources` or `agent.resources` entry for a Resource managed elsewhere is refused (`COMPILER_UNKNOWN_RESOURCE`):
+    those layers never have the Resource, so nothing configured there would run. Configure it at the root or in
+    `application`.
+
+- 88263a1: Documentation: `$access.can([])` answers `[]`, not a refusal; the MCP README states the query and fragment rule for
+  every authorization server.
+
+## 1.0.0-rc.9
+
+### Patch Changes
+
+- a0bb05e: The agent skill that `aventara new`, `aventara init` and `aventara skill` write has a new section, "Calling the API over
+  HTTP", with a working curl example: the operation path uses the model's name as written in the Prisma schema
+  (`/api/_resources/User/create/one`), every request sends the `Aventara-Protocol-Version: 1` and
+  `Aventara-Contract-Hash` headers (the hash comes from `GET /api/_contract`), and a create's body is `{ "data": … }`. It
+  lists the answers each mistake gets. The printed next steps point to it. To refresh the skill in an existing
+  project, run `aventara skill`.
+- 8c40b81: `aventara new` and `aventara init` now scaffold Next.js apps.
+
+  - `aventara new <name> --host next` runs `create-next-app@latest` (TypeScript, the App Router under `src/`, the `@/*`
+    alias, no install of its own), then the same `init` steps, then the install. create-next-app asks its own questions
+    on your terminal; with `--yes` it takes its defaults. Its own flags go after `--`, as they are:
+    `aventara new my-app --host next --yes -- --tailwind`. `--skip-git` becomes its `--disable-git`. Without a terminal,
+    `--yes` is required. `--host` defaults to `nest`: a NestJS project is scaffolded exactly as before.
+  - `aventara init` tells the host by `package.json`: `@nestjs/core` is NestJS 12, `next` is Next.js 16, and a project
+    that depends on both or neither is refused in one sentence, with nothing written. A Next.js app needs `src/app/`
+    and the `@/*` → `./src/*` path in `tsconfig.json`, and no ORM yet.
+  - In a Next.js app, init writes `src/aventara/config.ts`, `src/aventara/adapter.ts`, `src/aventara/server.ts`
+    (`Aventara()`, exporting `handlers`, `avClient`, `avApp` and `ready`), `src/app/api/[...aventara]/route.ts`,
+    `src/instrumentation.ts` (awaiting `ready()` on the Node.js runtime) and `src/prisma.ts`, with Prisma's schema and
+    config. `aventara:prepare` ends with `aventara-build --client` and runs on `postinstall` and `prebuild`; the files it
+    generates (`src/aventara/generated/`, `src/aventara/client.ts`, `src/aventara/universal.ts`) are added to
+    `.gitignore`. An instrumentation file of your own is never replaced: the lines to add are printed.
+  - Each host package now declares its project layout in its manifest (`"aventara": { "host": … }`). The CLI scaffolds
+    from it and `aventara-build` reads its paths from it, so the two always agree.
+
+- 501b832: `aventara new --host next` and `aventara init` in a Next.js app add `serverExternalPackages: ["@aventara/core",
+"@aventara/prisma7-adapter"]` to `next.config.ts`, so Node.js loads them once per server process: every route and
+  page shares one core, one Framework and one Prisma client. The line goes into create-next-app's config, or any config
+  whose `const nextConfig = {` object has no `serverExternalPackages`; an app with no config gets a `next.config.ts`. A
+  config that already names `serverExternalPackages`, or is written another way, is never changed, even with `--yes`:
+  the line to add is printed, with a warning. The agent skill's Next.js section says to keep it.
+- The agent skill's Next.js section says what a page that calls `avClient` or `avApp` needs under Cache Components
+  (create-next-app's default): the calling component inside `<Suspense>` (or a `loading.tsx`), `"use cache"` on the
+  function that makes the call, or `export const instant = false`.
+
+## 1.0.0-rc.8
+
+1.0.0-rc.5, rc.6 and rc.7 were tagged but never published; 1.0.0-rc.8 contains everything listed under them and the changes below.
+
+## 1.0.0-rc.7
+
+1.0.0-rc.5 and 1.0.0-rc.6 were tagged but never published; 1.0.0-rc.7 contains everything listed under them and the changes below.
+
+## 1.0.0-rc.6
+
+1.0.0-rc.5 was tagged but never published. 1.0.0-rc.6 contains everything listed under 1.0.0-rc.5 and the fix below.
+
+## 1.0.0-rc.5
+
+## 1.0.0-rc.4
+
+### Patch Changes
+
+- 7c3b65f: Build-time Contracts for serverless and edge cold starts.
+
+  - New package `@aventara/build`, bin `aventara-build`, a development dependency. It runs `src/aventara.config.ts` and
+    `src/aventara.adapter.ts` without a database client, compiles the Contracts with the project's `@aventara/core` and
+    writes `src/generated/aventara/contracts.generated.ts` (`aventaraContracts`), which a serverless or edge entry passes
+    to `createFramework` as `prebuilt`. A configuration that startup would refuse fails the build with the same
+    `CONFIG_…`/`COMPILER_…` diagnostics. `aventara-build --check` writes nothing and exits 1 when the file is missing or
+    stale, naming the Resources that changed.
+  - `@aventara/prisma7-adapter`: `describePrismaAdapter({ discovery, provider, driver })` states the adapter's passive
+    facts (the model, the driver's transaction capability, the referential actions, the computed fields) with no client.
+    `createPrismaAdapter({ ...description, client })` builds the adapter from the same facts, and still checks the client
+    against the discovery artifact.
+  - `@aventara/cli`: the scaffold's `src/aventara.config.ts` exports the configuration as a plain value
+    (`export const aventaraConfig = { … } as const`) with no `adapter`. A new `src/aventara.adapter.ts` default-exports
+    `describePrismaAdapter(…)`, and `app.module.ts` joins the two:
+    `config: { ...aventaraConfig, adapter: await createPrismaAdapter({ ...adapter, client: prisma }) }`. The Nest server
+    still compiles its Contracts at startup and passes no `prebuilt`. `aventara:prepare` ends with `&& aventara-build`,
+    and `@aventara/build` is an exact development dependency.
+
+- 2b1b17e: `aventara-build`'s files no longer land inside a Prisma client generated into `src/generated`.
+
+  When `aventara init` reuses a project whose Prisma client is generated into `src/generated`, it already puts the
+  discovery artifact in `src/aventara/`, because `prisma generate` deletes every file in its output directory that it did
+  not write. `aventara-build` still wrote its three files to `src/generated/aventara/`, so each `prisma generate` deleted
+  them and the project stopped compiling until the next `aventara:prepare`. Now all of Aventara's generated files are
+  in one place.
+
+  - `@aventara/build`: `aventara-build` writes `resources.generated.ts`, `computed-fields.generated.ts` and
+    `contracts.generated.ts` to the directory the configuration imports `aventaraResources` from, so the tree is always
+    written where the configuration reads it. A configuration that imports no tree keeps `src/generated/aventara/`.
+    The files of a project whose client is generated anywhere else are the same bytes, in the same place.
+  - `@aventara/prisma7-adapter`: with `--config`, the artifact imports the computed fields from its sibling,
+    `./computed-fields.generated`, wherever `--out` puts it. `--config` is still required for that import and the step
+    still checks that the file exists, but the step no longer uses its location. A scaffold's artifact is unchanged.
+  - `@aventara/cli`: in that project, `src/aventara.config.ts` imports the tree from `./aventara/resources.generated`,
+    and `.gitignore` gets the one `/src/aventara/` line that covers all four files (no separate
+    `/src/generated/aventara/contracts.generated.ts` line). The agent skill says where the generated files are in
+    both cases.
+
+- 99169d2: Policy engines, reads first. `createFramework` takes an optional root `policy: { engine, principal }`: an engine that
+  answers three questions (`can`, `scopeOf`, `fieldsOf`, each now or as a promise), and a function that derives a
+  request's principal from its `ctx.$state`. Core never imports an engine; one satisfies `AvPolicyEngine` by its shape,
+  and a scope or grant is a fragment of Aventara's own `where` (`AvPolicyWhere`).
+
+  - Client and agent requests are checked (an MCP tool call is an agent request). An application call is checked only
+    when it names a principal: `framework.application.Note.find.many(args, { as: user })`. A call a stage makes through
+    `ctx` never is.
+  - Before any guard, `can` and the fields the request names or receives (`fieldsOf`); a refusal is `403 A4002`. At the
+    adapter call, after every developer stage, the read scope is ANDed into the root `where`, every to-many include and
+    its `$count`, and every relation filter, at every level. A to-one include of a row out of scope refuses the request;
+    it is never nulled.
+  - Governed fields (the engine's `governed` list) are left out of every default projection and carry `governed: true`
+    in the Contracts. Name one to get it: `select: ["$defaults", "email"]`, where `$defaults` is the level's default
+    projection. It is refused where a returned row does not grant it, and a filter or sort by it is checked before the
+    query runs, so it cannot reveal values the caller may not read.
+  - The engine's `governed` and `paths` lists are checked against the Core Contract at startup. A rule's paths are lists
+    of segments, as other paths in core are: `["Note", "campaign", "members", "some", "userId", "equals"]`.
+  - Writes are checked as well; see the policy writes entry.
+
+  Without `policy`, nothing changes: the Contracts and their hashes are the same bytes.
+
+- 154e440: Policy engines check writes. Every create, update, delete and upsert a client or agent makes (or an application call
+  made `{ as }` a principal) is now checked by the configuration's `policy`, where before it was refused.
+
+  - The fields a write sends are held to `fieldsOf({ access: "write" })` before any guard; a field outside it answers
+    `403 A4002`. A field writable on some rows only is checked against every row an update reaches, and against the
+    row a create inserts, after the insert and inside its transaction.
+  - A create asks `can({ action: "create", row })` about each new row on its final data. Its rules can look rows up
+    through `exists`, which runs inside the write's transaction, so a plan that creates a campaign and then its first
+    note sees the campaign.
+  - An update or delete acts only on rows the caller may both change (`scopeOf` for the action) and read. A single-row
+    one that matches nothing answers `A4002` when the caller can read the row, and `A2003` when it cannot, so the
+    answer does not reveal that the row exists. A `many` or `count` one answers for the caller's rows only.
+  - An update that moves a row out of what the caller reads is rolled back with `A4002`. So is one that fails an `after`
+    condition: inside the transaction core asks `can({ action: "update", row })` about each changed row of every
+    checked update. The engine's new `afterChecks` member (`{ Note: ["update"] }`) names the updates whose grants carry
+    such a condition, which are the ones refused where there is no interactive transaction.
+  - Where the operation's `transactionsStyle` is `"interactive"`, a checked write runs in a transaction of its own. Where
+    it is `"none"` (Cloudflare D1), a write that can only be checked after it runs is refused before it runs; every other
+    write runs, a create looking up before it inserts, and an unlisted update without the after check.
+  - Nested writes (a relation directive in a write's data) are refused under a policy for now.
+
+  `afterChecks` is checked against the Core Contract at startup and changes no Contract and no prebuilt fingerprint.
+
+- 3813207: The Resource tree and the computed fields come from `aventara-build`.
+
+  - `@aventara/build`: before it compiles the Contracts, `aventara-build` writes two more files under
+    `src/generated/aventara/`. `resources.generated.ts` exports `aventaraResources`: every `defineResource(…)` result
+    that the files `src/resources/**/*.resource.ts` export, found by its type (never run), one `resources` tree per
+    layer, written as the plain spreads you wrote by hand (`root` always, `application`, `client` and `agent` when some
+    Resource has a block for them). Two definitions of one Resource stop the build, naming both. Imports are spelled as
+    the project spells its own. `computed-fields.generated.ts` exports `computedFields` and its type `AvComputedFields`:
+    which fields the configuration's write compute fills, read off its type after the tree exists, so a fresh install is
+    typed right on its first `aventara:prepare`. `--check` covers all three files. `typescript` (`>=5.7.0 <7`) is now a
+    peer dependency.
+  - `@aventara/prisma7-adapter`: the generate step no longer reads the configuration. With `--config`, the discovery
+    artifact imports `computedFields` and `AvComputedFields` from the file `aventara-build` writes beside the
+    configuration (`generated/aventara/computed-fields.generated.ts`); a `--config` file that does not exist is still
+    refused. `readConfigComputedFields`, `AvPrismaConfigReaderError` and `ConfigComputedFieldsReading` are removed from
+    `@aventara/prisma7-adapter/generate`, as are `PrismaGenerateToolchain.readComputedFields` and
+    `PrismaGenerateResult.computedFields`.
+  - `@aventara/cli`: the scaffold's `src/aventara.config.ts` takes its Resources from the tree,
+    `resources: aventaraResources.root`, so a new Resource file needs no configuration edit; the agent skill says so.
+
+## 1.0.0-rc.3
+
+### Patch Changes
+
+- b38034d: A refusal that quotes a failed child's output (`npm install`, `nest new`) ends with that output as the child wrote it.
+  It printed a period of its own after the child's last line (`npm ERR! the registry said no.`).
+
+## 1.0.0-rc.2
+
+### Patch Changes
+
+- `aventara init`'s refusal of a TypeScript 7 project names the supported range: "use TypeScript 5.7 to 6" (it said
+  "use TypeScript 6 or 5"). The Prisma adapter's `typescript` peer range starts at 5.7.0 now.
+- An agent skill for your AI coding agent. `aventara new` and `aventara init` write `.claude/skills/aventara/`:
+  `SKILL.md` (the Agent Skills format Claude Code reads: when to use it, and one rule per task) and
+  `reference/config.md`, `reference/stages.md`, `reference/recipes.md` and `reference/errors.md` (`@aventara/core`'s
+  `ERRORS.md`), for the Aventara version they install. They also add a short Aventara section to `AGENTS.md`, between
+  `<!-- aventara:start -->` and `<!-- aventara:end -->`, for agents that read `AGENTS.md`: an existing `AGENTS.md`
+  keeps everything else, and `CLAUDE.md` is never written.
+- `aventara skill` refreshes those files for the `@aventara/core` installed in the project (its version and its
+  `ERRORS.md`; it runs none of the project's packages). It rewrites the skill files it wrote, keeps one you changed
+  and says so (`--force` replaces it), and replaces only the marked section of `AGENTS.md`.
+- `aventara new` and `aventara init` write an `aventara:prepare` script that also passes
+  `--config src/aventara.config.ts`, so the generated types know which fields your configuration computes: a
+  variant's guards, pipes and filters may leave exactly those out of a create. A project set up before keeps working;
+  add the flag to its script to get the precise types.
+- The agent skill says that a `Date` or bytes value a stage is told is that stage's own copy, so changing it in place
+  changes nothing another stage sees, what is written or what the caller receives; and that a `compute.read` stage with
+  no `dependsOn` computes from the same inputs for every row, so its value usually belongs in response metadata or
+  `ctx.$state`. In rc.1 it said neither.
+- The agent skill says that a `compute.read` stage is told the row frozen: it returns its field's value, and writing
+  into `record` answers `A3000`. Its error reference lists a nested write that writes its relation back (`A2004`,
+  `V1012`).
+- The agent skill says that a computed value its field's `format` refuses (a relative path for `format: "url"`)
+  answers `A3000`, as a value of the wrong type does.
+- Released with the other Aventara packages, and `aventara new` and `aventara init` install them at 1.0.0-rc.2.
+
 ## 1.0.0-rc.1
 
 ### Patch Changes
@@ -65,7 +326,6 @@
               nullable: false,
               list: false,
               lifecycle: ["VIRTUAL"],
-              format: "url",
             },
             pipelines: {
               compute: {

package/README.md

@@ -1,11 +1,13 @@
 # `@aventara/cli`
 
-The `aventara` command: it scaffolds an Aventara server on NestJS 12.
+The `aventara` command: it scaffolds an Aventara server on NestJS 12 or Next.js 16.
 
 ```bash
 npm i -g @aventara/cli@rc  # or run it once: npx @aventara/cli@rc <command>
 aventara new my-api           # a new NestJS project with Aventara
-aventara init                 # Aventara added to the NestJS 12 project in this directory
+aventara new my-app --host next   # a new Next.js app with Aventara (create-next-app, then init)
+aventara init                 # Aventara added to the NestJS 12 or Next.js 16 project in this directory
+aventara skill                # refresh the agent skill for the installed @aventara/core
 ```
 
 It is run once, globally or through `npx`; it is not a dependency of the projects it writes. The frontend's side
@@ -22,16 +24,29 @@ without `.env` (it is in `.gitignore`). No commit is made, and one line says why
 `user.name`/`user.email`, or when the directory is already inside a git repository (a monorepo: commit it there).
 `--skip-git` makes no repository and no commit.
 
+### `aventara new <name> --host next`
+
+Runs `create-next-app@latest <name> --ts --app --src-dir --import-alias "@/*" --use-<npm|pnpm> --skip-install`, then
+`aventara init`'s pipeline over the new app, then the install. create-next-app asks its own questions on your terminal;
+with `--yes` it takes its defaults instead (and is given `--yes` too), which is also what a run with no terminal needs.
+Its own flags go after `--`, as they are: `aventara new my-app --host next --yes -- --tailwind --eslint`. `--skip-git`
+becomes its `--disable-git`. `--host` defaults to `nest`.
+
 ## `aventara init`
 
-Runs inside an existing NestJS 12 project. It refuses a directory with no `package.json`, another Nest major,
+Runs inside an existing NestJS 12 or Next.js 16 project, telling them apart by `package.json`: `@nestjs/core` is
+NestJS, `next` is Next.js, and a project depending on both or neither is refused in one sentence. A Next.js app must use
+the App Router under `src/app/` and map `@/*` to `./src/*` in `tsconfig.json` (as create-next-app writes it), and have
+no ORM yet. The rest of this section is NestJS's; a Next.js app gets [its own files](#what-it-writes-in-a-nextjs-app).
+
+In a NestJS project, it refuses another Nest major,
 TypeScript 7, a yarn-only lockfile, or a project already initialized.
 
 In a project with no ORM yet, the ORM and the database are asked (or taken from the flags), and everything below is
 written.
 
 In a project that already uses Prisma, the installed Prisma must be one an Aventara adapter supports, or the run is
-refused in one sentence with nothing written. Today that is Prisma 7 (`^7.10.0`) on SQLite or PostgreSQL, with a driver
+refused in one sentence with nothing written. Today that is Prisma 7 (`^7.10.1`) on SQLite or PostgreSQL, with a driver
 adapter and the `prisma-client` generator. Your schema, Prisma config and service are reused and never written, and
 your `.env` only gains a `CORS_ORIGINS` line at its end when it has none. Init finds the class extending `PrismaClient`
 and the module exporting it, or asks.
@@ -45,6 +60,7 @@ possible answer is shown, not asked.
 | Flag | Question | Default |
 |---|---|---|
 | `<name>` (`new` only) | The project directory. | required |
+| `--host <nest\|next>` (`new` only) | The framework to build on; `init` reads it from `package.json`. Not asked. | `nest` |
 | `--orm <alias>` | The ORM, as an adapter's alias: `prisma7` (Prisma 7, `@aventara/prisma7-adapter`). `--help` lists the aliases that exist. | the only one there is |
 | `--db <provider>` | The database: the adapter's providers (`sqlite`, `postgresql`). | `sqlite` |
 | `--package-manager <npm\|pnpm>` | The package manager. | the lockfile's, else the one that launched the CLI, else npm |
@@ -54,6 +70,7 @@ possible answer is shown, not asked.
 | `--skip-git` (`new`) | Passed to `nest new`. | |
 | `-y`, `--yes` | Accept every unanswered default, and replace existing content that differs. | |
 | `--verbose` | Show the output of `nest new` and the install as they run. | |
+| `-- <args>` (`new --host next`) | Passed to create-next-app as they are, after its own. | |
 
 While it works, each step is shown on stderr, such as `[3/4] Installing dependencies (npm install)`. On a terminal it
 has a spinner and the seconds so far; in a pipe, in CI (`CI`) or with `NO_COLOR` it is one plain line per step
@@ -77,6 +94,30 @@ when you confirm, or with `--yes`; where nobody can be asked, the run stops and
 | `package.json`: `@aventara/*` at this CLI's version, `prisma`, `@prisma/client` and the driver at `7.10.0`; `aventara:prepare`, run by `postinstall` and by `prebuild`, `prestart`, `prestart:dev` and `prestart:debug`, and the `.env` on the start scripts and `test:e2e` (`--env-file`, `--env-file-if-exists`) | you |
 | `pnpm-workspace.yaml` (pnpm only): `allowBuilds` for Prisma's and SQLite's install scripts | you |
 | `src/generated/prisma/**`, `src/generated/aventara/discovery.artifact.ts` | generated by `aventara:prepare` (run on every install, build and start, so a schema change needs only a restart); never edit |
+| `.claude/skills/aventara/` (`SKILL.md`, `reference/*.md`, `.aventara-skill.json`): the agent skill your AI coding agent reads | Aventara's: `aventara skill` refreshes it, and keeps a file you changed unless `--force` |
+| `AGENTS.md`: an Aventara section between `<!-- aventara:start -->` and `<!-- aventara:end -->`, appended to an existing file | you, except the marked section |
+
+### What it writes in a Next.js app
+
+Everything Aventara is in one folder, `src/aventara/`, at the paths `@aventara/next` declares and `aventara-build`
+reads.
+
+| Path | Owner afterwards |
+|---|---|
+| `prisma/schema.prisma`, `prisma.config.ts` | you (as in a NestJS project) |
+| `src/prisma.ts`: `prisma()`, the app's one Prisma client with the driver adapter, made on first use and kept across `next dev` reloads | you |
+| `src/aventara/config.ts`: `aventaraConfig`, as in a NestJS project, logging through `console.error` | you |
+| `src/aventara/adapter.ts`: the adapter's description | you |
+| `src/aventara/server.ts`: `Aventara({ ...aventaraConfig, adapter, prebuilt, state })` exporting `handlers`, `avClient`, `avApp` and `ready`; `@/aventara/server` | you |
+| `src/app/api/[...aventara]/route.ts`: every method of `handlers` | you |
+| `src/instrumentation.ts`: awaits `ready()` on the Node.js runtime, so a bad configuration stops `next start`. An instrumentation file of yours is never replaced, even with `--yes`: the lines to add are printed | you |
+| `next.config.ts`: `serverExternalPackages: ["@aventara/core", "@aventara/prisma7-adapter"]` added to its configuration object, so Node.js loads them once per server process (one core and one Prisma client for every route and page). Added to create-next-app's config, or to any whose `const nextConfig = {` object has no `serverExternalPackages`; written as a new `next.config.ts` when the app has none. A config that already names `serverExternalPackages`, or is written another way, is never changed, even with `--yes`: the line to add is printed | you |
+| `package.json`: `@aventara/core`, `@aventara/next`, the adapter and `@aventara/build` at this CLI's version, `server-only`, Prisma at `7.10.0`; `aventara:prepare` (ending in `aventara-build --client`), run by `postinstall` and `prebuild` | you |
+| `.env` (`DATABASE_URL`), `.gitignore` (`/src/generated/`, `/dev.db*`, `/src/aventara/generated/`, `/src/aventara/client.ts`, `/src/aventara/universal.ts`, `.env`) | you |
+| `src/aventara/client.ts`, `src/aventara/universal.ts`, `src/aventara/generated/` | generated by `aventara:prepare`; never edit |
+
+No CORS (the browser calls the same origin), no Pages Router, no proxy, and no MCP route: an `mcp` endpoint you add on
+Next.js needs `authorization`. Next steps: `npx prisma db push`, then `npm run dev`.
 
 ### Next steps it prints
 
@@ -120,15 +161,23 @@ lower-cased or pluralized.
 Results are read-only. A list result is a `readonly` array, so type it `readonly User[]`:
 `const users: readonly User[] = await avClient.User.find.many({});`.
 
+## `aventara skill`
+
+Writes the agent skill for the `@aventara/core` installed in the project in this directory: its version, and its
+`ERRORS.md` as `reference/errors.md`. It reads those files and runs none of the project's packages. A skill file it
+wrote before is replaced; one you changed is kept, with a warning, unless you pass `--force`. In `AGENTS.md` only the
+text between the Aventara markers is replaced (or the section appended), and `CLAUDE.md` is never written. Run it with
+the CLI at your `@aventara/core` version: `npx @aventara/cli@<version> skill`.
+
 ## Supported
 
 - NestJS 12.
-- Node `^22.18.0 || >=24.2.0`. On any other Node the bin refuses in one sentence naming that range. On Node 22 use
+- Node `^22.23.4 || >=24.22.1`. On any other Node the bin refuses in one sentence naming that range. On Node 22 use
   npm ≥ 11, because Node 22's bundled npm 10 cannot install Nest 12's own scaffold. A CommonJS project's jest e2e needs
   Node ≥ 24.9, which is Nest's and Jest's limit.
 - npm and pnpm. Yarn is not supported.
 - ESM and CommonJS projects.
-- Prisma 7 (`^7.10.0`) on SQLite and PostgreSQL.
+- Prisma 7 (`^7.10.1`) on SQLite and PostgreSQL.
 
 The ORMs, majors, databases and drivers on offer are generated from the Aventara adapter packages that exist
 (`src/catalog/adapter.catalog.generated.ts`), never listed by hand, so a future `@aventara/prisma8-adapter` appears

package/dist/apply/conflict.confirmer.js

@@ -1,7 +1,7 @@
 export class AvConflictsNotConfirmedError extends Error {
     name = "AvConflictsNotConfirmedError";
 }
-export function conflictWarning(conflicts) {
+function conflictWarning(conflicts) {
     return `${conflicts.join(", ")} already ${conflicts.length === 1 ? "has" : "have"} other content, and initializing will replace ${conflicts.length === 1 ? "it" : "them"}`;
 }
 export async function confirmConflicts(conflicts, consent) {

package/dist/catalog/adapter.catalog.generated.js

@@ -9,7 +9,7 @@ export const ADAPTER_CATALOG = [
             "package": "@prisma/client",
             "major": 7
         },
-        "range": "^7.10.0",
+        "range": "^7.10.1",
         "familyPackages": [
             "prisma",
             "@prisma/client",

package/dist/catalog/host-entry.interface.js

@@ -0,0 +1,10 @@
+import { HOST_CATALOG } from "./host.catalog.generated.js";
+import { lowestMajorOf } from "./range.reader.js";
+export const HOSTS = HOST_CATALOG;
+export const DEFAULT_HOST = "nest";
+export function hostOf(alias) {
+    return HOST_CATALOG.find((entry) => entry.alias === alias);
+}
+export function frameworkMajorOf(host) {
+    return lowestMajorOf(host.framework.range);
+}

package/dist/catalog/host.catalog.generated.js

@@ -0,0 +1,32 @@
+export const HOST_CATALOG = [
+    {
+        "alias": "nest",
+        "label": "NestJS",
+        "package": "@aventara/nest",
+        "framework": {
+            "package": "@nestjs/core",
+            "range": "^12.0.0"
+        },
+        "layout": {
+            "config": "src/aventara.config",
+            "adapter": "src/aventara.adapter",
+            "generated": "src/generated/aventara"
+        }
+    },
+    {
+        "alias": "next",
+        "label": "Next.js",
+        "package": "@aventara/next",
+        "framework": {
+            "package": "next",
+            "range": ">=16.4 <17"
+        },
+        "layout": {
+            "config": "src/aventara/config",
+            "adapter": "src/aventara/adapter",
+            "generated": "src/aventara/generated",
+            "client": "src/aventara/client.ts",
+            "universal": "src/aventara/universal.ts"
+        }
+    }
+];

package/dist/cli.js

@@ -6,6 +6,7 @@ import { AvProjectRefusedError } from "./project/project.inspector.js";
 import { runCommand } from "./run/command.runner.js";
 import { AvInstallFailedError, runInit } from "./run/init.orchestrator.js";
 import { runNew } from "./run/new.orchestrator.js";
+import { AvSkillRefusedError, runSkill } from "./run/skill.orchestrator.js";
 import { progressModeOf } from "./run/step.reporter.js";
 import { AvUnansweredQuestionsError, } from "./wizard/answer.resolver.js";
 import { AvWizardCancelledError, createReadlinePrompter, } from "./wizard/readline.prompter.js";
@@ -18,6 +19,7 @@ const REFUSALS = [
     AvProjectRefusedError,
     AvConflictsNotConfirmedError,
     AvInstallFailedError,
+    AvSkillRefusedError,
 ];
 const MANIFEST = new URL("../package.json", import.meta.url);
 function ownVersion() {
@@ -38,6 +40,14 @@ export async function runCli(argv, io) {
             io.stdout(`${ownVersion()}\n`);
             return 0;
         }
+        if (command.command === "skill") {
+            return runSkill(command, {
+                directory: io.cwd,
+                stdout: io.stdout,
+                stderr: io.stderr,
+                cliVersion: ownVersion(),
+            });
+        }
         if (command.command === "init") {
             return await runInit(command, {
                 directory: io.cwd,
@@ -65,10 +75,13 @@ export async function runCli(argv, io) {
     }
     catch (error) {
         if (REFUSALS.some((refusal) => error instanceof refusal)) {
-            io.stderr(`aventara: ${error.message}.\n`);
+            const { message } = error;
+            io.stderr(message.includes("\n")
+                ? `aventara: ${message.trimEnd()}\n`
+                : `aventara: ${message}.\n`);
             return 1;
         }
-        io.stderr(`${String(error instanceof Error ? error.stack : error)}\n`);
+        io.stderr(`${(error instanceof Error && error.stack) || String(error)}\n`);
         return 1;
     }
 }