@regardio/dev 2.0.1 → 2.1.0

package/README.md

@@ -1,25 +1,25 @@
 # @regardio/dev
 
-A unified developer toolchain for consistent, high-quality TypeScript projects.
+A shared developer toolchain for TypeScript projects that want consistent quality without wrestling with configuration.
 
-## Purpose
+## What it's for
 
-`@regardio/dev` provides a complete, opinionated development environment that can be adopted by any JavaScript/TypeScript project. It bundles best-in-class tools with sensible defaults, enabling teams to focus on building features rather than configuring tooling.
+`@regardio/dev` is an opinionated, complete development environment that any JavaScript or TypeScript project can pull in. It bundles well-tested tools with defaults that work out of the box, so a team can reach for features instead of assembling tooling.
 
-**One dependency. Zero configuration conflicts. Consistent quality across all projects.**
+**One dependency. No configuration tug-of-war. Steady quality across projects.**
 
-## Philosophy
+## The idea
 
-We believe in **balanced strictness**: rigorous enough to catch bugs early and maintain consistency, yet practical enough to not impede development velocity.
+Balanced strictness: rigorous enough to catch trouble early and keep things consistent, loose enough to stay out of the way.
 
-- **Strict by default** - TypeScript strict mode, comprehensive linting, conventional commits
-- **Sensible defaults** - Shared configs that work out of the box
-- **Minimal boilerplate** - Extend presets, override only what's necessary
-- **Fast feedback** - Quick linting and type checking during development
+- **Strict by default** — TypeScript strict mode, thorough linting, conventional commits
+- **Sensible defaults** — shared configs that work on first install
+- **Minimal boilerplate** — extend a preset, override only the odd line
+- **Fast feedback** — quick linting and type-checking during development
 
-The goal is code that's correct, consistent, and a pleasure to work with.
+The aim is code that's correct, consistent, and pleasant to work with — three things the industry likes to pretend are in tension.
 
-## What's Inside
+## What's inside
 
 | Category | Tools |
 |----------|-------|
@@ -29,13 +29,13 @@ The goal is code that's correct, consistent, and a pleasure to work with.
 | **Workflow** | Husky, GitLab Flow |
 | **CLI utilities** | `ship-staging`, `ship-production`, `ship-hotfix` |
 
-## Quick Start
+## Quick start
 
 ```bash
 pnpm add -D @regardio/dev
 ```
 
