@savvy-web/mcp 0.1.0

package/resources/content/packages/mcp/resource-taxonomy.md

@@ -0,0 +1,63 @@
+---
+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
+tags: [mcp]
+priority: 0.5
+related: [packages/silk-effects/]
+---
+
+## What
+
+`@savvy-web/mcp` serves a curated documentation corpus over the `silk://` URI
+scheme. The load-bearing principle is **information lives in the MCP, direction
+lives in the plugins**: the server carries every resource regardless of project,
+and each plugin points an agent at the subset it needs. Docs are markdown files
+with YAML front-matter under three tiers — `standards`, `packages`, `guides`.
+
+## API
+
+Every doc has a stable `id` — the URI suffix, tier-prefixed and slash-separated.
+`silk://<id>` is the address skills hard-code, `related[]` entries point at, and
+the catalog and search return. **The `id` is the contract; the URI derives from
+`id`, not the file path** — a `git mv` or filename tidy never silently breaks an
+inbound link. A directory-index doc uses a trailing-slash id (e.g.
+`packages/silk-effects/`) so its URI resolves to `index.md`.
+
+Front-matter carries `id`, `title`, `summary` (the "is this the doc I need" hook),
+`tier`, `source` (`hand` | `generated`), `status`, `tags` (a controlled
+vocabulary), `priority`, and `related`. The compile step
+(`scripts/build-catalog.ts`) fails the build on any integrity violation: `id`
+uniqueness, the file living under the directory matching its `tier`, every
+`related[]` resolving to a known id, every tag resolving against `tags.json`, the
+per-tier body budget, and a dead-name gate against the pre-rename identifiers.
+
+## Layer
+
+The tier rule: a doc's `tier` MUST equal its top-level content directory, and its
+`id` MUST start with `<tier>/`. `priority` follows a tier-based rubric —
+launch-core ≈ 0.8 (standards), fast-follow ≈ 0.5 (packages, guides), deep reference
+≈ 0.3 — so it is real data and doubles as a search tie-break. Each tier ships a
+one-screen structure template (standards: Rule / Why / Examples / See also;
+package topic: What / API / Layer / Usage / Related).
+
+## Usage
+
+Discovery surfaces, in priority order:
+
+1. `silk://catalog` — token-cheap orientation, grouped by tier, each line a URI +
+   `summary` hint; an agent's first read.
+2. The `silk_docs_search` tool — the primary path, plain-keyword input.
+3. `resources/read` by explicit URI — how skills point precisely.
+4. `resources/list` via one `ResourceTemplate` — fallback enumeration, excluding
+   `silk://catalog`.
+
+The compiler emits `manifest.json`, the single source the catalog, search, and
+`list()` all derive from, so there is no drift. Bodies stay in the markdown files;
+the manifest indexes them.
+
+## Related
+
+The library these docs describe: `silk://packages/silk-effects/`.

package/resources/content/packages/rslib-builder/overview.md

