@regardio/dev 2.4.1 → 2.5.0

package/dist/bin/ship/hotfix.bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as git, c as runScript, i as getWorkspacePackages, n as chooseForEach, o as gitRead, s as runQualityChecks, t as branchExists } from "./utils-rnvdLrkF.mjs";
+import { a as git, c as runQualityChecks, i as getWorkspacePackages, n as chooseForEach, o as gitRead, s as runPackageRelease, t as branchExists } from "./utils-BPxpSgv6.mjs";
 //#region src/bin/ship/hotfix.ts
 /**
 * ship-hotfix: Manage hotfix branches based on production code.
@@ -52,6 +52,8 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 			console.error("Working directory has uncommitted changes. Commit or stash them first.");
 			process.exit(1);
 		}
+		console.log("\nFetching latest state from origin...");
+		git("fetch", "origin");
 		console.log("\nRunning quality checks...");
 		try {
 			runQualityChecks();
@@ -61,27 +63,21 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		}
 		console.log("✅ Quality checks passed");
 		const packages = getWorkspacePackages(cwd);
-		if (packages.length === 0) {
-			console.error("No publishable workspace packages found.");
-			process.exit(1);
-		}
-		console.log("\nSelect a version bump for each package (or skip):");
-		const bumps = chooseForEach(packages);
-		if (bumps.length === 0) {
-			console.log("\nNo packages selected for release. Aborted.");
-			process.exit(0);
-		}
-		console.log("\nBumping versions and updating CHANGELOGs...");
-		const hasMajor = bumps.some((b) => b.bump === "major");
-		const hasMinor = bumps.some((b) => b.bump === "minor");
-		const highestBump = hasMajor ? "major" : hasMinor ? "minor" : "patch";
-		try {
-			runScript(`release:${highestBump}`);
-		} catch {
-			console.log("No release script found - skipping versioning (non-publishing repo)");
-		}
-		console.log("\nFetching latest state from origin...");
-		git("fetch", "origin");
+		const bumps = [];
+		if (packages.length > 0) {
+			console.log("\nSelect a version bump for each package (or skip):");
+			bumps.push(...chooseForEach(packages));
+			if (bumps.length === 0) {
+				console.log("\nNo packages selected for release. Aborted.");
+				process.exit(0);
+			}
+			console.log("\nBumping versions and updating CHANGELOGs...");
+			for (const { package: pkg, bump } of bumps) try {
+				runPackageRelease(pkg.path, bump);
+			} catch {
+				console.log(`No versioning configured for ${pkg.name} — skipping.`);
+			}
+		} else console.log("No publishable packages — skipping versioning.");
 		console.log("\nMerging hotfix into production...");
 		git("checkout", "production");
 		git("pull", "--ff-only", "origin", "production");
@@ -101,9 +97,11 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		try {
 			git("push", "origin", "--delete", currentBranch);
 		} catch {}
-		const shipped = bumps.map((b) => b.package.name).join(", ");
-		console.log(`\n✅ Hotfix ${shipped} shipped to production → staging → main`);
-		console.log("CI will publish changed packages to npm.");
+		if (bumps.length > 0) {
+			const shipped = bumps.map((b) => b.package.name).join(", ");
+			console.log(`\n✅ Hotfix ${shipped} shipped to production → staging → main`);
+			console.log("CI will publish changed packages to npm.");
+		} else console.log("\n✅ Hotfix shipped to production → staging → main.");
 		console.log("You are on main and ready to keep working.");
 		process.exit(0);
 	}

package/dist/bin/ship/production.bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as git, c as runScript, i as getWorkspacePackages, n as chooseForEach, o as gitRead, r as confirm, s as runQualityChecks, t as branchExists } from "./utils-rnvdLrkF.mjs";
+import { a as git, c as runQualityChecks, i as getWorkspacePackages, n as chooseForEach, o as gitRead, r as confirm, s as runPackageRelease, t as branchExists } from "./utils-BPxpSgv6.mjs";
 //#region src/bin/ship/production.ts
 /**
 * ship-production: Promote main to production following the GitLab workflow.
@@ -51,29 +51,25 @@ function runShipProduction(cwd = process.cwd()) {
 	}
 	console.log("✅ Quality checks passed");
 	const packages = getWorkspacePackages(cwd);
-	if (packages.length === 0) {
-		console.error("No publishable workspace packages found.");
-		process.exit(1);
-	}
-	console.log("\nSelect a version bump for each package (or skip):");
-	const bumps = chooseForEach(packages);
-	if (bumps.length === 0) {
-		console.log("\nNo packages selected for release. Aborted.");
-		process.exit(0);
-	}
-	if (!confirm(`\nShip to production?\n${bumps.map((b) => `  ${b.package.name}  →  ${b.bump}`).join("\n")}\n`)) {
-		console.log("Aborted.");
-		process.exit(0);
-	}
-	console.log("\nBumping versions and updating CHANGELOGs...");
-	const hasMajor = bumps.some((b) => b.bump === "major");
-	const hasMinor = bumps.some((b) => b.bump === "minor");
-	const highestBump = hasMajor ? "major" : hasMinor ? "minor" : "patch";
-	try {
-		runScript(`release:${highestBump}`);
-	} catch {
-		console.log("No release script found - skipping versioning (non-publishing repo)");
-	}
+	const bumps = [];
+	if (packages.length > 0) {
+		console.log("\nSelect a version bump for each package (or skip):");
+		bumps.push(...chooseForEach(packages));
+		if (bumps.length === 0) {
+			console.log("\nNo packages selected for release. Aborted.");
+			process.exit(0);
+		}
+		if (!confirm(`\nShip to production?\n${bumps.map((b) => `  ${b.package.name}  →  ${b.bump}`).join("\n")}\n`)) {
+			console.log("Aborted.");
+			process.exit(0);
+		}
+		console.log("\nBumping versions and updating CHANGELOGs...");
+		for (const { package: pkg, bump } of bumps) try {
+			runPackageRelease(pkg.path, bump);
+		} catch {
+			console.log(`No versioning configured for ${pkg.name} — skipping.`);
+		}
+	} else if (!confirm("\nNo publishable packages — ship commits to production?\n")) process.exit(0);
 	console.log("\nMerging main into production...");
 	git("checkout", "production");
 	git("pull", "--ff-only", "origin", "production");
@@ -86,8 +82,10 @@ function runShipProduction(cwd = process.cwd()) {
 	git("push", "origin", "staging");
 	git("checkout", "main");
 	git("push", "--follow-tags", "origin", "main");
-	const shipped = bumps.map((b) => b.package.name).join(", ");
-	console.log(`\n✅ Shipped ${shipped} to production. CI will publish changed packages to npm.`);
+	if (bumps.length > 0) {
+		const shipped = bumps.map((b) => b.package.name).join(", ");
+		console.log(`\n✅ Shipped ${shipped} to production. CI will publish changed packages to npm.`);
+	} else console.log("\n✅ Commits shipped to production.");
 	console.log("You are on main and ready to keep working.");
 }
 //#endregion

package/dist/bin/ship/staging.bin.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as git, o as gitRead, s as runQualityChecks, t as branchExists } from "./utils-rnvdLrkF.mjs";
+import { a as git, c as runQualityChecks, o as gitRead, t as branchExists } from "./utils-BPxpSgv6.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 //#region src/bin/ship/staging.ts

package/dist/bin/ship/{utils-rnvdLrkF.mjs → utils-BPxpSgv6.mjs}

@@ -19,6 +19,13 @@ const runScript = (script) => {
 	console.log(`$ pnpm ${script}`);
 	execSync(`pnpm ${script}`, { stdio: "inherit" });
 };
+const runPackageRelease = (pkgPath, bump) => {
+	console.log(`$ commit-and-tag-version --release-as ${bump}`);
+	execSync(`pnpm exec commit-and-tag-version --release-as ${bump}`, {
+		cwd: pkgPath,
+		stdio: "inherit"
+	});
+};
 const runQualityChecks = () => {
 	runScript("lint");
 	runScript("typecheck");
@@ -120,4 +127,4 @@ const choose = (prompt, options, ttyPath = "/dev/tty") => {
 	return chosen.value;
 };
 //#endregion
-export { git as a, runScript as c, getWorkspacePackages as i, chooseForEach as n, gitRead as o, confirm as r, runQualityChecks as s, branchExists as t };
+export { git as a, runQualityChecks as c, getWorkspacePackages as i, chooseForEach as n, gitRead as o, confirm as r, runPackageRelease as s, branchExists as t };

package/docs/en/tools/biome.md

@@ -11,7 +11,7 @@ area: "dev"
 
 # Biome
 
-[Biome](https://biomejs.dev/) is the linter and formatter every Regardio package reaches for. Configuration is centralised through `@regardio/dev`, and wrapper commands keep every package behaving the same way.
+[Biome](https://biomejs.dev/) is the linter and formatter every Regardio package reaches for. Configuration is centralised through `@regardio/dev`.
 
 ## Configuration
 
@@ -29,34 +29,22 @@ A `biome.jsonc` at the package root is all it takes:
 ```json
 {
   "scripts": {
-    "fix": "exec-s fix:pkg fix:md fix:biome",
-    "fix:biome": "lint-biome check --write --unsafe .",
-    "lint": "exec-s lint:md lint:biome",
-    "lint:biome": "lint-biome check ."
+    "fix:biome": "biome check --write --unsafe .",
+    "lint:biome": "biome check ."
   }
 }
 ```
 
-## CLI wrapper
-
-Use `lint-biome` rather than `biome` directly — the wrapper keeps behaviour consistent across the monorepo.
-
-```bash
-lint-biome check .           # Check for issues
-lint-biome check --write .   # Fix the auto-fixable
-lint-biome format .          # Format only
-```
-
 ## `package.json` handling
 
-The Biome preset leaves `package.json` alone. For those files, `lint-package` does the work:
+The Biome preset leaves `package.json` alone. For those files, use `sort-package-json`:
 
 1. Sorts `package.json` using the well-known field order
 2. Fixes export-condition order (`types` before `default` for TypeScript)
 
 ```bash
-lint-package              # Sort package.json in current directory
-lint-package path/to/pkg  # Sort a specific package.json
+pnpm sort-package-json              # Sort package.json in current directory
+pnpm sort-package-json path/to/pkg  # Sort a specific package.json
 ```
 
 It runs automatically as part of `pnpm fix`.

package/docs/en/tools/husky.md

@@ -20,7 +20,7 @@ Husky configures itself through the `prepare` script:
 ```json
 {
   "scripts": {
-    "prepare": "exec-husky"
+    "prepare": "husky"
   }
 }
 ```
@@ -35,7 +35,8 @@ Validates commit messages against the conventional-commit format:
 
 ```bash
 #!/bin/sh
-pnpm lint-commit --edit $1
+. "$(dirname "$0")/_/husky.sh"
+commitlint --edit $1
 ```
 
 ### `pre-commit` (optional)
@@ -47,10 +48,6 @@ Runs linting before a commit lands:
 pnpm lint
 ```
 
-## CLI wrapper
-
-`exec-husky` takes the place of `husky` directly — the wrapper handles monorepo scenarios that bare Husky doesn't.
-
 ## Bypassing hooks
 
 In the rare case where a hook truly has to be skipped:

package/docs/en/tools/markdownlint.md

@@ -11,7 +11,7 @@ area: "dev"
 
 # Markdownlint
 
-Markdownlint checks Markdown structure and formatting. The rules live in `@regardio/dev`; projects reach for the `lint-md` wrapper rather than calling the tool directly.
+Markdownlint checks Markdown structure and formatting. The rules live in `@regardio/dev`.
 
 ## Configuration
 
@@ -28,21 +28,12 @@ A `.markdownlint.json` at the package root:
 ```json
 {
   "scripts": {
-    "fix:md": "lint-md --fix \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
-    "lint:md": "lint-md \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\""
+    "fix:md": "markdownlint-cli2 --fix \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\"",
+    "lint:md": "markdownlint-cli2 \"**/*.md\" \"**/*.mdx\" \"!**/node_modules/**\" \"!**/dist/**\""
   }
 }
 ```
 
-## CLI wrapper
-
-Use `lint-md` rather than `markdownlint-cli2` directly:
-
-```bash
-lint-md "**/*.md"              # Check all Markdown files
-lint-md --fix "**/*.md"        # Auto-fix what can be auto-fixed
-```
-
 ## Key rules
 
 | Rule | Description |

package/docs/en/tools/releases.md

@@ -1,8 +1,8 @@
 ---
 
 title: "Release Workflow"
-description: "Branch-based release workflow for Regardio packages — main → staging → production, driven by commit-and-tag-version."
-publishedAt: 2026-04-17
+description: "GitLab-flow release workflow for Regardio repos — branches mirror environments, ship tooling drives versioning, CI carries it out."
+publishedAt: 2026-05-07
 language: "en"
 status: "published"
 kind: "guide"
@@ -11,115 +11,92 @@ area: "dev"
 
 # Release Workflow
 
-Branch-based release workflow for Regardio packages. `main` → `staging` → `production`. `commit-and-tag-version` reads conventional commits to determine the version bump; quality gates run locally before any branch promotion. Nothing broken reaches a shared branch.
+Branches mirror environments. `main` is where development happens. `staging` reflects what is deployed to the staging server. `production` reflects what is live. Version bumps happen locally at ship time — CI on `production` carries the result out (publishes to npm or deploys to a server).
 
-## Overview
+## The Three-Branch Model
 
-Branches mirror deployment environments:
+```text
+main  ──── ship:staging ────►  staging  (optional staging server)
+  │
+  └──── ship:production ──►  production  (live / npm)
+                                  │
+                             sync back to staging
+```
+
+| Branch | Contains | CI role |
+|--------|----------|---------|
+| `main` | All committed, tested work | None (Husky runs local gates on commit) |
+| `staging` | Deployed to staging server or preview | Verify + deploy to staging |
+| `production` | Only shipped, versioned releases | Verify + deploy or publish |
+
+**Why version bumps happen locally, not in CI.** Hotfixes start from `production` and must write their version bump back up through `staging` and `main` in one pass. Keeping the bump local means both the normal ship path and the hotfix path behave identically — there is no special case in CI.
+
+## Hotfix Flow
+
+A hotfix is an urgent fix that must go to production immediately, without pulling in unreleased changes from `main`.
 
 ```text
