@activatus/code-standards 3.0.2 → 3.0.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/README.md +15 -13
  2. package/docs/Guides/component-library-workflow.md +16 -16
  3. package/docs/Guides/migrating.md +18 -16
  4. package/docs/Guides/setup.md +9 -7
  5. package/docs/Standards/agent-skills.md +2 -2
  6. package/docs/Standards/agent-specs.md +3 -3
  7. package/docs/Standards/documentation.md +7 -7
  8. package/docs/Standards/eslint.md +321 -155
  9. package/docs/Standards/human-readable-names.md +15 -3
  10. package/docs/Standards/lint-errors.md +13 -12
  11. package/docs/Standards/readable-code.md +82 -43
  12. package/docs/Standards/stylelint.md +4 -4
  13. package/docs/Standards/styling.md +8 -8
  14. package/docs/Standards/tech-stack.md +1 -1
  15. package/docs/Structure/api-routes.md +3 -3
  16. package/docs/Structure/component-organization.md +19 -18
  17. package/docs/Structure/folder-structure.md +131 -12
  18. package/docs/Structure/naming-conventions.md +10 -8
  19. package/docs/design-system-components.md +3 -3
  20. package/docs/intro.md +20 -20
  21. package/docs/ontology.md +32 -31
  22. package/docs/templates.mdx +12 -12
  23. package/docs/version-history.md +77 -42
  24. package/package.json +19 -4
  25. package/static/templates/AGENTS.md +6 -5
  26. package/static/templates/docs/overview/writing-docs.md +1 -1
  27. package/static/templates/eslint/base/eslint.config.mjs +57 -33
  28. package/static/templates/eslint/nextjs/eslint.config.mjs +80 -32
  29. package/static/templates/eslint/react/eslint.config.mjs +76 -33
  30. package/static/templates/eslint/typescript/eslint.config.mjs +76 -33
package/README.md CHANGED
@@ -1,5 +1,7 @@
1
1
  # 🦘 Activatus Code Standards
2
2
 
3
+ ## 👋 About Code Standards
4
+
3
5
  **One way of doing things, written down, so nobody has to guess.**
4
6
 
5
7
  This is the rulebook for how we write code at Activatus. It's a docs site, a pile of copy-paste config files, and a set of lint rules that'll dob you in before your reviewer has to.
@@ -30,9 +32,9 @@ pnpm add -D @activatus/code-standards
30
32
 
31
33
  Then tell your agent: **"Follow the Activatus Code Standards. Start with `node_modules/@activatus/code-standards/docs/Guides/setup.md`."** It prints a numbered list of the standards, you say which ones you don't want, and it sets up the rest. You never touch the terminal.
32
34
 
33
- The package version is the standards version: `2.0.0` is version 2.
35
+ The package version is the standards version: `3.0.0` is version 3.
34
36
 
35
- > 🔢 **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.
37
+ > 🔢 **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.
36
38
 
37
39
  ---
38
40
 
