@regardio/dev 2.4.1 → 2.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,8 +1,8 @@
1
1
  ---
2
2
 
3
3
  title: "Release Workflow"
4
- description: "Branch-based release workflow for Regardio packagesmain staging production, driven by commit-and-tag-version."
5
- publishedAt: 2026-04-17
4
+ description: "GitLab-flow release workflow for Regardio reposbranches mirror environments, ship tooling drives versioning, CI carries it out."
5
+ publishedAt: 2026-05-07
6
6
  language: "en"
7
7
  status: "published"
8
8
  kind: "guide"
@@ -11,115 +11,92 @@ area: "dev"
11
11
 
12
12
  # Release Workflow
13
13
 
14
- Branch-based release workflow for Regardio packages. `main` `staging` `production`. `commit-and-tag-version` reads conventional commits to determine the version bump; quality gates run locally before any branch promotion. Nothing broken reaches a shared branch.
14
+ Branches mirror environments. `main` is where development happens. `staging` reflects what is deployed to the staging server. `production` reflects what is live. Version bumps happen locally at ship time CI on `production` carries the result out (publishes to npm or deploys to a server).
15
15
 
16
- ## Overview
16
+ ## The Three-Branch Model
17
17
 
18
- Branches mirror deployment environments:
18
+ ```text
19
+ main ──── ship:staging ────► staging (optional staging server)
20
+
21
+ └──── ship:production ──► production (live / npm)
22
+
23
+ sync back to staging
24
+ ```
25
+
26
+ | Branch | Contains | CI role |
27
+ |--------|----------|---------|
28
+ | `main` | All committed, tested work | None (Husky runs local gates on commit) |
29
+ | `staging` | Deployed to staging server or preview | Verify + deploy to staging |
30
+ | `production` | Only shipped, versioned releases | Verify + deploy or publish |
31
+
32
+ **Why version bumps happen locally, not in CI.** Hotfixes start from `production` and must write their version bump back up through `staging` and `main` in one pass. Keeping the bump local means both the normal ship path and the hotfix path behave identically — there is no special case in CI.
33
+
34
+ ## Hotfix Flow
35
+
36
+ A hotfix is an urgent fix that must go to production immediately, without pulling in unreleased changes from `main`.
19
37
 
20
38
  ```text
21
- main staging (optional) production
39
+ production ──► hotfix/<name> (fix here with conventional commits)
40
+
41
+ └──► production ──► staging ──► main
22
42
  ```
23
43
 
24
- - **`main`** active development, always deployable. Version bumps happen at ship time, not per-commit.
25
- - **`staging`** — optional validation environment. No versioning happens here.
26
- - **`production`** — versioned, published code only.
44
+ `ship:hotfix start <name>` creates the branch from `production`, not from `main`. This is deliberate: it avoids accidentally shipping work-in-progress that has not yet been reviewed for production.
27
45
 
28
- When `ship-production` runs, it discovers all publishable workspace packages and asks you to assign a bump type — `0` (skip), `1` (patch), `2` (minor), or `3` (major) to each one individually. Packages you skip are left untouched. It determines the highest bump type across all selected packages and runs `pnpm release:<type>` at the root, which bumps versions, rewrites `CHANGELOG.md`, and commits on `main`. If no release script exists (non-publishing repos like channels), versioning is skipped entirely and only the git merges happen. The branches merge once after all bumps are applied. CI on `production` publishes only the packages whose version changed.
46
+ `ship:hotfix finish` versions the fix, merges it into `production`, then propagates through `staging` and back to `main` so nothing is lost.
29
47
 
30
- ## How It Works
48
+ ## Commands
31
49
 
32
- ### Design principles
50
+ | Command | Purpose |
51
+ |---------|---------|
52
+ | `pnpm ship:staging` | Fast-forward `main` → `staging`, push. Triggers staging CI. |
53
+ | `pnpm ship:production` | Version selected packages (if any), fast-forward `main` → `production`, sync `staging`. Triggers production CI. |
54
+ | `pnpm ship:hotfix start <name>` | Create `hotfix/<name>` from `production`. |
55
+ | `pnpm ship:hotfix finish` | Version selected packages (if any), merge hotfix → `production` → `staging` → `main`. |
33
56
 