-main → staging (optional) → production
+production ──► hotfix/<name>  (fix here with conventional commits)
+                    │
+                    └──► production ──► staging ──► main
 ```
 
-- **`main`** — active development, always deployable. Version bumps happen at ship time, not per-commit.
-- **`staging`** — optional validation environment. No versioning happens here.
-- **`production`** — versioned, published code only.
+`ship:hotfix start <name>` creates the branch from `production`, not from `main`. This is deliberate: it avoids accidentally shipping work-in-progress that has not yet been reviewed for production.
 
-When `ship-production` runs, it discovers all publishable workspace packages and asks you to assign a bump type — `0` (skip), `1` (patch), `2` (minor), or `3` (major) — to each one individually. Packages you skip are left untouched. It determines the highest bump type across all selected packages and runs `pnpm release:<type>` at the root, which bumps versions, rewrites `CHANGELOG.md`, and commits on `main`. If no release script exists (non-publishing repos like channels), versioning is skipped entirely and only the git merges happen. The branches merge once after all bumps are applied. CI on `production` publishes only the packages whose version changed.
+`ship:hotfix finish` versions the fix, merges it into `production`, then propagates through `staging` and back to `main` so nothing is lost.
 
-## How It Works
+## Commands
 
-### Design principles
+| Command | Purpose |
+|---------|---------|
+| `pnpm ship:staging` | Fast-forward `main` → `staging`, push. Triggers staging CI. |
+| `pnpm ship:production` | Version selected packages (if any), fast-forward `main` → `production`, sync `staging`. Triggers production CI. |
+| `pnpm ship:hotfix start <name>` | Create `hotfix/<name>` from `production`. |
+| `pnpm ship:hotfix finish` | Version selected packages (if any), merge hotfix → `production` → `staging` → `main`. |
 
-1. **Branches mirror environments.** `staging` reflects what is deployed to the staging server (when used); `production` always reflects what is published to npm. There is never ambiguity about what is running where.
-2. **You choose the bump per package at ship time.** When running `ship-production` or `ship-hotfix finish`, every publishable package is listed and you assign it `0` (skip), `1` (patch), `2` (minor), or `3` (major). Packages you skip are untouched. The conventional commits in the log inform each choice; the decisions are always explicit.
-3. **Version numbers are a production guarantee.** Bumps are applied only at `ship-production` time. Every version tag in git and every release on npm corresponds to code that has been validated and shipped.
-4. **Staging is optional.** You can ship directly from `main` to `production`. Use `ship-staging` when you want to test changes in a staging environment first.
-5. **Tests are a local gate, not a CI gate.** Quality checks (`lint`, `typecheck`, `test`) run on your machine before any commit is made. Broken code cannot enter the repository.
-6. **You always land back on `main`.** Every command returns you to `main` when it finishes.
+## Versioning — Per-Package, at Ship Time
 
-### Full flow diagram
+`ship:production` and `ship:hotfix finish` discover all publishable workspace packages (those without `"private": true`) and ask you to assign a bump type to each:
 
-```text
-                ship-staging (OPTIONAL)
-                ┌──────────────────────────┐
-main ───────────┤ quality checks pass      ├──► staging (pushed)
-                │ ff-merge main → staging  │
-                └──────────────────────────┘
-                            │
-                   (validated in staging)
-                            │
-                            ▼
-                ship-production
-                ┌──────────────────────────┐
-                │ quality checks on main   │
-                │ select packages/bumps    │
-                │ pnpm release:<type>*      │
-main ───────────┤ bumps version +          ├──► production
-                │ rewrites CHANGELOG.md    │
-                │ ff-merge main → prod     │
-                │ ff-merge prod → staging  │
-                │ push --follow-tags main  │
-                └──────────────────────────┘
-                            │
-                   (CI: pnpm -r publish → npm)
-                            ▼
-                       production
-
-
-                ship-hotfix start fix-name
-                ┌──────────────────────────┐
-production ─────┤ create hotfix/fix-name   ├──► hotfix/fix-name
-                └──────────────────────────┘
-                            │
-                   (author fixes with conventional commits)
-                            │
-                ship-hotfix finish
-                ┌──────────────────────────┐
-                │ quality checks           │
-                │ pnpm release:<type>*      │
-hotfix/fix-name ┤ bumps version +          ├──► production → staging → main
-                │ rewrites CHANGELOG.md    │
-                │ merge to production      │
-                │ propagate to staging     │
-                │ propagate to main        │
-                └──────────────────────────┘
-```
+- `0` — skip (no version change)
+- `1` — patch
+- `2` — minor
+- `3` — major
 
-### What each branch represents at any point in time
+For each selected package, `commit-and-tag-version` runs from within that package's directory, reading the package's own `.versionrc.json`. It bumps the `version` field in `package.json`, rewrites `CHANGELOG.md` to include only commits that touched files under that package's directory (`gitRawCommitsOpts.path: "."`), commits the bump, and creates a scoped tag (e.g. `@regardio/dev@v1.2.0`).
 
-| Branch | Contains | Version bumped? |
-|--------|----------|-----------------|
-| `main` | All committed, tested work | Only after `ship-production` / `ship-hotfix finish` |
-| `staging` | Synced from `production` after each ship, or from `main` via `ship-staging` | After a ship propagates |
-| `production` | Only shipped, versioned releases | Yes — always |
+If a repo has no publishable packages (all are `private: true` or there are no `.versionrc.json` files), the versioning UI is skipped entirely and `ship:production` proceeds directly to the git merge.
 
-### CI role
+## CI — What Happens on Each Branch
 
-CI is intentionally minimal. On push to `production` it:
+CI behaviour differs by what the repo produces.
 
-1. Installs dependencies and builds
-2. Runs `pnpm -r publish --access public --no-git-checks` — publishes every workspace package whose current version is not yet on npm, skipping `private: true` packages
-3. Tags are already present (pushed by `ship-production` via `--follow-tags`)
+### Publishing monorepos (e.g. `commons`)
 
-## Commands
+- **staging**: Run typecheck and tests. Nothing is published.
+- **production**: Run typecheck, tests, then `pnpm -r publish --access public --no-git-checks`. Only packages whose current version is not yet on npm are published — packages with `"private": true` are skipped automatically.
 
-| Command | Usage | Purpose |
-|---------|-------|---------|
-| `pnpm release` | auto | Bump version from conventional commits, update CHANGELOG.md, commit |
-| `pnpm release:patch` | explicit | Force a patch bump |
-| `pnpm release:minor` | explicit | Force a minor bump |
-| `pnpm release:major` | explicit | Force a major bump |
-| `ship-staging` | `ship-staging` | (Optional) Deploy changes to staging for testing |
-| `ship-production` | `ship-production` | Bump version, merge main → production, trigger publish |
-| `ship-hotfix start <name>` | `ship-hotfix start <name>` | Create a hotfix branch from production |
-| `ship-hotfix finish` | `ship-hotfix finish` | Bump version, propagate hotfix through production → staging → main |
+### Server-deployed apps with Docker (e.g. `brass-berlin`)
 
-## Typical Release Flow
+- **staging**: Run tests, build the Docker image, push to the container registry, trigger a staging deploy (e.g. Coolify webhook).
+- **production**: Run typecheck + tests, build and push the Docker image, trigger a production deploy.
+
+### Cloudflare Workers apps (e.g. `magic-of-open-source`)
+
+- **staging**: Run tests, then `wrangler versions upload --preview-alias preview`.
+- **production**: Run typecheck + tests, then `wrangler deploy`.
+
+### Documentation / vocabulary repos (e.g. `system`)
 
-### 1. Develop with conventional commits
+- **staging** and **production**: Verify the repo is well-formed (build, typecheck, test). No publishing or deployment — the repo is distributed via git clone, not npm.
+
+### Static sites without a configured deployment (e.g. `bam-berlin-org`)
+
+- **staging** and **production**: Run tests, typecheck (production only), and build. A deployment step is left as a TODO until the hosting platform is chosen.
+
+## Typical Release Flow
 
-On `main`, use conventional commits so the bump type is inferred automatically:
+### 1. Develop on `main` with conventional commits
 
 ```bash
 feat: add user authentication       # → minor bump
