glirastes 0.3.2 → 0.5.0

package/README.md

@@ -1,927 +1,378 @@
 <p align="center">
-  <a href="https://github.com/chainmatics/glirastes">
-    <img alt="Glirastes SDK" src=".github/hero.gif" width="100%">
-  </a>
+  <img src=".github/assets/logo.png" alt="Glirastes logo: an orange mycelium mark" width="120">
 </p>
 
+<h1 align="center">Glirastes</h1>
+
 <p align="center">
-  <strong>The bridge between AI and your UI.</strong><br/>
-  <sub>Define tools once. Execute on the server. React on the client. All type-safe.</sub>
+  <em>The agentic framework that takes root in your product.</em>
 </p>
 
 <p align="center">
-  <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="#scaling-up--required-codegen-workflow-for-nextjs"><strong>Scaling up</strong></a> ·
-  <a href="#cli"><strong>CLI</strong></a> ·
-  <a href="#agent-skills"><strong>Skills</strong></a>
+  <a href="https://www.npmjs.com/package/glirastes"><img src="https://img.shields.io/npm/v/glirastes?style=flat-square&color=f2a618" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-f2a618?style=flat-square" alt="License: Apache-2.0"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020.6-f2a618?style=flat-square" alt="Node >= 20.6">
+  <img src="https://img.shields.io/badge/TypeScript-ready-f2a618?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/glirastes"><img src="https://img.shields.io/npm/v/glirastes?style=flat-square&labelColor=0a0a0a&color=6366f1" alt="npm version"/></a>
-  <a href="#"><img src="https://img.shields.io/badge/TypeScript-strict-3178c6?style=flat-square&logo=typescript&logoColor=white&labelColor=0a0a0a" alt="TypeScript"/></a>
-  <a href="https://sdk.vercel.ai/"><img src="https://img.shields.io/badge/Vercel_AI_SDK-compatible-8b5cf6?style=flat-square&labelColor=0a0a0a" alt="Vercel AI SDK"/></a>
-  <a href="https://langchain-ai.github.io/langgraph/"><img src="https://img.shields.io/badge/LangGraph-compatible-1c3c3c?style=flat-square&labelColor=0a0a0a" alt="LangGraph"/></a>
+  <a href="https://glirastes.io"><b>Website</b></a> ·
+  <a href="#quickstart-nextjs-app-router"><b>Quickstart</b></a> ·
+  <a href="docs/"><b>Docs</b></a> ·
+  <a href="skills/"><b>Skills</b></a> ·
+  <a href="CHANGELOG.md"><b>Changelog</b></a>
 </p>
 