@@ -0,0 +1,68 @@
+---
+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
+tags: [build]
+priority: 0.5
+related: [standards/catalog-usage, standards/publishability]
+---
+
+## What
+
+`@savvy-web/rslib-builder` is a zero-config rsbuild-based build tool for Silk Suite
+TypeScript packages. It reads a package's `exports` field to discover entry points,
+builds dev and production outputs, generates type declarations, and transforms the
+output `package.json` for publishing. A package opts in with a one-line
+`rslib.config.ts`.
+
+## API
+
+```typescript
+import { NodeLibraryBuilder } from "@savvy-web/rslib-builder";
+
+export default NodeLibraryBuilder.create({
+  externals: ["@rslib/core"], // optional: do not bundle these
+});
+```
+
+Entry points come from `package.json` `exports` (e.g. `"."` → `./src/index.ts`,
+`"./utils"` → `./src/utils/index.ts`). Peer dependencies are `@rslib/core` and
+`@typescript/native-preview`.
+
+## Layer
+
+Build scripts:
+
+```json
+{
+  "scripts": {
+    "build": "rslib build --env-mode dev",
+    "build:npm": "rslib build --env-mode npm"
+  }
+}
+```
+
+The dev build writes `dist/dev/` with bundled JS, source maps, declarations, and a
+transformed `package.json`. The npm build writes `dist/npm/` optimized for publish
+(no source maps, bundled declarations, a publish-ready `package.json`).
+
+## Usage
+
+The output `package.json` is transformed from source: export paths move from `.ts`
+to `.js`, type conditions are added to exports, pnpm `catalog:` references resolve
+to concrete versions, and the `files` array is generated. This is the mechanism
+behind the convention that a source `package.json` is `private: true` while its
+`publishConfig` declares publish intent — the builder flips `private` based on
+`publishConfig.access` at build time.
+
+First builds are slower due to cache warming; subsequent builds use `.rslib/cache/`.
+A common pitfall: relative imports must use `.js` extensions (the ESM requirement),
+or the build reports "cannot find module".
+
+## Related
+
+Dependency pinning the build resolves: `silk://standards/catalog-usage`. How
+`private` and `publishConfig` decide what publishes:
+`silk://standards/publishability`.

package/resources/content/packages/silk/export-map.md

@@ -0,0 +1,67 @@
+---
+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
+tags: [silk]
+priority: 0.5
+related: [packages/silk/install-and-setup]
+---
+
+## What
+
+`@savvy-web/silk` has no root barrel. It exposes a set of nested config-integration
+entry points, each loaded by a different external tool. The nested subpaths mirror
+exactly the module shapes those tools load, rather than implying a coherent library
+API.
+
+## API
+
+```text
+./changesets              ← changeset class/services API surface
+./changesets/changelog    ← ChangelogFunctions default for .changeset/config.json
+./changesets/markdownlint ← markdownlint-cli2 rules (default array + named)
+./changesets/remark       ← remark transform plugins + presets + lint rules
+./commitlint              ← CommitlintConfig (auto-detecting factory) + types
+./commitlint/static       ← static config default (no auto-detection)
+./commitlint/prompt       ← commitizen adapter
+./commitlint/formatter    ← custom error formatter
+./lint                    ← handlers / Preset / createConfig / utils / section data
+./biome                   ← static silk.jsonc asset (copied, not a shim)
+```
+
+The shim contract per subpath:
+
+- `./changesets/changelog` — default export is the `@changesets/types`
+  `ChangelogFunctions` object the Changesets CLI loads from the config's
+  `changelog` field.
+- `./changesets/markdownlint` — default export is the rule array markdownlint-cli2
+  loads, plus the named rule objects.
+- `./changesets/remark` — named exports for every transform plugin, preset, and
+  lint rule remark configs import.
+- `./commitlint/static` — default export is the static config object (no
+  auto-detection); the root `./commitlint` default-exports the auto-detecting
+  `CommitlintConfig` factory.
+- `./lint` — the full lint-staged consumer surface (handlers, `Preset`,
+  `createConfig`, workspace utils, section/template data). CLI commands are
+  deliberately NOT re-exported here — those belong to the `savvy` CLI.
+
+## Layer
+
+The `exports` field in silk's `package.json` is the authoritative wiring; the shim
+files under `src/` are the single source of truth for the exact reshaping. The
+`./biome` entry is a copied asset, not a shim.
+
+## Usage
+
+A markdownlint config loading the Silk rules:
+
+```text
+extends: "@savvy-web/silk/biome"            # biome.jsonc
+@savvy-web/silk/changesets/markdownlint     # markdownlint-cli2 customRules
+```
+
+## Related
+
+Install and setup: `silk://packages/silk/install-and-setup`.

package/resources/content/packages/silk/install-and-setup.md