@@ -127,111 +104,114 @@ fix: resolve login redirect loop    # → patch bump
 feat!: redesign authentication API  # → major bump
 ```
 
-### 2. Ship to production
+### 2. (Optional) Test in staging first
 
 ```bash
-pnpm ship:production
+pnpm ship:staging
 ```
 
-This will:
-
-1. Guard: must be on `main`, working tree clean
-2. Fetch and verify `staging` + `production` branches exist
-3. Show commits to be shipped
-4. Run full quality suite on `main` — aborts on failure
-5. For each publishable package: choose `0 (skip) / 1 (patch) / 2 (minor) / 3 (major)`
-6. Confirm the planned bumps — abort if declined or all skipped
-7. Run `pnpm release:<type>` at the root (highest bump type) — bumps versions, rewrites `CHANGELOG.md`, commits. If no release script exists, skip versioning.
-8. Fast-forward merge `main` into `production` and push
-9. Sync `staging` with `production`
-10. Push `main` with `--follow-tags` to push all new version tags
-11. Return to `main`
+Deploys `main` to `staging` without touching versions.
 
-CI on `production` runs `pnpm -r publish` to push changed packages to npm.
-
-### Option: Test in staging first
+### 3. Ship to production
 
 ```bash
-pnpm ship:staging
+pnpm ship:production
 ```
 
-Deploys `main` to `staging` without touching versions. Useful for validating in a staging environment before shipping to production.
-
-## Hotfix Flow
+1. Guard: must be on `main`, working tree clean.
+2. Fetch and verify `staging` and `production` branches exist.
+3. Show commits to be shipped.
+4. Run full quality suite — aborts on failure.
+5. If publishable packages exist: assign a bump type to each; confirm the planned bumps.
+6. If no publishable packages: confirm whether to ship (versioning is skipped).
+7. For each selected package: run `commit-and-tag-version --release-as <type>` from within the package directory.
+8. Fast-forward merge `main` → `production`, push.
+9. Sync `staging` with `production`, push.
+10. Push `main` with `--follow-tags` to carry the new version tags.
+11. Return to `main`.
 
-For urgent fixes that must go directly to production:
+### 4. Hotfix flow
 
 ```bash
 pnpm ship:hotfix start fix-auth-bug
