@activatus/code-standards 0.0.0-stage → 3.0.0

package/README.md

@@ -1,3 +1,200 @@
-# Temporary Holding Version
+# 🦘 Activatus Code Standards
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**One way of doing things, written down, so nobody has to guess.**
+
+This is the rulebook for how we write code at Activatus. It's a docs site, a pile of copy-paste config files, and a set of lint rules that'll dob you in before your reviewer has to.
+
+The whole point: you should be able to wander into any Activatus project at 4pm on a Friday and know exactly where everything lives, like walking into a mate's shed and finding the 10mm socket first go.
+
+---
+
+## 🤔 Why this exists
+
+Every team says they've got standards. Most of them live in one bloke's head and a Slack thread from 2022.
+
+Ours live here. If it's not in this repo, it's not a standard, it's an opinion.
+
+- 🧠 **Readable by humans.** If a new starter can't follow a file, the file's wrong, not the new starter.
+- 🤖 **Readable by AI.** Claude Code and friends follow the same rules we do. No special treatment.
+- 🚨 **Enforced by the linter where we can.** Rules that rely on everyone remembering are rules that get forgotten.
+
+---
+
+## 📦 Using it in a project
+
+The standards ship as an npm package, published on npm (npmjs.com) and installed with pnpm, so an AI agent reads the exact version a project uses, straight from `node_modules`:
+
+```bash
+pnpm add -D @activatus/code-standards
+```
+
+Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_modules/@activatus/code-standards/docs/Guides/setup.md`."** It prints a numbered list of the standards, you say which ones you don't want, and it sets up the rest. You never touch the terminal.
+
+The package version is the standards version: `2.0.0` is version 2.
+
+> 🔢 **Updating a project to newer standards?** Run `pnpm update @activatus/code-standards --latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
+
+---
+
+## 🚀 Get it running
+
+You'll need **Node 20+** and **pnpm**.
+
+```bash
+pnpm install
+pnpm start
+pnpm serve
+```
+
+That fires up the site locally with hot reload. Easy as.
+
+The live site is at **[activatus-code-standards.vercel.app](https://activatus-code-standards.vercel.app)**. That's the link to share.
+
+| Command          | What it does                                 |
+| ---------------- | -------------------------------------------- |
+| `pnpm start`     | 🔥 Dev server with hot reload                |
+| `pnpm build`     | 📦 Builds the static site into `build/`      |
+| `pnpm serve`     | 👀 Serves the built site so you can check it |
+| `pnpm typecheck` | 🔍 Runs TypeScript over the site config      |
+| `pnpm format`    | ✨ Formats everything with Prettier          |
+
+> 🔎 **Search only works on the built site.** Run `pnpm build` then `pnpm serve` if you want to test it. It won't show up in `pnpm start`, so don't go thinking you've broken it.
+
+> 🐌 **Install carking it on a slow connection?** One of the packages is a big unit. Run `pnpm install --fetch-timeout 600000` and go put the kettle on.
+
+---
+
+## 📚 What's in the box
+
+| Section                                                                                                 | What you'll find                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 📋 **Templates**                                                                                        | Ready-to-copy `AGENTS.md`, ESLint, Prettier, Stylelint and friends                                                                                    |
+| 📖 **Ontology**                                                                                         | The code words we use and what each one means                                                                                                         |
+| 🔢 **[Version History](https://activatus-code-standards.vercel.app/version-history)**                   | What changed in each version, and what a project has to do about it. Updating a project? Read only the versions newer than the one in its `AGENTS.md` |
+| 🧭 **Guides**                                                                                           | Setting up a new project, dragging an old one up to scratch, and how design becomes code                                                              |
+| 📏 **Standards**                                                                                        | Readable code, linting, formatting, styling, commits, the tech stack and AI agent rules                                                               |
+| 🏗️ **Structure**                                                                                        | Folders, components, naming, imports and API routes                                                                                                   |
+| 🧩 **[Design System Components](https://activatus-code-standards.vercel.app/design-system-components)** | Every standard component and its props, so each project builds them the same way                                                                      |
+
+---
+
+## ⚡ The rules, at pub-yarn speed
+
+The full detail's on the site. This is the version you'd tell someone over a schooner.
+
+### ✍️ Writing code
+
+- 📄 **No file over 300 lines.** If it's longer, it's doing two jobs. Split it. (Test files get a leave pass.)
+- 🗣️ **Every name is real English words.** Variables, props, form fields, types, files, folders, the lot. `button`, not `btn`. We're not paying by the letter. The one exception: names someone else owns, like Linear's `id` or Node's `cwd` option.
+- 🔒 **Always `const`.** Need `let`? Fine, but leave a comment saying why, or the linter knocks it back.
+- 🏹 **Arrow functions everywhere.** `const Button = () => {}`. The word `function` is clutter, so we don't use it.
+- 🔄 **No circular imports. Ever.** If two files import each other, pull the shared bit into a third file.
+- 🎯 **A function does one thing.** If you need the word "and" to describe it, it's two functions.
+- 🧪 **Every function and component gets a test file.** One test file, one thing tested. No test, not finished.
+- 🚫 **Functions, never classes.** Not even a little one.
+- 📦 **One parameter per function.** Need more? Pass an object, so the call explains itself.
+- 🚪 **Return early.** Deal with the dodgy cases up top instead of nesting four `if`s deep like a set of Russian dolls.
+- 🔢 **No magic numbers.** `MAXIMUM_RETRY_ATTEMPTS`, not a random `3` sitting there like it owns the place.
+- 🏷️ **Type names end in `Props` or `Type`.** So you can tell what you're looking at.
+- 💬 **Comments explain why, not what.** And no commented-out code. Git remembers, you don't have to.
+
+### 🎨 Styling
+
+- 🌬️ **Tailwind for everything.**
+- 📐 **Flexbox first.** Split layouts into child components. Only use CSS grid if someone specifically asks for it.
+- 🎨 **Colours come from the global palette. Full stop.** No hard-coded hex, no one-off values. If the colour's not in the palette, it's not in the build.
+
+### 📖 Docs
+
+- 📝 **Docs are plain Markdown in `docs/`, and every file is a Decision Doc.** Same folders in every project. Agents read the files; humans browse them at `/docs`.
+- 🔒 **`/docs` only exists when `DOCS_URL` is set.** It's never set in production, so the docs never leak onto a live site.
+- ✅ **Not finished until the docs are updated.** Change how something works, fix the doc in the same change.
+
+### 🤖 Workflow is the project's call
+
+- 🧭 **Branches, commit messages, Pull Requests and whether AI agents may commit are up to each project.** Every team runs its work differently, so it goes in the project's own `AGENTS.md` and docs, not here. These standards are the base for the code itself.
+
+### 📦 Third-party code
+
+- 📦 **Third-party code is exempt.** Anything in `node_modules/` or `vendor/` isn't ours. Don't lint it, don't tidy it, leave it be.
+
+### 🗂️ Structure
+
+- 🐫 **Code files are camelCase.** Components are PascalCase (`Button.tsx`) inside a camelCase folder (`button/`).
+- 🔗 **If it becomes a URL, it's kebab-case.** Route folders and doc files (`background-jobs.md`). CSS variables too.
+- 🧰 **Reusable functions live in `utils/`.** Global, section or component level, one folder per function, with an `index.ts` so imports stay tidy.
+- 📍 **Components live where they're used.** Design System Components in `components/ui/`, anything used on more than one page in `components/shared/`, and one-page components in that page's own `components/` folder. No feature folders.
+- 🧱 **Components follow the same order every time.** Imports, component, variables, state, effects, render. No inline functions in the render.
+- 🔀 **Server and client code live in separate files.** The server one wraps the client one.
+
+---
+
+## 📋 Just want the files?
+
+Fair enough. Head to the **Templates** page on the site, or grab them straight from [`static/templates/`](static/templates):
+
+```text
+static/templates/
+├── AGENTS.md               # 🤖 Context file for AI agents
+├── skills/                 # 🛠️ Eight ready-made agent skills
+├── docs/                   # 📖 The full set of Decision Doc templates, one per standard folder
+├── docsSite/               # 🌐 Docusaurus viewer that shows docs/ at /docs
+├── eslint/                 # 🚨 Four flavours: base, typescript, react, nextjs
+├── stylelint/              # 💅 CSS and SCSS
+├── 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
+```
+
+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.
+
+---
+
+## 🗺️ Finding your way around this repo
+
+```text
+.
+├── docs/                   # 📝 Every page on the site, as Markdown
+│   ├── Guides/
+│   ├── Standards/
+│   └── Structure/
+├── static/
+│   ├── images/             # 🖼️ Logo and favicon
+│   └── templates/          # 📋 The copy-paste files
+├── src/css/custom.css      # 🎨 Site theme overrides
+├── docusaurus.config.mjs   # ⚙️ Site config
+└── sidebars.mjs            # 📑 Sidebar (builds itself from docs/)
+```
+
+Built with [Docusaurus](https://docusaurus.io). The sidebar generates itself from the folders, so there's no menu file to forget about.
+
+---
+
+## ✏️ Changing a standard
+
+Reckon a rule's wrong, or there's one missing? Good. Standards that never change are standards nobody reads.
+
+1. 🌿 **Branch off `main`**, named after the ticket (`ACT-14-update-eslint-page`), or `type/short-description` if there's no ticket (`docs/update-eslint-page`).
+2. 📝 **Edit or add a Markdown file in `docs/`.** Name it in kebab-case (`naming-conventions.md`, not `namingConventions.md`), because the file name becomes the page's URL. Yes, we follow our own rules here.
+3. 📋 **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart.
+4. 🔢 **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump the major version in `package.json` to match (version 3 is `3.0.0`), and publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.
+5. 🔨 **Run `pnpm build`.** It fails on broken links, so you'll know quick smart if you've stuffed one.
+6. 🚀 **Open a pull request** and say why the change makes life better.
+
+A good rule of thumb: if you can't explain the rule to a new starter in one sentence, it's not ready.
+
+---
+
+## 🚧 Before this goes live
+
+- [ ] 🖼️ **Swap in the real logo.** `static/images/logo.svg` is a stand-in.
+
+---
+
+## 💚 The short version
+
+Write code the next person can read. Test it. Keep it small. Follow the pattern.
+
+Do that and we'll all get home on time.

package/docs/Guides/_category_.json

@@ -0,0 +1,4 @@
+{
+	"label": "Guides",
+	"position": 5
+}

package/docs/Guides/component-library-workflow.md

@@ -0,0 +1,182 @@
+---
+sidebar_position: 1
+sidebar_label: "Workflow"
+---
+
+# Component & Design-to-Code Workflow
+
+How components get from design into a project: where they come from, what we are allowed to change, and how AI automation fits without producing drift.
+
+:::tip[The one-line summary]
+
+**Every project builds on the same shadcn components. How a component works stays identical everywhere — only how it looks changes from project to project.**
+
+:::
+
+## How it fits together
+
+| Layer                 | What it is                                                                                         | Owned by      |
+| --------------------- | -------------------------------------------------------------------------------------------------- | ------------- |
+| **Claude Design**     | Where designs are produced, using shadcn components and the project's colour palette.              | Design        |
+| **shadcn/ui**         | The source of every base component. Added to a project with the shadcn CLI.                        | —             |
+| **`components/ui/`**  | The project's own copy of those components, converted to our standards and styled for the project. | Dev           |
+| **CMS components**    | Wrappers that connect `components/ui/` to a CMS such as Storyblok.                                 | Dev           |
+| **CMS project space** | Supplies content and data to the project.                                                          | Dev + Content |
+
+## Each project has its own components
+
+**There is no shared component library.** Each project adds the shadcn components it needs straight into its own `components/ui/` folder.
+
+Our projects are different products, so a shared library is not worth its upkeep yet. We will build one later — see [Future-proofing](#future-proofing). What keeps the projects consistent until then is one rule.
+
+## Same component, different paint
+
+**The way a component works is identical in every project. Only the way it looks changes.**
+
+|                  | Rule             | Examples                                                                     |
+| ---------------- | ---------------- | ---------------------------------------------------------------------------- |
+| **How it works** | ❌ Do not change | Props and their names, variants, behaviour, keyboard handling, accessibility |
+| **How it looks** | ✅ Change freely | Colours, spacing, corner radius, typography, shadows                         |
+
+A `Button` in one Activatus project takes the same props and behaves the same way as a `Button` in any other. A developer or an AI agent who knows one project's components knows them all.
+
+- **Keep shadcn's props exactly as they ship.** Do not rename, remove or repurpose a prop.
+- **Style through the [global colour palette](/Standards/styling#-colours-always-come-from-global-variables)** and Tailwind classes. Per-project branding is a palette change, not a component rewrite.
+- **Need different behaviour?** Build a new component that wraps the base one. Do not change the base component.
+
+Keeping the components identical is also what makes a shared library possible later — see [Future-proofing](#future-proofing).
+
+## Adding a shadcn component
+
+**shadcn is where a component starts. What lives in `components/ui/` is ours.**
+
+The shadcn CLI copies source code into the project. From that moment it is **our code, not third-party code**: we own it, and it follows every standard. It never goes in `vendor/`.
+
+The CLI writes files in shadcn's format, which breaks our standards — kebab-case file names, many components in one file, no folder, no types file and no tests. **Convert them in the same change that adds them.** Never leave raw CLI output in the project.
+
+### Before and after
+
+```text
+❌ What the shadcn CLI writes
+components/ui/
+├── button.tsx
+└── dropdown-menu.tsx              # 15 components in one file
+
+✅ What we keep
+components/ui/
+├── button/
+│   ├── Button.tsx
+│   ├── Button.test.tsx
+│   ├── types.ts
+│   └── index.ts
+└── dropdownMenu/
+    ├── DropdownMenu.tsx
+    ├── DropdownMenu.test.tsx
+    ├── types.ts
+    ├── index.ts
+    ├── dropdownMenuTrigger/
+    ├── dropdownMenuContent/
+    └── dropdownMenuItem/
+```
+
+### Converting a component
+
+1. **Add it** with the shadcn CLI.
+2. **Keep only the parts the project uses.** A shadcn file often exports many components. Delete the ones that are not used — if one is needed later, add it again and convert it the same way.
+3. **Give each component its own folder and file**: a camelCase folder with a PascalCase file (`button/Button.tsx`). One component per file — sub-components get [their own folders](/Structure/component-organization#nested-components) inside the parent.
+4. **Add the standard files** to each folder: `types.ts`, `index.ts` and a test file. See [Component Organization](/Structure/component-organization).
+5. **Apply the code standards**: named exports, type names ending in `Props` or `Type`, full English names for our own variables.
+6. **Leave the props and behaviour alone.** Converting changes the file layout and the styling, never [how the component works](#same-component-different-paint).
+7. **Use the global colour palette.** Replace shadcn's colour classes with colours from [the palette](/Standards/styling#-colours-always-come-from-global-variables).
+8. **Move shared helpers to `utils/`.** shadcn's `cn` helper lives in the [global `utils/` folder](/Structure/folder-structure#-utils), not in `lib/utilities.ts`.
+9. **Run `pnpm lint` and `pnpm test`.** The converted component must pass both.
+
+### What is still third-party
+
+The packages a shadcn component imports — Radix UI and the like — stay in `node_modules/` and are [exempt from the standards](/Standards/eslint#third-party-code-is-exempt). Only the component source that the CLI copies into the project becomes ours.
+
+## The design → code loop
+
+1. **Design in Claude Design** using shadcn components and the project's palette.
+2. **A new component is needed** → [look before you build](#1-look-before-you-build), then add it from shadcn and [convert it](#converting-a-component).
+3. **A new look is needed** → change the palette or the component's classes. The props stay as they are.
+4. **Something shadcn does not provide** → build it in `components/ui/` from existing components, following [Component Organization](/Structure/component-organization).
+
+:::caution[Design and code are decoupled]
+
+A design change does **not** automatically change the code. Component changes are made deliberately, in a reviewed change.
+
+:::
+
+## AI automation: governed, not soup
+
+Soup comes from letting AI generate components freely for every screen. We prevent it by making `components/ui/` a **hard constraint** and pointing automation at composition.
+
+- **Base components** come from shadcn and are converted once. AI does not invent a new button, input or dialog.
+- **Page composition** is where AI does the heavy lifting: assembling pages from the components already in `components/ui/`.
+
+**Guardrails:** typed props, lint rules (no hard-coded colours, no inline styles) and tests. **Gap-loop:** when a component is missing, AI _flags it_ and adds it from shadcn, instead of inventing one.
+
+## Maintenance
+
+- **Foundation upgrades** (Tailwind, Radix, React) are done per project, and proven with the project's tests.
+- **Updating a shadcn component** means adding it again from shadcn and converting it again. Because the props were never changed, the update drops in.
+
+## Future-proofing
+
+**We know we are building the same components more than once.** Each project has its own copy today. One day those copies will be pulled out into a single shared repository that every project installs.
+
+That refactor is **planned, but not now**. Until then, two things stop each project from reinventing the same component differently, and keep the eventual refactor cheap.
+
+### 1. Look before you build
+
+Before building any component, check these in order and stop at the first match:
+
+| #   | Look in                                                   | If it is there                                                                                                                   |
+| --- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | The project's own `components/ui/`                        | Use it                                                                                                                           |
+| 2   | The [Design System Components](/design-system-components) | Build it to the listed variants and props                                                                                        |
+| 3   | Another Activatus project                                 | Copy the component's whole folder — code, types and tests — then restyle it                                                      |
+| 4   | shadcn                                                    | Add it and [convert it](#converting-a-component)                                                                                 |
+| 5   | Nowhere                                                   | Build it, and **add it to the [Design System Components](/design-system-components)** so the next project builds it the same way |
+
+**Copying a finished component from another Activatus project is encouraged.** Rebuilding one from memory is how two projects end up with two different buttons.
+
+### 2. Build every component to be lifted out
+
+A component in `components/ui/` must be able to move to another project — or to a shared library — by copying its folder and changing nothing but its styling.
+
+| Rule                                                                                                        | Why                                               |
+| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| **Everything comes in through props.** No fetching data, no reading global state                            | The component cannot depend on one project's data |
+| **No imports from the project's pages, shared components, services, stores or `app/` folder**               | Those do not exist in the next project            |
+| **It may import only** other `components/ui/` components, the global `utils/` folder and installed packages | These travel with it                              |
+| **No project names, client names or business rules inside it**                                              | A `Button` knows nothing about invoices           |
+| **Its types and tests live in its folder**                                                                  | They move when the folder moves                   |
+| **Its props match the [Design System Components](/design-system-components)**                               | Every project's copy is interchangeable           |
+
+Logic that belongs to one project goes in a **page or shared component** (in the page's `components/` folder, or `components/shared/`) that wraps the base component and passes it props. See [Where components live](/Structure/folder-structure#-where-components-live). The base component stays clean.
+
+```tsx
+// ✅ Good — the base component takes props; the page component knows about invoices
+// app/(billing)/components/invoiceTable/InvoiceTable.tsx
+<DataTable
+  rows={invoices}
+  columns={INVOICE_COLUMNS}
+  onRowSelect={handleInvoiceSelect}
+/>;
+
+// ❌ Bad — a base component that fetches invoices cannot be reused anywhere else
+// components/ui/dataTable/DataTable.tsx
+const invoices = await getInvoices();
+```
+
+### When the shared library gets built
+
+Not on a date — on a signal. It is time to build it when any of these becomes true:
+
+- The same bug has to be fixed in the same component in more than one project.
+- Keeping the projects' components in step is taking real time.
+- A new project would copy most of its `components/ui/` from an existing one.
+
+Because every project followed the two rules above, the refactor is then a matter of moving folders, not rewriting components.

package/docs/Guides/migrating.md

@@ -0,0 +1,161 @@
+---
+sidebar_position: 3
+---
+
+# Migrating an Existing Project
+
+Migrating an established codebase to the shared standards is best done in stages to keep PRs reviewable.
+
+**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.
+
+## Before you start: third-party code is exempt
+
+The standards apply to **code we write**, not to packages we pull in. Do not lint, reformat, rename or restructure third-party code — see [Third-party code is exempt](/Standards/eslint#third-party-code-is-exempt).
+
+- `node_modules/` is ignored automatically.
+- Third-party code copied into the repo belongs in a `vendor/` folder, which the configs ignore.
+- Add `vendor/` to `.prettierignore` too.
+- **shadcn components are not third-party.** They are our code: convert them to the standards rather than moving them to `vendor/`. See [Adding a shadcn component](/Guides/component-library-workflow#adding-a-shadcn-component).
+
+## Stage 1 — Prettier (formatting only)
+
+Formatting changes are safe to land in one big PR because they don't change behaviour.
+
+```bash
+pnpm add -D prettier prettier-plugin-tailwindcss
+```
+
+Add `prettier.config.mjs` — see the [Prettier page](/Standards/prettier) for the full file contents.
+
+Format everything at once:
+
+```bash
+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.
+
+Add a `.prettierignore` if you have generated files you don't want touched:
+
+```text
+dist/
+build/
+coverage/
+vendor/
+*.generated.ts
+```
+
+## Stage 2 — EditorConfig
+
+Add the `.editorconfig` file. No code changes needed — your editor will handle it on next save.
+
+## Stage 3 — ESLint
+
+Add the [standard config](/Standards/eslint) for your project type, then start in warn-only mode to see what you're dealing with. Add a block before `prettier`:
+
+```js
+export default [
+  // ...
+  {
+    rules: {
+      // temporarily downgrade errors to warnings during migration
+      "@typescript-eslint/no-explicit-any": "warn",
+      "unicorn/filename-case": "warn",
+      "unicorn/name-replacements": "warn",
+    },
+  },
+  prettier,
+];
+```
+
+Run `pnpm lint` and triage the output. Fix issues in thematic PRs (e.g. all `any` removals together). Once clean, remove the overrides.
+
+## Stage 4 — Names
+
+Renaming is the biggest job in most migrations, and the easiest place to get confused. Every name we write becomes [Human-Readable Names](/Standards/human-readable-names). Work through it in this order.
+
+### 1. Decide what stays
+
+Before renaming anything, sort the short names into three piles:
+
+| Pile                                                                                                                   | What to do                | Where to check                                                            |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
+| **A dictionary word** — `id`, `docs`, `app`, `url`, `api`                                                              | Leave it                  | [Dictionary](/Standards/human-readable-names#dictionary)                  |
+| **A third-party name** — React's `ref`, Next.js's `params`, shadcn/ui's `cn`, Linear's `pageInfo`, Node's `cwd` option | Leave it exactly as it is | [Third-party names](/Standards/human-readable-names#third-party-names)    |
+| **Our own shorthand** — `btn`, `lib/`, `helpers/`, `utilities/`                                                        | Rename it                 | The [Never / Always](/Standards/human-readable-names#never--always) table |
+
+**Not sure which pile?** Don't guess and don't rename it. Ask, and if it is a dictionary word, [add it to the dictionary](/Standards/human-readable-names#adding-a-word-to-the-dictionary) first. Everyone then makes the same call.
+
+### 2. The common renames
+
+These come up in nearly every project:
+
+| Before                                 | After                                        |
+| -------------------------------------- | -------------------------------------------- |
+| `utilities/`, `helpers/`, `helpers.ts` | `utils/`, or a file named after what it does |
+| `ButtonProperties`, `properties`       | `ButtonProps`, `props`                       |
+| `MAX_`, `MIN_`                         | `MAXIMUM_`, `MINIMUM_`                       |
+| `"sm" \| "md" \| "lg"`                 | `"small" \| "medium" \| "large"`             |
+| `auth`, `useAuth`                      | `authentication`, `useAuthentication`        |
+| `(e) =>`, `(i) =>`                     | `(event) =>`, `(index) =>`                   |
+
+`docs/`, `docsSite/`, `DOCS_URL` and `pnpm docs:dev` already follow the standard. Leave them.
+
+### 3. Rename in this order, one pull request each
+
+1. **Folders**, with `git mv` so the history follows the files. Fix the imports in the same pull request.
+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.
+
+### 4. Names that leave the codebase
+
+Some names are used outside the code. Renaming them needs more than a code change:
+
+- **Database columns** need a migration.
+- **Environment variables** must be renamed in every `.env.local` and in Vercel's settings too, or the app gets an empty value.
+- **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.
+
+### Renaming from the command line
+
+An AI agent working in a terminal has no editor, so it cannot press F2. The package ships a script that does the same job, using the project's own TypeScript and the same rename engine as the editor:
+
+```bash
+node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs <file> <currentName> <newName>
+```
+
+```bash
+# Rename a type everywhere it is used
+node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs components/ui/button/types.ts ButtonProperties ButtonProps
+```
+
+- **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.
+- **It cannot reach keys in plain object literals that aren't typed**, such as the expected value in a test's `toEqual({ properties: … })`. Search the tests for the old name and fix those keys by hand.
+- **Run the type check and tests after each batch** of renames.
+
+## Stage 5 — AGENTS.md
+
+Copy the [AGENTS.md template](/templates#agents) to the project root and replace every `[placeholder]`. Agree the standards with the person first ([Setup, step 3](/Guides/setup#3-agree-the-standards)), and set the code standards version from the [Version History](/version-history).
+
+## Stage 6 — Agent skills
+
+Copy the eight [standard skill files](/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
+
+## Stage 7 — Docs
+
+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.
+- **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.