-Extend the shared configs in your project:
+Extend the shared configs:
 
 ```jsonc
 // biome.jsonc
@@ -47,47 +47,39 @@ Extend the shared configs in your project:
 
 ## Documentation
 
-Detailed documentation is organized by topic:
+Documentation sits alongside the code, organised by topic. Cross-project standards — principles, writing voice, documentation shape — live outside this package at [`commons/docs/en/`](../../docs/en/README.md), since they apply well beyond TypeScript.
 
-### Concepts
+### Code standards
 
-- [AI Agents](./docs/en/agents.md) - Instructions for AI coding assistants
-- [API](./docs/en/standards/api.md) - API design and implementation guidelines
-- [Coding](./docs/en/standards/coding.md) - TypeScript, React, and general patterns
-- [Commits](./docs/en/standards/commits.md) - Conventional commits and changelog generation
-- [Documentation](./docs/en/standards/documentation.md) - Documentation structure and conventions
-- [Naming](./docs/en/standards/naming.md) - Consistent naming across languages
-- [Principles](./docs/en/standards/principles.md) - Code quality, architecture, maintainability
-- [React](./docs/en/standards/react.md) - React and TypeScript development patterns
-- [SQL](./docs/en/standards/sql.md) - PostgreSQL schema styling, structure, and access control
-- [Testing](./docs/en/standards/testing.md) - Testing philosophy and patterns
-- [Writing](./docs/en/standards/writing.md) - Voice, tone, and language for content
+- [API](./docs/en/standards/api.md) — API design and implementation
+- [Coding](./docs/en/standards/coding.md) — TypeScript, React, and general patterns
+- [Commits](./docs/en/standards/commits.md) — conventional commits and changelog generation
+- [Naming](./docs/en/standards/naming.md) — consistent naming across languages
+- [React](./docs/en/standards/react.md) — React and TypeScript patterns
+- [SQL](./docs/en/standards/sql.md) — PostgreSQL schema, structure, access control
+- [Testing](./docs/en/standards/testing.md) — testing philosophy and patterns
 
 ### Toolchain
 
-- [Biome](./docs/en/tools/biome.md) - Linting and formatting
-- [Commitlint](./docs/en/tools/commitlint.md) - Commit message validation
-- [Dependencies](./docs/en/tools/dependencies.md) - Safe dependency updates and supply-chain controls
-- [Husky](./docs/en/tools/husky.md) - Git hooks
-- [Markdownlint](./docs/en/tools/markdownlint.md) - Markdown quality
-- [Playwright](./docs/en/tools/playwright.md) - End-to-end testing
-- [Releases](./docs/en/tools/releases.md) - GitLab-flow-based versioning and releases
-- [TypeScript](./docs/en/tools/typescript.md) - Strict TypeScript configuration
-- [Vitest](./docs/en/tools/vitest.md) - Unit and integration testing
+- [Biome](./docs/en/tools/biome.md) — linting and formatting
+- [Commitlint](./docs/en/tools/commitlint.md) — commit-message validation
+- [Dependencies](./docs/en/tools/dependencies.md) — safe dependency updates and supply-chain controls
+- [Husky](./docs/en/tools/husky.md) — git hooks
+- [Markdownlint](./docs/en/tools/markdownlint.md) — markdown quality
+- [Playwright](./docs/en/tools/playwright.md) — end-to-end testing
+- [Releases](./docs/en/tools/releases.md) — branch-based release flow with Changesets
+- [TypeScript](./docs/en/tools/typescript.md) — strict TypeScript configuration
+- [Vitest](./docs/en/tools/vitest.md) — unit and integration testing
 
 ## Portability
 
-While designed for Regardio projects, this toolchain follows well-established standards and can be adopted by any TypeScript project:
+The toolchain is designed for Regardio projects, but nothing about it ties it to Regardio. Any TypeScript project can adopt it:
 
-- All configs extend official tool presets
-- No proprietary conventions or lock-in
-- Standard npm package distribution
-- MIT licensed
+- Configs extend official tool presets
+- No proprietary conventions, no lock-in
+- Distributed as a standard npm package
+- MIT-licensed
 
 ## License
 
 MIT © [Regardio](https://regard.io)
-
-## Acknowledgments
-
-Built on the shoulders of giants: [Biome](https://biomejs.dev/), [TypeScript](https://www.typescriptlang.org/), [Vitest](https://vitest.dev/), [Playwright](https://playwright.dev/), [Vite](https://vitejs.dev/), and the entire open source ecosystem.

package/docs/en/README.md

@@ -1,34 +1,29 @@
 ---
 
-title: @regardio/dev Documentation
-type: guide
-status: published
-summary: Complete documentation for the @regardio/dev toolchain
-related: [coding-standards, development-principles]
-locale: en-US
+title: "@regardio/dev Documentation"
+description: "Index for the @regardio/dev toolchain — code-level standards and the tools that enforce them."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
 ---
 
 # Documentation
 
-Documentation index and quick reference for the `@regardio/dev` toolchain.
+Index for the `@regardio/dev` toolchain.
 
-## Concepts
+Cross-project standards — voice, documentation shape, principles — live at the commons root in [`docs/en/`](../../../../docs/en/README.md). The documents below are the code-level standards and the tools that enforce them.
 
-Foundational principles and standards that guide development:
+## Code standards
 
 | Document | Description |
 |----------|-------------|
-| [AI Agents](./agents.md) | Instructions for AI coding assistants |
-| [API](./standards/api.md) | API design and implementation guidelines |
+| [API](./standards/api.md) | API design and implementation |
 | [Coding](./standards/coding.md) | TypeScript, React, and general patterns |
 | [Commits](./standards/commits.md) | Conventional commits and changelog generation |
-| [Documentation](./standards/documentation.md) | Documentation structure and conventions |
 | [Naming](./standards/naming.md) | Consistent naming across languages |
-| [Principles](./standards/principles.md) | Code quality, architecture, maintainability |
-| [React](./standards/react.md) | React and TypeScript development patterns |
-| [SQL](./standards/sql.md) | PostgreSQL schema styling, structure, and access control |
+| [React](./standards/react.md) | React and TypeScript patterns |
+| [SQL](./standards/sql.md) | PostgreSQL schema, structure, access control |
 | [Testing](./standards/testing.md) | Testing philosophy and patterns |
-| [Writing](./standards/writing.md) | Voice, tone, and language |
 
 ## Toolchain
 
@@ -76,7 +71,7 @@ pnpm typecheck     # TypeScript type checking
 | `pnpm-workspace.yaml` | Workspace dependency and supply-chain policy |
 | `tsconfig.json` | TypeScript configuration |
 | `vitest.config.ts` | Unit test configuration |
-| `.sqlfluff` | SQL linting (copy from `@regardio/dev/sqlfluff/setup.cfg`) |
+| `.sqlfluff` | SQL linting (copy from `node_modules/@regardio/dev/templates/sqlfluff/setup.cfg`) |
 
 ### Extending Presets
 

package/docs/en/standards/api.md

@@ -317,7 +317,7 @@ describe('User API', () => {
 - [React](./react.md) — Patterns for the clients that consume the API
 - [SQL](./sql.md) — Naming, structure, and access on the database side
 - [Testing](./testing.md) — Testing philosophy and layers
-- [Principles](./principles.md) — Shared principles
+- [Principles](../../../../../docs/en/principles.md) — Shared principles
 
 ---
 

package/docs/en/standards/coding.md

@@ -134,7 +134,7 @@ An unjustified suppression is a regression.
 
 ## Related
 
-- [Principles](./principles.md) — Shared principles the patterns build on
+- [Principles](../../../../../docs/en/principles.md) — Shared principles the patterns build on
 - [React](./react.md) — Component, hook, and state patterns
 - [Naming](./naming.md) — Names across languages
 - [Testing](./testing.md) — Testing philosophy

package/docs/en/standards/naming.md

@@ -173,7 +173,7 @@ NODE_ENV=production
 - [Coding](./coding.md) — TypeScript and general patterns
 - [SQL](./sql.md) — PostgreSQL naming, structure, and access
 - [Commits](./commits.md) — Branch and commit naming
-- [Writing](./writing.md) — Voice, tone, language
+- [Writing](../../../../../docs/en/writing.md) — Voice, tone, language
 
 ---
 

package/docs/en/standards/react.md

@@ -238,7 +238,7 @@ describe('SearchForm', () => {
 
 - [Coding](./coding.md) — TypeScript patterns React code builds on
 - [Testing](./testing.md) — Testing philosophy and layers
-- [Principles](./principles.md) — Shared principles across the stack
+- [Principles](../../../../../docs/en/principles.md) — Shared principles across the stack
 - [Naming](./naming.md) — Names across languages
 
 ---

package/docs/en/standards/sql.md

@@ -250,8 +250,8 @@ create policy pol_task_update on public.task
 
 - [Naming](./naming.md) — Names across languages
 - [API](./api.md) — How the schema is consumed
-- [Principles](./principles.md) — Shared principles
-- [Writing](./writing.md) — Voice, tone, language
+- [Principles](../../../../../docs/en/principles.md) — Shared principles
+- [Writing](../../../../../docs/en/writing.md) — Voice, tone, language
 
 ---
 

package/docs/en/standards/testing.md

@@ -128,7 +128,7 @@ Before a package publishes:
 
 ## Related
 
-- [Principles](./principles.md) — Shared principles, including specification-led workflow
+- [Principles](../../../../../docs/en/principles.md) — Shared principles, including specification-led workflow
 - [React](./react.md) — How components are shaped to be testable
 - [API](./api.md) — Testing API endpoints and contracts
 - [Vitest](../tools/vitest.md) — Unit and integration testing

package/docs/en/tools/biome.md

@@ -1,20 +1,21 @@
 ---
 
-title: Biome
-type: guide
-status: published
-summary: Fast, unified linting and formatting for JavaScript and TypeScript
-related: [typescript, markdownlint]
-locale: en-US
+title: "Biome"
+description: "Linting and formatting for JavaScript and TypeScript, configured centrally through @regardio/dev."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Biome
 
-Fast, unified linting and formatting for JavaScript and TypeScript. Single tool replacing ESLint + Prettier. Configuration is centralized through `@regardio/dev`; use wrapper commands so all packages behave consistently.
+[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.
 
 ## Configuration
 
-Create `biome.jsonc` in your package root:
+A `biome.jsonc` at the package root is all it takes:
 
 ```jsonc
 {
@@ -36,54 +37,56 @@ Create `biome.jsonc` in your package root:
 }
 ```
 
-## CLI Wrapper
+## CLI wrapper
 
-Use `lint-biome` instead of `biome` directly. This wrapper ensures consistent behavior across the monorepo.
+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 auto-fixable issues
+lint-biome check --write .   # Fix the auto-fixable
 lint-biome format .          # Format only
 ```
 
