docs(kiira): type-check third-party libs via externalPackages (kiira 0.5.0)

Upgrade kiira to 0.5.0 and declare the third-party packages the docs import
(Vercel AI SDK, openai, arktype/valibot, redis/pino/@opentelemetry/api/express/
hono, @modelcontextprotocol/sdk, and the community adapters) under
externalPackages, so kiira installs them into an isolated cache and type-checks
against the real types instead of ignoring those fences. Un-ignored ~67 fences
across migration/comparison, community-adapters, advanced (redis/pino/otel),
mcp, structured-outputs, and server quick-starts -- catching real API drift in
the examples along the way. Remaining ignores are genuine: removed/old TanStack
APIs in before-code, framework route boilerplate, MCP/cencori subpath exports
kiira's external resolver can't map yet, and a couple of pseudo-code blocks.

Kiira: 663 snippets pass, 0 fail, 147 ignored (was 596 / 214).

Author: AlemTuzlak

.agent/self-learning/lessons/2026-06-23-authoring-kiira-doc-snippets.md

@@ -74,10 +74,20 @@ is a means (keep examples honest), not the end (a green check).
    sets `noImplicitReturns: false` for docs, so a hook that returns on some
    branches and falls through on others is fine un-annotated.
 
-7. **`ignore` is the last resort,** only for genuinely un-checkable fences:
-   competitor SDKs not installed (`ai`, `@ai-sdk/*`), uninstalled community
-   adapters, framework route-registration boilerplate (`createFileRoute`). Never
-   `ignore` to mask a fixable error.
+7. **Third-party libraries are NOT a reason to `ignore` anymore.** kiira 0.5.0+
+   has `externalPackages` (in kiira.config.ts) — declare the npm package + range
+   and kiira installs it into an isolated cache and type-checks against the real
+   types. We use it for the Vercel AI SDK (`ai`, `@ai-sdk/*`), `openai`,
+   `arktype`/`valibot`, `redis`/`pino`/`@opentelemetry/api`/`express`/`hono`,
+   `@modelcontextprotocol/sdk`, and every community adapter. So a snippet that
+   imports a real published package should declare it in `externalPackages` and
+   type-check — not be ignored. See [[kiira-ci-setup]].
+
+8. **`ignore` is the last resort,** only for genuinely un-checkable fences:
+   imports of packages NOT declared in `externalPackages` (e.g. `react-native` /
+   Expo, intentionally not installed), framework route-registration boilerplate
+   (`createFileRoute`, SvelteKit `./$types`), or deliberate non-compiling
+   pseudo-code. Never `ignore` to mask a fixable error.
 
 **Heuristic:** before committing a snippet fix, ask "did I make the example more
 correct, or just make the error go away?" If a reader copying this snippet would

.agent/self-learning/lessons/2026-06-23-kiira-ci-setup.md

@@ -19,6 +19,22 @@ its resolution model and always read errors with `--verbose` before acting.
 ("zod mismatch") and a CI-only failure (`@tanstack/ai-angular`). Both are
 explained by how kiira resolves and reports.
 
+**Third-party deps — use `externalPackages` (kiira 0.5.0+), don't `ignore`.**
+Declare any npm package the docs import but the workspace doesn't depend on under
+`externalPackages: { "<pkg>": "<range>" }` (also per-glob via `overrides`). kiira
+installs them into an isolated cache (`node_modules/.kiira`, gitignored) and
+type-checks against the real types. We declare the Vercel AI SDK (`ai`,
+`@ai-sdk/*`), `openai`, `arktype`/`valibot`, `redis`/`pino`/`@opentelemetry/api`/
+`express`/`hono`/`@modelcontextprotocol/sdk`, and every community adapter — so
+those snippets validate for real instead of being ignored. Notes:
+- The isolated install prints non-fatal `npm warn`/`npm error ... matches` noise
+  (a messy transitive dep tree in one community adapter) but still succeeds via
+  the pnpm fallback — exit code is 0; only the kiira "found N errors" line
+  matters. Verified on a cold cache (`rm -rf node_modules/.kiira`).
+- CI runs this install on each kiira run (network + time). Acceptable trade for
+  real type-checking; if a package's dep tree ever breaks the install, drop that
+  one package back to an `ignore`.
+
 **How it's wired (the working setup):**
 
 - `kiira` devDep + `kiira.config.ts` (no `tsconfig.docs.json`). Config:

docs/advanced/built-in-middleware.md

@@ -107,9 +107,12 @@ All methods may return a `Promise` for async backends. The middleware handles TT
 
 **Redis example:**
 
-```typescript ignore
+```typescript
+import { chat } from "@tanstack/ai";
 import { createClient } from "redis";
 import { toolCacheMiddleware, type ToolCacheStorage } from "@tanstack/ai/middlewares";
