glirastes 0.3.0 → 0.3.1

package/skills/integrating-glirastes-nestjs/SKILL.md

@@ -0,0 +1,346 @@
+---
+name: integrating-glirastes-nestjs
+description: Integrating the Glirastes SDK into a NestJS backend — AiChatModule wiring, @AiTool / @AiModule / @AiParam decorators, scanNestJsControllers, attachWebSockets for speech-to-text. Use when adding AI chat to a NestJS service or to a NestJS+Next.js full-stack app.
+version: 1.0.0
+tags:
+  - glirastes
+  - nestjs
+  - ai
+  - decorators
+triggers:
+  - integrate glirastes nestjs
+  - AiChatModule
+  - AiModule decorator
+  - AiTool decorator
+  - AiParam
+  - scanNestJsControllers
+  - chat module nestjs
+  - ai chat backend
+  - attachWebSockets
+---
+
+# Integrating Glirastes into NestJS
+
+> **Why pick this adapter:** NestJS already has your auth (JWT guard), tenant context, services and controllers. The decorators turn existing controllers into AI-callable tools — no second code path, no HTTP hop from frontend to backend per tool call. If you also have a Next.js frontend in the same workspace, the chat route still belongs **here**, not in a Next.js Route Handler.
+>
+> **Companion skills:**
+> - [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md) — tool authoring deep-dive, all CLI commands, codegen workflow
+> - [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md) — chat UI in your frontend (talks to this backend)
+
+## Stack detection
+
+Confirm before applying:
+
+- `nest-cli.json` exists at the project root → NestJS ✅
+- `package.json` has `@nestjs/core` and `@nestjs/common`
+- TypeScript backend (this adapter is type-driven)
+
+## Step 1 — Install
+
+```bash
+npm install glirastes @ai-sdk/openai
+# Optional: speech-to-text proxy via Deepgram WebSocket
+npm install ws
+```
+
+`@ai-sdk/openai` is the OpenAI provider — swap for `@ai-sdk/anthropic`, `@ai-sdk/mistral`, etc. as needed.
+
+`ws` is **only** needed if you enable `features.speechToText` and call `AiChatModule.attachWebSockets(app)`. Without that feature it's never loaded.
+
+## Step 2 — Environment variables
+
+`.env`:
+
+```
+OPENAI_API_KEY=sk-...
+# Optional speech-to-text:
+# DEEPGRAM_API_KEY=...
+# Optional Glirastes platform (PII Shield, intent routing, telemetry):
+# GLIRASTES_API_KEY=glir_...
+```
+
+## Step 3 — `tsconfig.json`
+
+The default NestJS template (`module: "commonjs"`) works as-is on Glirastes 0.3.1+ — no changes needed. The package ships dual CJS+ESM bundles plus subpath shims.
+
+If you're on a modern setup, this also works:
+
+```jsonc
+{
+  "compilerOptions": {
+    "module": "node16",          // or "nodenext" / "esnext"
+    "moduleResolution": "node16", // or "nodenext" / "bundler"
+    "target": "ES2022",
+    "esModuleInterop": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+`emitDecoratorMetadata` and `experimentalDecorators` are **required** — Glirastes' decorator scanner reads metadata.
+
+## Step 4 — Annotate existing controllers
+
+Two decorators turn an existing controller into an AI module:
+
+- `@AiModule({ intent, classification })` on the class — declares the intent group + classification hints
+- `@AiTool({ name, description })` on each AI-callable method
+- `@AiParam('description')` on DTO fields the LLM should fill (only needed for body/query DTOs; path params from `@Param()` are auto-extracted)
+
+```ts
+// src/tasks/tasks.controller.ts
+import { Body, Controller, Get, Param, Post, Query, UseGuards } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+import { AiModule, AiTool } from 'glirastes/server/nestjs';
+import { TasksService } from './tasks.service';
+import { CreateTaskDto, ListTasksQueryDto } from './dto';
+
+@Controller('tasks')
+@UseGuards(AuthGuard('jwt'))
+@AiModule({
+  intent: 'task_management',
+  classification: {
+    hint: 'User asks about listing, filtering, creating, or updating tasks.',
+    examples: [
+      'show me open tasks',
+      'create a task: review PR',
+      'mark task 42 as done',
+    ],
+  },
+})
+export class TasksController {
+  constructor(private readonly tasksService: TasksService) {}
+
+  @Get()
+  @AiTool({
+    name: 'list_tasks',
+    description: 'List tasks with an optional status filter.',
+  })
+  list(@Query() q: ListTasksQueryDto) {
+    return this.tasksService.list(q);
+  }
+
+  @Get(':id')
+  @AiTool({
+    name: 'get_task',
+    description: 'Fetch a single task by its ID.',
+  })
+  get(@Param('id') id: string) {
+    return this.tasksService.get(id);
+  }
+
+  @Post()
+  @AiTool({
+    name: 'create_task',
+    description: 'Create a new task. Always confirm the title with the user first.',
+  })
+  create(@Body() dto: CreateTaskDto) {
+    return this.tasksService.create(dto);
+  }
+}
+```
+
+```ts
+// src/tasks/dto.ts
+import { IsOptional, IsString, IsEnum } from 'class-validator';
+import { ApiProperty } from '@nestjs/swagger';
+import { AiParam } from 'glirastes/server/nestjs';
+
+export class ListTasksQueryDto {
+  @IsString()
+  @IsOptional()
+  @AiParam('Optional status filter — one of "open" | "done".')
+  @ApiProperty({ required: false })
+  status?: 'open' | 'done';
+}
+
+export class CreateTaskDto {
+  @IsString()
+  @AiParam('The task title (required). Must be confirmed with the user.')
+  @ApiProperty()
+  title!: string;
+
+  @IsString()
+  @IsOptional()
+  @AiParam('Optional assignee user ID — never invent, look up via find_user first.')
+  @ApiProperty({ required: false })
+  assigneeId?: string;
+}
+```
+
+The scanner derives the Zod input schema from your DTOs (`class-validator` decorators + `@AiParam` descriptions) and auto-extracts path params from `@Param()`. You write DTOs once for HTTP, Swagger, validation, and AI.
+
+## Step 5 — Wire AiChatModule
+
+Create a `ChatModule` that:
+1. Imports the modules whose controllers carry `@AiTool` decorators.
+2. Calls `AiChatModule.forRoot({ ... })` with model, system prompt, and your existing auth guard.
+
+```ts
+// src/chat/chat.module.ts
+import { openai } from '@ai-sdk/openai';
+import { Module } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+import { AiChatModule } from 'glirastes/server/nestjs';
+import { TasksModule } from '../tasks/tasks.module';
+
+@Module({
+  imports: [
+    TasksModule,
+    AiChatModule.forRoot({
+      model: openai('gpt-4o-mini'),
+      systemPrompt: ({ currentDate }) =>
+        `You are a helpful assistant. Today is ${currentDate}.`,
+      authGuard: AuthGuard('jwt'),
+    }),
+  ],
+})
+export class ChatModule {}
+```
+
+Register `ChatModule` in `AppModule`:
+
+```ts
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { ChatModule } from './chat/chat.module';
+// ... your other imports
+
+@Module({
+  imports: [
+    // ... existing modules
+    ChatModule,
+  ],
+})
+export class AppModule {}
+```
+
+`AiChatModule` exposes `POST /api/ai/chat` (and `GET /api/ai/tools` to inspect the registered tools). The `authGuard` runs before every chat request, so the same JWT validation that protects your other endpoints applies here too.
+
+## Step 6 — Verify
+
+```bash
+npm run build       # NestJS build
+npm start           # or npm run start:dev for watch mode
+```
+
+Then check the tool registry directly:
+
+```bash
+curl -H "Authorization: Bearer <jwt>" http://localhost:3000/api/ai/tools
+```
+
+You should see a JSON list of all tools the scanner discovered. Send a chat request:
+
+```bash
+curl -X POST http://localhost:3000/api/ai/chat \
+  -H "Authorization: Bearer <jwt>" \
+  -H "Content-Type: application/json" \
+  -d '{"messages":[{"role":"user","content":"list my open tasks"}]}'
+```
+
+The response is a streaming SSE — your frontend's `<VercelAiChat endpoint="...api/ai/chat" />` consumes it directly.
+
+## Step 7 — Frontend connection
+
+Your React frontend (any framework — Next.js, Vite + React, etc.) connects via the `endpoint` prop:
+
+```tsx
+'use client';
+import { VercelAiChat } from 'glirastes/react/vercel';
+
+const API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3000';
+
+export function ChatWidget() {
+  return (
+    <VercelAiChat
+      endpoint={`${API_URL}/api/ai/chat`}
+      headers={() => ({ Authorization: `Bearer ${getToken()}` })}
+    />
+  );
+}
+```
+
+CORS: ensure your NestJS app enables CORS for the frontend origin (typically in `main.ts` via `app.enableCors({ origin: '...', credentials: true })`).
+
+For UI customization, see [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md).
+
+## Step 8 — Optional: Speech-to-text WebSocket
+
+To enable live voice transcription via Deepgram:
+
+1. Set `features.speechToText: true` and provide an env var `DEEPGRAM_API_KEY`:
+
+   ```ts
+   AiChatModule.forRoot({
+     model: openai('gpt-4o-mini'),
+     authGuard: AuthGuard('jwt'),
+     features: { speechToText: true },
+   })
+   ```
+
+2. In your `main.ts`, attach the WebSocket server **after** `app.listen()`:
+
+   ```ts
+   // src/main.ts
+   import { NestFactory } from '@nestjs/core';
+   import { AiChatModule } from 'glirastes/server/nestjs';
+   import { AppModule } from './app.module';
+
+   async function bootstrap() {
+     const app = await NestFactory.create(AppModule);
+     await app.listen(3000);
+     await AiChatModule.attachWebSockets(app); // async since 0.3.1
+   }
+   bootstrap();
+   ```
+
+3. Install `ws`: `npm install ws` (only needed for this feature).
+
+4. Frontend: pass `showMic={true}` and install `wavesurfer.js` for the live waveform UI.
+
+The WebSocket lives at `/api/ai/speech-stream`. The browser sends audio frames; the SDK proxies them to Deepgram with your `DEEPGRAM_API_KEY` server-side and streams transcriptions back.
+
+## Multi-controller scanning (advanced)
+
+By default, `AiChatModule.forRoot` discovers tools at runtime via the `DiscoveryService`. For build-time scanning (e.g. to validate the registry before deploy), use `scanNestJsControllers`:
+
+```ts
+import { scanNestJsControllers } from 'glirastes/server/nestjs';
+import { endpointToolsToRegistry } from 'glirastes/server';
+import { TasksController } from './tasks/tasks.controller';
+import { UsersController } from './users/users.controller';
+
+const scan = scanNestJsControllers({
+  controllers: [TasksController, UsersController],
+});
+
+// scan.tools — flat array of tool definitions
+// scan.modules — module metadata
+// scan.toolsByModule — grouped by module
+const registry = endpointToolsToRegistry(scan.tools);
+```
+
+You typically don't need this — runtime DI is simpler — but it's useful when generating skill files (`glirastes generate-skills`) or MCP servers without booting NestJS.
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Cannot find module 'glirastes/server/nestjs'` | Old SDK version (≤0.3.0 was ESM-only) | Upgrade to ≥0.3.1 — dual-bundle works with default CJS NestJS template |
+| `TS1479: ECMAScript module cannot be imported with require` | Same as above | Upgrade to ≥0.3.1 |
+| Tools missing from `/api/ai/tools` | Module not in `imports: [...]` of `ChatModule` | Add the module that owns the controller — DI must reach it |
+| `attachWebSockets is not async` warning | Old SDK pre-0.3.1 | Upgrade to ≥0.3.1 and add `await` |
+| `ERR_MODULE_NOT_FOUND: Cannot find package 'ws'` at startup | `features.speechToText: true` without `ws` installed | `npm install ws` (only required when speech-to-text is on) |
+| Tool description ignored by the LLM | Description too vague | Rewrite as *"WHEN to call: ... WHAT it returns: ..."* — descriptions are the primary LLM hint |
+| Path param missing in tool input | DTO field with the same name shadows it | Path params are auto-extracted from `@Param()` — don't add them to your DTO |
+| LLM hallucinates IDs | No lookup tool exposed | Add a `find_user` / `list_*` tool the LLM can call to resolve IDs first |
+
+## What this skill does NOT cover
+
+- **Tool authoring deep-dive** (input schemas, UI patterns, output schemas, approvals, `module`/`sharedWith`, classification, codegen) — see [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md)
+- **Chat UI customization** (theming, mentions, voice input UI, approval cards, action bus, ChatWindow portal) — see [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md)
+- **Next.js standalone integration** (Next.js as the only backend) — see [integrating-glirastes-nextjs](../integrating-glirastes-nextjs/SKILL.md)
+- **LangGraph transport** — if your backend speaks LangGraph instead, swap `AiChatModule` for the LangGraph wiring patterns; client-side, swap `VercelAiChat` for `LangGraphAiChat` from `glirastes/react/langgraph`
+- **Glirastes platform features** (PII Shield via `createPiiShield`, intent routing via `createLancer`, guardrails, telemetry) — opt in via `GLIRASTES_API_KEY` env var; the SDK falls back to free-tier behaviour without it

