@activatus/code-standards 2.0.0 → 3.0.0

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

@@ -19,17 +19,14 @@ This applies to everyone writing code, **including AI agents**. An agent copies
 | `(e) =>`, `(item, i) =>`   | `(event) =>`, `(item, index) =>`               |
 | `acc` in a `reduce`        | `runningTotal` — what it actually holds        |
 | `args`, `params` (our own) | `commandArguments`, `searchFilters`            |
-| `inputRef`                 | `inputReference`                               |
-| `inputRef`                 | `inputReference`                               |
 | `cwd` (our own variable)   | `workingDirectory`                             |
-| `deps`, `repo`, `env`      | `dependencies`, `repository`, `environment`    |
+| `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 |
-| `lib/`                     | `library/`                                     |
 | `helpers/`, `utilities/`   | `utils/`                                       |
 | `useAuth`, `authStore`     | `useAuthentication`, `authenticationStore`     |
 | `STRIPE_SK`                | `STRIPE_SECRET_KEY`                            |
@@ -59,7 +56,6 @@ Everything that has a name:
 | **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")`                     |
-| **Branches**                    | `feat/invoice-export`                                | `fix/stuff`, `toms-branch`                        |
 | **Doc files**                   | `architecture/background-jobs.md`                    | `arch/bg.md`, `notes2.md`                         |
 | **Error messages**              | `"Enter an email address"`                           | `"Invalid input"`, `"Error 42"`                   |
 
@@ -129,30 +125,33 @@ Form fields are where names slip most, and where they matter most: a field's nam
 
 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` |
-| `props`                      | The values a component takes               | `props`, `ButtonProps`                            |
-| `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`                                   |
+| 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", "repository", "application" — write the long form.
+**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:** would a non-developer say this word out loud, and know what it means? `docs`: yes. `env`, `repo`, `btn`: no.
+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, props: false, utils: false }`.
+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.
 
@@ -189,6 +188,47 @@ execFile("pnpm", commandArguments, { workingDirectory });
 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
@@ -231,4 +271,4 @@ users.map((u) => u.name);
 | 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) it would otherwise flag (`docs`, `props`, `utils`), and exactly three third-party names as they are — `ref`, `params` and `searchParams`. It still flags any of our own names built from an third-party name, such as `inputRef`.
+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

