@activatus/code-standards 0.0.0-stage → 3.0.0

package/docs/Structure/naming-conventions.md

@@ -0,0 +1,334 @@
+---
+sidebar_position: 5
+---
+
+# Naming Conventions
+
+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).
+
+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`.
+
+## File Naming
+
+### Components
+
+**Use PascalCase** for React/Vue component files:
+
+```tsx
+✅ Good
+UserProfile.tsx
+DataTable.tsx
+SidebarNavigation.tsx
+SubmitButton.tsx
+
+❌ Bad
+userProfile.tsx
+data_table.tsx
+sidebar-nav.tsx
+```
+
+**Use PascalCase** for component declarations:
+
+```tsx
+✅ Good
+const UserProfile = () => { };
+const DataTable = () => { };
+const SubmitButton = () => { };
+
+❌ Bad
+const userProfile = () => { };
+const dataTable = () => { }
+const submit_button = () => { };
+```
+
+### Utils
+
+**Use camelCase** for utils files:
+
+```ts
+✅ Good
+apiUtils.ts
+formatDate.ts
+formatCurrency.ts
+
+❌ Bad
+api-utils.ts
+format-date.ts
+string-manipulation.ts
+format_currency.ts
+```
+
+### Hooks
+
+**Use camelCase** with `use` prefix:
+
+```ts
+✅ Good
+useUserData.ts
+useDebounce.ts
+useFormValidation.ts
+useLocalStorage.ts
+
+❌ Bad
+userData.ts
+getDebounce.ts
+formValidation.ts
+use-local-storage.ts
+```
+
+### Stores
+
+**Use camelCase** with `Store` suffix:
+
+```ts
+✅ Good
+userStore.ts
+cartStore.ts
+authenticationStore.ts
+preferencesStore.ts
+
+❌ Bad
+user.ts
+cart.ts
+useAuthStore.ts
+auth-store.ts
+```
+
+### Services
+
+**Use camelCase** with `Service` suffix:
+
+```ts
+✅ Good
+userService.ts
+apiService.ts
+paymentService.ts
+notificationService.ts
+
+❌ Bad
+UserService.ts
+api.ts
+payment.ts
+service-user.ts
+```
+
+### Types
+
+**Use camelCase** descriptive names:
+
+```ts
+✅ Good
+userWithPermissions.ts
+apiResponseData.ts
+cartItemWithProduct.ts
+recordingUsageData.ts
+
+❌ Bad
+UserWithPermissions.ts
+userTypes.ts
+apiResponse.ts
+data.ts
+```
+
+### Constants
+
+**Use camelCase** for constant file names, **SCREAMING_SNAKE_CASE** for the constants themselves:
+
+```ts
+✅ Good
+// File names
+userRole.ts
+httpStatus.ts
+paymentStatus.ts
+
+// Constant Variable Names
+const MAXIMUM_RETRY_ATTEMPTS = 3;
+const API_TIMEOUT_MILLISECONDS = 5000;
+const COOKIE_DURATION_DAYS = 30;
+
+❌ Bad Constant Variable Names
+const maxRetryAttempts = 3;
+const apiTimeout = 5000;
+const cookieDays = 30;
+```
+
+### CSS Modules
+
+**Use camelCase** with `.module.css` suffix:
+
+```tsx
+✅ Good
+userProfile.module.css
+dataTableStyles.module.css
+formComponents.module.css
+
+❌ Bad
+UserProfile.module.css
+data-table-styles.css
+form-components.module.css
+```
+
+### CSS Variables
+
+**Use kebab-case** for CSS variables (custom properties and design tokens): it is the CSS convention, it is what Tailwind requires, and Stylelint enforces it.
+
+```css
+/* ✅ Good */
+--color-brand-primary: #3b82f6;
+--spacing-unit: 0.25rem;
+
+/* ❌ Bad */
+--colorBrandPrimary: #3b82f6;
+--spacing_unit: 0.25rem;
+```
+
+See [CSS Styling](/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:
+
+```tsx
+✅ Good
+background-jobs.md        → /docs/architecture/background-jobs
+design-system.md
+product-market-fit.md
+
+❌ Bad
+backgroundJobs.md         → /docs/architecture/backgroundJobs
+design_system.md
+ProductMarketFit.md
+```
+
+---
+
+## Variables & Functions
+
+### Variables
+
+**Use camelCase**, and [full English words](/Standards/readable-code#names-are-full-english-words) — no shorthand:
+
+```ts
+✅ Good
+const userName = "John";
+const isLoading = true;
+const hasPermission = false;
+const itemCount = 10;
+
+❌ Bad
+const UserName = "John";
+const IsLoading = true;
+const has_permission = false;
+const item_count = 10;
+```
+
+### Functions
+
+Every function is an [arrow function](/Standards/readable-code#arrow-functions-everywhere).
+
+**Use camelCase** with descriptive verbs:
+
+```ts
+✅ Good
+const getUserData = () => { };
+const validateEmail = () => { };
+const calculateTotal = () => { };
+const handleSubmit = () => { };
+
+❌ Bad
+const GetUserData = () => { };
+const validate_email = () => { };
+const total = () => { };
+const submit = () => { };
+```
+
+### Boolean Variables
+
+**Prefix with `is`, `has`, `should`, `can`:**
+
+```ts
+✅ Good
+const isActive = true;
+const hasPermission = true;
+const shouldUpdate = false;
+const canDelete = true;
+
+❌ Bad
+const active = true;
+const permission = true;
+const update = false;
+const delete = true;
+```
+
+### Types & Interfaces
+
+**Use PascalCase** for types/interfaces, ending in **`Props`** or **`Type`** so it is clear what the name is:
+
+- **`Props`** — the single object parameter of a component or function (`ButtonProps`, `CreateUserProps`)
+- **`Type`** — everything else (`UserType`, `OrderStatusType`)
+
+```ts
+✅ Good
+type UserType = { };
+interface ApiResponseType { }
+interface UserCardProps { }
+
+❌ Bad
+type User = { };
+type userType = { };
+interface api_response { }
+interface UserCardData { }
+```
+
+See [Readable Code](/Standards/readable-code#type-names-say-what-they-are).
+
+---
+
+## When to Use kebab-case
+
+Code files are camelCase or PascalCase. A short list of things are kebab-case instead:
+
+| Thing                   | Example                                | Why                                      |
+| ----------------------- | -------------------------------------- | ---------------------------------------- |
+| **Route folders**       | `app/account-settings/`                | The folder name becomes the URL          |
+| **Documentation files** | `docs/architecture/background-jobs.md` | The file name becomes the URL            |
+| **CSS variables**       | `--color-brand-primary`                | The CSS convention; required by Tailwind |
+
+**The rule of thumb: if the name becomes a URL, it is kebab-case.**
+
+---
+
+## Quick Reference
+
+| Type                    | Convention                       | Example                      |
+| ----------------------- | -------------------------------- | ---------------------------- |
+| **Component files**     | PascalCase                       | `UserProfile.tsx`            |
+| **Utils files**         | camelCase                        | `formatDate.ts`              |
+| **Hook files**          | camelCase + `use`                | `useUserData.ts`             |
+| **Store files**         | camelCase + `Store`              | `userStore.ts`               |
+| **Service files**       | camelCase + `Service`            | `apiService.ts`              |
+| **Type files**          | camelCase                        | `userWithRoles.ts`           |
+| **Constant files**      | camelCase / SCREAMING_SNAKE_CASE | `userRole.ts` / `API_URL.ts` |
+| **CSS modules**         | camelCase + `.module.css`        | `userProfile.module.css`     |
+| **CSS variables**       | kebab-case                       | `--color-brand-primary`      |
+| **Documentation files** | kebab-case                       | `background-jobs.md`         |
+| **Variables**           | camelCase                        | `userName`                   |
+| **Functions**           | camelCase                        | `getUserData`                |
+| **Components**          | PascalCase                       | `UserProfile`                |
+| **Types**               | PascalCase + `Props` or `Type`   | `ButtonProps`, `UserType`    |
+| **Constants**           | SCREAMING_SNAKE_CASE             | `API_BASE_URL`               |
+| **Booleans**            | camelCase + prefix               | `isActive`, `hasPermission`  |
+
+---
+
+## Enforcing Conventions
+
+Use ESLint and Prettier to enforce these conventions automatically:
+
+- **eslint-plugin-react** - React naming conventions
+- **simple-import-sort** - Import ordering
+- **@typescript-eslint** - TypeScript naming rules
+
+See [ESLint](/Standards/eslint) and [Prettier](/Standards/prettier) configuration for setup.

package/docs/design-system-components.md

@@ -0,0 +1,117 @@
+---
+sidebar_position: 8
+sidebar_label: "Design System Components"
+---
+
+# 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.
+
+## 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).
+- **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.
+
+This applies to everyone building components, **including AI agents**.
+
+## Global / Navigation
+
+| #   | Component          | Variants                      | Key props                                                                                                              |
+| --- | ------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| 1   | **NavigationBar**  | default, large                | logo (asset)<br />navigationItems (link[])<br />callToAction (Button)<br />sticky (boolean)<br />transparent (boolean) |
+| 2   | **Expanded Menu**  | —                             | columns (linkGroup[])<br />featured (blok[])<br />trigger (text)                                                       |
+| 3   | **Hamburger Menu** | —                             | icon<br />menuItems (link[])<br />icon (asset)<br />position (left/right)                                              |
+| 4   | **Search Bar**     | inline, overlay               | placeholder<br />scope (text)<br />showSuggestions (boolean)                                                           |
+| 5   | **Promo Bar**      | —                             | text (richtext)<br />link<br />dismissible (boolean)<br />startDate<br />endDate                                       |
+| 6   | **Breadcrumbs**    | —                             | items (link[])<br />separator (text)<br />showHome (boolean)                                                           |
+| 7   | **Sidebar**        | —                             | items (link[])<br />position (left/right)<br />collapsible (boolean)<br />width                                        |
+| 8   | **Pagination**     | numbered, load-more, infinite | totalPages (number)<br />current (number)<br />showPrevNext (boolean)                                                  |
+| 9   | **Footer**         | slim, default, large          | logo<br />columns (linkGroup[])<br />socialLinks (link[])<br />legalLinks (link[])<br />copyright (text)               |
+
+## Auth / Account
+
+| #   | Component          | Variants | Key props                                                                               |
+| --- | ------------------ | -------- | --------------------------------------------------------------------------------------- |
+| 10  | **Login Form**     | —        | heading<br />forgotLink<br />signupLink<br />submitLabel                                |
+| 11  | **Sign-up Form**   | —        | heading<br />fields (Input[])<br />termsText (richtext)<br />loginLink<br />submitLabel |
+| 12  | **Password Reset** | —        | heading<br />helpText<br />submitLabel                                                  |
+| 13  | **Account Menu**   | —        | avatar (asset)<br />userName<br />menuItems (link[])<br />logoutLabel                   |
+
+## Hero / Headers
+
+| #   | Component       | Variants     | Key props                                                                                                                           |
+| --- | --------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
+| 14  | **Hero Banner** | Image, Video | heading<br />subheading<br />body (richtext)<br />media (asset/video)<br />buttons (Button[])<br />alignment<br />overlay (boolean) |
+| 15  | **Banner**      | —            | eyebrow<br />heading<br />subheading (richtext)<br />alignment                                                                      |
+
+## Layout primitives
+
+| #   | Component            | Variants | Key props                                                                                                     |
+| --- | -------------------- | -------- | ------------------------------------------------------------------------------------------------------------- |
+| 17  | **Duplex**           | —        | left (blok[])<br />right (blok[])<br />ratio (50/50, 60/40)<br />verticalAlign<br />reverseOnMobile (boolean) |
+| 18  | **Triplex**          | —        | columns (blok[] ×3)<br />gap<br />verticalAlign                                                               |
+| 19  | **Card Grid**        | —        | cards (blok[])<br />columns (number)<br />gap                                                                 |
+| 21  | **Section Wrapper**  | —        | content (blok[])<br />backgroundColor (token)<br />maximumWidth<br />anchorId                                 |
+| 22  | **Spacer / Divider** | —        | size (small/medium/large)<br />showLine (boolean)<br />lineColor                                              |
+| 23  | **Tab Group**        | —        | tabs array (label, content)<br />defaultTab                                                                   |
+| 25  | **Carousel**         | —        | slides (blok[])<br />autoplay (boolean)<br />interval<br />showArrows<br />showDots<br />slidesPerView        |
+| 26  | **Social Icons**     | —        | items array (icon, alt-text, url)                                                                             |
+
+## Content blocks
+
+| #   | Component              | Variants             | Key props                                                                                                    |
+| --- | ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ |
+| 26  | **Rich Text**          | —                    | content (richtext)                                                                                           |
+| 28  | **Notification Toast** | —                    | message<br />type (information/success/warning/error)<br />dismissible (boolean)<br />duration<br />position |
+| 29  | **Slider**             | —                    | direction<br />items array (image, title, url, testimonials)                                                 |
+| 46  | **Review**             | —                    | author<br />rating (number)<br />date<br />body<br />avatar<br />verified (boolean)                          |
+| 20  | **Card**               | default, image, icon | image (asset)<br />title<br />body (richtext)<br />link<br />button (Button)                                 |
+| 24  | **Accordion**          | —                    | items array (title, content)<br />allowMultiple (boolean)                                                    |
+
+## Media
+
+| #   | Component          | Variants | Key props                                                                                     |
+| --- | ------------------ | -------- | --------------------------------------------------------------------------------------------- |
+| 39  | **Image**          | —        | image (asset)<br />alt<br />caption<br />aspectRatio<br />link                                |
+| 40  | **Gallery**        | —        | images (asset[])<br />columns<br />enableLightbox (boolean)                                   |
+| 41  | **Video**          | —        | source (url/file)<br />poster (asset)<br />autoplay<br />loop<br />controls (boolean)         |
+| 42  | **Modal**          | —        | trigger (Button)<br />content (blok[])<br />size<br />closeOnOverlay (boolean)                |
+| 43  | **Map / Location** | —        | latitude (number)<br />longitude (number)<br />zoom<br />markers (blok[])<br />address (text) |
+| 44  | **Embed / iframe** | —        | url<br />aspectRatio<br />title<br />allowFullscreen (boolean)                                |
+
+## CTA / Forms
+
+| #   | Component                  | Variants                                            | Key props                                                                                                  |
+| --- | -------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| 49  | **CTA Banner**             | —                                                   | heading<br />body (richtext)<br />buttons (Button[])<br />backgroundColor (token)<br />alignment           |
+| 50  | **Newsletter Signup**      | inline, stacked                                     | heading<br />placeholder<br />submitLabel<br />consentText (richtext)                                      |
+| 51  | **Contact Form**           | —                                                   | heading<br />fields (Input[])<br />submitLabel<br />successMessage<br />recipientEmail                     |
+| 52  | **Input**                  | type: text, select, auto-select, dropdown, textarea | name<br />placeholder<br />required (boolean)<br />helpText<br />options (select/dropdown)<br />validation |
+| 53  | **Checkbox / Radio Group** | checkbox, radio                                     | name<br />options (text[])<br />required (boolean)<br />inline (boolean)                                   |
+| 54  | **Button**                 | primary, secondary, ghost                           | link<br />size (small/medium/large)<br />icon<br />iconPosition<br />fullWidth (boolean)                   |
+| 55  | **Cookie Banner**          | —                                                   | text (richtext)<br />acceptLabel<br />rejectLabel<br />policyLink                                          |
+
+## Utility (low-level primitives)
+
+| #   | Component        | Variants                             | Key props                                                                       |
+| --- | ---------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
+| 56  | **Icon**         | —                                    | name (text)<br />size<br />color (token)                                        |
+| 57  | **Avatar**       | image, initials                      | image (asset)<br />name<br />size<br />shape (circle/square)                    |
+| 59  | **Tooltip**      | —                                    | content (text)<br />position (top/right/bottom/left)<br />trigger (hover/click) |
+| 60  | **Progress Bar** | linear, circular                     | value (number)<br />maximum (number)<br />showLabel (boolean)                   |
+| 61  | **Alert**        | information, success, warning, error | message (richtext)<br />type<br />dismissible (boolean)<br />icon (asset)       |
+
+---
+
+**Legend:**
+
+- **blok[]** = Array of nested blocks/components (Storyblok terminology)
+- **richtext** = Rich text content (HTML/Markdown)
+- **asset** = Image or media file reference
+- **token** = Design system token (color, spacing, etc.)
+- **array (x, y)** = Array of objects with properties x, y

package/docs/intro.md

@@ -0,0 +1,44 @@
+---
+slug: /
+sidebar_position: 1
+sidebar_label: "Introduction"
+---
+
+# Activatus Code Standards
+
+This site documents the shared code standards used across all Activatus projects. Every project applies the same linting, formatting, structure and naming rules, so moving between codebases never means relearning the basics.
+
+## 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).
+
+## 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.
+
+## 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`.
+
+## 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.
+
+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).
+
+**If anything here is unclear, ask the person.** Do not guess, and do not invent a rule.

