Add compact docs search and AI answers

.agents/skills/inth-docs/SKILL.md

@@ -22,10 +22,10 @@ Use the packaged agent docs as reference data. Prefer the installed package copy
 
 Start with `docs/llms.txt`, then open the smallest matching topic page:
 
-- `components.md` for `mdxComponents`, `PackageCommandTabs`, `TypeTable`, and MDX rendering.
-- `convert.md` for `convertMdxFile`, `convertSingleMdxFile`, and `convertAllMdx`.
+- `components.md` for `mdxComponents`, `CommandTabs`, `TypeTable`, `ExtractedTypeTable`, and MDX rendering.
+- `convert.md` for `convertMdxToMarkdown`, `writeMdxFileAsMarkdown`, and `convertAllMdx`.
 - `remark.md` for `defaultRemarkPlugins`, `remarkInclude`, and plugin ordering.
-- `llm.md` for `generateLLMSummaries`, `generateLLMFullFiles`, and topic design.
+- `llm.md` for `generateLlmsTxt`, `generateLLMFullContextFiles`, and topic design.
 - `lint.md` for `lintDocs`, schema overrides, and `inth-docs-lint`.
 
 Open `docs/llms-full.txt` only when the summary page is insufficient.

README.md

@@ -1,13 +1,17 @@
 # @inth/docs
 
-Shared MDX-to-markdown tooling for Inth docs properties.
+Shared docs tooling for Inth docs projects: React MDX rendering, MDX-to-markdown conversion, LLM bundles, validation, and static search.
 
-`@inth/docs` is split into five main surfaces:
+`@inth/docs` is split into focused public entry points:
 
 - `@inth/docs`: React MDX component adapters via `mdxComponents`
 - `@inth/docs/remark`: remark plugins plus `defaultRemarkPlugins`
 - `@inth/docs/convert`: MDX-to-markdown conversion APIs
 - `@inth/docs/llm`: `llms.txt` and topic-scoped full-context generation
+- `@inth/docs/search`: edge-safe search runtime, content readers, guards, and rate limiter helpers
+- `@inth/docs/search/node`: Node-only search index generation
+- `@inth/docs/search/ai`: AI SDK answer streaming helper
+- `@inth/docs/search/bash`: optional bash-tool docs inspection adapter
 - `@inth/docs/lint`: docs validation and the `inth-docs-lint` CLI
 
 ## Install
@@ -34,7 +38,7 @@ The repo includes a canonical consumer demo at `apps/docs-smoke`.
 
 - Renders real `.mdx` fixture files through the package's exported `mdxComponents`.
 - Uses TanStack Start for SSR and hydration coverage.
-- Shows extracted `AutoTypeTable` output while keeping pipeline fixtures in the validation path.
+- Shows extracted `ExtractedTypeTable` output while keeping pipeline fixtures in the validation path.
 
 Local workflow:
 
@@ -54,9 +58,24 @@ bun run --filter docs-smoke test:e2e
 Validation layers:
 
 - Package unit tests in `packages/docs/src/**/*.test.ts*` cover component semantics and pure library behavior.
-- Pipeline fixtures in `apps/docs-smoke/scripts` and `apps/docs-smoke/content` cover MDX conversion, LLM generation, and `AutoTypeTable`.
+- Pipeline fixtures in `apps/docs-smoke/scripts` and `apps/docs-smoke/content` cover MDX conversion, LLM generation, and `ExtractedTypeTable`.
 - The TanStack Start demo app in `apps/docs-smoke/src` covers real browser rendering and hydration.
 
+## Where This Fits
+
+`@inth/docs` is not a hosted docs platform or a complete docs-site framework. Use tools such as Mintlify, Fumadocs, or Starlight when the primary job is shipping a polished docs website quickly.
+
+Use this package when the primary job is shared docs infrastructure: MDX rendering adapters, MDX-to-markdown conversion, LLM bundles, linting, static search artifacts, answer helpers, and agent-facing docs output that can feed multiple apps and tools.
+
+## Wiring It Into An App
+
+In a c15t-style repo with a top-level `docs/` directory, wire `@inth/docs` into the docs app and docs scripts:
+
+- The docs app imports `mdxComponents` only if it renders MDX directly.
+- A conversion script runs `convertAllMdx({ srcDir: process.cwd(), outDir: "public" })`.
+- LLM and search scripts read the converted markdown under `public/docs/`.
+- Product code does not import `@inth/docs` unless it also renders docs pages.
+
 ### Convert MDX to markdown
 
 ```ts
@@ -73,7 +92,7 @@ await convertAllMdx({
 ### Generate agent-facing docs bundles
 
 ```ts
