@regardio/dev 2.0.1 → 2.1.0

package/docs/en/tools/husky.md

@@ -1,20 +1,21 @@
 ---
 
-title: Husky
-type: guide
-status: published
-summary: Git hooks for quality gates
-related: [commitlint, biome]
-locale: en-US
+title: "Husky"
+description: "Git hooks for quality gates — the last chance to catch something before it lands in history."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Husky
 
-Runs quality checks at commit time via Git hooks. Configured through `@regardio/dev`; bypass only in genuine emergencies.
+Husky runs quality checks at commit time through git hooks. The configuration comes from `@regardio/dev`; bypass is available, but saved for real emergencies.
 
 ## Setup
 
-Husky is configured automatically via the `prepare` script:
+Husky configures itself through the `prepare` script:
 
 ```json
 {
@@ -28,63 +29,60 @@ This runs after `pnpm install` and sets up the `.husky` directory.
 
 ## Hooks
 
-### commit-msg
+### `commit-msg`
 
-Validates commit messages against conventional commit format:
+Validates commit messages against the conventional-commit format:
 
 ```bash
 #!/bin/sh
 pnpm lint-commit --edit $1
 ```
 
-### pre-commit (optional)
+### `pre-commit` (optional)
 
-Run linting before commit:
+Runs linting before a commit lands:
 
 ```bash
 #!/bin/sh
 pnpm lint
 ```
 
-## CLI Wrapper
+## CLI wrapper
 
-Use `exec-husky` instead of `husky` directly. This wrapper handles monorepo scenarios correctly.
+`exec-husky` takes the place of `husky` directly — the wrapper handles monorepo scenarios that bare Husky doesn't.
 
-## Bypassing Hooks
+## Bypassing hooks
 
-In rare cases where you need to skip hooks:
+In the rare case where a hook truly has to be skipped:
 
 ```bash
 git commit --no-verify -m "emergency fix"
 ```
 
-Use sparingly and only when absolutely necessary.
+Use sparingly. A bypass that becomes habit stops being a bypass.
 
 ## Troubleshooting
 
 ### Hooks not running
 
-Ensure Husky is installed:
+Make sure Husky is installed:
 
 ```bash
 pnpm install
 ```
 
-Check that `.husky` directory exists and contains hook files.
+Check that `.husky/` exists and carries the hook files.
 
 ### Permission denied
 
-Make hooks executable:
+Make the hooks executable:
 
 ```bash
 chmod +x .husky/*
 ```
 
-Related documents:
-
-- [Commitlint](./commitlint.md) — Commit message validation
-- [Biome](./biome.md) — Linting and formatting
-
-### Resources
+## Related
 
+- [Commitlint](./commitlint.md) — commit-message validation
+- [Biome](./biome.md) — linting and formatting
 - [Husky Documentation](https://typicode.github.io/husky/)

package/docs/en/tools/markdownlint.md

@@ -1,20 +1,21 @@
 ---
 
-title: Markdownlint
-type: guide
-status: published
-summary: Linting and formatting for Markdown files
-related: [biome]
-locale: en-US
+title: "Markdownlint"
+description: "Linting and light formatting for Markdown, so prose stays as consistent as the code alongside it."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Markdownlint
 
-Lints Markdown structure and formatting. Rules are centralized in `@regardio/dev`; use the `lint-md` wrapper instead of calling the tool directly.
+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.
 
 ## Configuration
 
-Create `.markdownlint.json` in your package root:
+A `.markdownlint.json` at the package root:
 
 ```json
 {
@@ -33,16 +34,16 @@ Create `.markdownlint.json` in your package root:
 }
 ```
 
-## CLI Wrapper
+## CLI wrapper
 
-Use `lint-md` instead of `markdownlint-cli2` directly:
+Use `lint-md` rather than `markdownlint-cli2` directly:
 
 ```bash
 lint-md "**/*.md"              # Check all Markdown files
