@brnshkr/config 0.0.1-beta.2 → 0.0.1-beta.4

package/README.md

@@ -1,6 +1,10 @@
 <h1 id="top">
   <a href="#top">
-    <img src="https://raw.githubusercontent.com/brnshkr/brand/refs/heads/master/images/projects/config.png" alt="@brnshkr/config project logo" title="@brnshkr/config">
+    <img
+      src="https://raw.githubusercontent.com/brnshkr/brand/refs/heads/master/images/projects/config.png"
+      alt="@brnshkr/config project logo"
+      title="@brnshkr/config"
+    >
   </a>
 
   [![Semantic Versioning 2.0.0][semver-2.0.0-shield-url]][semver-2.0.0-url]
@@ -18,23 +22,25 @@ _[☄️ Bug Reports / Feature Requests »][issues-url]_
 <!-- omit in toc -->
 ## Table of Contents
 
-<!-- NOTICE: GitHub strips emojis in anchors, but multi-codepoint characters may leave invisible remnants, causing anchors to differ and require URL encoding. -->
+<!-- 
+  NOTICE:
+  GitHub strips emojis in anchors, but multi-codepoint characters may leave invisible remnants,
+  causing anchors to differ and require URL encoding.
+-->
 - [👋 About the Project](#-about-the-project)
+- [📚 Documentation](#-documentation)
 - [☕ JS](#-js)
   - [🧰 Prerequisites](#-prerequisites)
   - [🚀 Installation](#-installation)
-    - [✋ Manual](#-manual)
     - [🎨 Custom](#-custom)
   - [👀 Usage](#-usage)
-  - [💻 Development](#-development)
+  - [🧩 Custom ESLint Rules](#-custom-eslint-rules)
 - [🐘 PHP](#-php)
   - [🧰 Prerequisites](#-prerequisites-1)
   - [🚀 Installation](#-installation-1)
-    - [🤖 Automatic](#-automatic)
-    - [✋ Manual](#-manual-1)
     - [🎨 Custom](#-custom-1)
   - [👀 Usage](#-usage-1)
-  - [💻 Development](#-development-1)
+  - [🧩 Custom PHPStan Rules](#-custom-phpstan-rules)
 - [🔨 TODOs / Roadmap](#-todos--roadmap)
 - [❤️ Contributing](#️-contributing)
   - [💄 Commit Style](#-commit-style)
@@ -47,10 +53,22 @@ _[☄️ Bug Reports / Feature Requests »][issues-url]_
 
 ## 👋 About the Project
 
-**@brnshkr/config** is a centralized, opinionated collection of shared configuration files, tooling, and workflows for JavaScript and PHP projects. It helps standardizing linting, formatting, static analysis, and development workflows across repositories — reducing setup time, preventing config drift, and improving code quality and consistency.
+**@brnshkr/config** is a centralized, opinionated collection of shared configuration files,
+tooling, and workflows for JavaScript and PHP projects.
+It helps standardizing linting, formatting, static analysis, and development workflows across repositories
+— reducing setup time, preventing config drift, and improving code quality and consistency.
 
 > ❗ **Note** ❗  
-> While you're more than welcome to use this in your own projects, the configurations are tailored specifically for the [@brnshkr][@brnshkr-organization-url] ecosystem and may not be a perfect fit elsewhere.
+> While you're more than welcome to use this in your own projects, the configurations are tailored specifically
+> for the [@brnshkr][@brnshkr-organization-url] ecosystem and may not be a perfect fit elsewhere.
+
+<p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
+
+## 📚 Documentation
+
+This README covers installation and usage. The full reference — custom rules, config builders, the Composer plugin,
+the shared [`Makefile`](https://github.com/brnshkr/config/blob/master/docs/Makefile.md), and the development setup
+— lives in [`./docs`](https://github.com/brnshkr/config/blob/master/docs), organized by stack and tool.
 
 <p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
 
@@ -58,7 +76,7 @@ _[☄️ Bug Reports / Feature Requests »][issues-url]_
 
 ### 🧰 Prerequisites
 
-- Node.js >= v24 or Bun >= v1.3 (Older versions may work, but are untested)
+- Node.js >= v24.15 or Bun >= v1.4 (Older versions may work, but are untested)
 - Any JavaScript package manager (Bun, Yarn, PNPM, NPM)
 
 <p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
@@ -93,71 +111,75 @@ pnpm add -D -E @brnshkr/config
 npm i -D -E @brnshkr/config
 ```
 
-This repository currently only provides one way to integrate configuration files (An automatic setup is planned, See [🔨 TODOs / Roadmap](#-todos--roadmap)):
+Take a look at the `peerDependencies` in the [package.json](./package.json) file
+and install the ones you need for the modules you want to use.  
+Copy the starter `Makefile` once, and let it write the rest:
 
-- [**Manual setup**](#-manual) by copying the example configuration files yourself
+```sh
+cp -v ./node_modules/@brnshkr/config/conf/Makefile.dist ./Makefile \
+  && make startup
+```
+
+`make startup` installs each stack, writes every config and `.gitignore` the project is missing, and never
+touches a file that is already there.
 
 <p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
 
-#### ✋ Manual
+#### 🎨 Custom
 
-Take a look at the `peerDependencies` in the [package.json](./package.json) file and install the ones you need for the modules you want to use.  
-You can then copy the specific configs to your project:
+Take a look at the function signatures for exact details.
 
 <!-- omit in toc -->
-##### TypeScript
+##### ESLint
 
-```sh
-cp -v ./node_modules/@brnshkr/config/conf/tsconfig.json.example ./tsconfig.json
-```
+```js
+// ./conf/eslint.mjs
 
-<!-- omit in toc -->
-##### ESLint
+import { getConfig } from '@brnshkr/config/eslint';
 
-```sh
-cp -v ./node_modules/@brnshkr/config/conf/eslint.config.mjs.example ./conf/eslint.config.mjs
+export default getConfig(/* customize */);
 ```
 
 <!-- omit in toc -->
 ##### Stylelint
 
-```sh
-cp -v ./node_modules/@brnshkr/config/conf/stylelint.config.mjs.example ./conf/stylelint.config.mjs
-```
+```js
+// ./conf/stylelint.mjs
 
-<!-- omit in toc -->
-##### All
+import { getConfig } from '@brnshkr/config/stylelint';
 
-```sh
-cp -v ./node_modules/@brnshkr/config/conf/tsconfig.json.example ./tsconfig.json \
-  && cp -v ./node_modules/@brnshkr/config/conf/eslint.config.mjs.example ./conf/eslint.config.mjs \
-  && cp -v ./node_modules/@brnshkr/config/conf/stylelint.config.mjs.example ./conf/stylelint.config.mjs
+export default getConfig(/* customize */);
 ```
 
-<p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
+<!-- omit in toc -->
+##### markdownlint
 
-#### 🎨 Custom
+```js
+// ./conf/markdownlint.mjs
 
-Take a look at the function signatures for exact details.
+import { getConfig } from '@brnshkr/config/markdownlint';
+
+export default getConfig(/* customize */);
+```
 
 <!-- omit in toc -->
-##### ESLint
+##### commitlint
 
 ```js
-// ./eslint.config.mjs
+// ./conf/commitlint.mjs
 
-import { getConfig } from '@brnshkr/config/eslint';
+import { getConfig } from '@brnshkr/config/commitlint';
 
 export default getConfig(/* customize */);
 ```
 
 <!-- omit in toc -->
-##### Stylelint
+##### Vitest
 
 ```js
-// ./stylelint.config.mjs
+// ./conf/vitest.mjs
 
-import { getConfig } from '@brnshkr/config/stylelint';
+import { getConfig } from '@brnshkr/config/vitest';
 
 export default getConfig(/* customize */);
 ```
@@ -181,7 +203,7 @@ A few possible ways are listed below:
 Example call, adjust as needed
 
 ```sh
-bun eslint --config ./conf/eslint.config.mjs --cache --cache-location ./.cache/eslint.cache.json
+bun eslint --config ./conf/eslint.mjs --cache --cache-location ./.cache/eslint.cache.json --max-warnings 0
 ```
 
 <!-- omit in toc -->
@@ -190,70 +212,95 @@ bun eslint --config ./conf/eslint.config.mjs --cache --cache-location ./.cache/e
 Example call, adjust as needed
 
 ```sh
-bun stylelint --config ./conf/stylelint.config.mjs --cache --cache-location ./.cache/stylelint.cache.json **/*.{css,ejs,html,less,postcss,scss,svelte,svg,vue}
+bun stylelint --config ./conf/stylelint.mjs --config-basedir ./ --cache --cache-location ./.cache/stylelint.cache.json --max-warnings 0 "**/*.{css,ejs,html,less,postcss,scss,svelte,svg,vue}"
 ```
 
 <!-- omit in toc -->
-##### Option 2 — Run Helper Scripts (Bun Only, @brnshkr Convention)
+###### markdownlint
 
-For these scripts to work you need to follow the convention of putting your configuration files into the [`./conf`](./conf) directory (Exactly how it is done in this project as well).
+Example call, adjust as needed
+
+```sh
+bun markdownlint-cli2 --config ./conf/markdownlint.mjs "**/*.md"
+```
 
 <!-- omit in toc -->
-###### ESLint (TypeScript Only)
+###### commitlint
 
-Expected configuration file: `./conf/eslint.config.ts`
+Example call, adjust as needed
 
 ```sh
-bun ./node_modules/@brnshkr/config/dist/scripts/eslint.mjs
+bun commitlint --config ./conf/commitlint.mjs --edit
 ```
 
 <!-- omit in toc -->
-###### Stylelint
+##### Option 2 — Run Make Targets (@brnshkr Convention)
+
+For these targets to work you need to follow the convention of putting your configuration files into the `./conf` directory
+(Exactly how it is done in this project as well; see [`./conf`](https://github.com/brnshkr/config/blob/master/conf)).
 
-Expected configuration file: `./conf/stylelint.config.mjs`
+Your own Makefile includes this one. Copy the starter rather than writing the include by hand: it guards the
+include, so a fresh clone can `make bootstrap` before anything is installed.
 
 ```sh
-bun ./node_modules/@brnshkr/config/dist/scripts/stylelint.mjs
+cp -v ./node_modules/@brnshkr/config/conf/Makefile.dist ./Makefile
 ```
 
+A target appears once the tool it runs is installed, so `make help` lists what your repository actually has,
+`make ci` runs all of it, and `make startup` writes any config you are still missing.
+The full reference is [`docs/Makefile.md`](https://github.com/brnshkr/config/blob/master/docs/Makefile.md).
+
 <!-- omit in toc -->
-#### IDE Setup
+###### ESLint (TypeScript Only)
 
-When using the recommended way of putting config files into the `./conf` directory it might be neccesary to instruct your IDE to read these files correctly.  
-If you need a VSCode setup and have the specific [`extensions`](https://github.com/brnshkr/config/blob/master/.vscode/extensions.json) installed you can take a look at the `Project specific` section in [`./.vscode/settings.json`](https://github.com/brnshkr/config/blob/master/.vscode/settings.json).
+Expected configuration file: `./conf/eslint.mjs`
 
-<p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
+```sh
+make eslint
+```
 
-### 💻 Development
+<!-- omit in toc -->
+###### Stylelint
+
+Expected configuration file: `./conf/stylelint.mjs`
+
+```sh
+make stylelint
+```
 
 <!-- omit in toc -->
-#### Setup
+###### markdownlint
 
-Install dependencies and setup git hooks:
+Expected configuration file: `./conf/markdownlint.mjs`
 
 ```sh
-bun install \
-  && bun install-hooks
+make markdownlint
 ```
 
 <!-- omit in toc -->
-#### Scripts
+###### commitlint
+
+Expected configuration file: `./conf/commitlint.mjs`
 
-We recommend using the scripts provided in the [package.json](./package.json) file as the primary way of running common tasks.  
-Have a look yourself for a full list of available targets.
+```sh
+make commitlint
+```
 
 <!-- omit in toc -->
-##### Common targets
+#### IDE Setup
+
+When using the recommended way of putting config files into the `./conf` directory
+it might be necessary to instruct your IDE to read these files correctly.  
+If you need a VS Code setup and have the specific [`extensions`](https://github.com/brnshkr/config/blob/master/.vscode/extensions.json)
+installed you can take a look at the `Project specific` section in [`./.vscode/settings.json`](https://github.com/brnshkr/config/blob/master/.vscode/settings.json).
+
+<p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
 
-Here are some frequently used examples:
+### 🧩 Custom ESLint Rules
 
-- `bun lint` — Run ESLint, Stylelint and Commitlint
-- `bun inspect:eslint` — Inspect ESLint configuration
-- `bun check` — Run TypeScript checks, linters and Vitest
-- `bun run test` — Run Vitest test suite
-- `bun test-update` — Run Vitest test suite and update snapshots
-- `bun run build` — Build the project and generate types
-- `bun watch` — Build the project in watch mode
+The default ESLint configuration ships a small `brnshkr` plugin that contributes a handful
+of project-specific rules, all enabled out of the box. Each rule is documented with examples
+in the [Custom ESLint Rules docs](https://github.com/brnshkr/config/blob/master/docs/js/eslint/rules/index.md).
 
 <p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
 
@@ -275,108 +322,25 @@ Here are some frequently used examples:
 #### Composer
 
 ```sh
-composer req --dev brnshkr/config
-```
-
-This repository provides two ways to integrate configuration files and setup tools into your project:
-
-- [**Automatic setup**](#-automatic) via the Composer plugin
-- [**Manual setup**](#-manual-1) by copying the example configuration files yourself
-
-#### 🤖 Automatic
-
-If you allow this package to run as a Composer plugin (Composer will prompt you on first install), several helper commands become available.  
-The most commonly used is the automatic setup command which installs packages for selected modules, copies example config files into your repository, and can optionally create a `Makefile` and/or a `.gitignore` file.
-
-Run the automatic setup with defaults:
-
-```sh
-composer brnshkr:config:setup
-```
-
-Run the automatic setup with all flags enabled:
-
-```sh
-composer brnshkr:config:setup -gofacme
-```
-
-Take a look at the [plugin commands](#plugin-commands) section to see a full list of available commands.
-
-<p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
-
-#### ✋ Manual
-
-Take a look at the `suggest`ed packages in the [composer.json](./composer.json) file and install the ones you need for the modules you want to use.  
-You can then copy the specific configs to your project:
-
-<!-- omit in toc -->
-##### PHP CS Fixer
-
-```sh
-cp -v ./vendor/brnshkr/config/conf/php-cs-fixer.php.example ./conf/php-cs-fixer.php \
-  && cp -v ./vendor/brnshkr/config/conf/php-cs-fixer.php.example ./conf/php-cs-fixer.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/php-cs-fixer.dist.php.example ./conf/php-cs-fixer.dist.php
-```
-
-<!-- omit in toc -->
-##### Rector
-
-```sh
-cp -v ./vendor/brnshkr/config/conf/rector.php.example ./conf/rector.php \
-  && cp -v ./vendor/brnshkr/config/conf/rector.php.example ./conf/rector.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/rector.dist.php.example ./conf/rector.dist.php
-```
-
-<!-- omit in toc -->
-##### PHPStan
-
-```sh
-cp -v ./vendor/brnshkr/config/conf/phpstan.php.example ./conf/phpstan.php \
-  && cp -v ./vendor/brnshkr/config/conf/phpstan.php.example ./conf/phpstan.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/phpstan.dist.php.example ./conf/phpstan.dist.php
-```
-
-<!-- omit in toc -->
-##### Twig CS Fixer
-
-```sh
-cp -v ./vendor/brnshkr/config/conf/twig-cs-fixer.php.example ./conf/twig-cs-fixer.php \
-  && cp -v ./vendor/brnshkr/config/conf/twig-cs-fixer.php.example ./conf/twig-cs-fixer.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/twig-cs-fixer.dist.php.example ./conf/twig-cs-fixer.dist.php
+composer r --dev brnshkr/config
 ```
 
-<!-- omit in toc -->
-##### Makefile
+Take a look at the `suggest`ed packages in the [composer.json](./composer.json) file and install the ones
+you need for the modules you want to use.  
+Copy the starter `Makefile` once, and let it write the rest:
 
 ```sh
-cp -v ./vendor/brnshkr/config/conf/Makefile.example ./Makefile
+cp -v ./vendor/brnshkr/config/conf/Makefile.dist ./Makefile \
+  && make startup
 ```
 
-<!-- omit in toc -->
-##### Gitignore
+`make startup` installs each stack, writes every config and `.gitignore` the project is missing, and never
+touches a file that is already there.
 
-```sh
-cp -v ./vendor/brnshkr/config/conf/.gitignore.example ./.gitignore
-```
-
-<!-- omit in toc -->
-##### All
+To have the packages installed for you, pick the modules interactively:
 
 ```sh
-cp -v ./vendor/brnshkr/config/conf/php-cs-fixer.php.example ./conf/php-cs-fixer.php \
-  && cp -v ./vendor/brnshkr/config/conf/php-cs-fixer.php.example ./conf/php-cs-fixer.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/php-cs-fixer.dist.php.example ./conf/php-cs-fixer.dist.php \
-  && cp -v ./vendor/brnshkr/config/conf/rector.php.example ./conf/rector.php \
-  && cp -v ./vendor/brnshkr/config/conf/rector.php.example ./conf/rector.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/rector.dist.php.example ./conf/rector.dist.php \
-  && cp -v ./vendor/brnshkr/config/conf/phpstan.php.example ./conf/phpstan.php \
-  && cp -v ./vendor/brnshkr/config/conf/phpstan.php.example ./conf/phpstan.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/phpstan.dist.php.example ./conf/phpstan.dist.php \
-  && cp -v ./vendor/brnshkr/config/conf/twig-cs-fixer.php.example ./conf/twig-cs-fixer.php \
-  && cp -v ./vendor/brnshkr/config/conf/twig-cs-fixer.php.example ./conf/twig-cs-fixer.php.example \
-  && cp -v ./vendor/brnshkr/config/conf/twig-cs-fixer.dist.php.example ./conf/twig-cs-fixer.dist.php \
-  && cp -v ./vendor/brnshkr/config/conf/Makefile.example ./Makefile \
-  && cp -v ./vendor/brnshkr/config/conf/.gitignore.example ./.gitignore
+composer brnshkr:config:setup
 ```
 
 <p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
@@ -389,9 +353,8 @@ Take a look at the function signatures for exact details.
 ##### PHP CS Fixer
 
 ```php
-// ./php-cs-fixer.dist.php
-
 <?php
+// ./conf/php-cs-fixer.dist.php
 
 declare(strict_types=1);
 
@@ -404,9 +367,8 @@ return PhpCsFixer::getConfig(/* customize */);
 ##### Rector
 
 ```php
-// ./rector.dist.php
-
 <?php
+// ./conf/rector.dist.php
 
 declare(strict_types=1);
 
@@ -419,9 +381,8 @@ return Rector::getConfig(/* customize */);
 ##### PHPStan
 
 ```php
-// ./phpstan.dist.php
-
 <?php
+// ./conf/phpstan.dist.php
 
 declare(strict_types=1);
 
@@ -434,9 +395,8 @@ return PhpStan::getConfig(/* customize */);
 ##### Twig CS Fixer
 
 ```php
-// ./twig-cs-fixer.dist.php
-
 <?php
+// ./conf/twig-cs-fixer.dist.php
 
 declare(strict_types=1);
 
@@ -495,16 +455,22 @@ php ./vendor/bin/twig-cs-fixer fix --config ./conf/twig-cs-fixer.php -v
 ```
 
 <!-- omit in toc -->
-##### Option 2 — Run Helper Scripts (Make Only, @brnshkr Convention)
+##### Option 2 — Run Make Targets (@brnshkr Convention)
 
-For these scripts to work you need to follow the convention of putting your configuration files into the [`./conf`](./conf) directory (Exactly how it is done in this project as well).
+For these targets to work you need to follow the convention of putting your configuration files into the `./conf` directory
+(Exactly how it is done in this project as well; see [`./conf`](https://github.com/brnshkr/config/blob/master/conf)).
 
-Do not forget to setup your Makefile with this projects Makefile as a base:
+Your own Makefile includes this one. Copy the shipped starter rather than writing the include by hand:
+it guards the include, so a fresh clone can `make bootstrap` before anything is installed.
 
-```Makefile
-include ./vendor/brnshkr/config/conf/Makefile
+```sh
+cp -v ./vendor/brnshkr/config/conf/Makefile.dist ./Makefile
 ```
 
+A target appears once the tool it runs is installed, so `make help` lists what your repository actually has,
+`make ci` runs all of it, and `make startup` writes any config you are still missing.
+The full reference is [`docs/Makefile.md`](https://github.com/brnshkr/config/blob/master/docs/Makefile.md).
+
 <!-- omit in toc -->
 ###### PHP CS Fixer
 
@@ -544,8 +510,10 @@ make twig-cs-fixer
 <!-- omit in toc -->
 #### IDE Setup
 
-When using the recommended way of putting config files into the `./conf` directory it might be neccesary to instruct your IDE to read these files correctly.  
-If you need a VSCode setup and have the specific [`extensions`](https://github.com/brnshkr/config/blob/master/.vscode/extensions.json) installed you can take a look at the `Project specific` section in [`./.vscode/settings.json`](https://github.com/brnshkr/config/blob/master/.vscode/settings.json).
+When using the recommended way of putting config files into the `./conf` directory
+it might be necessary to instruct your IDE to read these files correctly.  
+If you need a VS Code setup and have the specific [`extensions`](https://github.com/brnshkr/config/blob/master/.vscode/extensions.json)
+installed you can take a look at the `Project specific` section in [`./.vscode/settings.json`](https://github.com/brnshkr/config/blob/master/.vscode/settings.json).
 
 <!-- omit in toc -->
 #### Plugin Commands
@@ -556,55 +524,24 @@ For full usage run `composer help <command>`, `composer <command> --help` or `co
 | Command | Alias | Description |
 | --- | --- | --- |
 | `brnshkr:config` | `b:c` | Displays the plugin overview and a list of available commands. Useful to quickly discover what the plugin exposes. |
-| `brnshkr:config:setup [<modules>...]` | `b:c:s` | Interactive setup helper: installs suggested packages for modules, copies example config files, and can create a `Makefile` and/or a `.gitignore` file. |
 | `brnshkr:config:update-php-extensions` | `b:c:upe` | Scans installed packages and updates `composer.json` with required `ext-*` platform packages. |
 | `brnshkr:config:extract-phar <package>` | `b:c:ep` | Extracts a `.phar` file from a given vendor package. |
 
 <p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
 
-### 💻 Development
+### 🧩 Custom PHPStan Rules
 
-<!-- omit in toc -->
-#### Setup
-
-Install dependencies and setup project tooling with the following commands and adjust as needed:
-
-```sh
-composer install \
-  && cp -v ./conf/php-cs-fixer.php.example ./conf/php-cs-fixer.php \
-  && cp -v ./conf/rector.php.example ./conf/rector.php \
-  && cp -v ./conf/phpstan.php.example ./conf/phpstan.php \
-  && cp -v ./conf/twig-cs-fixer.php.example ./conf/twig-cs-fixer.php
-```
-
-<!-- omit in toc -->
-#### Make
-
-We recommend using [GNU Make][make-url] as the primary task runner.  
-See [the Makefile](./conf/Makefile) for a full list of available targets.  
-You can also run `make help` or simply `make` to view all targets with brief descriptions.
-
-If you need local overrides, create a `./.local/Makefile` — the main Makefile automatically includes it if present.
+Beyond the upstream rule set, the default configuration ships a number of custom PHPStan rules in two flavors.
+**Standalone rules** are general-purpose checks enabled out of the box,
+while **architecture presets** are opinionated bundles of class-placement and isolation rules tailored to a
+specific framework or architecture style — opt-in and configured through `setArchitecture()`.
+Both are documented with examples in the [Custom PHPStan Rules docs](https://github.com/brnshkr/config/blob/master/docs/php/phpstan/rules/index.md).
 
-<!-- omit in toc -->
-##### Common targets
-
-Here are some frequently used examples (see `make help` for the complete list):
-
-- `make help` — Show available targets and usage
-- `make rector` — Run Rector to apply automated PHP refactorings
-- `make php-cs-fixer` — Run PHP-CS-Fixer to format and fix coding-style issues
-- `make phpstan` — Run PHPStan static analysis
-- `make test` — Run PHPUnit test suite
-- `make test-update` — Run PHPUnit test suite and update snapshots
-- `make check` — Run Rector, PHP-CS-Fixer, Twig-CS-Fixer, PHPStan and PHPUnit
+<p align="right"><a href="#top" title="Back to top">&nbsp;&nbsp;&nbsp;⬆&nbsp;&nbsp;&nbsp;</a></p>
 
 ## 🔨 TODOs / Roadmap
 
-- Add setup command for JS package (like `composer brnshkr:config:setup`)
-- Expand [`⚙️ Worflows`](#️-workflows) section in readme
-- Write sections about custom PHPStan and ESLint rules
-- Add all around support for enforcing TypeScript aliases with ESLint
+- Expand [`⚙️ Workflows`](#️-workflows) section in readme
 - Add Vue support
 - Add React support
 - Add Tailwind support via <https://github.com/schoero/eslint-plugin-better-tailwindcss>
@@ -616,9 +553,11 @@ Any help is always greatly appreciated 🙂
 
 ## ❤️ Contributing
 
-Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.
+Contributions are what make the open source community such an amazing place to learn, inspire, and create.
+Any contributions you make are **greatly appreciated**.
 
-If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".
+If you have a suggestion that would make this better, please fork the repo and create a pull request.
+You can also simply open an issue with the tag "enhancement".
 Don't forget to give the project a star! Thanks again!
 
 1. Fork the project
@@ -627,13 +566,17 @@ Don't forget to give the project a star! Thanks again!
 4. Push to the branch => `git push origin feature/my-new-feature`
 5. Open a pull request
 
+New to the codebase?
+The [Development docs](https://github.com/brnshkr/config/blob/master/docs/development.md)
+cover environment setup and the day-to-day commands for both stacks.
+
 ### 💄 Commit Style
 
 This project mostly follows the [Conventional Commits](https://www.conventionalcommits.org) specification.  
 There are only a few differences. The main one is that the scope is required:  
 So **instead of** this commit message signature: `<type>[optional scope]: <description>`  
 You **should use** this one: `<type><scope>: <description>`  
-Further details can be found in the [Commitlint configuration](https://github.com/brnshkr/config/blob/master/conf/commitlint.config.mjs).
+Further details can be found in the [commitlint configuration](https://github.com/brnshkr/config/blob/master/conf/commitlint.mjs).
 
 ### ⚙️ Workflows
 
@@ -644,8 +587,15 @@ See [./.github/workflows](https://github.com/brnshkr/config/blob/master/.github/
 ## 🔖 Versioning
 
 This project follows [Semantic Versioning 2.0.0][semver-2.0.0-url].  
-The NPM and Composer packages are versioned in sync, so a version change does not necessarily indicate a change in a specific package.  
-Also please note the following additional information:
+The NPM and Composer packages are versioned in sync,
+so a version change does not necessarily indicate a change in a specific package.  
+
+> ❗ **Note** ❗  
+> Since changes to rules and dependencies are not considered breaking,
+> even a patch release may introduce new errors in code that hasn't changed and break your CI without notice.
+> We therefore strongly recommend pinning to an exact version
+> (`-E` for the JS package managers, `composer r --dev brnshkr/config:X.Y.Z` for Composer)
+> so updates stay opt-in and can be applied on your own schedule.
 
 <!-- omit in toc -->
 ### Changes Considered as Breaking Changes
@@ -672,8 +622,9 @@ Distributed under the MIT License. See [LICENSE](./LICENSE) for more information
 
 - [TypeScript](https://www.typescriptlang.org)
 - [ESLint](https://github.com/eslint/eslint)
+- [markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)
 - [Stylelint](https://github.com/stylelint/stylelint)
-- [Commitlint](https://github.com/conventional-changelog/commitlint)
+- [commitlint](https://github.com/conventional-changelog/commitlint)
 - [@antfu/eslint-config](https://github.com/antfu/eslint-config)
 - [PHP](https://www.php.net)
 - [PHPStan](https://github.com/phpstan/phpstan)
@@ -681,7 +632,7 @@ Distributed under the MIT License. See [LICENSE](./LICENSE) for more information
 - [PHP-CS-Fixer](https://github.com/PHP-CS-Fixer/PHP-CS-Fixer)
 - [Twig-CS-Fixer](https://github.com/VincentLanglet/Twig-CS-Fixer)
 - [GNU Make](https://www.gnu.org/software/make)
-- [Best-README-Template](https://github.com/othneildrew/Best-README-Template) by [othneildrew](https://github.com/othneildrew)
+- [Best-README-Template](https://github.com/othneildrew/Best-README-Template)
 - [Choose an Open Source License](https://choosealicense.com)
 - [Shields.io](https://shields.io)
 - <a href="https://github.com/brnshkr">
@@ -698,8 +649,6 @@ Distributed under the MIT License. See [LICENSE](./LICENSE) for more information
 
 [@brnshkr-organization-url]: https://github.com/brnshkr
 
-[make-url]: https://www.gnu.org/software/make
-
 [semver-2.0.0-url]: https://semver.org/#semantic-versioning-200
 [semver-2.0.0-shield-url]: https://img.shields.io/badge/semver-2.0.0-blue?label=🔖%20semver&style=flat-square&labelColor=%237f399d&color=%23a5097e