glirastes 0.3.1 → 0.3.2

package/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-04-29
+
+### Changed
+
+- Documentation pass that makes the **CLI codegen step explicit as a
+  required part of the Next.js setup** for any non-trivial app. The
+  earlier framing implied codegen was only "for scaling up" — in
+  practice the manual `endpointToolsToRegistry([…])` import list breaks
+  down past a handful of tools, and codegen is the canonical wiring.
+  - README quickstart Step 4 now points readers at the codegen workflow
+    immediately after the demo manual-import example.
+  - The "Scaling up" section is renamed to **"Scaling up — required
+    codegen workflow for Next.js"** and explicitly states NestJS users
+    skip it (runtime DI scan handles aggregation).
+  - The `integrating-glirastes-nextjs` and `maintaining-glirastes-tools`
+    skills mirror the same framing so coding agents pick the codegen
+    path by default for non-trivial apps.
+- Forward-looking note in README and skills: a `buildToolRegistry`
+  helper based on `import.meta.glob` / `require.context` is planned
+  for **0.4.0** and will let Next.js consumers skip the codegen step.
+
+No code changes — patch-level docs release.
+
 ## [0.3.1] - 2026-04-28
 
 ### Added

package/README.md

@@ -14,7 +14,7 @@
   <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--codegen-workflow"><strong>Scaling up</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>
 </p>
@@ -246,6 +246,10 @@ const registry = endpointToolsToRegistry(scan.tools);
 
 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
@@ -772,9 +776,13 @@ The voice button streams audio to your backend, which proxies it to a speech-to-
 
 <br/>
 
-## Scaling up — codegen workflow
+## Scaling up — required codegen workflow for Next.js
 
-Hand-importing 50 tool definitions into your chat route doesn't scale. The CLI generates a registry from co-located `*.ai-tool.ts` files so you can stay co-located while still wiring everything centrally.
+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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glirastes",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Official Chainmatics SDK for building AI-powered chat, tools, and agent systems. Part of the Glirastes platform.",
   "license": "Apache-2.0",
   "author": {

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

@@ -129,7 +129,7 @@ Edit `description` (the LLM reads this to decide when to call the tool), refine
 
 Two paths depending on tool count:
 
-### Few tools — manual import
+### Few tools (≤5) — manual import
 
 ```ts
 // src/app/api/chat/route.ts
@@ -145,9 +145,11 @@ export const POST = createAiChatHandler({
 });
 ```
 
-### Many tools — codegen pipeline
+OK as a starting point. The moment you go past a handful of tools, switch to the codegen pipeline below — manual maintenance of the import list breaks down fast.
 
-Add to `package.json`:
+### Production: codegen pipeline (required for non-trivial apps)
+
+In Glirastes 0.3.x **the canonical Next.js setup is to wire the codegen as a build hook**. Add to `package.json`:
 
 ```json
 {
@@ -163,6 +165,10 @@ Add to `package.json`:
 }
 ```
 
+The `predev` and `prebuild` hooks regenerate the registry on every dev server start and CI build, so the generated files stay in sync with your `*.ai-tool.ts` source-of-truth. Without these hooks the chat route imports would point at stale generated output.
+
+> **Coming in 0.4.0:** `buildToolRegistry` based on `import.meta.glob` / `require.context` will let you skip the codegen step and the build hook entirely. Until then, the codegen pipeline is the supported pattern for any non-trivial Next.js app.
+
 Then import the generated registry instead of individual tools:
 
 ```ts

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

@@ -242,9 +242,13 @@ const moduleMeta: Record<string, ModuleMeta> = {
 };
 ```
 
-## Codegen pipeline — scale to 50+ tools
+## Codegen pipeline — required for Next.js, not for NestJS
 
-Hand-importing every tool into the chat route doesn't scale. The CLI generates a registry from co-located `ai-tool.ts` files.
+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