@activatus/code-standards 0.0.0-stage → 3.0.0

package/docs/Guides/setup.md

@@ -0,0 +1,158 @@
+---
+sidebar_position: 2
+sidebar_label: "Setup"
+---
+
+# Setting Up a Project
+
+> For the AI agent. A person has told you to follow the Activatus Code Standards in their project. This is everything you do, in order.
+
+The person creates the app themselves — with `create-next-app`, Expo or anything else — and tells you to follow the standards. **Do not ask which framework the project uses.** Look at the project: its `package.json` and files tell you. The person only answers the questions below and checks your work. They never run a command.
+
+**These standards are the base, for code only.** A project builds on top of them: it can add its own folders and conventions, and it makes its own project-management decisions (tickets, statuses, releases, who commits). Those go in the project's own docs, not here.
+
+## 1. Install the standards
+
+```bash
+pnpm add -D @activatus/code-standards
+```
+
+**If pnpm refuses because the version is too new**, that is pnpm's `minimumReleaseAge` setting: by default it will not install a version published less than a day ago. The standards come from us, so add the package to `minimumReleaseAgeExclude` in `pnpm-workspace.yaml`:
+
+```yaml title="pnpm-workspace.yaml"
+minimumReleaseAgeExclude:
+  - "@activatus/code-standards"
+```
+
+The standards are now in `node_modules/@activatus/code-standards/`:
+
+| Folder                    | What it holds                                                                              |
+| ------------------------- | ------------------------------------------------------------------------------------------ |
+| `docs/`                   | Every standard, as Markdown. The same pages as https://activatus-code-standards.vercel.app |
+| `docs/version-history.md` | What changed in each version, and what a project has to do about it                        |
+| `static/templates/`       | The config files to copy: `AGENTS.md`, ESLint, Prettier, Stylelint and the rest            |
+
+**Read the standards from `node_modules`, not the website.** The installed package is the exact version the project uses. The package version is the standards version: `2.0.0` is version 2.
+
+## 2. Work out where the project is
+
+Open the project's `AGENTS.md` and look for `**Code standards version:**`.
+
+| What you find                                | What it means                        | Go to                                                       |
+| -------------------------------------------- | ------------------------------------ | ----------------------------------------------------------- |
+| No `AGENTS.md`, or no code standards version | The standards have never been set up | [3. Agree the standards](#3-agree-the-standards)            |
+| A version lower than the installed package   | The project follows an older version | [Updating to a newer version](#updating-to-a-newer-version) |
+| The same version as the installed package    | Already up to date                   | Nothing to do. Tell the person                              |
+
+## 3. Agree the standards
+
+**Print this list to the person exactly as it is written**, with the same numbers, so they can answer with numbers:
+
+```text
+These are the Activatus Code Standards. Want anything different?
+Tell me the numbers to skip or change, or say "all good".
+
+ 1. Human-readable names: every name is whole words, using the Dictionary
+ 2. Readable code: files under 300 lines, one job per function, one parameter, return early, no magic numbers
+ 3. Arrow functions and const only, named exports, no classes
+ 4. Every function and component has a test file
+ 5. Strict TypeScript: no any, no !, no unexplained as; type names end in Props or Type
+ 6. ESLint, with the standard config
+ 7. Prettier, with the Tailwind class-sorting plugin
+ 8. Stylelint, for any hand-written CSS
+ 9. EditorConfig
+10. Node version set by .nvmrc and direnv
+11. Styling: Tailwind, flexbox first, colours only from the global palette
+12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
+13. Components live where they are used: components/ui/, components/shared/, or beside their page
+14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
+15. Design System Components: every project builds the standard components with the same props
+16. Imports: no circular imports, import from folders not files
+17. API routes: one folder per route, kebab-case
+18. Docs: every file in docs/ is a Decision Doc, shown at /docs by the docs site
+19. Lint before every commit: a Husky hook runs pnpm lint
+20. AGENTS.md and the eight agent skills
+21. The Ontology: the shared words for code
+```
+
+Then wait for the answer.
+
+| The person says                         | Do                            |
+| --------------------------------------- | ----------------------------- |
+| "All good"                              | Apply every standard          |
+| "Skip 7"                                | Apply every standard except 7 |
+| "Change 7: we use Biome for formatting" | Apply 7 as they describe it   |
+| Something unclear                       | Ask. Do not guess             |
+
+**Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write its number, its name, what is different, and the reason the person gave. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
+
+The list has nothing about branches, commit messages or whether agents may commit. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/Standards/agent-specs#project-workflow).
+
+## 4. Apply the standards
+
+Do only the standards the person agreed to. Copy every file from `node_modules/@activatus/code-standards/static/templates/` — never write a config file from scratch.
+
+**Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment, for example `/** @type {import("next").NextConfig} */`. A tool that cannot read `.mjs` keeps its own format.
+
+**An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/Guides/migrating), one stage per pull request, after the config files below are in place.
+
+| Standard                 | What to set up                                                                                                                                                                                                                                                                                                       |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 6. ESLint                | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`. Install the packages listed on the [ESLint page](/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`                                                 |
+| 7. Prettier              | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the scripts `"format": "prettier --write ."` and `"format:check": "prettier --check ."`                                                                                                                         |
+| 8. Stylelint             | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/Standards/stylelint)                                                                                                                                                           |
+| 9. EditorConfig          | Copy `static/templates/.editorconfig`                                                                                                                                                                                                                                                                                |
+| 10. Node version         | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/Standards/direnv)                                                                                                                                                                                                                  |
+| 11. Styling              | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette                                                                                                                                                                                  |
+| 18. Docs                 | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/Standards/documentation#-setting-it-up)                                                                                                |
+| 19. Lint before commit   | Copy `static/templates/husky/pre-commit` to `.husky/pre-commit`, once `pnpm lint` passes. See [Lint before every commit](/Standards/lint-errors#lint-before-every-commit)                                                                                                                                            |
+| 20. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/` |
+
+The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
+
+**Finish by:**
+
+1. Setting `**Code standards version:**` in `AGENTS.md` to the installed package's major version. See [Finishing a change later](#finishing-a-change-later) if anything is left to do.
+2. Running `pnpm lint`, `pnpm format:check` and the tests.
+3. Telling the person what you set up, which standards they skipped, and anything only they can do, such as filling in a secret in `.env.local`.
+
+---
+
+## Updating to a newer version
+
+The project already follows the standards, and a newer version is out.
+
+1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
+2. **Update the package:**
+
+   ```bash
+   pnpm update @activatus/code-standards --latest
+   ```
+
+   Its major version is now the newest version.
+
+3. **Read `node_modules/@activatus/code-standards/docs/version-history.md`**, but only the versions newer than the project's. Do not re-read the rest of the standards.
+4. **Skip any change to a standard the project opted out of.** The opt-outs are listed in `docs/development/coding-standards.md`.
+5. **Do every other change** as its "What to do" says, and run its "How to check" search. One pull request per kind of change.
+6. **Set `**Code standards version:**`** in `AGENTS.md` to the new version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
+
+See the [Version History](/version-history) for the full update rules.
+
+---
+
+## Finishing a change later
+
+Sometimes a change is too big for the update, such as switching on the standard ESLint config in a project that never had it. It can be done later in its own Pull Request, but **the version number must stay honest**.
+
+1. Set the project's version to the new version anyway.
+2. In `docs/development/coding-standards.md`, under **Unfinished changes**, list each change that is not done yet: its version and number, what is left, and where it is being done (a ticket or a Pull Request).
+
+   ```md
+   ## Unfinished changes
+
+   - Version 2, change 4: the standard ESLint config is not switched on yet. Being done in ACT-120.
+   ```
+
+3. When it is finished, remove it from the list.
+
+An agent updating to a later version reads this list first, and finishes or skips those changes before starting the new ones.

package/docs/Standards/_category_.json

@@ -0,0 +1,4 @@
+{
+	"label": "Standards",
+	"position": 6
+}

package/docs/Standards/agent-skills.md

@@ -0,0 +1,125 @@
+---
+sidebar_position: 8
+---
+
+# Agent Skills
+
+A skill is a reusable instruction file an agent runs when you type `/lint`, `/format`, `/codeReview`. Every Activatus repository provides the same [standard set](/Standards/agent-specs#standard-skills), copied from the [Templates page](/templates#skills). This page is the standard they are written to.
+
+Skills are shared, versioned, and executed with real tool access. A vague one wastes a run; a wrong one edits files it was never meant to touch. They get the same review as any other code.
+
+## Where skills live
+
+One canonical copy, one mirror:
+
+| Path                    | Role                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------ |
+| `.agents/skills/*.md`   | **Canonical.** Portable location any compatible agent reads. The only copy you edit. |
+| `.claude/commands/*.md` | Claude Code mirror, exposed as `/name`.                                              |
+
+Keep the mirror identical to the canonical copy — edit the skill in `.agents/skills/`, then copy it across.
+
+:::note[Why two locations rather than one format]
+
+`.claude/commands/` is Claude Code's older flat-file layout; its newer equivalent is a directory per skill (`.claude/skills/<name>/SKILL.md`). Activatus stays on flat files because the same file has to serve `.agents/skills/` for non-Claude agents, and a flat `.md` is the only shape both read. Revisit this if bundled resources (`scripts/`, `references/`) are ever needed — that is what the directory format buys.
+
+:::
+
+## Frontmatter
+
+Every skill starts with YAML frontmatter. Without it the agent falls back to guessing from the first line of the body.
+
+```markdown
+---
+name: lint
+description: Run all linters in check-only mode and report issues
+argument-hint: "[path]"
+allowed-tools: Read, Glob, Grep, Bash(pnpm lint:*), Bash(eslint:*)
+---
+
+Run all configured linters and report issues without modifying any files.
+```
+
+| Field                      | Required              | Purpose                                                            |
+| -------------------------- | --------------------- | ------------------------------------------------------------------ |
+| `name`                     | Yes                   | The invocation name, in camelCase. Must match the filename.        |
+| `description`              | Yes                   | One line, **under 60 characters**. How an agent decides to use it. |
+| `argument-hint`            | If it takes arguments | Shown during autocomplete.                                         |
+| `allowed-tools`            | Strongly encouraged   | The tools the skill may use. See below.                            |
+| `model`                    | No                    | Pin only for genuinely mechanical skills.                          |
+| `disable-model-invocation` | No                    | Set when a skill must only ever be run by a human.                 |
+
+Quote any `argument-hint` that starts with `[`, or YAML parses it as a list:
+
+```yaml
+argument-hint: "[path]" # string
+argument-hint: [path] # a one-element array — wrong
+```
+
+## `allowed-tools` is the contract
+
+Prose like "this skill is read-only" is a request. `allowed-tools` is the enforcement. Whatever a skill's body promises not to do, the allowlist should make impossible:
+
+| The skill says             | So the allowlist omits |
+| -------------------------- | ---------------------- |
+| "Do NOT make file changes" | `Edit`, `Write`        |
+| "Do NOT auto-fix"          | `Edit`, `Write`        |
+| "Do NOT stage or commit"   | every `Bash(git …)`    |
+| "Do NOT push"              | `Bash(git push:*)`     |
+
+Three rules follow from this:
+
+1. **Every command the body tells the agent to run must be allowlisted.** A body that says `eslint $ARGUMENTS` under an allowlist of only `Bash(pnpm exec eslint:*)` blocks itself halfway through. List each form the body actually uses.
+2. **Grant the narrowest set that still works.** `Bash(pnpm lint:*), Bash(eslint:*)` over a bare `Bash`.
+3. **Never grant `git commit` or `git push`.** A skill does one job and leaves its changes for whoever ran it. Committing is the [project's workflow](/Standards/agent-specs#project-workflow), not a skill's.
+
+Be honest about the limit: patterns gate the command, not its flags. `Bash(eslint:*)` still permits `eslint --fix`. The allowlist reliably prevents a skill from reaching for a whole _category_ of tool; keep the prose instruction as well for anything finer.
+
+## Write for the agent, not the user
+
+A skill body is the agent's instructions. Write directives, not a description of what the user is about to experience.
+
+```markdown
+<!-- Good — tells the agent what to do -->
+
+Run each applicable linter in check-only mode and report the findings grouped by file.
+
+<!-- Bad — tells the user what will happen -->
+
+This command will check your code and give you a nice report.
+```
+
+## Structure
+
+- **Number the steps.** Agents follow ordered lists more reliably than prose paragraphs.
+
+- **Indent sub-steps by three spaces**, not two. An ordered item's content offset is three characters (`1. `), and at two spaces CommonMark — and Prettier — will lift the bullets out into a separate list and break the numbering.
+
+  ```markdown
+  2. Run each applicable linter:
+     - ESLint: `eslint $ARGUMENTS`
+     - Stylelint: `stylelint "**/*.{css,scss}"`
+  3. Collect the warnings.
+  ```
+
+- **State the contract explicitly**, in the body as well as the frontmatter — `Do NOT stage or commit`, `Do NOT push`.
+
+- **Say what to do when a prerequisite is missing.** Naming the fallback is what stops an agent from quietly substituting a worse one.
+
+## Prefer the project's own scripts
+
+Respect the project's own scripts. `pnpm lint` picks up workspace configuration that a bare `eslint .` at the root will miss, and in a monorepo the bare form is simply wrong.
+
+## Checklist
+
+Before merging a skill:
+
+- [ ] `name` matches the filename
+- [ ] `description` is one line, under 60 characters
+- [ ] `argument-hint` present if it takes arguments, and quoted if it starts with `[`
+- [ ] `allowed-tools` omits everything the body promises not to do
+- [ ] `allowed-tools` includes every command the body does invoke
+- [ ] Body is written as instructions to the agent
+- [ ] Sub-steps indented three spaces
+- [ ] Prettier leaves the file unchanged
+- [ ] `.claude/commands/` mirror matches `.agents/skills/`

package/docs/Standards/agent-specs.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 7
+sidebar_label: "AGENTS.md"
+---
+
+# AGENTS.md Specifications
+
+Every Activatus repository must have an `AGENTS.md` in its root. This file gives AI coding agents (Claude Code, Copilot, Cursor, etc.) the context they need to work effectively without repeated explanation.
+
+## Project workflow
+
+**How a project runs its work is not part of these standards.** Branch names, commit messages, Pull Requests, merging, releases, and whether AI agents may commit, push or make branches are all the project's own decisions. Every project makes them differently.
+
+Each project writes them up in its own docs, usually in `docs/development/`, and its `AGENTS.md` has a **Project workflow** section that points to them and states the rules an agent must follow. The most important one goes first: whether an agent may commit.
+
+## Template
+
+Start from the [AGENTS.md template](/templates#agents) and replace every `[placeholder]`.
+
+## Required sections
+
+Every `AGENTS.md` must include these sections. Monorepos (`pnpm-workspace.yaml`, Turborepo, Nx, etc.) also require a **Workspace packages** table listing each package, its path and a one-line description.
+
+| Section                    | Purpose                                                                                                                                      |
+| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Project overview           | One paragraph: what it does, who uses it, why it exists                                                                                      |
+| Repository layout          | Directory tree at depth 2                                                                                                                    |
+| Tech stack                 | Language, runtime, framework, database, infra (with versions)                                                                                |
+| Essential commands         | Install, dev, build, test, lint, type-check                                                                                                  |
+| Project workflow           | The project's own rules for branches, commits, Pull Requests and merging, and whether agents may commit. Points to where they are written up |
+| Environment variables      | All required and optional env vars with descriptions                                                                                         |
+| Ontology                   | Link to the [ontology](/ontology), and the instruction to read it and use its terms                                                          |
+| Documentation              | Where the project's docs are, and the instruction to read them before starting work                                                          |
+| Code standards             | Link to these standards and the rules agents must follow in every change                                                                     |
+| Available skills           | Table of the agent skills the project provides                                                                                               |
+| Out of scope for AI agents | Explicit list of what agents must not do in this project                                                                                     |
+
+## Standard skills
+
+Every project provides these eight skills. **The files are ready to copy from the [Templates page](/templates#skills)** — copy them into `.agents/skills/`, and again into `.claude/commands/` for Claude Code. They are written to the [agent skills standard](/Standards/agent-skills).
+
+| Skill          | Invocation                             | What it does                                                                                                   |
+| -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| Lint           | `/lint [path]`                         | Runs ESLint (and Stylelint if configured) in check-only mode; reports all issues grouped by file               |
+| Lint & fix     | `/lintFix [path]`                      | Runs ESLint and Stylelint in fix mode, then Prettier; reports what changed and what is left                    |
+| Format         | `/format [path]`                       | Runs Prettier in write mode; reports reformatted files                                                         |
+| Code review    | `/codeReview [branch, commit or path]` | Reviews changes for correctness, security, types, tests and standards compliance. Report only                  |
+| Update layout  | `/updateLayout`                        | Regenerates the "Repository layout" section of `AGENTS.md` (and "Workspace packages" in monorepos)             |
+| Security audit | `/securityAudit [path]`                | Audits dependencies and code for secrets, missing access control, unvalidated input and injection. Report only |
+| TypeScript     | `/typescript [path]`                   | Tightens loose types and removes `any`, `!` and unexplained `as`                                               |
+| Test           | `/test [path]`                         | Runs the test suite; reports failures grouped by cause, tests that never ran, and files missing a test         |
+
+Skill files are named in camelCase (`lintFix.md`), so the invocation is camelCase too (`/lintFix`). They are not documentation pages and have no URL, so the kebab-case rule for docs does not apply.
+
+No skill commits, pushes or makes branches. A skill does one job and leaves its changes for the agent or person who ran it. Whether those changes are then committed is the [project's workflow](#project-workflow).
+
+### Skill locations
+
+Skills are stored in two locations so they work with different tooling:
+
+| Path                | Used by                                   |
+| ------------------- | ----------------------------------------- |
+| `.agents/skills/`   | General agent discovery convention        |
+| `.claude/commands/` | Claude Code slash command system (mirror) |
+
+## Writing guidelines
+
+| Do                                                     | Don't                                        |
+| ------------------------------------------------------ | -------------------------------------------- |
+| Use concrete commands (`pnpm test`)                    | Use vague instructions ("run the tests")     |
+| State constraints explicitly ("do not push to `main`") | Assume the agent knows your branching policy |
+| Include version numbers in the tech stack              | Leave versions ambiguous                     |
+| Keep it under ~300 lines                               | Write a novel — agents have context limits   |
+| Run `/updateLayout` after structural changes           | Let the directory tree go stale              |

package/docs/Standards/direnv.mdx

@@ -0,0 +1,249 @@
+---
+sidebar_position: 4
+---
+
+# direnv + nvm
+
+Automatically switch to the project's Node.js version when you `cd` into the repository. No manual `nvm use` required.
+
+## How it works
+
+Two files work together:
+
+| File     | Purpose                                                                  |
+| -------- | ------------------------------------------------------------------------ |
+| `.nvmrc` | Declares the required Node.js major version (e.g. `20`)                  |
+| `.envrc` | Loaded by direnv on `cd`; sources nvm and activates the declared version |
+
+When you enter the project directory direnv runs `.envrc`, which installs the declared Node version (if missing) and activates it for your shell session. Leaving the directory restores the previous environment automatically.
+
+## Installation
+
+### macOS
+
+**Homebrew** (recommended):
+
+```bash
+brew install direnv nvm
+```
+
+Homebrew installs nvm to a prefix path rather than `$HOME/.nvm`. The `.envrc` handles this automatically by falling back to `$(brew --prefix nvm)/nvm.sh` when `$NVM_DIR/nvm.sh` is not found.
+
+Add to the **end** of `~/.zshrc` (or `~/.bashrc` for bash):
+
+```bash
+# nvm
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+
+# direnv
+eval "$(direnv hook zsh)"   # replace zsh with bash if needed
+```
+
+**Manual nvm install** (alternative):
+
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
+
+# Install direnv
+brew install direnv
+```
+
+The install script appends the nvm bootstrap to your shell profile automatically.
+
+Then add the direnv hook to the **end** of `~/.zshrc`:
+
+```bash
+eval "$(direnv hook zsh)"
+```
+
+Restart your shell (or `source ~/.zshrc`) after editing the profile.
+
+---
+
+### Linux
+
+```bash
+# Install nvm
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
+```
+
+The script appends the following to your `~/.bashrc` (or `~/.zshrc`):
+
+```bash
+export NVM_DIR="$HOME/.nvm"
+[ -s "$NVM_DIR/nvm.sh" ] && . "$NVM_DIR/nvm.sh"
+```
+
+Install direnv using your package manager:
+
+```bash
+# Debian / Ubuntu
+sudo apt install direnv
+
+# Arch
+sudo pacman -S direnv
+
+# Fedora
+sudo dnf install direnv
+
+# Or via the official install script:
+curl -sfL https://direnv.net/install.sh | bash
+```
+
+Add the direnv hook to the **end** of `~/.bashrc` (or `~/.zshrc`):
+
+```bash
+eval "$(direnv hook bash)"   # replace bash with zsh if needed
+```
+
+Restart your shell after editing the profile.
+
+---
+
+### Windows
+
+direnv and nvm are Unix tools. On Windows the recommended path is **WSL 2**. A Git Bash alternative is available for teams that cannot use WSL.
+
+#### Option A — WSL 2 (recommended)
+
+WSL 2 provides a full Linux environment. Follow the [Linux instructions](#linux) inside your WSL shell. Your editor (VS Code, JetBrains) should be configured to open projects inside WSL for the environment to be active.
+
+Install WSL 2 if you haven't already:
+
+```powershell
+# Run in PowerShell (Administrator)
+wsl --install
+```
+
+Then open a WSL terminal and follow the [Linux setup](#linux) above.
+
+#### Option B — Git Bash + nvm-windows
+
+If WSL is not available, direnv and [nvm-windows](https://github.com/coreybutler/nvm-windows) can be used together in Git Bash.
+
+**1. Install nvm-windows**
+
+Download and run the installer from the [nvm-windows releases page](https://github.com/coreybutler/nvm-windows/releases). This installs `nvm.exe` and adds it to `PATH`.
+
+nvm-windows exposes `nvm` as an executable in Git Bash — no `nvm.sh` sourcing is needed. The `.envrc` detects this automatically.
+
+**2. Install direnv**
+
+Download the latest Windows binary from the [direnv releases page](https://github.com/direnv/direnv/releases) (`direnv.windows-amd64.exe`), rename it to `direnv.exe`, and place it somewhere on your `PATH` (e.g. `C:\Program Files\direnv\`).
+
+**3. Hook direnv into Git Bash**
+
+Add to `~/.bashrc` inside Git Bash:
+
+```bash
+eval "$(direnv hook bash)"
+```
+
+Restart Git Bash after editing.
+
+:::note
+
+nvm-windows reads `.nvmrc` when a version is passed explicitly. The `.envrc` in this project uses `nvm install "$version"` and `nvm use "$version"` (reading from `.nvmrc`), which is compatible with both nvm and nvm-windows.
+
+:::
+
+---
+
+## After cloning
+
+After cloning a project that ships `.envrc`, run once:
+
+```bash
+direnv allow
+```
+
+direnv prompts for this on every new `.envrc` it has not seen before — this is a security feature that prevents untrusted scripts from running automatically. Re-run `direnv allow` whenever `.envrc` changes.
+
+---
+
+## Files
+
+### `.nvmrc`
+
+Contains just the Node.js major version:
+
+```text
+20
+```
+
+Update this when the project requires a new minimum Node version.
+
+### `.envrc`
+
+```bash
+export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"
+
+# Source the nvm shell function.
+# Handles: manual install ($HOME/.nvm), Homebrew on macOS, and WSL.
+# On Windows with nvm-windows, nvm is already an executable in PATH — no sourcing needed.
+if [ -s "$NVM_DIR/nvm.sh" ]; then
+  . "$NVM_DIR/nvm.sh"
+elif [ "$(uname -s 2>/dev/null)" = "Darwin" ] && command -v brew &>/dev/null; then
+  _nvm_sh="$(brew --prefix nvm 2>/dev/null)/nvm.sh"
+  [ -s "$_nvm_sh" ] && . "$_nvm_sh"
+  unset _nvm_sh
+fi
+
+if [ -f ".nvmrc" ]; then
+  _node_version="$(tr -d '[:space:]' < .nvmrc)"
+  nvm install "$_node_version"
+  nvm use "$_node_version"
+  unset _node_version
+fi
+
+# Ensure the pnpm shim declared in package.json#packageManager is active via Corepack.
+# `corepack enable` is idempotent — safe to run on every cd.
+if command -v corepack &>/dev/null; then
+  corepack enable pnpm
+fi
+```
+
+The script handles four environments:
+
+| Environment                      | How nvm is loaded                                               |
+| -------------------------------- | --------------------------------------------------------------- |
+| macOS — manual install           | `$HOME/.nvm/nvm.sh` sourced directly                            |
+| macOS — Homebrew                 | `$(brew --prefix nvm)/nvm.sh` sourced as fallback               |
+| Linux / WSL 2                    | `$HOME/.nvm/nvm.sh` sourced directly                            |
+| Windows — Git Bash + nvm-windows | `nvm` is already in `PATH` as an executable; no sourcing needed |
+
+The version is read explicitly from `.nvmrc` (stripping whitespace) and passed to both `nvm install` and `nvm use`, making the script compatible with both nvm and nvm-windows.
+
+`corepack enable pnpm` installs a global shim so that running `pnpm` always delegates to the exact version declared in `package.json#packageManager` (e.g. `pnpm@9.15.0`). It is idempotent — safe to run on every `cd`. Corepack ships with Node.js 16.9+ so no separate install is required. If `corepack` is not in `PATH`, the block is skipped safely.
+
+:::caution[Avoid `corepack use pnpm`]
+
+`corepack use pnpm` (without an explicit version) writes the **latest** pnpm release into `package.json#packageManager`, silently upgrading the project. Never use it in `.envrc`.
+
+:::
+
+## `.gitignore`
+
+Add the direnv cache directory — it contains compiled environment snapshots and should never be committed:
+
+```text
+.direnv/
+```
+
+---
+
+## Troubleshooting
+
+**`direnv: command not found`** — direnv is not installed or not on `PATH`. Follow the installation steps for your platform above.
+
+**`nvm: command not found` inside `.envrc`** — The `.envrc` could not locate `nvm.sh`. Check:
+
+- Manual install: confirm `$HOME/.nvm/nvm.sh` exists.
+- Homebrew (macOS): confirm `brew list nvm` shows nvm is installed.
+- The `NVM_DIR` environment variable is not pointing somewhere unexpected.
+
+**`direnv` not activating on `cd`** — The shell hook is missing or in the wrong position. Make sure `eval "$(direnv hook zsh)"` (or bash) appears at the very **end** of your shell profile, after all other tool initialisations.
+
+**`nvm use` reports wrong version on Windows** — Ensure nvm-windows v1.1.10 or later is installed. Earlier versions do not reliably accept explicit version arguments.