-lint-md --fix "**/*.md"        # Auto-fix issues
+lint-md --fix "**/*.md"        # Auto-fix what can be auto-fixed
 ```
 
-## Key Rules
+## Key rules
 
 | Rule | Description |
 |------|-------------|
@@ -52,11 +53,11 @@ lint-md --fix "**/*.md"        # Auto-fix issues
 | MD012 | No multiple consecutive blank lines |
 | MD022 | Headings surrounded by blank lines |
 | MD032 | Lists surrounded by blank lines |
-| MD041 | First line should be a top-level heading |
+| MD041 | First line is a top-level heading |
 
-## Ignoring Rules
+## Ignoring rules
 
-For specific files or sections:
+For a specific file or section, inline comments do the job:
 
 ```markdown
 <!-- markdownlint-disable MD013 -->
@@ -64,7 +65,7 @@ This line can be very long without triggering a warning.
 <!-- markdownlint-enable MD013 -->
 ```
 
-Or in config for specific files:
+Or, per-file, through the config:
 
 ```json
 {
@@ -73,12 +74,8 @@ Or in config for specific files:
 }
 ```
 
-Related documents:
-
-- [Documentation](../standards/documentation.md) — Structure and conventions
-- [Biome](./biome.md) — Fast, unified linting and formatting
-
-### Resources
+## Related
 
+- [Biome](./biome.md) — linting and formatting on the code side
 - [Markdownlint Rules](https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md)
 - [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)

package/docs/en/tools/playwright.md

@@ -1,16 +1,17 @@
 ---
 
-title: Playwright
-type: guide
-status: published
-summary: End-to-end testing for web applications
-related: [vitest]
-locale: en-US
+title: "Playwright"
+description: "End-to-end testing for web applications — for the flows users actually feel."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Playwright
 
-End-to-end testing for web applications. Prefer role-based, accessible selectors. Use E2E tests for critical user workflows, not as a substitute for unit or integration tests.
+End-to-end testing for web applications. Playwright covers the flows a user actually moves through; it isn't a stand-in for unit or integration tests, and tests read best when they reach for accessible, role-based selectors.
 
 ## Configuration
 
@@ -39,16 +40,16 @@ export default defineConfig(
 }
 ```
 
-## Running Tests
+## Running tests
 
 ```bash
 pnpm test:e2e                    # Run all E2E tests
 pnpm playwright test --ui        # Interactive UI mode
-pnpm playwright test --debug     # Debug mode with inspector
-pnpm playwright show-report      # View HTML report
+pnpm playwright test --debug     # Debug mode with the inspector
+pnpm playwright show-report      # View the HTML report
 ```
 
-## Writing Tests
+## Writing tests
 
 ```typescript
 import { test, expect } from '@playwright/test';
@@ -64,23 +65,25 @@ test('user can submit contact form', async ({ page }) => {
 });
 ```
 
-## Best Practices
+## Patterns that hold up
 
-### Use Role-Based Selectors
+### Role-based selectors
+
+Selectors that match roles and labels survive UI tidying — selectors that pin to CSS classes don't.
 
 ```typescript
-// Preferred - accessible and resilient
+// reads well — accessible and resilient
 await page.getByRole('button', { name: 'Submit' });
 await page.getByLabel('Email');
 
-// Avoid - brittle
+// brittle — breaks on any class rename
 await page.locator('.submit-btn');
 await page.locator('#email-input');
 ```
 
-### Add data-test Attributes
+### `data-test` attributes
 
-For elements without accessible names:
+For elements without a natural accessible name:
 
 ```tsx
 <div data-test="user-avatar">{avatar}</div>
@@ -90,9 +93,9 @@ For elements without accessible names:
 await page.getByTestId('user-avatar');
 ```
 
-### Page Object Pattern
+### Page objects for larger flows
 