-## Package.json Handling
+## `package.json` handling
 
-The Biome preset excludes `package.json` files from processing. Instead, use `lint-package` which:
+The Biome preset leaves `package.json` alone. For those files, `lint-package` does the work:
 
-1. Sorts package.json using the well-known field order
-2. Fixes exports condition order (`types` before `default` for TypeScript)
+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 specific package.json
+lint-package path/to/pkg  # Sort a specific package.json
 ```
 
-This is automatically run as part of `pnpm fix`.
+It runs automatically as part of `pnpm fix`.
 
-## Rule Categories
+## Rule categories
 
-The preset enables rules across categories:
+The preset enables rules across:
 
-- **Correctness** - Catch bugs and incorrect code
-- **Style** - Consistent code formatting
-- **Complexity** - Prevent overly complex code
-- **Performance** - Identify performance issues
-- **Security** - Flag potential security vulnerabilities
+- **Correctness** — catch bugs and incorrect code
+- **Style** — consistent code formatting
+- **Complexity** — prevent overly complex code
+- **Performance** — flag performance issues
+- **Security** — flag possible vulnerabilities
 
-## Ignoring Rules
+## Ignoring rules
 
-When a rule genuinely doesn't apply, use inline comments:
+When a rule genuinely doesn't apply, an inline comment names the exception:
 
 ```typescript
 // biome-ignore lint/complexity/noForEach: forEach is clearer here for side effects
 items.forEach(item => process(item));
 ```
 
-Always include a reason explaining why the exception is necessary.
+Always include a reason — an unjustified suppression is a regression waiting to spread.
 
-## Editor Setup
+## Editor integration
 
-- **VS Code**: [Biome extension](https://marketplace.visualstudio.com/items?itemName=biomejs.biome)
-- **JetBrains**: Built-in support via settings
+Most editors pick up `biome.jsonc` automatically through a Biome plugin or built-in support. If the editor formats on save, point it at Biome rather than another formatter so the two don't fight over the same file.
 
-Resources: [Biome Documentation](https://biomejs.dev/) · [Rules Reference](https://biomejs.dev/linter/rules/)
+## Related
+
+- [TypeScript](./typescript.md) — strict TypeScript configuration
+- [Markdownlint](./markdownlint.md) — linting and formatting for Markdown

package/docs/en/tools/commitlint.md

@@ -1,20 +1,21 @@
 ---
 
-title: Commitlint
-type: guide
-status: published
-summary: Enforce conventional commit messages
-related: [husky]
-locale: en-US
+title: "Commitlint"
+description: "Validates commit messages against the conventional format through git hooks."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Commitlint
 
-Validates commit messages against the conventional format via Git hooks. Rules are centralized in `@regardio/dev`.
+Commitlint checks commit messages against the conventional-commits format through git hooks. The rules live in `@regardio/dev`; projects extend them without restating them.
 
 ## Configuration
 
-At the workspace root, create `.commitlintrc.json`:
+At the workspace root, a `.commitlintrc.json`:
 
 ```json
 {
@@ -22,14 +23,14 @@ At the workspace root, create `.commitlintrc.json`:
 }
 ```
 
-Or use a JavaScript config:
+Or, for projects that prefer JavaScript config:
 
 ```javascript
 // commitlint.config.cjs
 module.exports = require('@regardio/dev/commitlint');
 ```
 
-## Commit Format
+## Commit format
 
 ```text
 <type>(<scope>): <subject>