@@ -132,8 +132,40 @@ Nothing else is switched off. If another rule seems impossible to satisfy, the c
 
 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`) | When a person commits     | The commit is refused until the errors are fixed                         |
-| **CI**                             | On every pull request     | The pull request cannot be merged                                        |
+| 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

@@ -15,23 +15,32 @@ pnpm add -D prettier prettier-plugin-tailwindcss
 
 ## Usage
 
-Create `prettier.config.js` in your project root:
+Create `prettier.config.mjs` in your project root:
 
-```js title="prettier.config.js"
+```js title="prettier.config.mjs"
 /** @type {import("prettier").Config & import("prettier-plugin-tailwindcss").PluginOptions} */
 const config = {
-  printWidth: 100,
-  tabWidth: 2,
-  useTabs: false,
-  singleQuote: false,
-  trailingComma: "all",
-  bracketSpacing: true,
-  bracketSameLine: false,
-  arrowParens: "always",
-  semi: true,
-  endOfLine: "lf",
-  plugins: ["prettier-plugin-tailwindcss"],
-  tailwindStylesheet: "./app/globals.css",
+	// 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;
@@ -66,18 +75,18 @@ The config includes [`prettier-plugin-tailwindcss`](https://github.com/tailwindl
 
 ## Settings reference
 
-| Option | Value | Rationale |
-| --- | --- | --- |
-| `printWidth` | `100` | Wider than 80 but avoids the illegibility of unconstrained lines |
-| `tabWidth` | `2` | Standard for JS/TS; matches `.editorconfig` |
-| `useTabs` | `false` | Spaces are consistent across all editors |
-| `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` |
+| 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
 

package/docs/Standards/readable-code.md

@@ -521,6 +521,36 @@ interface UserCardData {}
 
 Use a named type instead of a bare `string` wherever the value has a fixed set of options.
 
+### Name a type after what it is, not the job it does
+
+A type name says what the thing is. **If a type only describes one field of a function's props, don't give it its own name**: write it inside the `Props`, so the `Props` is the only type.
+
+```ts
+// ✅ Good — the dependencies are written inside the one Props type
+interface StartAgentRunProps {
+  ticketId: string;
+  dependencies: {
+    launchSession: (ticketId: string) => Promise<void>;
+    reportStatus: (status: AgentRunStatusType) => void;
+  };
+}
+```
+
+```ts
+// ❌ Bad — a second type named after the role it plays in one function
+interface StartAgentRunDependenciesType {
+  launchSession: (ticketId: string) => Promise<void>;
+  reportStatus: (status: AgentRunStatusType) => void;
+}
+
+interface StartAgentRunProps {
+  ticketId: string;
+  dependencies: StartAgentRunDependenciesType;
+}
+```
+
+Where that object is built somewhere else, don't annotate it with a separate type either. TypeScript checks it against `StartAgentRunProps` when it is passed in.
+
 ---
 
 ## Error messages say what happened and what to do

package/docs/Standards/stylelint.md

@@ -7,10 +7,10 @@ sidebar_label: "Stylelint"
 
 Components are styled with [Tailwind CSS](/Standards/styling), and Stylelint lints the CSS that is still written by hand — `globals.css` and any CSS Modules. Start from the config below that matches the project:
 
-| Config | Use when |
-| --- | --- |
+| Config                                  | Use when                                  |
+| --------------------------------------- | ----------------------------------------- |
 | [Plain CSS](#plain-css-and-css-modules) | Plain CSS and CSS Modules (`.module.css`) |
-| [SCSS](#scss) | SCSS / Sass |
+| [SCSS](#scss)                           | SCSS / Sass                               |
 
 ## Installation
 
@@ -34,7 +34,10 @@ Create `stylelint.config.mjs` in your project root:
 /** @type {import("stylelint").Config} */
 export default {
   ignoreFiles: ["**/vendor/**"],
-  extends: ["stylelint-config-standard", "stylelint-config-recess-order"],
+  extends: [
+    "stylelint-config-standard",
+    "stylelint-config-recess-order",
+  ],
   rules: {
     "selector-max-id": 0,
     "property-no-vendor-prefix": true,
@@ -42,7 +45,16 @@ export default {
     "import-notation": "string",
     "at-rule-no-unknown": [
       true,
-      { ignoreAtRules: ["theme", "utility", "variant", "custom-variant", "source", "plugin"] },
+      {
+        ignoreAtRules: [
+          "theme",
+          "utility",
+          "variant",
+          "custom-variant",
+          "source",
+          "plugin",
+        ],
+      },
     ],
   },
   overrides: [
@@ -67,7 +79,10 @@ export default {
 /** @type {import("stylelint").Config} */
 export default {
   ignoreFiles: ["**/vendor/**"],
-  extends: ["stylelint-config-standard-scss", "stylelint-config-recess-order"],
+  extends: [
+    "stylelint-config-standard-scss",
+    "stylelint-config-recess-order",
+  ],
   rules: {
     "selector-max-id": 0,
     "property-no-vendor-prefix": true,
@@ -104,11 +119,11 @@ Add a lint script to `package.json`:
 
 ## Extended configs
 
-| Config | Used by | Purpose |
-| --- | --- | --- |
-| `stylelint-config-standard` | Plain CSS and CSS Modules | Stylelint's recommended modern CSS rules |
-| `stylelint-config-standard-scss` | SCSS | Standard rules + SCSS-specific rules |
-| `stylelint-config-recess-order` | all | Enforces Bootstrap/RECESS property order |
+| Config                           | Used by                   | Purpose                                  |
+| -------------------------------- | ------------------------- | ---------------------------------------- |
+| `stylelint-config-standard`      | Plain CSS and CSS Modules | Stylelint's recommended modern CSS rules |
+| `stylelint-config-standard-scss` | SCSS                      | Standard rules + SCSS-specific rules     |
+| `stylelint-config-recess-order`  | all                       | Enforces Bootstrap/RECESS property order |
 
 ## Property order
 

package/docs/Standards/styling.md

@@ -56,7 +56,9 @@ export const PageHeaderActions = () => {
       <button className="rounded-md bg-brand-primary px-4 py-2 text-white">
         Save
       </button>
-      <button className="rounded-md px-4 py-2 text-text">Cancel</button>
+      <button className="rounded-md px-4 py-2 text-text">
+        Cancel
+      </button>
     </div>
   );
 };
@@ -71,13 +73,17 @@ export const PageHeader = () => {
     <header className="grid grid-cols-[1fr_auto] items-center gap-4">
       <div className="flex flex-col gap-1">
         <h1 className="text-2xl font-semibold text-text">Invoices</h1>
-        <p className="text-sm text-text">All invoices for this account</p>
+        <p className="text-sm text-text">
+          All invoices for this account
+        </p>
       </div>
       <div className="flex items-center gap-2">
         <button className="rounded-md bg-brand-primary px-4 py-2 text-white">
           Save
         </button>
-        <button className="rounded-md px-4 py-2 text-text">Cancel</button>
+        <button className="rounded-md px-4 py-2 text-text">
+          Cancel
+        </button>
       </div>
     </header>
   );

package/docs/Standards/tech-stack.md

@@ -38,7 +38,9 @@ the code reads as though it were typed. Storyblok's story type is the one to wat
 
 ```ts
 // storyblok-js-client