@@ -66,15 +68,15 @@ The live site is at **[activatus-code-standards.vercel.app](https://activatus-co
66
68
 
67
69
  ## 📚 What's in the box
68
70
 
69
- | Section | What you'll find |
70
- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
71
- | 📋 **Templates** | Ready-to-copy `AGENTS.md`, ESLint, Prettier, Stylelint and friends |
72
- | 📖 **Ontology** | The code words we use and what each one means |
73
- | 🔢 **[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` |
74
- | 🧭 **Guides** | Setting up a new project, dragging an old one up to scratch, and how design becomes code |
75
- | 📏 **Standards** | Readable code, linting, formatting, styling, commits, the tech stack and AI agent rules |
76
- | 🏗️ **Structure** | Folders, components, naming, imports and API routes |
77
- | 🧩 **[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 |
71
+ | Section | What you'll find |
72
+ | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
73
+ | 📋 **Templates** | Ready-to-copy `AGENTS.md`, ESLint, Prettier, Stylelint and friends |
74
+ | 📖 **Ontology** | The code words we use and what each one means |
75
+ | 🔢 **[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` |
76
+ | 🧭 **Guides** | Setting up a new project, dragging an old one up to scratch, and how design becomes code |
77
+ | 📏 **Standards** | Readable code, linting, formatting, styling, the tech stack and AI agent rules |
78
+ | 🏗️ **Structure** | Folders, components, naming, imports and API routes |
79
+ | 🧩 **[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 |
78
80
 
79
81
  ---
80
82
 
@@ -131,7 +133,7 @@ The full detail's on the site. This is the version you'd tell someone over a sch
131
133
 
132
134
  ## 📋 Just want the files?
133
135
 
134
- Fair enough. Head to the **Templates** page on the site, or grab them straight from [`static/templates/`](static/templates):
136
+ Fair enough. Head to the **Templates** page on the site, or grab them straight from [`static/templates/`](https://github.com/activatus-life/code-standards/tree/main/static/templates):
135
137
 
136
138
  ```text
137
139
  static/templates/
@@ -177,7 +179,7 @@ Reckon a rule's wrong, or there's one missing? Good. Standards that never change
177
179
 
178
180
  1. 🌿 **Branch off `main`**, named after the ticket (`ACT-14-update-eslint-page`), or `type/short-description` if there's no ticket (`docs/update-eslint-page`).
179
181
  2. 📝 **Edit or add a Markdown file in `docs/`.** Name it in kebab-case (`naming-conventions.md`, not `namingConventions.md`), because the file name becomes the page's URL. Yes, we follow our own rules here.
180
- 3. 📋 **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart.
182
+ 3. 📋 **Changing a config?** Edit the file in `static/templates/` and the matching page in `docs/Standards/` so the two don't drift apart. For an ESLint config, run `pnpm check:eslint-templates`: it lints each config against itself and fails if the ESLint page shows an old copy. Add `--update-docs` to copy the configs onto the page.
181
183
  4. 🔢 **Add a version** to `docs/version-history.md`: what changed, and what a project has to do about it. Bump the major version in `package.json` to match (version 3 is `3.0.0`), and publish it to npm (npmjs.com) once it's merged. We use pnpm for everything, so that's `pnpm publish`, which lands in the same npm registry as `npm publish`. Projects read only the new versions, so if it's not in there, nobody hears about it.
182
184
  5. 🔨 **Run `pnpm build`.** It fails on broken links, so you'll know quick smart if you've stuffed one.
183
185
  6. 🚀 **Open a pull request** and say why the change makes life better.
package/docs/Guides/component-library-workflow.md CHANGED
@@ -41,7 +41,7 @@ Our projects are different products, so a shared library is not worth its upkeep
41
41
  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.
42
42
 
43
43
  - **Keep shadcn's props exactly as they ship.** Do not rename, remove or repurpose a prop.
44
- - **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.
44
+ - **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.
45
45
  - **Need different behaviour?** Build a new component that wraps the base one. Do not change the base component.
46
46
 
47
47
  Keeping the components identical is also what makes a shared library possible later — see [Future-proofing](#future-proofing).
@@ -83,24 +83,24 @@ components/ui/
83
83
 
84
84
  1. **Add it** with the shadcn CLI.
85
85
  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.
86
- 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.
87
- 4. **Add the standard files** to each folder: `types.ts`, `index.ts` and a test file. See [Component Organization](/Structure/component-organization).
86
+ 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.
87
+ 4. **Add the standard files** to each folder: `types.ts`, `index.ts` and a test file. See [Component Organization](/docs/Structure/component-organization).
88
88
  5. **Apply the code standards**: named exports, type names ending in `Props` or `Type`, full English names for our own variables.
89
89
  6. **Leave the props and behaviour alone.** Converting changes the file layout and the styling, never [how the component works](#same-component-different-paint).
90
- 7. **Use the global colour palette.** Replace shadcn's colour classes with colours from [the palette](/Standards/styling#-colours-always-come-from-global-variables).
91
- 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`.
90
+ 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).
91
+ 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`.
92
92
  9. **Run `pnpm lint` and `pnpm test`.** The converted component must pass both.
93
93
 
94
94
  ### What is still third-party
95
95
 
96
- 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.
96
+ 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.
97
97
 
98
98
  ## The design → code loop
99
99
 
100
100
  1. **Design in Claude Design** using shadcn components and the project's palette.
101
101
  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).
102
102
  3. **A new look is needed** → change the palette or the component's classes. The props stay as they are.
103
- 4. **Something shadcn does not provide** → build it in `components/ui/` from existing components, following [Component Organization](/Structure/component-organization).
103
+ 4. **Something shadcn does not provide** → build it in `components/ui/` from existing components, following [Component Organization](/docs/Structure/component-organization).
104
104
 
105
105
  :::caution[Design and code are decoupled]
106
106
 
@@ -132,13 +132,13 @@ That refactor is **planned, but not now**. Until then, two things stop each proj
132
132
 
133
133
  Before building any component, check these in order and stop at the first match:
134
134
 
135
- | # | Look in | If it is there |
136
- | --- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
137
- | 1 | The project's own `components/ui/` | Use it |
138
- | 2 | The [Design System Components](/design-system-components) | Build it to the listed variants and props |
139
- | 3 | Another Activatus project | Copy the component's whole folder — code, types and tests — then restyle it |
140
- | 4 | shadcn | Add it and [convert it](#converting-a-component) |
141
- | 5 | Nowhere | Build it, and **add it to the [Design System Components](/design-system-components)** so the next project builds it the same way |
135
+ | # | Look in | If it is there |
136
+ | --- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
137
+ | 1 | The project's own `components/ui/` | Use it |
138
+ | 2 | The [Design System Components](/docs/design-system-components) | Build it to the listed variants and props |
139
+ | 3 | Another Activatus project | Copy the component's whole folder — code, types and tests — then restyle it |
140
+ | 4 | shadcn | Add it and [convert it](#converting-a-component) |
141
+ | 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 |
142
142
 
143
143
  **Copying a finished component from another Activatus project is encouraged.** Rebuilding one from memory is how two projects end up with two different buttons.
144
144
 
@@ -153,9 +153,9 @@ A component in `components/ui/` must be able to move to another project — or t
153
153
  | **It may import only** other `components/ui/` components, the global `utils/` folder and installed packages | These travel with it |
154
154
  | **No project names, client names or business rules inside it** | A `Button` knows nothing about invoices |
155
155
  | **Its types and tests live in its folder** | They move when the folder moves |
156
- | **Its props match the [Design System Components](/design-system-components)** | Every project's copy is interchangeable |
156
+ | **Its props match the [Design System Components](/docs/design-system-components)** | Every project's copy is interchangeable |
157
157
 
158
- 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.
158
+ 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.
159
159
 
160
160
  ```tsx
161
161
  // ✅ Good — the base component takes props; the page component knows about invoices
package/docs/Guides/migrating.md CHANGED
@@ -6,16 +6,16 @@ sidebar_position: 3
6
6
 
7
7
  Migrating an established codebase to the shared standards is best done in stages, so each change stays small enough to check properly.
8
8
 
9
- **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.
9
+ **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.
10
10
 
11
11
  ## Before you start: third-party code is exempt
12
12
 
13
- 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).
13
+ 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).
14
14
 
15
15
  - `node_modules/` is ignored automatically.
16
16
  - Third-party code copied into the repo belongs in a `vendor/` folder, which the configs ignore.
17
17
  - Add `vendor/` to `.prettierignore` too.
18
- - **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).
18
+ - **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).
19
19
 