-<br/>
-
----
-
-<br/>
-
-## What is this?
-
-**glirastes** is a TypeScript SDK for building AI-powered chat and tool systems. You describe what the AI can do with a handful of declarative tool definitions, and the SDK turns them into [Vercel AI SDK](https://sdk.vercel.ai/)-compatible tools that call your APIs, stream responses to the client, and trigger UI updates — all type-safe, all in one place. If your backend already runs [LangGraph](https://langchain-ai.github.io/langgraph/) instead, the same chat UI works against it via the LangGraph transport — no migration required.
-
-It ships as a single npm package with subpath exports:
-
-```ts
-import { defineEndpointTool } from 'glirastes';
-import { createAiChatHandler } from 'glirastes/server/nextjs';
-import { VercelAiChat } from 'glirastes/react/vercel';
-```
-
-The server bits run in Node (Next.js App Router, NestJS, or any framework). The client bits are React. Everything else — PII protection, intent routing, guardrails, approvals — is optional and unlocked via the [Glirastes platform](https://chainmatics.de).
-
-<br/>
-
-## Why glirastes?
-
-Building an AI feature means wiring together **tool definitions**, **API calls**, **streaming responses**, **UI reactions**, and — once real users hit it — **PII handling**, **approval flows**, **guardrails**, and **observability**. Every. Single. Time.
-
-<table>
-<tr>
-<td width="50%">
-
-**Without glirastes**
-```
-- Manual tool/function definitions
-- Hand-wired UI action dispatch
-- Custom PII redaction
-- Framework-specific glue
-- Bespoke approval flows
-- DIY observability
-```
-
-</td>
-<td width="50%">
-
-**With glirastes**
-```
-✦ One declarative definition per tool
-✦ Auto UI action dispatch
-✦ Optional PII Shield
-✦ Next.js / NestJS / LangGraph adapters
-✦ Pro approval flows via platform
-✦ Built-in telemetry
-```
-
-</td>
-</tr>
-</table>
-
-<br/>
-
-## 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**:
+<p align="center">
+  <a href="https://glirastes.io"><img src=".github/assets/hero-landing.gif" width="100%" alt="The glirastes.io hero: an orange mycelium network pulses behind the headline &quot;The agentic framework that takes root in your product.&quot; and the npm install glirastes command."></a>
+</p>
 
-| 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) |
+Glirastes is a TypeScript SDK for an embedded chat that operates your app: it
+calls your endpoints, navigates, sets filters and triggers UI actions. The tools
+come from your code, everything runs inside your app, and the optional Glirastes
+Platform manages reviewed configuration and rollouts without ever seeing prompts
+or business data.
 
-**Why prefer the real backend over a Next.js Route Handler?**
+## See it in action
 
-- **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.
+<p align="center">
+  <img src=".github/assets/chat-demo.gif" width="100%" alt="A task board app with the Glirastes chat docked on the right. The user asks to move the Q4 report to Finance and assign it to Lena; the assistant looks up the task and the person, asks for approval of tasks.update, and after Approve the card moves to the Finance column with Lena as assignee.">
+</p>
 
-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.
+<p align="center"><sub>One request moves a card on a task board: the chat finds the task and the person, asks for approval of <code>tasks.update</code>, then acts.</sub></p>
 
-Pick your stack — both come up in the same four steps.
+## Quickstart (Next.js App Router)
 
-### 1. Install
+**1. Install** the SDK and the chat peers (Node >= 20.6):
 
 ```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
+npm install glirastes @ai-sdk/openai @ai-sdk/react react-markdown
 ```
 
-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.
+**2. Initialize.** Run it inside your Codex or Claude Code session, or from a
+terminal with `--agent codex|claude`:
 
-> **Requirements:** Node.js `>=20`. The React chat UI needs `react` and `react-dom` `^19` — Next.js apps already have these.
->
-> **Optional** — only if you want voice input with a live waveform:
-> ```bash
-> npm install wavesurfer.js
-> ```
-
-### 2. Define a tool
-
-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
-import { z } from 'zod';
-import { defineEndpointTool } from 'glirastes';
-
-export const listTasks = defineEndpointTool({
-  id: 'tasks.list',
-  toolName: 'list_tasks',
-  description: 'List tasks with an optional status filter.',
-  method: 'GET',
-  path: '/api/tasks',
-  inputSchema: z.object({
-    status: z.enum(['open', 'done']).optional(),
-  }),
-});
-```
-
-</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);
-  }
-}
+```bash
+npx --no-install glirastes init
 ```
 
-</td>
-</tr>
-</table>
+`init` writes `.glirastes/tools.json`, `.glirastes/prompt-bundle.json`, the
+`predev` / `prebuild` scripts (`glirastes tools refresh`) and a short hint in
+`AGENTS.md` / `CLAUDE.md`, installs the [agent skills](#agent-skills) and hands
+the integration to your coding agent. Existing files are never replaced.
+`--dry-run --json` previews without writing anything.
 
-### 3. Drop a chat widget into your frontend
-
-```tsx
-'use client';
-import { VercelAiChat } from 'glirastes/react/vercel';
+**3. Derive the tools** from your routes, pages, URL filters and client actions:
 
-export default function RootLayout({ children }) {
-  return (
-    <body>
-      {children}
-      <VercelAiChat endpoint="/api/chat" />
-    </body>
-  );
-}
+```bash
+npx glirastes tools refresh
 ```
 
-### 4. Wire up the chat handler
+This writes the committed `.glirastes/` tool files and the generated module
+`src/generated/glirastes/tools.generated.ts`.
 
-<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">
+**4. Add the chat route.** Identity comes from your verified session; your
+endpoints keep their own authorization.
 
 ```ts
+// src/app/api/chat/route.ts
+import { createOpenAI } from '@ai-sdk/openai';
+import { createGlirastes } from 'glirastes/runtime';
 import { createAiChatHandler } from 'glirastes/server/nextjs';
-import { endpointToolsToRegistry } from 'glirastes/server';
-import { listTasks } from './tasks/ai-tool';
-
-export const POST = createAiChatHandler({
-  tools: endpointToolsToRegistry([listTasks]),
-});
-```
-
-</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.
-
-> **One more step for Next.js once you have more than a handful of tools.** The manual `endpointToolsToRegistry([listTasks, …])` import list above stops scaling around 5–10 tools. Today's required pattern: write each tool in a co-located `*.ai-tool.ts` file and run the CLI codegen as a `predev` / `prebuild` hook to aggregate them into a generated registry your chat route imports. See [Scaling up — required codegen workflow for Next.js](#scaling-up--required-codegen-workflow-for-nextjs) below for the full setup. **NestJS users skip this entirely** — the runtime decorator scan handles aggregation automatically.
->
-> *Coming in 0.4.0:* a `buildToolRegistry` helper backed by `import.meta.glob` / `require.context` that drops the codegen step for Next.js too. Track at [chainmatics/glirastes#issues](https://github.com/chainmatics/glirastes/issues).
-
-### 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/>
-
-## Core Concepts
-
-### Tool
-
-A **tool** is something the AI can do. It has a name, a description (so the LLM knows when to use it), an input schema (Zod — validated at the type layer and at runtime), and logic for what happens when it runs.
-
-Two flavors cover ~95% of real-world cases:
-
-### Endpoint Tool — talks to your backend
-
-```ts
-import { z } from 'zod';
-import { defineEndpointTool } from 'glirastes';
-
-export const listInvoices = defineEndpointTool({
-  id: 'invoices.list',
-  toolName: 'list_invoices',
-  module: 'billing',
-  description: 'List invoices with optional status filter.',
-  method: 'GET',
-  path: '/api/invoices',
-  inputSchema: z.object({
-    status: z.enum(['paid', 'open', 'overdue']).optional(),
-  }),
-  uiPattern: {
-    type: 'filter-and-navigate',
-    target: 'invoices',
-    filterMapping: { status: 'status' },
+import * as generated from '@/generated/glirastes/tools.generated';
+import { resolvePrincipal } from '@/lib/glirastes-principal'; // your session lookup
+
+const glirastes = createGlirastes({
+  generated,
+  localLimits: {
+    maxModelSteps: 6, maxToolCalls: 8, totalTimeoutMs: 60_000, toolTimeoutMs: 15_000,
+    maxInputTokens: 40_000, maxOutputTokens: 4_000, maxEstimatedCostUsd: 0.5,
+    maxRepeatedFingerprint: 3, maxConsecutiveErrors: 3,
+    delegation: { maxDepth: 1, maxBreadth: 1, sharedBudget: true },
   },
 });
-```
-
-You declare the HTTP method and path; the SDK generates the `execute` function that calls your API. You never write fetch boilerplate for a tool.
-
-### UI Tool — fires frontend actions
-
-```ts
-import { z } from 'zod';
-import { defineUiTool } from 'glirastes';
-
-export const openSettings = defineUiTool({
-  id: 'settings.open',
-  toolName: 'open_settings',
-  description: 'Open the settings dialog for the current user.',
-  inputSchema: z.object({}),
-  uiAction: { type: 'open-dialog', target: 'settings' },
-});
-```
-
-No API call. The tool result contains a `uiAction` payload that's dispatched to registered React handlers via the `UiActionBus`. This is how "LLM opens a dialog" or "LLM navigates the user" works without round-tripping through your backend.
-
-### Registry
-
-A **registry** is a key-value map (tool name → tool object) that the SDK uses internally. Build one with `endpointToolsToRegistry(...)` or `uiToolsToRegistry(...)`:
-
-```ts
-import { endpointToolsToRegistry, uiToolsToRegistry } from 'glirastes/server';
-
-const endpoints = endpointToolsToRegistry([listInvoices, createInvoice]);
-const ui = uiToolsToRegistry([openSettings]);
-const registry = { ...endpoints, ...ui };
-```
-
-Pass the merged registry to `createAiChatHandler({ tools: registry })` and the SDK converts it to AI SDK format at request time.
-
-### UI Patterns
-
-Declarative rules for what the frontend should do after a tool runs. Instead of writing custom dispatch code per tool, declare a pattern and the SDK resolves it automatically:
-
-| Pattern | What it does |
-|---|---|
-| `filter-and-navigate` | Navigate to a page with filters pre-applied |
-| `open-detail` | Open a detail view for a specific entity |
-| `open-dialog` | Open a modal dialog |
-| `refresh` | Refresh a specific UI region |
-| `toast` | Show a notification |
-
-Patterns support `$variable` placeholders that get replaced with values from the tool input or response. Example: `path: '/tasks/$taskId'` becomes `/tasks/abc-123` at runtime.
-
-### UI Action Dispatch
-
-On the frontend, register handlers for action IDs using the `useAiClientAction` hook:
-
-```tsx
-import { useAiClientAction } from 'glirastes/react';
-
-function TaskList() {
-  useAiClientAction('task-details.open', (payload) => {
-    router.push(`/tasks/${payload?.taskId}`);
-  });
-
-  useAiClientAction('task-list.filter', (payload) => {
-    setFilters(payload);
-  });
-
-  return <div>{/* your task list */}</div>;
+const openrouter = createOpenAI({ baseURL: 'https://openrouter.ai/api/v1', apiKey: process.env.OPENROUTER_API_KEY });
+
+export const runtime = 'nodejs';
+export async function POST(request: Request) {
+  const principal = await resolvePrincipal(request); // { subjectId, tenantId, roles, attributes }
+  if (!principal) return new Response('Unauthorized', { status: 401 });
+  const turn = await glirastes.chatTurn((runtimeTenantId) => ({ ...principal, tenantId: runtimeTenantId }));
+  return createAiChatHandler({
+    ...turn,
+    model: openrouter.chat('anthropic/claude-sonnet-5.5'),
+    systemPrompt: 'Use the tools of this app. Ask one short question when the target is unclear.',
+    toolDiscovery: true,
+  })(request);
 }
 ```
 
-When a tool returns a `uiAction` with a matching action ID, your handler fires. That's the full bridge between the LLM and your UI.
-
-### Modules (Intent Routing)
-
-Modules group tools by topic — e.g., a `billing` module contains `list_invoices`, `create_invoice`, `send_reminder`. When a user sends a message, the SDK can classify which module the message belongs to and scope the LLM's tool list to that module alone. Fewer tools = cheaper, faster, more accurate responses.
-
-Module assignment is declared per-tool via the `module` field. Intent classification is a Pro feature that runs through the [Glirastes platform](https://chainmatics.de) via `Lancer` (see [Advanced](#advanced)).
-
-<br/>
-
-## Examples
-
-### Full Next.js backend with the pipeline
-
-The pipeline orchestrates guardrails → intent classification → tool scoping → model selection in one call. It's the recommended setup once you have more than a handful of tools.
-
-```ts
-// app/api/chat/route.ts
-import { createAiChatHandler } from 'glirastes/server/nextjs';
-import { createAiPipeline, endpointToolsToRegistry } from 'glirastes/server';
-import { createLancer } from 'glirastes/server/lancer';
-import { endpointTools } from '@/lib/ai-tools';
-import { modules } from '@/lib/modules';
-
-const lancer = createLancer({
-  apiKey: process.env.GLIRASTES_API_KEY,
-});
-
-const pipeline = createAiPipeline({
-  lancer,
-  modules,
-  defaultModule: 'general',
-});
-
-const registry = endpointToolsToRegistry(endpointTools);
-
-export const POST = createAiChatHandler({
-  tools: registry,
-  pipeline,
-});
-```
-
-Without an API key, the pipeline **still works** — every Lancer call falls back to a safe local default. Guardrails pass, classification returns low confidence, telemetry is silently dropped. You can develop and ship without ever talking to the platform.
-
-### NestJS with decorators
-
-Prefer declaring tools where the endpoint lives? Use NestJS decorators. Three pieces: `@AiModule` on the controller, `@AiTool` on the method, `@AiParam` on the DTO properties.
-
-```ts
-// tasks.controller.ts
-import { Controller, Post, Body, Get, Param } from '@nestjs/common';
-import { AiModule, AiTool } from 'glirastes/server/nestjs';
-
-@Controller('tasks')
-@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({
-    name: 'create_task',
-    description: 'Create a new task',
-  })
-  async create(@Body() dto: CreateTaskDto) {
-    return this.taskService.create(dto);
-  }
-
-  // Endpoints without @AiTool are not exposed to the AI
-  @Get(':id/history')
-  getHistory(@Param('id') id: string) {
-    return this.taskService.getHistory(id);
-  }
-}
-```
-
-```ts
-// create-task.dto.ts
-import { IsString, IsOptional } from 'class-validator';
-import { AiParam } from 'glirastes/server/nestjs';
-
-export class CreateTaskDto {
-  @IsString()
-  @AiParam('The task title. Required. Ask the user if missing.')
-  title!: string;
-
-  @IsString()
-  @IsOptional()
-  @AiParam('Optional due date in ISO 8601 format.')
-  dueDate?: string;
-}
-```
-
-`@AiParam` descriptions are what the LLM sees when deciding whether and how to call the tool — write them as instructions for the model, not for humans. The input schema is auto-derived from the DTO's `class-validator` decorators.
-
-Wire it up in your `AiChatModule`:
-
-```ts
-import { scanNestJsControllers } from 'glirastes/server/nestjs';
-import { endpointToolsToRegistry } from 'glirastes/server';
-
-const scan = scanNestJsControllers({
-  controllers: [TaskController, /* ...other controllers */],
-});
-const registry = endpointToolsToRegistry(scan.tools);
-```
-
-`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
+The handler protects the route for you. Set `GLIRASTES_APPROVAL_SECRET` (at
+least 16 characters, the same on every instance) before production: it signs
+each approval the handler asks for to that tool call, its input, an expiry
+(15 minutes by default) and the user (the managed principal, as here, or your
+`approvalScope(request)`), so an approval in a forged or edited chat history
+runs nothing; production refuses to serve approvals without it. An approved
+call runs only when every check passed in that request; any other approved
+call without a result in the history is denied. With the default in-process store, each
+approval runs at most once per process within its lifetime, and each caller
+holds at most 200 live approvals. Without a managed runtime or
+`approvalScope`, the caller is told apart by a keyed hash of the request's
+`Authorization` or `Cookie` header (only requests without credentials share
+one quota); `approvalScope` also binds each approval to its user. With several instances, pass a
+shared `approvalStore` (e.g. Redis), or a replayed history can run once more
+on another instance. The handler also answers 415 to a body that is not
+`application/json`, 403 to a browser request from another origin (list yours
+in `allowedOrigins`), 413 above `maxBodyBytes` (1 MB), and 400 to a body that
+is not JSON (`invalid_json`), to a history that repeats a tool call id or an
+approval id (`duplicate_tool_call_id`, `duplicate_approval_id`), to a
+malformed tool part or approval (`tool_part_malformed`, `approval_malformed`)
+and to more than 32 approved calls in one request (`too_many_approvals`).
+
+Endpoint tools call the origin of the chat request's URL, the address your
+Next.js server listens on, so they reach the app's own route handlers. If your
+API runs in another process, even under the same public origin behind a
+proxy, pass `endpointCaller: (request) => createHttpEndpointCaller({ baseUrl,
+request })` with its origin; `trustForwardedHeaders: true` is the alternative
+only when every request comes through a proxy that sets `x-forwarded-host`
+(otherwise a client can aim the calls, with the user's cookie, at any host).
+
+`executeTool` and routes built from `glirastes/runtime/ai-sdk` alone run a tool
+without these approval checks; give them only input your server has authorized.
+
+**5. Mount the chat** and the navigation bridge (client components):
 
 ```tsx
-// components/chat-integration.tsx
 'use client';
-import { useAiClientAction } from 'glirastes/react';
 import { useRouter } from 'next/navigation';
-import { useQueryClient } from '@tanstack/react-query';
+import { useGlirastesNavigationBridge } from 'glirastes/react';
+import { VercelAiChat } from 'glirastes/react/vercel';
+import 'glirastes/react/styles.css';
 
-export function ChatIntegration() {
+export function Assistant() {
   const router = useRouter();
-  const qc = useQueryClient();
-
-  useAiClientAction('task-details.open', (payload) => {
-    router.push(`/tasks/${payload?.taskId}`);
-  });
-
-  useAiClientAction('task-list.refresh', () => {
-    qc.invalidateQueries({ queryKey: ['tasks'] });
-  });
-
-  useAiClientAction('open-dialog.settings', () => {
-    // open your settings modal
-  });
-
-  return null;
-}
-```
-
-Render this component anywhere inside your layout. Handlers fire whenever a tool result contains a matching `uiAction`.
-
-### OpenAPI code generation
-
-Already have an OpenAPI spec? Annotate your endpoints with `x-ai` extensions:
-
-```json
-{
-  "paths": {
-    "/api/tasks": {
-      "post": {
-        "operationId": "createTask",
-        "x-ai": {
-          "enabled": true,
-          "toolName": "create_task",
-          "description": "Create a new task",
-          "module": "task_management"
-        }
-      }
-    }
-  }
-}
-```
-
-Then generate tool definitions automatically:
-
-```bash
-npx glirastes generate --input openapi.json --output src/generated/tools.ts
-```
-
-The generator converts OpenAPI parameter schemas to Zod, preserves `x-ai` metadata, and outputs a ready-to-import registry file.
-
-### Testing without LLM calls
-
-```ts
-import { createAiTestSuite } from 'glirastes/server/testing';
-import { endpointTools } from '@/lib/ai-tools';
-import { modules } from '@/lib/modules';
-
-const suite = createAiTestSuite({
-  tools: endpointTools,
-  modules,
-});
-
-suite.expectRouted('show me open tasks', 'task_query');
-suite.expectNeedsApproval('delete_task');
-suite.expectNoApproval('list_tasks');
-suite.expectToolSchema('create_task').toAccept({ title: 'Buy milk' });
-```
-
-All assertions run without calling a real LLM or hitting HTTP — perfect for CI.
-
-<br/>
-
-## Advanced
-
-### LangGraph backend
-
-If your server already runs [LangGraph](https://langchain-ai.github.io/langgraph/), swap the drop-in widget for the LangGraph transport. Your LangGraph agent handles the model calls and tool execution; glirastes handles the chat UI and streaming transport:
-
-```tsx
-'use client';
-import { LangGraphAiChat } from 'glirastes/react/langgraph';
-
-export default function RootLayout({ children }) {
-  return (
-    <body>
-      {children}
-      <LangGraphAiChat endpoint="/api/chat" />
-    </body>
-  );
+  useGlirastesNavigationBridge({ push: (href) => router.push(href) });
+  return <VercelAiChat endpoint="/api/chat" />;
 }
 ```
 
-No `ai` / `@ai-sdk/react` imports needed — the LangGraph transport is pure HTTP and streams on its own.
-
-### Customizing the chat UI
-
-`VercelAiChat` and `LangGraphAiChat` are thin wrappers around `FloatingChatUI` and accept all its layout props directly:
-
-```tsx
-<VercelAiChat
-  endpoint="/api/chat"
-  title="Ask the assistant"
-  defaultOpen={false}
-  draggable={true}
-  resizable={true}
-  size={{ width: 480, height: 640 }}
-  shortcut="mod+k"
-/>
-```
-
-| Prop | What it does |
-|---|---|
-| `title` | Header text. Default: `"AI Assistant"` |
-| `defaultOpen` | Whether the window starts open. Default: `false` |
-| `draggable` | Window draggable by its header. Default: `true` |
-| `resizable` | Window resizable from corners. Default: `true` |
-| `size` | `{ width, height }` or a responsive size config |
-| `shortcut` | Keyboard shortcut to toggle, e.g. `'mod+k'`. Pass `false` to disable |
-| `hideTriggerWhenOpen` | Hide the floating trigger pill while the window is open |
-| `showClearButton` | Show the clear/trash button in the header. Default: `true` |
-| `showSessionSwitcher` | `true`, `false`, or `'auto'` (shows if sessions are configured) |
-| `headerActions` | Replace the default header actions with a custom `ReactNode` |
-| `triggerIcon` | Custom icon inside the floating trigger pill |
-
-### Styling
-
-Every visual slot accepts a class name through the `classNames` prop. Works with Tailwind, CSS Modules, or any class-based styling:
-
-```tsx
-<VercelAiChat
-  endpoint="/api/chat"
-  classNames={{
-    window: 'w-[500px] h-[640px] bg-slate-900 border-slate-700 shadow-2xl',
-    windowHeader: 'bg-slate-800 text-slate-100',
-    messageBubble: 'rounded-xl',
-    input: 'bg-slate-800 text-slate-100',
-    trigger: 'bottom-8 right-8',
-    triggerPill: 'bg-indigo-600 hover:bg-indigo-500',
-  }}
-/>
-```
-
-Available slots: `window`, `windowHeader`, `windowBody`, `panel`, `messageList`, `messageBubble`, `input`, `approvalCard`, `bulkApprovalCard`, `suggestionChip`, `mentionChip`, `pipelineTimeline`, `trigger`, `triggerPill`, `switcher`. Setting `classNames.window` drops the SDK's inline sizing styles so your classes win.
+**6. Run** `npm run dev` (the `predev` script refreshes the tools), then check
+the setup with `npx glirastes doctor`.
 
-You can also bring your own stylesheet via `import 'glirastes/react/styles.css'` for the default look, or skip it entirely and style everything from scratch.
+The full walkthrough, including filters, client actions, `@` mentions and `/`
+commands, is the bundled skill
+[`integrating-glirastes-nextjs`](skills/integrating-glirastes-nextjs/SKILL.md).
 
-### Persisting chat across sessions
+## How it works
 
-Every widget accepts a `session` config. The simplest version uses `localStorage`:
+- **Execution is local.** The model call, the tool loop and every tool call
+  run in your app's server. A normal chat turn makes no request to the
+  Platform.
+- **Your app keeps the sensitive parts.** Prompts, model calls and provider
+  keys, secrets, business data, tool arguments and results, and final
+  authorization stay in the app. `resolvePrincipal` only says who asks; each
+  endpoint still checks its own session and permissions.
+- **Guard rails per turn.** Each turn runs on one pinned tool and policy
+  snapshot, with local budgets (steps, tool calls, tokens, cost, timeouts),
+  loop detection and fail-closed authorization. Write and delete tools ask
+  the user before they run.
+- **The Platform gets metadata only.** A connected app sends content-free
+  metrics (tokens, cost, latency, errors, tool use) in batches off the turn
+  path, and receives signed configuration revisions.
 
-```tsx
-<VercelAiChat
-  endpoint="/api/chat"
-  session={{
-    save: (id, msgs) => localStorage.setItem(id, JSON.stringify(msgs)),
-    load: (id) => {
-      const v = localStorage.getItem(id);
-      return v ? JSON.parse(v) : null;
-    },
-  }}
-/>
-```
-
-For multi-device sync, point `save` and `load` at your own REST endpoints that persist messages to a database. The SDK also supports a full session-list bridge (`list`, `create`, `delete`, `rename`) for apps that show a sidebar of past conversations — see `SessionConfig` in the source for the full shape.
+## Tools from your code
 
-### Manual wiring (sharing chat state with other components)
-
-If you need to trigger chat programmatically from a button, show unread counts in the header, or render transcripts somewhere outside the chat panel, skip the drop-in widget and wire things manually:
-
-```tsx
-'use client';
-import { AiChatProvider, AiChatPanel, useAiChat } from 'glirastes/react';
-import { useVercelAiChatTransport } from 'glirastes/react/vercel';
-
-export function ChatShell({ children }: { children: React.ReactNode }) {
-  const transport = useVercelAiChatTransport({ endpoint: '/api/chat' });
-  return (
-    <AiChatProvider transport={transport}>
-      {children}
-      <AiChatPanel />
-    </AiChatProvider>
-  );
-}
-
-// Anywhere inside the provider:
-function HeaderBadge() {
-  const { messages, isLoading } = useAiChat();
-  return <span>{isLoading ? '•••' : messages.length}</span>;
-}
-```
-
-### PII Shield — protect personal data from the LLM
-
-```ts
-import { createPiiShield, createAiChatHandler } from 'glirastes/server';
-import { createLancer } from 'glirastes/server/lancer';
-
-const lancer = createLancer({ apiKey: process.env.GLIRASTES_API_KEY });
-
-const piiShield = createPiiShield({
-  lancer,             // delegate detection to Aegis (Pro)
-  mode: 'pseudonymize', // same PII → same pseudonym across a conversation
-});
-
-export const POST = createAiChatHandler({
-  tools: registry,
-  piiShield,
-});
-```
-
-User sends "Email the invoice to john@example.com" → shield replaces `john@example.com` with `Email_A` before the LLM sees it → LLM calls `send_email({ to: 'Email_A' })` → shield rehydrates the real address before your API is called.
-
-The free tier provides a **local detector** if you skip Lancer. Not as accurate as Aegis but zero-dependency and offline-safe.
-
-### Approvals — human-in-the-loop for sensitive tools
-
-Some tools shouldn't run just because the LLM decided to. `delete_user` should require human confirmation. Set it up via Lancer approvals (Pro):
-
-```ts
-const lancer = createLancer({
-  apiKey: process.env.GLIRASTES_API_KEY,
-  approvals: {
-    policies: {
-      'users.delete': 'require',
-      'billing.charge': 'require',
-      'users.list': 'auto',
-    },
-  },
-});
-```
-
-The chat UI renders an `<ApprovalCard>` in the conversation — "The AI wants to delete user X. Approve or Reject?" — and pauses execution until the user clicks. If Lancer is unavailable, the SDK falls back to the local `needsApproval` flag (deprecated but still functional).
-
-### Followup Suggestions
-
-After the LLM responds, it can suggest follow-up questions as clickable chips. This is powered by an internal `suggest_followups` tool that the LLM calls at the end of a turn. Configurable count (default 3, max 5), locale, and good/bad examples.
-
-Enable via:
-
-```ts
-createAiChatHandler({
-  tools: registry,
-  followups: { enabled: true, count: 3, locale: 'en-US' },
-});
-```
-
-### Voice input
-
-```tsx
-import { VoiceInputButton } from 'glirastes/react';
-
-<VoiceInputButton
-  onTranscript={(text) => console.log(text)}
-  language="en"
-  baseUrl="/api/ai/speech-transcribe"
-  getToken={() => authToken}
-/>
-```
-
-The voice button streams audio to your backend, which proxies it to a speech-to-text provider (Deepgram, etc.). The API key never leaves the server.
-
-> Install `wavesurfer.js` (`npm install wavesurfer.js`) to get the live waveform visualization during recording. Without it the button still works — it just falls back to a static recording indicator.
-
-<br/>
-
-## Scaling up — required codegen workflow for Next.js
-
-Hand-importing every tool definition into your chat route doesn't scale past a handful. **In Glirastes 0.3.x the canonical pattern for Next.js consumers is to run the CLI codegen as a build hook** — it generates a registry from co-located `*.ai-tool.ts` files. The chat route imports the generated registry instead of maintaining a manual import list.
-
-> NestJS users **skip this section entirely.** `AiChatModule.forRoot()` discovers `@AiTool`-decorated controllers at runtime via the NestJS `DiscoveryService` — no codegen step is ever needed.
->
-> **Coming in 0.4.0:** a `buildToolRegistry` helper based on `import.meta.glob` / `require.context` will let Next.js consumers skip the codegen step too. Until then the steps below are required for any non-trivial Next.js app.
-
-### 1. Bootstrap a tool from an existing route
+`glirastes tools refresh` derives endpoint, navigation, filter and
+client-action tools from Next.js, NestJS, OpenAPI (FastAPI), react-router and
+vue-router sources, and from `useAiClientAction` registrations. The output is
+committed with the code; `glirastes tools check` fails CI when it is stale.
 
 ```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"
-  }
-}
-```
+glirastes tools refresh           # derive tools (--watch next to `next dev`)
+glirastes tools status            # what the chat can do
+glirastes tools check             # verify committed outputs, no model, no network
+glirastes tools eval              # every example sentence finds its tool
+```
+
+**Policy.** Reads run directly, writes ask first, deletes and anything
+external or financial always ask. Change that locally with
+`glirastes tools policy` (`show`, `disable`, `confirm`, `relax`, `raise`,
+`roles`, `exclude`, ...); it writes `.glirastes/tool-policy.json`. See
+[docs/tool-policy.md](docs/tool-policy.md).
+
+**Describing tools.** Glirastes itself never calls a model. Descriptions,
+synonyms and example calls are written by a coding agent from work lists:
+
+- **Free:** your own coding agent works through `glirastes tools resolve --print`
+  and `glirastes tools describe --print` with the shipped skills
+  `maintaining-glirastes-tools` and `describing-glirastes-tools`, and you
+  commit the result.
+- **Pro:** the managed CI tool agent (`glirastes tools enrich --managed`)
+  runs the same skills in your CI, only on the tools a pull request or push
+  changed, and commits the result as `glirastes-bot`. Model requests go
+  through OpenRouter with the routing the Platform grants for the job (no
+  data collection, zero data retention), or your own key in
+  `GLIRASTES_TOOLS_OPENROUTER_KEY`. Requires the optional peer
+  `@ai-sdk/openai`.
+
+## CI
 
-`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
+npx glirastes init --ci github [--enrich-on staging,main] [--ci-environment staging]
+```
+
+writes `.github/workflows/glirastes-tools.yml` for your package manager with
+two jobs:
+
+| Job | What it does | Needs |
+|---|---|---|
+| `glirastes-tools` | `tools check` and `tools eval` on every pull request and push to `main` | nothing: no secrets, no model |
+| `glirastes-tools-enrich` (Pro) | runs the managed tool agent on pull requests and commits into the PR branch | variable `GLIRASTES_MANAGED_TOOLS=true`, variable `GLIRASTES_CONTROL_PLANE_URL`, secret `GLIRASTES_CI_KEY` |
+
+- `--enrich-on <branch,...>` (or `--enrich-on-main`) also runs the agent
+  after pushes to those branches; there it opens a pull request instead of
+  committing, and the workflow gets a manual start that works the whole
+  backlog once.
+- `--ci-environment <name>` reads the three values from that GitHub
+  environment instead of the repository.
+- Set the variable `GLIRASTES_BOT_APP_ID` and the secret
+  `GLIRASTES_BOT_APP_PRIVATE_KEY` to push as a GitHub App, so the bot's
+  commits and pull requests trigger your checks. Without them the job uses
+  the workflow token.
+- An existing workflow with other content is refused unless you pass `--force`.
+
+## Chat UI & speech
+
+`glirastes/react` ships one chat implementation; `VercelAiChat` from
+`glirastes/react/vercel` connects it to the AI SDK route.
+
+- Docked sidebar or floating window (`AssistantWorkspace`, `AssistantToggle`),
+  themes, slots, tool result renderers and approval cards.
+- `useAiClientAction(id, handler, contract)` lets the chat drive UI state;
+  `refresh` turns each registration into a tool.
+- Generic `@` mentions and `/` commands derived from your tools
+  ([docs/chat-interactions.md](docs/chat-interactions.md)).
+- A per-message work log of tool calls and an optional plan checklist.
+- `unstyled` to bring your own CSS; `deChatLocale` for German texts.
+- Push-to-talk speech input through one STT controller (`voice` config,
+  `glirastes/stt` adapters, `createRecordingTranscriptionHandler` for a
+  server-side transcription route). Audio goes from the app to its own
+  provider, never through Glirastes.
+- Without React: the `<glirastes-chat>` element from `glirastes/embed` and the
+  bridge in `glirastes/browser`.
+
+See the skill [`building-glirastes-chat-ui`](skills/building-glirastes-chat-ui/SKILL.md).
+
+## Standalone and Connected
+
+| | Standalone | Connected |
+|---|---|---|
+| Trigger | no `GLIRASTES_API_KEY` | `GLIRASTES_API_KEY` is set |
+| Network | none | Platform lookup, registration, sync and metrics, all off the turn path |
+| Config | local code and `.glirastes/` | reviewed, signed, immutable revisions with rollouts and revocations |
+
+`createGlirastes` from `glirastes/runtime` handles both. Connected, it falls
+back to the local code whenever the Platform is unreachable and reports errors
+to `onError` (operation and status only). `GLIRASTES_CONTROL_PLANE_URL` is
+optional and defaults to `https://api.glirastes.chainmatics.io`; set it only
+for a self-hosted or local Platform.
 
 ```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
+npx glirastes connect --base-url <platform-url>   # pair the app, writes GLIRASTES_API_KEY
+npx glirastes sync                                # upload the current local setup
+npx glirastes doctor                              # local checks, no network
 ```
 
-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 **Glirastes Platform** is the optional control plane: reviewed tool
+configuration, signed immutable revisions, staged rollouts, approvals and
+content-free health. **Free** covers the local SDK, the local skill workflow
+and a connected app; **Pro** adds the managed CI tool agent. Details:
+[docs/managed-runtime-sync.md](docs/managed-runtime-sync.md),
+[docs/runtime-persistence.md](docs/runtime-persistence.md).
 
-The SDK includes a `glirastes` CLI for scaffolding, code generation, and validation. Run any command with `npx glirastes <command>` or `bunx glirastes <command>`:
+## Package surface
 
-| Command | What it does |
+| Import | Purpose |
 |---|---|
-| `generate` | Generate endpoint tools from an OpenAPI spec |
-| `generate-tools` | Scan `*.ai-tool.ts` files, emit registry |
-| `generate-endpoint-tools` | Endpoint tool registry only |
-| `generate-ui-tools` | UI tool registry + action IDs |
-| `generate-modules` | Module (intent) registry |
-| `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 |
-| `scaffold` | Generate an `ai-tool.ts` template from an existing route |
-| `test` | Scaffold an AI behavior test file |
-| `check-upgrade` | Analyze release notes for breaking changes |
-| `sync` | Upload tool schemas to the Glirastes platform |
-
-<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 |
+| `glirastes` | Shared types, tool definition helpers and diagnostics |
+| `glirastes/runtime` | `createGlirastes`, local authorization, pinned turns, budgets, durable stores |
+| `glirastes/server` | Server pipeline, including `createLocalAiPipeline` |
+| `glirastes/server/nextjs` | Next.js handlers: `createAiChatHandler`, `createChatInteractionsHandler`, `createRecordingTranscriptionHandler` (alias `glirastes/adapter/nextjs`) |
+| `glirastes/server/testing` | Test helpers for tool setups without model calls (ESM only) |
+| `glirastes/react` | Chat UI, provider, hooks, client actions, navigation bridge, STT |
+| `glirastes/react/vercel` | AI SDK transport and `VercelAiChat` |
+| `glirastes/react/styles.css` | Shipped chat styles |
+| `glirastes/stt` | Provider-neutral STT controller and adapters |
+| `glirastes/ai-sdk` | Vercel AI SDK reference engine (alias `glirastes/runtime/ai-sdk`) |
+| `glirastes/contracts` | Principals, budgets, manifests, revisions, deployments |
+| `glirastes/sync` | Signed revision cache, rollout selection, revocations |
+| `glirastes/embed` | `<glirastes-chat>` element for apps without React |
+| `glirastes/browser` | Navigation bridge, query filters and client actions without React |
+| `glirastes/codegen` | Route scanning and execution-inventory discovery used by the CLI |
+
+## CLI reference
+
+| Command | Purpose |
 |---|---|
-| [`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
+| `glirastes init [--agent codex\|claude] [--dry-run] [--json]` | Scaffold inputs, install skills, hand setup to your coding agent |
+| `glirastes init --ci github [...]` | Write the GitHub tools workflow ([CI](#ci)) |
+| `glirastes tools refresh [--watch] [--mode write\|frozen\|integrity]` | Derive tools from the code |
+| `glirastes tools check [--strict] [--integrity-only]` | Verify committed tool outputs |
+| `glirastes tools status` | Show what the chat can do |
+| `glirastes tools resolve --print` | Work list of open findings for your agent |
+| `glirastes tools describe --print [<tool>...\|--all]` | Work list of descriptions, synonyms and examples |
+| `glirastes tools eval` | Check that example sentences find their tool |
+| `glirastes tools verify <tool>...\|--all` | Confirm agent-written contracts after review |
+| `glirastes tools policy <...>` | Change the local tool policy |
+| `glirastes tools enrich --managed [--first-run] [--base <branch>]` | Pro, CI only: run the managed tool agent |
+| `glirastes setup [--dry-run] [--managed]` | Validate and install the local setup artifacts |
+| `glirastes setup inspect` | Inspect project manifests before integration |
+| `glirastes connect --base-url <url>` | Pair the app with the Platform |
+| `glirastes sync` | Upload the current local setup |
+| `glirastes doctor [--managed] [--verbose] [--json]` | Diagnose the local setup |
+| `glirastes install [--host a,b]` | Install the agent skills only |
+
+`glirastes --help` lists every command and flag; `glirastes tools` and
+`glirastes tools policy` print their own usage.
 
-# Auto-update with the SDK on every npm install
-npx glirastes install-skills --symlink
+## Agent skills
 
-# Preview without writing
-npx glirastes install-skills --dry-run
+The package ships seven skills in [`skills/`](skills/README.md) for your
+existing coding agent (Codex, Claude Code, Gemini): `setting-up-glirastes`,
+`integrating-glirastes-nextjs`, `integrating-glirastes-web`,
+`maintaining-glirastes-tools`, `describing-glirastes-tools`,
+`building-glirastes-chat-ui` and `migrating-to-glirastes`. `glirastes init`
+installs them; `glirastes install --host codex --with-setup-skills` installs
+them without starting setup.
 
-# Overwrite previously installed skills
-npx glirastes install-skills --force
-```
+## Support matrix
 
-`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.
+Next.js 15 App Router, React (Vite, react-router) + NestJS 11 and Vue 3 +
+FastAPI are integrated and automatically checked. Exact levels and evidence:
+[docs/support-matrix.md](docs/support-matrix.md).
 
-> **`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.
+## Docs
 
-<br/>
+- [Support matrix](docs/support-matrix.md)
+- [Tool policy](docs/tool-policy.md)
+- [Chat interactions (`@` and `/`)](docs/chat-interactions.md)
+- [Managed runtime sync](docs/managed-runtime-sync.md)
+- [Runtime persistence](docs/runtime-persistence.md)
+- [0.5.0 acceptance](docs/acceptance/0.5.0-acceptance.md)
+- [Agent skills](skills/README.md)
+- Examples: [`examples/`](examples/)
 
-## License
+## Upgrading from 0.4
 
-Licensed under the [Apache License, Version 2.0](./LICENSE). You may use, modify, and distribute this SDK freely in commercial and non-commercial projects.
+`0.5.0` is the first Foundation release. Its surface differs from
+`glirastes@0.4.0`: exports, codegen APIs and CLI commands were removed or
+replaced. Read **Breaking** in [CHANGELOG.md](CHANGELOG.md) before upgrading;
+the skill [`migrating-to-glirastes`](skills/migrating-to-glirastes/SKILL.md)
+covers moving off `@chainmatics/agentic-*`.
 
-<br/>
+## Security & License
 
----
+Report vulnerabilities as described in [SECURITY.md](SECURITY.md).
+Contributions: [CONTRIBUTING.md](CONTRIBUTING.md).
 
-<p align="center">
-  <sub>Built by <a href="https://chainmatics.de">Chainmatics</a></sub>
-</p>
+Apache-2.0, see [LICENSE](LICENSE) and [NOTICE](NOTICE).