@savvy-web/mcp 0.1.0

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

@@ -0,0 +1,131 @@
+---
+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
+tags: [changeset]
+priority: 0.5
+related: [standards/changeset-discipline]
+---
+
+## Rule
+
+Every changeset file (`.changeset/*.md`) starts with YAML frontmatter declaring the
+affected packages and bump levels, followed by body content organized under one or
+more of the 13 valid `##` section headings.
+
+### Frontmatter shape
+
+```yaml
+---
+"@savvy-web/package-name": patch | minor | major
+---
+```
+
+Multiple packages list one line each:
+
+```yaml
+---
+"@savvy-web/package-a": minor
+"@savvy-web/package-b": patch
+---
+```
+
+### Bump type guide
+
+| Bump | Use for |
+| :--- | :--- |
+| `patch` | Bug fixes, docs, internal refactoring, tests, CI/build changes |
+| `minor` | New features, new exports, non-breaking additions |
+| `major` | Removed exports, changed signatures, breaking behavior changes |
+
+### 13 valid section headings
+
+All `##` headings must exactly match one of these (case-sensitive):
+
+| Priority | Heading | Use for |
+| :--- | :--- | :--- |
+| 1 | Breaking Changes | Backward-incompatible changes |
+| 2 | Features | New functionality |
+| 3 | Bug Fixes | Bug corrections |
+| 4 | Performance | Performance improvements |
+| 5 | Documentation | Documentation changes |
+| 6 | Refactoring | Code restructuring |
+| 7 | Tests | Test additions or modifications |
+| 8 | Build System | Build configuration changes |
+| 9 | CI | Continuous integration changes |
+| 10 | Dependencies | Dependency updates |
+| 11 | Maintenance | General maintenance |
+| 12 | Reverts | Reverted changes |
+| 13 | Other | Uncategorized changes |
+
+### Structural rules (CSH001–CSH005)
+
+| Rule | Description |
+| :--- | :--- |
+| **CSH001** | No `#` (h1) headings anywhere in the body. No heading depth skips (e.g., jumping from `##` directly to `####`). |
+| **CSH002** | All `##` headings must exactly match one of the 13 valid categories. |
+| **CSH003** | No empty sections. Code fences must include a language identifier. No empty list items. |
+| **CSH004** | No content before the first `##` heading (YAML frontmatter is not "content"). |
+| **CSH005** | A `## Dependencies` section containing a table must use the 5-column schema (Dependency, Type, Action, From, To). |
+
+**CSH005 dependency table schema:**
+
+```markdown
+| Dependency | Type        | Action  | From   | To     |
+| :--------- | :---------- | :------ | :----- | :----- |
+| effect     | dependency  | updated | 3.18.0 | 3.19.1 |
+```
+
+Valid **Type** values: `dependency`, `devDependency`, `peerDependency`,
+`optionalDependency`, `workspace`, `config`.
+
+Valid **Action** values: `added`, `updated`, `removed`. Use `—` (em dash) for From
+when adding, or for To when removing.
+
+## Why
+
+The section-aware format makes changelogs scannable by category. Structural rules
+are enforced by remark-lint pre-validation (and markdownlint in-editor); violations
+fail CI. The 13 headings map to conventional commit types so tooling can correlate
+commits to changelog entries.
+
+## Examples
+
+**Minimal valid changeset (Simple tier):**
+
+```markdown
+---
+"@savvy-web/foo": patch
+---
+
+## Bug Fixes
+
+- Corrects off-by-one error in pagination helper.
+```
+
+**Multi-section with dependency table (Structured tier):**
+
+```markdown
+---
+"@savvy-web/foo": minor
+---
+
+## Features
+
+- Adds `suppressWarnings` option to `ApiModelOptions`.
+
+## Dependencies
+
+| Dependency | Type        | Action  | From   | To     |
+| :--------- | :---------- | :------ | :----- | :----- |
+| effect     | dependency  | updated | 3.18.0 | 3.19.1 |
+```
+
+## See also
+
+The discipline rules governing when a changeset is required are at
+`silk://standards/changeset-discipline`. The `changeset-style` Claude Code skill
+carries worked examples for all three content-depth tiers. The `changeset-check`
+skill validates files against CSH001–CSH005 via `savvy changeset check`.

package/resources/content/standards/commit-contract.md