-For complex pages, use page objects:
+When a page has a handful of interactions worth naming, a small page object keeps tests readable:
 
 ```typescript
 class LoginPage {
@@ -106,12 +109,9 @@ class LoginPage {
 }
 ```
 
-Related documents:
-
-- [Testing Approach](../standards/testing.md) — Testing philosophy and patterns for Regardio projects
-- [Vitest](./vitest.md) — Unit and integration testing for TypeScript projects
-
-### Resources
+## Related
 
+- [Testing](../standards/testing.md) — testing philosophy and layers
+- [Vitest](./vitest.md) — unit and integration testing
 - [Playwright Documentation](https://playwright.dev/)
 - [Best Practices](https://playwright.dev/docs/best-practices)

package/docs/en/tools/releases.md

@@ -1,16 +1,17 @@
 ---
 
-title: Release Workflow
-type: guide
-status: published
-summary: GitLab-flow release process with Changesets for Regardio packages
-related: [commitlint]
-locale: en-US
+title: "Release Workflow"
+description: "Branch-based release workflow for Regardio packages — main → staging → production, driven by Changesets."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Release Workflow
 
-Branch-based release workflow for Regardio packages. `main` → `staging` → `production`. Versioning is driven by [Changesets](https://github.com/changesets/changesets); quality gates run locally before any branch promotion.
+Branch-based release workflow for Regardio packages. `main` → `staging` → `production`. Changesets carry the version bumps; quality gates run locally before any branch promotion. Nothing broken reaches a shared branch.
 
 ## Overview
 
@@ -209,13 +210,20 @@ Install `@regardio/dev` and:
    git checkout main
    ```
 
-4. **Copy the release workflow** for your forge:
+4. **Copy the release workflow** for your forge. A GitHub Actions template ships with `@regardio/dev`; Forgejo Actions accepts the same workflow syntax with minimal changes.
 
    ```bash
+   # GitHub
    mkdir -p .github/workflows
    cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+
+   # Forgejo / Codeberg
+   mkdir -p .forgejo/workflows
+   cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/release.yml
    ```
 
+   For other CI systems, treat the template as a reference: the workflow installs dependencies, builds, runs `pnpm changeset publish`, and pushes tags on every push to `production`.
+
 5. **First publish of any new package must be done locally**:
 
    ```bash
@@ -236,7 +244,7 @@ pnpm test       # Must succeed
 
 Packages that should never be published to npm must set `"private": true` in `package.json`. `changeset publish` skips them automatically. The git flow (`ship-staging`, `ship-production`, `ship-hotfix`) works identically for private packages — changesets, version bumps, and branch promotion all continue as normal; only the npm publish step is skipped.
 
-Related documents:
+## Related
 
-- [Commit Conventions](../standards/commits.md) — Conventional commits for consistent history
-- [Commitlint](./commitlint.md) — Commit message validation
+- [Commits](../standards/commits.md) — conventional commits and changelog generation
+- [Commitlint](./commitlint.md) — commit-message validation

package/docs/en/tools/typescript.md

@@ -1,20 +1,21 @@
 ---
 
-title: TypeScript Configuration
-type: guide
-status: published
-summary: TypeScript setup and configuration for Regardio projects
-related: [biome, vitest]
-locale: en-US
+title: "TypeScript Configuration"
+description: "Shared, strict TypeScript presets for Regardio projects, with enough knobs for each shape of project."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # TypeScript Configuration
 
-Strict shared TypeScript presets for Regardio projects. Extend from `@regardio/dev` instead of rebuilding config from scratch. Keep strict settings enabled.
+Strict, shared TypeScript presets for Regardio projects. Extending from `@regardio/dev` is the well-worn path; rebuilding a config from scratch is usually a path to drift.
 
 ## Presets
 
-| Preset | Use Case |
+| Preset | Use case |
 |--------|----------|
 | `@regardio/dev/typescript/base` | Node.js packages, libraries |
 | `@regardio/dev/typescript/react` | React applications and components |
@@ -22,7 +23,7 @@ Strict shared TypeScript presets for Regardio projects. Extend from `@regardio/d
 
 ## Configuration
 
-### tsconfig.json
+### `tsconfig.json`
 
 ```json
 {
@@ -40,9 +41,9 @@ For React projects:
 }
 ```
 
-### tsconfig.build.json
+### `tsconfig.build.json`
 
-Separate build config for production output:
+A separate build config for production output:
 
 ```json
 {
@@ -55,15 +56,15 @@ Separate build config for production output:
 }
 ```
 
-## Strict Settings
+## Strict settings
 
-The base config enables strict TypeScript checking:
+The base config turns on strict type-checking across the board:
 
-- `strict: true` - All strict type-checking options
-- `noUncheckedIndexedAccess: true` - Adds `undefined` to index signatures
-- `exactOptionalPropertyTypes: true` - Distinguishes between `undefined` and missing
-- `noImplicitReturns: true` - All code paths must return a value
-- `noFallthroughCasesInSwitch: true` - Prevents switch fallthrough bugs
+- `strict: true` — every strict type-checking option
+- `noUncheckedIndexedAccess: true` — adds `undefined` to index signatures
+- `exactOptionalPropertyTypes: true` — distinguishes `undefined` from missing
+- `noImplicitReturns: true` — every code path returns a value
+- `noFallthroughCasesInSwitch: true` — prevents switch-fallthrough surprises
 
 ## Scripts
 
@@ -76,14 +77,11 @@ The base config enables strict TypeScript checking:
 }
 ```
 
-Run `typecheck` regularly during development to catch type errors early.
+Running `typecheck` during development catches type errors at the moment they appear, rather than at the moment they break something.
 
-Related documents:
-
-- [Biome](./biome.md) — Linting and formatting
-- [Vitest](./vitest.md) — Unit and integration testing for TypeScript projects
-
-### Resources
+## Related
 
+- [Biome](./biome.md) — linting and formatting
+- [Vitest](./vitest.md) — unit and integration testing
 - [TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/)
 - [tsconfig Reference](https://www.typescriptlang.org/tsconfig)

package/docs/en/tools/vitest.md

@@ -1,20 +1,21 @@
 ---
 
-title: Vitest
-type: guide
-status: published
-summary: Unit and integration testing for TypeScript projects
-related: [typescript, playwright]
-locale: en-US
+title: "Vitest"
+description: "Unit and integration testing for TypeScript projects — Vite-native, TypeScript-first."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Vitest
 
-Unit and integration testing for TypeScript projects. Vite-native, TypeScript-first. Configuration centralized in `@regardio/dev`.
+Vitest runs unit and integration tests across Regardio's TypeScript projects. It's Vite-native, TypeScript-first, and configured centrally through `@regardio/dev`.
 
-## Coverage Thresholds
+## Coverage thresholds
 
-Library packages must meet minimum coverage thresholds before publishing:
+Library packages meet a minimum coverage floor before publishing:
 
 | Metric | Minimum |
 |--------|---------|
@@ -23,11 +24,11 @@ Library packages must meet minimum coverage thresholds before publishing:
 | **Functions** | 80% |
 | **Lines** | 80% |
 
-These thresholds are enforced by:
+The floor is enforced at three gates:
 
-1. **`pnpm report`** - Fails if coverage is below thresholds
-2. **`ship-staging`** - Runs coverage check before deploying to staging
-3. **GitHub Actions** - Runs coverage check before publishing to npm
+1. **`pnpm report`** — fails if coverage drops below the floor
+2. **`ship-staging`** — runs the coverage check before deploying to staging
+3. **GitHub Actions** — runs the coverage check before publishing to npm
 
 To check coverage locally:
 
@@ -35,9 +36,11 @@ To check coverage locally:
 pnpm report
 ```
 
+The floor is a minimum, not a target — the aim is meaningful tests, not arithmetic.
+
 ## Configuration
 
-### Node.js Packages
+### Node.js packages
 
 ```typescript
 // vitest.config.ts
@@ -47,7 +50,7 @@ import { vitestNodeConfig } from '@regardio/dev/vitest/node';
 export default defineConfig({ test: vitestNodeConfig });
 ```
 
-### React Packages
+### React packages
 
 ```typescript
 // vitest.config.ts
@@ -74,14 +77,14 @@ Required devDependencies:
 ```json
 {
   "devDependencies": {
-    "@regardio/dev": "^1.11.0",
+    "@regardio/dev": "^2.0.0",
     "@vitest/coverage-v8": "^4.0.0",
     "vitest": "^4.0.0"
   }
 }
 ```
 
-## Running Tests
+## Running tests
 
 ```bash
 pnpm test:unit          # Run all tests once
@@ -90,20 +93,20 @@ pnpm vitest --ui        # Visual UI
 pnpm vitest --coverage  # With coverage report
 ```
 
-## Test File Naming
+## Test file naming
 
 - Unit tests: `*.test.ts` or `*.test.tsx`
-- Place tests next to source files or in `__tests__` directories
+- Place tests next to the source file, or in a `__tests__` directory
 
-## Writing Tests
+## Writing tests
 
-Follow the Arrange-Act-Assert pattern:
+Arrange, Act, Assert — a rhythm that reads well in almost every test:
 
 ```typescript
 import { describe, it, expect } from 'vitest';
 
 describe('calculateTotal', () => {
-  it('should apply discount correctly', () => {
+  it('applies the discount correctly', () => {
     // Arrange
     const items = [{ price: 100 }, { price: 50 }];
     const discount = 0.1;
@@ -117,7 +120,7 @@ describe('calculateTotal', () => {
 });
 ```
 
-## React Component Testing
+## React component testing
 
 ```typescript
 import { render, screen } from '@testing-library/react';
@@ -134,13 +137,10 @@ it('calls onClick when clicked', async () => {
 });
 ```
 
-Related documents:
-
-- [Testing Approach](../standards/testing.md) — Testing philosophy and patterns for Regardio projects
-- [Playwright](./playwright.md) — End-to-end testing for web applications
-- [TypeScript Configuration](./typescript.md) — TypeScript setup and configuration for Regardio projects
-
-### Resources
+## Related
 
+- [Testing](../standards/testing.md) — testing philosophy and layers
+- [Playwright](./playwright.md) — end-to-end testing
+- [TypeScript](./typescript.md) — TypeScript configuration
 - [Vitest Documentation](https://vitest.dev/)
 - [Testing Library](https://testing-library.com/)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "private": false,
   "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
   "keywords": [
@@ -71,10 +71,9 @@
   "devDependencies": {
     "@total-typescript/ts-reset": "0.6.1",
     "@types/node": "25.6.0",
-    "@vitest/coverage-v8": "4.1.4",
-    "tsdown": "0.21.9",
-    "vitest": "4.1.4",
-    "@regardio/dev": "2.0.1"
+    "@vitest/coverage-v8": "4.1.5",
+    "tsdown": "0.21.10",
+    "vitest": "4.1.5"
   },
   "peerDependencies": {
     "@biomejs/biome": ">=2",
@@ -100,11 +99,11 @@
     "dev": "tsdown --watch",
     "fix": "run-s fix:pkg fix:md fix:biome",
     "fix:biome": "biome check --write --unsafe .",
-    "fix:md": "markdownlint-cli2 --fix",
+    "fix:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc --fix",
     "fix:pkg": "sort-package-json",
     "lint": "run-s lint:md lint:biome",
     "lint:biome": "biome check .",
-    "lint:md": "markdownlint-cli2",
+    "lint:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc",
     "lint:pkg": "sort-package-json --check",
     "test": "run-p test:*",
     "test:e2e": "echo 'no e2e tests'",