nestjs-boost 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## 1.2.0 — 2026-11-08
+
+First release after the package was republished (versions 1.0.0 and 1.1.0 can't be reused on npm). It includes everything below.
+
+### Repository security
+- `SECURITY.md` with private vulnerability reporting, CodeQL code scanning (JavaScript and workflows), Dependabot updates for the pinned Actions, `CODEOWNERS`, and LF line endings via `.gitattributes`.
+
+### Added
+- **Interactive setup.** `npx nestjs-boost install` asks which AI coding agents you use (detected ones pre-selected), shows the plan (skills, folders, which agents read each folder, instructions files, change counts) and installs after you confirm. The choice is saved in the lock file and reused by later runs and `npm install`.
+- **Seven more agents:** Gemini CLI, Windsurf, Cline, Roo Code, Kiro, JetBrains Junie and OpenCode, alongside Claude Code, OpenAI Codex, GitHub Copilot and Cursor. Each installs into the skills folder its own docs specify, with the guidelines block in its instructions file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md` or `.github/copilot-instructions.md`).
+- **Shared folders without duplicates:** with several agents selected, each skill is installed once into the folders that cover all of them (for example Claude Code + Cursor + Copilot share `.claude/skills/`).
+- `nestjs-boost agents` lists the supported agents and their folders. `-y` / `--yes` skips all questions.
+- Agent registry in `lib/agents.mjs`: adding an agent is one entry (see CONTRIBUTING.md).
+
+### Changed
+- **Install paths for Cursor and Copilot on their own:** selected alone (or without an agent that shares a folder with them), Cursor now uses `.cursor/skills/` and Copilot `.github/skills/`, their native folders, instead of `.agents/skills/`. The next sync moves the skills there and removes the old copies unless you edited them. With Claude Code or Codex also selected, nothing moves.
+- Deselecting an agent now also removes the guidelines block from its instructions file (and the file, if nestjs-boost created it and nothing else is left).
+- Install output groups skill changes per folder.
+- `install` never prompts in CI, with piped output, with `--yes`/`--agents`, or when `agents` is set in config, so scripted runs behave as before.
+
+### Security
+- **Lock file entries are validated.** Only skill folders under `.claude/skills/` / `.agents/skills/` and the known guideline files are honoured. Before this, a crafted `.ai/nestjs-boost.lock.json` could make `install` (and so `npm install`) delete any project folder whose hash it listed, and `uninstall --force` could target the project root.
+- **Symbolic links are never followed.** Writes and deletes refuse a link anywhere on the path. Links inside skill folders, `.ai/skills/` and `.ai/guidelines/` are skipped when hashing, copying or reading, so link loops and device files can't hang an install.
+- **Postinstall is opt-in and refresh-only.** It syncs only when the project has a lock file or a `"nestjs-boost"` config key, only when `nestjs-boost` is a direct dependency, and never under `npx`. Installing the package no longer adds agent instructions on its own; run `npx nestjs-boost install` once.
+- Block markers are stripped from project-supplied guideline text and skill descriptions, so they can't shift the managed block over user content.
+- Custom skill names in `.ai/skills/` must be lowercase-with-hyphens.
+- `scripts/validate.mjs` now runs on Windows. Before, it exited 0 without validating, which skipped the `npm test` / `prepublishOnly` gate there.
+- Release workflow: actions pinned to commit SHAs, npm pinned instead of `@latest`, publish job runs in an `npm-publish` environment, and the tag must match `package.json` and `manifest.json`.
+- `nestjs-openapi`: the Fastify helmet CSP example for Swagger UI now applies only when docs are enabled and no longer allows bare `https:` scripts.
+
+### Fixed
+- `manifest.json` version now follows `package.json` (it was `0.1.0`), and the validator checks they match.
+
+## 0.2.0 — 2026-11-06
+
+### npm package
+- `npm install -D nestjs-boost` installs the matching skills through a `postinstall` hook. The hook never fails an install, skips in CI (`NESTJS_BOOST_CI=1` opts in) and with `NESTJS_BOOST_SKIP=1`, and re-syncs on every install.
+- Hash-protected sync: skill folders you edited are never overwritten or deleted without `--force`, and skills for removed packages are pruned.
+- Agent detection from repository files; the default is Claude Code + Codex, which covers all four agents.
+- Config through a `"nestjs-boost"` key in `package.json` or `.ai/nestjs-boost.json`.
+- CLI: `install`, `list`, `uninstall`, plus `--dry-run`, `--force`, `--no-guidelines`, `--version`.
+- Zero dependencies, Node 20.19+, 18 tests (`node:test`), a Node skill validator run before publish, and CI plus trusted-publishing release workflows.
+- Per-skill evals moved from `skills/*/evals/` to `evals/skills/`, so they're no longer shipped or installed.
+
+### Skills
+
+- All **45 skills** written: 8 foundation + 37 package/operational skills, with 29 reference files (74 Markdown files under `skills/`).
+- Coverage: 159 documentation pages, every one owned by exactly one skill (or the core guidelines). All 136 requested URLs map to an owner (`coverage/requested-url-map.md`).
+- New in this release:
+  - HTTP and auth: http-platform, http-web-features, openapi, webhooks, authentication, authorization, passport-auth
+  - Data: TypeORM, Drizzle, Mongoose, Prisma, MikroORM, Sequelize, caching
+  - Application packages: events, scheduling, queues, http-client, mail, i18n, file-storage, cqrs, standalone-apps
+  - Reliability: resilience, idempotency, outbox, workflows, locks, health-checks, observability
+  - APIs: graphql, websockets, microservices
+  - AI: mcp-server, ai
+  - Operations: deployment, upgrading
+- Every skill passes `tools/validate_skills.py`, and every API claim was checked against the docs source.
+- New tool: `tools/condense.py` (per-skill digest of owned pages, used to ground skill writing).
+- Deferred: evals for the new skills, and the npm publish of the installer.
+
+## 0.1.0 — 2026-11-05
+
+- First build, from docs.nestjs.com @ `05c1fdfac8cf` (2026-11-04, NestJS 12).
+- Core guidelines template with detected project facts and a skill map.
+- 8 foundation skills: architecture, request-pipeline, validation-serialization, configuration, testing, cli-tooling, logging, security-hardening.
+- Installer prototype: `install` / `update` / `list`, with package-based skill selection, four agent targets, marker-based guideline blocks, `.ai/skills` and `.ai/guidelines` overrides, and a lock file.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nestjs-boost contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,6 @@
+# Notice
+
+The skills in this package are distilled from the official NestJS documentation
+(https://github.com/nestjs/docs.nestjs.com), Copyright (c) 2017-present Kamil Myśliwiec,
+licensed under the MIT License. nestjs-boost is a community project and is not affiliated
+with or endorsed by the NestJS team.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# nestjs-boost
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Agent Skills and project guidelines for AI-assisted **NestJS 12** development, for Claude Code, GitHub Copilot, Cursor, OpenAI Codex, Gemini CLI, Windsurf, Cline, Roo Code, Kiro, JetBrains Junie and OpenCode.
+
+Install it in a NestJS project. It detects which Nest packages you use, then copies in **only the skills you need**: 45 skills built from the official docs, covering everything from DI and testing to TypeORM, BullMQ, GraphQL, microservices, MCP and `@nestjs/ai`. It also adds a short guidelines block describing your project to each agent's instructions file (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`, ...).
+
+```bash
+npm install -D nestjs-boost
+npx nestjs-boost install
+```
+
+`install` asks which agents you use, shows what it will write, and installs after you confirm:
+
+```text
+? Which AI coding agents do you use?
+  ↑/↓ move · space select · a all/none · enter confirm · esc cancel
+❯ ◉ Claude Code                 .claude/skills/ · CLAUDE.md
+  ◯ OpenAI Codex                .agents/skills/ · AGENTS.md
+  ◯ GitHub Copilot              .github/skills/ · .github/copilot-instructions.md
+  ◉ Cursor          (detected)  .cursor/skills/ · AGENTS.md
+  ◯ Gemini CLI                  .gemini/skills/ · GEMINI.md
+  ...
+
+Skills: 14 skills (8 foundation, 6 for your packages)
+  .claude/skills/      read by Claude Code, Cursor
+Guidelines block: CLAUDE.md, AGENTS.md
+Changes: 16 new
+? Install now? (Y/n)
+```
+
+Agents already used in the repo are detected and pre-selected. Your choice is saved in `.ai/nestjs-boost.lock.json`, so later runs and `npm install` reuse it. Run `npx nestjs-boost install` again whenever you want to change it.
+
+The first `nestjs-boost install` is an explicit opt-in: installing the package alone never adds agent instructions to your project. After that, every `npm install` keeps the skills in sync.
+
+Commit the skill folders, instruction files and `.ai/nestjs-boost.lock.json` so the whole team and CI agents get the same skills.
+
+## Supported agents
+
+Every agent below supports the open [Agent Skills](https://agentskills.io) format (one `<name>/SKILL.md` folder per skill), so skills are copied unchanged into the folder that agent documents. Run `npx nestjs-boost agents` for the same table.
+
+| Agent | `--agents` id | Skills folder | Guidelines block in |
+| --- | --- | --- | --- |
+| Claude Code | `claude-code` | `.claude/skills/` | `CLAUDE.md` |
+| OpenAI Codex | `codex` | `.agents/skills/` | `AGENTS.md` |
+| GitHub Copilot | `copilot` | `.github/skills/` | `.github/copilot-instructions.md` |
+| Cursor | `cursor` | `.cursor/skills/` | `AGENTS.md` |
+| Gemini CLI | `gemini` | `.gemini/skills/` | `GEMINI.md` |
+| Windsurf | `windsurf` | `.windsurf/skills/` | `AGENTS.md` |
+| Cline | `cline` | `.cline/skills/` | `AGENTS.md` |
+| Roo Code | `roo` | `.roo/skills/` | `AGENTS.md` |
+| Kiro | `kiro` | `.kiro/skills/` | `AGENTS.md` |
+| JetBrains Junie | `junie` | `.junie/skills/` | `AGENTS.md` |
+| OpenCode | `opencode` | `.opencode/skills/` | `AGENTS.md` |
+
+**Shared folders.** Several agents also read other agents' folders. Cursor, Copilot and OpenCode read `.claude/skills/`; Gemini CLI, Roo Code, Cursor, Copilot and OpenCode read `.agents/skills/`. When you pick more than one agent, nestjs-boost installs each skill once into the folders that cover all of them, so no agent sees duplicates. For example, Claude Code + Cursor + Copilot share `.claude/skills/`. A single agent always gets its own folder. The install plan shows which agents read each folder.
+
+Using another agent that supports Agent Skills and `AGENTS.md`? Pick **OpenAI Codex**: `.agents/skills/` + `AGENTS.md` is the cross-agent convention.
+
+## How it works
+
+- **Selection:** the 8 foundation skills always install. Package skills install when their package is in `package.json` (for example `@nestjs/typeorm` → `nestjs-database-typeorm`). Monorepo `apps/*`, `libs/*` and `packages/*` are included. Run `npx nestjs-boost list` to see what was picked and why.
+- **Agents:** you pick them in `install`. Without a terminal to ask in (CI, piped output, `--yes`, the `postinstall` hook), nestjs-boost uses, in order: `--agents`, the `agents` config, your last choice from the lock file, then agents detected from repo files (`.claude/`, `.cursor/`, `.gemini/`, `.windsurf/`, `AGENTS.md`, ...). If nothing applies, it uses Claude Code + Codex, whose folders most agents read.
+- **Switching agents** removes what was installed for the agents you dropped: their skill folders, and the guidelines block in their instructions file. Files nestjs-boost created are deleted if nothing else is left in them. Folders you edited are kept.
+- **Updates:** once the project has opted in (it has `.ai/nestjs-boost.lock.json` from a first `nestjs-boost install`, or a `"nestjs-boost"` key in `package.json`), every `npm install` / `npm ci` re-syncs the skills:
+  - New packages get their skills.
+  - Upgrading `nestjs-boost` refreshes the skill text.
+  - Skills for removed packages are deleted.
+- **Your edits are safe.**
+  - A skill folder you changed is never overwritten or deleted. Changes are tracked by hash in the lock file.
+  - Text outside the `<!-- nestjs-boost:start/end -->` markers is never touched.
+  - It runs offline, has no dependencies, and writes only inside your project.
+
+## Package managers
+
+After the first `nestjs-boost install`, a `postinstall` script keeps the skills in sync. It runs only when `nestjs-boost` is a direct dependency of the project, never under `npx`. Some setups don't run dependency scripts. In that case, run the CLI again after adding Nest packages:
+
+```bash
+npx nestjs-boost install
+```
+
+| Setup | What to do |
+| --- | --- |
+| npm 11 (warns about unapproved install scripts) | `npm install-scripts approve nestjs-boost` (adds it to `allowScripts`) |
+| pnpm 10+ (blocks scripts by default) | `pnpm approve-builds`, or add `"pnpm": { "onlyBuiltDependencies": ["nestjs-boost"] }` |
+| Bun | add `"trustedDependencies": ["nestjs-boost"]` |
+| Yarn, npm ≤ 10 | nothing; scripts run |
+| `--ignore-scripts` | run `npx nestjs-boost install` |
+| CI (`CI` set) | skipped on purpose; set `NESTJS_BOOST_CI=1` to sync in CI |
+| Opt out temporarily | `NESTJS_BOOST_SKIP=1 npm install` |
+
+## Commands
+
+```bash
+npx nestjs-boost install               # pick agents, review the plan, install (opts the project in)
+npx nestjs-boost install --yes         # no questions: reuse the last choice (scripts, CI)
+npx nestjs-boost install --agents cursor,gemini   # choose agents without the picker
+npx nestjs-boost install --dry-run     # show the plan
+npx nestjs-boost install --force       # also overwrite skills you edited
+npx nestjs-boost list                  # detected facts + selected skills (writes nothing)
+npx nestjs-boost agents                # supported agents and their folders
+npx nestjs-boost uninstall             # remove skills, guideline blocks and the lock file
+```
+
+Options: `--agents <ids>` (see [Supported agents](#supported-agents)), `-y, --yes`, `--include <skills>`, `--exclude <skills>`, `--all`, `--no-guidelines`, `--root <dir>`.
+
+The picker appears only in an interactive terminal. It never appears in CI (`CI` set), when output is piped, with `--yes` or `--agents`, or when `agents` is set in config. Those runs never wait for input.
+
+## Configuration
+
+Settings persist in `package.json`, and the postinstall step uses them too. Adding this key also opts the project in to syncing on `npm install`, even before the first `nestjs-boost install`:
+
+```json
+{
+  "nestjs-boost": {
+    "agents": ["claude-code"],
+    "include": ["nestjs-deployment", "nestjs-upgrading"],
+    "exclude": ["nestjs-passport-auth"],
+    "guidelines": true
+  }
+}
+```
+
+You can put the same object in `.ai/nestjs-boost.json` instead. CLI flags override both. When `agents` is set here, `install` uses it and doesn't show the picker. Leave it out to choose interactively.
+
+## Customizing
+
+| Want to… | Do this |
+| --- | --- |
+| Change a pack skill for your team | Copy it to `.ai/skills/<skill-name>/` and edit it. Your version replaces the pack's on every sync |
+| Add your own skill | Create `.ai/skills/<new-name>/SKILL.md`. It's installed and listed in the guidelines skill map |
+| Add project rules to the guidelines | Add `.ai/guidelines/*.md`. These files are appended to the guidelines block |
+
+## Skills
+
+| Area | Skills |
+| --- | --- |
+| **Foundation** (always) | `nestjs-architecture`, `nestjs-request-pipeline`, `nestjs-validation-serialization`, `nestjs-configuration`, `nestjs-testing`, `nestjs-cli-tooling`, `nestjs-logging`, `nestjs-security-hardening` |
+| HTTP and API | `nestjs-http-platform`, `nestjs-http-web-features`, `nestjs-openapi`, `nestjs-graphql`, `nestjs-websockets`, `nestjs-webhooks` |
+| Auth | `nestjs-authentication`, `nestjs-authorization`, `nestjs-passport-auth` |
+| Data | `nestjs-database-typeorm`, `nestjs-database-drizzle`, `nestjs-database-prisma`, `nestjs-database-mongoose`, `nestjs-database-mikro-orm`, `nestjs-database-sequelize`, `nestjs-caching` |
+| Application | `nestjs-events`, `nestjs-scheduling`, `nestjs-queues`, `nestjs-http-client`, `nestjs-mail`, `nestjs-i18n`, `nestjs-file-storage`, `nestjs-cqrs`, `nestjs-standalone-apps`, `nestjs-microservices` |
+| Reliability and ops | `nestjs-resilience`, `nestjs-idempotency`, `nestjs-outbox`, `nestjs-workflows`, `nestjs-locks`, `nestjs-health-checks`, `nestjs-observability`, `nestjs-deployment`, `nestjs-upgrading` |
+| AI | `nestjs-mcp-server`, `nestjs-ai` |
+
+`nestjs-standalone-apps`, `nestjs-deployment` and `nestjs-upgrading` install only when their condition is met (`nest-commander`, a `Dockerfile`/`serverless.yml`, NestJS < 12) or when you `include` them.
+
+## Requirements
+
+- NestJS 12 projects. On older majors, the `list` command points you to `nestjs-upgrading`.
+- Node.js 20.19+.
+
+## Security
+
+The package has no dependencies and makes no network calls. It reads `package.json`, lockfile names, `nest-cli.json` and `.ai/`, and writes only the paths shown above, inside the project root. The install script never fails your install, and it never writes to a project that hasn't opted in. Source and skills are plain text you can review in `node_modules/nestjs-boost`.
+
+Hardening against a hostile repository or a tampered lock file:
+
+- **Lock file entries are not trusted.** Only `<agent skills folder>/<name>` folders (the folders in [Supported agents](#supported-agents)) and the agents' instructions files are honoured. Any other entry is ignored with a warning, so a lock file can't be used to delete other project files, even with `--force`.
+- **Symbolic links are never followed.** A link or junction on any path nestjs-boost writes to or deletes (for example a symlinked `.claude/`) stops the sync with an error. Links inside skill folders, `.ai/skills/` and `.ai/guidelines/` are skipped, never copied or read.
+- **The guideline block can't be hijacked.** Marker comments inside `.ai/guidelines/*.md` or a custom skill's description are stripped, so text outside the block stays yours.
+
+Report vulnerabilities privately through GitHub security advisories, not public issues.
+
+## License
+
+MIT. The skills are distilled from the [NestJS documentation](https://github.com/nestjs/docs.nestjs.com) (MIT); see `NOTICE.md`. This is a community project, not affiliated with the NestJS team.
+
+## Credits
+The NestJS team, with appreciation + love for their clean and clear documentation (https://github.com/nestjs/docs.nestjs.com).

package/bin/nestjs-boost.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AGENT_IDS, AGENT_LIST, BoostError, DEFAULT_AGENTS, MANIFEST, PACK_VERSION, sync, uninstall } from '../lib/installer.mjs';
+import { PromptCancelled, canPrompt } from '../lib/prompt.mjs';
+import { interactiveInstall } from '../lib/setup.mjs';
+
+const HELP = `nestjs-boost ${PACK_VERSION}: Agent Skills for NestJS ${MANIFEST.nestjs.targetMajor}
+
+Usage: nestjs-boost <command> [options]
+
+Commands:
+  install     Choose your AI coding agents, then install or refresh skills and guidelines (default)
+  list        Show detected facts and the skills that would be installed (writes nothing)
+  agents      Show the supported agents and where each one reads skills
+  uninstall   Remove installed skills, guideline blocks and the lock file
+
+Options:
+  --agents <list>    Skip the picker: ${AGENT_IDS.join(',')}
+                     (default: last choice, else detected, else ${DEFAULT_AGENTS.join(',')})
+  -y, --yes          Don't ask anything; use the last choice or detected agents
+  --include <list>   Add skills whose packages aren't detected (e.g. nestjs-deployment)
+  --exclude <list>   Skip skills
+  --all              Install every skill
+  --no-guidelines    Don't write the guidelines block into CLAUDE.md / AGENTS.md / ...
+  --force            Overwrite or remove skill folders you edited
+  --dry-run          Show the plan without writing
+  --root <dir>       Project root (default: current directory)
+  -v, --version      Print the version
+  -h, --help         Print this help
+
+\`install\` asks which agents you use when run in an interactive terminal. It never asks in CI,
+when output is piped, with --yes or --agents, or when agents are set in config.
+
+Config: a "nestjs-boost" key in package.json (or .ai/nestjs-boost.json) accepts
+{ "agents": [], "include": [], "exclude": [], "all": false, "guidelines": true }.`;
+
+const COMMANDS = ['install', 'update', 'list', 'agents', 'uninstall'];
+
+export function parseArgs(argv) {
+  const flags = new Set(['dry-run', 'all', 'force', 'help', 'version', 'no-guidelines', 'yes', 'no-interactive']);
+  const short = { '-h': 'help', '-v': 'version', '-y': 'yes' };
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (short[a]) { args[short[a]] = true; continue; }
+    if (!a.startsWith('--')) { args._.push(a); continue; }
+    const [key, inline] = a.slice(2).split('=', 2);
+    if (flags.has(key)) args[key] = true;
+    else if (inline !== undefined) args[key] = inline;
+    else if (argv[i + 1] === undefined || argv[i + 1].startsWith('-')) throw new BoostError(`--${key} needs a value`);
+    else args[key] = argv[++i];
+  }
+  return args;
+}
+
+const SIGN = { add: '+', update: '~', remove: '-' };
+
+// Skill-folder changes are grouped per folder ("+ .claude/skills/ 12 skills: a, b, c, …") so a
+// full install stays readable; other changes (guideline files) are listed one per line.
+export function formatChanges(changes) {
+  const groups = new Map();
+  const lines = [];
+  for (const c of changes) {
+    const m = c.path.match(/^(.+\/skills)\/([a-z0-9-]+)$/);
+    if (!m) { lines.push(`  ${SIGN[c.action]} ${c.path}`); continue; }
+    const key = `${c.action} ${m[1]}`;
+    if (!groups.has(key)) groups.set(key, { action: c.action, dir: m[1], names: [] });
+    groups.get(key).names.push(m[2]);
+  }
+  const grouped = [...groups.values()].map(({ action, dir, names }) => {
+    const shown = names.slice(0, 4).join(', ') + (names.length > 4 ? ', …' : '');
+    return `  ${SIGN[action]} ${dir}/ ${names.length} skill${names.length === 1 ? '' : 's'}: ${shown}`;
+  });
+  return [...grouped, ...lines];
+}
+
+function printFacts({ facts, skills, custom, opts }) {
+  const target = MANIFEST.nestjs.targetMajor;
+  console.log(`nestjs-boost ${PACK_VERSION}: NestJS ${facts.coreVersion}${facts.nestMajor && facts.nestMajor !== target ? ` (skills target ${target}; see nestjs-upgrading)` : ''}`);
+  console.log(`  ${facts.adapter} | ${facts.esm ? 'ESM' : 'CommonJS'} | tests: ${facts.testRunner} | lint: ${facts.linter} | ${facts.pm}${facts.monorepo ? ' | monorepo' : ''}`);
+  console.log(`  agents: ${opts.agents.join(', ')} (${opts.agentSource})`);
+  console.log(`Skills (${skills.length}${custom.length ? ` + ${custom.length} project` : ''}):`);
+  for (const s of skills) console.log(`  ${s.name.padEnd(34)} ${s.reason}`);
+  for (const n of custom) console.log(`  ${n.padEnd(34)} .ai/skills (project)`);
+}
+
+function print(result, { verbose = true } = {}) {
+  const { facts, changes, warnings, dryRun } = result;
+  if (facts && verbose) printFacts(result);
+  if (changes.length) {
+    console.log(dryRun ? 'Would change:' : 'Changed:');
+    for (const line of formatChanges(changes)) console.log(line);
+  } else if (verbose) console.log(dryRun ? 'Nothing would change.' : 'Already up to date.');
+  for (const w of warnings) console.warn(`  ! ${w}`);
+}
+
+function printAgents() {
+  const w = Math.max(...AGENT_LIST.map((a) => a.id.length)) + 2;
+  const n = Math.max(...AGENT_LIST.map((a) => a.name.length)) + 2;
+  console.log(`${'id'.padEnd(w)}${'agent'.padEnd(n)}${'skills folder'.padEnd(20)}instructions file`);
+  for (const a of AGENT_LIST) console.log(`${a.id.padEnd(w)}${a.name.padEnd(n)}${`${a.skills.dir}/`.padEnd(20)}${a.instructions}`);
+  console.log('\nWhen several agents read the same folder, skills are installed once and shared.');
+}
+
+export async function main(argv = process.argv.slice(2), io) {
+  const args = parseArgs(argv);
+  if (args.version) return console.log(PACK_VERSION);
+  const command = args._[0] ?? 'install';
+  if (args.help || !COMMANDS.includes(command)) {
+    console.log(HELP);
+    process.exitCode = args.help ? 0 : 2;
+    return;
+  }
+  if (command === 'agents') return printAgents();
+  const root = resolve(args.root ?? process.cwd());
+  const run = { dryRun: Boolean(args['dry-run']) || command === 'list', force: Boolean(args.force) };
+  if (command === 'uninstall') return print(uninstall(root, run));
+  const explicit = {
+    agents: args.agents, include: args.include, exclude: args.exclude,
+    all: args.all || undefined, guidelines: args['no-guidelines'] ? false : undefined,
+  };
+
+  const interactive = command !== 'list' && !run.dryRun && !args.yes && !args['no-interactive']
+    && args.agents === undefined && !process.env.CI && canPrompt(io);
+  if (!interactive) return print(sync(root, explicit, run));
+
+  const result = await interactiveInstall(root, explicit, run, io);
+  if (!result) { console.log('Nothing installed.'); return; }
+  if (!result.changes.length) { console.log('Already up to date.'); return; }
+  print(result, { verbose: false });
+  console.log('\nDone. Commit the files above and .ai/nestjs-boost.lock.json so your team gets the same skills.');
+  console.log('Run `npx nestjs-boost install` again any time to change agents.');
+}
+
+// Run only when executed as the CLI (directly, via npx or a node_modules/.bin link), not when
+// imported by tests. Real paths, because bin links and Windows drive-letter case differ.
+const invokedDirectly = () => {
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); } catch { return false; }
+};
+if (invokedDirectly()) {
+  main().catch((err) => {
+    if (err instanceof PromptCancelled) { console.log('\nCancelled; nothing was changed.'); process.exitCode = 130; return; }
+    console.error(`nestjs-boost: ${err instanceof BoostError ? err.message : err.stack}`);
+    process.exitCode = 1;
+  });
+}

package/guidelines/core.md

@@ -0,0 +1,64 @@
+## NestJS project guidelines (nestjs-boost)
+
+This is a **NestJS {{nestjsVersion}}** project. Follow these rules on every task; load the skill named in the skill map for detail. The pack was built from the official docs at https://docs.nestjs.com (crawled {{docsCrawled}}). Where your training data disagrees with these files, these files win: NestJS 12 changed many defaults.
+
+### Project facts (detected)
+
+| Fact | Value |
+| --- | --- |
+| HTTP adapter | {{httpAdapter}} |
+| Module format | {{moduleFormat}} |
+| Test runner | {{testRunner}} |
+| Linter | {{linter}} |
+| Package manager | {{packageManager}} |
+| Validation | {{validation}} |
+
+{{esmNote}}
+
+### Commands: verify before you report done
+
+Run these after every change, and fix failures before saying a task is finished:
+
+```bash
+{{buildCommand}}
+{{lintCommand}}
+{{testCommand}}
+{{e2eCommand}}
+```
+
+When a change affects startup (modules, DI, `main.ts`, configuration), also start the built app once (`{{startCommand}}`), because DI errors only appear at bootstrap, not at compile time.
+
+### Scaffold with the CLI, then edit
+
+Use `nest generate` instead of writing boilerplate by hand. It places files where Nest expects them, updates the parent module, and adds spec files. Preview with `--dry-run`.
+
+```bash
+npx nest g resource <name>      # module + controller + service + DTOs + entity + specs
+npx nest g module|controller|service|guard|interceptor|pipe|filter|decorator <name>
+```
+
+### Rules that apply everywhere
+
+- **Feature modules.** Group each feature's controller, providers and DTOs in its own module. A provider another module needs must be in its module's `exports`, and the consumer must import that module. Never re-register another module's provider in your own `providers`: that creates a second instance. Avoid `@Global()` except for truly app-wide infrastructure.
+- **Injection tokens exist at runtime.** Constructor injection by type needs a class. Interfaces and type aliases are erased, so inject those with `@Inject(TOKEN)`, using a string, symbol or `InjectionToken`.
+- **No barrel files** (`index.ts`) for module and provider classes; they cause circular-dependency errors.
+- **Request lifecycle order:**
+    1. middleware
+    2. guards (global → controller → route)
+    3. interceptors before the handler
+    4. pipes (global → controller → route → parameter)
+    5. the handler
+    6. interceptors after the handler (route → controller → global)
+    7. exception filters (route → controller → global; the first matching filter wins)
+- **Global enhancers that need DI** are registered as providers: `{ provide: APP_GUARD | APP_PIPE | APP_INTERCEPTOR | APP_FILTER, useClass: X }`. `app.useGlobal*()` in `main.ts` cannot inject dependencies, and tests that build the app with `Test.createTestingModule()` never run `main.ts`, so they miss it.
+- **Errors:** throw Nest's HTTP exceptions (`NotFoundException`, `BadRequestException`, ...). Give clients a stable code with the `errorCode` option, e.g. `new BadRequestException('Cart is empty', { errorCode: 'CART_EMPTY' })`.
+- **Logging:** use `new Logger(MyService.name)` from `@nestjs/common`, never `console.log`. Pass structured fields as a plain object after the message: `logger.log('User created', { userId })`.
+- **Configuration and secrets** come from `@nestjs/config` (`ConfigService`), never hard-coded values or committed `.env` files.
+- **Tests** use `@nestjs/testing` (`Test.createTestingModule`) with the project's runner API ({{testRunnerApi}}).
+- **Upgrades:** after changing NestJS packages, use `nest upgrade`, which moves all `@nestjs/*` packages together.
+
+### Skill map
+
+Load the matching skill before starting a task in its area:
+
+{{skillMap}}

package/lib/agents.mjs

@@ -0,0 +1,137 @@
+// Registry of supported AI coding agents. This is the only place that knows where each agent reads
+// skills and project instructions; the installer, CLI picker, lock-file validation and docs all
+// derive from it. To add an agent, add one entry (see CONTRIBUTING.md → "Adding an agent").
+//
+// Every agent here supports the open Agent Skills format (a `<name>/SKILL.md` folder per skill),
+// so skills are copied unchanged; only the location differs.
+//
+// Fields:
+//   id            stable key used in --agents, config and the lock file (never rename one)
+//   name          display name in the picker
+//   skills.dir    the agent's native project skills folder (its documented, recommended location)
+//   skills.reads  every project skills folder the agent loads, native first. Used to avoid
+//                 installing the same skills twice when several agents share a folder.
+//   instructions  the always-loaded project instructions file the guidelines block goes into
+//   markers       files/folders whose presence means the project already uses this agent
+//   docs          where the conventions above are documented
+export const AGENT_LIST = [
+  {
+    id: 'claude-code',
+    name: 'Claude Code',
+    skills: { dir: '.claude/skills', reads: ['.claude/skills'] },
+    instructions: 'CLAUDE.md',
+    markers: ['.claude', 'CLAUDE.md'],
+    docs: 'https://code.claude.com/docs/en/skills',
+  },
+  {
+    id: 'codex',
+    name: 'OpenAI Codex',
+    hint: 'also any tool using .agents/skills + AGENTS.md',
+    skills: { dir: '.agents/skills', reads: ['.agents/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.codex', '.agents', 'AGENTS.md'],
+    docs: 'https://developers.openai.com/codex/skills',
+  },
+  {
+    id: 'copilot',
+    name: 'GitHub Copilot',
+    skills: { dir: '.github/skills', reads: ['.github/skills', '.claude/skills', '.agents/skills'] },
+    instructions: '.github/copilot-instructions.md',
+    markers: ['.github/copilot-instructions.md', '.github/instructions', '.github/skills'],
+    docs: 'https://docs.github.com/en/copilot/how-tos/use-copilot-agents/cloud-agent/create-skills',
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    skills: { dir: '.cursor/skills', reads: ['.cursor/skills', '.agents/skills', '.claude/skills', '.codex/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.cursor', '.cursorrules'],
+    docs: 'https://cursor.com/docs/skills',
+  },
+  {
+    id: 'gemini',
+    name: 'Gemini CLI',
+    skills: { dir: '.gemini/skills', reads: ['.gemini/skills', '.agents/skills'] },
+    instructions: 'GEMINI.md',
+    markers: ['.gemini', 'GEMINI.md'],
+    docs: 'https://geminicli.com/docs/cli/creating-skills',
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    skills: { dir: '.windsurf/skills', reads: ['.windsurf/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.windsurf', '.windsurfrules'],
+    docs: 'https://docs.windsurf.com/windsurf/cascade/skills',
+  },
+  {
+    id: 'cline',
+    name: 'Cline',
+    skills: { dir: '.cline/skills', reads: ['.cline/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.cline', '.clinerules'],
+    docs: 'https://docs.cline.bot/customization/skills',
+  },
+  {
+    id: 'roo',
+    name: 'Roo Code',
+    skills: { dir: '.roo/skills', reads: ['.roo/skills', '.agents/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.roo', '.roorules'],
+    docs: 'https://docs.roocode.com/features/skills',
+  },
+  {
+    id: 'kiro',
+    name: 'Kiro',
+    skills: { dir: '.kiro/skills', reads: ['.kiro/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.kiro'],
+    docs: 'https://kiro.dev/docs/skills/',
+  },
+  {
+    id: 'junie',
+    name: 'JetBrains Junie',
+    skills: { dir: '.junie/skills', reads: ['.junie/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.junie'],
+    docs: 'https://junie.jetbrains.com/docs/agent-skills.html',
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    skills: { dir: '.opencode/skills', reads: ['.opencode/skills', '.claude/skills', '.agents/skills'] },
+    instructions: 'AGENTS.md',
+    markers: ['.opencode', 'opencode.json', 'opencode.jsonc'],
+    docs: 'https://opencode.ai/docs/skills',
+  },
+];
+
+export const AGENTS = Object.fromEntries(AGENT_LIST.map((a) => [a.id, a]));
+export const AGENT_IDS = AGENT_LIST.map((a) => a.id);
+
+// Used when nothing is detected and no one is asked (postinstall, CI, non-interactive shells).
+// Between them, .claude/skills and .agents/skills are read by most agents in the registry.
+export const DEFAULT_AGENTS = ['claude-code', 'codex'];
+
+// Every folder any agent loads skills from, and every instructions file: the only places
+// nestjs-boost may ever write. The lock-file allowlist is built from these.
+export const ALL_SKILL_DIRS = [...new Set(AGENT_LIST.flatMap((a) => a.skills.reads))];
+export const ALL_INSTRUCTION_FILES = [...new Set(AGENT_LIST.map((a) => a.instructions))];
+
+// Choose the fewest skills folders that every selected agent reads, so no agent sees each skill
+// twice. Agents that read the fewest folders choose first (they have no alternative); an agent
+// whose folders already include a chosen one is covered. A single agent always gets its native
+// folder. Deterministic: the same selection always gives the same folders.
+export function planSkillDirs(agentIds) {
+  const agents = agentIds.map((id) => AGENTS[id]);
+  const order = [...agents].sort((a, b) => a.skills.reads.length - b.skills.reads.length
+    || AGENT_IDS.indexOf(a.id) - AGENT_IDS.indexOf(b.id));
+  const dirs = [];
+  for (const a of order) {
+    if (!a.skills.reads.some((d) => dirs.includes(d))) dirs.push(a.skills.dir);
+  }
+  // Report which agents read each chosen folder (for the plan shown to the user).
+  return dirs.map((dir) => ({ dir, agents: agents.filter((a) => a.skills.reads.includes(dir)).map((a) => a.id) }));
+}
+
+export const instructionFiles = (agentIds) => [...new Set(agentIds.map((id) => AGENTS[id].instructions))];