34
- 1. **Branches mirror environments.** `staging` reflects what is deployed to the staging server (when used); `production` always reflects what is published to npm. There is never ambiguity about what is running where.
35
- 2. **You choose the bump per package at ship time.** When running `ship-production` or `ship-hotfix finish`, every publishable package is listed and you assign it `0` (skip), `1` (patch), `2` (minor), or `3` (major). Packages you skip are untouched. The conventional commits in the log inform each choice; the decisions are always explicit.
36
- 3. **Version numbers are a production guarantee.** Bumps are applied only at `ship-production` time. Every version tag in git and every release on npm corresponds to code that has been validated and shipped.
37
- 4. **Staging is optional.** You can ship directly from `main` to `production`. Use `ship-staging` when you want to test changes in a staging environment first.
38
- 5. **Tests are a local gate, not a CI gate.** Quality checks (`lint`, `typecheck`, `test`) run on your machine before any commit is made. Broken code cannot enter the repository.
39
- 6. **You always land back on `main`.** Every command returns you to `main` when it finishes.
57
+ ## Versioning Per-Package, at Ship Time
40
58
 
41
- ### Full flow diagram
59
+ `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:
42
60
 
43
- ```text
44
- ship-staging (OPTIONAL)
45
- ┌──────────────────────────┐
46
- main ───────────┤ quality checks pass ├──► staging (pushed)
47
- │ ff-merge main → staging │
48
- └──────────────────────────┘
49
-
50
- (validated in staging)
51
-
52
-
53
- ship-production
54
- ┌──────────────────────────┐
55
- │ quality checks on main │
56
- │ select packages/bumps │
57
- │ pnpm release:<type>* │
58
- main ───────────┤ bumps version + ├──► production
59
- │ rewrites CHANGELOG.md │
60
- │ ff-merge main → prod │
61
- │ ff-merge prod → staging │
62
- │ push --follow-tags main │
63
- └──────────────────────────┘
64
-
65
- (CI: pnpm -r publish → npm)
66
-
67
- production
68
-
69
-
70
- ship-hotfix start fix-name
71
- ┌──────────────────────────┐
72
- production ─────┤ create hotfix/fix-name ├──► hotfix/fix-name
73
- └──────────────────────────┘
74
-
75
- (author fixes with conventional commits)
76
-
77
- ship-hotfix finish
78
- ┌──────────────────────────┐
79
- │ quality checks │
80
- │ pnpm release:<type>* │
81
- hotfix/fix-name ┤ bumps version + ├──► production → staging → main
82
- │ rewrites CHANGELOG.md │
83
- │ merge to production │
84
- │ propagate to staging │
85
- │ propagate to main │
86
- └──────────────────────────┘
87
- ```
61
+ - `0` — skip (no version change)
62
+ - `1` — patch
63
+ - `2` — minor
64
+ - `3` major
88
65
 
89
- ### What each branch represents at any point in time
66
+ 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`).
90
67
 
91
- | Branch | Contains | Version bumped? |
92
- |--------|----------|-----------------|
93
- | `main` | All committed, tested work | Only after `ship-production` / `ship-hotfix finish` |
94
- | `staging` | Synced from `production` after each ship, or from `main` via `ship-staging` | After a ship propagates |
95
- | `production` | Only shipped, versioned releases | Yes — always |
68
+ If no packages have a `.versionrc.json`, the versioning UI is skipped and `ship:production` proceeds directly to the git merge.
96
69
 
97
- ### CI role
70
+ ## CI — What Happens on Each Branch
98
71
 
99
- CI is intentionally minimal. On push to `production` it:
72
+ CI behaviour differs by what the repo produces.
100
73
 
101
- 1. Installs dependencies and builds
102
- 2. Runs `pnpm -r publish --access public --no-git-checks` — publishes every workspace package whose current version is not yet on npm, skipping `private: true` packages
103
- 3. Tags are already present (pushed by `ship-production` via `--follow-tags`)
74
+ ### Publishing monorepos
104
75
 
105
- ## Commands
76
+ - **staging**: Run typecheck and tests. Nothing is published.
77
+ - **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.
106
78
 
