@activatus/code-standards 2.0.0 → 3.0.0

package/docs/ontology.md

@@ -17,7 +17,7 @@ An ontology is a shared vocabulary. When a person or an agent says "component",
 
 This page only holds **code words**: how code is written, named, tested, documented and reviewed.
 
-**Product words live in each project's own ontology**, in `docs/product/ontology.md`: the words for what that project builds and how its team plans the work. Launchpad's Draft Ticket, Pitch and UAT are product words, so they are in Launchpad's ontology, not here.
+**Product words live in each project's own ontology**, in `docs/product/ontology.md`: the words for what that project builds and how its team plans the work. **Project-management words live there too**: project, feature, ticket, branch, commit, Pull Request, release. Every project defines those for itself. Launchpad's Draft Ticket, Pitch and UAT are product words, so they are in Launchpad's ontology, not here.
 
 |              | Code words                                               | Product words                                       |
 | ------------ | -------------------------------------------------------- | --------------------------------------------------- |
@@ -48,12 +48,10 @@ The words stay the same everywhere. Only the casing changes, to match where the
 
 ## The terms
 
-### Projects and docs
+### Docs
 
 | Term           | Means                                                                                                                                                  |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `project`      | One product's code and docs. One project is exactly one repository                                                                                     |
-| `repository`   | The Git repository that holds a project's code and docs                                                                                                |
 | `decision`     | A choice made on purpose and written down, never left implied                                                                                          |
 | `decision_doc` | One Markdown file that records one decision and why it was made. Every file in a project's `docs/` folder is one. See [Docs](/Standards/documentation) |
 | `docs`         | A project's `docs/` folder: its Decision Docs, in the same standard folders in every project                                                           |
@@ -62,17 +60,17 @@ The words stay the same everywhere. Only the casing changes, to match where the
 
 ### People and agents
 
-| Term            | Means                                                                                                                                                                                                                                                  |
-| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `human`         | A person, as opposed to an agent. Only humans commit code, unless the project's `AGENTS.md` says agents may                                                                                                                                            |
-| `developer`     | A human who writes code                                                                                                                                                                                                                                |
-| `agent`         | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does. By default it never commits, pushes or makes branches — see [A project can choose otherwise](/Standards/agent-specs#a-project-can-choose-otherwise) |
-| `agent_spec`    | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/Standards/agent-specs)                                                                                                       |
-| `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves          |
-| `context`       | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on                                                                                                                                              |
-| `tool`          | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server                                                                                                                |
-| `model`         | The AI model an agent thinks with                                                                                                                                                                                                                      |
-| `mcp`           | Model Context Protocol: the standard way to connect an agent to outside tools and data, such as Linear or GitHub. An MCP server offers tools, and the agent calls them                                                                                 |
+| Term            | Means                                                                                                                                                                                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `human`         | A person, as opposed to an agent                                                                                                                                                                                                              |
+| `developer`     | A human who writes code                                                                                                                                                                                                                       |
+| `agent`         | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does                                                                                                                                             |
+| `agent_spec`    | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/Standards/agent-specs)                                                                                              |
+| `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves |
+| `context`       | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on                                                                                                                                     |
+| `tool`          | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server                                                                                                       |
+| `model`         | The AI model an agent thinks with                                                                                                                                                                                                             |
+| `mcp`           | Model Context Protocol: the standard way to connect an agent to outside tools and data, such as Linear or GitHub. An MCP server offers tools, and the agent calls them                                                                        |
 
 ### Code
 