@@ -0,0 +1,58 @@
+---
+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
+tags: [commit, dco, tdd]
+priority: 0.8
+related: [standards/changeset-discipline]
+---
+
+## Rule
+
+Commits follow `type(scope): subject`, with an optional body, optional `Closes #N`
+trailers, and a mandatory DCO `Signed-off-by` trailer as the last line. The
+`@savvy-web/commitlint` Silk preset enforces this through the `commit-msg` husky
+hook; violations reject the commit.
+
+**Type enum** (one lowercase identifier): `ai`, `build`, `chore`, `ci`, `docs`,
+`feat`, `fix`, `perf`, `refactor`, `release`, `revert`, `style`, `tdd`, `test`.
+Do not invent types.
+
+**Subject:** imperative mood ("add", not "added"/"adds"); lowercase first letter
+after the colon; the full header at most 100 characters; no trailing period; no
+markdown.
+
+**Body** (optional): explain what changed conceptually and why, one level above
+the diff. Each paragraph or bullet is one continuous line — do not soft-wrap.
+No markdown headers, numbered lists, code fences, links, bold, or italic. Name
+the concept that changed, not every file. For dependency updates list only direct
+deps, never transitive lockfile entries. Skip routine AI-context and config tweaks.
+
+## Why
+
+`tdd` commits require a structured scope `goalId:state` matching
+`^\d+:(spike|red|green|refactor)$` — for example `tdd(42:red)` or `tdd(7:green)`.
+The scope ties a commit to a TDD goal and its phase, so a bare `tdd` or
+`tdd(red)` is rejected. The DCO signoff is the Developer Certificate of Origin
+attestation; its exact `Signed-off-by: Full Name <email>` form is required
+verbatim, using the committer's real name and git email. When `commit.gpgsign`
+is true, confirm the signing agent is responsive rather than silently producing
+an unsigned commit.
+
+## Examples
+
+Good: `feat(auth): add JWT refresh token rotation`. Bad: `feat: Updated the auth
+flow` (past tense, capitalized, vague).
+
+A TDD green-phase commit: `tdd(14:green): implement scope validator for tdd commits`.
+
+A fix that closes an issue carries `Closes #87` above the signoff. Any of
+`Closes`, `Fixes`, or `Resolves` followed by `#N` is accepted, one trailer per
+issue.
+
+## See also
+
+The commit-create skill carries the full pre-commit checklist and worked examples.
+Release documentation discipline lives at `silk://standards/changeset-discipline`.

package/resources/content/standards/dependency-conventions.md

@@ -0,0 +1,82 @@
+---
+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
+tags: [dependencies, catalog]
+priority: 0.5
+related: [standards/catalog-usage]
+---
+
+## Rule
+
+All Silk Suite packages pin dependencies through the named catalogs provided by
+`@savvy-web/pnpm-plugin-silk`:
+
+- Use `catalog:silk` for `dependencies` and `devDependencies` (current pinned versions).
+- Use `catalog:silkPeers` for `peerDependencies` (permissive ranges).
+
+Do not hard-code version strings for catalog-managed packages.
+
+### How the plugin works
+
+`@savvy-web/pnpm-plugin-silk` is installed as a pnpm config dependency:
+
+```yaml
+configDependencies:
+  "@savvy-web/pnpm-plugin-silk": "0.3.0+sha512-..."
+```
+
+During `pnpm install` the plugin merges its catalog definitions, security overrides,
+and build configuration into the consuming repo's `pnpm-workspace.yaml`. The merge
+is non-destructive — local definitions always take precedence, and divergences are
+printed as warnings.
+
+The plugin ships:
+
+- `catalog:silk` — current/latest pinned versions for direct use
+- `catalog:silkPeers` — permissive ranges for peer declarations
+- `silkOverrides` — centralized CVE fixes propagated to all consumers
+- Shared `onlyBuiltDependencies`, `publicHoistPattern`, and `peerDependencyRules`
+
+### Effect ecosystem note
+
+The 26 `@effect/*` packages are updated together as one batch to preserve
+cross-package compatibility. For `@effect/*` packages (all at `0.x`),
+`catalog: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.
+
+## Why
+
+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 dual-catalog strategy balances two needs: direct consumers get a
+predictable pinned version; peer consumers stay compatible with a wider range of
+host environments without forcing lockstep upgrades.
+
+## Examples
+
+```json
+{
+  "devDependencies": {
+    "typescript": "catalog:silk",
+    "vitest": "catalog:silk"
+  },
+  "peerDependencies": {
+    "typescript": "catalog:silkPeers"
+  }
+}
+```
+
+To override a catalog entry for a single repo, add it under `catalogs.silk` in
+`pnpm-workspace.yaml`; the local value wins and the plugin prints a warning. Remove
+the local entry to revert to the Silk default.
+
+## See also
+
+Detailed catalog usage rules (including when to add a local override) are at
+`silk://standards/catalog-usage`. Publishability and registry targets that determine
+which packages enter the release pipeline are at `silk://standards/publishability`.