107
- | Command | Usage | Purpose |
108
- |---------|-------|---------|
109
- | `pnpm release` | auto | Bump version from conventional commits, update CHANGELOG.md, commit |
110
- | `pnpm release:patch` | explicit | Force a patch bump |
111
- | `pnpm release:minor` | explicit | Force a minor bump |
112
- | `pnpm release:major` | explicit | Force a major bump |
113
- | `ship-staging` | `ship-staging` | (Optional) Deploy changes to staging for testing |
114
- | `ship-production` | `ship-production` | Bump version, merge main → production, trigger publish |
115
- | `ship-hotfix start <name>` | `ship-hotfix start <name>` | Create a hotfix branch from production |
116
- | `ship-hotfix finish` | `ship-hotfix finish` | Bump version, propagate hotfix through production → staging → main |
79
+ ### Server-deployed apps with Docker
117
80
 
118
- ## Typical Release Flow
81
+ - **staging**: Run tests, build the Docker image, push to the container registry, trigger a staging deploy (e.g. Coolify webhook).
82
+ - **production**: Run typecheck + tests, build and push the Docker image, trigger a production deploy.
83
+
84
+ ### Cloudflare Workers apps
85
+
86
+ - **staging**: Run tests, then `wrangler versions upload --preview-alias preview`.
87
+ - **production**: Run typecheck + tests, then `wrangler deploy`.
88
+
89
+ ### Documentation / vocabulary repos
119
90
 
120
- ### 1. Develop with conventional commits
91
+ - **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.
121
92
 
122
- On `main`, use conventional commits so the bump type is inferred automatically:
93
+ ### Static sites without a configured deployment
94
+
95
+ - **staging** and **production**: Run tests, typecheck (production only), and build. A deployment step is left as a TODO until the hosting platform is chosen.
96
+
97
+ ## Typical Release Flow
98
+
99
+ ### 1. Develop on `main` with conventional commits
123
100
 
124
101
  ```bash
125
102
  feat: add user authentication # → minor bump
@@ -127,111 +104,111 @@ fix: resolve login redirect loop # → patch bump
127
104
  feat!: redesign authentication API # → major bump
128
105
  ```
129
106
 
130
- ### 2. Ship to production
107
+ ### 2. (Optional) Test in staging first
131
108
 
132
109
  ```bash
133
- pnpm ship:production
110
+ pnpm ship:staging
134
111
  ```
135
112
 
136
- This will:
137
-
138
- 1. Guard: must be on `main`, working tree clean
139
- 2. Fetch and verify `staging` + `production` branches exist
140
- 3. Show commits to be shipped
141
- 4. Run full quality suite on `main` — aborts on failure
142
- 5. For each publishable package: choose `0 (skip) / 1 (patch) / 2 (minor) / 3 (major)`
143
- 6. Confirm the planned bumps — abort if declined or all skipped
144
- 7. Run `pnpm release:<type>` at the root (highest bump type) — bumps versions, rewrites `CHANGELOG.md`, commits. If no release script exists, skip versioning.
145
- 8. Fast-forward merge `main` into `production` and push
146
- 9. Sync `staging` with `production`
147
- 10. Push `main` with `--follow-tags` to push all new version tags
148
- 11. Return to `main`
149
-
150
- CI on `production` runs `pnpm -r publish` to push changed packages to npm.
113
+ Deploys `main` to `staging` without touching versions.
151
114
 
152
- ### Option: Test in staging first
115
+ ### 3. Ship to production
153
116
 
154
117
  ```bash
155
- pnpm ship:staging
118
+ pnpm ship:production
156
119
  ```
157
120
 
158
- Deploys `main` to `staging` without touching versions. Useful for validating in a staging environment before shipping to production.
121
+ 1. Guard: must be on `main`, working tree clean.
122
+ 2. Fetch and verify `staging` and `production` branches exist.
123
+ 3. Show commits to be shipped.
124
+ 4. Run full quality suite — aborts on failure.
125
+ 5. If packages have `.versionrc.json`: assign a bump type to each; confirm the planned bumps.
126
+ 6. If no packages have `.versionrc.json`: confirm whether to ship (versioning is skipped).
127
+ 7. For each selected package: run `commit-and-tag-version --release-as <type>` from within the package directory.
128
+ 8. Fast-forward merge `main` → `production`, push.
129
+ 9. Sync `staging` with `production`, push.
130
+ 10. Push `main` with `--follow-tags` to carry the new version tags.
131
+ 11. Return to `main`.
159
132
 