@@ -52,7 +53,7 @@ module.exports = require('@regardio/dev/commitlint');
 | `test` | Adding or updating tests |
 | `build` | Build system or dependencies |
 | `ci` | CI configuration |
-| `chore` | Other changes (tooling, etc.) |
+| `chore` | Other changes (tooling, and so on) |
 | `revert` | Revert a previous commit |
 
 ### Examples
@@ -68,25 +69,20 @@ feat(auth): implement OAuth2 flow
 fix(api): handle null response gracefully
 ```
 
-## Rules
+## Rules the preset enforces
 
-The preset enforces:
+- **Header max length** — 100 characters
+- **Body leading blank** — blank line before the body
+- **Footer leading blank** — blank line before the footer
+- **Type enum** — one of the allowed types, nothing exotic
 
-- **Header max length**: 100 characters
-- **Body leading blank**: Blank line before body
-- **Footer leading blank**: Blank line before footer
-- **Type enum**: Must be one of the allowed types
+## Git hooks
 
-## Git Hooks
+Commitlint runs automatically through Husky on commit. See [Husky](./husky.md) for setup.
 
-Commitlint runs automatically via Husky on commit. See [Husky](./husky.md) for setup.
+## Related
 
-Related documents:
-
-- [Commit Conventions](../standards/commits.md) — Conventional commits and changelog generation
-- [Husky](./husky.md) — Git hooks for quality gates
-
-### Resources
-
-- [Conventional Commits](https://www.conventionalcommits.org/)
+- [Commits](../standards/commits.md) — conventional commits and changelog generation
+- [Husky](./husky.md) — git hooks for quality gates
+- [Conventional Commits](https://www.conventionalcommits.org/) — the specification behind all this
 - [Commitlint Documentation](https://commitlint.js.org/)

package/docs/en/tools/dependencies.md

@@ -1,24 +1,25 @@
 ---
 
-title: Dependency Handling
-type: guide
-status: published
-summary: Safe dependency updates and supply-chain controls for Regardio workspaces
-related: [releases, typescript, vitest]
-locale: en-US
+title: "Dependency Handling"
+description: "How Regardio workspaces keep dependencies up to date without letting the supply chain surprise them."
+publishedAt: 2026-04-17
+language: "en"
+status: "published"
+kind: "guide"
+area: "dev"
 ---
 
 # Dependency Handling
 
-Dependency update workflow and supply-chain controls for Regardio workspaces. Automated updates are combined with pnpm guardrails; the lockfile is authoritative.
+Dependency updates in a Regardio workspace walk a narrow path: automated update tooling on one side, pnpm guardrails on the other, and the lockfile as the final word.
 
 ## Update workflow
 
-- Use `pnpm ncu` to prepare workspace dependency upgrades
-- Install through `pnpm` so workspace-level safety settings are applied
-- Run the normal verification flow after updates:
+- `pnpm ncu` prepares the upgrade proposals
+- Installs go through `pnpm` so workspace-level safety settings apply
+- The normal verification flow runs after an update
 
-The root `ncu` script uses a 1-day cooldown so it does not propose versions that are newer than the workspace release-age policy.
+The root `ncu` script uses a 1-day cooldown, so it won't propose versions newer than the workspace's release-age policy allows anyway.
 
 ```bash
 pnpm audit