@@ -0,0 +1,59 @@
+---
+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
+tags: [silk, init]
+priority: 0.5
+related: [packages/silk/export-map, packages/cli/init-and-check]
+---
+
+## What
+
+`@savvy-web/silk` is the single package a consumer installs to get the whole Silk
+Suite dev-tooling system. It is an install surface, not a library: each subpath
+export is a thin config-integration **shim** that re-exports `@savvy-web/silk-effects`
+logic shaped into the exact module form an external tool's config loader expects.
+The shims carry no logic. It is a `fixed` changeset group with `@savvy-web/cli`.
+
+## API
+
+A shim is a drop-in replacement: a config file that imported a subpath of one of
+the three old packages (`@savvy-web/changesets`, `@savvy-web/commitlint`,
+`@savvy-web/lint-staged`) works unchanged after swapping the import to the matching
+`@savvy-web/silk` subpath. Each shim reproduces the **module shape** the loader
+consumes — default vs named, array vs object — not just the symbols. The full
+subpath map is at `silk://packages/silk/export-map`.
+
+## Layer
+
+silk's only dependency is `@savvy-web/silk-effects` (`workspace:*`). Its
+`peerDependencies` declare `@savvy-web/cli` (install-wiring) plus the merged
+real-tool peers (`@biomejs/biome` optional, `husky`, `@commitlint/*`, `commitizen`,
+`@changesets/cli`, `lint-staged`, `markdownlint-cli2`) via `catalog:silkPeers`.
+silk ships dual-format (esm + cjs) because some consumers `require()` its subpaths
+from CommonJS — notably markdownlint-cli2's custom-rule loader, which loads
+`./changesets/markdownlint` through a CJS path; silk-effects therefore also exposes
+a CJS entry. Dual-format is mandatory, not cosmetic.
+
+## Usage
+
+The consumer model:
+
+```text
+install @savvy-web/silk
+  → autoInstallPeers pulls cli (the savvy bin) + biome/husky/@commitlint/
+    @changesets/lint-staged/markdownlint
+  → savvy init seeds configs that reference @savvy-web/silk/* and wires husky
+    hooks to savvy subcommands
+  → at runtime both silk (via shims) and cli (via handlers) resolve their logic
+    from silk-effects
+```
+
+The Biome preset is referenced as `extends: "@savvy-web/silk/biome"`.
+
+## Related
+
+The export map: `silk://packages/silk/export-map`. The `init` step that follows
+install: `silk://packages/cli/init-and-check`.

package/resources/content/packages/silk-effects/index.md

@@ -0,0 +1,76 @@
+---
+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
+tags: [silk-effects, effect]
+priority: 0.5
+related: [packages/silk-effects/platform-layers, packages/silk-effects/managed-section, standards/publishability]
+---
+
+## What
+
+`@savvy-web/silk-effects` is a platform-agnostic Effect library holding the shared
+conventions of the Silk Suite. It extracts repeated patterns — publishability
+rules, changeset config reading, managed file sections, tool discovery — into one
+package consumed by the `savvy` CLI, `@savvy-web/silk`, GitHub Actions, and build
+scripts. It builds on `@effect/platform` abstractions rather than importing Node or
+Bun APIs directly, so the same service implementations run on any `@effect/platform`
+runtime once the consumer provides a context layer at the edge.
+
+## API
+
+Every service is a `Context.Tag` accessed with `yield*` inside `Effect.gen`. The
+entire public API ships from the single package root — there are no subpath exports.
+
+```typescript
+import {
+  SilkPublishability,
+  ManagedSection, ManagedSectionLive, SectionDefinition, SectionBlock,
+  ToolDiscovery, ToolDiscoveryLive, ToolDefinition,
+} from "@savvy-web/silk-effects";
+```
+
+Service index:
+
+- `SilkPublishability` — static publishability `detect` plus detector layers.
+- `TagStrategy` — git tag formatting (pure, no platform layer).
+- `ChangesetConfig` / `ChangesetConfigReader` — read and query `.changeset/config.json`.
+- `VersioningStrategy` — version resolution.
+- `ManagedSection` — BEGIN/END tool-owned regions in user-editable files.
+- `ConfigDiscovery` — locate config files.
+- `BiomeSchemaSync` — keep the Biome schema in sync.
+- `ToolDiscovery` — resolve and execute project tools (biome, husky, and the rest).
+
+It also hosts the dev-tooling business logic under three namespace exports —
+`Changesets`, `Commitlint`, `Lint` — which the `savvy` CLI and `@savvy-web/silk`
+shims both consume so neither imports the other.
+
+## Layer
+
+Services fall into three platform tiers: pure (no layer), `FileSystem`, and
+`FileSystem` + `CommandExecutor`. See `silk://packages/silk-effects/platform-layers`
+for the full guide. `effect` and `@effect/platform` are peer dependencies;
+`workspaces-effect`, `semver-effect`, `jsonc-effect`, and `yaml-effect` are direct.
+
+## Usage
+
+```typescript
+import { SilkPublishability } from "@savvy-web/silk-effects";
+
+const targets = SilkPublishability.detect("@my-org/pkg", {
+  private: true,
+  publishConfig: { access: "public", targets: ["npm"] },
+});
+// => [PublishTarget { registry: "https://registry.npmjs.org/", access: "public", ... }]
+```
+
+All errors extend `Data.TaggedError` with a `_tag` discriminant, so they are
+pattern-matchable with `Effect.catchTag`.
+
+## Related
+
+Platform layers: `silk://packages/silk-effects/platform-layers`. Managed sections:
+`silk://packages/silk-effects/managed-section`. The publishability rules this
+package encodes: `silk://standards/publishability`.

