@activatus/code-standards 3.0.1 → 3.0.4

package/docs/Standards/readable-code.md

@@ -8,28 +8,28 @@ Every file must be readable by a person who has never seen it before. Code is re
 
 ## The rules
 
-| Rule                                                                                                | Enforced by                                                   |
-| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| [No file longer than 300 lines](#no-file-longer-than-300-lines)                                     | ESLint `max-lines` (test files exempt)                        |
-| [Names are full English words](/Standards/human-readable-names) — everywhere, including form fields | ESLint for code names; code review and AI agents for the rest |
-| [Arrow functions everywhere](#arrow-functions-everywhere)                                           | ESLint `func-style`, `prefer-arrow-callback`                  |
-| [Always `const`](#always-const)                                                                     | ESLint `no-restricted-syntax`, `prefer-const`, `no-var`       |
-| [A function does one thing](#a-function-does-one-thing)                                             | Code review                                                   |
-| [Every function and component has a test file](#every-function-and-component-has-a-test-file)       | Developers and AI agents — not linted                         |
-| [Functions, never classes](#functions-never-classes)                                                | ESLint `no-restricted-syntax`                                 |
-| [Return early, nest shallow](#return-early-nest-shallow)                                            | ESLint `max-depth`                                            |
-| [No magic numbers or strings](#no-magic-numbers-or-strings)                                         | ESLint `no-magic-numbers` (numbers), code review (strings)    |
-| [One parameter; always an object for more](#one-parameter-always-an-object-for-more)                | ESLint `no-restricted-syntax`                                 |
-| [No nested ternaries](#no-nested-ternaries)                                                         | ESLint `no-nested-ternary`                                    |
-| [No boolean flag parameters](#no-boolean-flag-parameters)                                           | Code review                                                   |
-| [Comments explain why, not what](#comments-explain-why-not-what)                                    | Code review                                                   |
-| [No `any`, no `!`, no unexplained `as`](#no-any-no--no-unexplained-as)                              | ESLint `@typescript-eslint` rules                             |
-| [One component per file](#one-component-per-file)                                                   | ESLint `react/no-multi-comp`                                  |
-| [Named exports only](#named-exports-only)                                                           | ESLint `import-x/no-default-export`                           |
-| [Type names say what they are](#type-names-say-what-they-are)                                       | ESLint `@typescript-eslint/naming-convention`                 |
-| [Error messages say what happened and what to do](#error-messages-say-what-happened-and-what-to-do) | Code review                                                   |
-
-See the [ESLint configuration](/Standards/eslint) for the rule setup, and [Fixing Lint Errors](/Standards/lint-errors) for what each error means and how to fix it.
+| Rule                                                                                                     | Enforced by                                                   |
+| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| [No file longer than 300 lines](#no-file-longer-than-300-lines)                                          | ESLint `max-lines` (test files exempt)                        |
+| [Names are full English words](/docs/Standards/human-readable-names) — everywhere, including form fields | ESLint for code names; code review and AI agents for the rest |
+| [Arrow functions everywhere](#arrow-functions-everywhere)                                                | ESLint `func-style`, `prefer-arrow-callback`                  |
+| [Always `const`](#always-const)                                                                          | ESLint `no-restricted-syntax`, `prefer-const`, `no-var`       |
+| [A function does one thing](#a-function-does-one-thing)                                                  | Code review                                                   |
+| [Every function and component has a test file](#every-function-and-component-has-a-test-file)            | Developers and AI agents — not linted                         |
+| [Functions, never classes](#functions-never-classes)                                                     | ESLint `no-restricted-syntax`                                 |
+| [Return early, nest shallow](#return-early-nest-shallow)                                                 | ESLint `max-depth`                                            |
+| [No magic numbers or strings](#no-magic-numbers-or-strings)                                              | ESLint `no-magic-numbers` (numbers), code review (strings)    |
+| [One parameter; always an object for more](#one-parameter-always-an-object-for-more)                     | ESLint `no-restricted-syntax`                                 |
+| [No nested ternaries](#no-nested-ternaries)                                                              | ESLint `no-nested-ternary`                                    |
+| [No boolean flag parameters](#no-boolean-flag-parameters)                                                | Code review                                                   |
+| [Comments explain why, not what](#comments-explain-why-not-what)                                         | Code review                                                   |
+| [No `any`, no `!`, no unexplained `as`](#no-any-no--no-unexplained-as)                                   | ESLint `@typescript-eslint` rules                             |
+| [One component per file](#one-component-per-file)                                                        | ESLint `react/no-multi-comp`                                  |
+| [Named exports only](#named-exports-only)                                                                | ESLint `import-x/no-default-export`                           |
+| [Type names say what they are](#type-names-say-what-they-are)                                            | ESLint `@typescript-eslint/naming-convention`                 |
+| [Error messages say what happened and what to do](#error-messages-say-what-happened-and-what-to-do)      | Code review                                                   |
+
+See the [ESLint configuration](/docs/Standards/eslint) for the rule setup, and [Fixing Lint Errors](/docs/Standards/lint-errors) for what each error means and how to fix it.
 
 ---
 
@@ -37,8 +37,8 @@ See the [ESLint configuration](/Standards/eslint) for the rule setup, and [Fixin
 
 A file over 300 lines is doing more than one job. Split it before it gets there:
 
-- Move reusable functions into a [utils folder](/Structure/folder-structure#-utils)
-- Move sub-components into [their own folders](/Structure/component-organization#nested-components)
+- Move reusable functions into a [utils folder](/docs/Structure/folder-structure#-utils)
+- Move sub-components into [their own folders](/docs/Structure/component-organization#nested-components)
 - Move types into `types.ts`
 
 Blank lines and comments do not count towards the limit. **Test files are exempt** — a thorough test file can run long.
@@ -49,7 +49,7 @@ Blank lines and comments do not count towards the limit. **Test files are exempt
 
 **Every name in the project is made of whole, human-readable words** — not just variables, but folders, files, props, form fields, types, database columns, environment variables, everything.
 
-This rule has its own page, because it applies everywhere: **[Human-Readable Names](/Standards/human-readable-names)**. Read it in full.
+This rule has its own page, because it applies everywhere: **[Human-Readable Names](/docs/Standards/human-readable-names)**. Read it in full.
 
 ---
 
@@ -87,7 +87,7 @@ export const formatCurrency = function (amount: number) {
 
 Three things to know:
 
-- **Define before use.** An arrow function is written above the code that uses it. This is [enforced](/Structure/import-organization#3-define-before-use), and it means a mistake fails straight away instead of being hidden.
+- **Define before use.** An arrow function is written above the code that uses it. This is [enforced](/docs/Structure/import-organization#3-define-before-use), and it means a mistake fails straight away instead of being hidden.
 - **Generic components need a trailing comma** in `.tsx` files, so the type parameter is not read as JSX: `const List = <ItemType,>({ items }: ListProps<ItemType>) => { … }`.
 - **Next.js files that need a default export** take two lines:
 
@@ -194,7 +194,7 @@ utils/
 └── index.ts
 ```
 
-See [Utils](/Structure/folder-structure#-utils) for the folder layout and the `index.ts` files.
+See [Utils](/docs/Structure/folder-structure#-utils) for the folder layout and the `index.ts` files.
 
 ```ts title="utils/formatCurrency/formatCurrency.test.ts"
 import { describe, expect, it } from "vitest";
@@ -212,7 +212,7 @@ describe("formatCurrency", () => {
 });
 ```
 
-Components keep their test beside the component file (`button/Button.tsx` and `button/Button.test.tsx`) — see [Component Organization](/Structure/component-organization).
+Components keep their test beside the component file (`button/Button.tsx` and `button/Button.test.tsx`) — see [Component Organization](/docs/Structure/component-organization).
 
 ---
 
@@ -309,7 +309,7 @@ if (order.status === "shipped") {
 }
 ```
 
-`-1`, `0` and `1` are allowed. See [Naming Conventions](/Structure/naming-conventions#constants) for how to name constants.
+`-1`, `0` and `1` are allowed. See [Naming Conventions](/docs/Structure/naming-conventions#constants) for how to name constants.
 
 ---
 
@@ -451,13 +451,13 @@ const getUserName = (user: any) => {
 };
 ```
 
-`as const` is fine. See the [ESLint configuration](/Standards/eslint#typescript-eslintconsistent-type-assertions-never) for how to record the reason for a cast.
+`as const` is fine. See the [ESLint configuration](/docs/Standards/eslint#typescript-eslintconsistent-type-assertions-never) for how to record the reason for a cast.
 
 ---
 
 ## One component per file
 
-A file holds one component. A second component — however small — gets [its own folder](/Structure/component-organization#nested-components).
+A file holds one component. A second component — however small — gets [its own folder](/docs/Structure/component-organization#nested-components).
 
 ---
 
@@ -523,33 +523,70 @@ Use a named type instead of a bare `string` wherever the value has a fixed set o
 
 ### 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.
+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 that field inside the `Props`.
+
+**Every function still gets its own `Props` type** for its single object parameter, named after the function: `launchSession` takes `LaunchSessionProps`. Use it wherever that function is written, so its parameters always have a type.
 
 ```ts
-// ✅ Good — the dependencies are written inside the one Props type
+// ✅ Good — each function has its own Props; the dependencies are written inside StartAgentRunProps
+interface LaunchSessionProps {
+  worktreePath: string;
+}
+
 interface StartAgentRunProps {
   ticketId: string;
   dependencies: {
-    launchSession: (ticketId: string) => Promise<void>;
-    reportStatus: (status: AgentRunStatusType) => void;
+    launchSession: (props: LaunchSessionProps) => Promise<void>;
   };
 }
+
+const dependencies = {
+  launchSession: async ({ worktreePath }: LaunchSessionProps) =>
+    openTerminal(worktreePath),
+};
 ```
 
 ```ts
-// ❌ Bad — a second type named after the role it plays in one function
+// ❌ Bad — a wrapper type named after the role it plays in one function
 interface StartAgentRunDependenciesType {
-  launchSession: (ticketId: string) => Promise<void>;
-  reportStatus: (status: AgentRunStatusType) => void;
+  launchSession: (props: LaunchSessionProps) => Promise<void>;
 }
 
-interface StartAgentRunProps {
-  ticketId: string;
-  dependencies: StartAgentRunDependenciesType;
-}
+// ❌ Bad — no type: worktreePath is an implicit any, and the type check fails
+const dependencies = {
+  launchSession: async ({ worktreePath }) => openTerminal(worktreePath),
+};
+
+// ❌ Bad — the type is written out inline instead of using LaunchSessionProps
+const dependencies = {
+  launchSession: async ({ worktreePath }: { worktreePath: string }) =>
+    openTerminal(worktreePath),
+};
 ```
 
-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.
+### Type first, never `satisfies`
+
+**A value gets its type where it is declared**, and the value is written to match. Never write the value first and attach the type afterwards with `satisfies`.
+
+```ts
+// ✅ Good — the type comes first
+const config: ConfigType = {
+  name: "Activatus",
+  retries: MAXIMUM_RETRY_ATTEMPTS,
+};
+```
+
+```ts
+// ❌ Bad — the type is attached after the fact
+const config = {
+  name: "Activatus",
+  retries: MAXIMUM_RETRY_ATTEMPTS,
+} satisfies ConfigType;
+```
+
+ESLint reports `satisfies` as an error.
+
+**Story files are the one exception.** Storybook's own docs type stories with `satisfies Meta<typeof Component>`, because it lets Storybook see which props are already set for every story, so each story only sets the props that change. Story files (`*.stories.tsx`) follow Storybook's docs as they are, and ESLint allows `satisfies` there. See [Storybook stories](/docs/Structure/component-organization#-componentstoriestsx).
 
 ---
 

package/docs/Standards/stylelint.md

@@ -5,7 +5,7 @@ sidebar_label: "Stylelint"
 
 # Stylelint Configuration
 
-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:
+Components are styled with [Tailwind CSS](/docs/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                                  |
 | --------------------------------------- | ----------------------------------------- |
@@ -151,7 +151,7 @@ Enforces `rgb(255 0 0 / 50%)` instead of `rgba(255, 0, 0, 0.5)`. The modern synt
 
 ### `ignoreFiles`: third-party code is exempt
 
-CSS in a `vendor/` folder is not ours, so it is not linted. See [Third-party code is exempt](/Standards/eslint#third-party-code-is-exempt).
+CSS in a `vendor/` folder is not ours, so it is not linted. See [Third-party code is exempt](/docs/Standards/eslint#third-party-code-is-exempt).
 
 ### Tailwind: `import-notation: "string"` and `at-rule-no-unknown`
 
@@ -159,11 +159,11 @@ CSS in a `vendor/` folder is not ours, so it is not linted. See [Third-party cod
 
 ### Custom properties: kebab-case
 
-`stylelint-config-standard` requires CSS variables to be kebab-case (`--color-brand-primary`). See [CSS Styling](/Standards/styling#css-variables).
+`stylelint-config-standard` requires CSS variables to be kebab-case (`--color-brand-primary`). See [CSS Styling](/docs/Standards/styling#css-variables).
 
 ### CSS Modules: `color-named: never` and `color-no-hex`
 
-Colours come from the [global colour variables](/Standards/styling#-colours-always-come-from-global-variables). A CSS Module may not contain `white` or `#3b82f6` — it references `var(--color-white)` or `var(--color-brand-primary)`. Colour values are only written in `globals.css`.
+Colours come from the [global colour variables](/docs/Standards/styling#-colours-always-come-from-global-variables). A CSS Module may not contain `white` or `#3b82f6` — it references `var(--color-white)` or `var(--color-brand-primary)`. Colour values are only written in `globals.css`.
 
 ### CSS Modules: `selector-class-pattern: camelCase`
 

package/docs/Standards/styling.md

@@ -10,7 +10,7 @@ Standards for styling React components and applications.
 
 ## 🎨 Tailwind CSS
 
-Use Tailwind CSS utility classes for all component styling. Tailwind is compatible with React Server Components and is the foundation [shadcn/ui](/Guides/component-library-workflow) is built on.
+Use Tailwind CSS utility classes for all component styling. Tailwind is compatible with React Server Components and is the foundation [shadcn/ui](/docs/Guides/component-library-workflow) is built on.
 
 ```tsx
 // Button.tsx
@@ -94,7 +94,7 @@ export const PageHeader = () => {
 
 - **Flex first.** `flex`, `flex-col`, `gap-*`, `items-*` and `justify-*` cover almost every layout.
 - **The parent positions, the child styles itself.** A parent sets direction, spacing and alignment. Each child component owns its own padding, colour and typography.
-- **Split into child components** rather than growing one long `className` or a deep tree of `div`s. Each child gets [its own folder](/Structure/component-organization#nested-components).
+- **Split into child components** rather than growing one long `className` or a deep tree of `div`s. Each child gets [its own folder](/docs/Structure/component-organization#nested-components).
 - **Space with `gap`**, not margins on the children.
 - **Grid only when asked.** Do not choose CSS grid on your own — use it only when the task specifically asks for a grid.
 
@@ -149,7 +149,7 @@ Each project defines its colours once, in its global stylesheet:
 
 Tailwind turns every `--color-*` variable in `@theme` into utility classes: `--color-brand-primary` becomes `bg-brand-primary`, `text-brand-primary`, `border-brand-primary` and so on.
 
-The project's design decisions — what each colour is for, the fonts, the spacing — are recorded in its `docs/design/design-system.md` [Decision Doc](/Standards/documentation).
+The project's design decisions — what each colour is for, the fonts, the spacing — are recorded in its `docs/design/design-system.md` [Decision Doc](/docs/Standards/documentation).
 
 ### ✅ Use the colours
 
@@ -192,7 +192,7 @@ Tailwind's built-in colours are variables too — `white` is `var(--color-white)
 - **Colours**: Global palette only — Tailwind colours and project colours from `@theme` — never arbitrary values
 - **Long class lists**: Extract a component, not a CSS class
 - **Conditional classes**: Use `clsx`
-- **Class order**: Sorted automatically by [Prettier](/Standards/prettier#tailwind-class-sorting) — do not sort by hand
+- **Class order**: Sorted automatically by [Prettier](/docs/Standards/prettier#tailwind-class-sorting) — do not sort by hand
 
 ### Global CSS
 
@@ -284,7 +284,7 @@ Name colours by **role**, not by value: `--color-brand-primary`, not `--color-bl
 
 ## 📚 Related Documentation
 
-- [Stylelint](/Standards/stylelint) - Linting for hand-written CSS
-- [Component Organization](/Structure/component-organization) - How to organize component files
-- [Folder Structure](/Structure/folder-structure) - Overall project structure
-- [Naming Conventions](/Structure/naming-conventions) - File and folder naming rules
+- [Stylelint](/docs/Standards/stylelint) - Linting for hand-written CSS
+- [Component Organization](/docs/Structure/component-organization) - How to organize component files
+- [Folder Structure](/docs/Structure/folder-structure) - Overall project structure
+- [Naming Conventions](/docs/Structure/naming-conventions) - File and folder naming rules

package/docs/Standards/tech-stack.md

@@ -70,7 +70,7 @@ already contributes `_uid`, `component` and `_editable`, and a hand-written copy
 the moment the library changes.
 
 Read every library generic this way. An unparameterised one with a permissive default is
-usually a silent `any`, not a sensible fallback. The [`/typescript` skill](/Standards/agent-skills)
+usually a silent `any`, not a sensible fallback. The [`/typescript` skill](/docs/Standards/agent-skills)
 applies this as a rule.
 
 ---

package/docs/Structure/api-routes.md

@@ -113,6 +113,6 @@ app/api/
 
 ## 📚 Related Documentation
 
-- [Folder Structure](/Structure/folder-structure) - Overall project structure
-- [Naming Conventions](/Structure/naming-conventions) - File and folder naming
-- [TypeScript](/Standards/tech-stack) - Type safety standards
+- [Folder Structure](/docs/Structure/folder-structure) - Overall project structure
+- [Naming Conventions](/docs/Structure/naming-conventions) - File and folder naming
+- [TypeScript](/docs/Standards/tech-stack) - Type safety standards

package/docs/Structure/component-organization.md

@@ -103,7 +103,7 @@ describe('Button', () => {
 
 ### 📖 `Component.stories.tsx`
 
-Storybook stories for documentation and visual testing.
+Storybook stories for documentation and visual testing. Written the way [Storybook's docs](https://storybook.js.org/docs/writing-stories) write them, with `satisfies Meta<typeof Component>`: it is the one place `satisfies` is allowed. See [Type first, never `satisfies`](/docs/Standards/readable-code#type-first-never-satisfies).
 
 ```typescript
 // Button.stories.tsx
@@ -113,10 +113,11 @@ import { Button } from "./Button";
 const meta = {
   title: "Components/Button",
   component: Button,
+  args: { variant: "primary" },
 } satisfies Meta<typeof Button>;
 
 export default meta;
-type StoryType = StoryObj<typeof Button>;
+type StoryType = StoryObj<typeof meta>;
 
 export const Primary: StoryType = {
   args: {
@@ -156,16 +157,16 @@ export type { ButtonProps } from "./types";
 
 Every component file is laid out in the same order, so a reader always knows where to look.
 
-| #   | Section               | Rule                                                                                                                                                                                                                |
-| --- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | Imports               | Ordered per [Import Organization](/Structure/import-organization)                                                                                                                                                   |
-| 2   | Component             | The component is the first thing in the file after the imports. Always an [arrow function](/Standards/readable-code#arrow-functions-everywhere) — [never a class](/Standards/readable-code#functions-never-classes) |
-| 3   | Variable declarations | Plain values worked out from props                                                                                                                                                                                  |
-| 4   | State declarations    | `useState`, `useReducer`, `useRef`                                                                                                                                                                                  |
-| 5   | Calculated values     | Wrapped in `useMemo`                                                                                                                                                                                                |
-| 6   | Nested functions      | Only functions that need the component's state or props, wrapped in `useCallback`                                                                                                                                   |
-| 7   | Effects               | `useEffect`                                                                                                                                                                                                         |
-| 8   | Render logic          | The `return`. No inline functions                                                                                                                                                                                   |
+| #   | Section               | Rule                                                                                                                                                                                                                          |
+| --- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | Imports               | Ordered per [Import Organization](/docs/Structure/import-organization)                                                                                                                                                        |
+| 2   | Component             | The component is the first thing in the file after the imports. Always an [arrow function](/docs/Standards/readable-code#arrow-functions-everywhere) — [never a class](/docs/Standards/readable-code#functions-never-classes) |
+| 3   | Variable declarations | Plain values worked out from props                                                                                                                                                                                            |
+| 4   | State declarations    | `useState`, `useReducer`, `useRef`                                                                                                                                                                                            |
+| 5   | Calculated values     | Wrapped in `useMemo`                                                                                                                                                                                                          |
+| 6   | Nested functions      | Only functions that need the component's state or props, wrapped in `useCallback`                                                                                                                                             |
+| 7   | Effects               | `useEffect`                                                                                                                                                                                                                   |
+| 8   | Render logic          | The `return`. No inline functions                                                                                                                                                                                             |
 
 ### Example
 
@@ -230,7 +231,7 @@ export const UserListClient = ({
 
 ### Keep the UI file clean
 
-**If a function can be written in another file, move it out of the UI file.** A function that does not need the component's state or props is not a nested function — it belongs in a [utils folder](/Structure/folder-structure#-utils).
+**If a function can be written in another file, move it out of the UI file.** A function that does not need the component's state or props is not a nested function — it belongs in a [utils folder](/docs/Structure/folder-structure#-utils).
 
 `filterUsersByName` above only needs its arguments, so it lives in the component's `utils/` folder, in its own folder beside its test file:
 
@@ -326,7 +327,7 @@ export const UserListItem = ({
 - **`useMemo`** for any value calculated from props or state (filtering, sorting, totals)
 - **`useCallback`** for every function passed to a child component or a JSX prop
 
-ESLint enforces the function half of this with `react/jsx-no-bind` — see the [ESLint configuration](/Standards/eslint#reactjsx-no-bind-error).
+ESLint enforces the function half of this with `react/jsx-no-bind` — see the [ESLint configuration](/docs/Standards/eslint#reactjsx-no-bind-error).
 
 ---
 
@@ -381,13 +382,13 @@ export const UserListClient = ({ users }: UserListClientProps) => {
 
 ## Reusable by design
 
-Every component in `components/ui/` is built so it can be copied into another project unchanged: everything comes in through props, and it imports nothing from the project's features, services, stores or `app/` folder. Before building one, [look before you build](/Guides/component-library-workflow#1-look-before-you-build), and build it to the props in the [Design System Components](/design-system-components). See [Future-proofing](/Guides/component-library-workflow#future-proofing).
+Every component in `components/ui/` is built so it can be copied into another project unchanged: everything comes in through props, and it imports nothing from the project's features, services, stores or `app/` folder. Before building one, [look before you build](/docs/Guides/component-library-workflow#1-look-before-you-build), and build it to the props in the [Design System Components](/docs/design-system-components). See [Future-proofing](/docs/Guides/component-library-workflow#future-proofing).
 
 ---
 
 ## Components from shadcn
 
-A component added with the shadcn CLI is **our code** and follows everything on this page. Convert it when it is added: its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test file. See [Adding a shadcn component](/Guides/component-library-workflow#adding-a-shadcn-component).
+A component added with the shadcn CLI is **our code** and follows everything on this page. Convert it when it is added: its own camelCase folder, one component per file, `types.ts`, `index.ts` and a test file. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
 
 ---
 
@@ -458,7 +459,7 @@ export type { CardProps } from "./types";
 
 ### Within the Same Folder
 
-Inside a component's folder, import files directly. **Never import through the folder's own `index.ts`**, and never import the parent component from a sub-component — both create a [circular import](/Structure/import-organization#import-safety).
+Inside a component's folder, import files directly. **Never import through the folder's own `index.ts`**, and never import the parent component from a sub-component — both create a [circular import](/docs/Structure/import-organization#import-safety).
 
 ```typescript
 // card/Card.tsx — the parent imports its sub-components
@@ -514,7 +515,7 @@ app/
     └── page.tsx
 ```
 
-See [Where components live](/Structure/folder-structure#-where-components-live) for every location.
+See [Where components live](/docs/Structure/folder-structure#-where-components-live) for every location.
 
 ---
 

package/docs/Structure/folder-structure.md

@@ -65,7 +65,11 @@ project-root/
 │   │   ├── rateLimit.ts
 │   │   └── session.ts
 │   ├── validation/                                  # Schemas that check input
-│   ├── constants/                                   # Constants shared across the app
+│   ├── constants/                                   # Constants shared across the app: see Constants below
+│   │   ├── routes.ts                                # r: every link
+│   │   ├── strings.ts                               # s: every piece of static text
+│   │   ├── noData.ts                                # Stand-in data for local development
+│   │   └── index.ts
 │   ├── 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
@@ -131,12 +135,12 @@ project-root/
 
 **A component lives where it is used.** There are no feature folders: a component either belongs to one page, to one section, or is shared.
 
-| Used by                                                                                    | Lives in                                             | Example                                        |
-| ------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ---------------------------------------------- |
-| **Every project the same way** — the [Design System Components](/design-system-components) | `components/ui/`                                     | `components/ui/button/`                        |
-| **More than one page** of this project                                                     | `components/shared/`                                 | `components/shared/siteHeader/`                |
-| **A few pages in one section**                                                             | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/`       |
-| **One page only**                                                                          | A `components/` folder in that page's route folder   | `app/account-settings/components/accountForm/` |
+| Used by                                                                                         | Lives in                                             | Example                                        |
+| ----------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------- |
+| **Every project the same way** — the [Design System Components](/docs/design-system-components) | `components/ui/`                                     | `components/ui/button/`                        |
+| **More than one page** of this project                                                          | `components/shared/`                                 | `components/shared/siteHeader/`                |
+| **A few pages in one section**                                                                  | A `components/` folder in that section's route group | `app/(billing)/components/invoiceTable/`       |
+| **One page only**                                                                               | A `components/` folder in that page's route folder   | `app/account-settings/components/accountForm/` |
 
 A route group is a folder in brackets, such as `(billing)`. It groups pages without changing their URLs: `app/(billing)/invoices/page.tsx` is served at `/invoices`.
 
@@ -168,7 +172,7 @@ project-root/
 ### Rules
 
 - **Start where it is used, and move it when it is shared.** A new component goes in its page's `components/` folder. When a second page in the same section needs it, move it to the section's `components/` folder. When a page in another section needs it, move it to `components/shared/`.
-- **`components/ui/` is only for [Design System Components](/design-system-components).** They take everything through props and import nothing from the project, so they can be copied into another project unchanged. See [Reusable by design](/Structure/component-organization#reusable-by-design).
+- **`components/ui/` is only for [Design System Components](/docs/design-system-components).** They take everything through props and import nothing from the project, so they can be copied into another project unchanged. See [Reusable by design](/docs/Structure/component-organization#reusable-by-design).
 - **A page or shared component wraps Design System Components.** It holds this project's logic and data, and passes props down.
 - **Never group by type** (`atoms/`, `molecules/`, `organisms/`). Group by where a component is used.
 
@@ -262,9 +266,103 @@ Add the export to `utils/index.ts` whenever you add a function.
 
 - **Start local, promote when shared.** A function begins in the component's `utils/`. When another component in the same section needs it, move its folder to the section's `utils/`. When anything outside the section needs it, move it to the global `utils/`.
 - **One function per folder**, with the folder and file named after the function (`formatCurrency/formatCurrency.ts`), plus its test file and an `index.ts`.
-- **Every function has a test file** in the same folder. See [Readable Code](/Standards/readable-code#every-function-and-component-has-a-test-file).
+- **Every function has a test file** in the same folder. See [Readable Code](/docs/Standards/readable-code#every-function-and-component-has-a-test-file).
 - **Import from the `utils` folder**, never from the files inside it.
-- **Keep UI files clean.** If a function could be written in another file, it does not belong in the component file. See [Writing a component](/Structure/component-organization#-writing-a-component).
+- **Keep UI files clean.** If a function could be written in another file, it does not belong in the component file. See [Writing a component](/docs/Structure/component-organization#-writing-a-component).
+
+---
+
+## 🔤 Constants: `r`, `s` and noData {#constants}
+
+Every link, every piece of text on screen and every piece of stand-in data lives in `lib/constants/`, never written straight into a component:
+
+```text
+lib/constants/
+├── routes.ts      # r: every link
+├── strings.ts     # s: every piece of static text
+├── noData.ts      # Stand-in data for local development
+└── index.ts       # Exports all of them
+```
+
+A file outside the folder imports everything it needs in one line:
+
+```tsx
+import { NO_DATA_INSIGHTS, r, s } from "@/lib/constants";
+
+<a href={r.contact}>{s.contact}</a>;
+```
+
+### `r`: routes
+
+**`r` holds every link the app uses**: its own pages, outside sites, and `mailto:`, `tel:` and `sms:` links.
+
+```ts title="lib/constants/routes.ts"
+export const r = {
+	contact: "/contact",
+	email: "mailto:mail@example.com",
+	insights: "/insights",
+	linkedIn: "https://www.linkedin.com/in/example",
+	sms: "sms:+61400000000",
+};
+```
+
+- **A dynamic route starts from its `r` route.** Build the changing part where it is used: `` `${r.insights}/${insight.slug}` ``.
+- **Name each key after the place it goes**, in camelCase: `r.myStory`, `r.linkedIn`.
+
+### `s`: strings
+
+**`s` holds every piece of static text** shown on screen: headings, buttons, labels, aria-labels, page titles and descriptions, and longer Markdown copy.
+
+```ts title="lib/constants/strings.ts"
+export const s = {
+	contact: "CONTACT",
+	emailAriaLabel: "Email Tom",
+	pageNotFound: "PAGE NOT FOUND",
+	pageNotFoundDescription:
+		"The page you are looking for does not exist",
+};
+```
+
+- **The keys of `s` are the site's translation keys.** When a site gets more languages, each key is translated into each language. Name each key after what the text says or does, and never use one key for two different jobs.
+- **Only real copy goes in `s`.** Dummy text belongs in `noData.ts`.
+
+### noData: stand-in data for local development
+
+**`noData.ts` stands in for outside data while you work locally**, when the CMS, database or API can't be reached, such as when you have no internet. Every page still renders with something that looks real.
+
+```ts title="lib/constants/noData.ts"
+const DUMMY_HEADING = "A heading for local development";
+const DUMMY_SLUG = "/insights";
+
+export const NO_DATA_INSIGHT = {
+	heading: DUMMY_HEADING,
+	slug: DUMMY_SLUG,
+};
+
+export const NO_DATA_INSIGHTS = [NO_DATA_INSIGHT];
+```
+
+```ts
+const insights =
+	query?.insights ??
+	(IS_LOCAL_DEVELOPMENT ? NO_DATA_INSIGHTS : []);
+```
+
+`IS_LOCAL_DEVELOPMENT` is a constant in `lib/constants/`: `export const IS_LOCAL_DEVELOPMENT = process.env.NODE_ENV === "development";`.
+
+- **Local development only.** noData is never shown in production. Where the real data is missing in production, show the page's empty state.
+- **Name each export `NO_DATA_` plus the exact thing it stands in for**: singular for one item, plural for a list. `NO_DATA_INSIGHT` and `NO_DATA_INSIGHTS`, `NO_DATA_EVENT`, `NO_DATA_TOPICS`.
+- **Shape it exactly like the real response**, so the code using it cannot tell the difference.
+- **Dummy values sit at the top of `noData.ts`** as their own constants, `DUMMY_HEADING` and the rest. They are never added to `s`.
+- **noData is for the whole site.** All of it lives in this one file.
+
+### Rules
+
+- **Named exports only:** `export const r`, `export const s`. No default exports.
+- **Files outside `lib/constants/` import from `@/lib/constants`**, all in one import line.
+- **Files inside `lib/constants/` import each other directly**, `import { s } from "./strings";`, never through `index.ts`. See [Inside a folder, import files directly](/docs/Structure/import-organization#2-inside-a-folder-import-files-directly).
+- **`r` and `s` are the only single-letter names allowed anywhere.** See [Human-Readable Names](/docs/Standards/human-readable-names#r-and-s).
+- **Other constants** that hold a single value, such as `MAXIMUM_RETRY_ATTEMPTS`, follow [Naming Conventions](/docs/Structure/naming-conventions#constants).
 
 ---
 
@@ -310,7 +408,7 @@ project-root/
 └── docsSite/                # The viewer: Docusaurus config, no content
 ```
 
-See [Documentation](/Standards/documentation) for the full list of folders, the doc format, and how docs are displayed and kept up to date.
+See [Documentation](/docs/Standards/documentation) for the full list of folders, the doc format, and how docs are displayed and kept up to date.
 
 Name documentation folders and files in **kebab-case** (`background-jobs.md`), not camelCase (`backgroundJobs.md`). The name becomes the page's URL on the docs site.
 
@@ -345,7 +443,7 @@ Avoid these anti-patterns:
 
 ## 📚 Naming Conventions
 
-See [Naming Conventions](/Structure/naming-conventions) for detailed file and folder naming rules.
+See [Naming Conventions](/docs/Structure/naming-conventions) for detailed file and folder naming rules.
 
 **Quick reference:**