@activatus/code-standards 3.0.0 → 3.0.1

package/README.md

@@ -144,8 +144,7 @@ static/templates/
 ├── prettier.config.mjs     # ✨ Formatting
 ├── globals.css             # 🎨 Tailwind + starter colour palette
 ├── .editorconfig           # ⌨️ Editor whitespace rules
-├── .nvmrc / .envrc         # 🟢 Node version switching
-└── husky/pre-commit        # 🚦 Lint before every commit
+└── .nvmrc / .envrc         # 🟢 Node version switching
 ```
 
 Copy them. Don't retype them. The ESLint ones have been run against real code, so they actually work, which is more than you can say for most configs floating around the internet.

package/docs/Guides/migrating.md

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # Migrating an Existing Project
 
-Migrating an established codebase to the shared standards is best done in stages to keep PRs reviewable.
+Migrating an established codebase to the shared standards is best done in stages, so each change stays small enough to check properly.
 
 **Already following the standards, and just updating to a newer version?** You don't need this whole guide. Read the [Version History](/version-history) from your project's version onward, and do only what it lists.
 
@@ -19,7 +19,7 @@ The standards apply to **code we write**, not to packages we pull in. Do not lin
 
 ## Stage 1 — Prettier (formatting only)
 
-Formatting changes are safe to land in one big PR because they don't change behaviour.
+Formatting changes are safe to make all at once because they don't change behaviour.
 
 ```bash
 pnpm add -D prettier prettier-plugin-tailwindcss
@@ -33,7 +33,7 @@ Format everything at once:
 pnpm prettier --write .
 ```
 
-Commit it on its own, following the project's commit message format. This keeps the formatting diff isolated, making future `git blame` useful.
+Keep the reformat apart from any other change, so the formatting is easy to tell apart from real changes later.
 
 Add a `.prettierignore` if you have generated files you don't want touched:
 
@@ -68,7 +68,7 @@ export default [
 ];
 ```
 
-Run `pnpm lint` and triage the output. Fix issues in thematic PRs (e.g. all `any` removals together). Once clean, remove the overrides.
+Run `pnpm lint` and triage the output. Fix them one kind at a time (for example, all `any` removals together). Once clean, remove the overrides.
 
 ## Stage 4 — Names
 
@@ -101,9 +101,9 @@ These come up in nearly every project:
 
 `docs/`, `docsSite/`, `DOCS_URL` and `pnpm docs:dev` already follow the standard. Leave them.
 
-### 3. Rename in this order, one pull request each
+### 3. Rename in this order
 
-1. **Folders**, with `git mv` so the history follows the files. Fix the imports in the same pull request.
+1. **Folders**, with `git mv` so the history follows the files. Fix the imports at the same time.
 2. **Types**, so the `@typescript-eslint/naming-convention` errors clear.
 3. **Variables, functions and properties.** Use your editor's **Rename Symbol** (F2), not find-and-replace: it renames every use and nothing else. An agent working from the command line has no editor, so it uses the [rename script](#renaming-from-the-command-line) instead.
 4. **Everything the linter can't see** — form fields, union values, routes, scripts, environment variables. Search for each one by hand.
@@ -117,7 +117,7 @@ Some names are used outside the code. Renaming them needs more than a code chang
 - **API routes and request fields** used by another app need both names to work until that app is updated.
 - **Routes people have bookmarked** need a redirect from the old path.
 
-Write each of these up in the pull request so nobody gets caught out.
+Tell the person about each of these, so nobody gets caught out.
 
 ### Renaming from the command line
 
@@ -132,6 +132,18 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <cur
 node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs components/ui/button/types.ts ButtonProperties ButtonProps
 ```
 
+**Many renames at once:** list them in a text file, one per line, and pass it with `--list`. Blank lines and lines starting with `#` are skipped, and the renames run in order:
+
+```text title="renames.txt"
+# Version 3 renames
+components/ui/button/types.ts ButtonProperties ButtonProps
+lib/terminal/tabs.ts surfaceReference surfaceRef
+```
+
+```bash
+node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list renames.txt
+```
+
 - **Give it the file where the name is declared.** It renames that symbol and every use of it, across the whole project, and leaves anything else with the same name alone.
 - **Shorthand stays correct.** `{ properties }` becomes `{ properties: props }`, so objects keep their shape.
 - **It only renames TypeScript and JavaScript names.** Folders, files, form fields, routes and environment variables still need renaming by hand.
