@activatus/code-standards 3.0.2 → 3.0.5

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,124 @@ 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`, noData and numbers {#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
+├── durations.ts   # Shared numbers, one file per topic
+└── 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.
+
+### Numbers: named, and kept by topic
+
+**A number other than `-1`, `0` or `1` gets a name**, such as `MAXIMUM_RETRY_ATTEMPTS`. Those three mean "nothing", "one more" and "not found", so they read clearly as they are. Any other number was chosen by someone, and its name says what it controls. ESLint checks this with `no-magic-numbers`.
+
+There is no `n` object. Text and links are one kind of thing each, but numbers are not: a retry limit, a cookie lifetime and a page size have nothing in common. Put each number where its meaning lives:
+
+| Used by            | Where it goes                                     | Example                                                                                |
+| ------------------ | ------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| One file           | At the top of that file                           | `const MAXIMUM_NESTING_DEPTH = 3;` in `eslint.config.mjs`                              |
+| More than one file | `lib/constants/`, in a file named after its topic | `lib/constants/durations.ts`, `lib/constants/limits.ts`, `lib/constants/httpStatus.ts` |
+
+```ts title="lib/constants/durations.ts"
+export const COOKIE_DURATION_DAYS = 30;
+export const SESSION_TIMEOUT_MILLISECONDS = 900_000;
+```
+
+- **Start in the file that uses it**, and move it to `lib/constants/` when a second file needs it.
+- **Never a `numbers.ts`** or any other file of unrelated values. Name the file after the topic.
+- **Put the unit in the name**: `_MILLISECONDS`, `_DAYS`, `_PIXELS`.
+
+### 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**, such as numbers, are `SCREAMING_SNAKE_CASE`: see [Naming Conventions](/docs/Structure/naming-conventions#constants).
 
 ---
 
@@ -310,7 +429,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 +464,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:**
 

package/docs/Structure/naming-conventions.md

@@ -6,9 +6,9 @@ sidebar_position: 5
 
 Consistent naming conventions make codebases easier to navigate, understand, and maintain.
 
-**Every name must be human-readable** — folders, files, props, form fields, types, database columns, everything. See [Human-Readable Names](/Standards/human-readable-names).
+**Every name must be human-readable** — folders, files, props, form fields, types, database columns, everything. See [Human-Readable Names](/docs/Standards/human-readable-names).
 
-This page covers **how** a name is written. **Which words** to use comes from the [Ontology](/ontology): a Decision Doc is `decisionDoc` in code and `decision_doc` in the database, never `docDecision` or `decisionFile`.
+This page covers **how** a name is written. **Which words** to use comes from the [Ontology](/docs/ontology): a Decision Doc is `decisionDoc` in code and `decision_doc` in the database, never `docDecision` or `decisionFile`.
 
 ## File Naming
 
@@ -154,6 +154,8 @@ const apiTimeout = 5000;
 const cookieDays = 30;
 ```
 