-import { generateLLMFullFiles, generateLLMSummaries } from "@inth/docs/llm";
+import { generateLLMFullContextFiles, generateLlmsTxt } from "@inth/docs/llm";
 ```
 
 Run the packaged agent-doc generator locally with:
@@ -84,6 +103,19 @@ INTH_DOCS_AGENT_BASE_URL=https://docs.example.com/@inth/docs bun run docs:agent
 
 This writes a bundled reference set into `packages/docs/agent-docs/`.
 
+### Generate a static search index
+
+```ts
+import { generateDocsSearchFiles } from "@inth/docs/search/node";
+
+await generateDocsSearchFiles({
+  outDir: "public",
+  baseUrl: "https://docs.example.com",
+});
+```
+
+At runtime, query the generated JSON with `@inth/docs/search`. Add `@inth/docs/search/ai` only when a user explicitly asks for a source-grounded answer.
+
 ## Agent Docs
 
 The package now ships a small, topic-scoped agent reference bundle:
@@ -93,6 +125,7 @@ The package now ships a small, topic-scoped agent reference bundle:
 - `agent-docs/docs/convert.md`
 - `agent-docs/docs/remark.md`
 - `agent-docs/docs/llm.md`
+- `agent-docs/docs/search.md`
 - `agent-docs/docs/lint.md`
 
 Set `INTH_DOCS_AGENT_BASE_URL` to the hosted docs base before generating publishable `llms*.txt` files.

apps/docs-smoke/.gitignore

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

apps/docs-smoke/content/docs/guides/components-fixture.mdx

@@ -1,70 +1,58 @@
 ---
-title: "Components Fixture"
-description: "Render the runtime-facing adapters from @inth/docs in one browser route."
+title: "Runtime Components"
+description: "Render the browser-facing @inth/docs adapters through authored MDX."
 ---
 
-# Components Fixture
+# Runtime Components
 
 <Callout variant="success" title="Runtime fixture">
-  This page intentionally exercises the browser-facing adapters without replacing them with shadcn variants.
+  This page exercises the exported MDX adapters without replacing them with app-local variants.
 </Callout>
 
-## Authoring Example
+## Authoring Contract
 
 ```mdx
 <Callout variant="success" title="Runtime fixture">
-  Render the exported adapters through your shared `mdxComponents` map.
+  Render exported adapters through your shared `mdxComponents` map.
 </Callout>
 
-<PackageCommandTabs command="{pm} add @inth/docs" />
+<CommandTabs command="@inth/docs" mode="install" />
+
+<CommandTabs command="next-app" mode="create" />
 
 <Tabs items={["Overview", "Types"]}>
   <Tab value="Overview">Tabs hydrate in the browser.</Tab>
-  <Tab value="Types">Use `TypeTable` when the type data already exists in MDX.</Tab>
+  <Tab value="Types">Use `TypeTable` when type data already exists in MDX.</Tab>
 </Tabs>
 
 <Mermaid chart={`flowchart LR
   A[MDX] --> B[mdxComponents]
   B --> C[Rendered route]
 `} />