@@ -150,12 +162,8 @@ Copy the eight [standard skill files](/templates#skills) into `.agents/skills/`,
 
 Move the project's existing documentation into the standard [`docs/` folders](/Standards/documentation#-the-folders), rewriting each as a [Decision Doc](/Standards/documentation#-the-doc-format), then add the [`docsSite/` viewer](/Standards/documentation#-setting-it-up) so it shows at `/docs`.
 
-## Stage 8 — Lint before every commit
-
-Add the Husky hook that runs `pnpm lint` before every commit. Add it **last**, once the project passes `pnpm lint`. See [Lint before every commit](/Standards/lint-errors#lint-before-every-commit).
-
 ## Tips
 
-- **Don't mix formatting and logic changes** in the same PR.
+- **Don't mix formatting and logic changes.** Reformat on its own, then change the code.
 - **Exclude generated files** from ESLint with `// eslint-disable-file` or `.eslintignore`-equivalent glob ignores in the config.
 - **Fix new-file compliance first**: agree that all _new_ files must pass the full ruleset even before the migration is complete.

package/docs/Guides/setup.md

@@ -70,13 +70,21 @@ Tell me the numbers to skip or change, or say "all good".
 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
+19. Removed in version 3: commit messages are the project's own workflow
+20. Removed in version 3: branch names are the project's own workflow
+21. AGENTS.md and the eight agent skills
+22. Removed in version 3: whether agents commit is the project's own workflow
+23. The Ontology: the shared words for code
 ```
 
 Then wait for the answer.
 
+**The numbers never change.** A project records its choices by number, so the numbers stay put:
+
+- **A number is never reused.** A removed standard keeps its number in the list, marked "Removed in version N", so a project's old choices still point at the right thing.
+- **A new standard takes the number of the standard it sits closest to, plus a decimal:** a new styling standard after 11 is 11.1, then 11.2, up to 11.9. The list stays short, and nothing after it moves.
+- **Skip the removed ones** when applying the standards. There is nothing to do for them.
+
 | The person says                         | Do                            |
 | --------------------------------------- | ----------------------------- |
 | "All good"                              | Apply every standard          |
@@ -94,7 +102,7 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
 
 **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.
+**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 at a time, after the config files below are in place.
 
 | Standard                 | What to set up                                                                                                                                                                                                                                                                                                       |
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -105,8 +113,7 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
 | 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/` |
+| 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.
 
@@ -133,7 +140,7 @@ The project already follows the standards, and a newer version is out.
 
 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.
+5. **Do every other change** as its "What to do" says, and run its "How to check" search.
 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.
@@ -142,10 +149,10 @@ 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**.
+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 finished later, 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).
+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, if the project tracks that.
 
    ```md
    ## Unfinished changes

package/docs/Standards/human-readable-names.md

@@ -131,7 +131,7 @@ Some short names are not abbreviations. They are the word people actually say, a
 | `docs`                       | A project's documentation                                                                                   | `docs/`, `docsSite/`, `DOCS_URL`, `pnpm docs:dev` |
 | `lib`                        | The folder for outside connections and app-wide setup. Next.js and shadcn/ui use the same name              | `lib/`, `lib/integrations/`                       |
 | `props`                      | The values a component takes                                                                                | `props`, `ButtonProps`                            |
-| `ref`                        | A React ref: a handle on an element or a value kept between renders                                         | `inputRef`, `useRef`, `scrollContainerRef`        |
+| `ref`                        | A reference or handle to something: a React ref, or any other handle, such as a terminal tab's ref          | `inputRef`, `useRef`, `surfaceRef`                |
 | `repo`                       | A repository: in GitHub's words, it "contains all of your project's files and each file's revision history" | `repoName`, `repoUrl`                             |
 | `utils`                      | Reusable functions that are not components                                                                  | `utils/`, `utils/formatCurrency/`                 |
 | `app`                        | The application                                                                                             | `app/`, `appName`                                 |
@@ -150,7 +150,7 @@ Some short names are not abbreviations. They are the word people actually say, a
 When a short name feels like a dictionary word, don't just use it — add it here first:
 
 1. **Ask:** is this the word people actually say, so the long form would only be harder to read? `docs`, `repo`: yes. `env`, `btn`, `msg`: no.
-2. **Add a row** to the table above, in the same pull request as the code that uses it.
+2. **Add a row** to the table above, before or alongside the code that uses it.
 3. **If ESLint flags the word**, add it to `replacements` in the `unicorn/name-replacements` rule of the [ESLint config](/Standards/eslint), so the linter agrees: `replacements: { docs: false, lib: false, props: false, ref: false, repo: false, utils: false }`.
 
 The list is the record. If a word is not on it, it is not a dictionary word yet.

package/docs/Standards/lint-errors.md

@@ -128,44 +128,8 @@ Nothing else is switched off. If another rule seems impossible to satisfy, the c
 
 ---
 
-## How errors are caught
+## When lint must pass
 
-Lint runs in three places, so a broken standard is caught before it reaches `main`:
+**Work is not finished until `pnpm lint` passes.** That goes for people and AI agents alike: an agent fixes every lint error before it says a task is done.
 
-| Where                                                           | When                      | What happens on an error                                                 |
-| --------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------ |
-| **AI agents**                                                   | Before finishing any task | The agent fixes the error. Its work is not done until `pnpm lint` passes |
-| **Git hook** ([`.husky/pre-commit`](#lint-before-every-commit)) | On every commit           | The commit is refused until the errors are fixed                         |
-| **CI**                                                          | On every change pushed    | The change cannot be merged                                              |
-
-## Lint before every commit
-
-A [Husky](https://typicode.github.io/husky/) git hook runs `pnpm lint` before every commit, so code that breaks the standards cannot be committed.
-
-1. Install Husky:
-
-   ```bash
-   pnpm add -D husky
-   ```
-
-2. Add the `prepare` script to `package.json`, so the hook is installed whenever someone runs `pnpm install`:
-
-   ```json
-   {
-     "scripts": {
-       "prepare": "husky"
-     }
-   }
-   ```
-
-3. Copy the hook file [`.husky/pre-commit`](/templates#husky-pre-commit):
-
-   ```text title=".husky/pre-commit"
-   pnpm lint
-   ```
-
-4. Run `pnpm install` once to switch it on.
-
-**Add the hook last**, once the project already passes `pnpm lint`. Otherwise every commit is refused until the whole codebase is fixed.
-
-How the project names commits and branches, and who may commit, is up to the project. See [Project workflow](/Standards/agent-specs#project-workflow).
+How a project makes sure of it, such as a git hook or a check that runs on every change, is the project's own choice. See [Project workflow](/Standards/agent-specs#project-workflow).

package/docs/Standards/tech-stack.md

@@ -136,7 +136,6 @@ See `package.json` for specific version requirements. Key dependencies:
 
 - **Linting**: ESLint 9+
 - **Formatting**: Prettier
-- **Git Hooks**: Husky
 - **Monorepo**: Turborepo
 - **Documentation**: Docusaurus
 

package/docs/Structure/folder-structure.md

@@ -189,7 +189,7 @@ Three folders hold functions that are not components. Each function belongs in e
 - **Pages, API routes and server actions stay thin.** They take the request, call a function in `services/`, and return the result. Business logic never lives in them.
 - **`services/` uses `lib/` to reach the outside world.** A service that charges a card calls the Stripe client in `lib/integrations/stripe/`, never the Stripe package directly.
 - **`utils/` uses nothing outside itself.** If a function needs a database, an API or the environment, it is not a util: it belongs in `services/` or `lib/`.
-- **Group `services/` by the [Ontology](/ontology) word it works on**, one folder per function: `services/invoice/createInvoice/`.
+- **Group `services/` by the project's own ontology word it works on**, one folder per function: `services/invoice/createInvoice/`. The project's ontology is usually in `docs/product/ontology.md`, but it can be in another file. If you can't find it, ask.
 
 ## 🧰 Utils
 

package/docs/templates.mdx

@@ -33,7 +33,6 @@ import docsSiteGitignore from "!!raw-loader!@site/static/templates/docsSite/giti
 import decisionDoc from "!!raw-loader!@site/static/templates/decision-doc.md";
 import docsSiteHome from "!!raw-loader!@site/static/templates/docsSite/src/pages/index.tsx";
 import nextConfig from "!!raw-loader!@site/static/templates/next.config.mjs";
-import huskyPreCommit from "!!raw-loader!@site/static/templates/husky/pre-commit";
 
 # Templates
 
@@ -58,7 +57,6 @@ Each file is also served as a plain file, so a person or an AI agent can fetch i
 | [Node version](#nvmrc)                           | `.nvmrc` in the project root               | [`/templates/.nvmrc`](pathname:///templates/.nvmrc)                                                           |
 | [direnv](#envrc)                                 | `.envrc` in the project root               | [`/templates/.envrc`](pathname:///templates/.envrc)                                                           |
 | [Agent skills](#skills)                          | `.agents/skills/` and `.claude/commands/`  | Eight files — see [below](#skills)                                                                            |
-| [Lint before commit](#husky-pre-commit)          | `.husky/pre-commit`                        | [`/templates/husky/pre-commit`](pathname:///templates/husky/pre-commit)                                       |
 | [Docs site](#docs-site)                          | `docsSite/` in the project root            | Several files — see [below](#docs-site)                                                                       |
 | [`/docs` route](#docs-route)                     | `next.config.mjs`                          | [`/templates/next.config.mjs`](pathname:///templates/next.config.mjs)                                         |
 | [Document templates](#document-templates)        | `docs/` in the project root                | Several files — see [below](#document-templates)                                                              |
@@ -292,18 +290,6 @@ Runs the test suite; reports failures grouped by cause, tests that never ran, an
 
 ---
 
-## Lint before commit {#husky-pre-commit}
-
-**Copy to:** `.husky/pre-commit` in the project root
-
-Refuses a commit while `pnpm lint` reports errors. See [Lint before every commit](/Standards/lint-errors#lint-before-every-commit). Plain file: [`/templates/husky/pre-commit`](pathname:///templates/husky/pre-commit)
-
-<CodeBlock language="text" title=".husky/pre-commit">
-  {huskyPreCommit}
-</CodeBlock>
-
----
-
 ## Docs site {#docs-site}
 
 **Copy to:** a `docsSite/` folder in the project root

package/docs/version-history.md

@@ -21,30 +21,37 @@ sidebar_label: "Version History"
 2. **Update the package:** `pnpm update @activatus/code-standards --latest`. Then read this page from `node_modules/@activatus/code-standards/docs/version-history.md`.
 3. **Read each version newer than the project's**, oldest first. Skip any change to a standard the project opted out of: they are listed in `docs/development/coding-standards.md`.
 4. **For each change, do the "What to do" steps**, then run the "How to check" searches. A search that still finds something means the change is not finished.
-5. **One pull request per kind of change** (for example, all the folder renames together), so each one stays easy to review. Follow the project's commit rule in `AGENTS.md`.
-6. **Run `pnpm lint`, `pnpm test` and the build** after each change.
-7. **Update the version number** in `AGENTS.md` once every change is done.
+5. **Run `pnpm lint`, `pnpm test` and the build** after each change.
+6. **Update the version number** in `AGENTS.md` once every change is done.
 
 **When a change does not fit the project**, for example it renames a folder the project does not have, skip it. If you are not sure, ask; do not guess.
 
 ## Adding a version
 
-Anyone changing the standards adds a version, in the same pull request as the change:
+Anyone changing the standards adds a version, alongside the change:
 
 - **One version per release**, numbered one higher than the last. Whole numbers only. A version can collect several changes before it is released.
 - **Bump the package's major version to match** in `package.json`: version 3 is `3.0.0`. Then publish it to npm (npmjs.com) with `pnpm publish`. pnpm is the tool; npm is where the package lives, and projects install it from there with `pnpm add`.
 - **For every change, write:** what changed, why, what to do in a project, and how to check it is done. Write it for an agent that has not read the rest of the standards.
 - **If a project has nothing to do, say so.**
 - **Newest version at the top.**
-- **Work in progress goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over several Pull Requests. To release it: drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
+- **Work in progress goes under `## Version N — not released yet`**, with a line saying projects should not apply it yet. Changes can be added to it over time. To release it: drop "not released yet", add the **Released** date and **Updates from** line, set `package.json` to `N.0.0`, then publish.
+- **Fixing a released version** bumps only the last number: `3.0.0` → `3.0.1`. Update the version's changes in place, and list what was fixed under its **Fixes**. Projects keep the same version number in `AGENTS.md`.
 
 ---
 
 ## Version 3
 
-**Released:** 2026-10-17 · **Updates from:** version 2
+**Released:** 2026-10-17 · **Updates from:** version 2 · **Latest fix:** 3.0.1
 
-Install it with `pnpm add -D @activatus/code-standards@3.0.0`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
+Install it with `pnpm add -D @activatus/code-standards@3.0.1`. Do change 1 first: it says which parts of the project's `AGENTS.md` are now the project's own to write.
+
+**Fixes in 3.0.1.** If the project already applied 3.0.0, check these:
+
+- Setup list numbers are permanent again: 19, 20 and 22 are marked removed, and AGENTS.md and the Ontology are back to 21 and 23. Choices recorded under the version 2 numbers are still right.
+- The Husky lint hook is no longer a standard. Lint must pass before work is finished; how that is enforced is the project's choice.
+- Every name ending in `Reference` uses `Ref`, not only React refs.
+- The rename script takes a list of renames with `--list`.
 
 ### 1. Project workflow is no longer part of the standards
 
@@ -53,10 +60,10 @@ Install it with `pnpm add -D @activatus/code-standards@3.0.0`. Do change 1 first
 **What to do:**
 
 - The Branch Naming and Commit Messages standards are gone, along with standards 19, 20 and 22 from the setup list. Keep whatever the project already does, and make sure it is written up in the project's own docs, usually `docs/development/`.
-- In `AGENTS.md`, replace the "Development workflow" section with a **Project workflow** section, copied from the [template](/templates#agents). Fill it in with the project's own rules: who commits, branches, commit messages, Pull Requests, merging and releases. Put the most important rule for agents — whether they may commit — in the line at the very top.
+- **Standards 19, 20 and 22 keep their numbers, marked as removed.** No other number changes. If `docs/development/coding-standards.md` records a choice for 19, 20 or 22, move that rule into Project workflow and take it off the list.
+- In `AGENTS.md`, replace the "Development workflow" section with a **Project workflow** section, copied from the [template](/templates#agents). Fill it in with the project's own rules: who commits, branches, commit messages, Pull Requests, merging and releases. Put the most important rule for agents, usually whether they may commit, at the very top: one line, or a short section if it needs more.
 - Remove the "Never commit code" and "Do not create, switch or delete branches" lines from "Out of scope for AI agents", unless they are the project's own rule. If they are, they belong in Project workflow.
-- Commitlint and the `.husky/commit-msg` hook are no longer templates. Keep them if the project wants its commit messages checked; they are now the project's choice.
-- **Keep `.husky/pre-commit`.** Running `pnpm lint` before every commit is still a standard. See [Lint before every commit](/Standards/lint-errors#lint-before-every-commit).
+- Commitlint and the Husky hooks (`.husky/commit-msg` and `.husky/pre-commit`) are no longer templates. Keep them if the project wants them: they are now the project's choice. The standard is only that `pnpm lint` passes before work is finished. See [When lint must pass](/Standards/lint-errors#when-lint-must-pass).
 
 **How to check:** `AGENTS.md` has a Project workflow section, and every rule in it is written up in the project's docs.
 
@@ -67,7 +74,7 @@ Install it with `pnpm add -D @activatus/code-standards@3.0.0`. Do change 1 first
 **What to do:**
 
 - Rename the `library/` folder to `lib/` with `git mv`, and fix the imports: `@/library/` → `@/lib/`.
-- Rename names ending in `Reference` that hold a React ref back to `Ref`: `inputReference` → `inputRef`. Rename `repository` back to `repo` where it is short for a Git repository, such as `repositoryName` → `repoName`. Use the editor's Rename Symbol (F2), or the [rename script](/Guides/migrating#renaming-from-the-command-line).
+- Rename every name ending in `Reference` to end in `Ref`, whatever it refers to: `inputReference` → `inputRef`, `surfaceReference` → `surfaceRef`. Rename `repository` back to `repo` where it is short for a Git repository, such as `repositoryName` → `repoName`. Use the editor's Rename Symbol (F2), or the [rename script](/Guides/migrating#renaming-from-the-command-line).
 - Copy the new [ESLint config](/Standards/eslint). The naming rule now has `replacements: { docs: false, lib: false, props: false, ref: false, repo: false, utils: false }` and `allowList: { params: true, searchParams: true }`.
 - Update the "Dictionary words stay short" line in `AGENTS.md` from the [template](/templates#agents), and remove `lib/` → `library/` and `repo` → `repository` from its Never / Always table.
 
@@ -108,7 +115,7 @@ Install it with `pnpm add -D @activatus/code-standards@3.0.0`. Do change 1 first
 **What to do:**
 
 - Copy the new [`prettier.config.mjs`](/templates#prettier) and [`.editorconfig`](/templates#editorconfig). Prettier now has `printWidth: 70` and `useTabs: true`, and keeps spaces for Markdown and YAML. EditorConfig indents with tabs, except Markdown, YAML and Python.
-- Run `pnpm format` once, on its own, in a Pull Request with nothing else in it. It touches nearly every file, so keep it apart from real changes.
+- Run `pnpm format` once, on its own, with no other changes mixed in. It touches nearly every file, so keep it apart from real changes.
 - If the project shows code on a web page, such as its docs site, add `pre, code { tab-size: 2; }` to its CSS, so tabs are not shown 8 characters wide. The [`docsSite/` template](/templates#docs-site) already has it.
 
 **How to check:** `pnpm format:check` passes.
@@ -145,7 +152,7 @@ See [When a name clashes](/Standards/human-readable-names#when-a-name-clashes).
 
 ### 10. Unfinished changes are recorded, not hidden
 
-**Why:** A big change, such as switching on the standard ESLint config, may be done later in its own Pull Request. The version number has to stay honest about that.
+**Why:** A big change, such as switching on the standard ESLint config, may be finished later. The version number has to stay honest about that.
 
 **What to do:** Add an "Unfinished changes" section to `docs/development/coding-standards.md`, from the [template](/templates#document-templates). List any change from any version that is not done yet, with what is left and where it is being done, or write "None". See [Finishing a change later](/Guides/setup#finishing-a-change-later).
 
@@ -154,11 +161,10 @@ See [When a name clashes](/Standards/human-readable-names#when-a-name-clashes).
 ### No action needed
 
 - The [Ontology](/ontology) defines `dependency`: something the code relies on but does not define itself. Ticket relationships are not dependencies; each project names those itself.
-- The package now ships a rename script for agents working from the command line, using TypeScript's own rename: `node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>`. See [Renaming from the command line](/Guides/migrating#renaming-from-the-command-line).
+- The package now ships a rename script for agents working from the command line, using TypeScript's own rename: `node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>`. Pass `--list renames.txt` to do many renames in one run, one per line. It can't reach keys in untyped object literals, such as the expected value in a test's `toEqual({ … })`: search the tests for old names and fix those by hand. See [Renaming from the command line](/Guides/migrating#renaming-from-the-command-line).
 - The [Setup](/Guides/setup) guide says the standards are a base for code only, and explains how to get past pnpm's `minimumReleaseAge` when a new version is too fresh to install.
 - [Folder Structure](/Structure/folder-structure) explains each `lib/` folder in one line.
 - The [ESLint page](/Standards/eslint#installation) says the config needs ESLint 10.4 or later, and the React configs explain why they set `settings.react.version`.
-- "Lint before every commit" moved to [Lint Errors](/Standards/lint-errors#lint-before-every-commit).
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activatus/code-standards",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "The Activatus code standards: the rules as Markdown, and the config files to copy. Install it so an AI agent can read the standards from node_modules.",
   "repository": {
     "type": "git",

package/scripts/renameSymbol.mjs

@@ -6,14 +6,23 @@
 //   node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>
 // For example:
 //   node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs components/ui/button/types.ts ButtonProperties ButtonProps
+//
+// To do many renames in one run, list them in a text file, one per line: <file> <currentName> <newName>.
+// Blank lines and lines starting with # are skipped. The renames run in order.
+//   node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list renames.txt
 import { readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 
 // process.argv starts with the node binary and this script's path.
 const FIRST_ARGUMENT_INDEX = 2;
-const USAGE =
-	"Usage: node renameSymbol.mjs <file> <currentName> <newName>";
+const LIST_FLAG = "--list";
+// A rename line has three parts: file, current name, new name.
+const RENAME_PARTS = 3;
+const USAGE = [
+	"Usage: node renameSymbol.mjs <file> <currentName> <newName>",
+	"   or: node renameSymbol.mjs --list <file of renames>",
+].join("\n");
 
 // Uses the project's own TypeScript, so the rename matches the project's compiler exactly.
 const requireFromProject = createRequire(
@@ -176,12 +185,45 @@ const renameSymbol = ({ filePath, currentName, newName }) => {
 	return `Renamed ${currentName} to ${newName}: ${renameLocations.length} places in ${fileCount} ${fileWord}.`;
 };
 
-const [filePath, currentName, newName] = process.argv.slice(
-	FIRST_ARGUMENT_INDEX,
-);
+// Each line of a list file is one rename: <file> <currentName> <newName>.
+const readRenameList = (listPath) =>
+	readFileSync(listPath, "utf8")
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => line !== "" && !line.startsWith("#"))
+		.map((line) => {
+			const [filePath, currentName, newName] = line.split(
+				/\s+/u,
+				RENAME_PARTS,
+			);
+
+			return { filePath, currentName, newName };
+		});
 
-if (filePath && currentName && newName) {
-	console.log(renameSymbol({ filePath, currentName, newName }));
+const isCompleteRename = ({ filePath, currentName, newName }) =>
+	Boolean(filePath && currentName && newName);
+
+const commandArguments = process.argv.slice(FIRST_ARGUMENT_INDEX);
+const [firstArgument, secondArgument] = commandArguments;
+const renames =
+	firstArgument === LIST_FLAG && secondArgument
+		? readRenameList(secondArgument)
+		: [
+				{
+					filePath: commandArguments[0],
+					currentName: commandArguments[1],
+					newName: commandArguments[2],
+				},
+			];
+
+if (
+	renames.length > 0 &&
+	renames.every((rename) => isCompleteRename(rename))
+) {
+	// Each rename reloads the project, so it sees the renames before it.
+	for (const rename of renames) {
+		console.log(renameSymbol(rename));
+	}
 } else {
 	console.error(USAGE);
 	process.exitCode = 1;

package/static/templates/AGENTS.md

@@ -1,6 +1,6 @@
 # [Project Name]
 
-> [The project's most important workflow rule for agents, stated first so every agent sees it: whether an agent may commit, push or make branches. See "Project workflow" below.]
+> [The project's most important rule for agents, stated first so every agent sees it. Usually whether an agent may commit, push or make branches. One line, or a short section if it needs more, such as which agents may commit, when, and how the others ask. See "Project workflow" below.]
 
 > **"go" means carry on.** When the person sends only "go", carry on with the current task. It is never permission to commit, push or open a Pull Request, and it needs no reply asking what they meant.
 

package/static/templates/husky/pre-commit

@@ -1 +0,0 @@
-pnpm lint