package/resources/content/packages/silk-effects/managed-section.md

@@ -0,0 +1,84 @@
+---
+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
+tags: [managed-section, effect]
+priority: 0.5
+related: [packages/silk-effects/, packages/silk-effects/platform-layers]
+---
+
+## What
+
+`ManagedSection` lets a tool own a delimited region of a file while leaving the
+rest user-editable, using BEGIN/END markers. The motivating case is a husky hook
+that runs a tool's command inside a managed region surrounded by user commands.
+The service ships with value objects — `SectionDefinition` (section identity:
+tool name + comment style) and `SectionBlock` (the content between markers).
+Platform layer: `FileSystem`. Since 0.2.0.
+
+## API
+
+`SectionDefinition` and `SectionBlock` are `Schema.TaggedClass` value objects with
+structural equality — `SectionBlock` compares on normalized (trimmed,
+whitespace-collapsed) content, so whitespace-only differences are equal. Comment
+style is `"#"` (shell/YAML) or `"//"` (C-style); the tool name is uppercased into
+the markers. `SectionDefinition.block(content)` mints a block;
+`.generate(fn)` / `.generateEffect(fn)` build typed factories; `.withValidation`
+attaches a content predicate that throws `SectionValidationError`.
+
+The service Tag exposes (all dual-API, data-first or data-last):
+
+- `read(path, def)` → `SectionBlock | null` (null if no file or no markers).
+- `isManaged(path, def)` → `boolean` (always succeeds).
+- `write(path, block)` → replaces the managed region, appends if markerless,
+  creates the file if absent; preserves content outside the markers.
+- `sync(path, block)` → smart write reporting `SyncResult`: `Created`,
+  `Updated({ diff })`, or `Unchanged`; writes only when different.
+- `syncMany(path, blocks)` → syncs several ordered sections in one file
+  idempotently, inserting missing siblings and normalizing drift; returns one
+  `SyncResult` per block in input order.
+- `check(path, block)` → read-only `CheckResult`: `Found({ isUpToDate, diff })`
+  or `NotFound`.
+- `remove(path, def)` → deletes the span including markers and collapses the
+  leftover blank line; `true` if removed, `false` if absent (missing file → false).
+
+Identity-only operations (`read`, `isManaged`, `remove`) take a `SectionDefinition`;
+content operations take a `SectionBlock`. Errors: `SectionParseError`,
+`SectionWriteError`, `SectionValidationError`.
+
+## Layer
+
+```typescript
+export const ManagedSectionLive: Layer.Layer<ManagedSection, never, FileSystem.FileSystem>;
+```
+
+## Usage
+
+```typescript
+import { Effect } from "effect";
+import { NodeContext } from "@effect/platform-node";
+import { ManagedSection, ManagedSectionLive, SectionDefinition } from "@savvy-web/silk-effects";
+
+const def = SectionDefinition.make({ toolName: "LINT-STAGED" });
+
+await Effect.runPromise(
+  Effect.gen(function* () {
+    const ms = yield* ManagedSection;
+    const result = yield* ms.sync(".husky/pre-commit", def.block("\nnpx lint-staged\n"));
+    // result._tag => "Created" | "Updated" | "Unchanged"
+  }).pipe(Effect.provide(ManagedSectionLive), Effect.provide(NodeContext.layer)),
+);
+```
+
+The `SavvySections` helpers (since 0.5.0) provide ready-made husky-hook shells:
+`SavvyBaseSection` + `savvyBasePreamble()` define a shared package-manager preamble
+(`ROOT`, the `in_ci` predicate, `PM`, `pm_exec`), and `savvyToolSection(toolName,
+command)` builds a consumer's one-line tool section. Pass the base first to
+`syncMany` so `in_ci` and `pm_exec` are defined before a tool section uses them.
+
+## Related
+
+Overview: `silk://packages/silk-effects/`. Layer wiring:
+`silk://packages/silk-effects/platform-layers`.