-
-<TypeTable
-  type={{
-    command: {
-      type: "string",
-      description: "Command template with a {pm} placeholder.",
-      required: true,
-    },
-  }}
-/>
-
-<AutoTypeTable
-  name="PipelineExampleOptions"
-  path="./apps/docs-smoke/type-fixtures/pipeline-example.ts"
-  type={pipelineExampleType}
-/>
 ```
 
-`AutoTypeTable` still needs extracted `type` data from the route or conversion pipeline. This demo renders that extracted output on `/docs`.
+## Navigation Cards
 
 <Cards>
-  <Card title="Quickstart route" description="Internal docs route rendered by the package card component." href="/docs/guides/quickstart" />
-  <Card title="External reference" description="External links should preserve safe target and rel attributes." href="https://example.com/docs" />
+  <Card title="Quickstart route" description="Implementation steps for installing, rendering, converting, and validating." href="/docs/guides/quickstart" />
+  <Card title="External reference" description="External links preserve safe target and rel attributes." href="https://example.com/docs" />
 </Cards>
 
+## Browser Flow
+
 <Steps>
   <Step title="Author MDX">
-    Start with semantic components such as `Callout`, `Tabs`, `Cards`, and `TypeTable`.
+    Use semantic components such as `Callout`, `Tabs`, `Cards`, `Steps`, `CommandTabs`, and `TypeTable`.
   </Step>
-  <Step title="Render in TanStack Start">
+  <Step title="Render in the app">
     Import the `.mdx` file directly and provide `mdxComponents` through the shared runtime map.
   </Step>
-  <Step title="Validate separately">
-    Keep `AutoTypeTable` in pipeline coverage where source extraction actually happens.
+  <Step title="Validate the pipeline separately">
+    Keep `ExtractedTypeTable` coverage in the conversion pipeline where source extraction has a stable file-system base path.
   </Step>
 </Steps>
 
-<PackageCommandTabs command="{pm} add @inth/docs" />
+<CommandTabs command="@inth/docs" mode="install" />
 
 <Tabs items={["Overview", "Tables", "Pipeline note"]}>
   <Tab value="Overview">
@@ -74,25 +62,29 @@ description: "Render the runtime-facing adapters from @inth/docs in one browser
     `TypeTable` is safe to render live because all of its data is already present in the MDX payload.
   </Tab>
   <Tab value="Pipeline note">
-    `AutoTypeTable` is not shown live here because extraction depends on a stable build-time file system base path.
+    `ExtractedTypeTable` is rendered on `/docs` with extracted type data and verified in `content/docs/guides/extracted-type-table-fixture.mdx`.
   </Tab>
 </Tabs>
 
 <Mermaid chart={`flowchart LR
-  A[MDX fixture] --> B[mdxComponents]
+  A[Authored MDX] --> B[mdxComponents]
   B --> C[TanStack Start route]
   C --> D[Playwright coverage]
 `} />
 
 <TypeTable
-  type={{
+  properties={{
     command: {
       type: "string",
-      description: "Command template with a {pm} placeholder.",
+      description: "Package name, CLI name, or custom command template with a {pm} placeholder.",
       required: true,
     },
+    mode: {
+      type: "\"install\" | \"run\" | \"create\"",
+      description: "Optional expansion mode for package names, CLI names, or project starters such as `pnpm create next-app`.",
+    },
     commands: {
-      type: "Record<PackageManager, string>",
+      type: "Partial<Record<PackageManager, string>>",
       description: "Explicit per-manager overrides when templates are not enough.",
     },
     defaultManager: {
@@ -103,6 +95,6 @@ description: "Render the runtime-facing adapters from @inth/docs in one browser
   }}
 />
 
-<Callout variant="canary" title="Pipeline-only coverage">
-  `AutoTypeTable` is verified by the markdown conversion fixture at `content/docs/guides/auto-type-table-fixture.mdx` and by the dedicated pipeline test script.
+<Callout variant="canary" title="Pipeline-only extraction">
+  `ExtractedTypeTable` needs extracted type data. The live extracted output appears on `/docs`, and the pipeline fixture verifies markdown output from `PipelineExampleOptions`.
 </Callout>

apps/docs-smoke/content/docs/guides/auto-type-table-fixture.mdx → apps/docs-smoke/content/docs/guides/extracted-type-table-fixture.mdx

@@ -1,11 +1,11 @@
 ---
-title: "AutoTypeTable Fixture"
+title: "ExtractedTypeTable Fixture"
 description: "Pipeline-only fixture for type extraction coverage."
 ---
 
-# AutoTypeTable Fixture
+# ExtractedTypeTable Fixture
 
-<AutoTypeTable
+<ExtractedTypeTable
   name="PipelineExampleOptions"
   path="./apps/docs-smoke/type-fixtures/pipeline-example.ts"
 />