@savvy-web/mcp 1.3.3 → 1.3.4

package/README.md

@@ -42,7 +42,7 @@ npx @modelcontextprotocol/inspector savvy-mcp .
 ## Tools
 
 - `workspace_info` — returns a flat, structured projection of the workspace analysis: linked and fixed package groups as name arrays plus resolved registry targets. Backed by the same `silk-effects` analyzer the `savvy` CLI uses.
-- `silk_docs_search` — ranks documents in the corpus against a plain keyword or phrase query and returns hits with a normalized confidence score plus a high/medium/low label. It never returns empty: when nothing matches, it falls back to the priority-ordered top results.
+- `silk_docs_search` — ranks documents in the corpus against a plain keyword or phrase query and returns hits with a normalized confidence score plus a high/medium/low label. A query that matches nothing returns an empty result set, pointing the agent at `silk://catalog` to choose a doc by reasoning.
 - `turbo_inspect` — read-only Turborepo inspection over `turbo --dry`: diagnose a task's per-package cache hits, derive the task graph or list the packages affected by recent changes. It never runs a task. Backed by the same `silk-effects` `Turbo` inspector an agent would otherwise drive by hand.
 - `changeset_inspect` — read-only changeset analysis for release work: `mode=branch` diffs the current branch against its base and attributes every changed file to its owning package, `mode=config` surfaces the resolved `.changeset/config.json` with its release surfaces, version files and ignore list, and `mode=classify` reports how the branch's pending changesets classify each package's bump. It never writes a changeset. Backed by the same `silk-effects` changeset services the `savvy` CLI uses.
 - `changeset_validate` — read-only validation of the files in a changeset directory against the section-aware rules, returning typed diagnostics (file, rule, line, column, message) plus an ok flag and error count. Use it instead of shelling out to `savvy changeset lint`.
@@ -56,7 +56,7 @@ The server exposes a curated markdown corpus behind the `silk://` URI scheme:
 - `silk://catalog` — a single fixed resource listing every document grouped by tier with a "load when …" hint. The agent's mandated first read.
 - `silk://{+path}` — a template resolving any document by its stable id, covering Silk development standards (`silk://standards/<topic>`), per-package API and usage docs (`silk://packages/<pkg>/<topic>`) and conceptual guides (`silk://guides/<slug>`).
 
-Per-package API-reference docs under `silk://packages/<pkg>/api/*` are generated from API Extractor models and shipped with the package.
+Per-package API-reference docs under `silk://packages/<pkg>/api/*` are generated from API Extractor models and shipped with the package, with a bare `silk://packages/<pkg>/api` index page listing each package's symbols.
 
 ## License
 

package/index.d.ts