+**`r` and `s` are the exception:** the routes and strings objects are lowercase single letters, with camelCase keys, `r.myStory` and `s.pageNotFound`. Stand-in data follows the normal rule: `NO_DATA_INSIGHTS`. See [Constants](/docs/Structure/folder-structure#constants).
+
 ### CSS Modules
 
 **Use camelCase** with `.module.css` suffix:
@@ -184,11 +186,11 @@ form-components.module.css
 --spacing_unit: 0.25rem;
 ```
 
-See [CSS Styling](/Standards/styling#css-variables).
+See [CSS Styling](/docs/Standards/styling#css-variables).
 
 ### Documentation
 
-**Use kebab-case** for documentation files. The [docs site](/Standards/documentation) turns each file name into the page's URL, so a doc file is named the way a URL is written:
+**Use kebab-case** for documentation files. The [docs site](/docs/Standards/documentation) turns each file name into the page's URL, so a doc file is named the way a URL is written:
 
 ```tsx
 ✅ Good
@@ -208,7 +210,7 @@ ProductMarketFit.md
 
 ### Variables
 
-**Use camelCase**, and [full English words](/Standards/readable-code#names-are-full-english-words) — no shorthand:
+**Use camelCase**, and [full English words](/docs/Standards/readable-code#names-are-full-english-words) — no shorthand:
 
 ```ts
 ✅ Good
@@ -226,7 +228,7 @@ const item_count = 10;
 
 ### Functions
 
-Every function is an [arrow function](/Standards/readable-code#arrow-functions-everywhere).
+Every function is an [arrow function](/docs/Standards/readable-code#arrow-functions-everywhere).
 
 **Use camelCase** with descriptive verbs:
 
@@ -282,7 +284,7 @@ interface api_response { }
 interface UserCardData { }
 ```
 
-See [Readable Code](/Standards/readable-code#type-names-say-what-they-are).
+See [Readable Code](/docs/Standards/readable-code#type-names-say-what-they-are).
 
 ---
 
@@ -331,4 +333,4 @@ Use ESLint and Prettier to enforce these conventions automatically:
 - **simple-import-sort** - Import ordering
 - **@typescript-eslint** - TypeScript naming rules
 
-See [ESLint](/Standards/eslint) and [Prettier](/Standards/prettier) configuration for setup.
+See [ESLint](/docs/Standards/eslint) and [Prettier](/docs/Standards/prettier) configuration for setup.

package/docs/design-system-components.md

@@ -7,15 +7,15 @@ sidebar_label: "Design System Components"
 
 **This page is the contract for how every Activatus component works.** It lists each standard component with its variants and key props.
 
-We do not share component code between projects yet, so this page is what keeps them the same. Every project builds its components to the props listed here. See [Future-proofing](/Guides/component-library-workflow#future-proofing) for why.
+We do not share component code between projects yet, so this page is what keeps them the same. Every project builds its components to the props listed here. See [Future-proofing](/docs/Guides/component-library-workflow#future-proofing) for why.
 
 ## How to use this page
 
 - **Before building a component, look it up here.** If it is listed, build it with these variants and props — the same names, the same meaning. Do not invent your own.
-- **Do not rename, remove or repurpose a listed prop.** Projects differ in how a component looks, never in [how it works](/Guides/component-library-workflow#same-component-different-paint).
+- **Do not rename, remove or repurpose a listed prop.** Projects differ in how a component looks, never in [how it works](/docs/Guides/component-library-workflow#same-component-different-paint).
 - **Building a component that is not listed?** Add it to this page in the same piece of work, so the next project builds it the same way.
 - **A project needs something a listed component does not do?** Add the prop or variant here first, then build it. The reference changes before the code does.
-- **How to write each component** — its folder, files, the order inside the file, tests and stories — is in [Component Organization](/Structure/component-organization). This page says _what_ each component takes; that page says _how_ every component is written.
+- **How to write each component** — its folder, files, the order inside the file, tests and stories — is in [Component Organization](/docs/Structure/component-organization). This page says _what_ each component takes; that page says _how_ every component is written.
 
 This applies to everyone building components, **including AI agents**.
 

package/docs/intro.md

@@ -10,35 +10,35 @@ This site documents the shared code standards used across all Activatus projects
 
 ## What's included
 
-| Standard             | Config                                         | Purpose                                                                                         |
-| -------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------- |
-| Human-Readable Names | [Naming rule](/Standards/human-readable-names) | Every name is whole, readable words — variables, props, form fields, files, folders, everything |
-| Readable Code        | [Readability rules](/Standards/readable-code)  | File length, naming, single-purpose functions and tests                                         |
-| 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.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`                                                        |
-| 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                                              |
-
-Project layout is covered under **Structure**: [folder structure](/Structure/folder-structure), [component organization](/Structure/component-organization), [naming conventions](/Structure/naming-conventions), [import organization](/Structure/import-organization) and [API routes](/Structure/api-routes).
+| Standard             | Config                                              | Purpose                                                                                         |
+| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| Human-Readable Names | [Naming rule](/docs/Standards/human-readable-names) | Every name is whole, readable words — variables, props, form fields, files, folders, everything |
+| Readable Code        | [Readability rules](/docs/Standards/readable-code)  | File length, naming, single-purpose functions and tests                                         |
+| Documentation        | [Docs standard](/docs/Standards/documentation)      | How project docs are written and shown at `/docs`                                               |
+| ESLint               | [`eslint.config.mjs`](/docs/Standards/eslint)       | Linting rules for JS/TS/React/Next.js                                                           |
+| Fixing Lint Errors   | [Error guide](/docs/Standards/lint-errors)          | What each lint error means and how to fix it                                                    |
+| Prettier             | [`prettier.config.mjs`](/docs/Standards/prettier)   | Code formatting                                                                                 |
+| Stylelint            | [`stylelint.config.mjs`](/docs/Standards/stylelint) | Linting rules for CSS/SCSS/CSS Modules                                                          |
+| EditorConfig         | [`.editorconfig`](/docs/Standards/editorconfig)     | Editor-level whitespace rules                                                                   |
+| direnv + nvm         | [`.envrc` / `.nvmrc`](/docs/Standards/direnv)       | Automatic Node version switching on `cd`                                                        |
+| AGENTS.md            | [`AGENTS.md`](/docs/Standards/agent-specs)          | AI agent context and agent skills                                                               |
+| CSS Styling          | [Styling guide](/docs/Standards/styling)            | Tailwind CSS, flexbox-first layout and global colour variables                                  |
+| Tech Stack           | [Tech stack](/docs/Standards/tech-stack)            | The frameworks, libraries and versions we build on                                              |
+
+Project layout is covered under **Structure**: [folder structure](/docs/Structure/folder-structure), [component organization](/docs/Structure/component-organization), [naming conventions](/docs/Structure/naming-conventions), [import organization](/docs/Structure/import-organization) and [API routes](/docs/Structure/api-routes).
 
 ## Ontology
 
-The [Ontology](/ontology) is the shared vocabulary for code: what each code word means. Each project adds its own product words in `docs/product/ontology.md`. Read both first.
+The [Ontology](/docs/ontology) is the shared vocabulary for code: what each code word means. Each project adds its own product words in `docs/product/ontology.md`. Read both first.
 
 ## Version History
 
-The [Version History](/version-history) lists what changed in each version, and what a project has to do about it. Updating a project? Read only the versions newer than the one in its `AGENTS.md`.
+The [Version History](/docs/version-history) lists what changed in each version, and what a project has to do about it. Updating a project? Read only the versions newer than the one in its `AGENTS.md`.
 
 ## For AI agents: you were pointed here
 
-A person has told you to follow the Activatus Code Standards. **Follow [Setup](/Guides/setup) first.** It installs the standards as the `@activatus/code-standards` package, checks which version the project is on, agrees with the person which standards apply, and sets them up. It covers new projects, projects on an older version, and projects that have never followed the standards.
+A person has told you to follow the Activatus Code Standards. **Follow [Setup](/docs/Guides/setup) first.** It installs the standards as the `@activatus/code-standards` package, checks which version the project is on, agrees with the person which standards apply, and sets them up. It covers new projects, projects on an older version, and projects that have never followed the standards.
 
-After setup, follow every agreed standard in every change. Read a page when the work reaches its topic: [Styling](/Standards/styling) before writing styles, [Docs](/Standards/documentation) before writing docs, and so on. The ones to read first are the [Ontology](/ontology), [Human-Readable Names](/Standards/human-readable-names), [Readable Code](/Standards/readable-code), [Folder Structure](/Structure/folder-structure) and [Component Organization](/Structure/component-organization).
+After setup, follow every agreed standard in every change. Read a page when the work reaches its topic: [Styling](/docs/Standards/styling) before writing styles, [Docs](/docs/Standards/documentation) before writing docs, and so on. The ones to read first are the [Ontology](/docs/ontology), [Human-Readable Names](/docs/Standards/human-readable-names), [Readable Code](/docs/Standards/readable-code), [Folder Structure](/docs/Structure/folder-structure) and [Component Organization](/docs/Structure/component-organization).
 
 **If anything here is unclear, ask the person.** Do not guess, and do not invent a rule.

package/docs/ontology.md

@@ -7,7 +7,7 @@ sidebar_label: "Ontology"
 
 > The words these standards use about code, and exactly what each one means.
 
-**Status:** Decided · **Updated:** 2026-10-15
+**Status:** Decided · **Updated:** 2026-10-18
 
 **This page is the source of truth for every word about code.** Every Activatus project uses these terms, with these meanings, in docs, code, prompts and reviews.
 
@@ -50,13 +50,13 @@ The words stay the same everywhere. Only the casing changes, to match where the
 
 ### Docs
 
-| Term           | Means                                                                                                                                                  |
-| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `decision`     | A choice made on purpose and written down, never left implied                                                                                          |
-| `decision_doc` | One Markdown file that records one decision and why it was made. Every file in a project's `docs/` folder is one. See [Docs](/Standards/documentation) |
-| `docs`         | A project's `docs/` folder: its Decision Docs, in the same standard folders in every project                                                           |
-| `docs_site`    | The Docusaurus viewer in `docsSite/` that shows a project's docs at `/docs`. It only runs when `DOCS_URL` is set, which is never in production         |
-| `ontology`     | A shared vocabulary: this page for code words, and the project's own for product words                                                                 |
+| Term           | Means                                                                                                                                                       |
+| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `decision`     | A choice made on purpose and written down, never left implied                                                                                               |
+| `decision_doc` | One Markdown file that records one decision and why it was made. Every file in a project's `docs/` folder is one. See [Docs](/docs/Standards/documentation) |
+| `docs`         | A project's `docs/` folder: its Decision Docs, in the same standard folders in every project                                                                |
+| `docs_site`    | The Docusaurus viewer in `docsSite/` that shows a project's docs at `/docs`. It only runs when `DOCS_URL` is set, which is never in production              |
+| `ontology`     | A shared vocabulary: this page for code words, and the project's own for product words                                                                      |
 
 ### People and agents
 
@@ -65,7 +65,7 @@ The words stay the same everywhere. Only the casing changes, to match where the
 | `human`         | A person, as opposed to an agent                                                                                                                                                                                                              |
 | `developer`     | A human who writes code                                                                                                                                                                                                                       |
 | `agent`         | An AI that writes or checks code, such as Claude Code. It follows every standard a developer does                                                                                                                                             |
-| `agent_spec`    | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/Standards/agent-specs)                                                                                              |
+| `agent_spec`    | A project's `AGENTS.md` file: the first thing an agent reads, setting out how to work on that project. See [Agent Specs](/docs/Standards/agent-specs)                                                                                         |
 | `agent_harness` | Everything around an agent that runs it: the program it runs in (such as Claude Code), its instructions, the tools and permissions it has, and the rules it follows. The ontology says what words mean; the harness says how an agent behaves |
 | `context`       | Everything an agent is given to read for its task: the agent spec, the docs and the code it is working on                                                                                                                                     |
 | `tool`          | One action an agent is allowed to take, such as editing a file or running the tests. Tools come from the agent harness or an MCP server                                                                                                       |
@@ -74,31 +74,32 @@ The words stay the same everywhere. Only the casing changes, to match where the
 
 ### Code
 
-| Term                                    | Means                                                                                                                                                                                                                                                                                                                                                                                   |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `component`                             | One piece of the user interface that does one job. Its file is PascalCase (`InvoiceTable.tsx`) inside a camelCase folder (`invoiceTable/`). See [Component Organization](/Structure/component-organization)                                                                                                                                                                             |
-| `design_system_component`               | A standard component that every project builds the same way, with the same name, variants and props, such as Button or Card. Each one is listed on the [Design System Components](/design-system-components) page and lives in `components/ui/`. It takes everything through props and imports nothing from the project, so it can be copied into another project unchanged             |
-| `shared_component`                      | A component this project uses on more than one page, built from Design System Components. It lives in `components/shared/`                                                                                                                                                                                                                                                              |
-| `page_component`                        | A component used by one page, or by a few pages in one section. It lives in a `components/` folder beside that page, or in the section's route group. See [Where components live](/Structure/folder-structure#-where-components-live)                                                                                                                                                   |
-| `props`                                 | The values a component takes. `props` is a [dictionary word](/Standards/human-readable-names#dictionary). Their type is named after the component and ends in `Props`: `ButtonProps`                                                                                                                                                                                                    |
-| `type`                                  | A TypeScript type or interface. Its name ends in `Props` or `Type`                                                                                                                                                                                                                                                                                                                      |
-| `dependency`                            | Something the code relies on but does not define itself: a package it installs, or the functions handed into a function as its `dependencies`. How tickets wait on each other is not a dependency here: each project names that itself, such as Launchpad's `blocked_by`                                                                                                                |
-| `utils`                                 | Reusable functions that are not components, such as `formatCurrency`. They live in a `utils/` folder: global, for one section, or for one component. Each function has its own folder with its test file and an `index.ts`. `utils` is a [dictionary word](/Standards/human-readable-names#dictionary). Never `helpers` or `utilities`. See [Utils](/Structure/folder-structure#-utils) |
-| `services`                              | The business logic: what the app does, its rules and operations. Pages, API routes and server actions stay thin and call into `services/`. See [utils, services and lib](/Structure/folder-structure#utils-services-and-lib)                                                                                                                                                            |
-| `lib`                                   | Code that connects the app to something outside it, such as integration clients in `lib/integrations/stripe/`, and app-wide setup: permissions, middleware, validation, constants, errors and shared types                                                                                                                                                                              |
-| `route`                                 | A web address in the app, such as `/account-settings` or `/api/calendar-events`, and the folder or file that creates it. Route folders are kebab-case, because their names become the URL. In Next.js, routes are the folders under `app/`. See [API Routes](/Structure/api-routes)                                                                                                     |
-| `server_component` / `client_component` | A component that runs on the server, and one that runs in the browser. They live in separate files, and the server one wraps the client one                                                                                                                                                                                                                                             |
-| `test_file`                             | The file that tests one function or component, named after it: `formatCurrency.test.ts`. Every function and component has one                                                                                                                                                                                                                                                           |
-| `dictionary`                            | The list of short names that are words, not abbreviations: `id`, `docs`, `props`, `utils`, `url` and the rest. A short name not in the [Dictionary](/Standards/human-readable-names#dictionary) is written out in full. A new word is added to the Dictionary before it is used                                                                                                         |
-| `third_party_names`                     | Names that come from someone else's code — a package, a framework or an outside service — such as React's `ref`, Next.js's `params` or shadcn/ui's `cn`. They are used exactly as they are, because renaming them breaks the code. The naming rule is only for names we write. See [Third-party names](/Standards/human-readable-names#third-party-names)                               |
-| `third_party_code`                      | Code we did not write: `node_modules/`, and anything copied into `vendor/`. It is never linted, reformatted or renamed                                                                                                                                                                                                                                                                  |
-| `global_palette`                        | The colours defined in `app/globals.css`. Every colour in a project comes from it. See [Styling](/Standards/styling)                                                                                                                                                                                                                                                                    |
+| Term                                    | Means                                                                                                                                                                                                                                                                                                                                                                                             |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `component`                             | One piece of the user interface that does one job. Its file is PascalCase (`InvoiceTable.tsx`) inside a camelCase folder (`invoiceTable/`). See [Component Organization](/docs/Structure/component-organization)                                                                                                                                                                                  |
+| `design_system_component`               | A standard component that every project builds the same way, with the same name, variants and props, such as Button or Card. Each one is listed on the [Design System Components](/docs/design-system-components) page and lives in `components/ui/`. It takes everything through props and imports nothing from the project, so it can be copied into another project unchanged                  |
+| `shared_component`                      | A component this project uses on more than one page, built from Design System Components. It lives in `components/shared/`                                                                                                                                                                                                                                                                        |
+| `page_component`                        | A component used by one page, or by a few pages in one section. It lives in a `components/` folder beside that page, or in the section's route group. See [Where components live](/docs/Structure/folder-structure#-where-components-live)                                                                                                                                                        |
+| `props`                                 | The values a component takes. `props` is a [dictionary word](/docs/Standards/human-readable-names#dictionary). Their type is named after the component and ends in `Props`: `ButtonProps`                                                                                                                                                                                                         |
+| `type`                                  | A TypeScript type or interface. Its name ends in `Props` or `Type`                                                                                                                                                                                                                                                                                                                                |
+| `dependency`                            | Something the code relies on but does not define itself: a package it installs, or the functions handed into a function as its `dependencies`. How tickets wait on each other is not a dependency here: each project names that itself, such as Launchpad's `blocked_by`                                                                                                                          |
+| `utils`                                 | Reusable functions that are not components, such as `formatCurrency`. They live in a `utils/` folder: global, for one section, or for one component. Each function has its own folder with its test file and an `index.ts`. `utils` is a [dictionary word](/docs/Standards/human-readable-names#dictionary). Never `helpers` or `utilities`. See [Utils](/docs/Structure/folder-structure#-utils) |
+| `services`                              | The business logic: what the app does, its rules and operations. Pages, API routes and server actions stay thin and call into `services/`. See [utils, services and lib](/docs/Structure/folder-structure#utils-services-and-lib)                                                                                                                                                                 |
+| `lib`                                   | Code that connects the app to something outside it, such as integration clients in `lib/integrations/stripe/`, and app-wide setup: permissions, middleware, validation, constants, errors and shared types                                                                                                                                                                                        |
+| `route`                                 | A web address in the app, such as `/account-settings` or `/api/calendar-events`, and the folder or file that creates it. Route folders are kebab-case, because their names become the URL. In Next.js, routes are the folders under `app/`. See [API Routes](/docs/Structure/api-routes)                                                                                                          |
+| `no_data`                               | Stand-in data shaped exactly like a real response, used only in local development when the real source can't be reached. It lives in `lib/constants/noData.ts`, never in production. See [Constants](/docs/Structure/folder-structure#constants)                                                                                                                                                  |
+| `server_component` / `client_component` | A component that runs on the server, and one that runs in the browser. They live in separate files, and the server one wraps the client one                                                                                                                                                                                                                                                       |
+| `test_file`                             | The file that tests one function or component, named after it: `formatCurrency.test.ts`. Every function and component has one                                                                                                                                                                                                                                                                     |
+| `dictionary`                            | The list of short names that are words, not abbreviations: `id`, `docs`, `props`, `utils`, `url` and the rest. A short name not in the [Dictionary](/docs/Standards/human-readable-names#dictionary) is written out in full. A new word is added to the Dictionary before it is used                                                                                                              |
+| `third_party_names`                     | Names that come from someone else's code — a package, a framework or an outside service — such as React's `ref`, Next.js's `params` or shadcn/ui's `cn`. They are used exactly as they are, because renaming them breaks the code. The naming rule is only for names we write. See [Third-party names](/docs/Standards/human-readable-names#third-party-names)                                    |
+| `third_party_code`                      | Code we did not write: `node_modules/`, and anything copied into `vendor/`. It is never linted, reformatted or renamed                                                                                                                                                                                                                                                                            |
+| `global_palette`                        | The colours defined in `app/globals.css`. Every colour in a project comes from it. See [Styling](/docs/Standards/styling)                                                                                                                                                                                                                                                                         |
 
 ### Checks
 
-| Term         | Means                                                                                                                                             |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `lint_error` | A broken rule the linter reports. Fix the code; never switch the rule off without a comment saying why. See [Lint Errors](/Standards/lint-errors) |
+| Term         | Means                                                                                                                                                  |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `lint_error` | A broken rule the linter reports. Fix the code; never switch the rule off without a comment saying why. See [Lint Errors](/docs/Standards/lint-errors) |
 
 ---
 

package/docs/templates.mdx

@@ -67,7 +67,7 @@ Each file is also served as a plain file, so a person or an AI agent can fetch i
 
 **Copy to:** `AGENTS.md` in the project root
 
-Replace every `[placeholder]`. See [AGENTS.md Specifications](/Standards/agent-specs).
+Replace every `[placeholder]`. See [AGENTS.md Specifications](/docs/Standards/agent-specs).
 
 <CodeBlock language="markdown" title="AGENTS.md">
   {agents}
@@ -79,7 +79,7 @@ Replace every `[placeholder]`. See [AGENTS.md Specifications](/Standards/agent-s
 
 **Copy to:** `eslint.config.mjs` in the project root
 
-For TypeScript projects. Install commands are on the [ESLint page](/Standards/eslint#installation).
+For TypeScript projects. Install commands are on the [ESLint page](/docs/Standards/eslint#installation).
 
 <CodeBlock language="js" title="eslint.config.mjs">
   {eslintTypescript}
@@ -127,7 +127,7 @@ For plain JavaScript and Node.js projects.
 
 **Copy to:** `prettier.config.mjs` in the project root
 
-See the [Prettier page](/Standards/prettier).
+See the [Prettier page](/docs/Standards/prettier).
 
 <CodeBlock language="js" title="prettier.config.mjs">
   {prettier}
@@ -139,7 +139,7 @@ See the [Prettier page](/Standards/prettier).
 
 **Copy to:** `stylelint.config.mjs` in the project root
 
-See the [Stylelint page](/Standards/stylelint).
+See the [Stylelint page](/docs/Standards/stylelint).
 
 <CodeBlock language="js" title="stylelint.config.mjs">
   {stylelintCss}
@@ -163,7 +163,7 @@ For projects that use SCSS.
 
 **Copy to:** `app/globals.css`
 
-Replace the example colours with the project's palette. See [CSS Styling](/Standards/styling).
+Replace the example colours with the project's palette. See [CSS Styling](/docs/Standards/styling).
 
 <CodeBlock language="css" title="globals.css">
   {globalsCss}
@@ -175,7 +175,7 @@ Replace the example colours with the project's palette. See [CSS Styling](/Stand
 
 **Copy to:** `.editorconfig` in the project root
 
-See the [EditorConfig page](/Standards/editorconfig).
+See the [EditorConfig page](/docs/Standards/editorconfig).
 
 <CodeBlock language="ini" title=".editorconfig">
   {editorconfig}
@@ -187,7 +187,7 @@ See the [EditorConfig page](/Standards/editorconfig).
 
 **Copy to:** `.nvmrc` in the project root
 
-Set it to the project's Node major version. See [direnv + nvm](/Standards/direnv).
+Set it to the project's Node major version. See [direnv + nvm](/docs/Standards/direnv).
 
 <CodeBlock language="text" title=".nvmrc">
   {nvmrc}
@@ -199,7 +199,7 @@ Set it to the project's Node major version. See [direnv + nvm](/Standards/direnv
 
 **Copy to:** `.envrc` in the project root
 
-Run `direnv allow` after adding it. See [direnv + nvm](/Standards/direnv).
+Run `direnv allow` after adding it. See [direnv + nvm](/docs/Standards/direnv).
 
 <CodeBlock language="bash" title=".envrc">
   {envrc}
@@ -211,7 +211,7 @@ Run `direnv allow` after adding it. See [direnv + nvm](/Standards/direnv).
 
 **Copy to:** `.agents/skills/` in the project root, and again to `.claude/commands/` so Claude Code picks them up as slash commands.
 
-The eight standard skills. Copy all of them into every project. See [Agent Skills](/Standards/agent-skills) for how they are written.
+The eight standard skills. Copy all of them into every project. See [Agent Skills](/docs/Standards/agent-skills) for how they are written.
 
 | Skill                                  | Invocation                             | Plain file                                                                            |
 | -------------------------------------- | -------------------------------------- | ------------------------------------------------------------------------------------- |
@@ -294,7 +294,7 @@ Runs the test suite; reports failures grouped by cause, tests that never ran, an
 
 **Copy to:** a `docsSite/` folder in the project root
 
-The Docusaurus viewer that shows the project's `docs/` folder at `/docs`. Copy every file, keeping the folder layout. See [Documentation](/Standards/documentation#-setting-it-up).
+The Docusaurus viewer that shows the project's `docs/` folder at `/docs`. Copy every file, keeping the folder layout. See [Documentation](/docs/Standards/documentation#-setting-it-up).
 
 | File                     | Plain file                                                                                                                            |
 | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
@@ -360,7 +360,7 @@ Plain file: [`/templates/next.config.mjs`](pathname:///templates/next.config.mjs
 
 **Copy to:** the `docs/` folder in the project root, keeping the folder layout
 
-The full set of Decision Docs for a new project: every [reusable folder](/Standards/documentation#-the-folders) with every standard file, each marked `Status: Not started`. Copy the whole [`static/templates/docs/`](https://github.com/activatus-life/code-standards/tree/main/static/templates/docs) folder from this repository.
+The full set of Decision Docs for a new project: every [reusable folder](/docs/Standards/documentation#-the-folders) with every standard file, each marked `Status: Not started`. Copy the whole [`static/templates/docs/`](https://github.com/activatus-life/code-standards/tree/main/static/templates/docs) folder from this repository.
 
 | Folder          | Example file                                                                                  |
 | --------------- | --------------------------------------------------------------------------------------------- |
@@ -375,7 +375,7 @@ After copying, rename `overview/what-is-it.md` after the project and update its
 
 **Copy to:** any new doc that has no template file
 
-The shape every doc follows. See [The doc format](/Standards/documentation#-the-doc-format). Plain file: [`/templates/decision-doc.md`](pathname:///templates/decision-doc.md)
+The shape every doc follows. See [The doc format](/docs/Standards/documentation#-the-doc-format). Plain file: [`/templates/decision-doc.md`](pathname:///templates/decision-doc.md)
 
 <CodeBlock language="markdown" title="decision-doc.md">
   {decisionDoc}