160
- ## Hotfix Flow
161
-
162
- For urgent fixes that must go directly to production:
133
+ ### 4. Hotfix flow
163
134
 
164
135
  ```bash
165
136
  pnpm ship:hotfix start fix-auth-bug
166
- # apply your fix with conventional commits
137
+ # apply fix with conventional commits
167
138
  git add . && git commit -m "fix: ..."
168
139
  pnpm ship:hotfix finish
169
140
  ```
170
141
 
171
- `finish` asks you to assign a bump type (`0` (skip), `1` (patch), `2` (minor), or `3` (major)) to each publishable package, runs `pnpm release:<type>` at the root (highest bump type) to bump versions and update `CHANGELOG.md`. If no release script exists, versioning is skipped. Then it merges `hotfix → production → staging → main` and deletes the hotfix branch. CI publishes from `production`.
142
+ `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.
172
143
 
173
144
  ## Adoption
174
145
 
175
- Install `@regardio/dev` and:
146
+ ### 1. Add ship scripts to `package.json`
147
+
148
+ ```json
149
+ {
150
+ "scripts": {
151
+ "ship:hotfix": "ship-hotfix",
152
+ "ship:production": "ship-production",
153
+ "ship:staging": "ship-staging"
154
+ }
155
+ }
156
+ ```
157
+
158
+ ### 2. Add `.versionrc.json` to each package you want versioned
176
159
 
177
- 1. **Add the scripts to `package.json`** (optional, for publishing repos):
160
+ ```bash
161
+ cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
162
+ ```
178
163
 
179
- For repos that publish to npm, add release scripts to the root `package.json`:
164
+ Then replace both `@my-scope/my-pkg` placeholders in that file with your actual package name:
180
165
 
181
- ```json
182
- {
183
- "scripts": {
184
- "release": "commit-and-tag-version",
185
- "release:major": "commit-and-tag-version --release-as major",
186
- "release:minor": "commit-and-tag-version --release-as minor",
187
- "release:patch": "commit-and-tag-version --release-as patch",
188
- "ship:hotfix": "ship-hotfix",
189
- "ship:production": "ship-production",
190
- "ship:staging": "ship-staging"
191
- }
192
- }
193
- ```
166
+ ```json
167
+ {
168
+ "tagPrefix": "@my-scope/my-pkg@v",
169
+ "releaseCommitMessageFormat": "chore(release): @my-scope/my-pkg@v{{currentTag}}"
170
+ }
171
+ ```
194
172
 
195
- For non-publishing repos (e.g., channels that deploy to servers), omit the release scripts the ship commands will skip versioning and only perform the git merges. This makes the tools reusable across both publishing and non-publishing repositories.
173
+ `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.
196
174
 
197
- 2. **Add a `.versionrc.json` to each publishable package** with a scoped `tagPrefix` so tags and changelogs stay isolated per package:
175
+ 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.
198
176
 
199
- ```bash
200
- cp node_modules/@regardio/dev/templates/versionrc/.versionrc.json packages/my-pkg/.versionrc.json
201
- # then set "tagPrefix": "@my-scope/my-pkg@v" inside that file
202
- ```
177
+ For a single-package repo, place `.versionrc.json` at the root instead.
203
178
 
204
- For a single-package repo, put `.versionrc.json` at the root instead.
179
+ ### 3. Create the branches
180
+
181
+ ```bash
182
+ git checkout -b staging && git push -u origin staging
183
+ git checkout -b production && git push -u origin production
184
+ git checkout main
185
+ ```
205
186
 
206
- 3. **Create the branches**:
187
+ ### 4. Copy and adapt the CI workflow
207
188
 
208
- ```bash
209
- git checkout -b staging && git push -u origin staging
210
- git checkout -b production && git push -u origin production
211
- git checkout main
212
- ```
189
+ ```bash
190
+ # Forgejo / Codeberg
191
+ mkdir -p .forgejo/workflows
192
+ cp node_modules/@regardio/dev/templates/actions/forgejo-release.yml .forgejo/workflows/release.yml
213
193
 
214
- 4. **Copy the release workflow** for your forge:
194
+ # GitHub
195
+ mkdir -p .github/workflows
196
+ cp node_modules/@regardio/dev/templates/actions/github-release.yml .github/workflows/release.yml
197
+ ```
215
198
 
