glirastes 0.3.2 → 0.5.0

package/skills/maintaining-glirastes-tools/SKILL.md

@@ -1,467 +1,139 @@
 ---
 name: maintaining-glirastes-tools
-description: Authoring and maintaining Glirastes AI tool definitions, modules, and the codegen pipeline. Use when defining ai-tool.ts files, refining tool descriptions, configuring intent modules, declaring UI patterns, validating coverage, or wiring CI gates.
-version: 1.0.0
-tags:
-  - glirastes
-  - ai-tools
-  - codegen
-  - cli
-triggers:
-  - defineEndpointTool
-  - defineUiTool
-  - ai-tool.ts
-  - ai-ui-tool.ts
-  - tool definition
-  - module-meta
-  - intent module
-  - uiPattern
-  - generate-tools
-  - validate-tools
-  - coverage
-  - scaffold ai-tool
-  - tool authoring
-  - tool description
+description: Use when glirastes tools refresh reports findings, a tool needs attention or is disabled, a route, page, filter or client action changed, or the tool policy must be reviewed.
 ---
 
-# Maintaining Glirastes AI Tools
-
-> **Framework wiring lives elsewhere:**
-> - [integrating-glirastes-nextjs](../integrating-glirastes-nextjs/SKILL.md) — chat route + widget on Next.js
-> - [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md) — `@AiTool` decorators + `AiChatModule`
-> - [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md) — chat UI customization
-
-## Two flavors of tool
-
-A **tool** is something the AI can do. Glirastes ships two definitions; ~95% of real apps need only these two.
-
-### Endpoint Tool — calls your backend
-
-```ts
-import { z } from 'zod';
-import { defineEndpointTool } from 'glirastes';
-
-export const aiTool = defineEndpointTool({
-  id: 'tasks.list',           // unique dot-notation id
-  toolName: 'list_tasks',     // unique snake_case name (what the LLM sees)
-  module: 'task_query',       // intent module — controls routing & model tier
-  sharedWith: ['task_mutation'], // also available to these modules
-  description: `List tasks with an optional status filter.
-WHEN to call: user asks to see tasks, or you need a task ID for a follow-up tool.
-RETURNS: array of { id, title, status }.`,
-  method: 'GET',
-  path: '/api/tasks',
-  inputSchema: z.object({
-    status: z.enum(['open', 'done']).optional(),
-  }),
-  // outputSchema: z.array(...) — optional, helps the SDK validate responses
-  uiPattern: {
-    type: 'filter-and-navigate',
-    target: 'tasks',
-    filterMapping: { status: 'status' },
-  },
-});
-```
-
-### UI Tool — fires a frontend action without an API call
-
-```ts
-import { z } from 'zod';
-import { defineUiTool } from 'glirastes';
-
-export const openSettings = defineUiTool({
-  id: 'settings.open',
-  toolName: 'open_settings',
-  module: 'navigation',
-  description: 'Open the settings dialog for the current user.',
-  inputSchema: z.object({}),
-  uiAction: {
-    type: 'run-client-action',
-    actionId: 'settings.open',
-  },
-});
-```
-
-UI tools never round-trip to the server; the result is a `uiAction` payload that the frontend's `UiActionBus` dispatches to a registered `useAiClientAction(...)` handler.
-
-## Description anatomy — what the LLM actually reads
-
-The description is the **only** signal the LLM has for *when* to call the tool. Treat it as a prompt fragment, not a docstring:
-
-```
-description: `<one-line summary>.
-WHEN to call: <concrete trigger phrasing the user might use>.
-WHAT it returns: <shape>.
-DO NOT: <common LLM mistakes — invented IDs, premature mutations, etc.>.`
-```
-
-Real-world examples that drove down hallucinations:
-
-```ts
-description: `Create a new task.
-IMPORTANT: confirm the title with the user FIRST.
-DO NOT INVENT IDs — call list_users / list_groups to resolve names.`
-```
-
-```ts
-description: `List tasks with an optional status filter.
-WHEN to call: user asks to see, browse, or filter tasks; or you need a task ID for another tool.
-RETURNS: array of { id, title, status, assigneeId }.`
-```
-
-## Input schema — Zod, with `.describe()`
-
-Every input field should have `.describe()` — the LLM uses it as field-level docs:
-
-```ts
-inputSchema: z.object({
-  search: z.string().optional().describe('free-text search over title and description'),
-  status: z.enum(['open', 'done']).optional().describe('filter by lifecycle status'),
-  assigneeId: z.string().uuid().optional().describe('user UUID — never invent, look up via find_user'),
-}),
-```
-
-Path params (`:id` in the route): if the route is `/api/tasks/:id`, include `id` in the input schema. The SDK substitutes it into the URL at call time. (NestJS decorator mode auto-extracts these from `@Param()` — see [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md).)
-
-## Approval flow
-
-`needsApproval` controls whether mutations show an approval card before executing:
-
-```ts
-needsApproval: true,   // always require approval
-needsApproval: false,  // never require approval
-needsApproval: (input, ctx) => input.amount > 1000,  // dynamic
-```
-
-**Defaults** (when `needsApproval` is omitted):
-- `GET` → `false`
-- `POST` / `PATCH` / `PUT` / `DELETE` → `true`
-
-So mutations get approval cards by default; you only specify when you want to override.
-
-## UI Patterns — declarative reactions
-
-After a tool runs, what should the UI do? Glirastes ships 5 patterns. Use them instead of writing custom dispatch code:
-
-| Pattern | Use case | Example |
-|---|---|---|
-| `filter-and-navigate` | GET tools that map a filter to a page URL | `{ type: 'filter-and-navigate', target: 'tasks', filterMapping: { status: 'status' } }` |
-| `open-detail` | After lookup or creation, open a detail view | `{ type: 'open-detail', entity: 'task', idField: 'taskId' }` |
-| `open-dialog` | Open a modal (create / edit) | `{ type: 'open-dialog', dialog: 'create-task' }` |
-| `refresh` | Refresh a region after mutation | `{ type: 'refresh', target: 'tasks' }` |
-| `toast` | Show a notification | `{ type: 'toast', message: '$message', variant: 'success' }` |
-
-Patterns support `$variable` placeholders that interpolate from the **response** body (`$id`, `$message`) or from the **input** (`$status`).
-
-### Compound patterns
-
-Pass an array for multiple effects (toast + refresh after a mutation):
-
-```ts
-uiPattern: [
-  { type: 'toast', message: '$message', variant: 'success' },
-  { type: 'refresh', target: 'tasks' },
-],
-```
-
-Each entry is processed sequentially. Patterns with unmet `condition` fields are skipped — others still fire.
-
-### Manual `uiActionOnSuccess` (escape hatch)
-
-When no built-in pattern fits, emit a raw action:
-
-```ts
-uiActionOnSuccess: {
-  type: 'run-client-action',
-  actionId: 'tasks.celebrate',
-  payload: { taskId: '$id' },
-},
-```
-
-Frontend handler (anywhere a relevant component mounts):
-
-```tsx
-import { useAiClientAction } from 'glirastes/react';
-
-useAiClientAction('tasks.celebrate', (payload) => {
-  fireConfetti();
-});
-```
-
-**Priority** when multiple are present: response `uiAction` field > `uiPattern` > `uiActionOnSuccess`.
-
-## Module definitions (intent routing)
-
-> Module-based routing is a **Pro feature** — it requires `GLIRASTES_API_KEY` and a `lancer` client (intent classification via the Glirastes platform). Without it, all tools are exposed to the LLM on every request (free-tier mode). Module definitions are still useful pre-Pro: you author them upfront, they activate when you flip the env var.
-
-Modules group tools by intent. Define them in `src/lib/ai/module-meta.ts`:
-
-```ts
-import type { ModuleMeta } from 'glirastes';
-
-export const moduleMeta: Record<string, ModuleMeta> = {
-  task_query: {
-    classification: {
-      hint: 'User asks to view, list, or filter tasks (NOT create/modify).',
-      examples: ['show me open tasks', 'what is done?', 'filter by status'],
-    },
-    execution: {
-      maxSteps: 2,           // LLM tool-call rounds for this module
-      contextWindow: 12,     // messages sent to the LLM
-      modelTier: 'fast',     // fast | standard | powerful
-    },
-    systemPrompt: `Focus: list and filter tasks.
-For filter requests use list_tasks with appropriate status.`,
-  },
-  task_mutation: {
-    classification: {
-      hint: 'User asks to create, update, delete, or assign tasks.',
-      examples: ['create a task', 'mark as done', 'assign to Alice'],
-    },
-    execution: { maxSteps: 4, contextWindow: 16, modelTier: 'standard' },
-    systemPrompt: `Focus: mutate tasks.
-NEVER invent IDs — use list_tasks / find_user first.`,
-  },
-};
-```
-
-**Field cheat-sheet:**
-- `classification.hint` + `examples` → auto-generate the intent classifier prompt
-- `execution.modelTier` → which model tier handles the request (`fast` ≈ gpt-4o-mini, `standard` ≈ Sonnet, `powerful` ≈ Opus)
-- `execution.maxSteps` → cap LLM tool-call rounds (cost control)
-- `systemPrompt` → appended to the system prompt for this module only
-
-### Related modules (medium-confidence routing)
-
-When the intent classifier is uncertain (confidence 0.7–0.85), the router can include tools from related modules:
-
-```ts
-const moduleMeta: Record<string, ModuleMeta> = {
-  task_query: { /* ... */, related: ['task_mutation'] },
-  task_mutation: { /* ... */, related: ['task_query'] },
-};
-```
-
-## Codegen pipeline — required for Next.js, not for NestJS
-
-Hand-importing every tool into the chat route doesn't scale past a handful. In Glirastes 0.3.x **Next.js consumers run the CLI codegen as a build hook** — the generated registry is the canonical wiring, the manual import list shown in the quickstart is only OK for tiny demos.
-
-> **NestJS users skip this entire section.** `AiChatModule.forRoot()` discovers `@AiTool`-decorated controllers at runtime via the NestJS `DiscoveryService`. There is no codegen step at all on the NestJS path — runtime DI scan is the equivalent.
->
-> **Coming in 0.4.0:** a `buildToolRegistry` helper backed by `import.meta.glob` / `require.context` will let Next.js consumers also skip the codegen step. Until then the steps below describe the supported pattern.
-
-### Recommended `package.json` scripts
-
-```json
-{
-  "scripts": {
-    "predev":   "glirastes generate-tools --quiet",
-    "prebuild": "glirastes generate-tools --quiet",
-    "ai:scaffold":     "glirastes scaffold",
-    "ai:generate":     "glirastes generate-tools",
-    "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"
-  }
-}
-```
-
-The `predev` / `prebuild` hooks regenerate the registry on every dev start and CI build — the generated files become source-of-truth.
-
-### Output
-
-After `glirastes generate-tools`:
-
-```
-src/generated/ai-tools/
-├── endpoint.generated.ts    # exports `endpointToolRegistry`
-├── ui.generated.ts          # exports `uiToolRegistry`
-├── modules.generated.ts     # exports `toolsByModule`, `moduleTypes`, `relatedModules`,
-│                            #         `IntentType`, `IntentSchema`, `buildIntentModule`,
-│                            #         and (with --meta) `INTENT_MODULES`, `CLASSIFICATION_PROMPT`
-└── action-ids.generated.ts  # union of action IDs (for type-safe useAiClientAction)
-```
-
-Import in your chat route:
-
-```ts
-import { endpointToolRegistry } from '@/generated/ai-tools/endpoint.generated';
-import { uiToolRegistry } from '@/generated/ai-tools/ui.generated';
-
-const tools = { ...endpointToolRegistry, ...uiToolRegistry };
-```
-
-### Module bridge file (when using intent routing)
-
-The codegen produces raw module data (`toolsByModule`, `moduleTypes`). The pipeline (`createAiPipeline` / `createAiTestSuite`) consumes a `ModuleDefinition[]` shape. Author a thin bridge file that joins your `module-meta.ts` with the generated metadata:
-
-```ts
-// src/lib/ai/module-definitions.ts
-import type { ModuleDefinition } from 'glirastes';
-import {
-  toolsByModule,
-  moduleTypes,
-  relatedModules,
-  type IntentType,
-} from '@/generated/ai-tools/modules.generated';
-import { moduleMeta } from '@/lib/ai/module-meta';
-
-function buildModuleDefinition(type: IntentType): ModuleDefinition {
-  const meta = moduleMeta[type];
-  return {
-    id: type,
-    name: type.split('_').map((w) => w[0].toUpperCase() + w.slice(1)).join(' '),
-    description: meta.classification.hint,
-    tools: [...toolsByModule[type]],
-    executionDefaults: {
-      contextWindow: meta.execution.contextWindow,
-      modelTier: meta.execution.modelTier,
-    },
-    classification: meta.classification,
-    systemPrompt: meta.systemPrompt,
-  };
-}
-
-export const modules: ModuleDefinition[] = moduleTypes.map(buildModuleDefinition);
-export { relatedModules };
-```
-
-The chat handler and the test suite both import `modules` from this file.
-
-### Module metadata flag
-
-If your `module-meta.ts` lives at a non-default path:
+# Maintaining Glirastes Tools
+
+The app's code is the tool catalogue. The source-derived generator
+(`glirastes tools refresh`) turns route handlers, pages, URL filters and client
+actions into tools; where the code does not say enough, it prints a work list
+for you, the app's coding agent. Glirastes never calls a model: you resolve the
+findings, the next refresh checks every entry with the same rules, whoever
+wrote it, and an invalid entry is ignored (`resolution-rejected`) while the tool
+keeps its fallback.
+
+## Boundaries
+
+- Write only `.glirastes/tool-resolutions.json`, `.glirastes/tool-semantics.json`,
+  new `contract.ts` files next to route handlers, and app code the work list
+  names (a navigation bridge, a payload contract, an exported schema).
+- Never edit `.glirastes/tool-policy.json`, route handler logic, the inventory,
+  tool ids, exclusions or any generated output. Items owned by `developer`
+  are shown to the developer with their command; you never run them yourself.
+- Never resolve a finding by leaving a tool, a parameter or a mapping out:
+  every key a handler reads stays in its schema, and nothing is excluded to make
+  a list shorter (no `// @ai-ignore` comment, no exclusion proposal for that).
+- Never weaken a check to pass: effects may only raise the risk, a write tool
+  keeps asking first unless the developer (or, for a connected app, a Platform
+  owner or admin) relaxes it, delete, financial and external tools always ask
+  first.
+- No secrets, keys (`sk-or-v1…`), e-mail addresses, phone or account numbers in
+  anything you write.
+
+## Workflow
+
+1. After a change to routes, pages, URL filters or client actions run
+   `glirastes tools refresh`. Read the summary: added, changed, risk raised,
+   removed, needs attention, excluded, each with its next step.
+2. Run `glirastes tools resolve --print` and work through `items`:
+   - `owner: "agent"`, `target.kind: "file"`: write the `expected` entry at
+     `target.key` of `target.file`. Replace every `<…>` placeholder: `model`
+     names you (e.g. `claude-code`), `interfaceDigest` stays as printed, the
+     input schema gets real types, formats, enums, bounds and a description per
+     parameter, read from `files` (handler, services, schemas). Strict JSON
+     Schema 2020-12, an object with `additionalProperties: false`, at most
+     32 KB, no `patternProperties` or `propertyNames`.
+   - `owner: "agent"`, `target.kind: "app-code"`: change the app code in
+     `target.files` as the finding says (export the schema, add the payload
+     contract as third argument of `useAiClientAction`, mount the navigation
+     bridge, rename a colliding parameter, add the client action a UI
+     control proposes).
+   - `owner: "developer"`: show `target.command` and why; stop there.
+     With `target.kind: "review"` a person wrote or reviewed the entry at
+     `target.key` of `target.file` (human or locked): leave it exactly as it
+     is and report it with its `message` for review.
+   - `blocking`: fix these first (for example `export *` in a route file,
+     a linked source folder, an invalid `tool-policy.json`); nothing is
+     written until they are gone.
+3. Run `glirastes tools refresh` and `glirastes tools resolve --print` again
+   until no agent item is left. A rejected entry names its reason in
+   `message`; fix it rather than retrying blindly.
+4. Review the tool diff (`.glirastes/setup-artifact.json`,
+   `.glirastes/tool-contracts.json`) with the code change and commit both.
+5. In Standalone, restart the app to load the new tools; no Platform account
+   or sync is needed. A Connected app may run `glirastes sync`; it uploads the
+   technical result and never activates anything. Managed apps keep their
+   verified revision source.
+
+## Findings and what resolves them
+
+| Code | Resolve with |
+| --- | --- |
+| `input-contract-unresolved`, `input-role-unclear`, `input-role-unsupported`, `schema-json-unavailable` | a `tool-resolutions.json` entry (JSON Schema, or `schemaRef` to an exported Zod schema), or validation with an exported schema in a sibling `contract.ts` |
+| `auth-evidence-missing` | the name of the session helper the handler really calls, in `conventions.authHelpers`; never a helper that does not check the session |
+| `contract-stale` | a stale `contract.ts`: update it for the changed interface; a stale `tool-resolutions.json` entry (always written or reviewed by a person): developer, who renews or removes it |
+| `schema-not-exported`, `schema-module-unloadable`, `schema-content-rejected`, `parameter-collision`, `contract-effect-invalid` | the app code the message names; a schema moves into a side-effect-free module (a sibling `contract.ts` or a schema file) that the handler imports, never into a new export of `route.ts`, whose exports Next.js type-checks |
+| `ui-action-id-dynamic`, `ui-action-id-invalid`, `ui-action-id-reserved`, `definition-id-invalid`, `contract-presentation-invalid` | the registration or contract in `target.files`: a literal action id, a valid contract id or presentation |
+| `tool-semantics-invalid` | the entry `target.key` names in `.glirastes/tool-semantics.json`; keep its human text, fix only the shape |
+| `input-schema-not-object` | an object at the root of the input schema (optional fields, or one field holding the variants), changed together with every caller of the route; for an internal route, tell the developer instead |
+| `navigation-bridge-missing` | mount `useGlirastesNavigationBridge` (React) or `registerNavigationBridge` (`glirastes/browser`) where it is always mounted |
+| `ui-action-payload-untyped`, `ui-action-contract-conflict` | one payload contract per client action |
+| `ui-control-unbound` | a setting the chat cannot set yet (a context setter or the next-themes `setTheme` with a closed set of values). Add `expected.registration` in `expected.file`, inside the component that owns the state and is always mounted (the provider, or for `setTheme` a component rendered inside the `ThemeProvider`), never on the settings page. Keep `expected.actionId`; import `useAiClientAction` from `glirastes/react` and `z` from `zod`, and use the app's own const list (e.g. `z.enum(UI_SIZES)`) where it has one. If the chat must not set it, tell the developer: `glirastes tools policy exclude-control <subject> --reason <text>` |
+| `ui-control-contract-mismatch` | narrow the client action's contract to the values the setter takes |
+| `ui-action-write-unproven` | developer: `glirastes tools policy raise <tool> write` when the helper writes |
+| `risk-lower-available` | developer: `glirastes tools policy accept <tool>` after review |
+| `policy-entry-orphaned` | developer: `glirastes tools policy reset <tool>` or `include` |
+| `resolution-rejected` | the reason in the message; fix or remove that entry |
+
+The work list also names navigation and filter tools: they need the bridge,
+literal page paths and closed filter domains where possible.
+
+## Policy (developer only)
+
+The developer changes `.glirastes/tool-policy.json` through
+`glirastes tools policy`. Every change is checked like a refresh before it is
+written: disable, confirm, raise the risk and limit roles always work; relaxing
+confirmation needs `--yes`, works for write tools only and is pinned to the
+tool and its risk; a risk the code lowers is held until `accept`.
+
+When the app is connected, a Platform owner or admin may switch off a
+confirmation that comes from the code default, for tools up to `write`
+(`glirastes tools status` marks it `Platform may relax`).
+`glirastes tools policy confirm <tool>` writes `"requiresApproval": true`, a
+local lock the Platform never relaxes (`locked in tool-policy.json`);
+`glirastes tools policy reset <tool>` lifts it. Delete, financial and external
+tools always ask first.
+
+## Commands
 
 ```bash
-glirastes generate-tools --meta @/lib/ai/module-meta
-```
-
-`@/...` resolves to your TS path alias.
-
-## All CLI commands
-
-| Command | Purpose | Common flags |
-|---|---|---|
-| `glirastes scaffold --route <file>` | Bootstrap `ai-tool.ts` next to a `route.ts` from method, path params, body fields | `--dry-run`, `--force`, `--root <dir>` |
-| `glirastes generate-tools` | Run all generators (endpoint + UI + modules + action IDs) | `--meta <import-path>`, `--quiet` |
-| `glirastes generate-endpoint-tools` | Endpoint registry only | `--quiet` |
-| `glirastes generate-ui-tools` | UI tool registry + action IDs | `--quiet` |
-| `glirastes generate-modules` | Module/intent registry only | `--meta <import-path>` |
-| `glirastes generate-auto` | Auto-detect repo layout, choose generator + skill/MCP output | — |
-| `glirastes generate <openapi.yaml>` | Generate endpoint tools from an OpenAPI spec (good for legacy backends) | `--out <file>` |
-| `glirastes validate <openapi.yaml>` | Validate `x-ai` extensions in an OpenAPI spec | `--ci` |
-| `glirastes validate-tools` | Validate naming, duplicates, missing approvals, path mismatches | `--ci`, `--fix`, `--quiet` |
-| `glirastes coverage` | Routes without `ai-tool.ts`, orphan handlers, unhandled action IDs | `--ci`, `--quiet` |
-| `glirastes test` | Scaffold an AI behaviour test file (Vitest, no LLM call) | `--output <file>`, `--force`, `--dry-run` |
-| `glirastes install-skills` | Install the bundled agent skills (this directory) into a target like `.claude/skills` | `--target <dir>`, `--stack nextjs\|nestjs\|nextjs+nestjs\|all`, `--symlink`, `--force`, `--dry-run` |
-| `glirastes generate-skills` | Export the registry as Claude Code / Codex skill files (so *agents* can call your tools) | `--app-name`, `--base-url`, `--auth bearer\|api-key\|oauth2\|cookie`, `--token-env`, `--format markdown\|json\|both`, `--output-dir`, `--sync`, `--remote` |
-| `glirastes generate-mcp-server` | Export the registry as a standalone MCP server project | `--app-name`, `--base-url`, `--auth ...` |
-| `glirastes check-upgrade` | Compare current code against SDK release notes; flag breaking changes | `--from-version <ver>` |
-| `glirastes sync` | Upload tool schemas to the Glirastes platform (Pro registry) | `--api-key` (or `GLIRASTES_API_KEY` env), `--url` |
-
-### CLI flag deep-dive
-
-| Flag | Effect |
-|---|---|
-| `--quiet` | One-line output — ideal for `predev`/`prebuild` hooks |
-| `--ci` | Exit code 1 on any issue — for CI pipelines |
-| `--fix` | On `validate-tools`, prints quick-fix scaffold commands per missing tool |
-| `--dry-run` | On `scaffold` / `test`, preview generated code without writing |
-| `--force` | On `scaffold` / `test`, overwrite existing file |
-| `--meta <path>` | Path to `module-meta.ts` (uses TS path aliases like `@/lib/ai/module-meta`) |
-| `--app-name` (skills/mcp) | Name for the skill or MCP server |
-| `--base-url` (skills/mcp) | Backend base URL the agent should call |
-| `--auth bearer` (skills/mcp) | Auth strategy. `bearer` reads token from env var (default `API_TOKEN`); `api-key` uses an API key header; `oauth2` adds OAuth flow scaffolding; `cookie` uses session cookies |
-| `--token-env <NAME>` | For bearer auth, the env var the agent reads the token from |
-| `--sync` (skills) | Upload to Glirastes platform after generating |
-| `--remote` (skills) | `--sync` + trigger remote regeneration on the platform |
-
-### Coverage report — what it catches
-
-| Section | Catches |
-|---|---|
-| **Uncovered Routes** | `route.ts` without an `ai-tool.ts` next to it (with `glirastes scaffold` suggestion) |
-| **Uncovered Components** | Component directory without an `ai-ui-tool.ts` |
-| **Missing Handlers** | UI tool defines `actionId` X, but no `useAiClientAction('X')` found in `.tsx` files |
-| **Orphan Handlers** | `useAiClientAction('X')` exists, but no UI tool defines `actionId: 'X'` |
-
-### Validation report — severities
-
-- **Errors** (block CI with `--ci`): orphaned `ai-tool.ts` without a `route.ts`, missing exports, malformed Zod schemas
-- **Warnings**: routes without an `ai-tool.ts` (with scaffold suggestion), path mismatches between `path` and route filesystem location
-- **Info**: tools without a `module` field (with module-assignment hint)
-
-Add `--fix` to get a consolidated quick-fix block at the bottom.
-
-### Excluding routes from coverage
-
-Skip a route from coverage and validation:
-
-- File-level: `// @ai-ignore` at the top of `route.ts`
-- Directory-level: a `.ai-ignore` file in any directory excludes the entire subtree
-
-## Testing — deterministic, no LLM
-
-`glirastes test` scaffolds a Vitest test file using `glirastes/server/testing`:
-
-```ts
-import { createAiTestSuite } from 'glirastes/server/testing';
-import { modules } from '@/lib/ai/module-definitions';
-import { endpointToolRegistry } from '@/generated/ai-tools/endpoint.generated';
-import { uiToolRegistry } from '@/generated/ai-tools/ui.generated';
-
-const suite = createAiTestSuite({
-  tools: { ...endpointToolRegistry, ...uiToolRegistry },
-  modules,
-});
-
-suite.smokeTest();        // module completeness, naming, no duplicates
-suite.guardrailsTest();   // injection, length, sanitization
-suite.approvalTest();     // POST/DELETE → needsApproval:true (default)
-suite.routingTest([
-  { input: 'show tasks', expectModule: 'task_query', expectTools: ['list_tasks'] },
-  { input: 'create a task: review PR', expectModule: 'task_mutation' },
-]);
-
-// Low-level: simulate the pipeline directly
-const result = await suite.simulatePipeline('list my tasks', {
-  intent: 'task_query', confidence: 0.95,
-});
-expect(result.tools).toContain('list_tasks');
-```
-
-**When to update tests:**
-- New tool → add a routing case
-- Tool moved to a different module → update `expectModule`
-- Tool renamed → update `expectTools`
-- New mutation → confirm `needsApproval: true`
-- New module → add smoke + routing cases
-
-## Naming conventions
-
-| Field | Format | Example |
-|---|---|---|
-| `id` | dot-notation, `<resource>.<action>` | `tasks.list`, `tasks.bulk.update`, `users.search` |
-| `toolName` | snake_case | `list_tasks`, `bulk_update_tasks`, `find_user` |
-| `module` | snake_case noun phrase | `task_query`, `task_mutation`, `navigation` |
-| `actionId` (UI) | dot-notation, `<entity>.<action>` | `task-details.open`, `tasks.refresh` |
-
-Both `id` and `toolName` must be unique across the whole registry — `glirastes validate-tools` enforces this.
-
-## After every change — run the validation chain
-
-1. `npm run ai:generate` — regenerate registries
-2. `npm run ai:validate` — naming, duplicates, missing approvals, path mismatches
-3. `npm run ai:coverage` — routes without ai-tool.ts, orphan handlers
-4. `npm run ai:test` (if you have behaviour tests)
-5. `npm run build` — final type-check + Next.js / NestJS build
-
-CI: add `ai:coverage:ci` and `ai:validate:ci` as required steps.
-
-## What this skill does NOT cover
-
-- **Framework wiring** (chat route, decorators, `AiChatModule`) — see [integrating-glirastes-nextjs](../integrating-glirastes-nextjs/SKILL.md) or [integrating-glirastes-nestjs](../integrating-glirastes-nestjs/SKILL.md)
-- **Chat UI customization** (theming, mentions, voice, approval cards) — see [building-glirastes-chat-ui](../building-glirastes-chat-ui/SKILL.md)
-- **Glirastes platform deep-dive** (PII Shield via `createPiiShield`, intent routing via `createLancer`, custom guardrails, service degradation) — opt in via `GLIRASTES_API_KEY`; documented separately at [docs.chainmatics.de](https://chainmatics.de)
+glirastes tools refresh
+glirastes tools resolve --print
+glirastes tools check
+glirastes tools status
+# developer only: show these with the reason, never run them on your own
+glirastes tools policy show <tool>
+glirastes tools policy raise <tool> write --reason "<why>"
+glirastes tools policy confirm <tool>
+glirastes tools policy disable <tool> --reason "<why>"
+glirastes tools policy relax <tool> --yes --reason "<review>"
+glirastes tools policy exclude "POST /api/internal/**" --reason "<why>"
+glirastes tools policy include "POST /api/internal/**"
+glirastes tools policy accept <tool>
+glirastes tools policy reset <tool>
+glirastes doctor
+```
+
+## Verification
+
+- `glirastes tools resolve --print` shows no agent item; developer items are
+  reported with their commands.
+- `glirastes tools check` reports `Tool outputs match the code.`; CI fails on
+  stale outputs instead of keeping obsolete tools.
+- Adding, changing and deleting an endpoint, a navigation page and a filter
+  changes the tools; a removed tool cannot be called, also not after a
+  restart or a rollback.
+- The endpoint, not the tool, still refuses unauthorized calls:
+  `resolvePrincipal` is resolved again before every tool call.
+- `glirastes doctor` passes.