@jterrazz/test 9.0.0 → 9.1.0

package/README.md

@@ -297,7 +297,7 @@ import { mockOf, mockOfDate } from '@jterrazz/test';
 
 ## Conventions
 
-Normative rules live in [CONVENTIONS.md](CONVENTIONS.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
+Normative rules live in the constitution ([docs/09-conventions.md](docs/09-conventions.md)); the generated per-rule catalogue is [docs/10-linting.md](docs/10-linting.md). A facet (`specs/<facet>/`) carries its runner(s) at its root and holds domain folders; the folder follows the assets:
 
 ```
 specs/<facet>/                  # api | jobs | cli | integrations | lint
@@ -318,7 +318,7 @@ Every test contains `// Given -` and `// Then -` comments (always both; `// When
 
 ### Convention enforcement — the shipped lint plugin
 
-These conventions are not just prose: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) with ~40 AST rules, plus a `jterrazz-test-check` binary (the conventions checker) that reads the data fixtures and cross-file relationships oxlint cannot. Wire the plugin into your `oxlint.config.ts` and run `jterrazz-test-check specs` in CI — the full catalogue (each rule, its channel and rationale) lives in [CONVENTIONS-CATALOG.md](CONVENTIONS-CATALOG.md).
+These conventions are not just prose: the package ships an oxlint plugin (`@jterrazz/test/oxlint`) with ~40 AST rules, plus a `jterrazz-test-check` binary (the conventions checker) that reads the data fixtures and cross-file relationships oxlint cannot. Wire the plugin into your `oxlint.config.ts` and run `jterrazz-test-check specs` in CI — the full four-channel catalogue (each rule, its channel and rationale) is generated into [docs/10-linting.md](docs/10-linting.md).
 
 ## Requirements
 
@@ -329,6 +329,6 @@ These conventions are not just prose: the package ships an oxlint plugin (`@jter
 
 ## Docs
 
-- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI specs, assertions, tokens, contracts, services, conventions
-- API reference + LLM-friendly docs: <https://jterrazz.github.io/package-test/>
-- Agent ingestion: <https://jterrazz.github.io/package-test/llms-full.txt>
+- Guide (chapters): [docs/README.md](docs/README.md) — getting started, API/jobs/CLI specs, assertions, tokens, contracts, services, conventions, linting
+- API reference: committed under [docs/reference/](docs/reference/) — compiled from source by `npm run docs`
+- Agent skill: [skills/jterrazz-test/](skills/jterrazz-test/) — mental model, per-facet references, generated rule reference

package/dist/checker.js

@@ -375,7 +375,7 @@ function checkDockerRunnerAwaitUsing(rootDir) {
 			violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: result of docker-aware runner "${runner}" must be bound with \`await using\` so its containers are disposed (CONVENTIONS B5)`,
+				message: `${rel}:${line}: result of docker-aware runner "${runner}" must be bound with \`await using\` so its containers are disposed (B5 — see docs/10-linting.md)`,
 				severity: "error"
 			});
 		}
@@ -431,13 +431,13 @@ function checkDatabaseProperty(rootDir) {
 			if (count >= 2 && !hasDatabase) violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (CONVENTIONS A7)`,
+				message: `${rel}:${line}: .${verb}() must pass { database } — ${count} SQL databases are declared (A7 — see docs/10-linting.md)`,
 				severity: "error"
 			});
 			else if (count === 1 && hasDatabase) violations.push({
 				file: rel,
 				line,
-				message: `${rel}:${line}: .${verb}() must not pass { database } — a single SQL database is declared (CONVENTIONS A7)`,
+				message: `${rel}:${line}: .${verb}() must not pass { database } — a single SQL database is declared (A7 — see docs/10-linting.md)`,
 				severity: "error"
 			});
 		}
@@ -485,7 +485,7 @@ function checkDeadFixtures(rootDir) {
 			violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}: domain directory has conventional subdirs (${convSubdirs.join(", ")}) but no *.test.ts (CONVENTIONS C9)`,
+				message: `${rel}: domain directory has conventional subdirs (${convSubdirs.join(", ")}) but no *.test.ts (C9 — see docs/10-linting.md)`,
 				severity: "error"
 			});
 			continue;
@@ -507,7 +507,7 @@ function checkDeadFixtures(rootDir) {
 				violations.push({
 					file: relEntry,
 					line: 1,
-					message: `${relEntry}: dead fixture — no test literal in ${feature} references ${sub}/${entry.name} (CONVENTIONS C9)`,
+					message: `${relEntry}: dead fixture — no test literal in ${feature} references ${sub}/${entry.name} (C9 — see docs/10-linting.md)`,
 					severity
 				});
 			}