@@ -77,7 +77,7 @@ declare class DocIndex {
   private constructor();
   static fromManifest(manifest: Manifest, bodies: Readonly<Record<string, string>>): DocIndex;
   search(query: string, opts?: SearchOptions): SearchResult[];
-  /** Never return empty: surface the top entries (by priority) as low-confidence. */
+  /** Browse fallback: surface the top entries (by priority) as low-confidence. */
   private fallback;
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@savvy-web/mcp",
-	"version": "1.3.3",
+	"version": "1.3.4",
 	"private": false,
 	"description": "The savvy MCP server — Silk Suite tooling and library knowledge for coding agents",
 	"homepage": "https://github.com/savvy-web/systems/tree/main/packages/mcp",
@@ -36,7 +36,7 @@
 		"@effect/rpc": "^0.75.1",
 		"@effect/sql": "^0.51.1",
 		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@savvy-web/silk-effects": "1.5.0",
+		"@savvy-web/silk-effects": "1.5.1",
 		"effect": "^3.21.4",
 		"fuse.js": "^7.4.0",
 		"workspaces-effect": "^1.2.0",

package/public/content/guides/api-docs-from-api-extractor.md

@@ -1,12 +1,12 @@
 ---
 id: guides/api-docs-from-api-extractor
 title: Generating API docs from API Extractor
-summary: Configure apiModel, build the model, and render LLM-lean markdown with api-extractor-llms.
+summary: Configure the meta option, build the model, and render LLM-lean markdown with api-extractor-llms.
 tier: guides
 source: hand
 tags: [api, build]
 priority: 0.5
-related: [standards/api-model-pipeline, packages/rslib-builder/overview]
+related: [standards/api-model-pipeline, packages/bundler/overview]
 ---
 
 ## Overview
@@ -19,30 +19,38 @@ This guide walks through each stage as implemented in this repo.
 For the policy contract (what is generated, what must not be edited, where docs
 land), see `silk://standards/api-model-pipeline`.
 
-## Step 1 — Enable the API model in `rslib.config.ts`
+## Step 1 — Emit the API model from the build
 
-A library package opts in by passing an `apiModel` option to `NodeLibraryBuilder.create()`:
+A library built by `@savvy-web/bundler` emits an API Extractor model on its
+production build by default — there is nothing to enable. The model is controlled
+by the `meta` option in `savvy.build.ts`:
 
 ```typescript
-import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
+import { defineBuild, runBuild } from "@savvy-web/bundler";
 
-export default NodeLibraryBuilder.create({
-  apiModel: {
+const config = defineBuild({
+  // meta omitted → API model is generated with default options on --target prod.
+  // Pass an object only to override defaults, e.g. to register custom TSDoc tags:
+  meta: {
     tsdoc: {
       tagDefinitions: [{ tagName: "@since", syntaxKind: "block" }],
     },
   },
 });
-```
 
-Passing any truthy value for `apiModel` enables model emission. Options under
-`apiModel` are forwarded to the API Extractor TSDoc runner. A plain `apiModel: true`
-works when no custom tag definitions are needed.
+export default config;
 
-The entry point and package name are derived from the package's `exports` field.
-Only public API surfaces are captured; members annotated `@internal` are excluded.
+if (import.meta.main) {
+  await runBuild(config, { cwd: import.meta.dirname, argv: process.argv.slice(2) });
+}
+```
 
-See `silk://packages/rslib-builder/overview` for full builder configuration.
+Omitting `meta` generates the model with defaults; pass `false` to opt out
+entirely (the MCP server itself does this — it is an executable host, not a
+documented API). The entry point and package name are derived from `exports`.
+Only public surfaces are captured; members annotated `@internal` are excluded.
+
+See `silk://packages/bundler/overview` for the full builder surface.
 
 ## Step 2 — Build the model
 
@@ -50,12 +58,12 @@ See `silk://packages/rslib-builder/overview` for full builder configuration.
 pnpm --filter @savvy-web/your-package run build:prod
 ```
 
-The production build writes `dist/npm/<unscoped-name>.api.json`. For example,
-`@savvy-web/silk-effects` emits `dist/npm/silk-effects.api.json`. The filename
-is the unscoped package name with an `.api.json` suffix.
-
-`dist/dev/` may also contain a model depending on the build configuration.
-The generator script probes `dist/dev/` first, then `dist/npm/`.
+The production build writes `dist/prod/npm/meta/<unscoped-name>.api.json` and
+stages a copy into each consumer declared in `meta.localPaths` — for the MCP
+corpus that is `packages/mcp/lib/models/<dir>/<unscoped-name>.api.json`. For
+example, `@savvy-web/silk-effects` emits `silk-effects.api.json`. The generator
+reads the staged copy under `lib/models/`, so its inputs stay inside the mcp
+package and Turborepo can cache it.
 
 ## Step 3 — Render with `api-extractor-llms`
 
@@ -103,11 +111,13 @@ across all consumers.
 
 ## Step 4 — The MCP generator script
 
-`packages/mcp/scripts/generate-api-docs.ts` is the reference implementation of
+`packages/mcp/lib/scripts/generate-api-docs.ts` is the reference implementation of
 steps 3 and 4 for the MCP resource corpus. It iterates `API_TARGETS` (defined in
-`packages/mcp/scripts/api-targets.ts`), loads each model, injects silk-specific
-frontmatter and `silk://` crosslink routes, and writes output under
-`content/packages/<dir>/api/<kind>/<slug>.md` (gitignored).
+`packages/mcp/lib/scripts/api-targets.ts`), loads each model, injects silk-specific
+frontmatter and `silk://` crosslink routes, writes one page per symbol under
+`public/content/packages/<dir>/api/<kind>/<slug>.md`, and writes a per-package
+index page at `public/content/packages/<dir>/api.md` (served at the bare
+`silk://packages/<dir>/api` URI).
 
 ```typescript
 // The silk crosslink scheme
@@ -125,20 +135,24 @@ const docs = renderPackage(pkg, {
 ```
 
 Current targets (from `api-targets.ts`): `silk-effects`, `templates`,