@@ -28,7 +29,7 @@ pnpm test
 pnpm typecheck
 ```
 
-For larger automated upgrade passes, use the existing safety wrapper:
+For larger upgrade passes, the safety wrapper pulls everything together:
 
 ```bash
 pnpm safe-upgrade
@@ -36,15 +37,13 @@ pnpm safe-upgrade
 
 ## Workspace safety settings
 
-The root `pnpm-workspace.yaml` defines the main supply-chain controls.
+The root `pnpm-workspace.yaml` carries the main supply-chain controls.
 
 ### Allow-listed dependency builds
 
-Regardio keeps dependency build scripts restricted through `onlyBuiltDependencies`.
+Build scripts stay restricted through `onlyBuiltDependencies`. A dependency cannot run `build` or `postinstall` unless it's already trusted and listed explicitly. If a package that never needed a build step adds one in a compromised release, pnpm doesn't run it — the workspace notices before the damage does.
 
-This means dependencies cannot start running build or postinstall steps unless they are already trusted and listed explicitly. If a package that previously needed no build step suddenly adds one in a compromised release, pnpm will not execute it automatically.
-
-When a legitimate dependency genuinely needs a build step, add it deliberately to the allow-list and review why it is required.
+When a legitimate dependency genuinely needs a build step, add it deliberately to the allow-list and leave a note on why.
 
 ### Block exotic transitive dependencies
 