@@ -531,7 +531,7 @@ function checkPoolFixtures(rootDir) {
 			violations.push({
 				file: relEntry,
 				line: 1,
-				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot)} references $FIXTURES/${entry.name} (CONVENTIONS C9)`,
+				message: `${relEntry}: dead pool fixture — no spec under ${relative(rootDir, specsRoot)} references $FIXTURES/${entry.name} (C9 — see docs/10-linting.md)`,
 				severity: "error"
 			});
 		}
@@ -663,13 +663,13 @@ function checkConventionFiles(rootDir) {
 				if (depth1 && !REQUEST_LINE.test(firstLine(text))) violations.push({
 					file: rel,
 					line: 1,
-					message: `${rel}:1: a requests/*.http file must start with a request line "METHOD /path" (CONVENTIONS D4b)`,
+					message: `${rel}:1: a requests/*.http file must start with a request line "METHOD /path" (D4b — see docs/10-linting.md)`,
 					severity: "error"
 				});
 				for (const { line, token } of findKnownTokens(text)) violations.push({
 					file: rel,
 					line,
-					message: `${rel}:${line}: token ${token} in a requests/ file — requests are inputs, never matched; tokens are not validated here (CONVENTIONS D10)`,
+					message: `${rel}:${line}: token ${token} in a requests/ file — requests are inputs, never matched; tokens are not validated here (D10 — see docs/10-linting.md)`,
 					severity: "warn",
 					token
 				});
@@ -680,7 +680,7 @@ function checkConventionFiles(rootDir) {
 			if (depth1 && entry.name.endsWith(".http") && !STATUS_LINE.test(firstLine(text))) violations.push({
 				file: rel,
 				line: 1,
-				message: `${rel}:1: an expected/*.http file must start with a status line "HTTP/1.1 <status>" (CONVENTIONS D4b)`,
+				message: `${rel}:1: an expected/*.http file must start with a status line "HTTP/1.1 <status>" (D4b — see docs/10-linting.md)`,
 				severity: "error"
 			});
 			for (const { line, token } of findUnknownTokens(text)) violations.push({

package/dist/oxlint.cjs

@@ -657,7 +657,7 @@ const a1SpecificationFile = {
 	},
 	meta: {
 		docs: RULE_DOCS["a1-specification-file"],
-		messages: { outsideSpecification: "specification.{{member}}() must be called from a `*.specification.ts` file under specs/ (CONVENTIONS A1)." },
+		messages: { outsideSpecification: "specification.{{member}}() must be called from a `*.specification.ts` file under specs/ (A1 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -734,13 +734,13 @@ const a10DuplicateBinding = {
 	},
 	meta: {
 		docs: RULE_DOCS["a10-duplicate-binding"],
-		messages: { duplicate: "Service keys \"{{first}}\" and \"{{key}}\" both bind to compose service \"{{binding}}\" — one shadows the other; rename a key or set distinct composeService values (CONVENTIONS A10)." },
+		messages: { duplicate: "Service keys \"{{first}}\" and \"{{key}}\" both bind to compose service \"{{binding}}\" — one shadows the other; rename a key or set distinct composeService values (A10 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The three constructors, and only three (CONVENTIONS A2). */
+/** The three constructors, and only three (A2 — see docs/10-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
@@ -766,7 +766,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs() and specification.cli() (CONVENTIONS A2)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs() and specification.cli() (A2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -811,7 +811,7 @@ const a3NoDestructureAlias = {
 	},
 	meta: {
 		docs: RULE_DOCS["a3-no-destructure-alias"],
-		messages: { aliased: "Destructure the specification result with its canonical name: `{{key}}`, not `{{key}}: {{alias}}` (CONVENTIONS A3). Rename at the import site if a different local name is needed." },
+		messages: { aliased: "Destructure the specification result with its canonical name: `{{key}}`, not `{{key}}: {{alias}}` (A3 — see docs/10-linting.md). Rename at the import site if a different local name is needed." },
 		type: "problem"
 	}
 };
@@ -863,7 +863,7 @@ const a4CleanupAfterall = {
 	},
 	meta: {
 		docs: RULE_DOCS["a4-cleanup-afterall"],
-		messages: { unregistered: "`cleanup` is destructured but never passed to afterAll — add `afterAll(cleanup)` to the specification file (CONVENTIONS A4)." },
+		messages: { unregistered: "`cleanup` is destructured but never passed to afterAll — add `afterAll(cleanup)` to the specification file (A4 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -893,7 +893,7 @@ const a5ModeWithServer = {
 	},
 	meta: {
 		docs: RULE_DOCS["a5-mode-with-server"],
-		messages: { hardcodedMode: "`mode` must not be hardcoded when `server` is defined — the node/compose switch lives in vitest.config.ts via `env: { TEST_MODE: \"compose\" }` (CONVENTIONS A5)." },
+		messages: { hardcodedMode: "`mode` must not be hardcoded when `server` is defined — the node/compose switch lives in vitest.config.ts via `env: { TEST_MODE: \"compose\" }` (A5 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -934,7 +934,7 @@ const a6wRedundantComposeService = {
 	},
 	meta: {
 		docs: RULE_DOCS["a6w-redundant-compose-service"],
-		messages: { redundant: "composeService: \"{{name}}\" is redundant — the key \"{{key}}\" already binds to it (exact name or kebab-case derivation, CONVENTIONS A6)." },
+		messages: { redundant: "composeService: \"{{name}}\" is redundant — the key \"{{key}}\" already binds to it (exact name or kebab-case derivation, A6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -998,7 +998,7 @@ function readFileCached(path) {
 //#endregion
 //#region src/lint/rules/a9w-redundant-root.ts
 /**
-* The root the convention would derive (CONVENTIONS A9): walk up from the
+* The root the convention would derive (A9 — see docs/10-linting.md): walk up from the
 * specification file to the first directory containing
 * `docker/compose.test.yaml`, else the first containing `package.json`.
 */
@@ -1037,7 +1037,7 @@ const a9wRedundantRoot = {
 	},
 	meta: {
 		docs: RULE_DOCS["a9w-redundant-root"],
-		messages: { redundant: "root: \"{{root}}\" is redundant — walking up from the specification file already resolves to that directory (CONVENTIONS A9)." },
+		messages: { redundant: "root: \"{{root}}\" is redundant — walking up from the specification file already resolves to that directory (A9 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1101,7 +1101,7 @@ const b2KnownFixtureMarker = {
 	},
 	meta: {
 		docs: RULE_DOCS["b2-known-fixture-marker"],
-		messages: { unknownMarker: "Unknown fixture marker \"{{marker}}\" — known markers: {{known}}. A path without a marker is feature-local (CONVENTIONS B2)." },
+		messages: { unknownMarker: "Unknown fixture marker \"{{marker}}\" — known markers: {{known}}. A path without a marker is feature-local (B2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1166,8 +1166,8 @@ const b4GivenThen = {
 	meta: {
 		docs: RULE_DOCS["b4-given-then"],
 		messages: {
-			givenAfterThen: "The `// Given -` marker comes after `// Then -` — Given describes the setup and must precede Then (CONVENTIONS B4).",
-			missing: "Test is missing a `// {{marker}} -` comment (CONVENTIONS B4 — every test needs both `// Given -` and `// Then -`)."
+			givenAfterThen: "The `// Given -` marker comes after `// Then -` — Given describes the setup and must precede Then (B4 — see docs/10-linting.md).",
+			missing: "Test is missing a `// {{marker}} -` comment (B4 — see docs/10-linting.md — every test needs both `// Given -` and `// Then -`)."
 		},
 		type: "problem"
 	}
@@ -1208,7 +1208,7 @@ const b5AwaitUsing = {
 	meta: {
 		docs: RULE_DOCS["b5-await-using"],
 		defaultOptions: [{ runners: [] }],
-		messages: { requireAwaitUsing: "The result of docker-aware runner \"{{runner}}\" must be bound with `await using` so its containers are disposed (CONVENTIONS B5)." },
+		messages: { requireAwaitUsing: "The result of docker-aware runner \"{{runner}}\" must be bound with `await using` so its containers are disposed (B5 — see docs/10-linting.md)." },
 		schema: [{
 			additionalProperties: false,
 			properties: { runners: {
@@ -1251,7 +1251,7 @@ const b6wRedundantEnvUrl = {
 	},
 	meta: {
 		docs: RULE_DOCS["b6w-redundant-env-url"],
-		messages: { redundant: ".env({ {{key}}: ….connectionString }) is redundant — the framework already injects <KEY>_URL (and the DATABASE_URL/REDIS_URL aliases) for every service (CONVENTIONS B6)." },
+		messages: { redundant: ".env({ {{key}}: ….connectionString }) is redundant — the framework already injects <KEY>_URL (and the DATABASE_URL/REDIS_URL aliases) for every service (B6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1280,7 +1280,7 @@ const b8KebabTrigger = {
 	},
 	meta: {
 		docs: RULE_DOCS["b8-kebab-trigger"],
-		messages: { notKebab: "Job name \"{{name}}\" must be a stable kebab-case identifier (e.g. \"nightly-report\") — it is a contract between the app and its tests (CONVENTIONS B8)." },
+		messages: { notKebab: "Job name \"{{name}}\" must be a stable kebab-case identifier (e.g. \"nightly-report\") — it is a contract between the app and its tests (B8 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1335,7 +1335,7 @@ const b9wProductCommand = {
 	},
 	meta: {
 		docs: RULE_DOCS["b9w-product-command"],
-		messages: { thirdPartyBinary: "specification.cli() points at a third-party binary in node_modules/.bin — a spec should exercise your product command (cli.exec(\"check\"), …), not the tool underneath (CONVENTIONS B9). Suppress with a reason if the product genuinely is this binary." },
+		messages: { thirdPartyBinary: "specification.cli() points at a third-party binary in node_modules/.bin — a spec should exercise your product command (cli.exec(\"check\"), …), not the tool underneath (B9 — see docs/10-linting.md). Suppress with a reason if the product genuinely is this binary." },
 		type: "suggestion"
 	}
 };
@@ -1391,9 +1391,9 @@ const c1DomainStructure = {
 	meta: {
 		docs: RULE_DOCS["c1-domain-structure"],
 		messages: {
-			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (CONVENTIONS C1).",
-			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (CONVENTIONS C1).",
-			testTooDeep: "A `*.test.ts` must sit at facet/domain depth: `specs/<facet>/<domain>/<aspect>.test.ts` — no deeper nesting (CONVENTIONS C1)."
+			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (C1 — see docs/10-linting.md).",
+			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (C1 — see docs/10-linting.md).",
+			testTooDeep: "A `*.test.ts` must sit at facet/domain depth: `specs/<facet>/<domain>/<aspect>.test.ts` — no deeper nesting (C1 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -1423,13 +1423,13 @@ const c2HttpOnlyRequests = {
 	},
 	meta: {
 		docs: RULE_DOCS["c2-http-only-requests"],
-		messages: { notHttp: "requests/{{entry}} is not a .http file — requests/ contains only complete .http request files (CONVENTIONS C2)." },
+		messages: { notHttp: "requests/{{entry}} is not a .http file — requests/ contains only complete .http request files (C2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/c4-contract-shape.ts
-/** Providers a contract file may declare (CONVENTIONS C4). */
+/** Providers a contract file may declare (C4 — see docs/10-linting.md). */
 const PROVIDERS = /* @__PURE__ */ new Set([
 	"anthropic",
 	"http",
@@ -1495,12 +1495,12 @@ const c4ContractShape = {
 	meta: {
 		docs: RULE_DOCS["c4-contract-shape"],
 		messages: {
-			badName: "Contract file \"{{base}}\" must be named <name>.<provider>.ts with provider ∈ openai | anthropic | http (CONVENTIONS C4).",
-			foreignImport: "Contract imports \"{{source}}\" — a contract imports only from the public entry (@jterrazz/test) (CONVENTIONS C4).",
-			missingDefault: "Contract file has no `export default defineContract(...)` (CONVENTIONS C4).",
-			namedExport: "Contract files have no named exports — only `export default defineContract(...)` (CONVENTIONS C4).",
-			notDefineContract: "The default export of a contract file must be `defineContract(...)` syntactically (CONVENTIONS C4).",
-			subfolder: "Contract file \"{{base}}\" is nested — contracts/ is flat, no subfolders (CONVENTIONS C4)."
+			badName: "Contract file \"{{base}}\" must be named <name>.<provider>.ts with provider ∈ openai | anthropic | http (C4 — see docs/10-linting.md).",
+			foreignImport: "Contract imports \"{{source}}\" — a contract imports only from the public entry (@jterrazz/test) (C4 — see docs/10-linting.md).",
+			missingDefault: "Contract file has no `export default defineContract(...)` (C4 — see docs/10-linting.md).",
+			namedExport: "Contract files have no named exports — only `export default defineContract(...)` (C4 — see docs/10-linting.md).",
+			notDefineContract: "The default export of a contract file must be `defineContract(...)` syntactically (C4 — see docs/10-linting.md).",
+			subfolder: "Contract file \"{{base}}\" is nested — contracts/ is flat, no subfolders (C4 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -1551,7 +1551,7 @@ const c6ToMatchExtension = {
 	},
 	meta: {
 		docs: RULE_DOCS["c6-tomatch-extension"],
-		messages: { missingExtension: "toMatch(\"{{name}}\") is missing its extension — the extension is part of the fixture name (\"help.txt\", never \"help\"); only directory-tree snapshots (expected/<name>/) omit it (CONVENTIONS C6)." },
+		messages: { missingExtension: "toMatch(\"{{name}}\") is missing its extension — the extension is part of the fixture name (\"help.txt\", never \"help\"); only directory-tree snapshots (expected/<name>/) omit it (C6 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1579,7 +1579,7 @@ const c7SeedsSqlOnly = {
 	},
 	meta: {
 		docs: RULE_DOCS["c7-seeds-sql-only"],
-		messages: { notSql: "seeds/{{entry}} is not a .sql file — seeds/ carries database state only; file state goes through .fixture() (CONVENTIONS C7)." },
+		messages: { notSql: "seeds/{{entry}} is not a .sql file — seeds/ carries database state only; file state goes through .fixture() (C7 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1668,7 +1668,7 @@ const c8ReferencedFixtureExists = {
 	},
 	meta: {
 		docs: RULE_DOCS["c8-referenced-fixture-exists"],
-		messages: { missing: "Referenced fixture \"{{path}}\" does not exist on disk under its conventional {{root}}/ root (CONVENTIONS C8). Create it or fix the reference." },
+		messages: { missing: "Referenced fixture \"{{path}}\" does not exist on disk under its conventional {{root}}/ root (C8 — see docs/10-linting.md). Create it or fix the reference." },
 		type: "problem"
 	}
 };
@@ -1737,7 +1737,7 @@ const d12wResponseBodyProbe = {
 	meta: {
 		docs: RULE_DOCS["d12w-response-body-probe"],
 		defaultOptions: [{ threshold: DEFAULT_THRESHOLD }],
-		messages: { bodyProbeCluster: "{{count}} body probes in one test — this wants a full golden: expect(result.response).toMatch('x.http') (CONVENTIONS D12)." },
+		messages: { bodyProbeCluster: "{{count}} body probes in one test — this wants a full golden: expect(result.response).toMatch('x.http') (D12 — see docs/10-linting.md)." },
 		schema: [{
 			additionalProperties: false,
 			properties: { threshold: {
@@ -1820,7 +1820,7 @@ const d13wUnfrozenNegativeFixture = {
 	},
 	meta: {
 		docs: RULE_DOCS["d13w-unfrozen-negative-fixture"],
-		messages: { unfrozenNegativeFixture: "This toMatch asserts a mismatch (wrapped in expect(…).toThrow/.rejects) — pass { frozen: true } so TEST_UPDATE=1 never overwrites the deliberately-wrong fixture (CONVENTIONS D13)." },
+		messages: { unfrozenNegativeFixture: "This toMatch asserts a mismatch (wrapped in expect(…).toThrow/.rejects) — pass { frozen: true } so TEST_UPDATE=1 never overwrites the deliberately-wrong fixture (D13 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1896,7 +1896,7 @@ const d15wStatusOnlyProbe = {
 	},
 	meta: {
 		docs: RULE_DOCS["d15w-status-only-probe"],
-		messages: { statusOnlyProbe: "The test's only assertion(s) are status probes — pin the full response: expect(result.response).toMatch('case.http') (CONVENTIONS D11)." },
+		messages: { statusOnlyProbe: "The test's only assertion(s) are status probes — pin the full response: expect(result.response).toMatch('case.http') (D11 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1951,7 +1951,7 @@ const d2AwaitIoMatcher = {
 	},
 	meta: {
 		docs: RULE_DOCS["d2-await-io-matcher"],
-		messages: { mustAwait: "expect(…).{{matcher}}(…) is IO-backed and returns a promise — it must be awaited or returned, else the assertion never runs (CONVENTIONS D2)." },
+		messages: { mustAwait: "expect(…).{{matcher}}(…) is IO-backed and returns a promise — it must be awaited or returned, else the assertion never runs (D2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2005,7 +2005,7 @@ const d2wAwaitSyncMatcher = {
 	},
 	meta: {
 		docs: RULE_DOCS["d2w-await-sync-matcher"],
-		messages: { redundantAwait: "await on expect(…).{{matcher}}(…) is redundant — that matcher is synchronous; only IO-backed matchers (toMatchRows/toBeEmpty/toBeRunning) are awaited (CONVENTIONS D2)." },
+		messages: { redundantAwait: "await on expect(…).{{matcher}}(…) is redundant — that matcher is synchronous; only IO-backed matchers (toMatchRows/toBeEmpty/toBeRunning) are awaited (D2 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2082,7 +2082,7 @@ const d6wTransformTokenEquivalent = {
 	},
 	meta: {
 		docs: RULE_DOCS["d6w-transform-token-equivalent"],
-		messages: { tokenEquivalent: "This transform only rewrites output into known token literals — write the tokens in the expected/ fixture instead; transform is an escape hatch for uncovered noise (CONVENTIONS D6)." },
+		messages: { tokenEquivalent: "This transform only rewrites output into known token literals — write the tokens in the expected/ fixture instead; transform is an escape hatch for uncovered noise (D6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2116,7 +2116,7 @@ const d8wTextBypass = {
 	},
 	meta: {
 		docs: RULE_DOCS["d8w-text-bypass"],
-		messages: { textBypass: "expect(x.text).{{matcher}}(…) asserts on the raw stream — prefer the typed accessor subject (expect(x)) so the token grammar and fixture resolution apply (CONVENTIONS D8)." },
+		messages: { textBypass: "expect(x.text).{{matcher}}(…) asserts on the raw stream — prefer the typed accessor subject (expect(x)) so the token grammar and fixture resolution apply (D8 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2199,7 +2199,7 @@ const d9wSingleUseRef = {
 	},
 	meta: {
 		docs: RULE_DOCS["d9w-single-use-ref"],
-		messages: { singleUse: "Capture ref \"{{ref}}\" is used only once in this spec — a ref earns its name by asserting equality across occurrences; use a plain matcher instead (CONVENTIONS D9)." },
+		messages: { singleUse: "Capture ref \"{{ref}}\" is used only once in this spec — a ref earns its name by asserting equality across occurrences; use a plain matcher instead (D9 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2227,7 +2227,7 @@ const f1NoSubpathImport = {
 	},
 	meta: {
 		docs: RULE_DOCS["f1-no-subpath-import"],
-		messages: { subpath: "Import from \"@jterrazz/test\", not \"{{source}}\" — subpaths do not exist (CONVENTIONS F1; only the tool-facing @jterrazz/test/oxlint is exempt)." },
+		messages: { subpath: "Import from \"@jterrazz/test\", not \"{{source}}\" — subpaths do not exist (F1 — see docs/10-linting.md; only the tool-facing @jterrazz/test/oxlint is exempt)." },
 		type: "problem"
 	}
 };
@@ -2275,7 +2275,7 @@ const f2NoTestImportsInProd = {
 	},
 	meta: {
 		docs: RULE_DOCS["f2-no-test-imports-in-prod"],
-		messages: { testImport: "Production code must not import the test artefact \"{{source}}\" — test imports are only legal from specs/, *.test.ts, *.fixtures.ts or *.specification.ts (CONVENTIONS F2)." },
+		messages: { testImport: "Production code must not import the test artefact \"{{source}}\" — test imports are only legal from specs/, *.test.ts, *.fixtures.ts or *.specification.ts (F2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2339,7 +2339,7 @@ const f3SpecsPublicEntry = {
 	},
 	meta: {
 		docs: RULE_DOCS["f3-specs-public-entry"],
-		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (CONVENTIONS F3; only @jterrazz/test/oxlint, and src/integrations/** from specs/integrations/, are exempt)." },
+		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (F3 — see docs/10-linting.md; only @jterrazz/test/oxlint, and src/integrations/** from specs/integrations/, are exempt)." },
 		type: "problem"
 	}
 };
@@ -2365,7 +2365,7 @@ const f4NoTestToTestImport = {
 	},
 	meta: {
 		docs: RULE_DOCS["f4-no-test-to-test-import"],
-		messages: { testToTest: "A test file must not import another test file (\"{{source}}\") — share data via a *.fixtures.ts neighbour or a *.specification.ts runner (CONVENTIONS F4)." },
+		messages: { testToTest: "A test file must not import another test file (\"{{source}}\") — share data via a *.fixtures.ts neighbour or a *.specification.ts runner (F4 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2391,14 +2391,14 @@ const f5FixturesOnlyFromTests = {
 	},
 	meta: {
 		docs: RULE_DOCS["f5-fixtures-only-from-tests"],
-		messages: { fixturesImport: "A *.fixtures.ts module (\"{{source}}\") is only importable from *.test.ts files (CONVENTIONS F5)." },
+		messages: { fixturesImport: "A *.fixtures.ts module (\"{{source}}\") is only importable from *.test.ts files (F5 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/i1-layer-boundaries.ts
 /**
-* One folder = one external dependency (CONVENTIONS I1): the packages each
+* One folder = one external dependency (I1 — see docs/10-linting.md): the packages each
 * `src/integrations/<folder>/` may import.
 */
 const INTEGRATION_DEPS = {
@@ -2504,10 +2504,10 @@ const i1LayerBoundaries = {
 	meta: {
 		docs: RULE_DOCS["i1-layer-boundaries"],
 		messages: {
-			coreExternal: "core/ imports nothing external — \"{{source}}\" is not allowed (CONVENTIONS I1).",
-			crossLayer: "Layer \"{{layer}}\" must not import \"{{source}}\" — outside the sanctioned layer edges (CONVENTIONS I1).",
-			foreignDependency: "\"{{source}}\" is not this folder's own dependency — one integrations folder = one external dependency (CONVENTIONS I1).",
-			lintRuntime: "The lint layer imports nothing from the framework runtime — \"{{source}}\" is outside its pure-helper whitelist (CONVENTIONS I1)."
+			coreExternal: "core/ imports nothing external — \"{{source}}\" is not allowed (I1 — see docs/10-linting.md).",
+			crossLayer: "Layer \"{{layer}}\" must not import \"{{source}}\" — outside the sanctioned layer edges (I1 — see docs/10-linting.md).",
+			foreignDependency: "\"{{source}}\" is not this folder's own dependency — one integrations folder = one external dependency (I1 — see docs/10-linting.md).",
+			lintRuntime: "The lint layer imports nothing from the framework runtime — \"{{source}}\" is outside its pure-helper whitelist (I1 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2560,9 +2560,9 @@ const i2SiblingTestNaming = {
 	meta: {
 		docs: RULE_DOCS["i2-sibling-test-naming"],
 		messages: {
-			orphanTest: "A src/ module test must sit NEXT to the module it tests — no neighbour \"{{expected}}\" found (CONVENTIONS I2). A test needing more than its module is a specification: move it to specs/.",
-			rootTests: "A root-level tests/ directory is banned — module tests are siblings under src/, product specifications live in specs/ (CONVENTIONS I2).",
-			testsDir: "__tests__/ directories are banned under src/ — the test of <file>.ts is its neighbour <file>.test.ts (CONVENTIONS I2)."
+			orphanTest: "A src/ module test must sit NEXT to the module it tests — no neighbour \"{{expected}}\" found (I2 — see docs/10-linting.md). A test needing more than its module is a specification: move it to specs/.",
+			rootTests: "A root-level tests/ directory is banned — module tests are siblings under src/, product specifications live in specs/ (I2 — see docs/10-linting.md).",
+			testsDir: "__tests__/ directories are banned under src/ — the test of <file>.ts is its neighbour <file>.test.ts (I2 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2621,9 +2621,9 @@ const i4NoViMockInSrc = {
 	meta: {
 		docs: RULE_DOCS["i4-no-vi-mock-in-src"],
 		messages: {
-			assetImport: "A src/ module test must not import the data asset \"{{source}}\" — inline it as code or move the test to specs/ (CONVENTIONS I4).",
-			bannedDir: "`{{dir}}/` directories are banned under src/ — mocks and data are code: mockOf/mockOfDate inline, payloads in a *.fixtures.ts neighbour (CONVENTIONS I4).",
-			viMock: "`vi.mock` is banned under src/ — use mockOf/mockOfDate (CONVENTIONS I4)."
+			assetImport: "A src/ module test must not import the data asset \"{{source}}\" — inline it as code or move the test to specs/ (I4 — see docs/10-linting.md).",
+			bannedDir: "`{{dir}}/` directories are banned under src/ — mocks and data are code: mockOf/mockOfDate inline, payloads in a *.fixtures.ts neighbour (I4 — see docs/10-linting.md).",
+			viMock: "`vi.mock` is banned under src/ — use mockOf/mockOfDate (I4 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2667,7 +2667,7 @@ const j1NoOnlySkip = {
 	},
 	meta: {
 		docs: RULE_DOCS["j1-no-only-skip"],
-		messages: { forbidden: "Committed `{{runner}}.{{modifier}}` is not allowed (CONVENTIONS J1). Remove it before committing." },
+		messages: { forbidden: "Committed `{{runner}}.{{modifier}}` is not allowed (J1 — see docs/10-linting.md). Remove it before committing." },
 		type: "problem"
 	}
 };
@@ -2710,8 +2710,8 @@ const j2NoSleepInSpecs = {
 	meta: {
 		docs: RULE_DOCS["j2-no-sleep-in-specs"],
 		messages: {
-			sleep: "No arbitrary sleeps in specs — synchronise via `waitFor` or the framework (CONVENTIONS J2).",
-			timersImport: "No timer-based sleeps in specs — synchronise via `waitFor` or the framework (CONVENTIONS J2)."
+			sleep: "No arbitrary sleeps in specs — synchronise via `waitFor` or the framework (J2 — see docs/10-linting.md).",
+			timersImport: "No timer-based sleeps in specs — synchronise via `waitFor` or the framework (J2 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2751,7 +2751,7 @@ const j3NoExpectlessTest = {
 	},
 	meta: {
 		docs: RULE_DOCS["j3-no-expectless-test"],
-		messages: { noExpect: "Test has no `expect(…)` — a test must assert something (CONVENTIONS J3). Use `test.todo` for a pending test." },
+		messages: { noExpect: "Test has no `expect(…)` — a test must assert something (J3 — see docs/10-linting.md). Use `test.todo` for a pending test." },
 		type: "problem"
 	}
 };
@@ -2787,7 +2787,7 @@ const j4UniqueTestNames = {
 	},
 	meta: {
 		docs: RULE_DOCS["j4-unique-test-names"],
-		messages: { duplicate: "Duplicate test name \"{{name}}\" in this file — the test name is the sole description of behaviour, so it must be unique (CONVENTIONS J4)." },
+		messages: { duplicate: "Duplicate test name \"{{name}}\" in this file — the test name is the sole description of behaviour, so it must be unique (J4 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2883,7 +2883,7 @@ const plugin = {
 			},
 			meta: {
 				docs: RULE_DOCS["j5-lowercase-title"],
-				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (CONVENTIONS J5)." },
+				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
 				type: "problem"
 			}
 		}

package/dist/oxlint.js

@@ -653,7 +653,7 @@ const a1SpecificationFile = {
 	},
 	meta: {
 		docs: RULE_DOCS["a1-specification-file"],
-		messages: { outsideSpecification: "specification.{{member}}() must be called from a `*.specification.ts` file under specs/ (CONVENTIONS A1)." },
+		messages: { outsideSpecification: "specification.{{member}}() must be called from a `*.specification.ts` file under specs/ (A1 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -730,13 +730,13 @@ const a10DuplicateBinding = {
 	},
 	meta: {
 		docs: RULE_DOCS["a10-duplicate-binding"],
-		messages: { duplicate: "Service keys \"{{first}}\" and \"{{key}}\" both bind to compose service \"{{binding}}\" — one shadows the other; rename a key or set distinct composeService values (CONVENTIONS A10)." },
+		messages: { duplicate: "Service keys \"{{first}}\" and \"{{key}}\" both bind to compose service \"{{binding}}\" — one shadows the other; rename a key or set distinct composeService values (A10 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/a2-known-constructors.ts
-/** The three constructors, and only three (CONVENTIONS A2). */
+/** The three constructors, and only three (A2 — see docs/10-linting.md). */
 const KNOWN_CONSTRUCTORS = /* @__PURE__ */ new Set([
 	"api",
 	"cli",
@@ -762,7 +762,7 @@ const a2KnownConstructors = {
 	},
 	meta: {
 		docs: RULE_DOCS["a2-known-constructors"],
-		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs() and specification.cli() (CONVENTIONS A2)." },
+		messages: { unknownConstructor: "specification.{{member}} does not exist — the only constructors are specification.api(), specification.jobs() and specification.cli() (A2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -807,7 +807,7 @@ const a3NoDestructureAlias = {
 	},
 	meta: {
 		docs: RULE_DOCS["a3-no-destructure-alias"],
-		messages: { aliased: "Destructure the specification result with its canonical name: `{{key}}`, not `{{key}}: {{alias}}` (CONVENTIONS A3). Rename at the import site if a different local name is needed." },
+		messages: { aliased: "Destructure the specification result with its canonical name: `{{key}}`, not `{{key}}: {{alias}}` (A3 — see docs/10-linting.md). Rename at the import site if a different local name is needed." },
 		type: "problem"
 	}
 };
@@ -859,7 +859,7 @@ const a4CleanupAfterall = {
 	},
 	meta: {
 		docs: RULE_DOCS["a4-cleanup-afterall"],
-		messages: { unregistered: "`cleanup` is destructured but never passed to afterAll — add `afterAll(cleanup)` to the specification file (CONVENTIONS A4)." },
+		messages: { unregistered: "`cleanup` is destructured but never passed to afterAll — add `afterAll(cleanup)` to the specification file (A4 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -889,7 +889,7 @@ const a5ModeWithServer = {
 	},
 	meta: {
 		docs: RULE_DOCS["a5-mode-with-server"],
-		messages: { hardcodedMode: "`mode` must not be hardcoded when `server` is defined — the node/compose switch lives in vitest.config.ts via `env: { TEST_MODE: \"compose\" }` (CONVENTIONS A5)." },
+		messages: { hardcodedMode: "`mode` must not be hardcoded when `server` is defined — the node/compose switch lives in vitest.config.ts via `env: { TEST_MODE: \"compose\" }` (A5 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -930,7 +930,7 @@ const a6wRedundantComposeService = {
 	},
 	meta: {
 		docs: RULE_DOCS["a6w-redundant-compose-service"],
-		messages: { redundant: "composeService: \"{{name}}\" is redundant — the key \"{{key}}\" already binds to it (exact name or kebab-case derivation, CONVENTIONS A6)." },
+		messages: { redundant: "composeService: \"{{name}}\" is redundant — the key \"{{key}}\" already binds to it (exact name or kebab-case derivation, A6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -994,7 +994,7 @@ function readFileCached(path) {
 //#endregion
 //#region src/lint/rules/a9w-redundant-root.ts
 /**
-* The root the convention would derive (CONVENTIONS A9): walk up from the
+* The root the convention would derive (A9 — see docs/10-linting.md): walk up from the
 * specification file to the first directory containing
 * `docker/compose.test.yaml`, else the first containing `package.json`.
 */
@@ -1033,7 +1033,7 @@ const a9wRedundantRoot = {
 	},
 	meta: {
 		docs: RULE_DOCS["a9w-redundant-root"],
-		messages: { redundant: "root: \"{{root}}\" is redundant — walking up from the specification file already resolves to that directory (CONVENTIONS A9)." },
+		messages: { redundant: "root: \"{{root}}\" is redundant — walking up from the specification file already resolves to that directory (A9 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1097,7 +1097,7 @@ const b2KnownFixtureMarker = {
 	},
 	meta: {
 		docs: RULE_DOCS["b2-known-fixture-marker"],
-		messages: { unknownMarker: "Unknown fixture marker \"{{marker}}\" — known markers: {{known}}. A path without a marker is feature-local (CONVENTIONS B2)." },
+		messages: { unknownMarker: "Unknown fixture marker \"{{marker}}\" — known markers: {{known}}. A path without a marker is feature-local (B2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1162,8 +1162,8 @@ const b4GivenThen = {
 	meta: {
 		docs: RULE_DOCS["b4-given-then"],
 		messages: {
-			givenAfterThen: "The `// Given -` marker comes after `// Then -` — Given describes the setup and must precede Then (CONVENTIONS B4).",
-			missing: "Test is missing a `// {{marker}} -` comment (CONVENTIONS B4 — every test needs both `// Given -` and `// Then -`)."
+			givenAfterThen: "The `// Given -` marker comes after `// Then -` — Given describes the setup and must precede Then (B4 — see docs/10-linting.md).",
+			missing: "Test is missing a `// {{marker}} -` comment (B4 — see docs/10-linting.md — every test needs both `// Given -` and `// Then -`)."
 		},
 		type: "problem"
 	}
@@ -1204,7 +1204,7 @@ const b5AwaitUsing = {
 	meta: {
 		docs: RULE_DOCS["b5-await-using"],
 		defaultOptions: [{ runners: [] }],
-		messages: { requireAwaitUsing: "The result of docker-aware runner \"{{runner}}\" must be bound with `await using` so its containers are disposed (CONVENTIONS B5)." },
+		messages: { requireAwaitUsing: "The result of docker-aware runner \"{{runner}}\" must be bound with `await using` so its containers are disposed (B5 — see docs/10-linting.md)." },
 		schema: [{
 			additionalProperties: false,
 			properties: { runners: {
@@ -1247,7 +1247,7 @@ const b6wRedundantEnvUrl = {
 	},
 	meta: {
 		docs: RULE_DOCS["b6w-redundant-env-url"],
-		messages: { redundant: ".env({ {{key}}: ….connectionString }) is redundant — the framework already injects <KEY>_URL (and the DATABASE_URL/REDIS_URL aliases) for every service (CONVENTIONS B6)." },
+		messages: { redundant: ".env({ {{key}}: ….connectionString }) is redundant — the framework already injects <KEY>_URL (and the DATABASE_URL/REDIS_URL aliases) for every service (B6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1276,7 +1276,7 @@ const b8KebabTrigger = {
 	},
 	meta: {
 		docs: RULE_DOCS["b8-kebab-trigger"],
-		messages: { notKebab: "Job name \"{{name}}\" must be a stable kebab-case identifier (e.g. \"nightly-report\") — it is a contract between the app and its tests (CONVENTIONS B8)." },
+		messages: { notKebab: "Job name \"{{name}}\" must be a stable kebab-case identifier (e.g. \"nightly-report\") — it is a contract between the app and its tests (B8 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1331,7 +1331,7 @@ const b9wProductCommand = {
 	},
 	meta: {
 		docs: RULE_DOCS["b9w-product-command"],
-		messages: { thirdPartyBinary: "specification.cli() points at a third-party binary in node_modules/.bin — a spec should exercise your product command (cli.exec(\"check\"), …), not the tool underneath (CONVENTIONS B9). Suppress with a reason if the product genuinely is this binary." },
+		messages: { thirdPartyBinary: "specification.cli() points at a third-party binary in node_modules/.bin — a spec should exercise your product command (cli.exec(\"check\"), …), not the tool underneath (B9 — see docs/10-linting.md). Suppress with a reason if the product genuinely is this binary." },
 		type: "suggestion"
 	}
 };
@@ -1387,9 +1387,9 @@ const c1DomainStructure = {
 	meta: {
 		docs: RULE_DOCS["c1-domain-structure"],
 		messages: {
-			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (CONVENTIONS C1).",
-			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (CONVENTIONS C1).",
-			testTooDeep: "A `*.test.ts` must sit at facet/domain depth: `specs/<facet>/<domain>/<aspect>.test.ts` — no deeper nesting (CONVENTIONS C1)."
+			specNotAtFacetRoot: "A `*.specification.ts` must sit at the facet root: `specs/<facet>/<name>.specification.ts` (C1 — see docs/10-linting.md).",
+			testAtFacetRoot: "A `*.test.ts` must live in a domain folder: `specs/<facet>/<domain>/<aspect>.test.ts` — tests directly at the facet root are forbidden (C1 — see docs/10-linting.md).",
+			testTooDeep: "A `*.test.ts` must sit at facet/domain depth: `specs/<facet>/<domain>/<aspect>.test.ts` — no deeper nesting (C1 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -1419,13 +1419,13 @@ const c2HttpOnlyRequests = {
 	},
 	meta: {
 		docs: RULE_DOCS["c2-http-only-requests"],
-		messages: { notHttp: "requests/{{entry}} is not a .http file — requests/ contains only complete .http request files (CONVENTIONS C2)." },
+		messages: { notHttp: "requests/{{entry}} is not a .http file — requests/ contains only complete .http request files (C2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/c4-contract-shape.ts
-/** Providers a contract file may declare (CONVENTIONS C4). */
+/** Providers a contract file may declare (C4 — see docs/10-linting.md). */
 const PROVIDERS = /* @__PURE__ */ new Set([
 	"anthropic",
 	"http",
@@ -1491,12 +1491,12 @@ const c4ContractShape = {
 	meta: {
 		docs: RULE_DOCS["c4-contract-shape"],
 		messages: {
-			badName: "Contract file \"{{base}}\" must be named <name>.<provider>.ts with provider ∈ openai | anthropic | http (CONVENTIONS C4).",
-			foreignImport: "Contract imports \"{{source}}\" — a contract imports only from the public entry (@jterrazz/test) (CONVENTIONS C4).",
-			missingDefault: "Contract file has no `export default defineContract(...)` (CONVENTIONS C4).",
-			namedExport: "Contract files have no named exports — only `export default defineContract(...)` (CONVENTIONS C4).",
-			notDefineContract: "The default export of a contract file must be `defineContract(...)` syntactically (CONVENTIONS C4).",
-			subfolder: "Contract file \"{{base}}\" is nested — contracts/ is flat, no subfolders (CONVENTIONS C4)."
+			badName: "Contract file \"{{base}}\" must be named <name>.<provider>.ts with provider ∈ openai | anthropic | http (C4 — see docs/10-linting.md).",
+			foreignImport: "Contract imports \"{{source}}\" — a contract imports only from the public entry (@jterrazz/test) (C4 — see docs/10-linting.md).",
+			missingDefault: "Contract file has no `export default defineContract(...)` (C4 — see docs/10-linting.md).",
+			namedExport: "Contract files have no named exports — only `export default defineContract(...)` (C4 — see docs/10-linting.md).",
+			notDefineContract: "The default export of a contract file must be `defineContract(...)` syntactically (C4 — see docs/10-linting.md).",
+			subfolder: "Contract file \"{{base}}\" is nested — contracts/ is flat, no subfolders (C4 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -1547,7 +1547,7 @@ const c6ToMatchExtension = {
 	},
 	meta: {
 		docs: RULE_DOCS["c6-tomatch-extension"],
-		messages: { missingExtension: "toMatch(\"{{name}}\") is missing its extension — the extension is part of the fixture name (\"help.txt\", never \"help\"); only directory-tree snapshots (expected/<name>/) omit it (CONVENTIONS C6)." },
+		messages: { missingExtension: "toMatch(\"{{name}}\") is missing its extension — the extension is part of the fixture name (\"help.txt\", never \"help\"); only directory-tree snapshots (expected/<name>/) omit it (C6 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1575,7 +1575,7 @@ const c7SeedsSqlOnly = {
 	},
 	meta: {
 		docs: RULE_DOCS["c7-seeds-sql-only"],
-		messages: { notSql: "seeds/{{entry}} is not a .sql file — seeds/ carries database state only; file state goes through .fixture() (CONVENTIONS C7)." },
+		messages: { notSql: "seeds/{{entry}} is not a .sql file — seeds/ carries database state only; file state goes through .fixture() (C7 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -1664,7 +1664,7 @@ const c8ReferencedFixtureExists = {
 	},
 	meta: {
 		docs: RULE_DOCS["c8-referenced-fixture-exists"],
-		messages: { missing: "Referenced fixture \"{{path}}\" does not exist on disk under its conventional {{root}}/ root (CONVENTIONS C8). Create it or fix the reference." },
+		messages: { missing: "Referenced fixture \"{{path}}\" does not exist on disk under its conventional {{root}}/ root (C8 — see docs/10-linting.md). Create it or fix the reference." },
 		type: "problem"
 	}
 };
@@ -1733,7 +1733,7 @@ const d12wResponseBodyProbe = {
 	meta: {
 		docs: RULE_DOCS["d12w-response-body-probe"],
 		defaultOptions: [{ threshold: DEFAULT_THRESHOLD }],
-		messages: { bodyProbeCluster: "{{count}} body probes in one test — this wants a full golden: expect(result.response).toMatch('x.http') (CONVENTIONS D12)." },
+		messages: { bodyProbeCluster: "{{count}} body probes in one test — this wants a full golden: expect(result.response).toMatch('x.http') (D12 — see docs/10-linting.md)." },
 		schema: [{
 			additionalProperties: false,
 			properties: { threshold: {
@@ -1816,7 +1816,7 @@ const d13wUnfrozenNegativeFixture = {
 	},
 	meta: {
 		docs: RULE_DOCS["d13w-unfrozen-negative-fixture"],
-		messages: { unfrozenNegativeFixture: "This toMatch asserts a mismatch (wrapped in expect(…).toThrow/.rejects) — pass { frozen: true } so TEST_UPDATE=1 never overwrites the deliberately-wrong fixture (CONVENTIONS D13)." },
+		messages: { unfrozenNegativeFixture: "This toMatch asserts a mismatch (wrapped in expect(…).toThrow/.rejects) — pass { frozen: true } so TEST_UPDATE=1 never overwrites the deliberately-wrong fixture (D13 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1892,7 +1892,7 @@ const d15wStatusOnlyProbe = {
 	},
 	meta: {
 		docs: RULE_DOCS["d15w-status-only-probe"],
-		messages: { statusOnlyProbe: "The test's only assertion(s) are status probes — pin the full response: expect(result.response).toMatch('case.http') (CONVENTIONS D11)." },
+		messages: { statusOnlyProbe: "The test's only assertion(s) are status probes — pin the full response: expect(result.response).toMatch('case.http') (D11 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -1947,7 +1947,7 @@ const d2AwaitIoMatcher = {
 	},
 	meta: {
 		docs: RULE_DOCS["d2-await-io-matcher"],
-		messages: { mustAwait: "expect(…).{{matcher}}(…) is IO-backed and returns a promise — it must be awaited or returned, else the assertion never runs (CONVENTIONS D2)." },
+		messages: { mustAwait: "expect(…).{{matcher}}(…) is IO-backed and returns a promise — it must be awaited or returned, else the assertion never runs (D2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2001,7 +2001,7 @@ const d2wAwaitSyncMatcher = {
 	},
 	meta: {
 		docs: RULE_DOCS["d2w-await-sync-matcher"],
-		messages: { redundantAwait: "await on expect(…).{{matcher}}(…) is redundant — that matcher is synchronous; only IO-backed matchers (toMatchRows/toBeEmpty/toBeRunning) are awaited (CONVENTIONS D2)." },
+		messages: { redundantAwait: "await on expect(…).{{matcher}}(…) is redundant — that matcher is synchronous; only IO-backed matchers (toMatchRows/toBeEmpty/toBeRunning) are awaited (D2 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2078,7 +2078,7 @@ const d6wTransformTokenEquivalent = {
 	},
 	meta: {
 		docs: RULE_DOCS["d6w-transform-token-equivalent"],
-		messages: { tokenEquivalent: "This transform only rewrites output into known token literals — write the tokens in the expected/ fixture instead; transform is an escape hatch for uncovered noise (CONVENTIONS D6)." },
+		messages: { tokenEquivalent: "This transform only rewrites output into known token literals — write the tokens in the expected/ fixture instead; transform is an escape hatch for uncovered noise (D6 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2112,7 +2112,7 @@ const d8wTextBypass = {
 	},
 	meta: {
 		docs: RULE_DOCS["d8w-text-bypass"],
-		messages: { textBypass: "expect(x.text).{{matcher}}(…) asserts on the raw stream — prefer the typed accessor subject (expect(x)) so the token grammar and fixture resolution apply (CONVENTIONS D8)." },
+		messages: { textBypass: "expect(x.text).{{matcher}}(…) asserts on the raw stream — prefer the typed accessor subject (expect(x)) so the token grammar and fixture resolution apply (D8 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2195,7 +2195,7 @@ const d9wSingleUseRef = {
 	},
 	meta: {
 		docs: RULE_DOCS["d9w-single-use-ref"],
-		messages: { singleUse: "Capture ref \"{{ref}}\" is used only once in this spec — a ref earns its name by asserting equality across occurrences; use a plain matcher instead (CONVENTIONS D9)." },
+		messages: { singleUse: "Capture ref \"{{ref}}\" is used only once in this spec — a ref earns its name by asserting equality across occurrences; use a plain matcher instead (D9 — see docs/10-linting.md)." },
 		type: "suggestion"
 	}
 };
@@ -2223,7 +2223,7 @@ const f1NoSubpathImport = {
 	},
 	meta: {
 		docs: RULE_DOCS["f1-no-subpath-import"],
-		messages: { subpath: "Import from \"@jterrazz/test\", not \"{{source}}\" — subpaths do not exist (CONVENTIONS F1; only the tool-facing @jterrazz/test/oxlint is exempt)." },
+		messages: { subpath: "Import from \"@jterrazz/test\", not \"{{source}}\" — subpaths do not exist (F1 — see docs/10-linting.md; only the tool-facing @jterrazz/test/oxlint is exempt)." },
 		type: "problem"
 	}
 };
@@ -2271,7 +2271,7 @@ const f2NoTestImportsInProd = {
 	},
 	meta: {
 		docs: RULE_DOCS["f2-no-test-imports-in-prod"],
-		messages: { testImport: "Production code must not import the test artefact \"{{source}}\" — test imports are only legal from specs/, *.test.ts, *.fixtures.ts or *.specification.ts (CONVENTIONS F2)." },
+		messages: { testImport: "Production code must not import the test artefact \"{{source}}\" — test imports are only legal from specs/, *.test.ts, *.fixtures.ts or *.specification.ts (F2 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2335,7 +2335,7 @@ const f3SpecsPublicEntry = {
 	},
 	meta: {
 		docs: RULE_DOCS["f3-specs-public-entry"],
-		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (CONVENTIONS F3; only @jterrazz/test/oxlint, and src/integrations/** from specs/integrations/, are exempt)." },
+		messages: { deepImport: "specs/ must not deep-import framework internals — reach the framework via its public entry (@jterrazz/test, or src/index.js in this repo), not \"{{source}}\" (F3 — see docs/10-linting.md; only @jterrazz/test/oxlint, and src/integrations/** from specs/integrations/, are exempt)." },
 		type: "problem"
 	}
 };
@@ -2361,7 +2361,7 @@ const f4NoTestToTestImport = {
 	},
 	meta: {
 		docs: RULE_DOCS["f4-no-test-to-test-import"],
-		messages: { testToTest: "A test file must not import another test file (\"{{source}}\") — share data via a *.fixtures.ts neighbour or a *.specification.ts runner (CONVENTIONS F4)." },
+		messages: { testToTest: "A test file must not import another test file (\"{{source}}\") — share data via a *.fixtures.ts neighbour or a *.specification.ts runner (F4 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2387,14 +2387,14 @@ const f5FixturesOnlyFromTests = {
 	},
 	meta: {
 		docs: RULE_DOCS["f5-fixtures-only-from-tests"],
-		messages: { fixturesImport: "A *.fixtures.ts module (\"{{source}}\") is only importable from *.test.ts files (CONVENTIONS F5)." },
+		messages: { fixturesImport: "A *.fixtures.ts module (\"{{source}}\") is only importable from *.test.ts files (F5 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
 //#endregion
 //#region src/lint/rules/i1-layer-boundaries.ts
 /**
-* One folder = one external dependency (CONVENTIONS I1): the packages each
+* One folder = one external dependency (I1 — see docs/10-linting.md): the packages each
 * `src/integrations/<folder>/` may import.
 */
 const INTEGRATION_DEPS = {
@@ -2500,10 +2500,10 @@ const i1LayerBoundaries = {
 	meta: {
 		docs: RULE_DOCS["i1-layer-boundaries"],
 		messages: {
-			coreExternal: "core/ imports nothing external — \"{{source}}\" is not allowed (CONVENTIONS I1).",
-			crossLayer: "Layer \"{{layer}}\" must not import \"{{source}}\" — outside the sanctioned layer edges (CONVENTIONS I1).",
-			foreignDependency: "\"{{source}}\" is not this folder's own dependency — one integrations folder = one external dependency (CONVENTIONS I1).",
-			lintRuntime: "The lint layer imports nothing from the framework runtime — \"{{source}}\" is outside its pure-helper whitelist (CONVENTIONS I1)."
+			coreExternal: "core/ imports nothing external — \"{{source}}\" is not allowed (I1 — see docs/10-linting.md).",
+			crossLayer: "Layer \"{{layer}}\" must not import \"{{source}}\" — outside the sanctioned layer edges (I1 — see docs/10-linting.md).",
+			foreignDependency: "\"{{source}}\" is not this folder's own dependency — one integrations folder = one external dependency (I1 — see docs/10-linting.md).",
+			lintRuntime: "The lint layer imports nothing from the framework runtime — \"{{source}}\" is outside its pure-helper whitelist (I1 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2556,9 +2556,9 @@ const i2SiblingTestNaming = {
 	meta: {
 		docs: RULE_DOCS["i2-sibling-test-naming"],
 		messages: {
-			orphanTest: "A src/ module test must sit NEXT to the module it tests — no neighbour \"{{expected}}\" found (CONVENTIONS I2). A test needing more than its module is a specification: move it to specs/.",
-			rootTests: "A root-level tests/ directory is banned — module tests are siblings under src/, product specifications live in specs/ (CONVENTIONS I2).",
-			testsDir: "__tests__/ directories are banned under src/ — the test of <file>.ts is its neighbour <file>.test.ts (CONVENTIONS I2)."
+			orphanTest: "A src/ module test must sit NEXT to the module it tests — no neighbour \"{{expected}}\" found (I2 — see docs/10-linting.md). A test needing more than its module is a specification: move it to specs/.",
+			rootTests: "A root-level tests/ directory is banned — module tests are siblings under src/, product specifications live in specs/ (I2 — see docs/10-linting.md).",
+			testsDir: "__tests__/ directories are banned under src/ — the test of <file>.ts is its neighbour <file>.test.ts (I2 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2617,9 +2617,9 @@ const i4NoViMockInSrc = {
 	meta: {
 		docs: RULE_DOCS["i4-no-vi-mock-in-src"],
 		messages: {
-			assetImport: "A src/ module test must not import the data asset \"{{source}}\" — inline it as code or move the test to specs/ (CONVENTIONS I4).",
-			bannedDir: "`{{dir}}/` directories are banned under src/ — mocks and data are code: mockOf/mockOfDate inline, payloads in a *.fixtures.ts neighbour (CONVENTIONS I4).",
-			viMock: "`vi.mock` is banned under src/ — use mockOf/mockOfDate (CONVENTIONS I4)."
+			assetImport: "A src/ module test must not import the data asset \"{{source}}\" — inline it as code or move the test to specs/ (I4 — see docs/10-linting.md).",
+			bannedDir: "`{{dir}}/` directories are banned under src/ — mocks and data are code: mockOf/mockOfDate inline, payloads in a *.fixtures.ts neighbour (I4 — see docs/10-linting.md).",
+			viMock: "`vi.mock` is banned under src/ — use mockOf/mockOfDate (I4 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2663,7 +2663,7 @@ const j1NoOnlySkip = {
 	},
 	meta: {
 		docs: RULE_DOCS["j1-no-only-skip"],
-		messages: { forbidden: "Committed `{{runner}}.{{modifier}}` is not allowed (CONVENTIONS J1). Remove it before committing." },
+		messages: { forbidden: "Committed `{{runner}}.{{modifier}}` is not allowed (J1 — see docs/10-linting.md). Remove it before committing." },
 		type: "problem"
 	}
 };
@@ -2706,8 +2706,8 @@ const j2NoSleepInSpecs = {
 	meta: {
 		docs: RULE_DOCS["j2-no-sleep-in-specs"],
 		messages: {
-			sleep: "No arbitrary sleeps in specs — synchronise via `waitFor` or the framework (CONVENTIONS J2).",
-			timersImport: "No timer-based sleeps in specs — synchronise via `waitFor` or the framework (CONVENTIONS J2)."
+			sleep: "No arbitrary sleeps in specs — synchronise via `waitFor` or the framework (J2 — see docs/10-linting.md).",
+			timersImport: "No timer-based sleeps in specs — synchronise via `waitFor` or the framework (J2 — see docs/10-linting.md)."
 		},
 		type: "problem"
 	}
@@ -2747,7 +2747,7 @@ const j3NoExpectlessTest = {
 	},
 	meta: {
 		docs: RULE_DOCS["j3-no-expectless-test"],
-		messages: { noExpect: "Test has no `expect(…)` — a test must assert something (CONVENTIONS J3). Use `test.todo` for a pending test." },
+		messages: { noExpect: "Test has no `expect(…)` — a test must assert something (J3 — see docs/10-linting.md). Use `test.todo` for a pending test." },
 		type: "problem"
 	}
 };
@@ -2783,7 +2783,7 @@ const j4UniqueTestNames = {
 	},
 	meta: {
 		docs: RULE_DOCS["j4-unique-test-names"],
-		messages: { duplicate: "Duplicate test name \"{{name}}\" in this file — the test name is the sole description of behaviour, so it must be unique (CONVENTIONS J4)." },
+		messages: { duplicate: "Duplicate test name \"{{name}}\" in this file — the test name is the sole description of behaviour, so it must be unique (J4 — see docs/10-linting.md)." },
 		type: "problem"
 	}
 };
@@ -2879,7 +2879,7 @@ const plugin = {
 			},
 			meta: {
 				docs: RULE_DOCS["j5-lowercase-title"],
-				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (CONVENTIONS J5)." },
+				messages: { uppercase: "A {{runner}}() title must start lowercase — the test name is a prose fragment, not a sentence (J5 — see docs/10-linting.md)." },
 				type: "problem"
 			}
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jterrazz/test",
-    "version": "9.0.0",
+    "version": "9.1.0",
     "description": "Declarative testing framework for HTTP APIs, CLIs, and background jobs — one entry point, real infrastructure, golden-file assertions, plus an oxlint convention plugin.",
     "keywords": [
         "api-testing",
@@ -46,7 +46,7 @@
     },
     "scripts": {
         "build": "tsdown --config tsdown.config.ts",
-        "docs": "typescript docs && npm run build && node dist/catalog.js",
+        "docs": "npm run build && node dist/catalog.js && typescript docs",
         "lint": "typescript check && node dist/checker.js specs",
         "lint:fix": "typescript fix",
         "test": "vitest --run"
@@ -63,7 +63,7 @@
     },
     "devDependencies": {
         "@hono/node-server": "^2.0.8",
-        "@jterrazz/typescript": "^6.1.0",
+        "@jterrazz/typescript": "^7.0.0",
         "@types/better-sqlite3": "^7.6.13",
         "@types/node": "^26.1.1",
         "@types/pg": "^8.20.0",