package/resources/content/standards/linting-conventions.md

@@ -0,0 +1,47 @@
+---
+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
+tags: [lint]
+priority: 0.8
+related: [standards/test-classification]
+---
+
+## Rule
+
+TypeScript is formatted and linted with Biome; markdown with markdownlint-cli2.
+Both run in pre-commit through `@savvy-web/lint-staged` composable handlers, so
+code that violates these rules does not commit.
+
+## Why
+
+A single shared config means contributors and agents follow the project's style
+without being told it each session, and CI enforces the same rules locally and
+remotely. The lint-staged plugin injects the active rules into Claude Code at
+session start for exactly this reason.
+
+## Examples
+
+Biome enforcements that bite most often:
+
+- `useImportExtensions` — relative imports MUST use `.js` extensions (ESM).
+- `useImportType` — type-only imports use `import type { Foo }`, not `import { type Foo }`.
+- `useNodejsImportProtocol` — Node built-ins use the `node:` protocol (`node:fs`).
+- `useConsistentTypeDefinitions` — prefer interfaces.
+- `noUnusedVariables` and `noImportCycles` are errors. Imports auto-sort.
+- Test files relax `noUndeclaredDependencies`.
+
+markdownlint rules that bite most often:
+
+- No line-length limit (MD013 disabled).
+- Duplicate headings allowed only among siblings (MD024).
+- HTML restricted to `br`, `details`, `summary`, `img`, `sup`, `sub`.
+- Code fences MUST carry a language identifier (MD040).
+- Tables use compact style — single space around cell content (MD060).
+- Files end with a single trailing newline (MD047).
+
+## See also
+
+Test file naming and discovery is at `silk://standards/test-classification`.

package/resources/content/standards/publishability.md

@@ -0,0 +1,57 @@
+---
+id: standards/publishability
+title: Publishability rules
+summary: Load when deciding whether a package publishes and how private vs publishConfig interact.
+tier: standards
+source: hand
+tags: [publishability]
+priority: 0.8
+related: [packages/silk-effects/, standards/catalog-usage]
+---
+
+## Rule
+
+A package's publishability is resolved from its `package.json` by applying these
+rules in order; the first match wins:
+
+1. `publishConfig.targets` is a non-empty array → one target per surviving entry.
+2. `publishConfig.access` is `public` or `restricted` → a single target.
+3. `private !== true` → a single default target.
+4. otherwise → not publishable (empty).
+
+`publishConfig.targets` takes precedence over the `private` flag: a package with
+`private: true` and a `publishConfig.targets` array still publishes. The `private`
+flag is consulted only as the last-resort default in rule 3.
+
+## Why
+
+In the Silk ecosystem `private: true` is the norm on source `package.json` files,
+and `publishConfig` declares publish intent. The builder flips `private` based on
+`publishConfig.access` at build time, so a source package with `private: true` and
+`publishConfig.access: "public"` is publishable. Encoding intent in `publishConfig`
+rather than the bare `private` flag lets a workspace keep packages private during
+development and publish them deliberately.
+
+`SilkPublishability.detect` is the pure entry point. Shorthand string targets
+expand to registries: `"npm"` → npmjs, `"github"` → GitHub Packages, `"jsr"` →
+jsr; an `http(s)://…` value is verbatim. String targets inherit the parent
+`publishConfig.access`; object targets use their own access else the parent's.
+
+## Examples
+
+```text
+{ private: true, publishConfig: { access: "public", targets: ["npm", "github"] } }
+  → publishes to both npm and GitHub Packages
+
+{ private: true }
+  → not publishable (empty)
+```
+
+The adaptive detector additionally short-circuits changeset-ignored packages to
+empty and dispatches on changeset mode (`none` → empty, `silk` → Silk rules,
+`vanilla` → upstream default).
+
+## See also
+
+The detector services and layers are documented at `silk://packages/silk-effects/`.
+Dependency pinning is at `silk://standards/catalog-usage`.

package/resources/content/standards/semver.md