-# apply your fix with conventional commits
+# apply fix with conventional commits
 git add . && git commit -m "fix: ..."
 pnpm ship:hotfix finish
 ```
 
-`finish` asks you to assign a bump type (`0` (skip), `1` (patch), `2` (minor), or `3` (major)) to each publishable package, runs `pnpm release:<type>` at the root (highest bump type) to bump versions and update `CHANGELOG.md`. If no release script exists, versioning is skipped. Then it merges `hotfix → production → staging → main` and deletes the hotfix branch. CI publishes from `production`.
+`finish` fetches origin, runs quality checks, assigns bump types (if publishable packages exist), versions the fix, then merges `hotfix → production → staging → main` and deletes the hotfix branch.
 
 ## Adoption
 
-Install `@regardio/dev` and:
+### 1. Add ship scripts to `package.json`
 
-1. **Add the scripts to `package.json`** (optional, for publishing repos):
+```json
+{
+  "scripts": {
+    "ship:hotfix": "ship-hotfix",
+    "ship:production": "ship-production",
+    "ship:staging": "ship-staging"
+  }
+}
+```
 
-   For repos that publish to npm, add release scripts to the root `package.json`:
+For repos that publish to npm, also add:
+
+```json
+{
+  "scripts": {
+    "release": "commit-and-tag-version",
+    "release:major": "commit-and-tag-version --release-as major",
+    "release:minor": "commit-and-tag-version --release-as minor",
+    "release:patch": "commit-and-tag-version --release-as patch"
+  }
+}
+```
 
-   ```json
-   {
-     "scripts": {
-       "release": "commit-and-tag-version",
-       "release:major": "commit-and-tag-version --release-as major",
-       "release:minor": "commit-and-tag-version --release-as minor",
-       "release:patch": "commit-and-tag-version --release-as patch",
-       "ship:hotfix": "ship-hotfix",
-       "ship:production": "ship-production",
-       "ship:staging": "ship-staging"
-     }
-   }
-   ```
+### 2. Add `.versionrc.json` to each publishable package
 
-   For non-publishing repos (e.g., channels that deploy to servers), omit the release scripts — the ship commands will skip versioning and only perform the git merges. This makes the tools reusable across both publishing and non-publishing repositories.
+```bash
+cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
+# then set "tagPrefix": "@my-scope/my-pkg@v" inside that file
+```
 
-2. **Add a `.versionrc.json` to each publishable package** with a scoped `tagPrefix` so tags and changelogs stay isolated per package:
+Every `.versionrc.json` must include `"gitRawCommitsOpts": { "path": "." }` to filter the git log to commits that actually touched files under that package's directory. Without this, the changelog accumulates noise from unrelated packages.
 
-   ```bash
-   cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
-   # then set "tagPrefix": "@my-scope/my-pkg@v" inside that file
-   ```
+For a single-package repo, place `.versionrc.json` at the root instead.
 
-   For a single-package repo, put `.versionrc.json` at the root instead.
+### 3. Create the branches
 
-3. **Create the branches**:
+```bash
+git checkout -b staging && git push -u origin staging
+git checkout -b production && git push -u origin production
+git checkout main
+```
 
-   ```bash
-   git checkout -b staging && git push -u origin staging
-   git checkout -b production && git push -u origin production
-   git checkout main
-   ```
+### 4. Copy and adapt the CI workflow
 
-4. **Copy the release workflow** for your forge:
+```bash
+# Forgejo / Codeberg
+mkdir -p .forgejo/workflows
+cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/production.yml
 