-`github-action-effects`, `github-action-builder`. The MCP package itself and `cli`/`silk`
-are excluded (a generate→mcp build dependency would create a Turborepo cycle; cli
-and silk are not library APIs).
+`github-action-effects`, `github-action-builder`, `bundler`, `tsdown-plugins`,
+`rspress-builder`. The MCP package itself and `cli`/`silk` are excluded (a
+generate→mcp build dependency would create a Turborepo cycle; cli and silk are
+not library APIs).
 
 ## Step 5 — Compile into the corpus
 
 After `generate-api-docs.ts` writes the markdown files, `build:catalog` picks them
 up along with hand-authored docs and compiles the unified manifest. Generated docs
-appear in `silk://catalog` marked `(generated)`.
+appear in `silk://catalog` marked `(generated)`. The rendered markdown and the
+inflated manifest are committed tracked source — only the raw `.api.json` models
+under `lib/models/` are gitignored — so the published package ships the corpus
+even though a release machine does not regenerate it.
 
 In Turborepo the pipeline is:
 
 ```text
-build:prod (each library) → generate-api-docs → build:catalog
+build:prod (each library) → generate-api-docs → build:catalog → mcp build:prod
 ```
 
 ## Authoring notes
@@ -149,12 +163,12 @@ build:prod (each library) → generate-api-docs → build:catalog
   `silk://packages/foo/api/class/myservice`.
 - Cross-links in prose (`{@link OtherClass}`) resolve only if `OtherClass` is in
   the same package's rendered set.
-- Do not edit generated files under `content/packages/*/api/` — changes are
-  overwritten on the next `generate-api-docs` run.
+- Do not hand-edit files under `public/content/packages/*/api/` (or the `api.md`
+  index) — they are overwritten on the next `generate-api-docs` run; change the
+  source TSDoc instead.
 
 ## See also
 
 - `silk://standards/api-model-pipeline` — policy: what is generated, provenance
   markers, coverage scope
-- `silk://packages/rslib-builder/overview` — configuring the builder that emits
-  the model
+- `silk://packages/bundler/overview` — configuring the builder that emits the model

package/public/content/guides/building-a-github-action.md

@@ -24,8 +24,8 @@ Neither package depends on the other at build time. The builder bundles whatever
 action code you write; the effects library provides the services that code uses.
 
 For choosing the right builder, see `silk://guides/choosing-a-builder`. The
