@savvy-web/mcp 0.1.0

package/resources/content/guides/llm-friendly-json-schemas.md

@@ -0,0 +1,64 @@
+---
+id: guides/llm-friendly-json-schemas
+title: LLM-friendly JSON Schemas for tool outputs
+summary: Load when designing the output schema of an MCP tool or a GitHub Action.
+tier: guides
+source: hand
+tags: [mcp]
+priority: 0.5
+related: [packages/mcp/resource-taxonomy]
+---
+
+A coding agent consumes a tool's structured output by reading it, not by running a
+parser against it. The schema you choose is a prompt: it decides how reliably the
+model can locate a value, follow a reference, and reason about what it got back.
+Read this when designing a new MCP tool's output schema or a GitHub Action's
+`outputs`, where the same constraints apply.
+
+## Prefer flat, named fields over deep nesting
+
+A model retrieves a value by following a path it has to hold in working memory.
+`result.targets[0].registry` is harder to reference reliably than a flat
+`registries: string[]`. Keep the shape shallow. When you must nest, name every
+level with a descriptive key rather than relying on positional structure, so the
+path reads like prose.
+
+## Avoid recursive and open-ended shapes
+
+A schema that can nest itself arbitrarily (a tree of the same node type) forces the
+model to track depth it cannot see. Where the domain is genuinely recursive,
+flatten it: emit a list of nodes plus a parent-id field rather than a literal tree.
+
+## Use enums and literals for closed sets
+
+When a field can only take a handful of values, type it as a union of literals, not
+an open string. An enum tells the model the complete option set up front, which
+both narrows its generation and lets it reason exhaustively ("if not `public`, then
+`restricted`"). This mirrors how the Silk schemas type `access` as
+`"public" | "restricted"` and `tier` as `standards | packages | guides`.
+
+## Collapse relations to identifier arrays
+
+Do not inline a related entity's full record where a reference will do. Emit an
+array of stable identifiers (the `related: string[]` pattern in the resource
+corpus) and let the consumer fetch the target if it needs more. This keeps each
+payload small and the relationship explicit, and it survives the related record
+changing shape.
+
+## Pair the structured payload with a short human-readable summary
+
+A model orients faster on one sentence than on a field-by-field scan. Return both:
+the structured object for precise extraction, and a brief natural-language summary
+for orientation. The MCP tools in this ecosystem follow this dual-channel
+convention — a structured result alongside a lean markdown transcript — so the
+agent gets a fast "what is this" read and an exact "what are the values" read from
+the same call.
+
+## Putting it together
+
+When you sketch a new output schema, ask: can the model name every value in one
+short path; is every closed set an enum; are relations references rather than
+inlined records; and is there a one-line summary to orient on? If so, the schema
+is doing its job as a prompt. The resource taxonomy
+(`silk://packages/mcp/resource-taxonomy`) applies these same rules to the
+documentation corpus's own front-matter.

package/resources/content/manifest.json

@@ -0,0 +1,490 @@
+{
+	"generatedAt": "2026-06-02T04:03:48.449Z",
+	"entries": [
+		{
+			"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.",
+			"tier": "guides",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"api",
+				"build"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"standards/api-model-pipeline",
+				"packages/rslib-builder/overview"
+			],
+			"uri": "silk://guides/api-docs-from-api-extractor",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "guides/building-a-github-action",
+			"title": "Building a GitHub Action",
+			"summary": "Scaffold a Node.js 24 GitHub Action with @savvy-web/github-action-builder and the github-action-effects services.",
+			"tier": "guides",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"github-actions",
+				"build"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"guides/choosing-a-builder",
+				"standards/api-model-pipeline"
+			],
+			"uri": "silk://guides/building-a-github-action",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"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.",
+			"tier": "guides",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"build"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/rslib-builder/overview"
+			],
+			"uri": "silk://guides/choosing-a-builder",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "guides/llm-friendly-json-schemas",
+			"title": "LLM-friendly JSON Schemas for tool outputs",
+			"summary": "Load when designing the output schema of an MCP tool or a GitHub Action.",
+			"tier": "guides",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"mcp"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/mcp/resource-taxonomy"
+			],
+			"uri": "silk://guides/llm-friendly-json-schemas",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/cli/command-tree",
+			"title": "The savvy command tree",
+			"summary": "Load to orient on what the savvy binary does and how its command groups are organized.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"cli"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/cli/init-and-check",
+				"packages/silk/install-and-setup"
+			],
+			"uri": "silk://packages/cli/command-tree",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/cli/init-and-check",
+			"title": "savvy init and check",
+			"summary": "Load when running or wiring the savvy init/check orchestrators.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"cli",
+				"init"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/cli/command-tree",
+				"packages/silk/install-and-setup"
+			],
+			"uri": "silk://packages/cli/init-and-check",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/mcp/resource-taxonomy",
+			"title": "The silk:// resource taxonomy",
+			"summary": "Load to understand how silk:// docs are addressed, tiered, and discovered.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"mcp"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/silk-effects/"
+			],
+			"uri": "silk://packages/mcp/resource-taxonomy",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/rslib-builder/overview",
+			"title": "rslib-builder overview",
+			"summary": "Load when setting up or understanding the rslib-builder build for a Silk package.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"build"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"standards/catalog-usage",
+				"standards/publishability"
+			],
+			"uri": "silk://packages/rslib-builder/overview",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/silk/export-map",
+			"title": "silk subpath export map",
+			"summary": "Load when wiring a config file to a @savvy-web/silk subpath, or auditing the export map.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"silk"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/silk/install-and-setup"
+			],
+			"uri": "silk://packages/silk/export-map",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/silk/install-and-setup",
+			"title": "Installing @savvy-web/silk",
+			"summary": "Load when installing the Silk dev-tooling system into a consumer repo.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"silk",
+				"init"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/silk/export-map",
+				"packages/cli/init-and-check"
+			],
+			"uri": "silk://packages/silk/install-and-setup",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/silk-effects/",
+			"title": "silk-effects overview",
+			"summary": "Load to orient on the shared Effect library and its service map before diving into a service.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"silk-effects",
+				"effect"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/silk-effects/platform-layers",
+				"packages/silk-effects/managed-section",
+				"standards/publishability"
+			],
+			"uri": "silk://packages/silk-effects/",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/silk-effects/managed-section",
+			"title": "ManagedSection",
+			"summary": "Load when reading, writing, or syncing tool-owned BEGIN/END regions in user-editable files.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"managed-section",
+				"effect"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/silk-effects/",
+				"packages/silk-effects/platform-layers"
+			],
+			"uri": "silk://packages/silk-effects/managed-section",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "packages/silk-effects/platform-layers",
+			"title": "Providing platform layers",
+			"summary": "Load when wiring silk-effects services into a program and deciding which layers to provide.",
+			"tier": "packages",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"silk-effects",
+				"effect"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/silk-effects/",
+				"packages/silk-effects/managed-section"
+			],
+			"uri": "silk://packages/silk-effects/platform-layers",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/api-model-pipeline",
+			"title": "API Extractor as docs source of truth",
+			"summary": "How package API surfaces become generated silk://packages/<pkg>/api docs via API Extractor models.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"api",
+				"build"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"packages/mcp/resource-taxonomy"
+			],
+			"uri": "silk://standards/api-model-pipeline",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/catalog-usage",
+			"title": "Catalog usage",
+			"summary": "Load when adding or pinning a dependency in a Silk Suite package.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"catalog",
+				"dependencies"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.8,
+			"related": [
+				"standards/publishability"
+			],
+			"uri": "silk://standards/catalog-usage",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/changeset-discipline",
+			"title": "Changeset discipline",
+			"summary": "Load when deciding whether a branch needs a changeset and how to author one.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"changeset",
+				"release"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.8,
+			"related": [
+				"packages/silk-effects/",
+				"standards/publishability"
+			],
+			"uri": "silk://standards/changeset-discipline",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/changeset-format",
+			"title": "Changeset file format (CSH001–CSH005)",
+			"summary": "The YAML frontmatter, 13 valid section headings, and CSH001–CSH005 structural rules for changesets.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"changeset"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"standards/changeset-discipline"
+			],
+			"uri": "silk://standards/changeset-format",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/commit-contract",
+			"title": "Silk commit contract",
+			"summary": "Load when composing any conventional commit, amending, squashing, or opening a PR.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"commit",
+				"dco",
+				"tdd"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.8,
+			"related": [
+				"standards/changeset-discipline"
+			],
+			"uri": "silk://standards/commit-contract",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/dependency-conventions",
+			"title": "Dependency conventions",
+			"summary": "When to use catalog:silk vs catalog:silkPeers, and how the pnpm-plugin-silk config dependency pins versions.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"dependencies",
+				"catalog"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"standards/catalog-usage"
+			],
+			"uri": "silk://standards/dependency-conventions",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/linting-conventions",
+			"title": "Linting and formatting",
+			"summary": "Load when writing TypeScript or markdown that must pass Biome and markdownlint.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"lint"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.8,
+			"related": [
+				"standards/test-classification"
+			],
+			"uri": "silk://standards/linting-conventions",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/publishability",
+			"title": "Publishability rules",
+			"summary": "Load when deciding whether a package publishes and how private vs publishConfig interact.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"publishability"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.8,
+			"related": [
+				"packages/silk-effects/",
+				"standards/catalog-usage"
+			],
+			"uri": "silk://standards/publishability",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/semver",
+			"title": "Strict SemVer (no v-prefix)",
+			"summary": "Strict SemVer 2.0.0 everywhere; git tags carry no leading v.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"semver"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.5,
+			"related": [
+				"standards/changeset-discipline"
+			],
+			"uri": "silk://standards/semver",
+			"lastModified": "2026-06-02T03:58:56Z"
+		},
+		{
+			"id": "standards/test-classification",
+			"title": "Test classification",
+			"summary": "Load when naming a test file or wondering why Vitest classifies it as unit, e2e, or int.",
+			"tier": "standards",
+			"source": "hand",
+			"status": "stable",
+			"tags": [
+				"test"
+			],
+			"audience": [
+				"assistant"
+			],
+			"priority": 0.8,
+			"related": [
+				"standards/linting-conventions"
+			],
+			"uri": "silk://standards/test-classification",
+			"lastModified": "2026-06-02T03:58:56Z"
+		}
+	]
+}