package/resources/content/packages/silk-effects/platform-layers.md

@@ -0,0 +1,94 @@
+---
+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
+tags: [silk-effects, effect]
+priority: 0.5
+related: [packages/silk-effects/, packages/silk-effects/managed-section]
+---
+
+## What
+
+silk-effects is platform-agnostic: services declare their dependencies through
+Effect's `Layer` type system, and the consumer provides concrete implementations at
+the edge of the program. There are three tiers.
+
+## API
+
+**Tier 0 — no platform layer.** Pure services with no I/O. `SilkPublishability.detect`
+is a static needing no layer or runtime. `TagStrategy` is a `Context.Tag`, so provide
+its `TagStrategyLive`.
+
+**Tier 1 — FileSystem.** Read/write services depend on `FileSystem` from
+`@effect/platform`, supplied by the runtime context layer (`NodeContext.layer` or
+`BunContext.layer`). Members: `SilkPublishabilityDetectorLive`,
+`PublishabilityDetectorAdaptiveLive`, `ChangesetConfig`, `ChangesetConfigReader`,
+`VersioningStrategy`, `ManagedSection`, `ConfigDiscovery`, `BiomeSchemaSync`.
+
+**Tier 2 — FileSystem + CommandExecutor.** `ToolDiscovery` also needs
+`CommandExecutor` plus `PackageManagerDetector` and `WorkspaceRoot` from
+`workspaces-effect`. `NodeContext.layer` provides `FileSystem` and `CommandExecutor`.
+
+Dependency graph:
+
+```text
+SilkPublishability.detect          (pure static, no layer)
+TagStrategy                        (no deps)
+SilkPublishabilityDetectorLive     --> FileSystem
+PublishabilityDetectorAdaptiveLive --> FileSystem, ChangesetConfig
+ChangesetConfigReader              --> FileSystem
+ChangesetConfig                    --> ChangesetConfigReader
+VersioningStrategy                 --> ChangesetConfigReader
+ManagedSection, ConfigDiscovery, BiomeSchemaSync --> FileSystem
+ToolDiscovery                      --> CommandExecutor, PackageManagerDetector, WorkspaceRoot
+```
+
+## Layer
+
+Compose with `Effect.provide` / `Layer.mergeAll`; services sharing a dependency
+(like `FileSystem`) need the platform layer provided once.
+
+```typescript
+import { Effect } from "effect";
+import { NodeContext } from "@effect/platform-node";
+import { ManagedSection, ManagedSectionLive } from "@savvy-web/silk-effects";
+
+await Effect.runPromise(
+  Effect.gen(function* () {
+    const ms = yield* ManagedSection;
+    // ...
+  }).pipe(Effect.provide(ManagedSectionLive), Effect.provide(NodeContext.layer)),
+);
+```
+
+## Usage
+
+The adaptive detector overrides `workspaces-effect`'s `PublishabilityDetector` Tag
+and dispatches by changeset mode; it needs `ChangesetConfig`, which needs
+`ChangesetConfigReader`:
+
+```typescript
+import { Layer } from "effect";
+import { NodeContext } from "@effect/platform-node";
+import {
+  ChangesetConfigLive, ChangesetConfigReaderLive,
+  PublishabilityDetectorAdaptiveLive,
+} from "@savvy-web/silk-effects";
+
+const layer = Layer.mergeAll(
+  PublishabilityDetectorAdaptiveLive.pipe(Layer.provide(ChangesetConfigLive)),
+  ChangesetConfigLive,
+  ChangesetConfigReaderLive,
+).pipe(Layer.provide(NodeContext.layer));
+```
+
+For unconditional Silk rules without changeset awareness, use
+`SilkPublishabilityDetectorLive`, which needs only the platform layer. For tests,
+provide a mock `FileSystem` layer in place of `NodeContext.layer`.
+
+## Related
+
+Overview: `silk://packages/silk-effects/`. ManagedSection:
+`silk://packages/silk-effects/managed-section`.