-github-action-builder is separate from rslib-builder and bun-builder — it targets
-a different output shape (single-file committed ESM bundles, not npm-published
+github-action-builder is separate from the library bundler — it targets a
+different output shape (single-file committed ESM bundles, not npm-published
 libraries).
 
 ## Step 1 — Project structure

package/public/content/guides/choosing-a-builder.md

@@ -1,140 +1,93 @@
 ---
 id: guides/choosing-a-builder
-title: Choosing a builder (rslib vs bun)
-summary: When to reach for @savvy-web/rslib-builder vs @savvy-web/bun-builder for a Silk package.
+title: Choosing a builder
+summary: When to reach for @savvy-web/bundler, @savvy-web/rspress-builder, or @savvy-web/github-action-builder for a Silk package.
 tier: guides
 source: hand
 tags: [build]
 priority: 0.5
-related: [packages/rslib-builder/overview]
+related: [packages/bundler/overview, guides/building-a-github-action]
 ---
 
 ## Overview
 
-The Silk Suite has two zero-config build tools for TypeScript libraries:
+The Silk Suite has three zero-config build tools, each targeting a different
+output shape. Pick by what the package produces, not by personal preference.
 
-| Package | Bundler core | Primary target |
+| Package | Builds | Output |
 | --- | --- | --- |
-| `@savvy-web/rslib-builder` | rsbuild / rspack | Node.js (pnpm monorepos) |
-| `@savvy-web/bun-builder` | Bun.build() | Bun monorepos |
-
-Both tools auto-detect entry points from `package.json` `exports`, emit `dist/dev/`
-and `dist/npm/` build modes, generate rolled-up `.d.ts` declarations via API
-Extractor, resolve `catalog:` and `workspace:` protocol references for publishing,
-and transform the output `package.json` for publish readiness.
-
-## `@savvy-web/rslib-builder`
-
-The **ecosystem default** for packages inside the `savvy-web/systems` monorepo and
-any pnpm-managed Silk Suite package.
-
-### What it does
-
-- Zero-config builds via `NodeLibraryBuilder.create({})` in `rslib.config.ts`
-- Reads `exports` to discover entry points; builds `dist/dev/` and `dist/npm/`
-- Generates type declarations and emits a Microsoft API Extractor model
-  (`<unscoped>.api.json`) on the npm build
-- Transforms the output `package.json`: resolves `pnpm catalog:` references,
-  flips `private: true` to publish-ready based on `publishConfig.access`, rewrites
-  export paths from `.ts` to `.js`, adds type conditions
-- Supports dual-format ESM+CJS builds when needed (e.g. `@savvy-web/silk` for CJS
-  consumers)
-- Peer dependencies: `@rslib/core`, `@typescript/native-preview`
-
-### Configuration
-
-```typescript
-import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
-
-export default NodeLibraryBuilder.create({
-  externals: ["effect", "@effect/platform"],
-  apiModel: {
-    tsdoc: {
-      tagDefinitions: [{ tagName: "@since", syntaxKind: "block" }],
-    },
-  },
-});
-```
-
-Pass `apiModel: true` (or an options object) to enable API Extractor model
-emission. See `silk://packages/rslib-builder/overview` for full details.
-
-### When to use it
+| `@savvy-web/bundler` | TypeScript libraries | npm-published `dist/dev` + `dist/prod` |
+| `@savvy-web/rspress-builder` | RSPress doc-site plugins | npm-published plugin package |
+| `@savvy-web/github-action-builder` | Node.js 24 GitHub Actions | committed single-file ESM bundles |
 
-- You are building a package inside `savvy-web/systems` (or a pnpm-based Silk repo)
-- You need dual-format ESM+CJS output
-- You want API Extractor model emission for MCP doc generation
-- The package uses `pnpm catalog:` or `workspace:` protocol in its dependencies
+All three auto-detect their inputs, emit a transformed publish-ready
+`package.json` where applicable, and resolve `catalog:` and `workspace:` protocol
+references. They differ in what they emit and how it is consumed.
 
-## `@savvy-web/bun-builder`
+## `@savvy-web/bundler`
 
-For **Bun-managed monorepos** where Bun.build() is the preferred bundler.
+The **default** for any TypeScript library inside `savvy-web/systems` (or any
+pnpm-managed Silk Suite package). It is the tsdown-based build orchestrator: it
+reads `exports` to discover entry points, builds `dist/dev/` and per-target
+`dist/prod/<target>/`, emits a bundled self-contained `.d.ts` per public entry,
+and on `--target prod` emits an API Extractor model for MCP and website doc
+generation.
 
-### What it does
+A package opts in with a self-executing `savvy.build.ts` that calls `defineBuild`
+and `runBuild`, with `node savvy.build.ts --target dev` / `--target prod` build
+scripts. See `silk://packages/bundler/overview` for the full surface.
 
-- Zero-config builds via `BunLibraryBuilder.create({})` in `bun.config.ts`
-- Auto-detects entry points from `package.json` `exports`
-- Bundled or bundleless output (`bundle: false` preserves source structure)
-- Rolled-up `.d.ts` in bundled mode; raw `.d.ts` in bundleless mode
-- API Extractor model generation on npm builds (enabled by default)
-- TSDoc warnings reported with source locations; severity configurable per
-  environment (`"fail"` in CI, `"log"` locally)
-- Resolves Bun `catalog:` and `workspace:` protocol references for publishing
-- Peer dependencies: `@microsoft/api-extractor`, `@typescript/native-preview`,
-  `typescript`, `@types/bun`
+### When to use it
 
-### Configuration
+- You are building a library inside `savvy-web/systems` (or a pnpm-based Silk repo)
+- You publish to npm and want bundled type declarations
+- You want API Extractor model emission for MCP doc generation
+- The package uses `pnpm catalog:` or `workspace:` protocol in its dependencies
 
-```typescript
-import { BunLibraryBuilder } from "@savvy-web/bun-builder";
+## `@savvy-web/rspress-builder`
 
-export default BunLibraryBuilder.create({
-  bundle: true,       // default; set false for bundleless
-  apiModel: true,     // default; emits model on npm build
-});
-```
+A thin sibling to the bundler for **RSPress documentation-site plugins**. It
+applies the same entry-point discovery and publish transform, tuned for the
+shape an RSPress plugin package ships. Reach for it only when the package is an
+RSPress plugin; for every other library, use the bundler.
 
-Build via:
+## `@savvy-web/github-action-builder`
 
-```bash
-bun run bun.config.ts              # all modes
-bun run bun.config.ts --env-mode dev
-bun run bun.config.ts --env-mode npm
-```
+For **Node.js 24 GitHub Actions**, whose output is a different shape entirely:
+self-contained ESM bundles committed to the repository (not an npm package) so a
+runner can execute them directly. It bundles `src/main.ts` (plus optional
+`pre.ts`/`post.ts`) into flat `dist/*.js` files and validates `action.yml`. See
+`silk://guides/building-a-github-action`.
 
 ### When to use it
 
-- You are in a Bun-managed workspace (`bun.lock`, Bun catalog protocol)
-- You want sub-second build iteration times
-- You do not need rspack's CJS-to-ESM interop (which is important for certain
-  bundled GitHub Actions scenarios)
+- You are building a GitHub Action, not a published library
+- The output must be a committed single-file bundle referenced from `action.yml`
 
 ## Decision guide
 
 ```text
-Is this a package in savvy-web/systems (pnpm monorepo)?
-  Yes → rslib-builder
-
-Does the package need dual-format ESM+CJS output?
-  Yes → rslib-builder
+Is the package a GitHub Action (committed Node.js 24 bundle)?
+  Yes → github-action-builder
 
-Is this a Bun-managed workspace?
-  Yes → bun-builder
+Is the package an RSPress doc-site plugin?
+  Yes → rspress-builder
 
-Are you building a GitHub Action (bundled Node.js 24 binary)?
-  Use @savvy-web/github-action-builder instead — see silk://guides/building-a-github-action
+Otherwise (any npm-published TypeScript library)
+  → bundler
 ```
 
 ## Common pitfalls
 
-**rslib-builder:** Relative imports inside source must use `.js` extensions
-(ESM requirement). The build will report "cannot find module" on missing extensions.
+**bundler / rspress-builder:** Relative imports inside source must use `.js`
+extensions (the ESM requirement). The build reports "cannot find module" on a
+missing extension.
 
-**bun-builder:** The Bun catalog protocol uses `workspaces.catalog` in the root
-`package.json`, distinct from pnpm's catalog. Do not mix the two in the same
-workspace.
+**github-action-builder:** The `dist/` bundle must be committed so GitHub runners
+can execute it; `action.yml` must declare `runs.using: "node24"`.
 
 ## See also
 
-- `silk://packages/rslib-builder/overview` — full rslib-builder reference
+- `silk://packages/bundler/overview` — the library build front door in full
 - `silk://guides/building-a-github-action` — GitHub Actions use a separate builder
+- `silk://standards/api-model-pipeline` — how the bundler's prod API model becomes docs