20
20
  ## Stage 1 — Prettier (formatting only)
21
21
 
@@ -25,7 +25,7 @@ Formatting changes are safe to make all at once because they don't change behavi
25
25
  pnpm add -D prettier prettier-plugin-tailwindcss
26
26
  ```
27
27
 
28
- Add `prettier.config.mjs` — see the [Prettier page](/Standards/prettier) for the full file contents.
28
+ Add `prettier.config.mjs` — see the [Prettier page](/docs/Standards/prettier) for the full file contents.
29
29
 
30
30
  Format everything at once:
31
31
 
@@ -51,10 +51,10 @@ Add the `.editorconfig` file. No code changes needed — your editor will handle
51
51
 
52
52
  ## Stage 3 — ESLint
53
53
 
54
- 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`:
54
+ 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`:
55
55
 
56
56
  ```js
57
- export default [
57
+ const config = [
58
58
  // ...
59
59
  {
60
60
  rules: {
@@ -66,25 +66,27 @@ export default [
66
66
  },
67
67
  prettier,
68
68
  ];
69
+
70
+ export default config;
69
71
  ```
70
72
 
71
73
  Run `pnpm lint` and triage the output. Fix them one kind at a time (for example, all `any` removals together). Once clean, remove the overrides.
72
74
 
73
75
  ## Stage 4 — Names
74
76
 
75
- 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.
77
+ 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.
76
78
 
77
79
  ### 1. Decide what stays
78
80
 
79
81
  Before renaming anything, sort the short names into three piles:
80
82
 
81
- | Pile | What to do | Where to check |
82
- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------- |
83
- | **A dictionary word** — `id`, `docs`, `app`, `url`, `api` | Leave it | [Dictionary](/Standards/human-readable-names#dictionary) |
84
- | **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) |
85
- | **Our own shorthand** — `btn`, `lib/`, `helpers/`, `utilities/` | Rename it | The [Never / Always](/Standards/human-readable-names#never--always) table |
83
+ | Pile | What to do | Where to check |
84
+ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------ |
85
+ | **A dictionary word** — `id`, `docs`, `app`, `url`, `api` | Leave it | [Dictionary](/docs/Standards/human-readable-names#dictionary) |
86
+ | **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) |
87
+ | **Our own shorthand** — `btn`, `lib/`, `helpers/`, `utilities/` | Rename it | The [Never / Always](/docs/Standards/human-readable-names#never--always) table |
86
88
 
87
- **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.
89
+ **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.
88
90
 
89
91
  ### 2. The common renames
90
92
 
@@ -152,15 +154,15 @@ node node_modules/@activatus/code-standards/scripts/renameSymbol.mjs --list rena
152
154
 
153
155
  ## Stage 5 — AGENTS.md
154
156
 
155
- 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).
157
+ 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).
156
158
 
157
159
  ## Stage 6 — Agent skills
158
160
 
159
- Copy the eight [standard skill files](/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
161
+ Copy the eight [standard skill files](/docs/templates#skills) into `.agents/skills/`, and again into `.claude/commands/`.
160
162
 
161
163
  ## Stage 7 — Docs
162
164
 
163
- 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`.
165
+ 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`.
164
166
 
165
167
  ## Tips
166
168
 
package/docs/Guides/setup.md CHANGED
@@ -64,6 +64,7 @@ Tell me the numbers to skip or change, or say "all good".
64
64
  10. Node version set by .nvmrc and direnv
65
65
  11. Styling: Tailwind, flexbox first, colours only from the global palette
66
66
  12. Folder structure: folders at the project root; reusable helper functions in utils/ (no business rules, no outside calls)
67
+ 12.1. Constants: r for every link, s for every piece of text, noData for local stand-in data, shared numbers by topic, all in lib/constants/
67
68
  13. Components live where they are used: components/ui/, components/shared/, or beside their page
68
69
  14. Component files in a fixed order, with index.ts exports, and server and client code in separate files
69
70
  15. Design System Components: every project builds the standard components with the same props
@@ -95,7 +96,7 @@ Then wait for the answer.
95
96
 
96
97
  **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.
97
98
 
98
- 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).
99
+ 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).
99
100
 
100
101
  ## 4. Apply the standards
101
102
 
@@ -103,17 +104,18 @@ Do only the standards the person agreed to. Copy every file from `node_modules/@
103
104
 
104
105
  **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.
105
106
 
106
- **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.
107
+ **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.
107
108
 
108
109
  | Standard | What to set up |
109
110
  | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
- | 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"` |
111
+ | 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"` |
111
112
  | 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 ."` |
112
- | 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) |
113
+ | 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) |
113
114
  | 9. EditorConfig | Copy `static/templates/.editorconfig` |
114
- | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/Standards/direnv) |
115
+ | 10. Node version | Copy `static/templates/.nvmrc` and `static/templates/.envrc`. See [direnv + nvm](/docs/Standards/direnv) |
115
116
  | 11. Styling | Copy `static/templates/globals.css` to `app/globals.css`. Ask the person for the project's colours, and replace the example palette |
