glirastes 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-04-28
+
+### Added
+
+- Dual-bundle output (CJS + ESM). The package now ships a CommonJS build at
+  `dist/cjs/` alongside the ESM build at `dist/`, so legacy NestJS backends
+  on `module: commonjs` can consume `glirastes/server/nestjs` without an ESM
+  migration. The `exports` map uses conditional `import`/`require` branches
+  with their own typings.
+- Legacy subpath shim directories at the package root (`server/`, `react/`,
+  `codegen/`, `openapi/`) so consumers on `moduleResolution: node` (without
+  `exports`-map support) still resolve subpaths.
+- Pre-built agent skills under `skills/` (shipped in the npm tarball):
+  `integrating-glirastes-nextjs`, `integrating-glirastes-nestjs`,
+  `integrating-glirastes-nextjs-with-nestjs-backend`,
+  `maintaining-glirastes-tools`, `building-glirastes-chat-ui`. Drop into
+  `.claude/skills/` (or `.codex/skills/`) to give a coding agent
+  framework-specific guidance for integrating, maintaining, and customizing
+  the SDK.
+- New CLI command `glirastes install-skills` — installs the bundled agent
+  skills into a target directory. Flags:
+  - default: `./.claude/skills` (project-local)
+  - `-g` / `--global`: `~/.claude/skills` (shared across all projects on the
+    machine; mutually exclusive with `--target`)
+  - `--target <dir>`: override the destination (accepts relative, absolute,
+    or `~/`-prefixed paths)
+  - `--stack nextjs|nestjs|nextjs+nestjs|all` (default `all`): filter
+  - `--symlink`: track the installed SDK version automatically
+  - `--force`: overwrite existing
+  - `--dry-run`: preview without writing
+- Adapter-selection guidance in the README: when both a frontend and a
+  separate backend exist, put the chat route on the backend.
+- Scaling-up section in the README explaining the `glirastes scaffold` →
+  `generate-tools` → registry-import codegen workflow.
+
+### Changed
+
+- `@ai-sdk/react` and `react-markdown` moved from `dependencies` to optional
+  `peerDependencies`. Backend-only consumers no longer pull a phantom React
+  tree into `node_modules`. Frontend consumers must install them themselves
+  (the README install section is split per stack).
+- `dependencies.zod` bumped to `^3.25.76` to match what `ai@6` and
+  `@ai-sdk/openai` require.
+- `AiChatModule.attachWebSockets()` is now `async`. Consumers that enable
+  the speech-to-text feature must `await` the call.
+
+### Fixed
+
+- Optional peer `wavesurfer.js` is now truly optional. The voice
+  components load it via a runtime `Function('s', 'return import(s)')`
+  helper so browser-side bundlers (Webpack, Turbopack, Vite, esbuild)
+  don't try to resolve the specifier at build time when the package is
+  not installed. Note: requires `script-src 'unsafe-eval'` CSP — projects
+  with strict CSP should install `wavesurfer.js` unconditionally to
+  bypass the runtime trick. See `skills/building-glirastes-chat-ui` for
+  details.
+- Optional peer `ws` is now truly optional. The NestJS speech-to-text
+  gateway uses a plain dynamic `import('ws')` inside `attachWebSockets`,
+  guarded by try/catch — backends that don't enable speech-to-text no
+  longer crash with `ERR_MODULE_NOT_FOUND` at startup. (Bundled NestJS
+  deployments must either install `ws` unconditionally or mark it as a
+  bundler external.)
+
+## [0.3.0] - 2026-04-28
+
+### Fixed
+
+- README NestJS examples now match the real decorator API: `@AiTool({ name })`
+  not `toolName`, `@AiModule({ intent, classification })` takes an options
+  object, `scanNestJsControllers({ controllers })` takes an options object
+  and returns `{ tools, modules, toolsByModule }` (destructure `.tools`
+  before passing to `endpointToolsToRegistry`).
+- Stream handler no longer emits the fallback `"No output generated.
+  Check the stream for errors."` event when an upstream error has
+  already been streamed in the same response.
+
+### Changed
+
+- Peer-dep range for `@nestjs/common`, `@nestjs/core`, `@nestjs/config`,
+  `@nestjs/swagger` widened to support v10 alongside v11.
+
+### Added
+
+- `examples/quickstart-nestjs/` and `examples/quickstart-nextjs/` —
+  compile-tested in CI via `tests/examples-compile.test.ts`. What you
+  copy from the README is what compiles.
+- README "Setup notes" section: recommended `tsconfig.json` (so
+  `Cannot find module 'glirastes/server/nestjs'` no longer surprises
+  consumers on legacy `moduleResolution`) and a subpath decision-tree
+  table.
+- `FOLLOWUPS.md` capturing deferred work: dual ESM+CJS bundle,
+  `glirastes`+`glirastes-react` split for production trim, optional
+  `baseUrl` for endpoint tools, registry sugar, CLI docs.
+- `DEFAULT_SAFETY_MAX_STEPS` and `resolveStepLimit` are now public exports
+  so consumers can pin / replicate the safety-cap behaviour in tests.
+
 ## [0.2.1] - 2026-04-27
 
 ### Changed

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,85 @@
+
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at hello@chainmatics.net. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing to glirastes
+
+Thanks for your interest in contributing! This document describes how to
+propose changes to the project.
+
+## Code of Conduct
+
+This project follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+By participating you agree to uphold its terms. Report unacceptable behavior to
+**conduct@chainmatics.net**.
+
+## Development Setup
+
+Requirements:
+
+- [Bun](https://bun.sh) ≥ 1.0
+- Node.js ≥ 20 (for compatibility checks; runtime is Bun)
+
+```bash
+git clone https://github.com/chainmatics/glirastes.git
+cd glirastes
+bun install
+bun run typecheck
+bun run test
+bun run build
+```
+
+There is no linter or formatter; TypeScript strict mode is the only static
+check.
+
+## Submitting Changes
+
+1. Fork the repository and create a branch from `main`
+2. Keep PRs **small and focused** — one logical change per PR
+3. Make sure `bun run typecheck` and `bun run test` pass locally
+4. Use [Conventional Commits](https://www.conventionalcommits.org/) for commit
+   messages, e.g. `feat(server): add streaming support`
+5. Open the PR with a clear description of *what* changed and *why*
+
+## Developer Certificate of Origin (DCO)
+
+We use the [Developer Certificate of Origin](https://developercertificate.org/)
+rather than a CLA. By contributing, you certify that you have the right to
+submit your work under the project license (Apache-2.0).
+
+Sign-off is **encouraged but not enforced** in CI today. If you want to
+sign-off your commits — or for substantial contributions where provenance
+matters — append a `Signed-off-by` trailer:
+
+```bash
+git commit -s -m "feat(server): add streaming support"
+```
+
+This adds a `Signed-off-by: Your Name <you@example.com>` line.
+
+## Code Style
+
+- TypeScript **strict mode** — no `any` without justification
+- ESM only (`"type": "module"`)
+- Relative imports only — no path aliases
+- Avoid comments unless they explain a non-obvious *why*
+- Tests use Vitest; place them next to the source as `*.test.ts`
+
+## Reporting Bugs
+
+[Open an issue](https://github.com/chainmatics/glirastes/issues/new/choose)
+and include:
+
+- `glirastes` version (`bun pm ls glirastes`)
+- Minimal reproduction (a tiny repo or gist is best)
+- Expected vs actual behavior
+- Stack trace, if any
+
+## Reporting Security Issues
+
+**Do not** open a public issue for security vulnerabilities. See
+[SECURITY.md](SECURITY.md) for the private reporting channel.
+
+## Releasing
+
+Releases are published from CI on tagged commits. Maintainers only:
+
+1. Bump `version` in `package.json`
+2. Commit and push to `main`
+3. `git tag v<version> && git push origin v<version>`
+
+The `Publish glirastes` workflow builds and publishes to npm with provenance.

package/README.md

@@ -10,11 +10,13 @@
 </p>
 
 <p align="center">
-  <a href="#quick-start"><strong>Quick Start</strong></a> ·
+  <a href="#quick-start-nextjs-or-nestjs"><strong>Quick Start</strong></a> ·
   <a href="#core-concepts"><strong>Concepts</strong></a> ·
   <a href="#examples"><strong>Examples</strong></a> ·
   <a href="#advanced"><strong>Advanced</strong></a> ·
-  <a href="#cli"><strong>CLI</strong></a>
+  <a href="#scaling-up--codegen-workflow"><strong>Scaling up</strong></a> ·
+  <a href="#cli"><strong>CLI</strong></a> ·
+  <a href="#agent-skills"><strong>Skills</strong></a>
 </p>
 
 <p align="center">
@@ -83,31 +85,61 @@ Building an AI feature means wiring together **tool definitions**, **API calls**
 
 <br/>
 
-## Quick Start ([Next.js](https://nextjs.org/) + [Vercel AI SDK](https://sdk.vercel.ai/))
+## Quick Start ([Next.js](https://nextjs.org/) or [NestJS](https://nestjs.com/))
+
+### Which adapter should I use?
+
+If you only have one server, the answer is "that one". If you have **both** a Next.js frontend *and* a separate backend (NestJS, Express, …), put the chat route on the **backend**:
+
+| Setup | Use this adapter |
+|---|---|
+| Next.js full-stack (no separate backend) | `glirastes/server/nextjs` |
+| Next.js frontend + NestJS backend | `glirastes/server/nestjs` ✅ |
+| Pure NestJS (Swagger UI as client) | `glirastes/server/nestjs` |
+| Express backend + any frontend | `glirastes/server` (manual wiring) |
+
+**Why prefer the real backend over a Next.js Route Handler?**
+
+- **Tools are annotated controllers.** Your existing endpoints become AI-callable in place — no second code path, no `defineEndpointTool` mirroring controller URLs.
+- **One auth source.** Your JWT guard / tenant context already runs there. Don't re-validate tokens in a Next.js route just to forward them.
+- **No extra HTTP hop.** Browser → backend → DB instead of Browser → Next.js → backend → DB on every tool call.
+- **Tools can call services directly.** No HTTP membrane between the AI tool and your business logic.
+- **One observability pipeline.** Logs, traces, rate limits where they already live.
+
+The Next.js Route Handler is right when Next.js *is* your backend, when you're prototyping, or when every tool is an external API call anyway.
+
+Pick your stack — both come up in the same four steps.
 
 ### 1. Install
 
 ```bash
+# Backend only (NestJS / Next.js Route Handlers)
 npm install glirastes
+
+# Frontend / chat UI consumers — add the React UI peers
+npm install glirastes @ai-sdk/react react-markdown
 ```
 
-> **Requirements:** Node.js `>=20`, React `^19` (for the chat UI — `react-dom` is pinned to `^19`).
+The Vercel AI SDK (`ai`) is bundled. `@ai-sdk/react` and `react-markdown` are declared as **optional peer dependencies** so backend-only consumers don't have a phantom React tree in their `node_modules`. Install them yourself when you use any `glirastes/react/*` subpath.
+
+> **Requirements:** Node.js `>=20`. The React chat UI needs `react` and `react-dom` `^19` — Next.js apps already have these.
 >
-> **Peer dependencies for the React chat UI** (only install what you use):
+> **Optional** — only if you want voice input with a live waveform:
 > ```bash
-> # Required for VercelAiChat / LangGraphAiChat:
-> npm install react react-dom ai @ai-sdk/react
->
-> # Optional — enables Markdown rendering in messages (falls back to plain text):
-> npm install react-markdown
->
-> # Optional — enables waveform visualization for voice input:
 > npm install wavesurfer.js
 > ```
 
-### 2. Define a tool next to your API route
+### 2. Define a tool
 
-Co-locate the tool definition with the `route.ts` it exposes. The SDK uses the declared `method` + `path` to call your own API when the LLM picks this tool — you never write a `fetch` yourself.
+The SDK uses the declared `method` + `path` (or the route the decorator already exposes) to call your own API when the LLM picks this tool — you never write a `fetch` yourself.
+
+<table>
+<tr>
+<th>Next.js — co-located <code>ai-tool.ts</code></th>
+<th>NestJS — decorators on your controller</th>
+</tr>
+<tr>
+<td valign="top">
 
 ```ts
 // app/api/tasks/ai-tool.ts
@@ -126,7 +158,39 @@ export const listTasks = defineEndpointTool({
 });
 ```
 
-### 3. Drop a chat widget into `app/layout.tsx`
+</td>
+<td valign="top">
+
+```ts
+// tasks.controller.ts
+import { Controller, Get, Query } from '@nestjs/common';
+import { AiModule, AiTool } from 'glirastes/server/nestjs';
+
+@Controller('tasks')
+@AiModule({
+  intent: 'task_management',
+  classification: {
+    hint: 'User asks about listing or filtering tasks.',
+    examples: ['show me open tasks', 'what is done?', 'list my tasks'],
+  },
+})
+export class TaskController {
+  @Get()
+  @AiTool({
+    name: 'list_tasks',
+    description: 'List tasks with an optional status filter.',
+  })
+  list(@Query('status') status?: 'open' | 'done') {
+    return this.taskService.list(status);
+  }
+}
+```
+
+</td>
+</tr>
+</table>
+
+### 3. Drop a chat widget into your frontend
 
 ```tsx
 'use client';
@@ -142,7 +206,15 @@ export default function RootLayout({ children }) {
 }
 ```
 
-### 4. Wire up `app/api/chat/route.ts`
+### 4. Wire up the chat handler
+
+<table>
+<tr>
+<th>Next.js — <code>app/api/chat/route.ts</code></th>
+<th>NestJS — register controllers in <code>AiChatModule</code></th>
+</tr>
+<tr>
+<td valign="top">
 
 ```ts
 import { createAiChatHandler } from 'glirastes/server/nextjs';
@@ -154,7 +226,62 @@ export const POST = createAiChatHandler({
 });
 ```
 
-Done. AI chat is live, streaming, and your `list_tasks` tool is callable. Add more tools the same way — one `ai-tool.ts` per route, import them all in `app/api/chat/route.ts`.
+</td>
+<td valign="top">
+
+```ts
+import { scanNestJsControllers } from 'glirastes/server/nestjs';
+import { endpointToolsToRegistry } from 'glirastes/server';
+import { TaskController } from './tasks/tasks.controller';
+
+const scan = scanNestJsControllers({ controllers: [TaskController] });
+const registry = endpointToolsToRegistry(scan.tools);
+
+// Pass `registry` to createAiChatHandler in your chat route.
+```
+
+</td>
+</tr>
+</table>
+
+Done. AI chat is live, streaming, and your `list_tasks` tool is callable. Add more tools the same way — pick the style that matches your stack. See [NestJS with decorators](#nestjs-with-decorators) below for DTOs, `@AiParam`, and multi-controller scanning.
+
+### Setup notes
+
+#### tsconfig — modern is best, legacy still works
+
+Glirastes ships **both** ESM (`dist/`) and CommonJS (`dist/cjs/`) with a conditional `exports` map, plus subpath shim directories at the package root for legacy resolvers. Both setups below are supported:
+
+**Modern (recommended):**
+
+```jsonc
+{
+  "compilerOptions": {
+    "module": "node16",          // or "nodenext" / "esnext"
+    "moduleResolution": "node16", // or "nodenext" / "bundler"
+    "target": "ES2022",
+    "esModuleInterop": true,
+    "experimentalDecorators": true,    // NestJS only
+    "emitDecoratorMetadata": true      // NestJS only
+  }
+}
+```
+
+**Legacy NestJS template (default `module: commonjs`):** works as-is — no tsconfig changes required. The shim directories under `glirastes/server/`, `glirastes/react/` etc. let the classic Node resolver find each subpath, and the CommonJS build under `dist/cjs/` provides the runtime artifacts.
+
+#### Which subpath do I import from?
+
+| Where the code runs | Import from |
+|---|---|
+| Anywhere (tool definitions, types, helpers) | `glirastes` |
+| Server-side core (registry helpers, pipeline) | `glirastes/server` |
+| Next.js App Router route handlers | `glirastes/server/nextjs` |
+| NestJS controllers / modules | `glirastes/server/nestjs` |
+| Test suite without LLM calls | `glirastes/server/testing` |
+| React components, client hooks | `glirastes/react` |
+| Vercel AI SDK chat widget | `glirastes/react/vercel` |
+| LangGraph chat widget | `glirastes/react/langgraph` |
+| Default chat panel CSS | `glirastes/react/styles.css` |
 
 <br/>
 
@@ -307,15 +434,21 @@ Prefer declaring tools where the endpoint lives? Use NestJS decorators. Three pi
 
 ```ts
 // tasks.controller.ts
-import { Controller, Post, Body } from '@nestjs/common';
+import { Controller, Post, Body, Get, Param } from '@nestjs/common';
 import { AiModule, AiTool } from 'glirastes/server/nestjs';
 
 @Controller('tasks')
-@AiModule('task_management')
+@AiModule({
+  intent: 'task_management',
+  classification: {
+    hint: 'User wants to create, update, or query tasks.',
+    examples: ['create a task', 'mark task as done', 'list my tasks'],
+  },
+})
 export class TaskController {
   @Post()
   @AiTool({
-    toolName: 'create_task',
+    name: 'create_task',
     description: 'Create a new task',
   })
   async create(@Body() dto: CreateTaskDto) {
@@ -355,11 +488,13 @@ Wire it up in your `AiChatModule`:
 import { scanNestJsControllers } from 'glirastes/server/nestjs';
 import { endpointToolsToRegistry } from 'glirastes/server';
 
-const definitions = scanNestJsControllers([TaskController, /* ...other controllers */]);
-const registry = endpointToolsToRegistry(definitions);
+const scan = scanNestJsControllers({
+  controllers: [TaskController, /* ...other controllers */],
+});
+const registry = endpointToolsToRegistry(scan.tools);
 ```
 
-Pass `registry` to `createAiChatHandler({ tools: registry })`. No separate `ai-tool.ts` files, no manual registration.
+`scanNestJsControllers` returns `{ tools, modules, toolsByModule }` — pass `scan.tools` to `endpointToolsToRegistry`, then hand `registry` to `createAiChatHandler({ tools: registry })`. No separate `ai-tool.ts` files, no manual registration.
 
 ### Client-side action handlers
 
@@ -637,6 +772,65 @@ The voice button streams audio to your backend, which proxies it to a speech-to-
 
 <br/>
 
+## Scaling up — codegen workflow
+
+Hand-importing 50 tool definitions into your chat route doesn't scale. The CLI generates a registry from co-located `*.ai-tool.ts` files so you can stay co-located while still wiring everything centrally.
+
+### 1. Bootstrap a tool from an existing route
+
+```bash
+npx glirastes scaffold --route src/app/api/tasks/route.ts
+# --dry-run to preview, --force to overwrite
+```
+
+Produces `src/app/api/tasks/ai-tool.ts` with a starter `defineEndpointTool({ ... })` call — input schema derived from your route, TODO description, sensible defaults. Edit, save.
+
+### 2. Wire the codegen into your scripts
+
+```json
+{
+  "scripts": {
+    "predev":   "glirastes generate-tools --quiet",
+    "prebuild": "glirastes generate-tools --quiet",
+    "ai:scaffold":     "glirastes scaffold",
+    "ai:coverage":     "glirastes coverage",
+    "ai:coverage:ci":  "glirastes coverage --ci",
+    "ai:validate":     "glirastes validate-tools",
+    "ai:validate:ci":  "glirastes validate-tools --ci",
+    "ai:test":         "glirastes test"
+  }
+}
+```
+
+`predev` / `prebuild` regenerate `src/generated/ai-tools/{endpoint,ui,modules,action-ids}.generated.ts` on every dev start and CI build — the generated registry becomes source-of-truth.
+
+### 3. Import the registry in your chat route
+
+```ts
+// app/api/chat/route.ts (Next.js)
+import { createAiChatHandler } from 'glirastes/server/nextjs';
+import { endpointToolRegistry } from '@/generated/ai-tools/endpoint.generated';
+import { uiToolRegistry } from '@/generated/ai-tools/ui.generated';
+
+export const POST = createAiChatHandler({
+  tools: { ...endpointToolRegistry, ...uiToolRegistry },
+  model: openai('gpt-4o-mini'),
+});
+```
+
+NestJS users skip this entire workflow: `scanNestJsControllers` reads your `@AiTool`-decorated controllers at runtime. No co-located files, no `*.generated.ts`. See [NestJS with decorators](#nestjs-with-decorators).
+
+### 4. CI gates
+
+```bash
+npm run ai:coverage:ci   # fails if any route lacks an ai-tool.ts (or has an orphan handler)
+npm run ai:validate:ci   # fails if a tool definition is malformed or path-mismatched
+```
+
+For the full deep-dive — UI patterns, intent modules, approval flow, naming conventions, deterministic testing — drop the [`maintaining-glirastes-tools`](./skills/maintaining-glirastes-tools/SKILL.md) skill into your agent. See [Agent skills](#agent-skills) below.
+
+<br/>
+
 ## CLI
 
 The SDK includes a `glirastes` CLI for scaffolding, code generation, and validation. Run any command with `npx glirastes <command>` or `bunx glirastes <command>`:
@@ -651,6 +845,7 @@ The SDK includes a `glirastes` CLI for scaffolding, code generation, and validat
 | `generate-skills` | Export tools as Claude Code / Codex skill files |
 | `generate-mcp-server` | Export tools as a standalone MCP server project |
 | `generate-auto` | Auto-detect layout and run the right generator |
+| `install-skills` | Install the bundled agent skills under `skills/` into your repo (e.g. `.claude/skills/`) |
 | `validate` | Validate OpenAPI spec for `x-ai` correctness |
 | `validate-tools` | Validate AI tool configuration |
 | `coverage` | Report which API routes have AI tools and which don't |
@@ -661,6 +856,56 @@ The SDK includes a `glirastes` CLI for scaffolding, code generation, and validat
 
 <br/>
 
+## Agent skills
+
+Glirastes ships pre-built [agent skills](https://docs.claude.com/en/docs/claude-code/skills) under [`skills/`](./skills) that teach a coding agent (Claude Code, Codex, Cursor, …) how to integrate, maintain, and customize the SDK. Drop them into your repo and the agent picks the right one automatically.
+
+| Skill | Use when |
+|---|---|
+| [`integrating-glirastes-nextjs`](./skills/integrating-glirastes-nextjs/SKILL.md) | Adding chat to a Next.js app where Next.js is the backend |
+| [`integrating-glirastes-nestjs`](./skills/integrating-glirastes-nestjs/SKILL.md) | Adding chat to a NestJS backend (with or without a frontend) |
+| [`integrating-glirastes-nextjs-with-nestjs-backend`](./skills/integrating-glirastes-nextjs-with-nestjs-backend/SKILL.md) | Full-stack setup: Next.js frontend + separate NestJS backend |
+| [`maintaining-glirastes-tools`](./skills/maintaining-glirastes-tools/SKILL.md) | Authoring `ai-tool.ts`, intent modules, codegen, all CLI commands |
+| [`building-glirastes-chat-ui`](./skills/building-glirastes-chat-ui/SKILL.md) | Customizing the chat UI — theming, mentions, voice input, action bus |
+
+### Install via the bundled CLI
+
+After `npm install glirastes`, run the bundled installer. Two scopes:
+
+- **Project-local** (default): writes to `./.claude/skills`. Each project gets the skills tied to its own installed `glirastes` version. Best for teams checking the directory into git.
+- **Global** (`-g`): writes to `~/.claude/skills`. Shared across every project on the machine. Best for solo work across multiple Glirastes projects.
+
+```bash
+# Project-local — installs into ./.claude/skills (default)
+npx glirastes install-skills
+
+# Global — installs into ~/.claude/skills (shared across all projects on this machine)
+npx glirastes install-skills -g
+
+# Only the skills relevant to your stack
+npx glirastes install-skills --stack nextjs            # Next.js standalone
+npx glirastes install-skills --stack nestjs            # NestJS standalone
+npx glirastes install-skills --stack nextjs+nestjs     # full-stack monorepo
+
+# Different agent? Pass --target
+npx glirastes install-skills --target .codex/skills
+
+# Auto-update with the SDK on every npm install
+npx glirastes install-skills --symlink
+
+# Preview without writing
+npx glirastes install-skills --dry-run
+
+# Overwrite previously installed skills
+npx glirastes install-skills --force
+```
+
+`install-skills` reads the bundled skills under `node_modules/glirastes/skills/` and writes them to your repo. The `--symlink` mode keeps them auto-fresh — bumping `glirastes` and rerunning `npm install` updates the skill content without re-running the installer.
+
+> **`generate-skills` (CLI command) ≠ these skills.** `generate-skills` exports *your tools* as skill files so external agents can call them. The skills under `skills/` instruct an agent on how to *integrate Glirastes itself*. Both ship in the npm package; they don't conflict.
+
+<br/>
+
 ## License
 
 Licensed under the [Apache License, Version 2.0](./LICENSE). You may use, modify, and distribute this SDK freely in commercial and non-commercial projects.