@activatus/code-standards 0.0.0-stage → 2.0.0

package/docs/Guides/setup.md

@@ -0,0 +1,130 @@
+---
+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.
+
+## 1. Install the standards
+
+```bash
+pnpm add -D @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, functions in utils/
+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. Conventional Commits, checked by Husky, with pnpm lint before every commit
+20. Branch names: type/short-description
+21. AGENTS.md and the eight agent skills
+22. AI agents never commit, push or make branches (strict no commit)
+23. 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 22: agents can commit when I say I'm on my phone" | Apply 22 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.
+
+If standard 22 is changed, also replace the "NEVER COMMIT CODE" lines in `AGENTS.md` with the person's rule. See [A project can choose otherwise](/Standards/agent-specs#a-project-can-choose-otherwise).
+
+## 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.
+
+**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.js`. 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. Commits              | Copy `static/templates/.commitlintrc.json` and the two hooks in `static/templates/husky/`. Add the lint hook last, once `pnpm lint` passes. See [Enforcing commit messages](/Standards/conventional-commits#enforcing-commit-messages)                                                                               |
+| 21. 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.
+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.
+
+See the [Version History](/version-history) for the full update rules.

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`.** [Agents never commit code](/Standards/agent-specs#agents-never-commit-code), so no skill is allowed to.
+
+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,89 @@
+---
+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.
+
+## Agents never commit code
+
+**An AI agent never commits.** It does not run `git commit`, `git push`, `git merge`, `git rebase` or `git stash`, and it does not create, switch or delete branches.
+
+The agent makes the changes, leaves them uncommitted in the working tree, and says what it changed. A person reviews the changes and commits them.
+
+Every `AGENTS.md` states this at the very top and again under "Out of scope for AI agents". The [template](/templates#agents) already does.
+
+### A project can choose otherwise
+
+**Strict no commit is the default.** It is standard 22 in the list the person agrees to during [Setup](/Guides/setup#3-agree-the-standards), so they can change it then. Or they can be asked directly:
+
+> Should AI agents be allowed to commit in this project, or is it strict no commit?
+
+| Answer                             | What goes in `AGENTS.md`                                                                                                                                                                                             |
+| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Strict no commit** (the default) | The template as it is                                                                                                                                                                                                |
+| **Agents may commit**              | Replace the "NEVER COMMIT CODE" lines with the project's own rule, saying exactly which agents may commit, push and open Pull Requests, and when. A tool built to ship code with AI, such as Launchpad, chooses this |
+
+A person can also allow it for one piece of work, such as when they are away from their computer. That permission lasts for that piece of work only, and never changes the project's rule.
+
+## 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                                               |
+| Development workflow       | [Branch naming](/Standards/branch-naming), commit format, PR requirements, merge strategy |
+| 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 forbidden agent actions — always including "never commit code"           |
+
+## 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 code — see [Agents never commit code](#agents-never-commit-code).
+
+### 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/branch-naming.md

@@ -0,0 +1,66 @@
+---
+sidebar_position: 6.5
+---
+
+# Branch Naming
+
+Every branch name says what kind of work it holds and what the work is.
+
+## Format
+
+```text
+<type>/<short-description>
+```
+
+```text
+feat/invoice-export
+fix/login-redirect-loop
+docs/update-readme
+```
+
+## Rules
+
+- **Start with a type**, followed by a slash. The types are the same as [Conventional Commits](/Standards/conventional-commits#type-reference).
+- **Describe the work in two to five words**, in lower-case kebab-case. Branch names are kebab-case, like route folders, documentation files and CSS variables — it is the Git convention, and it is safe on every operating system.
+- **Use full English words**, the same as in code: `fix/button-alignment`, not `fix/btn-align`.
+- **One piece of work per branch.** If the description needs the word "and", it is two branches.
+- **Never work directly on `main`.**
+
+## Types
+
+| Type       | Use for                                | Example                       |
+| ---------- | -------------------------------------- | ----------------------------- |
+| `feat`     | A new feature                          | `feat/invoice-export`         |
+| `fix`      | A bug fix                              | `fix/login-redirect-loop`     |
+| `docs`     | Documentation only                     | `docs/update-readme`          |
+| `refactor` | Restructuring with no behaviour change | `refactor/split-user-service` |
+| `test`     | Adding or correcting tests             | `test/invoice-total-rounding` |
+| `chore`    | Maintenance, dependencies, tooling     | `chore/upgrade-next`          |
+
+## Examples
+
+```text
+✅ Good
+feat/hero-question-rail
+fix/checkout-total-rounding
+chore/upgrade-tailwind
+
+❌ Bad
+hero                         # No type, and too vague
+feature/HeroQuestionRail     # Not a standard type, and not kebab-case
+fix/btn                      # Shorthand
+toms-branch                  # Says nothing about the work
+feat/invoices-and-login-fix  # Two pieces of work
+```
+
+## Ticket numbers
+
+When the work has a ticket, put the ticket number after the type:
+
+```text
+feat/ACT-142-invoice-export
+```
+
+## AI agents
+
+AI agents **never commit code**, so they do not create branches to commit to either. A person creates the branch, reviews the agent's changes, and commits them. See [AGENTS.md](/Standards/agent-specs#agents-never-commit-code).

package/docs/Standards/conventional-commits.md

@@ -0,0 +1,189 @@
+---
+sidebar_position: 6
+---
+
+# Conventional Commits
+
+All Activatus repositories follow the [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/) specification for commit messages. This gives us machine-readable history, automatic changelogs, and a shared vocabulary for what a commit does.
+
+## Format
+
+```text
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+The first line (header) must not exceed **72 characters**. Everything else is optional.
+
+## Quick examples
+
+```text
+feat(authentication): add magic-link login flow
+fix(api): handle null response from payment provider
+docs: clarify AGENTS.md authoring guide
+refactor(ui): extract Button into shared component library
+chore(deps): bump eslint-config to v0.2.0
+feat!: drop support for Node 18
+```
+
+## Type reference
+
+| Type | When to use |
+| --- | --- |
+| `feat` | A new feature visible to users or API consumers |
+| `fix` | A bug fix |
+| `docs` | Documentation changes only |
+| `style` | Formatting or whitespace — no logic change |
+| `refactor` | Code restructuring with no feature or bug change |
+| `perf` | A performance improvement |
+| `test` | Adding or correcting tests |
+| `build` | Build system or dependency changes |
+| `ci` | CI/CD pipeline changes |
+| `chore` | Maintenance that doesn't fit elsewhere |
+| `revert` | Reverts a previous commit |
+
+## Scope
+
+The scope is optional and goes in parentheses after the type. It names the part of the codebase the commit touches:
+
+```text
+feat(authentication): ...
+fix(checkout): ...
+refactor(ui/button): ...
+```
+
+Use lowercase, kebab-case names. If a commit spans many areas, omit the scope rather than writing a vague one.
+
+## Description
+
+- Imperative, present tense: **"add"** not "added" or "adds"
+- No capital letter at the start
+- No period at the end
+- Describes *what* the commit does, not *how*
+
+```text
+✓  feat: add dark mode toggle
+✗  feat: Added dark mode toggle.
+✗  feat: dark mode
+```
+
+## Body
+
+The body explains the *why* behind a change — context that won't be obvious from the diff. Wrap at 72 characters.
+
+```text
+fix(api): retry on transient 503 from payments provider
+
+The payments API returns a 503 during brief maintenance windows.
+Previously this caused checkout to fail immediately. Now we retry
+up to 3 times with exponential back-off before surfacing an error.
+```
+
+## Breaking changes
+
+Signal a breaking change in one of two ways:
+
+**Inline `!` after the type** (for the header only):
+
+```text
+feat!: remove deprecated /v1/users endpoint
+```
+
+**`BREAKING CHANGE:` footer** (required when a body explains the break):
+
+```text
+feat(api)!: require explicit content-type header on all requests
+
+BREAKING CHANGE: requests without a Content-Type header now return
+400. Previously the API defaulted to application/json.
+```
+
+A breaking change bumps the **major** version in SemVer (`1.0.0` → `2.0.0`).
+
+## Versioning implications
+
+When using [Changesets](https://github.com/changesets/changesets) or a changelog tool that understands Conventional Commits:
+
+| Commit type | SemVer bump |
+| --- | --- |
+| `fix`, `perf` | patch (`1.0.0` → `1.0.1`) |
+| `feat` | minor (`1.0.0` → `1.1.0`) |
+| Any with `!` or `BREAKING CHANGE` | major (`1.0.0` → `2.0.0`) |
+| All others (`docs`, `chore`, `ci`, …) | none |
+
+## Multi-commit PRs
+
+Each commit in a PR should be independently meaningful and deployable. Prefer:
+
+```text
+feat(authentication): scaffold magic-link token model
+feat(authentication): add magic-link send endpoint
+feat(authentication): add magic-link verify endpoint
+test(authentication): add integration tests for magic-link flow
+docs(authentication): document magic-link API in AGENTS.md
+```
+
+Over a single `feat(authentication): implement magic-link` that touches everything at once. Granular commits make `git bisect` and revert effective.
+
+## People commit, not AI agents
+
+Commits are made by people. [AI agents never commit code](/Standards/agent-specs#agents-never-commit-code) — an agent leaves its changes uncommitted, and a person reviews them and writes the commit.
+
+Branches follow the [Branch Naming](/Standards/branch-naming) standard.
+
+## Enforcing commit messages
+
+Every project uses [Commitlint](https://commitlint.io) with a [Husky](https://typicode.github.io/husky/) git hook, so a commit with a badly formatted message is refused. **Set up both — the config file on its own enforces nothing.**
+
+### Setup
+
+1. Install the packages:
+
+   ```bash
+   pnpm add -D @commitlint/cli @commitlint/config-conventional husky
+   ```
+
+2. Add the `prepare` script to `package.json`, so the hooks are installed whenever someone runs `pnpm install`:
+
+   ```json
+   {
+     "scripts": {
+       "prepare": "husky"
+     }
+   }
+   ```
+
+3. Add [`.commitlintrc.json`](/templates#commitlint) to the project root.
+
+4. Add the hook file [`.husky/commit-msg`](/templates#husky):
+
+   ```text title=".husky/commit-msg"
+   pnpm exec commitlint --edit "$1"
+   ```
+
+5. Run `pnpm install` once to activate the hook.
+
+After that, every commit runs the `commit-msg` hook.
+
+### Lint before every commit
+
+Add a second hook, [`.husky/pre-commit`](/templates#husky), so code that breaks the standards cannot be committed:
+
+```text title=".husky/pre-commit"
+pnpm lint
+```
+
+If `pnpm lint` reports an error, the commit is refused. See [Fixing Lint Errors](/Standards/lint-errors).
+
+### Configuration
+
+The configuration is in `.commitlintrc.json`:
+
+```json
+{
+  "extends": ["@commitlint/config-conventional"]
+}
+```