-   ```bash
-   # GitHub
-   mkdir -p .github/workflows
-   cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+# GitHub
+mkdir -p .github/workflows
+cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+```
+
+Adapt the workflow for your repo type (see CI section above). The template covers the npm-publishing case; server-deployed and Cloudflare repos need the deployment step replaced.
 
-   # Forgejo / Codeberg
-   mkdir -p .forgejo/workflows
-   cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/release.yml
-   ```
+### 5. First publish of any new package must be done locally
 
-5. **First publish of any new package must be done locally**:
+```bash
+pnpm build && npm publish --access public
+```
 
-   ```bash
-   pnpm build && npm publish --access public
-   ```
+CI publishes subsequent versions; the very first one requires a local publish because the package does not yet exist on npm.
 
 ## Quality Gates
 
-Every ship command enforces the same gates — no broken code reaches any environment:
+Every ship command enforces the same gates before any commit or merge:
 
 ```bash
 pnpm build      # Must succeed
@@ -241,9 +221,9 @@ pnpm test       # Must succeed
 
 ## Private Packages and Non-Publishing Repos
 
-Packages that should never be published to npm must set `"private": true` in `package.json`. `pnpm -r publish` skips them automatically.
+Packages with `"private": true` are skipped by `pnpm -r publish` automatically.
 
