@activatus/code-standards 3.0.1 → 3.0.4

package/README.md

@@ -32,7 +32,7 @@ Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_m
 
 The package version is the standards version: `2.0.0` is version 2.
 
-> 🔢 **Updating a project to newer standards?** Run `pnpm update @activatus/code-standards --latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
+> 🔢 **Updating a project to newer standards?** Run `pnpm update @activatus/code-standards --latest`, then point the agent at the **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**: it reads only the versions newer than the project's, does exactly what each one says, and bumps the number. Cheaper than shouting the whole pub a round.
 
 ---
 
@@ -66,15 +66,15 @@ The live site is at **[activatus-code-standards.vercel.app](https://activatus-co
 
 ## 📚 What's in the box
 
-| Section                                                                                                 | What you'll find                                                                                                                                      |
-| ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 📋 **Templates**                                                                                        | Ready-to-copy `AGENTS.md`, ESLint, Prettier, Stylelint and friends                                                                                    |
-| 📖 **Ontology**                                                                                         | The code words we use and what each one means                                                                                                         |
-| 🔢 **[Version History](https://activatus-code-standards.vercel.app/version-history)**                   | What changed in each version, and what a project has to do about it. Updating a project? Read only the versions newer than the one in its `AGENTS.md` |
-| 🧭 **Guides**                                                                                           | Setting up a new project, dragging an old one up to scratch, and how design becomes code                                                              |
-| 📏 **Standards**                                                                                        | Readable code, linting, formatting, styling, commits, the tech stack and AI agent rules                                                               |
-| 🏗️ **Structure**                                                                                        | Folders, components, naming, imports and API routes                                                                                                   |
-| 🧩 **[Design System Components](https://activatus-code-standards.vercel.app/design-system-components)** | Every standard component and its props, so each project builds them the same way                                                                      |
+| Section                                                                                                      | What you'll find                                                                                                                                      |
+| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 📋 **Templates**                                                                                             | Ready-to-copy `AGENTS.md`, ESLint, Prettier, Stylelint and friends                                                                                    |
+| 📖 **Ontology**                                                                                              | The code words we use and what each one means                                                                                                         |
+| 🔢 **[Version History](https://activatus-code-standards.vercel.app/docs/version-history)**                   | What changed in each version, and what a project has to do about it. Updating a project? Read only the versions newer than the one in its `AGENTS.md` |
+| 🧭 **Guides**                                                                                                | Setting up a new project, dragging an old one up to scratch, and how design becomes code                                                              |
+| 📏 **Standards**                                                                                             | Readable code, linting, formatting, styling, commits, the tech stack and AI agent rules                                                               |
+| 🏗️ **Structure**                                                                                             | Folders, components, naming, imports and API routes                                                                                                   |
+| 🧩 **[Design System Components](https://activatus-code-standards.vercel.app/docs/design-system-components)** | Every standard component and its props, so each project builds them the same way                                                                      |
 
 ---
 

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

@@ -41,7 +41,7 @@ Our projects are different products, so a shared library is not worth its upkeep
 A `Button` in one Activatus project takes the same props and behaves the same way as a `Button` in any other. A developer or an AI agent who knows one project's components knows them all.
 
 - **Keep shadcn's props exactly as they ship.** Do not rename, remove or repurpose a prop.
-- **Style through the [global colour palette](/Standards/styling#-colours-always-come-from-global-variables)** and Tailwind classes. Per-project branding is a palette change, not a component rewrite.
+- **Style through the [global colour palette](/docs/Standards/styling#-colours-always-come-from-global-variables)** and Tailwind classes. Per-project branding is a palette change, not a component rewrite.
 - **Need different behaviour?** Build a new component that wraps the base one. Do not change the base component.
 
 Keeping the components identical is also what makes a shared library possible later — see [Future-proofing](#future-proofing).
@@ -83,24 +83,24 @@ components/ui/
 
 1. **Add it** with the shadcn CLI.
 2. **Keep only the parts the project uses.** A shadcn file often exports many components. Delete the ones that are not used — if one is needed later, add it again and convert it the same way.
-3. **Give each component its own folder and file**: a camelCase folder with a PascalCase file (`button/Button.tsx`). One component per file — sub-components get [their own folders](/Structure/component-organization#nested-components) inside the parent.
-4. **Add the standard files** to each folder: `types.ts`, `index.ts` and a test file. See [Component Organization](/Structure/component-organization).
+3. **Give each component its own folder and file**: a camelCase folder with a PascalCase file (`button/Button.tsx`). One component per file — sub-components get [their own folders](/docs/Structure/component-organization#nested-components) inside the parent.
+4. **Add the standard files** to each folder: `types.ts`, `index.ts` and a test file. See [Component Organization](/docs/Structure/component-organization).
 5. **Apply the code standards**: named exports, type names ending in `Props` or `Type`, full English names for our own variables.
 6. **Leave the props and behaviour alone.** Converting changes the file layout and the styling, never [how the component works](#same-component-different-paint).
-7. **Use the global colour palette.** Replace shadcn's colour classes with colours from [the palette](/Standards/styling#-colours-always-come-from-global-variables).
-8. **Move shared helpers to `utils/`.** shadcn's `cn` helper lives in the [global `utils/` folder](/Structure/folder-structure#-utils), not in `lib/utilities.ts`.
+7. **Use the global colour palette.** Replace shadcn's colour classes with colours from [the palette](/docs/Standards/styling#-colours-always-come-from-global-variables).
+8. **Move shared helpers to `utils/`.** shadcn's `cn` helper lives in the [global `utils/` folder](/docs/Structure/folder-structure#-utils), not in `lib/utilities.ts`.
 9. **Run `pnpm lint` and `pnpm test`.** The converted component must pass both.
 
 ### What is still third-party
 
-The packages a shadcn component imports — Radix UI and the like — stay in `node_modules/` and are [exempt from the standards](/Standards/eslint#third-party-code-is-exempt). Only the component source that the CLI copies into the project becomes ours.
+The packages a shadcn component imports — Radix UI and the like — stay in `node_modules/` and are [exempt from the standards](/docs/Standards/eslint#third-party-code-is-exempt). Only the component source that the CLI copies into the project becomes ours.
 
 ## The design → code loop
 
 1. **Design in Claude Design** using shadcn components and the project's palette.
 2. **A new component is needed** → [look before you build](#1-look-before-you-build), then add it from shadcn and [convert it](#converting-a-component).
 3. **A new look is needed** → change the palette or the component's classes. The props stay as they are.
-4. **Something shadcn does not provide** → build it in `components/ui/` from existing components, following [Component Organization](/Structure/component-organization).
+4. **Something shadcn does not provide** → build it in `components/ui/` from existing components, following [Component Organization](/docs/Structure/component-organization).
 
 :::caution[Design and code are decoupled]
 
@@ -132,13 +132,13 @@ That refactor is **planned, but not now**. Until then, two things stop each proj
 
 Before building any component, check these in order and stop at the first match:
 
-| #   | Look in                                                   | If it is there                                                                                                                   |
-| --- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | The project's own `components/ui/`                        | Use it                                                                                                                           |
-| 2   | The [Design System Components](/design-system-components) | Build it to the listed variants and props                                                                                        |
-| 3   | Another Activatus project                                 | Copy the component's whole folder — code, types and tests — then restyle it                                                      |
-| 4   | shadcn                                                    | Add it and [convert it](#converting-a-component)                                                                                 |
-| 5   | Nowhere                                                   | Build it, and **add it to the [Design System Components](/design-system-components)** so the next project builds it the same way |
+| #   | Look in                                                        | If it is there                                                                                                                        |
+| --- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| 1   | The project's own `components/ui/`                             | Use it                                                                                                                                |
+| 2   | The [Design System Components](/docs/design-system-components) | Build it to the listed variants and props                                                                                             |
+| 3   | Another Activatus project                                      | Copy the component's whole folder — code, types and tests — then restyle it                                                           |
+| 4   | shadcn                                                         | Add it and [convert it](#converting-a-component)                                                                                      |
+| 5   | Nowhere                                                        | Build it, and **add it to the [Design System Components](/docs/design-system-components)** so the next project builds it the same way |
 
 **Copying a finished component from another Activatus project is encouraged.** Rebuilding one from memory is how two projects end up with two different buttons.
 
@@ -153,9 +153,9 @@ A component in `components/ui/` must be able to move to another project — or t
 | **It may import only** other `components/ui/` components, the global `utils/` folder and installed packages | These travel with it                              |
 | **No project names, client names or business rules inside it**                                              | A `Button` knows nothing about invoices           |
 | **Its types and tests live in its folder**                                                                  | They move when the folder moves                   |
-| **Its props match the [Design System Components](/design-system-components)**                               | Every project's copy is interchangeable           |
+| **Its props match the [Design System Components](/docs/design-system-components)**                          | Every project's copy is interchangeable           |
 
-Logic that belongs to one project goes in a **page or shared component** (in the page's `components/` folder, or `components/shared/`) that wraps the base component and passes it props. See [Where components live](/Structure/folder-structure#-where-components-live). The base component stays clean.
+Logic that belongs to one project goes in a **page or shared component** (in the page's `components/` folder, or `components/shared/`) that wraps the base component and passes it props. See [Where components live](/docs/Structure/folder-structure#-where-components-live). The base component stays clean.
 
 ```tsx
 // ✅ Good — the base component takes props; the page component knows about invoices