package/resources/content/standards/api-model-pipeline.md

@@ -0,0 +1,63 @@
+---
+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
+tags: [api, build]
+priority: 0.5
+related: [packages/mcp/resource-taxonomy]
+---
+
+## Rule
+
+Package API-reference docs are **generated** from Microsoft API Extractor models,
+not hand-written. Do not edit generated docs directly — changes are overwritten on
+the next build.
+
+### Pipeline
+
+1. A library package sets `apiModel` in its rslib config.
+2. `build:prod` emits `<unscoped>.api.json` (a Microsoft API Extractor model file).
+3. The `api-extractor-llms` library renders that model into LLM-lean
+   markdown.
+4. The rendered docs appear in the MCP resource layer under
+   `silk://packages/<pkg>/api/<kind>/<name>`.
+5. The `silk://catalog` lists these entries marked `(generated)`.
+
+Generated docs carry a provenance marker indicating they must not be hand-edited.
+
+### Coverage scope
+
+Only public API surfaces are included. Internal and `@internal`-tagged members are
+excluded. Quality tracks TSDoc coverage: undocumented public members degrade the
+model and produce sparse rendered output.
+
+## Why
+
+Hand-written API docs drift from code. Generating docs from the type surface and
+TSDoc comments keeps them accurate by construction: a renamed export, a removed
+parameter, or a new option surfaces automatically in the next build. The API
+Extractor model format is the standard Microsoft toolchain for TypeScript API
+management, making the pipeline compatible with upstream tooling.
+
+## Examples
+
+A package `@savvy-web/silk-effects` with `apiModel` in its rslib config builds
+`silk-effects.api.json`. The renderer produces entries such as:
+
+```text
+silk://packages/silk-effects/api/class/SilkPublishability
+silk://packages/silk-effects/api/namespace/Changesets
+silk://packages/silk-effects/api/class/ChangesetConfig
+```
+
+These appear in `silk://catalog` as `(generated)` entries alongside hand-authored
+docs.
+
+## See also
+
+The resource taxonomy that governs where generated and hand-authored docs live is at
+`silk://packages/mcp/resource-taxonomy`. The `api-extractor-llms` library
+is the renderer; the `@savvy-web/rslib-builder` build tool exposes the `apiModel`
+config option.

package/resources/content/standards/catalog-usage.md