package/resources/content/packages/cli/command-tree.md

@@ -0,0 +1,70 @@
+---
+id: packages/cli/command-tree
+title: The savvy command tree
+summary: Load to orient on what the savvy binary does and how its command groups are organized.
+tier: packages
+source: hand
+tags: [cli]
+priority: 0.5
+related: [packages/cli/init-and-check, packages/silk/install-and-setup]
+---
+
+## What
+
+`@savvy-web/cli` owns the `savvy` binary — the single command host for the Silk
+Suite's everyday dev tooling, built on `@effect/cli` + `@effect/platform-node`. It
+carries no business logic of its own: every handler imports its work from
+`@savvy-web/silk-effects`. The binary replaces three standalone bins
+(`savvy-changesets`, `savvy-commit`, `savvy-lint`) with one. It is a `fixed`
+changeset group with `@savvy-web/silk` — they always release together.
+
+## API
+
+The tree is static — no runtime discovery, no contribution manifest, no per-command
+"is the system configured" gate. Commands assume the system is set up (`savvy init`
+sets it up).
+
+```text
+savvy init        orchestrator → changeset · commit · lint init in one pass
+savvy check       orchestrator → runs all three checks
+savvy commit      init · check · hook(session-start · pre-commit-message ·
+                  post-commit-verify · user-prompt-submit)
+savvy changeset   init · check · lint · transform · validate-file · version ·
+                  classify · analyze-branch · release-surface ·
+                  config(show · validate) · deps(detect · regen)
+savvy lint        init · check · fmt(package-json · pnpm-workspace · yaml)
+```
+
+Each group lives under `src/commands/{commit,changeset,lint}/` and exports its
+group command plus named handlers (e.g. `runChangesetInit`). The top-level `init`
+and `check` orchestrators sequence the three tool handlers and short-circuit on
+first failure; the tool handlers are injected so the orchestration logic is
+unit-testable without a runtime. The plugin hooks and skills shell out to these
+subcommands.
+
+## Layer
+
+The runtime layer stack is assembled once in `runCli()` (`src/cli/index.ts`) as the
+union of the three source CLIs' stacks. It uses `provideMerge` (not `provide`) so
+base silk-effects services are both fed to upper services and re-exposed for
+handlers that yield those tags directly, and it hand-wires a minimal workspace
+trio (`WorkspaceRoot`, `WorkspaceDiscovery`, `PackageManagerDetector`) rather than
+the heavier `WorkspacesLive`.
+
+Because the command groups are typed with an `any` R-channel (an Effect/cli
+declaration-emit escape hatch), the type-checker cannot prove `AppLive` supplies
+every required service. The real layer-completeness gate is the **runtime smoke
+tests** that run each command, not `tsgo`. Treat them as the contract when adding a
+command that needs a new service.
+
+## Usage
+
+The `savvy` bin resolves to `src/bin/cli.ts` → `runCli()`. Tools it shells out to
+(`@biomejs/biome`, `husky`, `@commitlint/*`, `@changesets/cli`, `lint-staged`,
+`markdownlint-cli2`) are not direct deps; `@savvy-web/silk` co-installs them as
+peers and pnpm's public-hoist-pattern makes them resolvable.
+
+## Related
+
+Init and check: `silk://packages/cli/init-and-check`. Install surface:
+`silk://packages/silk/install-and-setup`.

