@regardio/dev 2.5.0 → 2.6.1

package/README.md

@@ -47,7 +47,7 @@ Extend the shared configs:
 
 ## Documentation
 
-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.
+Documentation sits alongside the code in `docs/en/`, organised by topic. It covers cross-project principles and writing standards as well as code-level standards and toolchain configuration.
 
 ### Code standards
 

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-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";
+import { a as git, c as runQualityChecks, i as getWorkspacePackages, n as chooseForEach, o as gitRead, s as runPackageRelease, t as branchExists } from "./utils-sL-BT4MX.mjs";
 //#region src/bin/ship/hotfix.ts
 /**
 * ship-hotfix: Manage hotfix branches based on production code.
@@ -77,7 +77,7 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 			} catch {
 				console.log(`No versioning configured for ${pkg.name} — skipping.`);
 			}
-		} else console.log("No publishable packages — skipping versioning.");
+		} else console.log("No packages configured for versioning — skipping.");
 		console.log("\nMerging hotfix into production...");
 		git("checkout", "production");
 		git("pull", "--ff-only", "origin", "production");
@@ -99,8 +99,8 @@ function runShipHotfix(subcommand, subArgs, cwd = process.cwd()) {
 		} catch {}
 		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.");
+			console.log(`\n✅ Hotfix ${shipped} shipped to production → staging → main.`);
+			console.log("CI will handle the rest.");
 		} 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 runQualityChecks, i as getWorkspacePackages, n as chooseForEach, o as gitRead, r as confirm, s as runPackageRelease, t as branchExists } from "./utils-BPxpSgv6.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-sL-BT4MX.mjs";
 //#region src/bin/ship/production.ts
 /**
 * ship-production: Promote main to production following the GitLab workflow.
@@ -69,7 +69,7 @@ function runShipProduction(cwd = process.cwd()) {
 		} catch {
 			console.log(`No versioning configured for ${pkg.name} — skipping.`);
 		}
-	} else if (!confirm("\nNo publishable packages — ship commits to production?\n")) process.exit(0);
+	} else if (!confirm("\nNo packages configured for versioning — ship commits to production?\n")) process.exit(0);
 	console.log("\nMerging main into production...");
 	git("checkout", "production");
 	git("pull", "--ff-only", "origin", "production");
@@ -84,7 +84,7 @@ function runShipProduction(cwd = process.cwd()) {
 	git("push", "--follow-tags", "origin", "main");
 	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.`);
+		console.log(`\n✅ Shipped ${shipped} to production. CI will handle the rest.`);
 	} else console.log("\n✅ Commits shipped to production.");
 	console.log("You are on main and ready to keep working.");
 }

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

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

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { execFileSync, execSync } from "node:child_process";
-import { closeSync, openSync, readSync } from "node:fs";
+import { closeSync, existsSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
 //#region src/bin/ship/utils.ts
 /**
 * Shared utilities for ship-staging, ship-production, and ship-hotfix.
@@ -42,7 +43,7 @@ const getWorkspacePackages = (cwd = process.cwd()) => {
 		cwd,
 		encoding: "utf-8"
 	});
-	return JSON.parse(raw).filter((p) => p.private !== true && p.name !== void 0).map(({ name, path }) => ({
+	return JSON.parse(raw).filter((p) => p.name !== void 0 && existsSync(join(p.path, ".versionrc.json"))).map(({ name, path }) => ({
 		name,
 		path
 	}));

package/docs/en/README.md

@@ -1,7 +1,7 @@
 ---
 
 title: "@regardio/dev Documentation"
-description: "Index for the @regardio/dev toolchain — code-level standards and the tools that enforce them."
+description: "Index for the @regardio/dev toolchain — principles, code-level standards, and the tools that enforce them."
 publishedAt: 2026-04-17
 language: "en"
 status: "published"
@@ -9,9 +9,17 @@ status: "published"
 
 # Documentation
 
-Index for the `@regardio/dev` toolchain.
+Index for the `@regardio/dev` toolchain. All Regardio standards ship with this package and are available at `node_modules/@regardio/dev/docs/en/` after install.
 
-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.
+## Principles & writing
+
+Cross-project standards that carry across every Regardio codebase, regardless of language or framework:
+
+| Document | Description |
+|----------|-------------|
+| [Principles](./principles.md) | Code quality, architecture, security, maintainability, collaboration, implementation workflow |
+| [Writing](./writing.md) | Voice, tone, and language — English and German |
+| [Documentation](./documentation.md) | Shape of documents, frontmatter, cross-references, tense and stance |
 
 ## Code standards
 

package/docs/en/documentation.md

@@ -0,0 +1,170 @@
+---
+
+title: "Documentation"
+description: "How Regardio shapes its documents — a thin shared surface with room for each document to take the form its content asks for."
+publishedAt: 2026-04-17
+order: 1
+language: "en"
+status: "published"
+---
+
+## Context
+
+A Regardio document is read for answers about the system, for judgement about what the project does and why, and as the specification its tests are measured against. These readings do not all need the same shape on every page. An architectural decision reads best as a short chain of reasoning — context, alternatives, what was chosen and why. A naming reference reads best as a catalogue. A quick introduction to a tool reads best as a few paragraphs and a short example. Forcing every document into one template serves the template rather than the content, and what the reader comes away with is ceremony instead of understanding.
+
+What the documentation needs is enough predictability for tooling to rely on — a consistent frontmatter, a recognisable title, a place to find related reading — and enough freedom for each document to take the shape its content asks for.
+
+## Decision
+
+Every Regardio document carries a small shared surface. Underneath, it takes whichever of a few shapes fits the content it carries.
+
+### Shared surface
+
+Every document has the same top:
+
+- **Frontmatter** that identifies the document and lets tooling index it
+- **A title** as a heading or implicit from frontmatter
+- **An opening that names what the document is for** — one or two sentences, before any sub-headings, so that a reader landing cold knows where they are
+
+Every document has the same bottom:
+
+- **Cross-references** to documents the reader is likely to want next, either inline in the prose or collected under `## Related` at the end
+
+Between the top and the bottom, the document takes the shape its content asks for.
+
+### Shapes the body takes
+
+A few shapes recur. Pick the one the content fits; do not pad the content into a shape it resists.
+
+**Decision record.** When the document captures a choice with real trade-offs, the ADR shape carries the reasoning well: *Status → Context → Decision → Alternatives Considered → Operational Rules → Consequences*. Operational Rules are the part tests bind to. The shape is an option for decision-heavy documents, not a requirement for every document.
+
+**Reference catalogue.** When the content is a set of rules, names, or mappings that readers look up rather than read end-to-end, a catalogue of short sections with examples is the honest form. Naming conventions, file-layout rules, linter settings, and configuration tables read this way.
+
+**Concept or entity note.** When the document describes a thing in the domain — a Channel, a Piece, a Plan — a short run of paragraphs that names the thing, its role, and its relations is usually enough. Two or three headings if the thing has parts worth naming separately.
+
+**Quick introduction.** When the document introduces a tool or a workflow, a few paragraphs and a small example are enough. The reader needs to know what the thing is, when to reach for it, and where to go next. No ADR skeleton is required for a tool page.
+
+**Warm reasoning.** When the document is working something out — a use case, a walkthrough, an explanation of why a piece of the domain behaves the way it does — prose that follows the thought is the right form. Headings appear where they help the reader keep their place, not because structure is owed.
+
+A document can borrow from more than one shape. An architectural document might open with warm reasoning and close with Operational Rules. An entity note might include a short alternatives paragraph when the entity's shape had genuine contenders. The shapes are orientation, not slots.
+
+### Frontmatter
+
+Frontmatter is the part tooling reads. Keep it stable.
+
+| Field | Required | Notes |
+|---|---|---|
+| `title` | yes | Noun phrase naming the document. Decision records may prefix `"ADR: "`. |
+| `description` | yes | One sentence. What this document is for, without hedging. |
+| `publishedAt` | yes | ISO date (`YYYY-MM-DD`) the document was first accepted. |
+| `status` | yes | `"draft"`, `"published"`, `"superseded"`. |
+| `language` | yes | `"en"`, `"de"`. |
+| `order` | no | Integer, when a sibling set has a meaningful reading order. |
+| `kind` | no | `"adr"`, `"entity"`, `"concept"`, `"architecture"`, `"guide"`, `"use-case"`, `"reference"`. Lets renderers pick the right treatment. |
+| `area` | no | Names the implementation the document belongs to. |
+| `supersedes` | no | Filename (without extension) of the document this one replaces. |
+| `supersededBy` | no | Filename of the document that replaced this one. |
+
+### Tense and stance
+
+Documents describe what the system does, in the present tense, observed rather than advertised. "The publication function returns pieces ordered by `sort_order`." Not "The publication function will return…" and not "We should implement…". The tense holds whether the behaviour is currently built or still being specified; the `status` frontmatter carries the difference.
+
+The stance is observational. A Regardio document is not a pitch. It notices how the system fits together and what follows from that. Reliability, safety, transparency, usefulness, and care for the people the software serves show up through how the reasoning is laid out, not by being claimed. A reader who finishes a document should be able to make their own judgement about whether the system is sound — that is what the prose is for.
+
+### What shows up where
+
+- **Code snippets** appear where they clarify a contract, a data shape, or a naming pattern. Reference catalogues quite properly carry several; decision records rarely need any. A snippet never stands in for the reasoning around it.
+- **Names** (files, functions, columns, handles) appear where they are contracts readers rely on. They do not appear as a substitute for describing what something does.
+- **Procedural steps** belong in runbooks and READMEs. A domain spec does not read like a cookbook.
+
+### Cross-references
+
+Links carry a short descriptor of what the link leads to, not just a filename:
+
+```markdown
+The [Channel](../entities/channel.md) is the publication destination;
+the [Publishing Architecture](../architecture/publishing-architecture.md)
+describes how callers reach it.
+```
+
+`## Related` at the end of a document lists the next pages a reader is likely to want.
+
+### Voice
+
+The [Writing](./writing.md) standard covers voice, tone, and language. This document relies on it rather than repeating it.
+
+## Alternatives Considered
+
+### A single ADR skeleton for every document
+
+**Dismissed because** it presses reference catalogues and tool introductions into a shape that does not suit them. The skeleton adds ceremony where the content is already clear, and readers learn to skim past sections that carry no weight. The skeleton remains available for documents whose content earns it.
+
+### No shared shape at all
+
+**Dismissed because** indexing and cross-referencing need something predictable to bind to, and readers benefit from landing on any document and knowing roughly where to look. A thin shared surface — frontmatter, opening line, closing references — is enough.
+
+### Separate templates per document kind
+
+**Dismissed because** the kinds blur at the edges. An entity note sometimes carries a decision; a use case sometimes carries a catalogue. A small set of recognisable shapes that documents can borrow from works better than a closed list of templates.
+
+## Operational Rules
+
+### Frontmatter is complete
+
+Every document carries `title`, `description`, `publishedAt`, `status`, and `language`. Tooling that indexes or lists documents relies on these five.
+
+### Opening names the subject
+
+Before the first sub-heading, a reader can tell what the document is for. If the opening does not make this clear, the document is not ready.
+
+### Shape follows content
+
+The body takes the shape the content asks for. A decision record uses the ADR skeleton if that skeleton helps the reasoning; a reference uses a catalogue; an introduction stays short. Where a document borrows from more than one shape, it does so in service of the reader, not in service of the template.
+
+### Tense is present, stance is observational
+
+Documents describe the system as it is, in the present tense. Not-yet-built behaviour is flagged through `status`, not through hedged tense. The prose observes rather than promotes.
+
+### Reasoning is preserved, not rewritten
+
+When a decision is revisited, the existing document is superseded. The old reasoning stays readable so that future readers can see what was known at the time. An in-place rewrite that changes direction without supersession loses the history.
+
+### Code and names earn their place
+
+A snippet appears because it clarifies a contract the prose cannot carry alone. A specific name appears because callers rely on it. Both are tools for the reader, not decoration.
+
+### Tests can point at a document
+
+A behaviour worth testing has a place in a document that names it. The document does not need a section labelled "Operational Rules" for this — it needs prose clear enough that a test can quote it and both the test author and the reviewer know what is being verified.
+
+### One subject per document
+
+A document names one entity, one concept, one decision, one scenario. When a draft sprawls across several, the move is to split it.
+
+## Consequences
+
+### Positive
+
+- Documents read naturally for their content. ADRs feel like ADRs; reference catalogues feel like reference catalogues; introductions stay short.
+- Readers find a predictable frontmatter and opening, and the body of each document carries its reasoning in the form that fits.
+- The docs stay honest. Observational prose about what the system does leaves room for the reader to form a judgement, rather than prescribing one.
+- Tests bind to the prose that describes behaviour, wherever in the document that prose lives.
+
+### Negative
+
+- "Shape follows content" asks for judgement. Contributors unsure of the right shape need a reference document to look at; the existing documents serve that role.
+- Without a single template, reviewers sometimes have to say "this would read better as a catalogue" or "this would read better as an ADR". That conversation is part of the standard, not a cost around it.
+
+### Mitigations
+
+- New documents are often patterned on a nearby existing one. A contributor writing a new entity note copies the shape of an adjacent entity note; a contributor writing an ADR copies an adjacent ADR.
+- Reviewers point at this document when a draft has picked a shape that resists its content, and help the author find the form the content already has.
+
+## Related
+
+- [Writing](./writing.md) — Voice, tone, language
+- [Principles](./principles.md) — Shared principles
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/principles.md

@@ -0,0 +1,83 @@
+---
+
+title: "Principles"
+description: "The shared ground Regardio projects stand on — clusters of principles that carry across languages and repos."
+publishedAt: 2026-04-17
+order: 3
+language: "en"
+status: "published"
+kind: "reference"
+---
+
+Regardio spans several codebases and several languages. What keeps them legible to each other is a short list of principles held in common — enough shared ground that a contributor moving between projects finds the same habits in force, and enough room left for each codebase to speak its own idiom.
+
+Seven clusters, a handful of items each.
+
+## Code quality
+
+- Readable code over clever code
+- Consistent naming within each language — `camelCase` in TypeScript, `snake_case` in SQL
+- Small functions with a single responsibility
+- Explicit choices over implicit defaults
+
+## Architecture
+
+- Modules decouple from each other; dependencies are deliberate
+- Duplication resolves into an abstraction only when the pattern is clear
+- Interfaces describe what a module does, not how it does it
+- Concerns separate along the seams the domain suggests
+
+## Error handling
+
+- Input is validated early; failures surface with a clear message
+- Validation covers correctness and security in the same pass
+- Logic stays separated from side effects so it remains testable
+- Dependencies can fail; the code degrades gracefully when they do
+
+## Performance
+
+- Data structures match the shape of the work
+- Measurement comes before optimisation
+- Memory, connections, and file handles are released on the path that acquired them
+- Scale is considered at design time, not retrofitted
+
+## Security
+
+- Client data is untrusted by default; server-side validation is the line
+- Privileges stay narrow; access is opened deliberately
+- Defence is layered; a single check never stands alone
+- Openness is an opt-in, not the default posture
+
+## Maintainability
+
+- Patterns repeat across the codebase so that reading one teaches reading the rest
+- Commits are atomic and speak to one change at a time
+- Refactoring is continuous; debt is paid down rather than accumulated
+
+## Collaboration
+
+- Every change passes through review
+- Code quality is shared, not owned
+- Decisions that involve a real trade-off leave a trace in the project's `docs/en` tree
+
+## Implementation workflow
+
+Non-trivial work tends to follow this sequence — not as a ritual, but because skipping a step usually costs more later than it saves now:
+
+1. **Understand the business logic first.** The deepest defects come from misunderstood requirements. Read the relevant domain document; know what is needed now rather than what might be needed later.
+2. **Look for existing solutions.** Well-maintained libraries are evaluated before custom code is written. Dependencies are vetted for design quality, test coverage, and recent activity.
+3. **Write the tests as specification.** The behaviour a change produces is described as tests before the change is written. Tests are the contract; the code is measured against them.
+4. **Implement with reusability in mind, not reusability as the goal.** Duplicate until the pattern is clear, then extract. Wrong abstractions cost more than duplication.
+5. **Stop and reconsider when complexity grows.** Difficulty that keeps growing despite good preparation is a signal. Back out, simplify, or question the approach.
+6. **Document intent, not mechanics.** Comments explain *why*; the code explains *what*. Existing context is checked before new prose is added.
+
+## Related
+
+- [Writing](./writing.md) — Voice, tone, language
+- [Documentation](./documentation.md) — How documents are shaped
+- [Coding](./standards/coding.md) — TypeScript and general patterns
+- [Testing](./standards/testing.md) — Testing philosophy
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/docs/en/tools/releases.md

@@ -56,7 +56,7 @@ production ──► hotfix/<name>  (fix here with conventional commits)
 
 ## Versioning — Per-Package, at Ship Time
 
-`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:
+`ship:production` and `ship:hotfix finish` discover all workspace packages that have a `.versionrc.json` and ask you to assign a bump type to each:
 
 - `0` — skip (no version change)
 - `1` — patch
@@ -65,32 +65,32 @@ production ──► hotfix/<name>  (fix here with conventional commits)
 
 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`).
 
-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.
+If no packages have a `.versionrc.json`, the versioning UI is skipped and `ship:production` proceeds directly to the git merge.
 
 ## CI — What Happens on Each Branch
 
 CI behaviour differs by what the repo produces.
 
-### Publishing monorepos (e.g. `commons`)
+### Publishing monorepos
 
 - **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.
 
-### Server-deployed apps with Docker (e.g. `brass-berlin`)
+### Server-deployed apps with Docker
 
 - **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`)
+### Cloudflare Workers apps
 
 - **staging**: Run tests, then `wrangler versions upload --preview-alias preview`.
 - **production**: Run typecheck + tests, then `wrangler deploy`.
 
-### Documentation / vocabulary repos (e.g. `system`)
+### Documentation / vocabulary repos
 
 - **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`)
+### Static sites without a configured deployment
 
 - **staging** and **production**: Run tests, typecheck (production only), and build. A deployment step is left as a TODO until the hosting platform is chosen.
 
@@ -122,8 +122,8 @@ pnpm ship:production
 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).
+5. If packages have `.versionrc.json`: assign a bump type to each; confirm the planned bumps.
+6. If no packages have `.versionrc.json`: 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.
@@ -139,7 +139,7 @@ git add . && git commit -m "fix: ..."
 pnpm ship:hotfix finish
 ```
 
-`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.
+`finish` fetches origin, runs quality checks, assigns bump types (for packages with `.versionrc.json`), versions the fix, then merges `hotfix → production → staging → main` and deletes the hotfix branch.
 
 ## Adoption
 
@@ -155,25 +155,22 @@ pnpm ship:hotfix finish
 }
 ```
 
-For repos that publish to npm, also add:
+### 2. Add `.versionrc.json` to each package you want versioned
+
+```bash
+cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
+```
+
+Then replace both `@my-scope/my-pkg` placeholders in that file with your actual package name:
 
 ```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"
-  }
+  "tagPrefix": "@my-scope/my-pkg@v",
+  "releaseCommitMessageFormat": "chore(release): @my-scope/my-pkg@v{{currentTag}}"
 }
 ```
 
-### 2. Add `.versionrc.json` to each publishable package
-
-```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
-```
+`tagPrefix` scopes the git tag to the package. `releaseCommitMessageFormat` puts the full package identifier in the release commit subject, so the monorepo history reads `chore(release): @my-scope/my-pkg@v1.2.0` rather than a bare version number.
 
 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.
 
@@ -192,14 +189,14 @@ git checkout main
 ```bash
 # Forgejo / Codeberg
 mkdir -p .forgejo/workflows
-cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/production.yml
+cp node_modules/@regardio/dev/templates/actions/forgejo-release.yml .forgejo/workflows/release.yml
 
 # GitHub
 mkdir -p .github/workflows
-cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
+cp node_modules/@regardio/dev/templates/actions/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.
+Both templates cover the npm-publishing case. Adapt the publish job for Docker / Cloudflare deployments as described in the CI section above.
 
 ### 5. First publish of any new package must be done locally
 
@@ -219,11 +216,11 @@ pnpm typecheck  # Must succeed
 pnpm test       # Must succeed
 ```
 
-## Private Packages and Non-Publishing Repos
+## Publishing vs Non-Publishing Repos
 
-Packages with `"private": true` are skipped by `pnpm -r publish` automatically.
+Packages with `"private": true` are skipped by `pnpm -r publish` automatically — CI only publishes public packages to npm.
 
-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.
+Whether a package is published to npm is independent of whether it gets versioned. The ship tooling uses `.versionrc.json` presence as the signal for versioning, not the `private` flag. A private channel app or a vocabulary repo can run `ship:production`, get a version bump, a CHANGELOG entry, and a scoped git tag, without ever touching npm.
 
 ## Related
 

package/docs/en/writing.md

@@ -0,0 +1,118 @@
+---
+
+title: "Writing"
+description: "Voice, tone, and language Regardio content carries, in English and German."
+publishedAt: 2026-04-17
+order: 2
+language: "en"
+status: "published"
+kind: "concept"
+---
+
+The voice in which Regardio writes about itself and its tools.
+
+## What you are doing
+
+You write *from within* the System, not *about* it. Your aim is to trigger recognition. The reader you are writing for should be able to think *Yes, that's how it is.*
+
+Two trains of thought carry everything the System does — and everything you write about it.
+
+**Any one object can be observed from two sides.** Front and back, inside and outside, past and future, still and moving, question and answer, start and finish. A thing that looks complete from one angle shows something new from the other. Writing that only shows one side flattens what it describes. Writing that acknowledges both gives the reader room to stand where they already stand.
+
+**A whole becomes graspable when it is cut into a few distinct parts.** Six is the number to return to: enough variety to cover what matters, few enough to hold in the head at once, clear enough to name and locate each piece. A pie cut into six slices is something anyone can picture. When a subject resists clarity, the move is not more words — it is better cuts.
+
+These two habits are the grammar underneath the System. Carry them quietly. You rarely name them. They are just the shape of the thinking.
+
+## How to meet the reader
+
+Every reader comes with their own life and their own pursuit. Assume they notice things for themselves. Trust them to do their own connecting. Address them directly, without talking up or down.
+
+The ground under the writing is careful observation of how people actually feel, think, and act — not advice about how they should. When an idea becomes personally recognizable while staying broadly true, it has landed. When it only flatters or only instructs, it hasn't.
+
+## Stance
+
+Six movements carry every piece.
+
+1. **Derive, don't declare.** One thought leads to the next. "The System recognizes…" speaks from above. Better: the observation that leads to the structure. Readers follow a line of thought, not an instruction.
+2. **Observe, don't instruct.** Write like someone who has listened carefully and is sharing an observation, not like someone explaining a method.
+3. **Structure offers freedom, not rules.** The cuts exist to widen a view that has become too narrow, not to discipline one that is already broad.
+4. **Suggest possibilities to choose from.** Offer angles, not answers. Let the reader decide what fits. Suggest questions that people have, not riddles to solve.
+5. **Turned toward what could be, without promises.** Warm, attentive, spacious. Curious about people rather than diagnostic. No salvation talk, no coaching register.
+6. **Good humor makes the deepest thought approachable.** Lightness when it fits. Not forced, not absent. When the moment is right, a small wink can carry weight without claiming it.
+
+## Before and after
+
+**Instead of:** *"Apply this framework to align your team."*
+**Try:** *"What does the decision we made last week have to do with what's slowing us down now?"*
+
+**Instead of:** *"The System helps you gain clarity."*
+**Try:** *"A few angles worth looking at, whatever the pursuit."*
+
+**Instead of:** *"Pursuits flourish with a clear core."*
+**Try:** *"How will we know when we've arrived?"*
+
+The System's questions are not headers. They are real questions, worth sitting with.
+
+## Language
+
+Language that leaves room lets readers think. Language that pushes does the thinking for them. Given the choice, choose room.
+
+**Favor:** notice, explore, find, might, could, pattern, rhythm, carry, hold — words that leave room.
+
+**Avoid:** must, potential, resources, values, purpose, sustainability, growth, leverage, empower, ownership, good, bad. These either push or have been worn down to noise.
+
+**No method jargon.** Not from business, not from coaching, not from therapy, not from spirituality. If a term has a clear everyday word behind it, use the everyday word.
+
+**People are not categories.** Describe what people do and bring about, not what they are. This is also how gendered forms are handled — name actions, not groups.
+
+**The System is humane.** Equal, free cooperation is built in. Avoid connotations of hierarchy, ownership, dominance, control, or force. Reflect that without announcing it.
+
+**Complexity earns its place or goes.** Make hard ideas reachable without flattening them. If a sentence has to be read twice, shorten it. If an idea has been reduced past recognition, let it breathe again.
+
+## System terms
+
+System terms carry precisely defined concepts. Use them as they are; don't swap in synonyms for variety. When tempted to reach for a buzzword, reach for a System term instead — if it fits. If no System term fits, the buzzword probably isn't earning its place either.
+
+In every language the System is written in, the terms are chosen to capture the spirit of each concept in that language — not to translate literally from another. Don't import words from other languages into the prose. Let each language stand on its own.
+
+## Roots, kept in the background
+
+The System draws from many traditions of thought. Reference intents and ideas, not names or schools. The sources show themselves in the structure, not in citation. This is working craft carried by collective intelligence, not an elaborate treatise.
+
+## Format and craft
+
+**Headers** for orientation. **Prose** for connected thought. **Bold** for System terms at first introduction. *Italics* for genuine emphasis. No emojis. Lists only when the content is genuinely a list — bullets never replace a thought.
+
+## Language-specific caveats
+
+### German
+
+- Address the reader with *du* unless the context clearly calls for *Sie* (formal contracts, legal notices). Keep it direct, without affectation.
+- No gendering artifacts: no *:innen*, no asterisks, no *(m/w/d)*. Prefer action-based descriptions over group labels: *wer etwas vorhat*, *ein Mensch, der …*, *die Person, die …*, *Mitwirkende*, *Beteiligte*.
+- Quotation marks: German low-high („…") in body text.
+
+### English
+
+- American English: *organize*, *color*, *toward*, *behavior*, *center*. Periods and commas inside quotation marks.
+- No gendered forms. Name actions: *the person pursuing this*, *contributors*, *those involved*. Singular *they* is fine where a pronoun is unavoidable.
+- Quotation marks: straight double quotes (") in Markdown source; typographic quotes ("…") in rendered prose.
+
+## Check before publishing
+
+- Does it sound like a conversation the reader would want to be in?
+- Does the text derive rather than declare?
+- Are abstract thoughts grounded in concrete examples?
+- Are System terms used consistently, in their precise meaning?
+- Is it free of coaching register, pigeonholing, and tired buzzwords?
+- Could the honest response be *"Yes, that's how it is"*?
+
+*This guide is itself a living text. When in doubt: would you enjoy reading this?*
+
+## Related
+
+- [Documentation](./documentation.md) — How Regardio shapes its documents
+- [Principles](./principles.md) — Shared principles
+
+---
+
+**License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "@regardio/dev",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "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.1",
+    "@types/node": "25.6.2",
     "@vitest/coverage-v8": "4.1.5",
     "tsdown": "0.22.0",
     "vitest": "4.1.5"

package/templates/actions/forgejo-release.yml

@@ -0,0 +1,116 @@
+# Regardio npm-publishing workflow — Forgejo Actions
+#
+# Pushes to staging and production are driven by ship tooling, not by hand:
+#   pnpm ship:staging    — fast-forward main → staging (no version bump)
+#   pnpm ship:production — version bump + main → production + sync staging
+#   pnpm ship:hotfix finish — version bump + hotfix → production → staging → main
+#
+# Full documentation: node_modules/@regardio/dev/docs/en/tools/releases.md
+#
+# This template covers the npm-publishing case.
+# Adapt the publish job for Docker / Coolify deployments as needed.
+#
+# Required setup:
+#   1. Ship scripts in package.json (ship:hotfix, ship:production, ship:staging)
+#   2. .versionrc.json in each publishable package directory
+#      (template: node_modules/@regardio/dev/templates/versionrc/.versionrc.json)
+#   3. staging and production branches created and pushed
+#   4. NPM_TOKEN repo secret; first publish of any new package done locally
+#
+# NOTE: npm provenance is not supported on Forgejo. If Forgejo is added to
+# npm's trusted-publisher list in the future, add --provenance to the publish step.
+
+name: Release
+
+on:
+  push:
+    branches: [staging, production]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_name == 'staging' }}
+
+jobs:
+  typecheck:
+    name: ʦ TypeScript
+    # Husky enforces typecheck pre-commit; only re-run on production to guard against hotfixes.
+    if: github.ref_name == 'production'
+    runs-on: codeberg-small
+    timeout-minutes: 8
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: corepack enable
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: pnpm-${{ runner.os }}-
+      - run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
+      - run: pnpm typecheck
+
+  test:
+    name: ⚫️ Test
+    runs-on: codeberg-small
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 1
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: corepack enable
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: pnpm-${{ runner.os }}-
+      - run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
+      - run: pnpm test
+
+  publish:
+    name: 📦 Publish
+    needs: [typecheck, test]
+    if: |
+      always() &&
+      github.ref_name == 'production' &&
+      needs.typecheck.result == 'success' &&
+      needs.test.result == 'success'
+    runs-on: codeberg-small
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: corepack enable
+      - name: Get pnpm store path
+        id: pnpm-store
+        run: echo "path=$(pnpm store path --silent)" >> $GITHUB_OUTPUT
+      - uses: actions/cache@v4
+        with:
+          path: ${{ steps.pnpm-store.outputs.path }}
+          key: pnpm-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+          restore-keys: pnpm-${{ runner.os }}-
+      - name: Configure npm auth
+        run: echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
+      - run: pnpm -r build
+      - run: pnpm -r publish --access public --no-git-checks
+        env:
+          NPM_CONFIG_USERCONFIG: /root/.npmrc

package/templates/actions/github-release.yml

@@ -0,0 +1,93 @@
+# Regardio npm-publishing workflow — GitHub Actions
+#
+# Pushes to staging and production are driven by ship tooling, not by hand:
+#   pnpm ship:staging    — fast-forward main → staging (no version bump)
+#   pnpm ship:production — version bump + main → production + sync staging
+#   pnpm ship:hotfix finish — version bump + hotfix → production → staging → main
+#
+# Full documentation: node_modules/@regardio/dev/docs/en/tools/releases.md
+#
+# This template covers the npm-publishing case.
+# Adapt the publish job for Docker / Cloudflare deployments as needed.
+#
+# Required setup:
+#   1. Ship scripts in package.json (ship:hotfix, ship:production, ship:staging)
+#   2. .versionrc.json in each publishable package directory
+#      (template: node_modules/@regardio/dev/templates/versionrc/.versionrc.json)
+#   3. staging and production branches created and pushed
+#   4. NPM_TOKEN repo secret; first publish of any new package done locally
+
+name: Release
+
+on:
+  push:
+    branches: [staging, production]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref_name == 'staging' }}
+
+jobs:
+  typecheck:
+    name: ʦ TypeScript
+    # Husky enforces typecheck pre-commit; only re-run on production to guard against hotfixes.
+    if: github.ref_name == 'production'
+    runs-on: ubuntu-latest
+    timeout-minutes: 8
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+      - uses: pnpm/action-setup@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
+      - run: pnpm typecheck
+
+  test:
+    name: ⚫️ Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 1
+      - uses: pnpm/action-setup@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
+      - run: pnpm test
+
+  publish:
+    name: 📦 Publish
+    needs: [typecheck, test]
+    if: |
+      always() &&
+      github.ref_name == 'production' &&
+      needs.typecheck.result == 'success' &&
+      needs.test.result == 'success'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: pnpm/action-setup@v5
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: pnpm
+          registry-url: https://registry.npmjs.org
+      - run: pnpm install --frozen-lockfile --ignore-scripts --prefer-offline
+      - run: pnpm -r build
+      - run: pnpm -r publish --access public --no-git-checks
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NPM_CONFIG_PROVENANCE: "true"

package/templates/agents/CLAUDE.md

@@ -0,0 +1,37 @@
+# [Project Name] — Agent Context
+
+[One sentence: what this project is and its role.]
+
+## Standards
+
+This project uses `@regardio/dev`. After `pnpm install`, all Regardio standards are available locally:
+
+| What | Path |
+|------|------|
+| Full index | `node_modules/@regardio/dev/docs/en/README.md` |
+| Principles | `node_modules/@regardio/dev/docs/en/principles.md` |
+| Writing & language | `node_modules/@regardio/dev/docs/en/writing.md` |
+| Documentation shape | `node_modules/@regardio/dev/docs/en/documentation.md` |
+| Code standards | `node_modules/@regardio/dev/docs/en/standards/` |
+| Toolchain | `node_modules/@regardio/dev/docs/en/tools/` |
+
+Read the full index first. It lists every standard and toolchain doc in one place.
+
+## Structure
+
+[Describe the project's key directories and what lives where.]
+
+## Commands
+
+```bash
+pnpm build      # Build
+pnpm test       # Run tests
+pnpm typecheck  # Type check
+pnpm lint       # Lint
+```
+
+Run `typecheck` and `lint` before calling a task done.
+
+## Working here
+
+[Anything project-specific an agent needs to know: domain context, conventions that differ from the standards, areas to be careful about.]

package/templates/versionrc/.versionrc.json

@@ -1,17 +1,48 @@
 {
   "commitAll": false,
-  "gitRawCommitsOpts": { "path": "." },
+  "gitRawCommitsOpts": {
+    "path": "."
+  },
+  "releaseCommitMessageFormat": "chore(release): @my-scope/my-pkg@v{{currentTag}}",
   "sign": false,
-  "tagPrefix": "v",
+  "tagPrefix": "@my-scope/my-pkg@v",
   "types": [
-    { "section": "Features", "type": "feat" },
-    { "section": "Bug Fixes", "type": "fix" },
-    { "section": "Performance", "type": "perf" },
-    { "section": "Refactoring", "type": "refactor" },
-    { "hidden": false, "section": "Chores", "type": "chore" },
-    { "hidden": true, "type": "docs" },
-    { "hidden": true, "type": "style" },
-    { "hidden": true, "type": "test" },
-    { "hidden": true, "type": "ci" }
+    {
+      "section": "Features",
+      "type": "feat"
+    },
+    {
+      "section": "Bug Fixes",
+      "type": "fix"
+    },
+    {
+      "section": "Performance",
+      "type": "perf"
+    },
+    {
+      "section": "Refactoring",
+      "type": "refactor"
+    },
+    {
+      "hidden": false,
+      "section": "Chores",
+      "type": "chore"
+    },
+    {
+      "hidden": true,
+      "type": "docs"
+    },
+    {
+      "hidden": true,
+      "type": "style"
+    },
+    {
+      "hidden": true,
+      "type": "test"
+    },
+    {
+      "hidden": true,
+      "type": "ci"
+    }
   ]
 }

package/templates/github/release.yml

@@ -1,68 +0,0 @@
-# Regardio Release Workflow (GitHub Actions)
-# Copy this file to .github/workflows/release.yml
-#
-# Required setup:
-# 1. Add these scripts to package.json:
-#      "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:staging": "ship-staging",
-#      "ship:production": "ship-production",
-#      "ship:hotfix": "ship-hotfix"
-# 2. Copy .versionrc.json from node_modules/@regardio/dev/templates/versionrc/.versionrc.json
-# 3. Create the branches:
-#      git checkout -b staging && git push -u origin staging
-#      git checkout -b production && git push -u origin production
-# 4. Add `NPM_TOKEN` to repo secrets. First npm publish of any new package
-#    must be done locally (`npm publish --access public`).
-#
-# Usage:
-# - `pnpm ship:staging` deploys to staging for validation (optional)
-# - `pnpm ship:production` runs commit-and-tag-version locally, bumps the version,
-#   merges to production. This workflow then publishes to npm.
-
-name: Release
-
-on:
-  push:
-    branches:
-      - production
-
-concurrency: ${{ github.workflow }}-${{ github.ref }}
-
-jobs:
-  release:
-    name: Release
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      id-token: write
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v5
-        with:
-          version: 10
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: 24
-          registry-url: https://registry.npmjs.org
-
-      - name: Install dependencies
-        run: pnpm install --frozen-lockfile
-
-      - name: Build
-        run: pnpm -r build
-
-      - name: Publish changed public packages
-        run: pnpm -r publish --access public --no-git-checks
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-          NPM_CONFIG_PROVENANCE: "true"