@activatus/code-standards 0.0.0-stage → 3.0.0

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

@@ -0,0 +1,274 @@
+---
+sidebar_position: -1
+sidebar_label: "Human-Readable Names"
+---
+
+# Human-Readable Names
+
+**Every name we write is made of whole words a person can read out loud.** Variables, function parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters, no numbered names — not even for a loop counter or an event handler.
+
+Anyone reading the code should never have to guess what a name stands for.
+
+This applies to everyone writing code, **including AI agents**. An agent copies the examples it sees, so every example in these standards follows this rule too.
+
+## Never / Always
+
+| Never                      | Always                                         |
+| -------------------------- | ---------------------------------------------- |
+| `btn`, `msg`, `val`        | `button`, `message`, `value`                   |
+| `(e) =>`, `(item, i) =>`   | `(event) =>`, `(item, index) =>`               |
+| `acc` in a `reduce`        | `runningTotal` — what it actually holds        |
+| `args`, `params` (our own) | `commandArguments`, `searchFilters`            |
+| `cwd` (our own variable)   | `workingDirectory`                             |
+| `deps`, `env`              | `dependencies`, `environment`                  |
+| `timeoutMs`                | `timeoutMilliseconds`                          |
+| `MAX_RETRY_ATTEMPTS`       | `MAXIMUM_RETRY_ATTEMPTS`                       |
+| `size: "sm" \| "lg"`       | `size: "small" \| "large"`                     |
+| `<T>`                      | `<ItemType>`                                   |
+| `name="email1"`            | `name="emailAddress"`                          |
+| `helpers.ts`, `misc.ts`    | `formatCurrency.ts` — named after what it does |
+| `helpers/`, `utilities/`   | `utils/`                                       |
+| `useAuth`, `authStore`     | `useAuthentication`, `authenticationStore`     |
+| `STRIPE_SK`                | `STRIPE_SECRET_KEY`                            |
+
+## Where it applies
+
+Everything that has a name:
+
+| Thing                           | ✅ Human-readable                                    | ❌ Not                                            |
+| ------------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
+| **Folders**                     | `accountSettings/`, `invoiceTable/`                  | `acctSet/`, `misc/`, `stuff/`, `new/`             |
+| **Files**                       | `formatCurrency.ts`, `InvoiceTable.tsx`              | `fmtCur.ts`, `utils2.ts`, `helpers.ts`, `temp.ts` |
+| **Components**                  | `InvoiceTable`, `SubmitButton`                       | `Tbl`, `Comp1`, `MyComponent`, `Wrapper2`         |
+| **Component props**             | `isDisabled`, `onUserSelect`, `invoiceTotal`         | `dis`, `cb`, `val`, `data`                        |
+| **Variables**                   | `userEmailAddress`, `activeUsers`                    | `addr`, `x`, `temp`, `data`, `res`, `obj`         |
+| **Functions**                   | `calculateOrderTotal`, `sendWelcomeEmail`            | `calc`, `doIt`, `process`, `handle`               |
+| **Event handlers**              | `handleSearchTextChange`                             | `onChg`, `handler`, `fn`                          |
+| **Booleans**                    | `isLoading`, `hasPermission`, `canDelete`            | `loading`, `flag`, `ok`, `chk`                    |
+| **Constants**                   | `MAXIMUM_RETRY_ATTEMPTS`, `RETRY_DELAY_MILLISECONDS` | `MAX`, `N`, `DELAY`                               |
+| **Types**                       | `UserType`, `InvoiceStatusType`, `ButtonProps`       | `U`, `Data`, `IProps`, `Obj`                      |
+| **Generic type parameters**     | `<ItemType>`, `<ResponseType>`                       | `<T>`, `<K, V>`                                   |
+| **Union and enum values**       | `"processing" \| "shipped" \| "cancelled"`           | `"p" \| "s"`, `1 \| 2 \| 3`                       |
+| **Form fields**                 | `name="emailAddress"`, `name="companyName"`          | `name="email1"`, `name="fld3"`, `name="q"`        |
+| **CSS Module classes**          | `.primaryButton`, `.invoiceRow`                      | `.pb`, `.btn2`, `.wrapper3`                       |
+| **CSS variables**               | `--color-brand-primary`                              | `--c1`, `--blue2`                                 |
+| **Database tables and columns** | `draft_ticket`, `created_at`, `invoice_total`        | `dt`, `col1`, `amt`, `flag`                       |
+| **API routes**                  | `/api/calendar-events`                               | `/api/ce`, `/api/data`, `/api/v2x`                |
+| **Environment variables**       | `STRIPE_SECRET_KEY`, `DOCS_URL`                      | `SK`, `KEY2`, `URL_1`                             |
+| **Test names**                  | `it("adds a thousands separator")`                   | `it("works")`, `it("test 1")`                     |
+| **Doc files**                   | `architecture/background-jobs.md`                    | `arch/bg.md`, `notes2.md`                         |
+| **Error messages**              | `"Enter an email address"`                           | `"Invalid input"`, `"Error 42"`                   |
+
+The words come from the [Ontology](/ontology) wherever it has a term: reusable functions are in `utils/`, never `helpers/` or `utilities/`. A project's own ontology adds its product words: in Launchpad, a Draft Ticket is `draftTicket`, never `pendingTicket`. The casing comes from [Naming Conventions](/Structure/naming-conventions).
+
+---
+
+## Form fields
+
+Form fields are where names slip most, and where they matter most: a field's name travels through the whole system.
+
+**One field, one name, everywhere it goes.** The same words name the input, the form's data, the API request, the type and the database column:
+
+| Where                           | Name                   |
+| ------------------------------- | ---------------------- |
+| Input `name` and `id`           | `emailAddress`         |
+| Form data and validation schema | `emailAddress`         |
+| API request body                | `emailAddress`         |
+| Type property                   | `emailAddress: string` |
+| Database column                 | `email_address`        |
+
+```tsx
+// ✅ Good
+<label htmlFor="emailAddress">Email address</label>
+<input id="emailAddress" name="emailAddress" type="email" />
+
+<label htmlFor="billingFrequency">Billing frequency</label>
+<select id="billingFrequency" name="billingFrequency">
+  <option value="monthly">Monthly</option>
+  <option value="yearly">Yearly</option>
+</select>
+```
+
+```tsx
+// ❌ Bad
+<input id="f3" name="email1" placeholder="Email" />
+
+<select name="freq">
+  <option value="1">Monthly</option>
+  <option value="2">Yearly</option>
+</select>
+```
+
+- **`name` and `id` are full words**, and match each other.
+- **Every field has a visible `<label>`** in plain English. A placeholder is never the label.
+- **Option values are words**, not numbers: `value="monthly"`, not `value="1"`.
+- **Buttons with only an icon get an `aria-label`** that says what they do: `aria-label="Delete invoice"`.
+- **Validation messages name the field and say what to do**: "Enter an email address", not "Required".
+
+---
+
+## `id` is a word
+
+**`id` is its own word. Never write it out as `identifier`.**
+
+| Where                  | Write                           |
+| ---------------------- | ------------------------------- |
+| A property or variable | `id`, `userId`, `draftTicketId` |
+| A list of them         | `userIds`                       |
+| A constant             | `DEFAULT_PROJECT_ID`            |
+| A database column      | `user_id`                       |
+
+- **Case it as a word**: `userId`, never `userID`.
+- **`identifier` means something else.** Use it only when an outside system has a separate field with that name. Linear has both: `id` is its hidden unique code, and `identifier` is the readable `ACT-73`. Writing `identifier` for an `id` would mix the two up.
+
+## Dictionary
+
+Some short names are not abbreviations. They are the word people actually say, and the long form would only make the name harder to read. **These are dictionary words, and stay short:**
+
+| Word                         | Means                                                                                                       | Example names                                     |
+| ---------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `id`                         | A unique id                                                                                                 | `userId`, `user_id`, `DEFAULT_PROJECT_ID`         |
+| `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`        |
+| `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`                                 |
+| `url`                        | A web address                                                                                               | `imageUrl`, `DOCS_URL`                            |
+| `api`                        | An application programming interface                                                                        | `api/`, `apiResponse`                             |
+| `uat`                        | User acceptance testing                                                                                     | `uatEnvironment`                                  |
+| `pdf`, `html`, `css`, `json` | File formats                                                                                                | `invoicePdf`, `htmlContent`, `globals.css`        |
+| `readme`                     | A project's README file                                                                                     | `readmeContent`                                   |
+
+**Case them as words** in camelCase and PascalCase: `imageUrl`, `apiResponse`, `docsSite` — never `imageURL` or `APIResponse`.
+
+**This list is the only back door.** A short name not on it gets written out in full. If people say the long form out loud — "environment", "dependencies", "message" — write the long form.
+
+### Adding a word to the dictionary
+
+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.
+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.
+
+---
+
+## Third-party names
+
+**This rule is for the names we write.** It does not cover names that come from someone else's code — a package, a framework, an outside service. Those stay exactly as they are: everyone knows them by that name, their docs use that name, and renaming them breaks the code. Use them as they are where they touch the outside, then **give the value a full-word name as soon as it comes into our code**.
+
+| From                      | Examples                                                                                                    |
+| ------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| An outside service's data | Linear's `id`, `identifier` and `pageInfo`                                                                  |
+| Node and library options  | `cwd` in `execFile`, `process.env`, `stdout`, `argv`                                                        |
+| React                     | `ref`, `children`, `useRef`, `useEffect`                                                                    |
+| shadcn/ui                 | the `cn` class-name function, and the component files it generates                                          |
+| Next.js                   | the `app/` folder, `params`, `searchParams`, `LayoutProps`, `generateMetadata`                              |
+| HTML and CSS              | `href`, `src`, `alt`, `tabIndex`, Tailwind classes like `text-sm`                                           |
+| Tools                     | `node_modules`, `.env.local`, Docusaurus's `src/pages`, Storybook's `args`, the `dev` and `prepare` scripts |
+| A project's own ontology  | Its decided product terms, such as Launchpad's `dev_agent`                                                  |
+
+```ts
+// ✅ Good — the option keeps its third-party name; our value gets a full-word name
+const workingDirectory = process.cwd();
+const commandArguments = ["lint", "--fix"];
+
+execFile("pnpm", commandArguments, { cwd: workingDirectory });
+```
+
+```ts
+// ❌ Bad — renaming the third-party option breaks the call: execFile ignores "workingDirectory"
+execFile("pnpm", commandArguments, { workingDirectory });
+
+// ❌ Bad — the third-party name leaks into our own code
+const cwd = process.cwd();
+```
+
+### When a name clashes
+
+**Keep a third-party import's own name.** When it clashes with something the file declares itself, **rename our own thing first**. A clash usually means our name is too vague: give it a more specific full-word name that says what it actually is.
+
+```ts
+// ✅ Good — our function says what it makes, so Supabase's createClient keeps its name
+import { createClient } from "@supabase/supabase-js";
+
+export const createProjectDatabaseClient = () =>
+  createClient(DATABASE_URL, DATABASE_KEY);
+```
+
+```ts
+// ❌ Bad — the import is renamed to make room for our vague name
+import { createClient as createSupabaseClient } from "@supabase/supabase-js";
+
+export const createClient = () =>
+  createSupabaseClient(DATABASE_URL, DATABASE_KEY);
+```
+
+**Rename the import only when our side can't change:**
+
+| The clash                                                                                          | Why our side can't change                      | Rename the import to                                       |
+| -------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
+| **Two third-party names**, such as `Link` from `next/link` and the `Link` icon from `lucide-react` | Neither name is ours                           | The owner plus the original name: `Link as LucideLinkIcon` |
+| **Our name is fixed by a framework**, such as a Next.js route's `GET` or `generateMetadata`        | The framework finds it only by that exact name | The owner plus the original name                           |
+
+```ts
+// ✅ Good — two third-party names clash, so one import is renamed: owner plus original name
+import Link from "next/link";
+import { Link as LucideLinkIcon } from "lucide-react";
+```
+
+```ts
+// ❌ Bad — renamed for taste, or shortened
+import { createClient as makeDb } from "@supabase/supabase-js";
+import { Link as Icon } from "lucide-react";
+```
+
+Never rename an import for taste, and never shorten it.
+
+---
+
+## Examples in code
+
+```ts
+// ✅ Good
+const userEmailAddress = user.email;
+const isSubmitButtonDisabled = !isFormValid;
+
+const calculateOrderTotal = (orderItems: OrderItemType[]) => {
+  return orderItems.reduce(
+    (runningTotal, orderItem) => runningTotal + orderItem.price,
+    0,
+  );
+};
+
+users.map((user) => user.name);
+```
+
+```ts
+// ❌ Bad
+const addr = user.email;
+const btnDis = !valid;
+
+const calc = (arr: OrderItemType[]) => {
+  return arr.reduce((acc, i) => acc + i.price, 0);
+};
+
+users.map((u) => u.name);
+```
+
+---
+
+## How it is checked
+
+| Names                                                                                                                        | Checked by                                                                                           |
+| ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Variables, functions, parameters and file names                                                                              | ESLint `unicorn/name-replacements` and `unicorn/filename-case`                                       |
+| Type names                                                                                                                   | ESLint `@typescript-eslint/naming-convention`                                                        |
+| CSS variables and CSS Module classes                                                                                         | Stylelint                                                                                            |
+| **Everything else** — folders, props, form fields, union values, database columns, routes, environment variables, test names | **Code review and AI agents.** The linter cannot read these, so every agent and reviewer checks them |
+
+ESLint allows the [dictionary](#dictionary) words it would otherwise flag (`docs`, `lib`, `props`, `ref`, `repo`, `utils`), and exactly two third-party names as they are: `params` and `searchParams`. It still flags any of our own names built from an third-party name, such as `inputRef`.

package/docs/Standards/lint-errors.md

@@ -0,0 +1,171 @@
+---
+sidebar_position: 1.5
+sidebar_label: "Fixing Lint Errors"
+---
+
+# Fixing Lint Errors
+
+When `pnpm lint` reports an error, find the rule name at the end of the line in the tables below. Each row says what the error means in plain English and how to fix it.
+
+```text
+src/userService.ts
+  12:3  error  Dependency cycle detected  import-x/no-cycle
+  │            │                          └── the rule name — look this up below
+  │            └── the message
+  └── line 12, column 3
+```
+
+## The golden rule
+
+**Fix the code. Never switch the rule off to make the error go away.**
+
+A lint error means the code breaks a standard. The fix is always to change the code. Do not add `eslint-disable` comments, do not delete rules from the config, and do not move files into `vendor/` to hide them.
+
+There are exactly two rules that may be switched off for one line, and both need a comment saying why — see [the only allowed exceptions](#the-only-allowed-exceptions).
+
+This applies to everyone, **including AI agents**. An agent's work is not finished while `pnpm lint` reports errors.
+
+---
+
+## Imports
+
+| Rule                                         | What you will see                                                        | What it means                                                                                         | How to fix it                                                                                                                                                                                                      |
+| -------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `import-x/no-cycle`                          | `Dependency cycle detected`                                              | Two files import each other, directly or through other files. One will load before the other is ready | Move the part both files need into a **third file** that both import. If the cycle goes through an `index.ts`, import the file directly instead. See [Import safety](/Structure/import-organization#import-safety) |
+| `import-x/no-unresolved`                     | `Unable to resolve path to module '…'`                                   | The file being imported does not exist at that path                                                   | Check the spelling and the path. If the file was renamed or moved, update the import                                                                                                                               |
+| `import-x/no-default-export`                 | `Prefer named exports`                                                   | The file uses `export default`                                                                        | Change to a named export: `export const formatCurrency = …`                                                                                                                                                        |
+| `@typescript-eslint/consistent-type-imports` | `All imports in the declaration are only used as types. Use import type` | A type is imported like a value                                                                       | Change `import { UserType }` to `import type { UserType }`                                                                                                                                                         |
+
+## Order and variables
+
+| Rule                                | What you will see                                       | What it means                                    | How to fix it                                                                                                        |
+| ----------------------------------- | ------------------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `no-use-before-define`              | `'formatReport' was used before it was defined`         | Something is used above the line that creates it | Move the definition **above** the code that uses it                                                                  |
+| `no-restricted-syntax`              | `Use const. If this value really must be reassigned…`   | A variable is declared with `let`                | Change `let` to `const`. If the value really must change, see [the allowed exceptions](#the-only-allowed-exceptions) |
+| `no-var`                            | `Unexpected var, use let or const instead`              | A variable is declared with `var`                | Change `var` to `const`                                                                                              |
+| `prefer-const`                      | `'total' is never reassigned. Use 'const' instead`      | A `let` variable never changes                   | Change `let` to `const`                                                                                              |
+| `no-magic-numbers`                  | `No magic number: 3`                                    | A bare number is used in the logic               | Give it a name: `const MAXIMUM_RETRY_ATTEMPTS = 3;`                                                                  |
+| `unicorn/name-replacements`         | ``The variable `btn` should be named `button` ``        | A name is shorthand                              | Rename it to the full English word                                                                                   |
+| `unicorn/no-top-level-side-effects` | `Do not use top-level side effects in exported modules` | The file runs code as it loads                   | Put the code inside a function and export the function                                                               |
+
+## Functions
+
+| Rule                    | What you will see                                                         | What it means                                   | How to fix it                                                                  |
+| ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ |
+| `func-style`            | `Expected a function expression`                                          | The `function` keyword was used                 | Rewrite as an arrow function: `const name = () => { … };`                      |
+| `prefer-arrow-callback` | `Unexpected function expression`                                          | A callback uses the `function` keyword          | Rewrite the callback as an arrow function                                      |
+| `no-restricted-syntax`  | `Use an arrow function`                                                   | `const name = function () {}` was used          | Rewrite as `const name = () => {}`                                             |
+| `no-restricted-syntax`  | `Use a single object parameter when a function needs more than one value` | A function has more than one parameter          | Take one object instead: `({ name, emailAddress }: CreateUserProps) =>`        |
+| `no-restricted-syntax`  | `Use functions, not classes`                                              | A `class` was used                              | Rewrite it as functions                                                        |
+| `max-depth`             | `Blocks are nested too deeply (4). Maximum allowed is 3`                  | `if`s and loops are nested more than three deep | Return early for the error cases, or move the inner part into its own function |
+| `no-nested-ternary`     | `Do not nest ternary expressions`                                         | A `? :` sits inside another `? :`               | Use an `if`, or move it into its own function                                  |
+
+## Files
+
+| Rule                    | What you will see                                       | What it means                      | How to fix it                                                                                  |
+| ----------------------- | ------------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `max-lines`             | `File has too many lines (312). Maximum allowed is 300` | The file is over 300 lines         | Split it: move functions to `utils/`, sub-components to their own folders, types to `types.ts` |
+| `unicorn/filename-case` | `Filename is not in camel case or pascal case`          | The file name is in the wrong case | Rename it: camelCase for code files, PascalCase for component files                            |
+
+## Types
+
+| Rule                                            | What you will see                                                  | What it means                                 | How to fix it                                                                                                     |
+| ----------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `@typescript-eslint/no-explicit-any`            | `Unexpected any. Specify a different type`                         | `any` was used                                | Use the real type, or `unknown` and then check it                                                                 |
+| `@typescript-eslint/no-non-null-assertion`      | `Forbidden non-null assertion`                                     | `value!` was used                             | Check that the value exists first: `if (!value) { return; }`                                                      |
+| `@typescript-eslint/consistent-type-assertions` | `Do not use any type assertions`                                   | `value as SomeType` was used                  | Validate the value instead. If a cast is truly needed, see [the allowed exceptions](#the-only-allowed-exceptions) |
+| `@typescript-eslint/naming-convention`          | ``Interface name `User` must match the RegExp: /(Props\|Type)$/u`` | A type name does not end in `Props` or `Type` | Rename it: `UserType`, `ButtonProps`                                                                              |
+
+## React
+
+| Rule                                  | What you will see                           | What it means                                                         | How to fix it                                                            |
+| ------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| `react/jsx-no-bind`                   | `JSX props should not use arrow functions`  | A function is written inside the JSX, or passed without `useCallback` | Declare it above with `useCallback` and pass it by name                  |
+| `react/no-multi-comp`                 | `Declare only one React component per file` | The file has more than one component                                  | Move the second component to its own folder                              |
+| `react/function-component-definition` | An error naming this rule                   | A component is written with the `function` keyword                    | Rewrite it as an arrow function. `pnpm lint:fix` does this automatically |
+
+## Comments
+
+| Rule                                                    | What you will see                                                                                        | What it means                             | How to fix it                                                          |
+| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
+| `@eslint-community/eslint-comments/require-description` | `Unexpected undescribed directive comment. Include descriptions to explain why the comment is necessary` | An `eslint-disable` comment has no reason | Add the reason after `--`. Better: remove the comment and fix the code |
+
+---
+
+## The only allowed exceptions
+
+Two rules may be switched off for a single line. Both need the reason written after `--`, and ESLint rejects the comment without one.
+
+### A variable that must be reassigned
+
+Always use `const`. When a value genuinely has to change — a running total, a retry counter — use `let` and say why:
+
+```ts
+// eslint-disable-next-line no-restricted-syntax -- the running total is built up across the loop
+let runningTotal = 0;
+```
+
+Before reaching for `let`, check whether `const` with `map`, `filter` or `reduce` does the job. It usually does.
+
+### A type cast that cannot be avoided
+
+```ts
+// eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- the API returns untyped JSON; validated by parseUser below
+const user = response.data as UserType;
+```
+
+Nothing else is switched off. If another rule seems impossible to satisfy, the code needs restructuring — ask before disabling it.
+
+---
+
+## Errors that stop ESLint running
+
+| What you will see                                 | What it means                                    | How to fix it                                                                     |
+| ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
+| `typescript-eslint does not support TS 7.0`       | The linter cannot run against TypeScript 7 yet   | See the [TypeScript 7 note](/Standards/eslint#installation) on the ESLint page    |
+| `contextOrFilename.getFilename is not a function` | The React plugin cannot detect the React version | Set `settings.react.version` to the project's React version instead of `"detect"` |
+| `Cannot find module '…'`                          | A lint package is not installed                  | Run the install commands on the [ESLint page](/Standards/eslint#installation)     |
+
+---
+
+## How errors are caught
+
+Lint runs in three places, so a broken standard is caught before it reaches `main`:
+
+| 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).

package/docs/Standards/prettier.md

@@ -0,0 +1,106 @@
+---
+sidebar_position: 2
+sidebar_label: "Prettier"
+---
+
+# Prettier Configuration
+
+A single shared Prettier config keeps formatting consistent and eliminates "style" discussion in code review.
+
+## Installation
+
+```bash
+pnpm add -D prettier prettier-plugin-tailwindcss
+```
+
+## Usage
+
+Create `prettier.config.mjs` in your project root:
+
+```js title="prettier.config.mjs"
+/** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
+const config = {
+	// Short lines, so code reads well on a phone.
+	printWidth: 70,
+	// Tabs indent. A tab counts as 2 characters towards the line width.
+	useTabs: true,
+	tabWidth: 2,
+	singleQuote: false,
+	trailingComma: "all",
+	bracketSpacing: true,
+	bracketSameLine: false,
+	arrowParens: "always",
+	semi: true,
+	endOfLine: "lf",
+	plugins: ["prettier-plugin-tailwindcss"],
+	tailwindStylesheet: "./app/globals.css",
+	overrides: [
+		{
+			// YAML does not allow tabs, and Markdown reads a tab as four spaces.
+			files: ["*.md", "*.mdx", "*.yml", "*.yaml"],
+			options: { useTabs: false },
+		},
+	],
+};
+
+export default config;
+```
+
+Add scripts to `package.json`:
+
+```json
+{
+  "scripts": {
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}
+```
+
+## Tailwind class sorting
+
+The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindlabs/prettier-plugin-tailwindcss), the official Tailwind plugin. It sorts the classes in every `className` into one standard order when the file is formatted, so the same classes are always written the same way:
+
+```tsx
+// Before formatting
+<button className="text-white px-8 hover:bg-brand-primary-hover rounded-md bg-brand-primary py-4 flex">
+
+// After formatting
+<button className="flex rounded-md bg-brand-primary px-8 py-4 text-white hover:bg-brand-primary-hover">
+```
+
+- **It is part of the standard**, not a project extra. Every project that uses Tailwind has it.
+- **`tailwindStylesheet` points at the project's global stylesheet**, so the plugin knows the project's own colours. Change the path if `globals.css` lives somewhere else.
+- **A project with no Tailwind** (a plain Node.js service) removes the `plugins` and `tailwindStylesheet` lines.
+
+## Settings reference
+
+| Option            | Value      | Rationale                                                                                                   |
+| ----------------- | ---------- | ----------------------------------------------------------------------------------------------------------- |
+| `printWidth`      | `70`       | Short lines read well on a phone, where a lot of code is reviewed                                           |
+| `tabWidth`        | `2`        | How many characters a tab counts as towards the line width; matches `.editorconfig`                         |
+| `useTabs`         | `true`     | Tabs indent code: each person sees the width they like, and files are smaller. Markdown and YAML use spaces |
+| `singleQuote`     | `false`    | Double quotes are standard in JSX and HTML; one style for all                                               |
+| `trailingComma`   | `"all"`    | Cleaner diffs when adding items to the end of a list                                                        |
+| `bracketSpacing`  | `true`     | `{ foo }` is more readable than `{foo}`                                                                     |
+| `bracketSameLine` | `false`    | Closing `>` on its own line for JSX                                                                         |
+| `arrowParens`     | `"always"` | `(x) => x` is consistent whether 0, 1, or many params                                                       |
+| `semi`            | `true`     | Explicit semicolons avoid ASI footguns                                                                      |
+| `endOfLine`       | `"lf"`     | Unix line endings everywhere; matches `.editorconfig`                                                       |
+
+## Editor integration
+
+### VS Code
+
+Install the [Prettier - Code formatter](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) extension, then add to your workspace settings:
+
+```json
+{
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true
+}
+```
+
+### JetBrains IDEs
+
+Go to **Settings → Languages & Frameworks → JavaScript → Prettier** and enable "Run on save".