@@ -0,0 +1,51 @@
+---
+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
+tags: [semver]
+priority: 0.5
+related: [standards/changeset-discipline]
+---
+
+## Rule
+
+Silk uses strict SemVer 2.0.0 for all version numbers. Git tags carry **no
+leading `v` prefix**. This applies everywhere — package versions, git tags, and
+version ranges authored by hand.
+
+| Context | Correct | Incorrect |
+| :--- | :--- | :--- |
+| `package.json` `"version"` | `"1.2.3"` | `"v1.2.3"` |
+| git tag for a release | `foo@1.2.3` or `1.2.3` | `vfoo@1.2.3` or `v1.2.3` |
+| changeset bump result | `1.2.3` | `v1.2.3` |
+
+## Why
+
+The `v` prefix is noise that breaks strict SemVer parsers. Many tools (including
+the Node.js SemVer library in strict mode) treat `v1.2.3` as an invalid version.
+Consistent, tool-parseable versions across every surface — npm registry, git tags,
+changelog entries, and API references — removes an entire class of subtle breakage
+where one tool normalizes the prefix and another does not.
+
+## Examples
+
+A release of `@savvy-web/foo` at version `1.2.3` is tagged `foo@1.2.3` (or
+`1.2.3` for single-package repos). The `package.json` carries `"version": "1.2.3"`.
+The CHANGELOG entry title reads `1.2.3`. No `v` anywhere.
+
+```bash
+# correct
+git tag foo@1.2.3
+
+# incorrect — never do this
+git tag vfoo@1.2.3
+git tag v1.2.3
+```
+
+## See also
+
+Changesets and bump mechanics are at `silk://standards/changeset-discipline`.
+Publishability rules (which determine when a tag triggers a release) are at
+`silk://standards/publishability`.

package/resources/content/standards/test-classification.md

@@ -0,0 +1,49 @@
+---
+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
+tags: [test]
+priority: 0.8
+related: [standards/linting-conventions]
+---
+
+## Rule
+
+`VitestConfig.create()` discovers workspace packages and classifies each test file
+by its **filename**, not its directory. The first matching pattern wins:
+
+- `*.e2e.(test|spec).(ts|tsx|js|jsx)` → e2e
+- `*.int.(test|spec).(ts|tsx|js|jsx)` → integration
+- `*.(test|spec).(ts|tsx|js|jsx)` → unit (catch-all; `*.unit.test.ts` lands here)
+
+Files matching none are ignored. Tests live in `src/` and an optional `__test__/`
+directory beside it; only packages with a `src/` directory are scanned.
+
+## Why
+
+Filename-driven classification keeps the directory layout free and the kind
+unambiguous — `foo.e2e.test.ts` is never double-counted as a unit test because the
+e2e pattern is checked first. A package with one test kind gets a bare project name
+(`@scope/pkg`); two or more kinds get suffixed names (`@scope/pkg:unit`,
+`@scope/pkg:e2e`). A package with `src/` but no tests still gets a unit project as
+a forward-looking placeholder.
+
+## Examples
+
+`parser.test.ts` and `parser.unit.test.ts` → unit. `auth.e2e.test.ts` → e2e.
+`db.int.test.ts` → integration.
+
+Helper and fixture directories are excluded from discovery at conventional
+locations only: `__test__/fixtures/`, `__test__/utils/`, and the same under
+`__test__/{unit,e2e,integration}/`. A `vitest.setup.{ts,tsx,js,jsx}` at the
+package root is auto-detected and added to `setupFiles`.
+
+Coverage defaults to the `"strict"` level (lines 80, branches 75, functions 80,
+statements 80). Passing `--project` flags scopes coverage to the union of the
+matched packages.
+
+## See also
+
+Lint and format rules are at `silk://standards/linting-conventions`.

package/resources/content/tags.json

@@ -0,0 +1,27 @@
+{
+	"changeset": ["changesets"],
+	"release": [],
+	"commit": ["commits", "conventional-commits"],
+	"dco": [],
+	"tdd": [],
+	"catalog": ["version-catalog"],
+	"dependencies": ["deps", "peer-dependencies"],
+	"lint": ["linting", "biome", "markdownlint"],
+	"test": ["testing", "vitest"],
+	"publishability": ["publish", "publishConfig", "private"],
+	"silk-effects": [],
+	"effect": ["layers", "context-tag"],
+	"managed-section": ["sections", "husky"],
+	"cli": ["savvy"],
+	"init": ["setup", "scaffold"],
+	"silk": ["install"],
+	"mcp": ["resources", "savvy-mcp"],
+	"build": ["rslib", "esm"],
+	"workspace": ["monorepo", "workspaces"],
+	"api": ["api-reference", "reference"],
+	"templates": ["scaffolding"],
+	"github-action-effects": ["gha-effects"],
+	"github-action-builder": ["gha-builder"],
+	"semver": ["versioning"],
+	"github-actions": ["gha", "actions"]
+}

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.7"
+    }
+  ]
+}