@regardio/dev 2.0.2 → 2.1.1

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

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,57 @@ 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:
+## Workspace-Level Automation
+
+The meta-workspace (`workspace/`) provides scripts that operate across all repos at once. Run these from the `workspace/` directory.
+
+### Daily maintenance: safe-upgrade-and-ship
+
+After a dependency upgrade cycle, ship everything to staging in one command:
+
+```bash
+cd workspace
+pnpm safe-upgrade-and-ship
+```
+
+What it does:
+
+1. Runs `pnpm safe-upgrade` — upgrades all dependencies, runs build + lint + test + typecheck across the full workspace. Aborts if anything fails.
+2. For every repo (workspace itself, commons, ensemble, system, channels/*): checks `git status`.
+3. If only `package.json` and/or `pnpm-lock.yaml` changed: commits with `chore: upgrade dependencies`, pushes `main` to origin, fast-forward merges `main → staging`, pushes `staging`, returns to `main`.
+4. If unexpected files are uncommitted: skips that repo and reports it.
+
+No further interaction needed — husky pre-commit hooks run on the commit step, and the full quality suite already passed in step 1.
+
+### Selective staging ship
+
+If changes are already committed and ready:
+
+```bash
+cd workspace
+pnpm ship:staging
+```
+
+Delegates to each repo's `ship:staging` (which re-runs quality checks per repo). Workspace itself is handled directly to avoid recursion.
+
+### Production ship
+
+```bash
+cd workspace
+pnpm ship:production
+```
+
+Calls each sub-repo's `ship:production` in sequence, then promotes workspace itself (`main → production → staging`). For repos with Changesets (commons), this triggers the full version-bump flow. For app repos without Changesets (ensemble, system, channels), it promotes the branch without versioning.
+
+### When to use each command
+
+| Command | When |
+|---------|------|
+| `pnpm safe-upgrade-and-ship` | Daily/weekly dependency maintenance — upgrade all, verify all, ship all to staging |
+| `pnpm ship:staging` | Changes are already committed; just push everything to staging |
+| `pnpm ship:production` | Ready to go to production across all repos |
+
+## 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)