+import { adapter, messages } from "./server";
+import { weatherTool } from "./tools";
 
 const redis = createClient();
 
@@ -213,10 +216,12 @@ const stream = chat({
 
 Emits vendor-neutral OpenTelemetry traces and metrics for every `chat()` call — a root span per call, a child span per agent-loop iteration, and a grandchild span per tool execution, all tagged with [GenAI semantic-convention attributes](https://opentelemetry.io/docs/specs/semconv/gen-ai/).
 
-```typescript ignore
+```typescript
 import { chat } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
 import { otelMiddleware } from "@tanstack/ai/middlewares/otel";
 import { trace, metrics } from "@opentelemetry/api";
+import { messages } from "./server";
 
 const otel = otelMiddleware({
   tracer: trace.getTracer("my-app"),

docs/advanced/debug-logging.md

@@ -27,7 +27,7 @@ import { chat } from "@tanstack/ai";
 import { openaiText } from "@tanstack/ai-openai";
 
 const stream = chat({
-  adapter: openaiText("gpt-4o"),
+  adapter: openaiText("gpt-5.5"),
   messages: [{ role: "user", content: "Hello" }],
   debug: true,
 });
@@ -36,7 +36,7 @@ const stream = chat({
 Every internal event now prints to the console with a `[tanstack-ai:<category>]` prefix:
 
 ```
-[tanstack-ai:request] activity=chat provider=openai model=gpt-4o messages=1 tools=0 stream=true
+[tanstack-ai:request] activity=chat provider=openai model=gpt-5.5 messages=1 tools=0 stream=true
 [tanstack-ai:agentLoop] run started
 [tanstack-ai:provider] provider=openai type=response.output_text.delta
 [tanstack-ai:output] type=TEXT_MESSAGE_CONTENT
@@ -84,9 +84,11 @@ chat({
 
 Pass a `Logger` implementation and all debug output flows through it instead of `console`:
 
-```typescript ignore
-import type { Logger } from "@tanstack/ai";
+```typescript
+import { chat, type Logger } from "@tanstack/ai";
+import { openaiText } from "@tanstack/ai-openai";
 import pino from "pino";
+import { messages } from "./server";
 
 const pinoLogger = pino();
 const logger: Logger = {
@@ -97,7 +99,7 @@ const logger: Logger = {
 };
 
 chat({
-  adapter: openaiText("gpt-4o"),
+  adapter: openaiText("gpt-5.5"),
   messages,
   debug: { logger }, // all categories on, piped to pino
 });
@@ -115,7 +117,11 @@ If your `Logger` implementation throws — a cyclic-meta `JSON.stringify`, a tra
 
 If you need to know when your own logger is failing, guard inside your implementation:
 
-```typescript ignore
+```typescript
+import { type Logger } from "@tanstack/ai";
+import pino from "pino";
+
+const pinoLogger = pino();
 const logger: Logger = {
   debug: (msg, meta) => {
     try {
@@ -125,7 +131,9 @@ const logger: Logger = {
       process.stderr.write(`logger failed: ${String(err)}\n`);
     }
   },
-  // ... info, warn, error
+  info:  (msg, meta) => pinoLogger.info(meta, msg),
+  warn:  (msg, meta) => pinoLogger.warn(meta, msg),
+  error: (msg, meta) => pinoLogger.error(meta, msg),
 };
 ```
 

docs/advanced/otel.md

@@ -38,7 +38,7 @@ const otel = otelMiddleware({
 })
 
 const result = await chat({
-  adapter: openaiText('gpt-4o'),
+  adapter: openaiText('gpt-5.5'),
   messages: [{ role: 'user', content: 'hi' }],
   middleware: [otel],
   stream: false,
@@ -50,11 +50,11 @@ const result = await chat({
 ### Spans
 
 ```text
-chat gpt-4o              (root, kind: INTERNAL)
-├── chat gpt-4o #0       (iteration, kind: CLIENT)
+chat gpt-5.5              (root, kind: INTERNAL)
+├── chat gpt-5.5 #0       (iteration, kind: CLIENT)
 │   ├── execute_tool get_weather
 │   └── execute_tool get_time
-└── chat gpt-4o #1       (iteration, kind: CLIENT)
+└── chat gpt-5.5 #1       (iteration, kind: CLIENT)
 ```
 
 Iteration spans are numbered (`#0`, `#1`, ...) so distinct iterations of the same chat are easy to pick apart in trace viewers.
@@ -109,7 +109,12 @@ By default, only metadata lands on spans. To record prompt and completion conten
 
 Pass a `redact` function to strip PII before anything is recorded:
 
-```ts ignore
+```ts
+import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
+import { trace } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('my-app')
+
 otelMiddleware({
   tracer,
   captureContent: true,
@@ -133,7 +138,12 @@ All four extensions are optional. Each wraps user code in try/catch — a thrown
 
 Override default span names. `info.kind` is `'chat' | 'iteration' | 'tool'`.
 
-```ts ignore
+```ts
+import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
+import { trace } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('my-app')
+
 otelMiddleware({
   tracer,
   spanNameFormatter: (info) =>
@@ -145,7 +155,13 @@ otelMiddleware({
 
 Add custom attributes to every span. Fires once per span.
 
-```ts ignore
+```ts
+import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
+import { trace } from '@opentelemetry/api'
+import { getCurrentTenant } from './context'
+
+const tracer = trace.getTracer('my-app')
+
 otelMiddleware({
   tracer,
   attributeEnricher: () => ({
@@ -162,7 +178,13 @@ Mutate `SpanOptions` immediately before `tracer.startSpan(...)`. Useful for addi
 
 Fires just before every `span.end()`. Common uses: record custom events, emit per-tool metrics via your own `Meter`.
 
-```ts ignore
+```ts
+import { otelMiddleware } from '@tanstack/ai/middlewares/otel'
+import { trace, metrics } from '@opentelemetry/api'
+
+const tracer = trace.getTracer('my-app')
+const meter = metrics.getMeter('my-app')
+
 const toolDuration = meter.createHistogram('tool.duration')
 otelMiddleware({
   tracer,

docs/community-adapters/cencori.md

@@ -24,10 +24,13 @@ npm install @cencori/ai-sdk
 ## Basic Usage
 
 ```typescript ignore
+// ignore: @cencori/ai-sdk/tanstack is a subpath export; kiira's paths["*"] wildcard maps it
+// to a flat directory lookup and does not consult the package.json exports field,
+// so the subpath cannot be resolved until kiira.config.ts adds an explicit path entry.
 import { chat } from "@tanstack/ai";
 import { cencori } from "@cencori/ai-sdk/tanstack";
 
-const adapter = cencori("gpt-4o");
+const adapter = cencori("o1");
 
 for await (const chunk of chat({
   adapter,
@@ -42,19 +45,21 @@ for await (const chunk of chat({
 ## Configuration
 
 ```typescript ignore
+// ignore: @cencori/ai-sdk/tanstack subpath not resolvable via kiira's paths["*"] wildcard.
 import { createCencori } from "@cencori/ai-sdk/tanstack";
 
-const cencori = createCencori({
+const myCencori = createCencori({
   apiKey: process.env.CENCORI_API_KEY!,
   baseUrl: "https://cencori.com", // Optional
 });
 
-const adapter = cencori("gpt-4o");
+const adapter = myCencori("o1");
 ```
 
 ## Streaming
 
 ```typescript ignore
+// ignore: @cencori/ai-sdk/tanstack subpath not resolvable via kiira's paths["*"] wildcard.
 import { chat } from "@tanstack/ai";
 import { cencori } from "@cencori/ai-sdk/tanstack";
 
@@ -67,7 +72,7 @@ for await (const chunk of chat({
   if (chunk.type === "TEXT_MESSAGE_CONTENT") {
     process.stdout.write(chunk.delta);
   } else if (chunk.type === "RUN_FINISHED") {
-    console.log("\nDone:", chunk.finishReason);
+    console.log("\nDone");
   }
 }
 ```
@@ -76,11 +81,12 @@ for await (const chunk of chat({
 ## Tool Calling
 
 ```typescript ignore
+// ignore: @cencori/ai-sdk/tanstack subpath not resolvable via kiira's paths["*"] wildcard.
 import { chat, toolDefinition } from "@tanstack/ai";
 import { cencori } from "@cencori/ai-sdk/tanstack";
 import { z } from "zod";
 
-const adapter = cencori("gpt-4o");
+const adapter = cencori("o1");
 
 const getWeatherDef = toolDefinition({
   name: "getWeather",
@@ -99,9 +105,9 @@ for await (const chunk of chat({
   tools: [getWeather],
 })) {
   if (chunk.type === "TOOL_CALL_START") {
-    console.log("Tool call:", chunk.toolName);
+    console.log("Tool call:", chunk.toolCallName);
   } else if (chunk.type === "TOOL_CALL_END") {
-    console.log("Tool result:", chunk.result);
+    console.log("Tool call finished:", chunk.toolCallId);
   }
 }
 ```
@@ -112,10 +118,11 @@ for await (const chunk of chat({
 Switch between providers with a single parameter:
 
 ```typescript ignore
+// ignore: @cencori/ai-sdk/tanstack subpath not resolvable via kiira's paths["*"] wildcard.
 import { cencori } from "@cencori/ai-sdk/tanstack";
 
-// OpenAI
-const openai = cencori("gpt-4o");
+// OpenAI-compatible
+const openaiCompat = cencori("o1");
 
 // Anthropic
 const anthropic = cencori("claude-3-5-sonnet");