@@ -0,0 +1,48 @@
+---
+id: standards/catalog-usage
+title: Catalog usage
+summary: Load when adding or pinning a dependency in a Silk Suite package.
+tier: standards
+source: hand
+tags: [catalog, dependencies]
+priority: 0.8
+related: [standards/publishability]
+---
+
+## Rule
+
+Pin dependencies through the named catalogs that `@savvy-web/pnpm-plugin-silk`
+merges into `pnpm-workspace.yaml` during `pnpm install`. Use `catalog:silk` for
+direct `dependencies` and `devDependencies`; use `catalog:silkPeers` for
+`peerDependencies`. Do not hard-code version strings for catalog-managed packages.
+
+## Why
+
+`catalog:silk` carries current/latest pinned versions; `catalog:silkPeers` carries
+wider permissive ranges so a consuming package does not force its users to upgrade
+in lockstep. Centralizing versions in the plugin keeps every repo in the ecosystem
+on one coordinated set, and lets security overrides for transitive CVEs land
+without per-repo edits.
+
+The 26 Effect ecosystem packages are updated together as one batch to preserve
+cross-package compatibility. For `@effect/*` packages (all at `0.x`), `silkPeers`
+uses `>=` floor-only ranges rather than `^` caret ranges, because `^0.x.y`
+restricts to patch-only and would not overlap with the `silk` pinned version one
+minor ahead. For `effect` itself (at `3.x`) the standard `^` caret works.
+
+## Examples
+
+```json
+{
+  "devDependencies": { "typescript": "catalog:silk", "vitest": "catalog:silk" },
+  "peerDependencies": { "typescript": "catalog:silkPeers" }
+}
+```
+
+To override a catalog entry locally, add it under `catalogs.silk` in
+`pnpm-workspace.yaml`; the local value wins and the plugin prints a warning so the
+divergence is visible. Remove the local entry to revert to the Silk default.
+
+## See also
+
+Publishability and registry targets are at `silk://standards/publishability`.

package/resources/content/standards/changeset-discipline.md

@@ -0,0 +1,52 @@
+---
+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
+tags: [changeset, release]
+priority: 0.8
+related: [packages/silk-effects/, standards/publishability]
+---
+
+## Rule
+
+Every branch that changes a publishable package's runtime behavior, public API, or
+shipped output ships a changeset that describes the change in user-facing terms.
+Changes that do not affect what a consumer installs — AI context files, design
+docs, internal tests, trivial config — do not get a changeset. The Silk ecosystem
+formats changelogs through `@savvy-web/changesets`, a section-aware formatter that
+categorizes entries with `h2`/`h3` headings (Features, Bug Fixes, Breaking Changes,
+and the rest of the 13 valid headings) and enriches them with PR links and
+contributor attribution.
+
+## Why
+
+A changeset is release documentation, not a commit log. It answers "what changed
+for someone consuming this package" one level above the diff. Reconciling the
+changeset set against the branch diff before merge keeps the `.changeset/`
+directory an accurate description of the pending release: stale entries that name
+packages no longer touched are removed, and missing entries for shipped work are
+added. Pure dependency bumps follow a one-package-per-changeset, one-dependency-
+changeset-per-package convention so the changelog reads cleanly.
+
+A config is detected as Silk (versus vanilla changesets) when its `changelog`
+field references `@savvy-web/changesets`; Silk mode is what enables the
+section-aware pipeline and the ignore-aware publishability rules.
+
+## Examples
+
+A `feat` that adds a public export needs a `minor` changeset under a Features
+heading. A `fix` that corrects shipped behavior needs a `patch` changeset under
+Bug Fixes. A branch that only edits `CLAUDE.md` and `.claude/design/` needs no
+changeset. A breaking signature change needs a `major` changeset under Breaking
+Changes.
+
+## See also
+
+Authoring and reconciliation are handled by the changeset skills — the
+`changeset-create` skill reconciles changesets against the branch diff, and the
+`changeset-style` skill carries the full format spec (the 13 headings and rules
+CSH001–CSH005). The publishability rules that decide which packages a changeset
+may name live at `silk://standards/publishability`; the config reader and the
+fixed/ignore groups it exposes are documented at `silk://packages/silk-effects/`.