nestjs-boost 0.0.0-stage → 1.2.0

package/package.json

@@ -1,6 +1,67 @@
-{
-  "name": "nestjs-boost",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "nestjs-boost",
+  "version": "1.2.0",
+  "description": "Agent Skills and project guidelines for AI-assisted NestJS 12 development. Interactive installer for Claude Code, GitHub Copilot, Cursor, Codex, Gemini CLI, Windsurf, Cline, Roo Code, Kiro, Junie and OpenCode.",
+  "keywords": [
+    "nestjs",
+    "agent-skills",
+    "skills",
+    "ai",
+    "claude-code",
+    "codex",
+    "cursor",
+    "copilot",
+    "agents-md",
+    "mcp",
+    "gemini-cli",
+    "windsurf",
+    "cline",
+    "roo-code",
+    "kiro",
+    "junie",
+    "opencode",
+    "skill-md"
+  ],
+  "license": "MIT",
+  "author": "Ruwan Bandara",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ruwanb/nestjs-boost.git"
+  },
+  "homepage": "https://github.com/ruwanb/nestjs-boost#readme",
+  "bugs": {
+    "url": "https://github.com/ruwanb/nestjs-boost/issues"
+  },
+  "type": "module",
+  "bin": {
+    "nestjs-boost": "bin/nestjs-boost.mjs"
+  },
+  "exports": {
+    ".": "./lib/installer.mjs",
+    "./manifest.json": "./manifest.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "scripts/postinstall.mjs",
+    "guidelines/",
+    "skills/",
+    "manifest.json",
+    "CHANGELOG.md",
+    "NOTICE.md"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/postinstall.mjs",
+    "validate": "node scripts/validate.mjs .",
+    "test": "node scripts/validate.mjs . && node --test test/installer.test.mjs test/agents.test.mjs",
+    "prepublishOnly": "npm test",
+    "version": "node -e \"const fs=require('fs');const v=JSON.parse(fs.readFileSync('package.json','utf8')).version;const m=JSON.parse(fs.readFileSync('manifest.json','utf8'));m.version=v;fs.writeFileSync('manifest.json',JSON.stringify(m,null,2)+'\\n')\" && git add manifest.json"
+  },
+  "engines": {
+    "node": ">=20.19"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/postinstall.mjs

@@ -0,0 +1,49 @@
+// Runs on `npm install` / `npm ci` (and yarn, or pnpm/bun when allowed). It keeps skills in sync in
+// a project that has opted in. It must never fail or slow down an install, so every problem is
+// reported as a one-line note and the script always exits 0.
+//
+// Opt-in: the hook never adds agent instructions to a project on its own. It syncs only when the
+// project already has `.ai/nestjs-boost.lock.json` (written by running `npx nestjs-boost install`
+// once) or a "nestjs-boost" key in package.json. Otherwise it prints how to opt in.
+//
+// Skipped when:
+//   - NESTJS_BOOST_SKIP=1, or CI is set (unless NESTJS_BOOST_CI=1)
+//   - installing globally, through npx, or inside this package's own repository
+//   - nestjs-boost isn't a direct dependency of the project (it was pulled in by another package)
+//   - the project root can't be found or isn't a NestJS project
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+const env = process.env;
+const note = (msg) => console.log(`nestjs-boost: ${msg}`);
+
+function projectRoot() {
+  // npm sets npm_config_local_prefix to the project root; INIT_CWD is where the command ran (npm, yarn, pnpm).
+  for (const dir of [env.npm_config_local_prefix, env.INIT_CWD]) {
+    if (dir && existsSync(join(dir, 'package.json'))) return resolve(dir);
+  }
+  return null;
+}
+
+async function run() {
+  if (env.NESTJS_BOOST_SKIP === '1' || env.NESTJS_BOOST_SKIP === 'true') return;
+  if (env.CI && env.NESTJS_BOOST_CI !== '1') return;
+  if (env.npm_config_global === 'true') return note('global install: run `nestjs-boost install` inside a NestJS project.');
+  if (env.npm_command === 'exec') return; // `npx nestjs-boost ...`: the command itself decides what to write
+  const root = projectRoot();
+  if (!root) return;
+  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8'));
+  if (pkg.name === 'nestjs-boost') return; // developing this package
+  if (!{ ...pkg.devDependencies, ...pkg.dependencies }['nestjs-boost']) return; // transitive dependency
+
+  const { LOCK, isNestProject, sync } = await import('../lib/installer.mjs');
+  if (!isNestProject(root)) return note('no @nestjs/core in package.json; skills not installed.');
+  if (!existsSync(join(root, LOCK)) && pkg['nestjs-boost'] === undefined) {
+    return note('run `npx nestjs-boost install` once to add the skills; later installs keep them in sync.');
+  }
+  const { skills, changes, warnings } = sync(root, {}, { force: false });
+  if (changes.length) note(`${skills.length} skills synced (${changes.length} change${changes.length === 1 ? '' : 's'}). Run \`npx nestjs-boost list\` for details.`);
+  for (const w of warnings) note(w);
+}
+
+run().catch((err) => note(`skipped (${err.message}). Run \`npx nestjs-boost install\` to retry.`));

package/skills/nestjs-ai/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: nestjs-ai
+description: Brings language models into NestJS 12 apps with @nestjs/ai on the AI SDK — AiModule.forRoot/forRootAsync with named models (Anthropic, OpenAI, Google and other @ai-sdk providers), AiService generateText, generateObject with Zod schemas and streamText to the browser (pipeUIMessageStreamToResponse, useChat), per-call/model/module timeouts, retries and fallback models on @nestjs/resilience, pricing, onUsage, budgets, AiModelError/AiOutputError/AiBudgetExceededError, @AgentFunction tools with caller, scopes, guards and AiExecutionContext, the agent loop (maxSteps, conversations), durable agent runs with human approval on @nestjs/workflows, @InjectModel and AiTools for raw AI SDK calls, and FakeModel testing. Use when adding LLM features (classification, extraction, drafting, chat assistants, agents with tools), making model calls reliable and cost-bounded, or testing code that calls models without a provider. Not for exposing the app to external assistants (nestjs-mcp-server).
+compatibility: NestJS 12.x; @nestjs/ai, @nestjs/resilience, ai (AI SDK), an @ai-sdk/* provider package, zod 4.2+; @nestjs/workflows for durable runs
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS AI (@nestjs/ai)
+
+```bash
+npm i @nestjs/ai @nestjs/resilience ai @ai-sdk/anthropic zod     # any @ai-sdk/* provider works the same way
+```
+
+The schema rules are the same as for `@nestjs/mcp`: Zod 4.2+, ArkType, or Valibot via `toStandardJsonSchema()`.
+
+```typescript
+AiModule.forRootAsync({
+  isGlobal: true,                                       // otherwise AiService is injectable only where AiModule is imported
+  imports: [ConfigModule], inject: [ConfigService],
+  useFactory: (config: ConfigService) => {
+    const anthropic = createAnthropic({ apiKey: config.getOrThrow('ANTHROPIC_API_KEY') });
+    return {
+      models: {
+        default: { model: anthropic('claude-opus-5-5'), pricing: { input: 4, output: 20, cachedInput: 0.2 }, fallback: 'backup' },
+        fast: { model: anthropic('claude-haiku-5-5'), timeout: '15s', fallback: 'default' },
+        backup: openai('gpt-5'),
+      },
+      defaults: { timeout: '30s', retry: { attempts: 3 }, maxOutputTokens: 1_000 },
+    };
+  },
+}),
+```
+
+Calls that name no model use `default`. In the module, a string such as `'openai/gpt-5'` is an AI Gateway model id; in a call, a string always names one of the module's models. Without a factory, the provider reads its key from the environment (`ANTHROPIC_API_KEY`). A setting resolves from the call first, then the model definition, then `defaults`.
+
+## Calls
+
+```typescript
+@Injectable()
+export class TriageService {
+  constructor(private readonly ai: AiService) {}
+
+  async draft(email: string) {
+    const { text } = await this.ai.generateText({
+      model: 'fast', label: 'draft-reply',                // label names the call in usage and policy events
+      instructions: 'Draft a short, friendly reply. Sign it "The Cat Store".',
+      prompt: email,                                      // or messages: ModelMessage[] (not both)
+      maxOutputTokens: 400,
+    });
+    return text;
+  }
+
+  async triage(email: string) {
+    const { object } = await this.ai.generateObject({
+      model: 'fast', label: 'triage',
+      schema: z.object({
+        category: z.enum(['shipping', 'billing', 'product', 'other']).describe('What the email is about'),
+        orderId: z.string().nullable().describe('The order id it mentions, such as ord_123, or null'),
+        urgent: z.boolean().describe('Whether the customer needs an answer today'),
+      }),
+      prompt: email,
+    });
+    return object;                                         // typed and validated; schema transforms run on the answer
+  }
+}
+```
+
+- Results include `text`, `finishReason` (`stop`, `length`, or `tool-calls` when `maxSteps` ran out), `usage`, `cost`, `steps`, `toolCalls`, `toolResults`, `responseMessages` and `model`.
+- `streamText()` returns a stream immediately. In a route, call `await answer.pipeUIMessageStreamToResponse(res)` with `@Res()`, then use `useChat()` from `@ai-sdk/react` in the browser. Use `pipeTextStreamToResponse()` for plain text. Details: reference.
+- `.describe()` texts reach the model: say what each field means and give an example value.
+
+## Reliability and cost
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| `timeout` | `'60s'` per attempt | Until the full answer (until the first chunk for streams). Tool time doesn't count. `false` = no limit |
+| `retry` | 3 attempts, backoff from `'1s'` doubling to `'30s'` with jitter | Retries 408/409/429/5xx, connection failures and timeouts; honours `retry-after` |
+| `fallback` | the model's | Models tried in order after retries run out. Only the call's own model's `fallback` is followed, so list every model. Narrow with `fallbackIf` (skip on 400). Each fallback is logged as a warning |
+| `resilience` | | A policy or a `ResilienceService` preset name (circuit breaker, bulkhead) in place of `retry`+`timeout` |
+| `budget` | | `{ maxTokens, maxCost }` per call, checked before each model call → `AiBudgetExceededError` |
+| `maxSteps` | 10 | Model calls per call while tools are requested |
+| `onUsage` | | On the module and/or the call (both run). `event.cost` needs `pricing`. A listener that throws is logged and never fails the call |
+
+Errors (all extend `AiError`):
+- `AiModelError`: every attempt on every model failed. It has `attempts` and `cause`; map it to 503 in a filter.
+- `AiOutputError`: the answer isn't valid for the schema, or tools were still being called at `maxSteps`. It carries `text` and is **never retried or sent to a fallback**.
+- `AiBudgetExceededError`.
+- `AiConfigurationError`: an unknown model, tool or option, raised before anything is sent.
+- `AiToolError`.
+
+Once a chunk has streamed or tools have started, the outcome is committed: no retry or fallback can replay it. An `abortSignal` (for example `AbortSignal.timeout(120_000)`) cancels the call immediately, without retries.
+
+`@InjectModel('fast') model: LanguageModel` gives the raw provider model for direct AI SDK calls. These calls get **none** of the timeouts, fallbacks, budgets or usage events. Pass agent functions to them with `this.tools.select(['find-order'], { caller: { request } })` from `AiTools`.
+
+## Agent functions (tools)
+
+```typescript
+@Injectable()                                      // singleton: agent functions on request-scoped providers fail at startup
+export class AssistantTools {
+  constructor(private readonly orders: OrdersService) {}
+
+  @AgentFunction({
+    name: 'change-address',                        // 1–64 chars [A-Za-z0-9_-]; defaults to the method name
+    description: 'Change the delivery address of an order that has not shipped yet',
+    inputSchema: z.object({ orderId: z.string().describe('The order id, such as ord_123'), address: z.string().min(10) }),
+    scopes: ['orders:write'],                      // checked against caller.scopes before guards
+  })
+  @UseGuards(OrderOwnerGuard)
+  changeAddress({ orderId, address }: { orderId: string; address: string }, ctx: AgentFunctionContext) {
+    return this.orders.changeAddress(orderId, address, { signal: ctx.signal });
+  }
+}
+
+// in a route: tools by name or provider class; caller = who the agent acts for
+await this.ai.generateText({ prompt: body.question, tools: ['find-order', AssistantTools], caller: { request }, maxSteps: 5 });
+// in a job: caller: { user: { id: 'refund-bot' }, scopes: ['orders:refund'] }
+```
+
+- **Order of a call:** schema validation → `scopes` → guards (global first) → interceptors → pipes → method.
+- **Context:** the type is `'ai'`. Read it with `AiExecutionContext.create(context)`, which provides `getInput()`, `getContext()`, `getName()` and `getRequest()`. HTTP-only global enhancers must check `context.getType()`.
+- **`AgentFunctionContext`:** `name`, `request`, `user`, `scopes`, `toolCallId`, `idempotencyKey` (durable runs), `messages`, `signal` and `reportProgress()`.
+- **Errors:** thrown errors are fed back to the model. `HttpException` messages pass through; other errors become `Internal server error`.
+- **Results:** return values are serialized as JSON for the model.
+- **Calls with no `caller`** run with no request, no user and no scopes.
+- **MCP:** one method can carry both `@Tool()` (`@nestjs/mcp`) and `@AgentFunction()`. Branch on `'mcp'` vs `'ai'` in guards.
+- **With `@nestjs/authentication` ≥ 0.1.4 and `@nestjs/authorization` ≥ 0.1.2:**
+  - `@CurrentUser()` and `@Can()` work in agent functions.
+  - Providers that jobs call need `@Public()`.
+
+## Workflow
+
+- [ ] 1. Install the provider package; register named models (`default` plus cheaper `fast`, with a fallback) from config; set `defaults`.
+- [ ] 2. Use `generateObject` for classification and extraction (schemas with `.describe()`), `generateText`/`streamText` for prose and chat.
+- [ ] 3. Set timeouts, retries and fallbacks; add `pricing` + `onUsage` metering and `budget` on agentic calls; map `AiModelError` to 503.
+- [ ] 4. Agent functions: model-oriented descriptions, `caller`, scopes and guards, `signal` passthrough, idempotent side effects.
+- [ ] 5. Tests with `FakeModel` / `overrideModels()` / `callTool()`, never a real provider. Build, lint, run tests, start the app.
+
+## Reference files
+
+- `references/ai-reference.md`: module options, the agent loop and conversations, streaming (errors, keep-alive, progress chunks, other stream readers), durable agent runs with approvals (`AiWorkflowsModule`, `AiAgents.run` options, `idempotencyKey`), resilience presets and diagnostics channels, Observe integration, and testing (FakeModel answers, `providerError`, `overrideModels`, `callTool`, stream and durable-run tests). Read when building chat or agents, durable flows, or tests.
+
+Sources: [Overview](https://docs.nestjs.com/ai/overview) · [Models](https://docs.nestjs.com/ai/models) · [Tools](https://docs.nestjs.com/ai/tools) · [Agents](https://docs.nestjs.com/ai/agents) · [Testing](https://docs.nestjs.com/ai/testing)

package/skills/nestjs-ai/references/ai-reference.md

@@ -0,0 +1,143 @@
+# @nestjs/ai reference
+
+## Contents
+- Module options and setting precedence
+- Resilience presets and events
+- The agent loop and conversations
+- Streaming to the browser
+- Durable agent runs
+- Testing
+
+## Module options and setting precedence
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `models` | | Required. Each value is a `LanguageModel` or `{ model, fallback, pricing, timeout, retry, resilience, maxOutputTokens, … }` |
+| `defaults.timeout` / `retry` / `resilience` | `'60s'` / 3 attempts from `'1s'` / | `retry` = `RetryPolicy` options (`attempts`, `backoff` {`delay`, `factor`, `maxDelay`, `jitter`}, `retryIf`); `false` disables |
+| `defaults.maxSteps` | `10` | Also caps durable runs (whose own default is 25) |
+| `defaults.budget` | | `maxTokens`, `maxCost` |
+| `defaults.maxOutputTokens`, `temperature`, `providerOptions`, `headers` | | Sent to the model |
+| `onUsage` | | Usage event: `label`, `model`, `step`, `attempt`, `fallback`, `stream`, `usage`, `cost`, `durationMs`, `finishReason` |
+| `include` | all modules | Where agent functions are searched |
+| `isGlobal` | `false` | Top level of `forRootAsync()` |
+| `modelNames` | | Extra names `@InjectModel()` may inject (lazy-loaded classes). Top level of `forRootAsync()` |
+
+| Setting | Where it can be set |
+| --- | --- |
+| `timeout`, `retry`, `resilience`, generation settings | call, model, `defaults` |
+| `maxSteps`, `budget` | call, `defaults` |
+| `fallback` | call, model |
+| `pricing` | model (per million tokens, in your unit) |
+| `topP`, `topK`, `seed`, `stopSequences`, penalties, `toolChoice`, `fallbackIf`, `abortSignal` | call only |
+
+`forRootAsync()` accepts `useFactory`, `useClass` (`AiOptionsFactory.createAiOptions()`) or `useExisting`. `@InjectModel('typo')` fails at startup and names the class that asked.
+
+## Resilience presets and events
+
+```typescript
+ResilienceModule.forRoot({ presets: { anthropic: { retry: { attempts: 3 }, timeout: '30s', circuitBreaker: { name: 'anthropic', failureRateThreshold: 50 } } } }),
+AiModule.forRoot({ models: { default: { model: anthropic('claude-opus-5-5'), resilience: 'anthropic', fallback: 'backup' }, backup: openai('gpt-5') } }),
+```
+
+- A preset replaces the model's `retry` and `timeout`. A preset without a timeout means **no timeout**.
+- `CircuitOpenError` or `BulkheadFullError` reaches the caller as-is when no fallback takes over.
+- Events are published on the `nestjs:resilience:retry|timeout|fallback` diagnostics channels, named `ai:<model> retry`, with `source` = the call's label: `subscribe('nestjs:resilience:retry', …)`.
+- `@nestjs/observe` ≥ 0.3.20 records the model and tokens on the outbound span. For AI Gateway ids, add `ai-gateway.vercel.sh` to `outgoing.llm.hosts`.
+
+## The agent loop and conversations
+
+- Each model call is a **step** (`result.steps[i]`: `index`, `text`, `toolCalls`, `toolResults` (`output` or `error`), `finishReason`, `usage`, `cost`, `model`, `attempts`).
+- If `maxSteps` runs out: `generateText` resolves with `finishReason: 'tool-calls'`, and `generateObject` rejects with `AiOutputError`.
+- `toolChoice`: `'auto'` (default), `'none'`, `'required'`, or `{ type: 'tool', toolName }`. Not every model supports the last two.
+- Conversations: send `messages: ModelMessage[]` and append `responseMessages` after each call. Store conversations in a database, not in memory. `instructions` aren't part of the conversation and are sent on every call.
+- A failed agent function call is a tool result the model reads, not a failed call.
+
+## Streaming to the browser
+
+```typescript
+@Post('chat')
+async chat(@Body() { messages }: { messages: UIMessage[] }, @Req() request: Request, @Res() response: Response) {
+  const answer = this.ai.streamText({
+    label: 'assistant', instructions: '…',
+    messages: await convertToModelMessages(messages),        // from 'ai'
+    tools: ['find-order', 'change-address'], caller: { request },
+  });
+  await answer.pipeUIMessageStreamToResponse(response, {
+    keepAlive: '10s',                                         // default 15 s comment lines; false disables
+    errorText: (e) => (e instanceof AiModelError ? 'The assistant is unavailable. Try again in a minute.' : 'Something went wrong.'),
+  });
+}
+// browser: useChat({ transport: new DefaultChatTransport({ api: '/assistant/chat' }), onData: (p) => p.type === 'data-tool-progress' && … })
+```
+
+- Works on Express, Fastify (`FastifyReply`, keeps pre-set headers) and the Node adapter.
+- **Errors:** a failure before the first chunk rejects normally, so route filters answer it, and retries/fallbacks still apply. A failure after it ends the stream with `An error occurred.`; customise this with `errorText`.
+- **Disconnects:** a browser disconnect aborts the model call and the tools' `signal`.
+- **Headers:** `text/event-stream` with `x-accel-buffering: no`. Add your own with `status` and `headers`.
+- **Progress:** `ctx.reportProgress()` in an agent function sends a transient `data-tool-progress` chunk `{ toolCallId, toolName, progress, total, message }`.
+- **Other readers:**
+  - `pipeTextStreamToResponse(res)` (text/plain)
+  - `textStream`, `toUIMessageStream()`, `toUIMessageStreamResponse()`
+  - promises: `text`, `usage`, `steps`, `finishReason`, `responseMessages`, `result`
+
+## Durable agent runs
+
+```bash
+npm i @nestjs/workflows
+```
+
+```typescript
+@Module({ imports: [AiWorkflowsModule], controllers: [ApprovalsController], providers: [RefundRequest, RefundTools] })   // from '@nestjs/ai/workflows'
+export class RefundsModule {}
+
+@Workflow('refund-request')
+export class RefundRequest {
+  constructor(private readonly agents: AiAgents) {}
+  run(ctx: WorkflowContext, input: { email: string; customerId: string }) {
+    return this.agents.run(ctx, {
+      label: 'refund-request', instructions: '…', prompt: input.email,
+      tools: ['find-order', 'refund'], approve: ['refund'],
+      caller: { user: { id: input.customerId }, scopes: ['orders:refund'] },
+    });
+  }
+}
+
+await this.workflows.start(RefundRequest, input, { id: `refund-${ticket.id}` });   // WorkflowClient; same id → same run
+this.agents.pendingApprovals(runId);  // [{ key, toolName, input }]
+this.agents.approve(key);  this.agents.reject(key, { reason });   // both also accept `by` (who answered), kept with the answer
+```
+
+- The app also imports `WorkflowsModule` (with a DB store) and `AiModule`.
+- Options are stored as data: models and tools by name, and `caller` as `user` + `scopes` only (there is no request after a restart). With authentication, mark the tool providers `@Public()`.
+- Calls listed in `approve` suspend the instance until a person answers, or until `approvalTimeout` passes, in which case the call doesn't run. Rejected calls tell the model the reason.
+- Agent function calls run **at least once**. Pass `ctx.idempotencyKey` to payment providers and other side effects.
+- Failed model calls retry as workflow steps (3 attempts by default). After `stepsPerInstance` (10) model calls, the run continues in a child workflow to keep journals short.
+- The output is the `generateText` result as JSON, also available via `WorkflowClient.getStatus(runId)`.
+- `run()` options: `model`, `fallback`, `instructions`, `prompt`, `messages`, `tools`, `approve`, `approvalTimeout`, `caller`, `maxSteps` (25), `stepsPerInstance` (10), `budget`, `label`, `toolChoice`, `maxOutputTokens`, `temperature`, `providerOptions`.
+
+## Testing
+
+```typescript
+import { FakeModel, providerError, overrideModels, callTool } from '@nestjs/ai/testing';
+
+const model = new FakeModel([
+  'Your order has shipped.',                                                   // text
+  { toolCalls: [{ name: 'find-order', input: { orderId: 'ord_123' } }] },     // tool call
+  (call) => `The order is ${JSON.stringify(call.toolResults[0].output)}`,      // function of the call
+  { object: { category: 'shipping', orderId: 'ord_123', urgent: false } },     // generateObject
+  providerError(529),                                                          // APICallError; retryable for 408/409/429/5xx
+]);
+```
+
+- **Answer options:**
+  - `usage` (10/10 tokens by default), `finishReason`
+  - `delay`, which abort and timeout cut short
+  - `chunkDelay`, for streams sent in word-sized chunks
+  - `streamError`
+- **Helpers:** `model.reply(...)` appends answers, and `fakeModel(...)` is a shorthand. When answers run out, the call fails with `no answer left for call N`.
+- **Inspecting calls:** `model.calls` and `model.lastCall` expose `instructions`, `lastUserMessage`, `toolResults`, `tools`, `stream` and `options`.
+- **Unit and service tests:** `AiModule.forRoot({ models: { default: new FakeModel(), fast } })` in a testing module. For retry tests, use `timeout: 50` and `retry: { attempts: 2, backoff: { delay: 0 } }`.
+- **E2E:** `overrideModels(Test.createTestingModule({ imports: [AppModule] }), { default: model })` keeps pricing, fallbacks and policies, and replaces `@InjectModel()` models too. Agent functions run for real, and their failures appear in `model.lastCall.toolResults`.
+- **Agent functions:** `callTool(moduleRef, 'change-address', input, { caller: { request: { user } } })` runs schema → scopes → enhancers → method, and rejects with `AiToolError`. A direct method call skips all of that.
+- **Streams:** POST to the chat route with `UIMessage`s and expect a 200 `text/event-stream` response, then split the body on `\n\n`.
+- **Durable runs:** use `WorkflowsModule` with the in-memory store, a `ManualWorkflowClock` and the worker off. `WorkflowWorker.drain()` advances the run. Journaled calls aren't repeated on resume.

package/skills/nestjs-architecture/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: nestjs-architecture
+description: Structures NestJS 12 applications with feature modules, providers and dependency injection — custom and async providers, injection tokens, dynamic modules (ConfigurableModuleBuilder), injection scopes, circular dependencies, ModuleRef, lazy-loaded modules and lifecycle hooks. Use when adding a feature module, sharing a provider between modules, injecting a value/config/third-party client, building a reusable forRoot/forRootAsync module, or when the app fails at startup with "Nest can't resolve dependencies", a circular-dependency or "undefined at index" error, even if the user doesn't mention DI. Not for guards/pipes/interceptors (nestjs-request-pipeline) or ConfigModule specifics (nestjs-configuration).
+compatibility: NestJS 12.x; Node 20.19+ to run, 22.22.3+/24.15+ for CLI generators
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-04"
+---
+
+# NestJS architecture and dependency injection
+
+## Default approach
+
+One **feature module** per feature: its controller, providers and DTOs live together, and only what other modules need is exported. Scaffold, then wire:
+
+```bash
+npx nest g resource billing --no-spec   # or: nest g module|service|controller billing
+```
+
+A provider used by another module must be **exported by its own module**, and the consumer **imports that module**:
+
+```typescript
+@Module({ providers: [UsersService, UsersRepository], exports: [UsersService] })
+export class UsersModule {}
+
+@Module({ imports: [UsersModule], providers: [OrdersService] })
+export class OrdersModule {}
+```
+
+Never add another module's provider to your own `providers` to "fix" a resolution error. That creates a second, independent instance, and the provider's own dependencies usually fail to resolve next.
+
+## Workflow
+
+- [ ] 1. Scaffold with `nest g` in the feature folder (`--dry-run` first if unsure where files will go).
+- [ ] 2. Implement providers. Inject classes by type; inject anything that is not a class with `@Inject(TOKEN)` (see "Tokens").
+- [ ] 3. Wire the modules: `providers` for what the module owns, `exports` for what others may inject, `imports` for modules whose exports it uses.
+- [ ] 4. Build, then **start the app once**. Resolution errors appear only at bootstrap, never at compile time.
+- [ ] 5. Run the unit and e2e tests; e2e tests that import `AppModule` catch wiring errors too.
+
+## Tokens: injecting things that are not classes
+
+Interfaces and type aliases are erased at runtime, so they cannot be tokens. Choose by what you have:
+
+| You have | Register | Inject |
+| --- | --- | --- |
+| A class | `providers: [MyService]` | `constructor(private s: MyService)` |
+| An interface-typed value (config object, client instance) | `{ provide: PAYMENT_OPTIONS, useValue: {...} }` with `export const PAYMENT_OPTIONS = Symbol('PAYMENT_OPTIONS')` | `@Inject(PAYMENT_OPTIONS) private opts: PaymentOptions` |
+| A contract with swappable implementations | `{ provide: LoggerService, useClass: PinoLogger }` where `LoggerService` is an **abstract class** | `constructor(private logger: LoggerService)`, no `@Inject()` needed |
+| A value built from other providers / async setup | `{ provide: DB, useFactory: async (cfg: ConfigService) => connect(cfg.get('DB_URL')), inject: [ConfigService] }` | `@Inject(DB)` |
+| An alias of an existing provider | `{ provide: 'AliasedLogger', useExisting: LoggerService }` | `@Inject('AliasedLogger')` |
+
+Put tokens in their own file (e.g. `payments.constants.ts`), not in the module file: a module file that both declares a token and imports the provider using it causes a circular file import.
+
+## Decision points
+
+- **Reusable module configured by its consumer** (`forRoot`/`forRootAsync`/`register`) → use `ConfigurableModuleBuilder`; read `references/dynamic-modules.md`.
+- **Per-request state** (tenant, user) → `Scope.REQUEST` or `@Inject(REQUEST)`. Scope bubbles up: every consumer of a request-scoped provider becomes request-scoped. Read `references/scopes-lifecycle.md` first and prefer `AsyncLocalStorage` (see the nestjs-logging skill) when only context needs to travel.
+- **Two providers need each other** → refactor first (extract a third provider). If unavoidable, use `forwardRef()` on **both** sides; see `references/troubleshooting.md`.
+- **Startup or shutdown work** (connect, warm caches, close connections) → `onModuleInit` / `onApplicationBootstrap` / `onModuleDestroy` / `onApplicationShutdown`. Shutdown hooks run only after `app.close()`, or on a signal if `app.enableShutdownHooks()` was called in `main.ts`.
+- **Load a heavy module only when needed** → `LazyModuleLoader`; lifecycle hooks do not run in lazy-loaded modules.
+- **Resolve providers dynamically** → `ModuleRef.get()` for singletons; `ModuleRef.resolve()` for request-scoped/transient ones (`get()` can't retrieve them).
+
+## Gotchas
+
+- **`Nest can't resolve dependencies ... argument X at index [n] is available in the Y module`:** X is neither in Y's `providers` nor exported by a module Y imports. Fix the export/import; don't duplicate the provider. Full procedure in `references/troubleshooting.md` ([Common errors](https://docs.nestjs.com/faq/common-errors)).
+- **`... the argument at index [n] is available in the current module` (no token name):** the dependency is `undefined` at runtime. The usual causes are an interface/type used as the parameter type, an `import type` of an injectable class, or a circular file import.
+- **Barrel files** (`index.ts`) re-exporting modules and providers cause circular-import errors. Import from the concrete file ([Circular dependency](https://docs.nestjs.com/fundamentals/circular-dependency)).
+- **ESM projects** (`"type": "module"`) import local files with a `.js` extension: `import { UsersService } from './users.service.js'`.
+- **`@Global()`** is for app-wide infrastructure only (config, logging, database). Making feature modules global hides dependencies and is "not a good design decision" ([Modules](https://docs.nestjs.com/modules)).
+- **Lifecycle hooks** do not run for request-scoped providers, and in v12 they are called by component hierarchy level. Don't rely on the order between sibling providers ([Migration guide](https://docs.nestjs.com/migration-guide)).
+- **`@Optional()` is not inherited** by a subclass that declares its own constructor (v12); repeat it on the subclass parameter.
+- **Passport strategies and cron jobs must stay singletons**; never make their dependencies request-scoped ([Injection scopes](https://docs.nestjs.com/fundamentals/injection-scopes)).
+- **SWC/ESM and circular DI:** wrap the type of a `forwardRef()` dependency in a `WrapperType<T> = T` alias (or the ORM's `Relation<T>`), so its type isn't emitted into decorator metadata ([SWC](https://docs.nestjs.com/recipes/swc)).
+- **Debugging:** set `NEST_DEBUG=1` to log how each dependency is resolved and in which module Nest looks for it.
+
+## Reference files
+
+- `references/troubleshooting.md`: step-by-step diagnosis of resolution, undefined-dependency and circular-dependency errors, `forwardRef` patterns, monorepo duplicate `@nestjs/core`. Read when the app fails at startup or a dependency is `undefined`.
+- `references/dynamic-modules.md`: `ConfigurableModuleBuilder`, `forRoot`/`forRootAsync`, custom method keys, extra options. Read when building a configurable module.
+- `references/scopes-lifecycle.md`: injection scopes, `REQUEST`/`INQUIRER`, durable providers, lifecycle hook order, shutdown hooks, lazy loading, `ModuleRef`, `DiscoveryService`. Read before making anything request-scoped or relying on hook order.
+
+Sources: [Providers](https://docs.nestjs.com/providers) · [Modules](https://docs.nestjs.com/modules) · [Custom providers](https://docs.nestjs.com/fundamentals/custom-providers) · [Common errors](https://docs.nestjs.com/faq/common-errors)

package/skills/nestjs-architecture/references/dynamic-modules.md

@@ -0,0 +1,92 @@
+# Dynamic modules with ConfigurableModuleBuilder
+
+Source: [Dynamic modules](https://docs.nestjs.com/fundamentals/dynamic-modules) (NestJS 12).
+
+## Contents
+- Naming: register vs forRoot vs forFeature
+- Building a configurable module (default path)
+- Consumer side: sync and async
+- Options factory classes
+- Extra options (e.g. isGlobal)
+- Extending generated methods
+
+## Naming: register vs forRoot vs forFeature
+
+| Method | Meaning |
+| --- | --- |
+| `register()` | Configures the module for the calling module only. Each importer can pass different options. |
+| `forRoot()` | Configured once (usually in `AppModule`), shared everywhere. |
+| `forFeature()` | Uses the `forRoot()` configuration, adjusted for the calling module (e.g. which repositories it can inject). |
+
+Each has an async twin (`registerAsync`, `forRootAsync`, `forFeatureAsync`) that resolves options through DI.
+
+## Building a configurable module (default path)
+
+Don't hand-write `static register()`/`registerAsync()`. Use the builder in a separate `*.module-definition.ts` file:
+
+```typescript
+// id-generator.module-definition.ts
+import { ConfigurableModuleBuilder } from '@nestjs/common';
+import type { IdGeneratorModuleOptions } from './id-generator.interfaces.js';
+
+export const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } =
+  new ConfigurableModuleBuilder<IdGeneratorModuleOptions>()
+    .setClassMethodName('forRoot') // omit to get register()/registerAsync()
+    .build();
+```
+
+```typescript
+// id-generator.module.ts
+@Module({ providers: [IdGenerator], exports: [IdGenerator] })
+export class IdGeneratorModule extends ConfigurableModuleClass {}
+```
+
+```typescript
+// id-generator.ts — inject the generated options token
+@Injectable()
+export class IdGenerator {
+  constructor(@Inject(MODULE_OPTIONS_TOKEN) private readonly options: IdGeneratorModuleOptions) {}
+}
+```
+
+The metadata returned by the generated methods is merged with the `@Module()` metadata, so `providers`/`exports` in the decorator still apply.
+
+## Consumer side
+
+```typescript
+IdGeneratorModule.forRoot({ prefix: 'id' })
+
+IdGeneratorModule.forRootAsync({
+  imports: [ConfigModule],               // modules whose exports the factory needs
+  useFactory: (config: ConfigService) => ({ prefix: config.getOrThrow<string>('ID_PREFIX') }),
+  inject: [ConfigService],               // order matches the factory's parameters
+})
+```
+
+Async options accept exactly one of `useFactory`, `useClass` or `useExisting`. `provideInjectionTokensFrom` lets a module forward providers it already has into the factory's `inject` list.
+
+## Options factory classes
+
+`useClass`/`useExisting` take a class implementing `ConfigurableModuleOptionsFactory<Options, 'create'>`, i.e. a `create()` method returning the options. Rename the expected method with `.setFactoryMethodName('createIdGeneratorOptions')`.
+
+## Extra options (e.g. isGlobal)
+
+Options that change the module definition but must not reach `MODULE_OPTIONS_TOKEN`:
+
+```typescript
+new ConfigurableModuleBuilder<IdGeneratorModuleOptions>()
+  .setExtras({ isGlobal: false }, (definition, extras) => ({ ...definition, global: extras.isGlobal }))
+  .build();
+```
+
+The injected options object does not contain `isGlobal`.
+
+## Extending generated methods
+
+```typescript
+export class IdGeneratorModule extends ConfigurableModuleClass {
+  static forRoot(options: typeof OPTIONS_TYPE): DynamicModule {
+    return { ...super.forRoot(options) /* plus your additions */ };
+  }
+}
+```