Add headless docs search and AI answers

apps/docs-smoke/.gitignore

@@ -1,4 +1,6 @@
+.output/
 content-fixtures/
 public/
 public-real/
 public-real2/
+test-results/

apps/docs-smoke/content/docs/index.mdx

@@ -28,6 +28,10 @@ description: "Package docs for runtime adapters, remark plugins, conversion, LLM
       type: "pipeline",
       description: "Generate `llms.txt` and topic-scoped agent context files.",
     },
+    "@inth/docs/search": {
+      type: "runtime",
+      description: "Static local search, source-grounded answer context, request guards, and AI SDK streaming helpers.",
+    },
     "@inth/docs/lint": {
       type: "pipeline",
       description: "Validation APIs and the `inth-docs-lint` CLI.",
@@ -71,6 +75,11 @@ await convertAllMdx({
 ## What to open in this app
 
 <Cards>
+  <Card
+    title="Search and AI Answers"
+    description="Explains the headless search surfaces, generated index, AI answer route, abuse guards, and demo."
+    href="/docs/search"
+  />
   <Card
     title="Quickstart"
     description="Shows the basic conversion flow plus hydrated `Tabs` and `PackageCommandTabs`."

apps/docs-smoke/content/docs/meta.json

@@ -2,6 +2,7 @@
   "title": "Docs",
   "pages": [
     "index",
+    "search",
     "guides/quickstart",
     "guides/components-fixture",
     "guides/auto-type-table-fixture"

apps/docs-smoke/content/docs/search.mdx

@@ -0,0 +1,94 @@
+---
+title: "Search and AI Answers"
+description: "Generate a local docs search index and stream source-grounded AI answers."
+---
+
+# Search and AI Answers
+
+`@inth/docs` includes headless search logic for docs sites that want to bring their own UI.
+
+<Callout title="Demo route">
+  Open the live search example at [/search](/search). Typing runs local search only; the `Ask` button is the only action that can call the model.
+</Callout>
+
+## Package Surfaces
+
+<TypeTable
+  type={{
+    "@inth/docs/search": {
+      type: "runtime",
+      description: "Edge-safe search, answer context, query validation, JSON body limits, and rate limiter helpers.",
+      required: true,
+    },
+    "@inth/docs/search/node": {
+      type: "build time",
+      description: "Node-only `generateSearchIndex` helper that reads converted markdown and writes `docs/search-index.json`.",
+      required: true,
+    },
+    "@inth/docs/search/ai": {
+      type: "runtime",
+      description: "Vercel AI SDK `streamText` wrapper for source-grounded plain text answer streams.",
+    },
+  }}
+/>
+
+## Build the Index
+
+Run conversion first, then generate the search index from markdown:
+
+```ts
+import { generateSearchIndex } from "@inth/docs/search/node";
+
+await generateSearchIndex({
+  outDir: "public",
+  baseUrl: "https://docs.example.com",
+});
+```
+
+The generated index is static JSON. In the demo app, `scripts/search-generate.ts` copies it into `src/generated/docs-search-index.json` so routes can import it without reading from the file system at request time.
+
+## Runtime Search
+
+Import the generated JSON and query it from your own route handler:
+
+```ts
+import { searchDocs, type DocsSearchIndex } from "@inth/docs/search";
+import indexJson from "./generated/docs-search-index.json";
+
+const results = searchDocs(indexJson as DocsSearchIndex, "package tabs");
+```
+
+Search results include `urlWithHash` and `absoluteUrlWithHash` so the UI can link directly to the matched heading. The demo renders matching heading `id`s with `slugifyDocsHeading`.
+
+## AI Answers
+
+Use `streamDocsAnswer` when you want a simple Vercel AI SDK integration:
+
+```ts
+import { streamDocsAnswer } from "@inth/docs/search/ai";
+
+const { response } = streamDocsAnswer({
+  index,
+  query,
+  model: process.env.DOCS_SEARCH_MODEL ?? "moonshotai/kimi-k2.6",
+  productName: "@inth/docs",
+});
+```
+
+The answer prompt only includes retrieved docs context, tells the model to cite sources, and asks it to say when the docs do not contain enough context.
+
+## Abuse Protection
+
+<Steps>
+  <Step title="Search is cheap">
+    Debounced typing should call only the local `/api/docs/search` route. It does not call the model.
+  </Step>
+  <Step title="Answers are explicit">
+    Keep model calls behind a button such as `Ask`, `Enter to ask`, or `Cmd+Enter`.
+  </Step>
+  <Step title="Limit request paths">
+    Use `validateDocsQuery`, `readJsonWithLimit`, `getClientIdentifier`, and a `RateLimiter` implementation around public routes.
+  </Step>
+</Steps>
+
+The demo uses an in-memory limiter for local smoke coverage. Production apps should adapt the same `RateLimiter` interface to a shared store such as Redis, Vercel KV, Cloudflare KV, or Durable Objects.

apps/docs-smoke/package.json

@@ -16,7 +16,8 @@
     "bench": "bun run pipeline:bench",
     "pipeline:convert": "bun run scripts/mdx-convert.ts",
     "pipeline:llm": "bun run scripts/llm-generate.ts",
-    "pipeline:build": "bun run pipeline:convert && bun run pipeline:llm",
+    "pipeline:search": "bun run scripts/search-generate.ts",
+    "pipeline:build": "bun run pipeline:convert && bun run pipeline:llm && bun run pipeline:search",
     "pipeline:test": "bun run scripts/test-pipeline.ts",
     "pipeline:setup-real": "bun run scripts/setup-real-content.ts",
     "pipeline:test-real": "bun run pipeline:setup-real && bun run scripts/test-real.ts",
@@ -33,6 +34,7 @@
     "@radix-ui/react-slot": "^1.2.3",
     "@tanstack/react-router": "^1.167.4",
     "@tanstack/react-start": "^1.166.15",
+    "ai": "^6.0.168",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "nitro": "3.0.260415-beta",

apps/docs-smoke/scripts/mdx-convert.ts

@@ -19,8 +19,9 @@ import {
 
 const scriptsRoot = dirname(fileURLToPath(import.meta.url));
 const repoRoot = join(scriptsRoot, "..", "..");
-const srcDir = join(scriptsRoot, "content");
-const outDir = join(scriptsRoot, "public");
+const appRoot = join(scriptsRoot, "..");
+const srcDir = join(appRoot, "content");
+const outDir = join(appRoot, "public");
 const typeTableRemarkPlugin: NonNullable<
   MdxToMarkdownConfig["remarkPlugins"]
 >[number] = [remarkTypeTableToMarkdown, { basePath: repoRoot }];

apps/docs-smoke/scripts/search-generate.ts

@@ -0,0 +1,27 @@
+#!/usr/bin/env bun
+/**
+ * Generates a static docs search index from converted markdown.
+ */
+
+import { copyFile, mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { generateSearchIndex } from "../../../packages/docs/src/search/node-index.ts";
+
+const scriptsRoot = dirname(fileURLToPath(import.meta.url));
+const appRoot = join(scriptsRoot, "..");
+const outDir = join(appRoot, "public");
+const generatedDir = join(appRoot, "src", "generated");
+const generatedIndexPath = join(generatedDir, "docs-search-index.json");
+
+const result = await generateSearchIndex({
+  outDir,
+  baseUrl: "https://docs.example.com",
+});
+
+await mkdir(generatedDir, { recursive: true });
+await copyFile(result.outputPath, generatedIndexPath);
+
+process.stdout.write(
+  `Search index generated: ${result.docs} docs, ${result.chunks} chunks, ${result.terms} terms\n`
+);