package/skills/integrating-glirastes-nextjs/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: integrating-glirastes-nextjs
+description: Integrating the Glirastes SDK into a Next.js App Router project — chat route handler, VercelAiChat widget, co-located ai-tool.ts files, codegen pipeline. Use when adding AI chat to a Next.js app where Next.js itself is the backend.
+version: 1.0.0
+tags:
+  - glirastes
+  - nextjs
+  - ai
+  - app-router
+triggers:
+  - integrate glirastes
+  - integrate glirastes nextjs
+  - add glirastes to next
+  - add chat to next.js
+  - createAiChatHandler
+  - VercelAiChat
+  - chat route nextjs
+  - ai chat next.js
+---
+
+# Integrating Glirastes into Next.js
+
+> **Scope:** Next.js is the only backend in this project. If a separate NestJS / Express backend exists, use [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md) instead — putting the chat route on the real backend avoids duplicate auth and an extra HTTP hop per tool call.
+>
+> **Companion skills:**
+> - [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md) — tool authoring deep-dive, all CLI commands, codegen workflow
+> - [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md) — chat UI customization, mentions, voice input, action bus
+
+## Stack detection
+
+Confirm before applying:
+
+- `next.config.{ts,js,mjs}` exists at the project root → Next.js ✅
+- No `nest-cli.json` or sibling backend workspace
+- `package.json` shows React 19+, Next.js 15+
+
+If a NestJS backend lives in the same workspace (e.g. `apps/api/`), stop and use the NestJS skill — the chat route belongs there.
+
+## Step 1 — Install
+
+```bash
+# Core + a model provider
+npm install glirastes @ai-sdk/openai
+
+# React UI peers (declared as optional peerDeps in glirastes 0.3.1+)
+npm install @ai-sdk/react react-markdown
+
+# Optional: voice input with live waveform
+npm install wavesurfer.js
+```
+
+`@ai-sdk/openai` is the OpenAI provider. Swap for `@ai-sdk/anthropic`, `@ai-sdk/mistral`, etc. — Glirastes accepts any AI SDK v6 provider.
+
+## Step 2 — Environment variables
+
+Add to `.env.local`:
+
+```
+OPENAI_API_KEY=sk-...
+# Optional — unlocks Glirastes platform features (PII Shield, intent routing, telemetry)
+# GLIRASTES_API_KEY=glir_...
+```
+
+API keys must stay server-side. Next.js Route Handlers run on the server, so this is safe — never reference `OPENAI_API_KEY` from a client component.
+
+## Step 3 — File structure convention
+
+Co-locate `ai-tool.ts` next to the route it wraps. The codegen scanner discovers tools by this convention:
+
+```
+src/app/api/
+├── chat/route.ts                # createAiChatHandler with the registry
+├── tasks/
+│   ├── route.ts                 # The actual API handler
+│   └── ai-tool.ts               # AI-callable wrapper (defineEndpointTool)
+├── tasks/[id]/
+│   ├── route.ts
+│   └── ai-tool.ts
+└── users/search/
+    ├── route.ts
+    └── ai-tool.ts
+
+src/components/
+├── tasks/ai-ui-tool.ts          # UI tool definitions (defineUiTool)
+└── layout/ai-ui-tool.ts
+
+src/generated/ai-tools/
+├── endpoint.generated.ts        # AUTO — produced by `glirastes generate-tools`
+├── ui.generated.ts
+├── modules.generated.ts
+└── action-ids.generated.ts
+```
+
+Ignore the `src/generated/ai-tools/` directory in your editor — it's regenerated by the CLI on every `predev` / `prebuild`.
+
+## Step 4 — Bootstrap your first tool
+
+Use the CLI scaffolder. Pass an existing route file:
+
+```bash
+npx glirastes scaffold --route src/app/api/tasks/route.ts
+# Add --dry-run to preview without writing
+# Add --force to overwrite existing ai-tool.ts
+```
+
+The scaffolder analyzes the route (HTTP methods, path params, body fields, search params) and emits a starter `src/app/api/tasks/ai-tool.ts`:
+
+```ts
+import { z } from 'zod';
+import { defineEndpointTool } from 'glirastes';
+
+export const aiTool = defineEndpointTool({
+  id: 'tasks.list',
+  toolName: 'list_tasks',
+  module: 'task_query',
+  description: 'list tasks. TODO: write a clear description for the AI.',
+  method: 'GET',
+  path: '/api/tasks',
+  inputSchema: z.object({
+    status: z.enum(['open', 'done']).optional(),
+  }),
+  // uiPattern: { type: 'filter-and-navigate', target: 'tasks', filterMapping: { status: 'status' } },
+});
+```
+
+Edit `description` (the LLM reads this to decide when to call the tool), refine the schema, optionally add a `uiPattern`. For the full tool authoring API, see [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md).
+
+## Step 5 — Wire the chat route handler
+
+Two paths depending on tool count:
+
+### Few tools — manual import
+
+```ts
+// src/app/api/chat/route.ts
+import { openai } from '@ai-sdk/openai';
+import { endpointToolsToRegistry } from 'glirastes/server';
+import { createAiChatHandler } from 'glirastes/server/nextjs';
+import { aiTool as listTasks } from '../tasks/ai-tool';
+
+export const POST = createAiChatHandler({
+  tools: endpointToolsToRegistry([listTasks]),
+  model: openai('gpt-4o-mini'),
+  systemPrompt: 'You are a helpful assistant for our app.',
+});
+```
+
+### Many tools — codegen pipeline
+
+Add to `package.json`:
+
+```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"
+  }
+}
+```
+
+Then import the generated registry instead of individual tools:
+
+```ts
+// src/app/api/chat/route.ts
+import { openai } from '@ai-sdk/openai';
+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'),
+  systemPrompt: 'You are a helpful assistant for our app.',
+});
+```
+
+The registries are typed as `ToolRegistry` (Record<string, Tool>) — pass them straight to `createAiChatHandler({ tools })`.
+
+## Step 6 — Mount the chat widget
+
+Client-side component, then drop into the root layout:
+
+```tsx
+// src/components/chat/ChatWidget.tsx
+'use client';
+
+import { VercelAiChat } from 'glirastes/react/vercel';
+
+export function ChatWidget() {
+  return <VercelAiChat endpoint="/api/chat" />;
+}
+```
+
+```tsx
+// src/app/layout.tsx
+import { ChatWidget } from '@/components/chat/ChatWidget';
+import 'glirastes/react/styles.css';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <ChatWidget />
+      </body>
+    </html>
+  );
+}
+```
+
+For UI customization (props on `VercelAiChat`, theming, mentions, voice input, custom approval cards), see [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md).
+
+## Step 7 — Verify
+
+Run the codegen + production build first — surfaces most issues:
+
+```bash
+npm run ai:validate   # catches malformed ai-tool.ts files
+npm run ai:coverage   # lists routes without ai-tool.ts (informational)
+npm run build         # full Next.js build, runs `predev`/`prebuild` scripts
+```
+
+Build output should list `/api/chat` as a dynamic route (`ƒ /api/chat`). Then:
+
+```bash
+npm run dev
+```
+
+Open the app, click the floating chat trigger (bottom-right by default), send a message that should fire your tool (*"show me my open tasks"*). The tool result must show up; `uiPattern` actions fire automatically (e.g. `filter-and-navigate` rewrites the URL).
+
+## Step 8 — Hook up frontend UI actions (optional)
+
+If your tools declare `uiPattern: { type: 'open-dialog' | 'open-detail' | 'refresh' | 'toast' }`, the SDK derives an action ID and fires it through the `UiActionBus`. Register handlers anywhere a relevant component mounts:
+
+```tsx
+'use client';
+import { useAiClientAction } from 'glirastes/react';
+import { useRouter } from 'next/navigation';
+
+export function TaskList() {
+  const router = useRouter();
+  useAiClientAction('task-details.open', (payload) => {
+    router.push(`/tasks/${payload?.taskId}`);
+  });
+  // ...
+}
+```
+
+Action IDs are derived from `uiPattern`:
+
+| `uiPattern.type` | Action ID |
+|---|---|
+| `open-detail`, `entity: 'task'` | `task-details.open` |
+| `open-dialog`, `dialog: 'create-task'` | `task-create-dialog.open` |
+| `refresh`, `target: 'tasks'` | `tasks.refresh` |
+| `toast` | dispatched directly via your toast lib (sonner/react-hot-toast) |
+
+`glirastes coverage` reports any UI action ID declared in tools but not handled in `.tsx` files (and vice versa).
+
+## CLI quick reference
+
+| Command | Purpose | Common flags |
+|---|---|---|
+| `glirastes scaffold --route <file>` | Create `ai-tool.ts` next to a `route.ts` | `--dry-run`, `--force` |
+| `glirastes generate-tools` | Scan all `*.ai-tool.ts` files, emit `src/generated/ai-tools/*.generated.ts` | `--quiet` (predev/prebuild) |
+| `glirastes generate-endpoint-tools` | Endpoint registry only | `--quiet` |
+| `glirastes generate-ui-tools` | UI tool registry + action IDs | `--quiet` |
+| `glirastes generate-modules` | Module/intent registry | `--meta @/lib/ai/module-meta` |
+| `glirastes generate-auto` | Auto-detect repo layout, run the right generator | — |
+| `glirastes validate-tools` | Validate naming, duplicates, missing approvals | `--ci`, `--fix`, `--quiet` |
+| `glirastes coverage` | Report routes without `ai-tool.ts`, orphan handlers | `--ci`, `--quiet` |
+| `glirastes test` | Scaffold an AI behavior test file | — |
+| `glirastes generate-skills` | Export current tool registry as Claude Code / Codex skills (for *agents to call your tools*) | `--app-name`, `--base-url`, `--auth bearer` |
+| `glirastes generate-mcp-server` | Export current tool registry as a standalone MCP server project | `--app-name`, `--base-url` |
+| `glirastes generate <openapi.yaml>` | Generate endpoint tools from an OpenAPI spec | `--out <file>` |
+| `glirastes check-upgrade` | Analyze release notes for breaking changes against your code | `--from-version <ver>` |
+| `glirastes sync` | Upload tool schemas to the Glirastes platform (Pro) | `--api-key` (or `GLIRASTES_API_KEY` env) |
+
+For the full deep-dive, see [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md).
+
+## Common pitfalls
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `Cannot resolve '@ai-sdk/react'` at build | Optional peer not installed | `npm install @ai-sdk/react react-markdown` |
+| `Cannot resolve 'wavesurfer.js/dist/plugins/record.esm.js'` | Voice input components reachable in bundle without peer | Either install `wavesurfer.js` or set `showMic={false}` on `<VercelAiChat />` |
+| Chat widget unstyled | `styles.css` not imported | Add `import 'glirastes/react/styles.css'` to root layout |
+| Tool never fires | `path` mismatches the actual route | Endpoint tool's `path` must match the URL the route handler serves exactly |
+| `OPENAI_API_KEY is not configured` | Env var missing | `.env.local` + restart dev server (Next caches env at startup) |
+| `endpointToolRegistry is undefined` | Codegen script never ran | `npm run predev` or run `glirastes generate-tools` once manually |
+| LLM ignores a tool | Description missing or vague | Rewrite to *"WHEN to call: ... WHAT it returns: ..."* in the description |
+| UI action `task-details.open` fires but nothing happens | No `useAiClientAction` registered | Add handler in a mounted component; verify with `glirastes coverage` |
+| OpenAPI spec generation fails | Spec not validated | Run `glirastes validate <openapi.yaml>` first |
+
+## What this skill does NOT cover
+
+- **NestJS adapter** — see [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md)
+- **Tool authoring deep-dive** (UI patterns, output schemas, approvals, `module`/`sharedWith`, classification metadata) — see [maintaining-glirastes-tools](../maintaining-glirastes-tools/SKILL.md)
+- **Chat UI customization** (theming, mentions, voice input, approval cards, action bus, ChatWindow portal) — see [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md)
+- **LangGraph transport** — replace `createAiChatHandler` + `VercelAiChat` with the LangGraph variants from `glirastes/server/nextjs` and `glirastes/react/langgraph`
+- **Glirastes platform features** (PII Shield via `createPiiShield`, intent routing via `createLancer`, guardrails, usage telemetry) — opt in via `GLIRASTES_API_KEY` env var; the SDK falls back to free-tier behaviour without it