docs(AGENTS.md): refine (#1251)

Author: fi3ework

AGENTS.md

@@ -1,44 +1,52 @@
 # Repository guidelines
 
+## Setup environment
+
+1. Install [fnm](https://github.com/Schniz/fnm) and run `fnm install`/`fnm use` to match the Node.js version in `.nvmrc` (`v24.5.0`).
+2. Enable Corepack (`corepack enable`) and then activate pnpm via `corepack prepare` (the pnpm version is specified in `packageManager` field in `package.json`).
+3. Clone the repository and install dependencies with `pnpm install` from the repository root.
+
 ## Project structure & module organization
 
-- Monorepo via `pnpm` + `Nx`.
-- Packages: `packages/core` (CLI + `@rslib/core`), `packages/plugin-dts` (DTS plugin), `packages/create-rslib` (scaffolder).
-- Tests: `packages/*/tests` (unit) and `tests/` (`integration`, `e2e`, `benchmark`); examples in `examples/`.
-- Key config: `nx.json`, `biome.json`, `.prettierrc.json`, `rslint.jsonc`, `pnpm-workspace.yaml`.
+- Monorepo via the `pnpm` workspace.
+- `packages/core` (`@rslib/core`): CLI entry (`rslib build`, `--watch`) and programmatic helpers (`build`, `defineConfig`, `loadConfig`).
+- `packages/plugin-dts` (`rsbuild-plugin-dts`): provides the `dts` configuration hook (e.g., `{ dts: { bundle: true } }`).
+- `packages/create-rslib` (`create-rslib`): scaffolds new projects via `pnpm dlx create-rslib` or `npx create-rslib`.
+- Tests live in `packages/*/tests` (unit) and `tests/` (`integration`, `e2e`, `benchmark`); examples in `examples/`.
+- Key configuration files: `nx.json`, `biome.json`, `.prettierrc.json`, `rslint.jsonc`, `pnpm-workspace.yaml`.
 
 ## Build, test, and development commands
 
-- Install: `pnpm install` (Node >= 18.12, pnpm >= 10.15).
+- Install: `pnpm install` (all packages will be built in postinstall).
 - Build: `pnpm build` (all) and `pnpm build:examples`.
 - Watch dev: `pnpm -C packages/core dev` (or other package).
 - Lint/format: `pnpm lint`; auto-fix: `pnpm format`.
 - Type-check: `pnpm type-check`.
-- Tests: `pnpm test`; targeted: `test:unit|:integration|:e2e|:benchmark`; update snapshots: `pnpm testu`.
+- Tests:
+  - `pnpm test` runs the entire suites.
+  - `pnpm test:unit` scopes to unit tests.
+  - `pnpm test:integration` scopes to integration tests; add `<pattern>` to match specific cases.
+  - `pnpm test:e2e` runs end-to-end tests.
 
 ## Coding style & naming conventions
 
 - TypeScript + ESM; spaces; single quotes.
 - Biome is canonical linter/formatter; Prettier formats MD/CSS/JSON and `package.json`.
+- Run `pnpm biome check --write --unsafe` on modified source files; when `package.json` changes, also run `prettier --write package.json`.
 - Filenames: `camelCase` or `PascalCase` (Biome enforced).
 
 ## Testing guidelines
 
 - Unit/integration: `@rstest/core`; E2E: `@playwright/test`.
 - Naming: `*.test.ts`/`*.test.tsx`; snapshots in `__snapshots__/`.
 - Placement: unit under `packages/*/tests`; integration under `tests/integration`; e2e under `tests/e2e`.
+- Target specific integration cases: `pnpm test:integration <pattern>` (faster than the full suite).
 
 ## Commit & pull request guidelines
 
 - Conventional Commits (e.g., `fix(dts): ...`); keep commits focused; run lint + tests.
 - User-facing changes need a Changeset (`pnpm changeset`); PRs should include description, linked issues, and doc/example updates when needed.
 
-## Architecture overview
-
-- `packages/core` (`@rslib/core`): CLI `rslib build` (add `--watch`), config via `rslib.config.ts` using `defineConfig`; programmatic `import { build, defineConfig, loadConfig } from '@rslib/core'`.
-- `packages/plugin-dts` (`rsbuild-plugin-dts`): detail implementation of `dts` in `rslib.config.ts` (e.g., `{ dts: { bundle: true } }`);
-- `packages/create-rslib` (`create-rslib`): scaffold new projects/templates with `pnpm dlx create-rslib` (or `npx create-rslib`).
-
 ## Security & configuration tips
 
 - Do not commit build artifacts (`dist/`, `compiled/`).

packages/create-rslib/AGENTS.md

@@ -0,0 +1,24 @@
+# Package guidelines — create-rslib
+
+This guide extends the repository instructions in `../../AGENTS.md`. Refer there for workspace setup, tooling versions, and global workflows.
+
+## Package overview
+
+- `create-rslib` provides the `pnpm create rslib` scaffolding CLI shipped from `dist/`.
+- Author source changes under `src/`; treat `dist/` as build output regenerated via `pnpm -C packages/create-rslib build`.
+- Template inputs live in `fragments/`; generated scaffolding blueprints are the `template-*` directories.
+- Tests in `test/` use `@rstest/core` to exercise CLI flows and validate generated projects.
+
+## Common commands
+
+- Build once before testing locally: `pnpm -C packages/create-rslib build`.
+- Watch rebuild during development: `pnpm -C packages/create-rslib dev`.
+- Regenerate template directories after touching fragments or generators: `pnpm -C packages/create-rslib generate-templates`.
+- Run package tests: `pnpm -C packages/create-rslib test`; the repo-level `pnpm test:unit` also covers this package.
+
+## Working on templates
+
+- Add or update base files in `fragments/base/*` and tool overlays in `fragments/tools/*`; keep naming aligned with `src/helpers.ts`.
+- Update `TEMPLATES` in `src/helpers.ts` whenever you introduce a new template combination so the CLI prompts and tests remain exhaustive.
+- Treat `template-*` directories as generated output from `pnpm -C packages/create-rslib generate-templates`; keep changes reproducible by updating generators in `src/` or fragments under `fragments/` instead of editing the generated files directly.
+- Keep dependency versions aligned across all `template-*` directories; when one template upgrades a shared dependency, update the others via fragments or generators to match.