package/docs/ontology.md

@@ -0,0 +1,127 @@
+---
+sidebar_position: 1.5
+sidebar_label: "Ontology"
+---
+
+# Ontology
+
+> The words these standards use about code, and exactly what each one means.
+
+**Status:** Decided · **Updated:** 2026-10-15
+
+**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.
+
+An ontology is a shared vocabulary. When a person or an agent says "component", "utils" or "Decision Doc", this page is what they mean. Nobody has to guess, and nobody invents a second word for the same thing.
+
+## Code words and product words
+
+This page only holds **code words**: how code is written, named, tested, documented and reviewed.
+
+**Product words live in each project's own ontology**, in `docs/product/ontology.md`: the words for what that project builds and how its team plans the work. **Project-management words live there too**: project, feature, ticket, branch, commit, Pull Request, release. Every project defines those for itself. Launchpad's Draft Ticket, Pitch and UAT are product words, so they are in Launchpad's ontology, not here.
+
+|              | Code words                                               | Product words                                       |
+| ------------ | -------------------------------------------------------- | --------------------------------------------------- |
+| **Kept in**  | This page                                                | The project's `docs/product/ontology.md`            |
+| **Covers**   | Writing, naming, testing, documenting and reviewing code | What the project builds and how its work is planned |
+| **Examples** | component, utils, Decision Doc, dictionary word          | Launchpad's Draft Ticket, Pitch, UAT                |
+
+**A project's ontology pulls in this page. It never redefines a code word.** If a project's ontology gives a word on this page a different meaning, this page wins. Point the difference out so the project's ontology can be fixed.
+
+## How to use this page
+
+- **Read it before starting work on any Activatus project**, then read the project's own ontology.
+- **Use the term on this page**, not a synonym: `utils`, never `helpers` or `utilities`.
+- **If a term here has no definition, or you are not sure what is meant, ask.** Do not guess, and do not invent a new term.
+
+### Writing a term
+
+The words stay the same everywhere. Only the casing changes, to match where the term is written:
+
+| Where                                          | Written as   | Example           |
+| ---------------------------------------------- | ------------ | ----------------- |
+| Database names, and the form used on this page | `snake_case` | `decision_doc`    |
+| Code — variables and functions                 | camelCase    | `decisionDoc`     |
+| Code — types and components                    | PascalCase   | `DecisionDocType` |
+| Docs, prompts and UI                           | Title Case   | Decision Doc      |
+
+---
+
+## The terms
+
+### 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                                                                 |
+
+### People and agents
+
+| Term            | Means                                                                                                                                                                                                                                         |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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_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                                                                                                       |
+| `model`         | The AI model an agent thinks with                                                                                                                                                                                                             |
+| `mcp`           | Model Context Protocol: the standard way to connect an agent to outside tools and data, such as Linear or GitHub. An MCP server offers tools, and the agent calls them                                                                        |
+
+### 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)                                                                                                                                                                                                                                                                    |
+
+### 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) |
+
+---
+
+## Key distinctions
+
+These are the terms most easily confused. The **Not** column is the word we do not use.
+
+| Term                                        | Means                                                                                                                                                   | Not                    |
+| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |
+| **Decision / Decision Doc**                 | The choice itself vs the file that records it                                                                                                           |                        |
+| **Docs / Docs Site**                        | The Markdown files vs the viewer that shows them                                                                                                        |                        |
+| **Props**                                   | The values a component takes                                                                                                                            | `properties`           |
+| **Utils**                                   | Reusable functions                                                                                                                                      | `helpers`, `utilities` |
+| **Dictionary Word / Third-Party Name**      | A short name we chose to keep vs a name someone else chose for us                                                                                       |                        |
+| **Design System / Shared / Page Component** | The same in every project (`components/ui/`) vs used on several pages of this project (`components/shared/`) vs used by one page or section (beside it) |                        |
+
+---
+
+## Changing the ontology
+
+**This page is the one place code words are kept.** Change them here, never in a project's ontology.
+
+- **Adding a term**: add it to the right group above. If it could be confused with another term, add a row to [Key distinctions](#key-distinctions).
+- **Removing a term**: say what to use instead, in the same change.
+- **A product word that every project uses** — not just one — can move here. Agree it first, then remove it from each project's ontology.
+- **Either way**, update the date at the top of this page.