package/resources/content/packages/cli/init-and-check.md

@@ -0,0 +1,51 @@
+---
+id: packages/cli/init-and-check
+title: savvy init and check
+summary: Load when running or wiring the savvy init/check orchestrators.
+tier: packages
+source: hand
+tags: [cli, init]
+priority: 0.5
+related: [packages/cli/command-tree, packages/silk/install-and-setup]
+---
+
+## What
+
+`savvy init` and `savvy check` are the top-level orchestrators of the `savvy`
+command tree. `init` is what sets the system up — it runs the changeset, commit,
+and lint `init` handlers in one pass, seeding configs and wiring husky hooks.
+`check` runs all three checks. The rest of the tree (`commit`, `changeset`, `lint`)
+assumes `init` has already run.
+
+## API
+
+Both orchestrators sequence the three per-tool handlers and short-circuit on the
+first failure. They live at `src/commands/init.ts` and `src/commands/check.ts`. The
+per-tool handlers are injected rather than imported inline, so the orchestration
+logic — the sequencing and short-circuit — is unit-testable without standing up the
+full runtime. Per-tool `init` and `check` stay reachable under their namespaces
+(`savvy changeset init`, `savvy lint check`, and so on).
+
+## Layer
+
+`init` and `check` run on the same merged runtime stack as the rest of the tree,
+assembled once in `runCli()`. Because they orchestrate the same handlers the plugin
+hooks call, they are covered by the runtime smoke tests that gate layer
+completeness.
+
+## Usage
+
+```bash
+savvy init     # seed configs + wire husky hooks for changesets, commitlint, lint-staged
+savvy check    # run the changeset, commit, and lint checks; fail on the first violation
+```
+
+`savvy init` is what a consumer runs after installing `@savvy-web/silk`: the
+install pulls the `savvy` bin and the real tools as peers, then `init` seeds the
+configs that reference `@savvy-web/silk/*` and points the husky hooks at `savvy`
+subcommands.
+
+## Related
+
+The full command tree: `silk://packages/cli/command-tree`. The install flow that
+precedes `init`: `silk://packages/silk/install-and-setup`.