-interface ISbStoryData<Content = ISbComponentType<string> & { [index: string]: any }> {
+interface ISbStoryData<
+  Content = ISbComponentType<string> & { [index: string]: any },
+> {
   content: Content;
   // …
 }

package/docs/Structure/_category_.json

@@ -1,4 +1,4 @@
 {
-  "label": "Structure",
-  "position": 7
+	"label": "Structure",
+	"position": 7
 }

package/docs/Structure/component-organization.md

@@ -216,7 +216,11 @@ export const UserListClient = ({
       <input value={searchText} onChange={handleSearchTextChange} />
       <ul>
         {visibleUsers.map((user) => (
-          <UserListItem key={user.id} user={user} onUserSelect={onUserSelect} />
+          <UserListItem
+            key={user.id}
+            user={user}
+            onUserSelect={onUserSelect}
+          />
         ))}
       </ul>
     </section>
@@ -301,7 +305,10 @@ interface UserListItemProps {
   onUserSelect?: (user: UserType) => void;
 }
 
-export const UserListItem = ({ user, onUserSelect }: UserListItemProps) => {
+export const UserListItem = ({
+  user,
+  onUserSelect,
+}: UserListItemProps) => {
   const handleClick = useCallback(() => {
     onUserSelect?.(user);
   }, [onUserSelect, user]);

package/docs/Structure/folder-structure.md

@@ -49,25 +49,25 @@ project-root/
 │   │       ├── types.ts                             # Component types
 │   │       └── index.ts                             # Export file
 │   └── shared/                                      # Used by more than one page
-├── library/                                             # Core libraries & integrations
-│   ├── permissions/                                 # Permission files (grouped)
+├── lib/                                             # Outside connections and app-wide setup
+│   ├── permissions/                                 # Who may do what
 │   │   ├── index.ts                                 # Main definitions
 │   │   ├── api.ts                                   # API permissions
 │   │   ├── page.ts                                  # Page permissions
 │   │   └── plan.ts                                  # Plan permissions
-│   ├── integrations/                                # External services (grouped)
+│   ├── integrations/                                # The only code that talks to outside services
 │   │   ├── stripe.ts                                # Payment processing
 │   │   └── supabase/                                # Database integration
 │   │       ├── client.ts
 │   │       └── mock/
-│   ├── middleware/                                  # Middleware concerns (grouped)
+│   ├── middleware/                                  # Code that runs on every request
 │   │   ├── cors.ts
 │   │   ├── rateLimit.ts
 │   │   └── session.ts
-│   ├── validation/                                  # Validation schemas
-│   ├── constants/                                   # Constants
-│   ├── errors/                                      # Error handlers
-│   └── types/                                       # Type definitions
+│   ├── validation/                                  # Schemas that check input
+│   ├── constants/                                   # Constants shared across the app
+│   ├── errors/                                      # Error types and handlers shared across the app
+│   └── types/                                       # Types shared across the app; a component's own types stay in its types.ts
 ├── utils/                                           # Reusable functions used across the app
 │   ├── formatCurrency/                              # One folder per function
 │   │   ├── formatCurrency.ts
@@ -79,10 +79,8 @@ project-root/
 │   │   └── index.ts
 │   └── index.ts                                     # Exports every function
 ├── hooks/                                           # Custom React hooks
-├── services/                                        # Business logic services
+├── services/                                        # Business logic: what the app does
 ├── stores/                                          # State management stores
-├── types/                                           # TypeScript type definitions
-├── constants/                                       # App constants
 ├── styles/                                          # Global styles
 ├── public/                                          # Static assets
 ├── tests/                                           # Test files
@@ -108,7 +106,7 @@ project-root/
 project-root/
 ├── app/                    # Next.js App Router
 ├── components/             # React components
-├── library/                    # Core libraries & integrations
+├── lib/                    # Outside connections and app-wide setup
 ├── utils/                  # Reusable functions
 ├── public/                 # Static assets
 ├── docs/                   # Project documentation (Markdown)
@@ -178,6 +176,21 @@ Other frameworks follow the same rule with their own folders. In a React app wit
 
 ---
 
+## 🗂️ utils, services and lib {#utils-services-and-lib}
+
+Three folders hold functions that are not components. Each function belongs in exactly one of them:
+
+| Folder          | What goes in it                                                                                                                                                                              | Ask yourself                                                              | Examples                                                          |
+| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| **`utils/`**    | Small reusable functions with no side effects. The same input always gives the same output: formatting, calculating, sorting, checking                                                       | "Does it only work with what it is given?"                                | `formatCurrency`, `calculateInvoiceTotal`, `sortInvoicesByDate`   |
+| **`services/`** | The business logic: what the app actually does. Its rules and operations, which may read and write data                                                                                      | "Is this a rule or an action of the product itself?"                      | `createInvoice`, `decideNextActions`, `sendWelcomeEmail`          |
+| **`lib/`**      | Code that connects the app to something outside it, and the app-wide setup around that: integration clients, permissions, middleware, validation schemas, constants, errors and shared types | "Does it talk to another system, or set up something the whole app uses?" | `lib/integrations/stripe/`, `lib/permissions/`, `lib/validation/` |
+
+- **Pages, API routes and server actions stay thin.** They take the request, call a function in `services/`, and return the result. Business logic never lives in them.
+- **`services/` uses `lib/` to reach the outside world.** A service that charges a card calls the Stripe client in `lib/integrations/stripe/`, never the Stripe package directly.
+- **`utils/` uses nothing outside itself.** If a function needs a database, an API or the environment, it is not a util: it belongs in `services/` or `lib/`.
+- **Group `services/` by the [Ontology](/ontology) word it works on**, one folder per function: `services/invoice/createInvoice/`.
+
 ## 🧰 Utils
 
 **Every reusable function lives in a `utils/` folder**, never inside a UI file. Where it goes depends on who uses it:
@@ -310,7 +323,7 @@ Name documentation folders and files in **kebab-case** (`background-jobs.md`), n
 ```text
 /root
 ├── eslint.config.mjs         # ESLint configuration
-├── prettier.config.js       # Prettier configuration
+├── prettier.config.mjs       # Prettier configuration
 ├── tsconfig.json            # TypeScript configuration
 ├── next.config.mjs          # Next.js configuration
 ├── package.json             # Dependencies & scripts

package/docs/Structure/naming-conventions.md

@@ -295,7 +295,6 @@ Code files are camelCase or PascalCase. A short list of things are kebab-case in
 | **Route folders**       | `app/account-settings/`                | The folder name becomes the URL          |
 | **Documentation files** | `docs/architecture/background-jobs.md` | The file name becomes the URL            |
 | **CSS variables**       | `--color-brand-primary`                | The CSS convention; required by Tailwind |
-| **Branch names**        | `feat/invoice-export`                  | The Git convention                       |
 
 **The rule of thumb: if the name becomes a URL, it is kebab-case.**
 
@@ -314,7 +313,6 @@ Code files are camelCase or PascalCase. A short list of things are kebab-case in
 | **Constant files**      | camelCase / SCREAMING_SNAKE_CASE | `userRole.ts` / `API_URL.ts` |
 | **CSS modules**         | camelCase + `.module.css`        | `userProfile.module.css`     |
 | **CSS variables**       | kebab-case                       | `--color-brand-primary`      |
-| **Branches**            | `type/kebab-case`                | `feat/invoice-export`        |
 | **Documentation files** | kebab-case                       | `background-jobs.md`         |
 | **Variables**           | camelCase                        | `userName`                   |
 | **Functions**           | camelCase                        | `getUserData`                |

package/docs/intro.md

@@ -17,12 +17,10 @@ This site documents the shared code standards used across all Activatus projects
 | Documentation        | [Docs standard](/Standards/documentation)      | How project docs are written and shown at `/docs`                                               |
 | ESLint               | [`eslint.config.mjs`](/Standards/eslint)       | Linting rules for JS/TS/React/Next.js                                                           |
 | Fixing Lint Errors   | [Error guide](/Standards/lint-errors)          | What each lint error means and how to fix it                                                    |
-| Prettier             | [`prettier.config.js`](/Standards/prettier)    | Code formatting                                                                                 |
+| Prettier             | [`prettier.config.mjs`](/Standards/prettier)   | Code formatting                                                                                 |
 | Stylelint            | [`stylelint.config.mjs`](/Standards/stylelint) | Linting rules for CSS/SCSS/CSS Modules                                                          |
 | EditorConfig         | [`.editorconfig`](/Standards/editorconfig)     | Editor-level whitespace rules                                                                   |
 | direnv + nvm         | [`.envrc` / `.nvmrc`](/Standards/direnv)       | Automatic Node version switching on `cd`                                                        |
-| Conventional Commits | [Commit spec](/Standards/conventional-commits) | Commit message format and tooling                                                               |
-| Branch Naming        | [Branch names](/Standards/branch-naming)       | `type/short-description` branch names                                                           |
 | AGENTS.md            | [`AGENTS.md`](/Standards/agent-specs)          | AI agent context and agent skills                                                               |
 | CSS Styling          | [Styling guide](/Standards/styling)            | Tailwind CSS, flexbox-first layout and global colour variables                                  |
 | Tech Stack           | [Tech stack](/Standards/tech-stack)            | The frameworks, libraries and versions we build on                                              |