216
- ```bash
217
- # GitHub
218
- mkdir -p .github/workflows
219
- cp node_modules/@regardio/dev/templates/github/release.yml .github/workflows/release.yml
199
+ Both templates cover the npm-publishing case. Adapt the publish job for Docker / Cloudflare deployments as described in the CI section above.
220
200
 
221
- # Forgejo / Codeberg
222
- mkdir -p .forgejo/workflows
223
- cp node_modules/@regardio/dev/templates/github/release.yml .forgejo/workflows/release.yml
224
- ```
201
+ ### 5. First publish of any new package must be done locally
225
202
 
226
- 5. **First publish of any new package must be done locally**:
203
+ ```bash
204
+ pnpm build && npm publish --access public
205
+ ```
227
206
 
228
- ```bash
229
- pnpm build && npm publish --access public
230
- ```
207
+ CI publishes subsequent versions; the very first one requires a local publish because the package does not yet exist on npm.
231
208
 
232
209
  ## Quality Gates
233
210
 
234
- Every ship command enforces the same gates no broken code reaches any environment:
211
+ Every ship command enforces the same gates before any commit or merge:
235
212
 
236
213
  ```bash
237
214
  pnpm build # Must succeed
@@ -239,11 +216,11 @@ pnpm typecheck # Must succeed
239
216
  pnpm test # Must succeed
240
217
  ```
241
218
 
242
- ## Private Packages and Non-Publishing Repos
219
+ ## Publishing vs Non-Publishing Repos
243
220
 
244
- Packages that should never be published to npm must set `"private": true` in `package.json`. `pnpm -r publish` skips them automatically.
221
+ Packages with `"private": true` are skipped by `pnpm -r publish` automatically CI only publishes public packages to npm.
245
222
 
246
- For non-publishing repos (e.g., channels that deploy directly to servers instead of npm), omit the `release:*` scripts from `package.json`. The ship tools will skip versioning entirely and only perform the git merges. CI can then handle deployment to servers based on the `production` branch.
223
+ 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.
247
224
 
248
225
  ## Related
249
226
 