package/docs/Guides/migrating.md

@@ -6,16 +6,16 @@ sidebar_position: 3
 
 Migrating an established codebase to the shared standards is best done in stages, so each change stays small enough to check properly.
 
-**Already following the standards, and just updating to a newer version?** You don't need this whole guide. Read the [Version History](/version-history) from your project's version onward, and do only what it lists.
+**Already following the standards, and just updating to a newer version?** You don't need this whole guide. Read the [Version History](/docs/version-history) from your project's version onward, and do only what it lists.
 
 ## Before you start: third-party code is exempt
 
-The standards apply to **code we write**, not to packages we pull in. Do not lint, reformat, rename or restructure third-party code — see [Third-party code is exempt](/Standards/eslint#third-party-code-is-exempt).
+The standards apply to **code we write**, not to packages we pull in. Do not lint, reformat, rename or restructure third-party code — see [Third-party code is exempt](/docs/Standards/eslint#third-party-code-is-exempt).
 
 - `node_modules/` is ignored automatically.
 - Third-party code copied into the repo belongs in a `vendor/` folder, which the configs ignore.
 - Add `vendor/` to `.prettierignore` too.
-- **shadcn components are not third-party.** They are our code: convert them to the standards rather than moving them to `vendor/`. See [Adding a shadcn component](/Guides/component-library-workflow#adding-a-shadcn-component).
+- **shadcn components are not third-party.** They are our code: convert them to the standards rather than moving them to `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
 
 ## Stage 1 — Prettier (formatting only)
 
@@ -25,7 +25,7 @@ Formatting changes are safe to make all at once because they don't change behavi
 pnpm add -D prettier prettier-plugin-tailwindcss
 ```
 
-Add `prettier.config.mjs` — see the [Prettier page](/Standards/prettier) for the full file contents.
+Add `prettier.config.mjs` — see the [Prettier page](/docs/Standards/prettier) for the full file contents.
 
 Format everything at once:
 
@@ -51,7 +51,7 @@ Add the `.editorconfig` file. No code changes needed — your editor will handle
 
 ## Stage 3 — ESLint
 
-Add the [standard config](/Standards/eslint) for your project type, then start in warn-only mode to see what you're dealing with. Add a block before `prettier`:
+Add the [standard config](/docs/Standards/eslint) for your project type, then start in warn-only mode to see what you're dealing with. Add a block before `prettier`:
 
 ```js
 export default [
@@ -72,19 +72,19 @@ Run `pnpm lint` and triage the output. Fix them one kind at a time (for example,
 
 ## Stage 4 — Names
 
-Renaming is the biggest job in most migrations, and the easiest place to get confused. Every name we write becomes [Human-Readable Names](/Standards/human-readable-names). Work through it in this order.
+Renaming is the biggest job in most migrations, and the easiest place to get confused. Every name we write becomes [Human-Readable Names](/docs/Standards/human-readable-names). Work through it in this order.
 
 ### 1. Decide what stays
 
 Before renaming anything, sort the short names into three piles:
 
-| Pile                                                                                                                   | What to do                | Where to check                                                            |
-| ---------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
-| **A dictionary word** — `id`, `docs`, `app`, `url`, `api`                                                              | Leave it                  | [Dictionary](/Standards/human-readable-names#dictionary)                  |
-| **A third-party name** — React's `ref`, Next.js's `params`, shadcn/ui's `cn`, Linear's `pageInfo`, Node's `cwd` option | Leave it exactly as it is | [Third-party names](/Standards/human-readable-names#third-party-names)    |
-| **Our own shorthand** — `btn`, `lib/`, `helpers/`, `utilities/`                                                        | Rename it                 | The [Never / Always](/Standards/human-readable-names#never--always) table |
+| Pile                                                                                                                   | What to do                | Where to check                                                                 |
+| ---------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------ |
+| **A dictionary word** — `id`, `docs`, `app`, `url`, `api`                                                              | Leave it                  | [Dictionary](/docs/Standards/human-readable-names#dictionary)                  |
+| **A third-party name** — React's `ref`, Next.js's `params`, shadcn/ui's `cn`, Linear's `pageInfo`, Node's `cwd` option | Leave it exactly as it is | [Third-party names](/docs/Standards/human-readable-names#third-party-names)    |
+| **Our own shorthand** — `btn`, `lib/`, `helpers/`, `utilities/`                                                        | Rename it                 | The [Never / Always](/docs/Standards/human-readable-names#never--always) table |
 
-**Not sure which pile?** Don't guess and don't rename it. Ask, and if it is a dictionary word, [add it to the dictionary](/Standards/human-readable-names#adding-a-word-to-the-dictionary) first. Everyone then makes the same call.
+**Not sure which pile?** Don't guess and don't rename it. Ask, and if it is a dictionary word, [add it to the dictionary](/docs/Standards/human-readable-names#adding-a-word-to-the-dictionary) first. Everyone then makes the same call.
 
 ### 2. The common renames
 
@@ -152,15 +152,15 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
 
 ## Stage 5 — AGENTS.md
 
-Copy the [AGENTS.md template](/templates#agents) to the project root and replace every `[placeholder]`. Agree the standards with the person first ([Setup, step 3](/Guides/setup#3-agree-the-standards)), and set the code standards version from the [Version History](/version-history).
+Copy the [AGENTS.md template](/docs/templates#agents) to the project root and replace every `[placeholder]`. Agree the standards with the person first ([Setup, step 3](/docs/Guides/setup#3-agree-the-standards)), and set the code standards version from the [Version History](/docs/version-history).
 
 ## Stage 6 — Agent skills
 
-Copy the eight [standard skill files](/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
+Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
 
 ## Stage 7 — Docs
 
-Move the project's existing documentation into the standard [`docs/` folders](/Standards/documentation#-the-folders), rewriting each as a [Decision Doc](/Standards/documentation#-the-doc-format), then add the [`docsSite/` viewer](/Standards/documentation#-setting-it-up) so it shows at `/docs`.
+Move the project's existing documentation into the standard [`docs/` folders](/docs/Standards/documentation#-the-folders), rewriting each as a [Decision Doc](/docs/Standards/documentation#-the-doc-format), then add the [`docsSite/` viewer](/docs/Standards/documentation#-setting-it-up) so it shows at `/docs`.
 
 ## Tips
 

package/docs/Guides/setup.md

@@ -64,6 +64,7 @@ Tell me the numbers to skip or change, or say "all good".
 10. Node version set by .nvmrc and direnv
 11. Styling: Tailwind, flexbox first, colours only from the global palette
 12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
+12.1. Constants: r for every link, s for every piece of text, noData for local stand-in data, all in lib/constants/
 13. Components live where they are used: components/ui/, components/shared/, or beside their page
 14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
 15. Design System Components: every project builds the standard components with the same props
@@ -83,6 +84,7 @@ Then wait for the answer.
 
 - **A number is never reused.** A removed standard keeps its number in the list, marked "Removed in version N", so a project's old choices still point at the right thing.
 - **A new standard takes the number of the standard it sits closest to, plus a decimal:** a new styling standard after 11 is 11.1, then 11.2, up to 11.9. The list stays short, and nothing after it moves.
+- **A removed decimal standard keeps its number too**, marked the same way: `11.2. Removed in version N`.
 - **Skip the removed ones** when applying the standards. There is nothing to do for them.
 
 | The person says                         | Do                            |
@@ -94,7 +96,7 @@ Then wait for the answer.
 
 **Record the answer** in `docs/development/coding-standards.md`, under "Details". For each skipped or changed standard, write its number, its name, what is different, and the reason the person gave. If nothing is different, write "No differences". Copy the file from `static/templates/docs/development/coding-standards.md` if it does not exist.
 
-The list has nothing about branches, commit messages or whether agents may commit. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/Standards/agent-specs#project-workflow).
+The list has nothing about branches, commit messages or whether agents may commit. Those are the project's own workflow. Ask the person how they work, and write it in the "Project workflow" section of `AGENTS.md`. See [Project workflow](/docs/Standards/agent-specs#project-workflow).
 
 ## 4. Apply the standards
 
@@ -102,17 +104,18 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
 
 **Every config file is `.mjs`, even in a TypeScript project.** Never convert one to `.ts` or `.mts`. `.mjs` works in both, so every project looks the same. If the project has a config as `.js`, `.ts` or `.mts`, such as `next.config.ts` from `create-next-app` or `vitest.config.mts`, rename it to `.mjs`, removing any TypeScript-only syntax: a type annotation becomes a JSDoc comment, for example `/** @type {import("next").NextConfig} */`. A tool that cannot read `.mjs` keeps its own format.
 
-**An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/Guides/migrating), one stage at a time, after the config files below are in place.
+**An existing project with code already in it** also needs its code brought up to the standards. Do that with [Migrating an Existing Project](/docs/Guides/migrating), one stage at a time, after the config files below are in place.
 
 | Standard                 | What to set up                                                                                                                                                                                                                                                                                                       |
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 6. ESLint                | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`. Install the packages listed on the [ESLint page](/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`                                                 |
+| 6. ESLint                | Copy the config for the project's framework from `static/templates/eslint/`: `base`, `typescript`, `react` or `nextjs`. Install the packages listed on the [ESLint page](/docs/Standards/eslint). Add the scripts `"lint": "eslint ."` and `"lint:fix": "eslint . --fix"`                                            |
 | 7. Prettier              | `pnpm add -D prettier prettier-plugin-tailwindcss`. Copy `static/templates/prettier.config.mjs`. Add the scripts `"format": "prettier --write ."` and `"format:check": "prettier --check ."`                                                                                                                         |
-| 8. Stylelint             | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/Standards/stylelint)                                                                                                                                                           |
+| 8. Stylelint             | Only if the project has hand-written CSS or SCSS. Copy the config from `static/templates/stylelint/css/` or `scss/`. See [Stylelint](/docs/Standards/stylelint)                                                                                                                                                      |
 | 9. EditorConfig          | Copy `static/templates/.editorconfig`                                                                                                                                                                                                                                                                                |
-| 10. Node version         | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/Standards/direnv)                                                                                                                                                                                                                  |
+| 10. Node version         | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv)                                                                                                                                                                                                             |
 | 11. Styling              | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette                                                                                                                                                                                  |
-| 18. Docs                 | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/Standards/documentation#-setting-it-up)                                                                                                |
+| 12.1. Constants          | Create `lib/constants/` with `routes.ts` (`r`), `strings.ts` (`s`), `noData.ts` and an `index.ts` that exports them. If the project keeps them somewhere else, such as `app/constants/`, move them. See [Constants](/docs/Structure/folder-structure#constants)                                                      |
+| 18. Docs                 | Copy `static/templates/docs/` to `docs/` and `static/templates/docsSite/` to `docsSite/`. Add the `/docs` route from `static/templates/next.config.mjs`. See [Setting it up](/docs/Standards/documentation#-setting-it-up)                                                                                           |
 | 21. AGENTS.md and skills | Copy `static/templates/AGENTS.md` to the project root and fill in every `[placeholder]`. If the framework wrote its own `AGENTS.md` (Next.js does), keep any instruction it gives about reading the framework's own docs. Copy `static/templates/skills/` into `.agents/skills/`, and again into `.claude/commands/` |
 
 The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
@@ -129,6 +132,8 @@ The other standards are rules for how code is written. There is nothing to insta
 
 The project already follows the standards, and a newer version is out.
 
+**A patch keeps the same version number.** When only the last number changes, such as 3.0.0 → 3.0.1, the project's version in `AGENTS.md` stays the same, but there may still be work to do. Update the package, then read that version's **Fixes** list and do anything it asks for the project's version. Check it every time the package is updated, even when the version number has not changed.
+
 1. **Note the project's version.** Read `**Code standards version:**` in `AGENTS.md`. This is the version the code follows.
 2. **Update the package:**
 
@@ -143,7 +148,7 @@ The project already follows the standards, and a newer version is out.
 5. **Do every other change** as its "What to do" says, and run its "How to check" search.
 6. **Set `**Code standards version:**`** in `AGENTS.md` to the new version, and tell the person what changed. If a change is being finished later, record it first: see [Finishing a change later](#finishing-a-change-later).
 
-See the [Version History](/version-history) for the full update rules.
+See the [Version History](/docs/version-history) for the full update rules.
 
 ---
 

package/docs/Standards/agent-skills.md

@@ -4,7 +4,7 @@ sidebar_position: 8
 
 # Agent Skills
 
-A skill is a reusable instruction file an agent runs when you type `/lint`, `/format`, `/codeReview`. Every Activatus repository provides the same [standard set](/Standards/agent-specs#standard-skills), copied from the [Templates page](/templates#skills). This page is the standard they are written to.
+A skill is a reusable instruction file an agent runs when you type `/lint`, `/format`, `/codeReview`. Every Activatus repository provides the same [standard set](/docs/Standards/agent-specs#standard-skills), copied from the [Templates page](/docs/templates#skills). This page is the standard they are written to.
 
 Skills are shared, versioned, and executed with real tool access. A vague one wastes a run; a wrong one edits files it was never meant to touch. They get the same review as any other code.
 
@@ -71,7 +71,7 @@ Three rules follow from this:
 
 1. **Every command the body tells the agent to run must be allowlisted.** A body that says `eslint $ARGUMENTS` under an allowlist of only `Bash(pnpm exec eslint:*)` blocks itself halfway through. List each form the body actually uses.
 2. **Grant the narrowest set that still works.** `Bash(pnpm lint:*), Bash(eslint:*)` over a bare `Bash`.
-3. **Never grant `git commit` or `git push`.** A skill does one job and leaves its changes for whoever ran it. Committing is the [project's workflow](/Standards/agent-specs#project-workflow), not a skill's.
+3. **Never grant `git commit` or `git push`.** A skill does one job and leaves its changes for whoever ran it. Committing is the [project's workflow](/docs/Standards/agent-specs#project-workflow), not a skill's.
 
 Be honest about the limit: patterns gate the command, not its flags. `Bash(eslint:*)` still permits `eslint --fix`. The allowlist reliably prevents a skill from reaching for a whole _category_ of tool; keep the prose instruction as well for anything finer.
 

package/docs/Standards/agent-specs.md

@@ -15,7 +15,7 @@ Each project writes them up in its own docs, usually in `docs/development/`, and
 
 ## Template
 
-Start from the [AGENTS.md template](/templates#agents) and replace every `[placeholder]`.
+Start from the [AGENTS.md template](/docs/templates#agents) and replace every `[placeholder]`.
 
 ## Required sections
 
@@ -29,7 +29,7 @@ Every `AGENTS.md` must include these sections. Monorepos (`pnpm-workspace.yaml`,
 | Essential commands         | Install, dev, build, test, lint, type-check                                                                                                  |
 | Project workflow           | The project's own rules for branches, commits, Pull Requests and merging, and whether agents may commit. Points to where they are written up |
 | Environment variables      | All required and optional env vars with descriptions                                                                                         |
-| Ontology                   | Link to the [ontology](/ontology), and the instruction to read it and use its terms                                                          |
+| Ontology                   | Link to the [ontology](/docs/ontology), and the instruction to read it and use its terms                                                     |
 | Documentation              | Where the project's docs are, and the instruction to read them before starting work                                                          |
 | Code standards             | Link to these standards and the rules agents must follow in every change                                                                     |
 | Available skills           | Table of the agent skills the project provides                                                                                               |
@@ -37,7 +37,7 @@ Every `AGENTS.md` must include these sections. Monorepos (`pnpm-workspace.yaml`,
 
 ## Standard skills
 
-Every project provides these eight skills. **The files are ready to copy from the [Templates page](/templates#skills)** — copy them into `.agents/skills/`, and again into `.claude/commands/` for Claude Code. They are written to the [agent skills standard](/Standards/agent-skills).
+Every project provides these eight skills. **The files are ready to copy from the [Templates page](/docs/templates#skills)** — copy them into `.agents/skills/`, and again into `.claude/commands/` for Claude Code. They are written to the [agent skills standard](/docs/Standards/agent-skills).
 
 | Skill          | Invocation                             | What it does                                                                                                   |
 | -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |

package/docs/Standards/documentation.md

@@ -32,7 +32,7 @@ A design system is a decision. A scope is a decision. A database choice is a dec
 - **Tickets own the _what_.** "Build GitHub authentication."
 - **Decision Docs own the _why_.** "Developers are our audience and we must sync directly to their repositories."
 
-See the [Ontology](/ontology#key-distinctions) for the terms.
+See the [Ontology](/docs/ontology#key-distinctions) for the terms.
 
 ---
 
@@ -88,7 +88,7 @@ Keep these pairs distinct:
 
 ### Every file exists from the start
 
-**A new project starts with every reusable file already in place**, each marked `Status: Not started`. Copy the [doc templates](/templates#document-templates).
+**A new project starts with every reusable file already in place**, each marked `Status: Not started`. Copy the [doc templates](/docs/templates#document-templates).
 
 - When a decision is made, **write it into the matching file**.
 - **Create a new file** only when a topic has no home.
@@ -165,7 +165,7 @@ The docs menu is built straight from the `docs/` folder, so every doc is in the
 
 - **Overview comes first** in the menu. Every other group is in alphabetical order, and items are alphabetical within their group.
 - **Link between docs with relative `.md` paths** — `[Future](../scope/future.md)`. The link works in the file and on the site.
-- **Folder and file names are kebab-case**, because they become the route. See [Naming Conventions](/Structure/naming-conventions#when-to-use-kebab-case).
+- **Folder and file names are kebab-case**, because they become the route. See [Naming Conventions](/docs/Structure/naming-conventions#when-to-use-kebab-case).
 
 The viewer does this automatically. There is no menu file to maintain.
 
@@ -173,7 +173,7 @@ The viewer does this automatically. There is no menu file to maintain.
 
 ## ✍️ Rules for writing
 
-- **Use the [Ontology](/ontology).** Use its terms for code, and the project's own ontology for product words.
+- **Use the [Ontology](/docs/ontology).** Use its terms for code, and the project's own ontology for product words.
 - **One decision per file.**
 - **Plain Markdown (`.md`).** No JSX or imports, so every file reads the same for an agent as it does on the page.
 - **One `# Heading` per file**, at the top, in the form `# Group — Menu item`.
@@ -182,7 +182,7 @@ The viewer does this automatically. There is no menu file to maintain.
 
 ### Not finished until the docs are updated
 
-**A change is not finished until the docs match it.** If a change makes a doc wrong, the doc is fixed in the same change — the same rule as [test files](/Standards/readable-code#every-function-and-component-has-a-test-file).
+**A change is not finished until the docs match it.** If a change makes a doc wrong, the doc is fixed in the same change — the same rule as [test files](/docs/Standards/readable-code#every-function-and-component-has-a-test-file).
 
 This applies to everyone writing code, **including AI agents**. An agent that changes how something works updates the Decision Doc that describes it.
 
@@ -262,9 +262,9 @@ export default nextConfig;
 
 ## 🚀 Setting it up
 
-1. **Copy the docs.** Copy the [`docs/` templates](/templates#document-templates) into the project's `docs/` folder. Rename `overview/what-is-it.md` after the project (`what-is-launchpad.md`) and update its title.
+1. **Copy the docs.** Copy the [`docs/` templates](/docs/templates#document-templates) into the project's `docs/` folder. Rename `overview/what-is-it.md` after the project (`what-is-launchpad.md`) and update its title.
 
-2. **Copy the viewer.** Copy the [`docsSite/` template](/templates#docs-site) into the project root. Rename `package.json.txt` to `package.json` and `gitignore.txt` to `.gitignore`, set `PROJECT_NAME` in `docusaurus.config.mjs`, and point the home redirect in `src/pages/index.tsx` at the renamed overview file.
+2. **Copy the viewer.** Copy the [`docsSite/` template](/docs/templates#docs-site) into the project root. Rename `package.json.txt` to `package.json` and `gitignore.txt` to `.gitignore`, set `PROJECT_NAME` in `docusaurus.config.mjs`, and point the home redirect in `src/pages/index.tsx` at the renamed overview file.
 
 3. **Add the route.** Add the rewrite above to `next.config.mjs`.