@activatus/code-standards 3.0.1 → 3.0.4

package/docs/Standards/eslint.md

@@ -191,6 +191,45 @@ import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 import { configs as typescript } from "typescript-eslint";
 
+// Code patterns that are errors in every file.
+const RESTRICTED_SYNTAX = [
+	{
+		selector: "ClassDeclaration",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "ClassExpression",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "VariableDeclarator > FunctionExpression",
+		message: "Use an arrow function.",
+	},
+	{
+		selector: "VariableDeclaration[kind='let']",
+		message:
+			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
+	},
+	{
+		selector: "FunctionDeclaration[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+	{
+		selector:
+			"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+];
+
+// Type a value where it is declared. Story files are the exception: see below.
+const NO_SATISFIES = {
+	selector: "TSSatisfiesExpression",
+	message:
+		"Type a value where it is declared, not with satisfies afterwards.",
+};
+
 export default [
 	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
 	js.configs.recommended,
@@ -228,34 +267,8 @@ export default [
 			],
 			"no-restricted-syntax": [
 				"error",
-				{
-					selector: "ClassDeclaration",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "ClassExpression",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "VariableDeclarator > FunctionExpression",
-					message: "Use an arrow function.",
-				},
-				{
-					selector: "VariableDeclaration[kind='let']",
-					message:
-						"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
-				},
-				{
-					selector: "FunctionDeclaration[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
-				{
-					selector:
-						"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -334,6 +347,13 @@ export default [
 		files: ["**/*.config.{js,mjs,ts}"],
 		rules: { "unicorn/no-top-level-side-effects": "off" },
 	},
+	{
+		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
+		files: ["**/*.stories.{ts,tsx}"],
+		rules: {
+			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+		},
+	},
 	prettier,
 ];
 ```
@@ -356,6 +376,45 @@ import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 import { configs as typescript } from "typescript-eslint";
 
+// Code patterns that are errors in every file.
+const RESTRICTED_SYNTAX = [
+	{
+		selector: "ClassDeclaration",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "ClassExpression",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "VariableDeclarator > FunctionExpression",
+		message: "Use an arrow function.",
+	},
+	{
+		selector: "VariableDeclaration[kind='let']",
+		message:
+			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
+	},
+	{
+		selector: "FunctionDeclaration[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+	{
+		selector:
+			"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+];
+
+// Type a value where it is declared. Story files are the exception: see below.
+const NO_SATISFIES = {
+	selector: "TSSatisfiesExpression",
+	message:
+		"Type a value where it is declared, not with satisfies afterwards.",
+};
+
 export default [
 	{ ignores: ["dist/", "build/", "coverage/", "**/vendor/**"] },
 	js.configs.recommended,
@@ -401,34 +460,8 @@ export default [
 			],
 			"no-restricted-syntax": [
 				"error",
-				{
-					selector: "ClassDeclaration",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "ClassExpression",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "VariableDeclarator > FunctionExpression",
-					message: "Use an arrow function.",
-				},
-				{
-					selector: "VariableDeclaration[kind='let']",
-					message:
-						"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
-				},
-				{
-					selector: "FunctionDeclaration[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
-				{
-					selector:
-						"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -516,6 +549,13 @@ export default [
 		files: ["**/*.config.{js,mjs,ts}"],
 		rules: { "unicorn/no-top-level-side-effects": "off" },
 	},
+	{
+		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
+		files: ["**/*.stories.{ts,tsx}"],
+		rules: {
+			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+		},
+	},
 	prettier,
 ];
 ```
@@ -540,6 +580,45 @@ import { flatConfigs as importX } from "eslint-plugin-import-x";
 import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 
+// Code patterns that are errors in every file.
+const RESTRICTED_SYNTAX = [
+	{
+		selector: "ClassDeclaration",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "ClassExpression",
+		message: "Use functions, not classes.",
+	},
+	{
+		selector: "VariableDeclarator > FunctionExpression",
+		message: "Use an arrow function.",
+	},
+	{
+		selector: "VariableDeclaration[kind='let']",
+		message:
+			"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
+	},
+	{
+		selector: "FunctionDeclaration[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+	{
+		selector:
+			"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
+		message:
+			"Use a single object parameter when a function needs more than one value.",
+	},
+];
+
+// Type a value where it is declared. Story files are the exception: see below.
+const NO_SATISFIES = {
+	selector: "TSSatisfiesExpression",
+	message:
+		"Type a value where it is declared, not with satisfies afterwards.",
+};
+
 export default [
 	{
 		ignores: [
@@ -591,34 +670,8 @@ export default [
 			],
 			"no-restricted-syntax": [
 				"error",
-				{
-					selector: "ClassDeclaration",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "ClassExpression",
-					message: "Use functions, not classes.",
-				},
-				{
-					selector: "VariableDeclarator > FunctionExpression",
-					message: "Use an arrow function.",
-				},
-				{
-					selector: "VariableDeclaration[kind='let']",
-					message:
-						"Use const. If this value really must be reassigned, disable this rule on this line with a comment saying why.",
-				},
-				{
-					selector: "FunctionDeclaration[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
-				{
-					selector:
-						"VariableDeclarator > :matches(ArrowFunctionExpression, FunctionExpression)[params.length>1]",
-					message:
-						"Use a single object parameter when a function needs more than one value.",
-				},
+				NO_SATISFIES,
+				...RESTRICTED_SYNTAX,
 			],
 			"import-x/no-cycle": "error",
 			"import-x/no-default-export": "error",
@@ -710,6 +763,13 @@ export default [
 		files: ["**/*.config.{js,mjs,ts}"],
 		rules: { "unicorn/no-top-level-side-effects": "off" },
 	},
+	{
+		// Storybook's own docs type stories with `satisfies Meta<typeof Component>`, so story files may use it.
+		files: ["**/*.stories.{ts,tsx}"],
+		rules: {
+			"no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+		},
+	},
 	prettier,
 ];
 ```
@@ -786,7 +846,7 @@ Third-party code that is copied into the repository lives in a `vendor/` folder,
 
 `vendor/` is only for third-party code we **do not change** — code that is replaced wholesale when the package updates.
 
-Code that is copied into the project and then **owned and edited by us** is our code, and every standard applies to it. The main case is **shadcn/ui**: the CLI copies component source into the project, and from then on it is ours. It is converted to our standards and lives in `components/ui/`, never in `vendor/`. See [Adding a shadcn component](/Guides/component-library-workflow#adding-a-shadcn-component).
+Code that is copied into the project and then **owned and edited by us** is our code, and every standard applies to it. The main case is **shadcn/ui**: the CLI copies component source into the project, and from then on it is ours. It is converted to our standards and lives in `components/ui/`, never in `vendor/`. See [Adding a shadcn component](/docs/Guides/component-library-workflow#adding-a-shadcn-component).
 
 | Code                                                      | Ours?   | Follows the standards?                     |
 | --------------------------------------------------------- | ------- | ------------------------------------------ |
@@ -799,11 +859,11 @@ If a vendored package lives somewhere else and cannot be moved, add its path to
 
 ## Key rule decisions
 
-Most of these enforce the [Readable Code](/Standards/readable-code) rules. For what each error means and how to fix it, see [Fixing Lint Errors](/Standards/lint-errors).
+Most of these enforce the [Readable Code](/docs/Standards/readable-code) rules. For what each error means and how to fix it, see [Fixing Lint Errors](/docs/Standards/lint-errors).
 
 ### `func-style`, `prefer-arrow-callback`: arrow functions everywhere
 
-Every function is an arrow function. See [Readable Code](/Standards/readable-code#arrow-functions-everywhere).
+Every function is an arrow function. See [Readable Code](/docs/Standards/readable-code#arrow-functions-everywhere).
 
 - `func-style: expression` rejects `function name() {}` declarations.
 - `prefer-arrow-callback` rejects `function` callbacks.
@@ -813,58 +873,58 @@ Every function is an arrow function. See [Readable Code](/Standards/readable-cod
 
 ### `no-restricted-syntax`, `prefer-const`, `no-var`: always `const`
 
-Variables are declared with `const`. `let` is an error unless the line carries a disable comment with a reason; `var` is never allowed. See [Readable Code](/Standards/readable-code#always-const).
+Variables are declared with `const`. `let` is an error unless the line carries a disable comment with a reason; `var` is never allowed. See [Readable Code](/docs/Standards/readable-code#always-const).
 
 ### `@eslint-community/eslint-comments/require-description`
 
-Every `eslint-disable` comment must say why, after `--`. A rule is never switched off silently. See [the only allowed exceptions](/Standards/lint-errors#the-only-allowed-exceptions).
+Every `eslint-disable` comment must say why, after `--`. A rule is never switched off silently. See [the only allowed exceptions](/docs/Standards/lint-errors#the-only-allowed-exceptions).
 
 ### `max-lines: 300`
 
-No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt. See [Readable Code](/Standards/readable-code#no-file-longer-than-300-lines).
+No file is longer than 300 lines, not counting blank lines and comments. Test files are exempt. See [Readable Code](/docs/Standards/readable-code#no-file-longer-than-300-lines).
 
 ### `max-depth: 3`
 
-Blocks nest at most three levels deep. Return early instead. See [Readable Code](/Standards/readable-code#return-early-nest-shallow).
+Blocks nest at most three levels deep. Return early instead. See [Readable Code](/docs/Standards/readable-code#return-early-nest-shallow).
 
 ### `no-nested-ternary`
 
-A ternary inside a ternary is an error. See [Readable Code](/Standards/readable-code#no-nested-ternaries).
+A ternary inside a ternary is an error. See [Readable Code](/docs/Standards/readable-code#no-nested-ternaries).
 
 ### `no-magic-numbers`
 
-Numbers other than `-1`, `0` and `1` must be named constants. Test files are exempt. TypeScript files use `@typescript-eslint/no-magic-numbers`, which understands enums and numeric literal types. See [Readable Code](/Standards/readable-code#no-magic-numbers-or-strings).
+Numbers other than `-1`, `0` and `1` must be named constants. Test files are exempt. TypeScript files use `@typescript-eslint/no-magic-numbers`, which understands enums and numeric literal types. See [Readable Code](/docs/Standards/readable-code#no-magic-numbers-or-strings).
 
 ### `no-restricted-syntax`: no classes, one parameter
 
 These are banned by syntax, along with `function` expressions (above):
 
-- **Class declarations and class expressions.** See [Readable Code](/Standards/readable-code#functions-never-classes).
-- **Functions you define with more than one parameter.** Use a single object parameter. Inline callbacks whose signature is set by someone else — `array.reduce((total, item) => …)`, event handlers — are not affected. See [Readable Code](/Standards/readable-code#one-parameter-always-an-object-for-more).
+- **Class declarations and class expressions.** See [Readable Code](/docs/Standards/readable-code#functions-never-classes).
+- **Functions you define with more than one parameter.** Use a single object parameter. Inline callbacks whose signature is set by someone else — `array.reduce((total, item) => …)`, event handlers — are not affected. See [Readable Code](/docs/Standards/readable-code#one-parameter-always-an-object-for-more).
 
 ### `import-x/no-cycle`: no circular imports
 
-A file may never import a file that imports it back, directly or through a chain of other files. See [Import safety](/Structure/import-organization#import-safety).
+A file may never import a file that imports it back, directly or through a chain of other files. See [Import safety](/docs/Structure/import-organization#import-safety).
 
 ### `no-use-before-define`
 
-A function or variable is defined above the code that uses it. TypeScript files use `@typescript-eslint/no-use-before-define`. See [Import safety](/Structure/import-organization#import-safety).
+A function or variable is defined above the code that uses it. TypeScript files use `@typescript-eslint/no-use-before-define`. See [Import safety](/docs/Structure/import-organization#import-safety).
 
 ### `import-x/no-default-export`
 
-Named exports only. Default exports are allowed where a tool requires them: config files, Storybook stories and Next.js route files. See [Readable Code](/Standards/readable-code#named-exports-only).
+Named exports only. Default exports are allowed where a tool requires them: config files, Storybook stories and Next.js route files. See [Readable Code](/docs/Standards/readable-code#named-exports-only).
 
 ### Import order is not linted
 
-There is deliberately no import-**order** rule (circular imports are a different matter — see above). Follow the [Import Organization](/Structure/import-organization) pattern for consistency, but ESLint will not complain about it.
+There is deliberately no import-**order** rule (circular imports are a different matter — see above). Follow the [Import Organization](/docs/Structure/import-organization) pattern for consistency, but ESLint will not complain about it.
 
 ### `unicorn/filename-case: camelCase or PascalCase`
 
-The plugin's default is kebab-case, which contradicts our [naming conventions](/Structure/naming-conventions). Files are camelCase (`formatDate.ts`), and component files are PascalCase (`UserProfile.tsx`).
+The plugin's default is kebab-case, which contradicts our [naming conventions](/docs/Structure/naming-conventions). Files are camelCase (`formatDate.ts`), and component files are PascalCase (`UserProfile.tsx`).
 
 ### `unicorn/name-replacements: error`
 
-Names are full English words: `btn` must be `button`, `e` must be `error` or `event`, `acc` must be `accumulator`. `docs`, `lib`, `props`, `ref`, `repo` and `utils` are allowed because they are on the [dictionary](/Standards/human-readable-names#dictionary) list. Only three names owned by React and Next.js are allowed exactly as they are — `ref`, `params` and `searchParams` — and our own names built from them are still flagged (`inputRef` must be `inputReference`). See [Human-Readable Names](/Standards/human-readable-names). (Before `eslint-plugin-unicorn` 77 this rule was called `unicorn/prevent-abbreviations`.)
+Names are full English words: `btn` must be `button`, `e` must be `error` or `event`, `acc` must be `accumulator`. `docs`, `lib`, `props`, `ref`, `repo` and `utils` are allowed because they are on the [dictionary](/docs/Standards/human-readable-names#dictionary) list. Only three names owned by React and Next.js are allowed exactly as they are — `ref`, `params` and `searchParams` — and our own names built from them are still flagged (`inputRef` must be `inputReference`). See [Human-Readable Names](/docs/Standards/human-readable-names). (Before `eslint-plugin-unicorn` 77 this rule was called `unicorn/prevent-abbreviations`.)
 
 ### `@typescript-eslint/no-explicit-any: error`
 
@@ -874,9 +934,13 @@ Names are full English words: `btn` must be `button`, `e` must be `error` or `ev
 
 The `!` operator tells the compiler a value exists without checking. Check it instead.
 
+### `no-restricted-syntax`: type first, never `satisfies`
+
+A value gets its type where it is declared: `const config: ConfigType = { … }`. `satisfies` attaches the type afterwards, so it is an error in the TypeScript, React and Next.js configs, except in story files (`*.stories.{ts,tsx}`), which follow Storybook's docs. The rule lists live in `RESTRICTED_SYNTAX` and `NO_SATISFIES` at the top of each config, so story files use every other restriction without repeating it. See [Type first, never `satisfies`](/docs/Standards/readable-code#type-first-never-satisfies).
+
 ### `@typescript-eslint/consistent-type-assertions: never`
 
-`as` casts are errors (`as const` is still allowed). When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/Standards/readable-code#no-any-no--no-unexplained-as) requires:
+`as` casts are errors (`as const` is still allowed). When a cast is genuinely needed, disable the rule on that line **with the reason** — which is exactly the comment the [standard](/docs/Standards/readable-code#no-any-no--no-unexplained-as) requires:
 
 ```ts
 // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- the API returns untyped JSON; validated by parseUser below
@@ -885,7 +949,7 @@ const user = response.data as UserType;
 
 ### `@typescript-eslint/naming-convention`: `Props` or `Type` suffix
 
-Every interface and type alias ends in `Props` or `Type`. See [Naming Conventions](/Structure/naming-conventions#types--interfaces).
+Every interface and type alias ends in `Props` or `Type`. See [Naming Conventions](/docs/Structure/naming-conventions#types--interfaces).
 
 ### `@typescript-eslint/consistent-type-imports: error`
 
@@ -893,8 +957,8 @@ Type-only imports use `import type { Foo }` or inline `import { type Foo }`. Thi
 
 ### `react/jsx-no-bind: error`
 
-No inline functions in render. A function passed as a JSX prop must be wrapped in `useCallback`, so it is not recreated on every render. See [Writing a component](/Structure/component-organization#-writing-a-component).
+No inline functions in render. A function passed as a JSX prop must be wrapped in `useCallback`, so it is not recreated on every render. See [Writing a component](/docs/Structure/component-organization#-writing-a-component).
 
 ### `react/no-multi-comp: error`
 
-One component per file. See [Readable Code](/Standards/readable-code#one-component-per-file).
+One component per file. See [Readable Code](/docs/Standards/readable-code#one-component-per-file).

package/docs/Standards/human-readable-names.md

@@ -5,7 +5,7 @@ sidebar_label: "Human-Readable Names"
 
 # Human-Readable Names
 
-**Every name we write is made of whole words a person can read out loud.** Variables, function parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters, no numbered names — not even for a loop counter or an event handler.
+**Every name we write is made of whole words a person can read out loud.** Variables, function parameters, props, types, constants, form fields, files, folders, routes, database columns, scripts and environment variables — everything. No shortened words, no single letters, no numbered names — not even for a loop counter or an event handler. The one exception is [`r` and `s`](#r-and-s).
 
 Anyone reading the code should never have to guess what a name stands for.
 
@@ -59,7 +59,7 @@ Everything that has a name:
 | **Doc files**                   | `architecture/background-jobs.md`                    | `arch/bg.md`, `notes2.md`                         |
 | **Error messages**              | `"Enter an email address"`                           | `"Invalid input"`, `"Error 42"`                   |
 
-The words come from the [Ontology](/ontology) wherever it has a term: reusable functions are in `utils/`, never `helpers/` or `utilities/`. A project's own ontology adds its product words: in Launchpad, a Draft Ticket is `draftTicket`, never `pendingTicket`. The casing comes from [Naming Conventions](/Structure/naming-conventions).
+The words come from the [Ontology](/docs/ontology) wherever it has a term: reusable functions are in `utils/`, never `helpers/` or `utilities/`. A project's own ontology adds its product words: in Launchpad, a Draft Ticket is `draftTicket`, never `pendingTicket`. The casing comes from [Naming Conventions](/docs/Structure/naming-conventions).
 
 ---
 
@@ -151,10 +151,20 @@ When a short name feels like a dictionary word, don't just use it — add it her
 
 1. **Ask:** is this the word people actually say, so the long form would only be harder to read? `docs`, `repo`: yes. `env`, `btn`, `msg`: no.
 2. **Add a row** to the table above, before or alongside the code that uses it.
-3. **If ESLint flags the word**, add it to `replacements` in the `unicorn/name-replacements` rule of the [ESLint config](/Standards/eslint), so the linter agrees: `replacements: { docs: false, lib: false, props: false, ref: false, repo: false, utils: false }`.
+3. **If ESLint flags the word**, add it to `replacements` in the `unicorn/name-replacements` rule of the [ESLint config](/docs/Standards/eslint), so the linter agrees: `replacements: { docs: false, lib: false, props: false, ref: false, repo: false, utils: false }`.
 
 The list is the record. If a word is not on it, it is not a dictionary word yet.
 
+## `r` and `s`: the only single letters {#r-and-s}
+
+**Two names are allowed to be a single letter:** `r`, the object of every route, and `s`, the object of every piece of static text. Both live in `lib/constants/`. See [Constants](/docs/Structure/folder-structure#constants).
+
+They are used so often that the short form is easier to read: `href={r.contact}` and `{s.contact}` read cleanly in a component, where `routes.contact` and `strings.contact` crowd it.
+
+- **Only these two.** No other single letter is allowed anywhere: not `e`, `i`, `x` or `T`, and not another constants object.
+- **Only as those two objects.** `r` is never a request or a result, and `s` is never a string or a second.
+- **Their keys are full words:** `r.linkedIn`, `s.pageNotFound`.
+
 ---
 
 ## Third-party names
@@ -272,3 +282,5 @@ users.map((u) => u.name);
 | **Everything else** — folders, props, form fields, union values, database columns, routes, environment variables, test names | **Code review and AI agents.** The linter cannot read these, so every agent and reviewer checks them |
 
 ESLint allows the [dictionary](#dictionary) words it would otherwise flag (`docs`, `lib`, `props`, `ref`, `repo`, `utils`), and exactly two third-party names as they are: `params` and `searchParams`. It still flags any of our own names built from an third-party name, such as `inputRef`.
+
+ESLint does not flag `r` or `s`. Reviewers check that they are only ever the two constants objects.

package/docs/Standards/lint-errors.md

@@ -29,12 +29,12 @@ This applies to everyone, **including AI agents**. An agent's work is not finish
 
 ## Imports
 
-| Rule                                         | What you will see                                                        | What it means                                                                                         | How to fix it                                                                                                                                                                                                      |
-| -------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `import-x/no-cycle`                          | `Dependency cycle detected`                                              | Two files import each other, directly or through other files. One will load before the other is ready | Move the part both files need into a **third file** that both import. If the cycle goes through an `index.ts`, import the file directly instead. See [Import safety](/Structure/import-organization#import-safety) |
-| `import-x/no-unresolved`                     | `Unable to resolve path to module '…'`                                   | The file being imported does not exist at that path                                                   | Check the spelling and the path. If the file was renamed or moved, update the import                                                                                                                               |
-| `import-x/no-default-export`                 | `Prefer named exports`                                                   | The file uses `export default`                                                                        | Change to a named export: `export const formatCurrency = …`                                                                                                                                                        |
-| `@typescript-eslint/consistent-type-imports` | `All imports in the declaration are only used as types. Use import type` | A type is imported like a value                                                                       | Change `import { UserType }` to `import type { UserType }`                                                                                                                                                         |
+| Rule                                         | What you will see                                                        | What it means                                                                                         | How to fix it                                                                                                                                                                                                           |
+| -------------------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `import-x/no-cycle`                          | `Dependency cycle detected`                                              | Two files import each other, directly or through other files. One will load before the other is ready | Move the part both files need into a **third file** that both import. If the cycle goes through an `index.ts`, import the file directly instead. See [Import safety](/docs/Structure/import-organization#import-safety) |
+| `import-x/no-unresolved`                     | `Unable to resolve path to module '…'`                                   | The file being imported does not exist at that path                                                   | Check the spelling and the path. If the file was renamed or moved, update the import                                                                                                                                    |
+| `import-x/no-default-export`                 | `Prefer named exports`                                                   | The file uses `export default`                                                                        | Change to a named export: `export const formatCurrency = …`                                                                                                                                                             |
+| `@typescript-eslint/consistent-type-imports` | `All imports in the declaration are only used as types. Use import type` | A type is imported like a value                                                                       | Change `import { UserType }` to `import type { UserType }`                                                                                                                                                              |
 
 ## Order and variables
 
@@ -57,6 +57,7 @@ This applies to everyone, **including AI agents**. An agent's work is not finish
 | `no-restricted-syntax`  | `Use an arrow function`                                                   | `const name = function () {}` was used          | Rewrite as `const name = () => {}`                                             |
 | `no-restricted-syntax`  | `Use a single object parameter when a function needs more than one value` | A function has more than one parameter          | Take one object instead: `({ name, emailAddress }: CreateUserProps) =>`        |
 | `no-restricted-syntax`  | `Use functions, not classes`                                              | A `class` was used                              | Rewrite it as functions                                                        |
+| `no-restricted-syntax`  | `Type a value where it is declared, not with satisfies afterwards`        | `satisfies` was used outside a story file       | Put the type on the declaration instead: `const config: ConfigType = { … }`    |
 | `max-depth`             | `Blocks are nested too deeply (4). Maximum allowed is 3`                  | `if`s and loops are nested more than three deep | Return early for the error cases, or move the inner part into its own function |
 | `no-nested-ternary`     | `Do not nest ternary expressions`                                         | A `? :` sits inside another `? :`               | Use an `if`, or move it into its own function                                  |
 
@@ -120,11 +121,11 @@ Nothing else is switched off. If another rule seems impossible to satisfy, the c
 
 ## Errors that stop ESLint running
 
-| What you will see                                 | What it means                                    | How to fix it                                                                     |
-| ------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------- |
-| `typescript-eslint does not support TS 7.0`       | The linter cannot run against TypeScript 7 yet   | See the [TypeScript 7 note](/Standards/eslint#installation) on the ESLint page    |
-| `contextOrFilename.getFilename is not a function` | The React plugin cannot detect the React version | Set `settings.react.version` to the project's React version instead of `"detect"` |
-| `Cannot find module '…'`                          | A lint package is not installed                  | Run the install commands on the [ESLint page](/Standards/eslint#installation)     |
+| What you will see                                 | What it means                                    | How to fix it                                                                       |
+| ------------------------------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `typescript-eslint does not support TS 7.0`       | The linter cannot run against TypeScript 7 yet   | See the [TypeScript 7 note](/docs/Standards/eslint#installation) on the ESLint page |
+| `contextOrFilename.getFilename is not a function` | The React plugin cannot detect the React version | Set `settings.react.version` to the project's React version instead of `"detect"`   |
+| `Cannot find module '…'`                          | A lint package is not installed                  | Run the install commands on the [ESLint page](/docs/Standards/eslint#installation)  |
 
 ---
 
@@ -132,4 +133,4 @@ Nothing else is switched off. If another rule seems impossible to satisfy, the c
 
 **Work is not finished until `pnpm lint` passes.** That goes for people and AI agents alike: an agent fixes every lint error before it says a task is done.
 
-How a project makes sure of it, such as a git hook or a check that runs on every change, is the project's own choice. See [Project workflow](/Standards/agent-specs#project-workflow).
+Most projects check it automatically on every change, with a CI job that runs `pnpm lint` (often with `pnpm test` and the build) or with a git hook. Which one, if any, is the project's own choice. See [Project workflow](/docs/Standards/agent-specs#project-workflow).