@@ -52,7 +51,7 @@ When a legitimate dependency genuinely needs a build step, add it deliberately t
 blockExoticSubdeps: true
 ```
 
-This prevents transitive dependencies from resolving through git URLs, tarballs, or other non-registry sources.
+Transitive dependencies can't resolve through git URLs, tarballs, or other non-registry sources. The registry remains the only door in.
 
 ### Delay newly published versions
 
@@ -60,9 +59,9 @@ This prevents transitive dependencies from resolving through git URLs, tarballs,
 minimumReleaseAge: 1440
 ```
 
-We wait 24 hours before pnpm may install a newly published version. This gives time for compromised packages to be detected and removed before they reach the workspace.
+pnpm waits 24 hours before installing a newly published version. That window is long enough for most compromised packages to be detected and pulled before they land in a workspace.
 
-The root `ncu` script mirrors this with `--cooldown 1`, which helps align version selection with the install policy. pnpm still remains the authoritative enforcement point during installation.
+The root `ncu` script mirrors this with `--cooldown 1`, which lines version selection up with the install policy. pnpm is still the authoritative enforcement point at install time.
 
 ### Prevent trust downgrades
 
@@ -70,47 +69,45 @@ The root `ncu` script mirrors this with `--cooldown 1`, which helps align versio
 trustPolicy: no-downgrade
 ```
 
-If a package release becomes less trustworthy than earlier releases, pnpm rejects the installation instead of silently accepting the downgrade.
+If a package release becomes less trustworthy than earlier releases, pnpm refuses to install it rather than silently accepting the downgrade.
 
-`npm-check-updates` does not enforce trust policy, build-script allow-lists, or exotic transitive source restrictions. Those safeguards only take effect when `pnpm install` resolves and installs dependencies.
+`npm-check-updates` does not enforce trust policy, build-script allow-lists, or exotic-source restrictions. Those safeguards take effect when `pnpm install` resolves and installs — not before.
 
 ## Lockfile discipline
 
-- Commit `pnpm-lock.yaml`
-- Review lockfile changes together with manifest changes
-- Prefer normal installs over ad hoc per-package package manager commands so the workspace lock remains authoritative
+- `pnpm-lock.yaml` is committed
+- Lockfile changes are reviewed alongside manifest changes
+- Prefer regular installs over ad-hoc per-package commands so the workspace lock stays authoritative
 
 ## Reviewing dependency updates
 
-When an automated update lands, review:
+When an automated update lands, a few questions are worth asking:
 
-- whether the package is direct or transitive
-- whether the update adds or changes a build requirement
-- whether the package affects runtime, build tooling, or release tooling
-- whether overrides should be added for newly disclosed vulnerabilities
+- Is the package direct or transitive?
+- Does the update add or change a build requirement?
+- Does the package affect runtime, build tooling, or release tooling?
+- Do any newly disclosed vulnerabilities want a workspace override?
 
 ## Shipping dependency changes
 
-Dependency updates follow the same release gates as any other change.
-
-- verify locally before shipping
-- keep changelog subjects clear when a release is primarily dependency maintenance
-- use provenance when publishing public packages
+Dependency updates go through the same release gates as any other change.
 
-## When to make an exception
+- Verify locally before shipping
+- Keep changelog subjects clear when the release is primarily dependency maintenance
+- Use provenance when publishing public packages
 
-Exceptions should stay explicit and rare.
+## When an exception is warranted
 
-Examples:
+Exceptions stay explicit and rare. A few examples of what qualifies:
 
-- adding a package to `onlyBuiltDependencies`
-- introducing a workspace override for a vulnerable transitive dependency
-- reducing the release-age delay for a security-critical emergency update
+- Adding a package to `onlyBuiltDependencies`
+- Introducing a workspace override for a vulnerable transitive dependency
+- Reducing the release-age delay for a security-critical emergency update
 
-When an exception is necessary, document the reason in the change itself so later readers can understand why the safer default was not enough.
+When an exception is needed, record the reason in the change itself — later readers will thank whoever left the note.
 
-Related documents:
+## Related
 
-- [Release Workflow](./releases.md) — Automated release process for Regardio packages
-- [Testing Approach](../standards/testing.md) — Testing philosophy and patterns for Regardio projects
-- [TypeScript Configuration](./typescript.md) — TypeScript setup and configuration for Regardio projects
+- [Releases](./releases.md) — the release process dependency changes pass through
+- [Testing](../standards/testing.md) — the layer that catches what slips past the update review
+- [TypeScript](./typescript.md) — TypeScript configuration for Regardio projects