116
- | 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) |
117
+ | 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) |
118
+ | 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) |
117
119
  | 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/` |
118
120
 
119
121
  The other standards are rules for how code is written. There is nothing to install for them: follow them in every change.
@@ -146,7 +148,7 @@ The project already follows the standards, and a newer version is out.
146
148
  5. **Do every other change** as its "What to do" says, and run its "How to check" search.
147
149
  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).
148
150
 
149
- See the [Version History](/version-history) for the full update rules.
151
+ See the [Version History](/docs/version-history) for the full update rules.
150
152
 
151
153
  ---
152
154
 
package/docs/Standards/agent-skills.md CHANGED
@@ -4,7 +4,7 @@ sidebar_position: 8
4
4
 
5
5
  # Agent Skills
6
6
 
7
- 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.
7
+ 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.
8
8
 
9
9
  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.
10
10
 
@@ -71,7 +71,7 @@ Three rules follow from this:
71
71
 
72
72
  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.
73
73
  2. **Grant the narrowest set that still works.** `Bash(pnpm lint:*), Bash(eslint:*)` over a bare `Bash`.
74
- 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.
74
+ 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.
75
75
 
76
76
  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.
77
77
 
package/docs/Standards/agent-specs.md CHANGED
@@ -15,7 +15,7 @@ Each project writes them up in its own docs, usually in `docs/development/`, and
15
15
 
16
16
  ## Template
17
17
 
18
- Start from the [AGENTS.md template](/templates#agents) and replace every `[placeholder]`.
18
+ Start from the [AGENTS.md template](/docs/templates#agents) and replace every `[placeholder]`.
19
19
 
20
20
  ## Required sections
21
21
 
@@ -29,7 +29,7 @@ Every `AGENTS.md` must include these sections. Monorepos (`pnpm-workspace.yaml`,
29
29
  | Essential commands | Install, dev, build, test, lint, type-check |
30
30
  | 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 |
31
31
  | Environment variables | All required and optional env vars with descriptions |
32
- | Ontology | Link to the [ontology](/ontology), and the instruction to read it and use its terms |
32
+ | Ontology | Link to the [ontology](/docs/ontology), and the instruction to read it and use its terms |
33
33
  | Documentation | Where the project's docs are, and the instruction to read them before starting work |
34
34
  | Code standards | Link to these standards and the rules agents must follow in every change |
35
35
  | 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`,