@@ -65,7 +65,7 @@ export default defineConfig({ test: vitestReactConfig });
65
65
  ```json
66
66
  {
67
67
  "scripts": {
68
- "test": "exec-s test:*",
68
+ "test": "vitest run",
69
69
  "test:unit": "vitest run",
70
70
  "report": "vitest run --coverage"
71
71
  }
@@ -0,0 +1,118 @@
1
+ ---
2
+
3
+ title: "Writing"
4
+ description: "Voice, tone, and language Regardio content carries, in English and German."
5
+ publishedAt: 2026-04-17
6
+ order: 2
7
+ language: "en"
8
+ status: "published"
9
+ kind: "concept"
10
+ ---
11
+
12
+ The voice in which Regardio writes about itself and its tools.
13
+
14
+ ## What you are doing
15
+
16
+ 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.*
17
+
18
+ Two trains of thought carry everything the System does — and everything you write about it.
19
+
20
+ **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.
21
+
22
+ **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.
23
+
24
+ These two habits are the grammar underneath the System. Carry them quietly. You rarely name them. They are just the shape of the thinking.
25
+
26
+ ## How to meet the reader
27
+
28
+ 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.
29
+
30
+ 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.
31
+
32
+ ## Stance
33
+
34
+ Six movements carry every piece.
35
+
36
+ 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.
37
+ 2. **Observe, don't instruct.** Write like someone who has listened carefully and is sharing an observation, not like someone explaining a method.
38
+ 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.
39
+ 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.
40
+ 5. **Turned toward what could be, without promises.** Warm, attentive, spacious. Curious about people rather than diagnostic. No salvation talk, no coaching register.
41
+ 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.
42
+
43
+ ## Before and after
44
+
45
+ **Instead of:** *"Apply this framework to align your team."*
46
+ **Try:** *"What does the decision we made last week have to do with what's slowing us down now?"*
47
+
48
+ **Instead of:** *"The System helps you gain clarity."*
49
+ **Try:** *"A few angles worth looking at, whatever the pursuit."*
50
+
51
+ **Instead of:** *"Pursuits flourish with a clear core."*
52
+ **Try:** *"How will we know when we've arrived?"*
53
+
54
+ The System's questions are not headers. They are real questions, worth sitting with.
55
+
56
+ ## Language
57
+
58
+ Language that leaves room lets readers think. Language that pushes does the thinking for them. Given the choice, choose room.
59
+
60
+ **Favor:** notice, explore, find, might, could, pattern, rhythm, carry, hold — words that leave room.
61
+
62
+ **Avoid:** must, potential, resources, values, purpose, sustainability, growth, leverage, empower, ownership, good, bad. These either push or have been worn down to noise.
63
+
64
+ **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.
65
+
66
+ **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.
67
+
68
+ **The System is humane.** Equal, free cooperation is built in. Avoid connotations of hierarchy, ownership, dominance, control, or force. Reflect that without announcing it.
69
+
70
+ **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.
71
+
72
+ ## System terms
73
+
74
+ 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.
75
+
76
+ 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.
77
+
78
+ ## Roots, kept in the background
79
+
80
+ 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.
81
+
82
+ ## Format and craft
83
+
84
+ **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.
85
+
86
+ ## Language-specific caveats
87
+
88
+ ### German
89
+
90
+ - Address the reader with *du* unless the context clearly calls for *Sie* (formal contracts, legal notices). Keep it direct, without affectation.
91
+ - 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*.
92
+ - Quotation marks: German low-high („…") in body text.
93
+
94
+ ### English
95
+
96
+ - American English: *organize*, *color*, *toward*, *behavior*, *center*. Periods and commas inside quotation marks.
97
+ - No gendered forms. Name actions: *the person pursuing this*, *contributors*, *those involved*. Singular *they* is fine where a pronoun is unavoidable.
98
+ - Quotation marks: straight double quotes (") in Markdown source; typographic quotes ("…") in rendered prose.
99
+
100
+ ## Check before publishing
101
+
102
+ - Does it sound like a conversation the reader would want to be in?
103
+ - Does the text derive rather than declare?
104
+ - Are abstract thoughts grounded in concrete examples?
105
+ - Are System terms used consistently, in their precise meaning?
106
+ - Is it free of coaching register, pigeonholing, and tired buzzwords?
107
+ - Could the honest response be *"Yes, that's how it is"*?
108
+
109
+ *This guide is itself a living text. When in doubt: would you enjoy reading this?*
110
+
111
+ ## Related
112
+
113
+ - [Documentation](./documentation.md) — How Regardio shapes its documents
114
+ - [Principles](./principles.md) — Shared principles
115
+
116
+ ---
117
+
118
+ **License**: [CC-BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) © Regardio
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://www.schemastore.org/package.json",
3
3
  "name": "@regardio/dev",
4
- "version": "2.4.1",
4
+ "version": "2.6.0",
5
5
  "private": false,
6
6
  "description": "Regardio development presets: biome, typescript, commitlint, markdownlint, vitest, playwright, sqlfluff, husky, and GitLab-flow ship tooling",
7
7
  "keywords": [
@@ -74,7 +74,7 @@
74
74
  ],
75
75
  "devDependencies": {
76
76
  "@total-typescript/ts-reset": "0.6.1",
77
- "@types/node": "25.6.0",
77
+ "@types/node": "25.6.2",
78
78
  "@vitest/coverage-v8": "4.1.5",
79
79
  "tsdown": "0.22.0",
80
80
  "vitest": "4.1.5"
@@ -101,7 +101,7 @@
101
101
  "fix:biome": "biome check --write --unsafe .",
102
102
  "fix:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc --fix",
103
103
  "fix:pkg": "sort-package-json",
104
- "lint": "run-s lint:md lint:biome",
104
+ "lint": "run-p lint:*",
105
105
  "lint:biome": "biome check .",
106
106
  "lint:md": "markdownlint-cli2 --config ../../.markdownlint-cli2.jsonc",
107
107
  "lint:pkg": "sort-package-json --check",