@@ -84,7 +82,10 @@ The words stay the same everywhere. Only the casing changes, to match where the
 | `page_component`                        | A component used by one page, or by a few pages in one section. It lives in a `components/` folder beside that page, or in the section's route group. See [Where components live](/Structure/folder-structure#-where-components-live)                                                                                                                                                   |
 | `props`                                 | The values a component takes. `props` is a [dictionary word](/Standards/human-readable-names#dictionary). Their type is named after the component and ends in `Props`: `ButtonProps`                                                                                                                                                                                                    |
 | `type`                                  | A TypeScript type or interface. Its name ends in `Props` or `Type`                                                                                                                                                                                                                                                                                                                      |
+| `dependency`                            | Something the code relies on but does not define itself: a package it installs, or the functions handed into a function as its `dependencies`. How tickets wait on each other is not a dependency here: each project names that itself, such as Launchpad's `blocked_by`                                                                                                                |
 | `utils`                                 | Reusable functions that are not components, such as `formatCurrency`. They live in a `utils/` folder: global, for one section, or for one component. Each function has its own folder with its test file and an `index.ts`. `utils` is a [dictionary word](/Standards/human-readable-names#dictionary). Never `helpers` or `utilities`. See [Utils](/Structure/folder-structure#-utils) |
+| `services`                              | The business logic: what the app does, its rules and operations. Pages, API routes and server actions stay thin and call into `services/`. See [utils, services and lib](/Structure/folder-structure#utils-services-and-lib)                                                                                                                                                            |
+| `lib`                                   | Code that connects the app to something outside it, such as integration clients in `lib/integrations/stripe/`, and app-wide setup: permissions, middleware, validation, constants, errors and shared types                                                                                                                                                                              |
 | `route`                                 | A web address in the app, such as `/account-settings` or `/api/calendar-events`, and the folder or file that creates it. Route folders are kebab-case, because their names become the URL. In Next.js, routes are the folders under `app/`. See [API Routes](/Structure/api-routes)                                                                                                     |
 | `server_component` / `client_component` | A component that runs on the server, and one that runs in the browser. They live in separate files, and the server one wraps the client one                                                                                                                                                                                                                                             |
 | `test_file`                             | The file that tests one function or component, named after it: `formatCurrency.test.ts`. Every function and component has one                                                                                                                                                                                                                                                           |
@@ -93,16 +94,11 @@ The words stay the same everywhere. Only the casing changes, to match where the
 | `third_party_code`                      | Code we did not write: `node_modules/`, and anything copied into `vendor/`. It is never linted, reformatted or renamed                                                                                                                                                                                                                                                                  |
 | `global_palette`                        | The colours defined in `app/globals.css`. Every colour in a project comes from it. See [Styling](/Standards/styling)                                                                                                                                                                                                                                                                    |
 
-### Changes and checks
+### Checks
 
-| Term                  | Means                                                                                                                                                |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `branch`              | A line of work in Git, named `type/short-description`. Nobody works straight on `main`. See [Branch Naming](/Standards/branch-naming)                |
-| `commit`              | A saved change, with a [Conventional Commits](/Standards/conventional-commits) message. Only humans make commits, unless the project says agents may |
-| `pull_request`        | A request to merge a branch into `main`, with a description of what changed and why                                                                  |
-| `pull_request_review` | Checking a Pull Request against these standards before it is merged, by a human or an agent                                                          |
-| `lint_error`          | A broken rule the linter reports. Fix the code; never switch the rule off without a comment saying why. See [Lint Errors](/Standards/lint-errors)    |
-| `production`          | The live app that real users use                                                                                                                     |
+| Term         | Means                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lint_error` | A broken rule the linter reports. Fix the code; never switch the rule off without a comment saying why. See [Lint Errors](/Standards/lint-errors) |
 
 ---
 
@@ -114,11 +110,10 @@ These are the terms most easily confused. The **Not** column is the word we do n
 | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
 | **Decision / Decision Doc**                 | The choice itself vs the file that records it                                                                                                           |                        |
 | **Docs / Docs Site**                        | The Markdown files vs the viewer that shows them                                                                                                        |                        |
-| **Human / Agent**                           | By default only a human commits. An agent makes the change and leaves it for a human to review                                                          |                        |
 | **Props**                                   | The values a component takes                                                                                                                            | `properties`           |
 | **Utils**                                   | Reusable functions                                                                                                                                      | `helpers`, `utilities` |
 | **Dictionary Word / Third-Party Name**      | A short name we chose to keep vs a name someone else chose for us                                                                                       |                        |
-| **Design System / Shared / Page Component** | The same in every project (`components/ui/`) vs used on several pages of this project (`components/shared/`) vs used by one page or section (beside it) | feature components     |
+| **Design System / Shared / Page Component** | The same in every project (`components/ui/`) vs used on several pages of this project (`components/shared/`) vs used by one page or section (beside it) |                        |
 
 ---
 

package/docs/templates.mdx

@@ -8,14 +8,13 @@ import eslintTypescript from "!!raw-loader!@site/static/templates/eslint/typescr
 import eslintReact from "!!raw-loader!@site/static/templates/eslint/react/eslint.config.mjs";
 import eslintNextjs from "!!raw-loader!@site/static/templates/eslint/nextjs/eslint.config.mjs";
 import eslintBase from "!!raw-loader!@site/static/templates/eslint/base/eslint.config.mjs";
-import prettier from "!!raw-loader!@site/static/templates/prettier.config.js";
+import prettier from "!!raw-loader!@site/static/templates/prettier.config.mjs";
 import stylelintCss from "!!raw-loader!@site/static/templates/stylelint/css/stylelint.config.mjs";
 import stylelintScss from "!!raw-loader!@site/static/templates/stylelint/scss/stylelint.config.mjs";
 import globalsCss from "!!raw-loader!@site/static/templates/globals.css";
 import editorconfig from "!!raw-loader!@site/static/templates/.editorconfig";
 import nvmrc from "!!raw-loader!@site/static/templates/.nvmrc";
 import envrc from "!!raw-loader!@site/static/templates/.envrc";
-import commitlint from "!!raw-loader!@site/static/templates/.commitlintrc.json";
 import skillLint from "!!raw-loader!@site/static/templates/skills/lint.md";
 import skillLintFix from "!!raw-loader!@site/static/templates/skills/lintFix.md";
 import skillFormat from "!!raw-loader!@site/static/templates/skills/format.md";
@@ -25,8 +24,8 @@ import skillSecurityAudit from "!!raw-loader!@site/static/templates/skills/secur
 import skillTypescript from "!!raw-loader!@site/static/templates/skills/typescript.md";
 import skillTest from "!!raw-loader!@site/static/templates/skills/test.md";
 import docsSitePackage from "!!raw-loader!@site/static/templates/docsSite/package.json.txt";
-import docsSiteConfig from "!!raw-loader!@site/static/templates/docsSite/docusaurus.config.ts";
-import docsSiteSidebars from "!!raw-loader!@site/static/templates/docsSite/sidebars.ts";
+import docsSiteConfig from "!!raw-loader!@site/static/templates/docsSite/docusaurus.config.mjs";
+import docsSiteSidebars from "!!raw-loader!@site/static/templates/docsSite/sidebars.mjs";
 import docsSiteTsconfig from "!!raw-loader!@site/static/templates/docsSite/tsconfig.json";
 import docsSiteWorkspace from "!!raw-loader!@site/static/templates/docsSite/pnpm-workspace.yaml";
 import docsSiteCss from "!!raw-loader!@site/static/templates/docsSite/src/css/custom.css";
@@ -34,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 huskyHook from "!!raw-loader!@site/static/templates/husky/commit-msg";
 import huskyPreCommit from "!!raw-loader!@site/static/templates/husky/pre-commit";
 
 # Templates
@@ -43,6 +41,8 @@ Ready-made files to copy into a project. Every config on this page is the exact
 
 Each file is also served as a plain file, so a person or an AI agent can fetch it directly instead of copying from this page.
 
+**Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. It works in both, so every project looks the same. A tool that cannot read `.mjs` keeps its own format.
+
 | File                                             | Copy to                                    | Plain file                                                                                                    |
 | ------------------------------------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
 | [AGENTS.md](#agents)                             | `AGENTS.md` in the project root            | [`/templates/AGENTS.md`](pathname:///templates/AGENTS.md)                                                     |
@@ -50,16 +50,15 @@ Each file is also served as a plain file, so a person or an AI agent can fetch i
 | [ESLint — React + TypeScript](#eslintreact)      | `eslint.config.mjs` in the project root    | [`/templates/eslint/react/eslint.config.mjs`](pathname:///templates/eslint/react/eslint.config.mjs)           |
 | [ESLint — Next.js](#eslintnextjs)                | `eslint.config.mjs` in the project root    | [`/templates/eslint/nextjs/eslint.config.mjs`](pathname:///templates/eslint/nextjs/eslint.config.mjs)         |
 | [ESLint — JavaScript / Node.js](#eslintbase)     | `eslint.config.mjs` in the project root    | [`/templates/eslint/base/eslint.config.mjs`](pathname:///templates/eslint/base/eslint.config.mjs)             |
-| [Prettier](#prettier)                            | `prettier.config.js` in the project root   | [`/templates/prettier.config.js`](pathname:///templates/prettier.config.js)                                   |
+| [Prettier](#prettier)                            | `prettier.config.mjs` in the project root  | [`/templates/prettier.config.mjs`](pathname:///templates/prettier.config.mjs)                                 |
 | [Stylelint — CSS and CSS Modules](#stylelintcss) | `stylelint.config.mjs` in the project root | [`/templates/stylelint/css/stylelint.config.mjs`](pathname:///templates/stylelint/css/stylelint.config.mjs)   |
 | [Stylelint — SCSS](#stylelintscss)               | `stylelint.config.mjs` in the project root | [`/templates/stylelint/scss/stylelint.config.mjs`](pathname:///templates/stylelint/scss/stylelint.config.mjs) |
 | [Global styles and colour palette](#globalscss)  | `app/globals.css`                          | [`/templates/globals.css`](pathname:///templates/globals.css)                                                 |
 | [EditorConfig](#editorconfig)                    | `.editorconfig` in the project root        | [`/templates/.editorconfig`](pathname:///templates/.editorconfig)                                             |
 | [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)                                                           |
-| [Commitlint](#commitlint)                        | `.commitlintrc.json` in the project root   | [`/templates/.commitlintrc.json`](pathname:///templates/.commitlintrc.json)                                   |
 | [Agent skills](#skills)                          | `.agents/skills/` and `.claude/commands/`  | Eight files — see [below](#skills)                                                                            |
-| [Husky commit hook](#husky)                      | `.husky/commit-msg`                        | [`/templates/husky/commit-msg`](pathname:///templates/husky/commit-msg)                                       |
+| [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)                                                              |
@@ -128,11 +127,11 @@ For plain JavaScript and Node.js projects.
 
 ## Prettier {#prettier}
 
-**Copy to:** `prettier.config.js` in the project root
+**Copy to:** `prettier.config.mjs` in the project root
 
 See the [Prettier page](/Standards/prettier).
 
-<CodeBlock language="js" title="prettier.config.js">
+<CodeBlock language="js" title="prettier.config.mjs">
   {prettier}
 </CodeBlock>
 
@@ -210,18 +209,6 @@ Run `direnv allow` after adding it. See [direnv + nvm](/Standards/direnv).
 
 ---
 
-## Commitlint {#commitlint}
-
-**Copy to:** `.commitlintrc.json` in the project root
-
-See [Conventional Commits](/Standards/conventional-commits).
-
-<CodeBlock language="json" title=".commitlintrc.json">
-  {commitlint}
-</CodeBlock>
-
----
-
 ## Agent skills {#skills}
 
 **Copy to:** `.agents/skills/` in the project root, and again to `.claude/commands/` so Claude Code picks them up as slash commands.
@@ -305,21 +292,11 @@ Runs the test suite; reports failures grouped by cause, tests that never ran, an
 
 ---
 
-## Husky commit hook {#husky}
-
-**Copy to:** `.husky/commit-msg` in the project root
-
-Refuses a commit whose message does not follow [Conventional Commits](/Standards/conventional-commits#enforcing-commit-messages). Plain file: [`/templates/husky/commit-msg`](pathname:///templates/husky/commit-msg)
-
-<CodeBlock language="text" title=".husky/commit-msg">
-  {huskyHook}
-</CodeBlock>
-
-### Lint before commit {#husky-pre-commit}
+## Lint before commit {#husky-pre-commit}
 
 **Copy to:** `.husky/pre-commit` in the project root
 
-Refuses a commit while `pnpm lint` reports errors. Plain file: [`/templates/husky/pre-commit`](pathname:///templates/husky/pre-commit)
+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}
@@ -336,8 +313,8 @@ The Docusaurus viewer that shows the project's `docs/` folder at `/docs`. Copy e
 | File                     | Plain file                                                                                                                            |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `package.json`           | [`/templates/docsSite/package.json.txt`](pathname:///templates/docsSite/package.json.txt) — rename to `package.json`                  |
-| `docusaurus.config.ts`   | [`/templates/docsSite/docusaurus.config.ts`](pathname:///templates/docsSite/docusaurus.config.ts)                                     |
-| `sidebars.ts`            | [`/templates/docsSite/sidebars.ts`](pathname:///templates/docsSite/sidebars.ts)                                                       |
+| `docusaurus.config.mjs`  | [`/templates/docsSite/docusaurus.config.mjs`](pathname:///templates/docsSite/docusaurus.config.mjs)                                   |
+| `sidebars.mjs`           | [`/templates/docsSite/sidebars.mjs`](pathname:///templates/docsSite/sidebars.mjs)                                                     |
 | `tsconfig.json`          | [`/templates/docsSite/tsconfig.json`](pathname:///templates/docsSite/tsconfig.json)                                                   |
 | `pnpm-workspace.yaml`    | [`/templates/docsSite/pnpm-workspace.yaml`](pathname:///templates/docsSite/pnpm-workspace.yaml)                                       |
 | `src/css/custom.css`     | [`/templates/docsSite/src/css/custom.css`](pathname:///templates/docsSite/src/css/custom.css)                                         |
@@ -347,7 +324,7 @@ The Docusaurus viewer that shows the project's `docs/` folder at `/docs`. Copy e
 
 Set `PROJECT_NAME` at the top of the config:
 
-<CodeBlock language="ts" title="docusaurus.config.ts">
+<CodeBlock language="js" title="docusaurus.config.mjs">
   {docsSiteConfig}
 </CodeBlock>
 
@@ -355,7 +332,7 @@ Set `PROJECT_NAME` at the top of the config:
   {docsSitePackage}
 </CodeBlock>
 
-<CodeBlock language="ts" title="sidebars.ts">
+<CodeBlock language="js" title="sidebars.mjs">
   {docsSiteSidebars}
 </CodeBlock>
 

package/docs/version-history.md

@@ -31,11 +31,134 @@ sidebar_label: "Version History"
 
 Anyone changing the standards adds a version, in the same pull request as the change:
 
-- **One version per change that reaches `main`**, numbered one higher than the last. Whole numbers only.
+- **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.
+
+---
+
+## Version 3
+
+**Released:** 2026-10-17 · **Updates from:** version 2
+
+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.
+
+### 1. Project workflow is no longer part of the standards
+
+**Why:** The standards are a base for code. How a project runs its work — branch names, commit messages, Pull Requests, merging, releases, and whether AI agents may commit — is each project's own decision, and every project makes it differently.
+
+**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.
+- 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).
+
+**How to check:** `AGENTS.md` has a Project workflow section, and every rule in it is written up in the project's docs.
+
+### 2. `lib`, `ref` and `repo` are dictionary words, and `library/` is `lib/`
+
+**Why:** They are the words developers use. `lib/` is the name Next.js and shadcn/ui use too.
+
+**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).
+- 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.
+
+**How to check:** There is no `library/` folder, `grep -rn "@/library" --exclude-dir=node_modules .` finds nothing, and `pnpm lint` passes.
+
+### 3. utils, services and lib are defined
+
+**Why:** It wasn't clear which functions go in `utils/`, `services/` or `lib/`. See [utils, services and lib](/Structure/folder-structure#utils-services-and-lib).
+
+**What to do:** Check each function in those three folders against the definitions, and move any that are in the wrong one. The common one: a function in `utils/` that calls a database or an API belongs in `services/` or `lib/`. Shared constants and types live in `lib/constants/` and `lib/types/`; a component's own types stay in its `types.ts`. Move any root-level `constants/` or `types/` folder into `lib/`.
+
+**How to check:** Nothing in `utils/` imports from `services/`, `lib/integrations/` or a database client, and there is no root-level `constants/` or `types/` folder.
+
+### 4. The Ontology only holds code words
+
+**Why:** Project-management words mean different things in different projects. Launchpad's "project" is a product made of several MVPs, and its Pull Requests go through `feature → dev → uat → main`.
+
+**What to do:** The code [Ontology](/ontology) no longer defines `project`, `repository`, `branch`, `commit`, `pull_request`, `pull_request_review` or `production`, and `human`, `developer` and `agent` no longer say who may commit. If the project uses those words, define them in its own `docs/product/ontology.md`, the way the project actually works.
+
+**How to check:** The project's ontology defines every project-management word it uses.
+
+### 5. Every config file is `.mjs`
+
+**Why:** `.mjs` works in TypeScript and JavaScript projects alike, so every project looks the same.
+
+**What to do:**
+
+- Rename each config file that is `.js`, `.ts` or `.mts` to `.mjs`, even in a TypeScript project, wherever the tool can read `.mjs`: `prettier.config.mjs`, `next.config.mjs`, `eslint.config.mjs`, `docsSite/docusaurus.config.mjs`, `docsSite/sidebars.mjs` and so on. Use `git mv`. Never convert a config to `.ts` or `.mts`.
+- Remove any TypeScript-only syntax as you go. A type annotation becomes a JSDoc comment: `const config: NextConfig = {` becomes `/** @type {import("next").NextConfig} */ const config = {`. Copy the [`docsSite/` templates](/templates#docs-site), which are already `.mjs`.
+- Update anything that names the old file, such as `sidebarPath: './sidebars.mjs'` in the docs site config.
+
+**How to check:** `ls *.config.* docsSite/*.config.* docsSite/sidebars.*` shows only `.mjs` files, and `pnpm lint`, `pnpm format:check`, the build and `pnpm docs:build` still run.
+
+### 6. Prettier: 70-character lines and tabs
+
+**Why:** A lot of code is read and reviewed on a phone, where short lines fit the screen. Tabs let each person see the indent at the width they like.
+
+**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.
+- 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.
+
+### 7. When a name clashes, rename our own thing first
+
+**Why:** A third-party name is the name everyone knows it by, and a clash usually means our own name is too vague. Renaming an import for taste makes the code harder to search and to match against the package's docs.
+
+**What to do:** Search for renamed imports: `grep -rn "import {[^}]* as " --include=*.ts --include=*.tsx --exclude-dir=node_modules .`. For each one:
+
+- **If nothing in the file clashes with the original name**, undo the rename and use the original name.
+- **If our own thing clashes**, rename ours to a more specific full-word name, with the editor's Rename Symbol or the [rename script](/Guides/migrating#renaming-from-the-command-line). Then undo the import rename. For example, our `createClient` becomes `createProjectDatabaseClient`, and Supabase's `createClient` keeps its name.
+- **If both names are third-party, or ours is fixed by a framework** (such as a Next.js route's `GET`), keep the import renamed, as the owner plus the original name, never shortened: `Link as LucideLinkIcon`.
+
+See [When a name clashes](/Standards/human-readable-names#when-a-name-clashes).
+
+**How to check:** Every renamed import that is left clashes with another third-party name or a framework-fixed name, and starts with its owner's name.
+
+### 8. Name a type after what it is, not the job it does
+
+**Why:** A type named after its role in one function, such as `StartAgentRunDependenciesType`, is a second name for what is really part of that function's props.
+
+**What to do:** Find types used for only one field of one `Props` type. Move each one inside that `Props` and delete the separate type. Where the object is built somewhere else, remove its type annotation: TypeScript checks it against the `Props` when it is passed in. See [Name a type after what it is](/Standards/readable-code#name-a-type-after-what-it-is-not-the-job-it-does).
+
+**How to check:** No type is used only as the type of one field of one `Props`.
+
+### 9. "go" means carry on
+
+**Why:** People often send just "go" to nudge an agent along, for example when their connection drops and the agent looks stuck. An agent must never read it as permission to commit.
+
+**What to do:** Copy the line that starts **"go" means carry on** from the top of the [`AGENTS.md` template](/templates#agents) into the top of the project's `AGENTS.md`.
+
+**How to check:** The project's `AGENTS.md` has the line near the top.
+
+### 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.
+
+**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).
+
+**How to check:** `docs/development/coding-standards.md` has an "Unfinished changes" section.
+
+### 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 [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).
 
 ---
 
@@ -73,14 +196,17 @@ Anyone changing the standards adds a version, in the same pull request as the ch
 **What to do:**
 
 - Rename the folders with `git mv`: `documentation/` → `docs/`, `documentationSite/` → `docsSite/`.
+- **If both `docsSite/` and `documentationSite/` exist**, merge them into `docsSite/`: move each tracked file from `documentationSite/` with `git mv`, keeping whichever copy is newer, then delete `documentationSite/`. Ask the person before deleting a file that exists in only one of them.
 - Rename `docs/overview/writing-documentation.md` → `docs/overview/writing-docs.md`, and fix every link to it.
 - Rename the environment variable `DOCUMENTATION_URL` → `DOCS_URL` in `next.config.mjs`, `.env.local`, `.env.example` and the hosting provider's settings.
 - Rename the route `/documentation` → `/docs`. Copy the new rewrite from the [`next.config.mjs` template](/templates#docs-route).
-- In `docsSite/docusaurus.config.ts`, set `baseUrl: '/docs/'` and `path: '../docs'`. Copy the [`docsSite/` template](/templates#docs-site) if unsure.
+- **Re-copy `docsSite/docusaurus.config.ts`** from the [`docsSite/` template](/templates#docs-site), keeping the project's name and theme. Version 2 changed it: `baseUrl: '/docs/'`, `path: '../docs'`, full-word variable names (`rest` → `remainingArguments`, `doc` → `page`), and `static/img` → `static/images`. Rename the project's `docsSite/static/img/` to `static/images/` to match.
 - Rename the scripts in `package.json`: `documentation:install` → `docs:install`, `documentation:dev` → `docs:dev`, `documentation:build` → `docs:build`.
+- If the docs site's generated folders were ever committed, stop tracking them: `git rm -r --cached docsSite/.docusaurus docsSite/build`. They are in the [`docsSite/` template's](/templates#docs-site) `.gitignore`.
 - Update every mention in `AGENTS.md`, `README.md` and the docs themselves.
+- **Update every ignore list** that names the old folders: ESLint, Prettier, `tsconfig.json`, Vitest or Jest, and `.gitignore`. A leftover docs site with its own `node_modules` makes test runners and linters run its files too.
 
-**How to check:** `grep -rn "documentation/\|documentationSite\|DOCUMENTATION_URL\|documentation:" --exclude-dir=node_modules .` finds nothing. Normal sentences that say "documentation" are fine.
+**How to check:** `grep -rn "documentation/\|'../documentation'\|documentationSite\|DOCUMENTATION_URL\|documentation:" --exclude-dir=node_modules .` finds nothing. Normal sentences that say "documentation" are fine.
 
 ### 4. `props` is a dictionary word: prop types end in `Props`
 
@@ -88,11 +214,12 @@ Anyone changing the standards adds a version, in the same pull request as the ch
 
 **What to do:**
 
-- Rename every type ending in `Properties` to end in `Props`: `ButtonProperties` → `ButtonProps`. Use the editor's Rename Symbol (F2), not find-and-replace.
+- Rename every type ending in `Properties` to end in `Props`: `ButtonProperties` → `ButtonProps`. Never use find-and-replace. Use the editor's Rename Symbol (F2) or, for an agent working from the command line, the rename script in version 3 and later of the package: `node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>`. Both use TypeScript's own rename, so they change every use and nothing else.
 - Rename variables and parameters called `properties` to `props`, including spreads: `...buttonProperties` → `...buttonProps`.
-- Copy the new [ESLint config](/Standards/eslint). Two things changed in it:
+- **If the project already uses the standard ESLint config**, copy the new [ESLint config](/Standards/eslint). It needs ESLint 10.4 or later. Two things changed in it:
   - The type-name rule is now `(Props|Type)$`.
   - `unicorn/name-replacements` now has `replacements: { docs: false, props: false, utils: false }`.
+- **If the project never had the standard ESLint config**, do only the renames in this change. Switching the config on can find hundreds of problems, so do it separately with [Migrating an Existing Project](/Guides/migrating), one stage per Pull Request, and record it as unfinished: see [Finishing a change later](/Guides/setup#finishing-a-change-later).
 
 **How to check:** `grep -rn "Properties\b" --include=*.ts --include=*.tsx --exclude-dir=node_modules .` finds nothing of ours, and `pnpm lint` passes.
 
@@ -179,7 +306,7 @@ Anyone changing the standards adds a version, in the same pull request as the ch
 
 **Why:** Strict no commit is right for most projects, but a tool built to ship code with AI, such as Launchpad, needs agents to commit.
 
-**What to do:** This is standard 22 in the list from change 2. If the person kept it, keep the template's "NEVER COMMIT CODE" lines for strict no commit. Otherwise, replace them with the project's own rule, saying exactly which agents may commit, push and open Pull Requests, and when. See [A project can choose otherwise](/Standards/agent-specs#a-project-can-choose-otherwise).
+**What to do:** This is standard 22 in the list from change 2. If the person kept it, keep the template's "NEVER COMMIT CODE" lines for strict no commit. Otherwise, replace them with the project's own rule, saying exactly which agents may commit, push and open Pull Requests, and when. See [A project can choose otherwise](/Standards/agent-specs#project-workflow).
 
 **How to check:** The top of `AGENTS.md` states the project's commit rule.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@activatus/code-standards",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "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",
@@ -9,6 +9,7 @@
   "homepage": "https://activatus-code-standards.vercel.app",
   "files": [
     "docs",
+    "scripts",
     "static/templates",
     "README.md"
   ],
@@ -27,6 +28,7 @@
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "pagefind": "^1.3.0",
+    "prettier": "^3.9.10",
     "prism-react-renderer": "^2.3.0",
     "raw-loader": "^4.0.2",
     "react": "^18.3.1",
@@ -54,6 +56,8 @@
     "build": "docusaurus build",
     "serve": "docusaurus serve",
     "clear": "docusaurus clear",
-    "typecheck": "tsc"
+    "typecheck": "tsc",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   }
 }