37
37
 
38
38
  ## Standard skills
39
39
 
40
- 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).
40
+ 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).
41
41
 
42
42
  | Skill | Invocation | What it does |
43
43
  | -------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
package/docs/Standards/documentation.md CHANGED
@@ -32,7 +32,7 @@ A design system is a decision. A scope is a decision. A database choice is a dec
32
32
  - **Tickets own the _what_.** "Build GitHub authentication."
33
33
  - **Decision Docs own the _why_.** "Developers are our audience and we must sync directly to their repositories."
34
34
 
35
- See the [Ontology](/ontology#key-distinctions) for the terms.
35
+ See the [Ontology](/docs/ontology#key-distinctions) for the terms.
36
36
 
37
37
  ---
38
38
 
@@ -88,7 +88,7 @@ Keep these pairs distinct:
88
88
 
89
89
  ### Every file exists from the start
90
90
 
91
- **A new project starts with every reusable file already in place**, each marked `Status: Not started`. Copy the [doc templates](/templates#document-templates).
91
+ **A new project starts with every reusable file already in place**, each marked `Status: Not started`. Copy the [doc templates](/docs/templates#document-templates).
92
92
 
93
93
  - When a decision is made, **write it into the matching file**.
94
94
  - **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
165
165
 
166
166
  - **Overview comes first** in the menu. Every other group is in alphabetical order, and items are alphabetical within their group.
167
167
  - **Link between docs with relative `.md` paths** — `[Future](../scope/future.md)`. The link works in the file and on the site.
168
- - **Folder and file names are kebab-case**, because they become the route. See [Naming Conventions](/Structure/naming-conventions#when-to-use-kebab-case).
168
+ - **Folder and file names are kebab-case**, because they become the route. See [Naming Conventions](/docs/Structure/naming-conventions#when-to-use-kebab-case).
169
169
 
170
170
  The viewer does this automatically. There is no menu file to maintain.
171
171
 
@@ -173,7 +173,7 @@ The viewer does this automatically. There is no menu file to maintain.
173
173
 
174
174
  ## ✍️ Rules for writing
175
175
 
176
- - **Use the [Ontology](/ontology).** Use its terms for code, and the project's own ontology for product words.
176
+ - **Use the [Ontology](/docs/ontology).** Use its terms for code, and the project's own ontology for product words.
177
177
  - **One decision per file.**
178
178
  - **Plain Markdown (`.md`).** No JSX or imports, so every file reads the same for an agent as it does on the page.
179
179
  - **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.
182
182
 
183
183
  ### Not finished until the docs are updated
184
184
 
185
- **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).
185
+ **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).
186
186
 
187
187
  This applies to everyone writing code, **including AI agents**. An agent that changes how something works updates the Decision Doc that describes it.
188
188
 
@@ -262,9 +262,9 @@ export default nextConfig;
262
262
 
263
263
  ## 🚀 Setting it up
264
264
 
265
- 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.
265
+ 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.
266
266
 
267
- 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.
267
+ 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.
268
268
 
269
269
  3. **Add the route.** Add the rewrite above to `next.config.mjs`.
270
270