-For non-publishing repos (e.g., channels that deploy directly to servers instead of npm), omit the `release:*` scripts from `package.json`. The ship tools will skip versioning entirely and only perform the git merges. CI can then handle deployment to servers based on the `production` branch.
+For repos where all packages are private (channels, deployment repos), the ship tools skip the versioning UI entirely and only perform the git merges. This makes the same tooling reusable across publishing and non-publishing repositories.
 
 ## Related
 

package/docs/en/tools/vitest.md

@@ -65,7 +65,7 @@ export default defineConfig({ test: vitestReactConfig });
 ```json
 {
   "scripts": {
-    "test": "exec-s test:*",
+    "test": "vitest run",
     "test:unit": "vitest run",
     "report": "vitest run --coverage"
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "private": false,
   "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
   "keywords": [
@@ -74,7 +74,7 @@
   ],
   "devDependencies": {
     "@total-typescript/ts-reset": "0.6.1",
-    "@types/node": "25.6.0",
+    "@types/node": "25.6.1",
     "@vitest/coverage-v8": "4.1.5",
     "tsdown": "0.22.0",
     "vitest": "4.1.5"
@@ -101,7 +101,7 @@
     "fix:biome": "biome check --write --unsafe .",
     "fix:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc --fix",
     "fix:pkg": "sort-package-json",
-    "lint": "run-s lint:md lint:biome",
+    "lint": "run-p lint:*",
     "lint:biome": "biome check .",
     "lint:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc",
     "lint:pkg": "sort-package-json --check",

package/templates/versionrc/.versionrc.json

@@ -1,5 +1,6 @@
 {
   "commitAll": false,
+  "gitRawCommitsOpts": { "path": "." },
   "sign": false,
   "tagPrefix": "v",
   "types": [