📦 build: slim the skill installation package

.gitattributes

@@ -12,3 +12,7 @@ evals/review.html -text -whitespace linguist-generated=true
 evals/review-node.html -text -whitespace linguist-generated=true
 # Keep generated viewers available without counting them as authored source.
 examples/rendered/** linguist-generated=true
+# Committed copies keep Skills CLI installation independent of contributor setup.
+skills/database-dependency-migration/** linguist-generated=true
+skills/database-dependency-migration/SKILL.md linguist-generated=false
+skills/database-dependency-migration/README.md linguist-generated=false

.github/workflows/ci.yml

@@ -14,6 +14,7 @@ jobs:
           node-version: "24"
       - run: npm install --global pnpm@12.10.1 --ignore-scripts
       - run: pnpm install --frozen-lockfile --ignore-scripts
+      - run: pnpm check:skill
       - run: pnpm audit --audit-level=low
       - run: pnpm exec playwright install --with-deps chromium
       - run: pnpm test
@@ -26,6 +27,8 @@ jobs:
       - run: pnpm package:skill
       - run: pnpm package:site
       - run: pnpm smoke:artifacts
+      - run: npm install --prefix out/skills-cli --ignore-scripts --no-audit --no-fund skills@1.7.2
+      - run: pnpm smoke:skills --cli out/skills-cli/node_modules/skills/bin/cli.mjs
       - name: build the GitHub Pages repository prefix
         run: pnpm build
         env:

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+Move the discoverable skill into `skills/database-dependency-migration/`. Generate its committed toolkit/resources with a shared distribution allowlist, exclude website/evaluation/development files and use the same payload for `.skill` archives. Add stale-copy checks, installed-link regressions and a real Skills CLI smoke in CI. Update manual-copy instructions and website documentation paths.
+
 Make source-cited migration review the default skill workflow without Node.js, pnpm, installed packages, builds or a database server. Add manual EF Core/C#, Prisma and TypeORM mapping guidance, sequential schema ledgers and PR-ready summaries. Keep parser-backed models and interactive reports in the optional toolkit, with a production-only npm installation path. Update the README, troubleshooting, report outline, agent prompt and English/Spanish website installation and quickstart guidance. Record broader automation and independent accuracy testing as future work.
 
 Find npm in both official Windows and POSIX Node installation layouts during artifact installation checks. Resolve prerequisites before creating a temporary workspace. The first remote Linux CI run exposed this portability bug after all engine/browser/build checks passed.

CONTRIBUTING.md

@@ -6,7 +6,7 @@ Keep dependency claims grounded in source evidence, preserve explicit unknowns,
 
 Anyone can fork this public repository, create a branch in their fork, and open a pull request targeting `main`. Repository write access is not needed. Describe the problem, resulting behavior and checks performed, and follow the commit format below.
 
-The [code owners](.github/CODEOWNERS) are `@JoseDFlorez` and `@Juanfrxz`. A pull request requires an approval from at least one of them, passing required CI checks and resolved review conversations before merging. New changes invalidate earlier approvals. Maintainers also use pull requests; the author cannot approve their own request and the latest push needs another maintainer's approval.
+The [code owners](.github/CODEOWNERS) are `@JoseDFlorez` and `@Juanfrxz`. They use pull requests and may merge without a separate review approval through their explicit review exemption. The normal contributor path requires approval from at least one code owner; new changes invalidate earlier approvals and the latest push needs another maintainer's approval. Every pull request must pass required CI checks and resolve review conversations before merging.
 
 Public contributors can comment and submit reviews. Their approval does not replace the required code-owner approval. Keep vulnerabilities and private database artifacts out of public pull requests; follow [SECURITY.md](SECURITY.md).
 
@@ -41,7 +41,7 @@ Use `pnpm exec prettier --check` with the files you changed. Describe checks act
 | Catalog capture or normalization   | `src/dbdep/catalog.mjs`, fixed-query contract, catalog guidance, isolated live tests and sanitized provenance                      |
 | Hazard rules or phase guidance     | `src/dbdep/rules.mjs`, `planning.mjs`, migration guidance, positive/negative and UNKNOWN regressions                               |
 | Reports or viewer                  | `src/dbdep/reports.mjs`, `assets/viewer/`, schemas as needed, browser checks and regenerated examples                              |
-| CLI or installation                | `src/dbdep/cli.mjs`, `SKILL.md`, README, site command docs, CLI and real-install smoke checks                                      |
+| CLI or installation                | `src/dbdep/cli.mjs`, `skills/database-dependency-migration/SKILL.md`, README, distribution sync and real-install smoke checks      |
 | Website                            | `site/src/`, bilingual copy/accessibility, site tests and retained license notices                                                 |
 
 Add an observable failing regression before changing graph semantics, hazards or safety boundaries. Preserve stable IDs, deterministic ordering, UTF-8 source locations, hashes and evidence states. Unsupported or ambiguous resolution must remain UNKNOWN. The current canonical contract is 1.0.0; explain incompatible changes explicitly.
@@ -81,6 +81,8 @@ Build and package the current local version, then test both npm/unpacked skill a
 pnpm build
 pnpm check:site
 pnpm pack --pack-destination dist/v0.3.2
+pnpm sync:skill
+pnpm check:skill
 pnpm package:skill
 pnpm package:site
 pnpm smoke:artifacts
@@ -95,7 +97,9 @@ pnpm exec node scripts/smoke-skills-install.mjs --cli out/skills-cli/node_module
 
 `DBDEP_SKILLS_CLI` can supply the same cached entry point. The smoke installs a current worktree snapshot into a project outside the checkout, disables telemetry, checks archive/version/member hashes and sensitive filenames, installs frozen production dependencies, runs `doctor`, creates all three demos and strictly validates them. Its checked temporary directory is removed and its receipt is written under `dist/v<version>/`. This catches the installer excluding files named `metadata.json`; the active high-traffic input is `workload-profile.json`.
 
-The Skills CLI copies the root skill directory, including site/evaluation/development files. npm and `.skill` packaging use their own allowlists. Test their actual contents and preserve licenses. Rebuild the website after README or SKILL changes; site packaging rejects stale documentation copies. Development checks require the full workspace. An installed skill needs no package installation for source review; only its optional toolkit needs the production-only npm or frozen pnpm setup documented in the README.
+The Skills CLI installs only `skills/database-dependency-migration/`. Its canonical `SKILL.md` and installation README are authored there; `pnpm sync:skill` refreshes the other committed files from an explicit root-source allowlist. After changing toolkit sources, references, templates, metadata, examples, manifests, lockfiles or licenses, run the sync and include its changes in the same commit. `pnpm check:skill` rejects stale or unexpected files, and CI runs it before tests. Do not edit the generated copies directly.
+
+The `.skill` archive uses that same checked payload. npm retains its separate toolkit file allowlist. The real installer smoke compares installation member hashes against the dedicated directory, rejects website/evaluation/development files and reports installed bytes. Test actual contents and preserve licenses. Rebuild the website after README or skill-entry changes; site packaging rejects stale documentation copies. Development checks require the full workspace. Source review needs no package installation; only the optional toolkit needs the production-only npm or frozen pnpm setup documented in the README.
 
 ## Style and commits
 
@@ -113,7 +117,7 @@ Examples are `🐛 fix: preserve metadata in skills installs` and `📝 docs: ex
 
 ## Releases and deployment
 
-Follow [SemVer](https://semver.org/) and [docs/releases.md](docs/releases.md). Update root/site package versions, `SKILL.md` metadata, the lockfile and changelog together. The pending local release is v0.3.2; historical v0.3.0/v0.3.1 receipts and frozen evaluations remain historical.
+Follow [SemVer](https://semver.org/) and [docs/releases.md](docs/releases.md). Update root/site package versions, `skills/database-dependency-migration/SKILL.md` metadata, the lockfile and changelog together, then sync the dedicated skill directory. The pending local release is v0.3.2; historical v0.3.0/v0.3.1 receipts and frozen evaluations remain historical.
 
 Complete relevant checks and artifact/hash comparisons on final `main` before creating an annotated `v<version>` tag. Never move or replace an existing release tag. Local commit/tag creation, remote push, GitHub release assets, npm publication and Pages deployment are distinct actions; perform publication only when authorized.
 

README.md

@@ -25,27 +25,32 @@ You need an agent that supports `SKILL.md`, such as Codex or Claude Code, and ac
 
 ### Manual installation without Node.js
 
-Copy or symlink this checkout, or unpack the `.skill` archive, into your agent's skill directory. Keep `SKILL.md`, `references/` and `templates/` together. The scripts, schemas and viewer are optional toolkit resources. Reload your agent and use the skill immediately.
+Copy or symlink [skills/database-dependency-migration](https://github.com/whetstone-dev/Database-Dependency-Migration-Visualizer/tree/main/skills/database-dependency-migration), or unpack the `.skill` archive, into your agent's skill directory. Keep its `SKILL.md`, references and templates together. The scripts, schemas and viewer are optional toolkit resources. Reload your agent and use the skill immediately.
 
-Alternatively, clone from your project root:
+For a project installation on macOS/Linux, clone the repository and copy its distributable directory:
 
 ```sh
-git clone https://github.com/whetstone-dev/Database-Dependency-Migration-Visualizer.git .agents/skills/database-dependency-migration
+git clone https://github.com/whetstone-dev/Database-Dependency-Migration-Visualizer.git dbdep-skill-source
+mkdir -p .agents/skills
+cp -R dbdep-skill-source/skills/database-dependency-migration .agents/skills/
 ```
 
 For a personal Codex skill on macOS/Linux:
 
 ```sh
-git clone https://github.com/whetstone-dev/Database-Dependency-Migration-Visualizer.git ~/.agents/skills/database-dependency-migration
+mkdir -p ~/.agents/skills
+cp -R dbdep-skill-source/skills/database-dependency-migration ~/.agents/skills/
 ```
 
 On Windows PowerShell:
 
 ```powershell
-git clone https://github.com/whetstone-dev/Database-Dependency-Migration-Visualizer.git "$HOME/.agents/skills/database-dependency-migration"
+git clone https://github.com/whetstone-dev/Database-Dependency-Migration-Visualizer.git dbdep-skill-source
+New-Item -ItemType Directory -Path .agents/skills -Force
+Copy-Item -LiteralPath ./dbdep-skill-source/skills/database-dependency-migration -Destination .agents/skills/database-dependency-migration -Recurse
 ```
 
-For Claude Code, use `.claude/skills/database-dependency-migration` in a project or `~/.claude/skills/database-dependency-migration` personally. No package installation is needed.
+For a personal Windows installation, use `$HOME/.agents/skills` as the destination parent. For Claude Code, use `.claude/skills/database-dependency-migration` in a project or `~/.claude/skills/database-dependency-migration` personally. No package installation is needed.
 
 ### Skills CLI
 
@@ -57,16 +62,16 @@ npx skills@1.7.2 add whetstone-dev/Database-Dependency-Migration-Visualizer --sk
 
 This installs into `.agents/skills/database-dependency-migration` in the current project. Replace `codex` with `claude-code`, or add `--global` for a personal installation. Reload your agent and use the skill; there is no follow-up `pnpm install` step. The installer itself requires Node.js 22.20+; manual copying/cloning does not.
 
-Skills CLI copies the repository directory containing the root `SKILL.md`, including development files, website and evaluations. The `.skill` archive excludes the website and evaluation records. Neither installation needs those development files to run a source review.
+Skills CLI discovers `skills/database-dependency-migration/` and copies only that directory. It includes the skill guidance, optional toolkit, examples and licenses, while excluding the website, evaluation records, tests and development scripts. The `.skill` archive uses the same checked payload. No contributor build or dependency installation is needed to install or use the skill.
 
 ### Updating
 
 ```sh
 npx skills@1.7.2 update database-dependency-migration --project
 # Personal Skills CLI installation:
 npx skills@1.7.2 update database-dependency-migration --global
-# Manual Git project installation:
-git -C .agents/skills/database-dependency-migration pull --ff-only
+# Manual installation: update the source checkout, then copy its skill directory again.
+git -C dbdep-skill-source pull --ff-only
 ```
 
 For a personal/manual installation, use its actual directory with `git -C`; replace copied files with the updated skill when not using Git. Reload the agent. Only users of the optional toolkit need to refresh runtime dependencies after updating. Keep inputs and reports in the user's workspace, outside the installed skill directory.
@@ -114,7 +119,7 @@ node scripts/dbdep.mjs inspect --catalog examples/analytics/catalog.json --out o
 node scripts/dbdep.mjs demo out/demo --json
 ```
 
-`pnpm dbdep <command>` runs the same entry point. From another working directory, use `node "<skill-directory>/scripts/dbdep.mjs" ...`. A local npm tarball can expose `dbdep` through `npm install -g <package.tgz>`; no published npm package is assumed.
+`pnpm dbdep <command>` runs the same entry point. From another working directory, use `node "<skill-directory>/scripts/dbdep.mjs" ...`. A local npm tarball can expose `dbdep` through `npm install -g <package.tgz>`; no published npm package is assumed. The npm tarball supplies the standalone toolkit. Install the complete agent skill through Skills CLI, manual copying or the `.skill` archive.
 
 `snapshot` aliases `inspect`. A schema directory contains declarations; it does not replay migrations. Review without a baseline is explicitly partial. Exit **0** means analysis completed, **2** means invalid input/prerequisites, and **3** means a requested policy gate failed. A successful analysis may contain high-risk findings; failed risk gates still write review artifacts.
 
@@ -156,11 +161,12 @@ Open the localhost URL printed by the preview. GitHub Pages deployment is a manu
 
 | Path                                    | Contents                                                                              |
 | --------------------------------------- | ------------------------------------------------------------------------------------- |
-| `SKILL.md`, `agents/`                   | Agent entry point, task routing and display metadata                                  |
+| `skills/database-dependency-migration/` | Discoverable skill entry point and complete, checked installation payload             |
+| `agents/`, `references/`, `templates/`  | Source guidance and metadata copied into the distributable skill                      |
 | `src/dbdep/`                            | Independent model, parser, graph, catalog, hazard, planning, reporting and CLI engine |
 | `scripts/dbdep.mjs`                     | Standalone CLI entry point                                                            |
 | `scripts/`                              | Fixture, packaging, install-smoke and evaluation development tools                    |
-| `schemas/`, `references/`, `templates/` | Canonical schemas, evidence semantics, safety guidance and report template            |
+| `schemas/`                              | Canonical model, findings and review schemas                                          |
 | `assets/viewer/`                        | Offline report viewer and embedded licensed fonts                                     |
 | `examples/`                             | Curated inputs, authentic sanitized capture and generated reports                     |
 | `tests/`                                | Node, browser and isolated live regressions                                           |

SECURITY.md

@@ -8,7 +8,7 @@ Use the repository's private vulnerability reporting option when available. Othe
 
 ## Trust boundaries
 
-The installed skill contains agent instructions and an optional Node.js toolkit. Ordinary source reviews require no dependency installation or executable toolkit code. Review the toolkit's source and dependencies before choosing to run it; install with `--ignore-scripts`, using the frozen production path when reproducibility is required. The Skills CLI copies the root skill directory, including development files and evaluations; the separate `.skill` archive has a narrower file allowlist.
+The installed skill contains agent instructions and an optional Node.js toolkit. Ordinary source reviews require no dependency installation or executable toolkit code. Review the toolkit's source and dependencies before choosing to run it; install with `--ignore-scripts`, using the frozen production path when reproducibility is required. Skills CLI copies only `skills/database-dependency-migration/`; the `.skill` archive uses the same checked payload. Website, evaluation, test and development files stay outside this installation.
 
 The analyzer reads supplied SQL and catalog captures as data. It has no migration execution command or API. Live discovery requires an explicitly selected environment variable and read-only mode, uses fixed catalog queries, omits routine bodies and business rows, and hashes stored default-expression trees. Development fixture scripts execute shipped example SQL only in their own disposable cluster or explicitly configured CI fixture database.