@opengroundplan/core 0.1.1

package/templates/bases/turborepo-monorepo/files/packages/eslint-config/index.js

@@ -0,0 +1,21 @@
+import js from '@eslint/js';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+// Every workspace re-exports this, so a rule change lands everywhere at once.
+export default tseslint.config(
+  { ignores: ['dist/**', 'node_modules/**', '**/*.tsbuildinfo'] },
+  js.configs.recommended,
+  tseslint.configs.recommended,
+  {
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: { ...globals.node },
+    },
+    rules: {
+      '@typescript-eslint/consistent-type-imports': 'error',
+      'no-console': 'off',
+    },
+  },
+);

package/templates/bases/turborepo-monorepo/files/packages/eslint-config/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@{{ solutionName | kebab }}/eslint-config",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js"
+  ],
+  "dependencies": {
+    "@eslint/js": "^10.0.1",
+    "globals": "^17.7.0",
+    "typescript-eslint": "^8.64.0"
+  },
+  "peerDependencies": {
+    "eslint": "^10.0.0"
+  }
+}

package/templates/bases/turborepo-monorepo/files/packages/shared/eslint.config.js

@@ -0,0 +1,3 @@
+import config from '@{{ solutionName | kebab }}/eslint-config';
+
+export default config;

package/templates/bases/turborepo-monorepo/files/packages/shared/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@{{ solutionName | kebab }}/shared",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "check-types": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "devDependencies": {
+    "@{{ solutionName | kebab }}/eslint-config": "workspace:*",
+    "@{{ solutionName | kebab }}/tsconfig": "workspace:*",
+    "@types/node": "^{{ nodeVersion }}.0.0",
+    "eslint": "^10.7.0",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/bases/turborepo-monorepo/files/packages/shared/src/health.ts

@@ -0,0 +1,23 @@
+export const serviceName = '{{ solutionName | kebab }}';
+
+export type HealthStatus = 'ok' | 'degraded';
+
+export interface HealthReport {
+  readonly service: string;
+  readonly status: HealthStatus;
+  readonly uptimeSeconds: number;
+  readonly checkedAt: string;
+}
+
+/** Shared so every workspace that exposes /health answers in the same shape. */
+export function buildHealthReport(
+  uptimeSeconds: number,
+  status: HealthStatus = 'ok',
+): HealthReport {
+  return {
+    service: serviceName,
+    status,
+    uptimeSeconds: Math.round(uptimeSeconds),
+    checkedAt: new Date().toISOString(),
+  };
+}

package/templates/bases/turborepo-monorepo/files/packages/shared/src/index.ts

@@ -0,0 +1,2 @@
+export { serviceName, buildHealthReport } from './health.js';
+export type { HealthReport, HealthStatus } from './health.js';

package/templates/bases/turborepo-monorepo/files/packages/shared/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "@{{ solutionName | kebab }}/tsconfig/node.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "declaration": true,
+    "declarationMap": true
+  },
+  "include": ["src"]
+}

package/templates/bases/turborepo-monorepo/files/packages/tsconfig/base.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "es2023",
+    "lib": ["es2023"],
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "sourceMap": true
+  }
+}

package/templates/bases/turborepo-monorepo/files/packages/tsconfig/node.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "./base.json",
+  "compilerOptions": {
+    "types": ["node"]
+  }
+}

package/templates/bases/turborepo-monorepo/files/packages/tsconfig/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@{{ solutionName | kebab }}/tsconfig",
+  "version": "0.1.0",
+  "private": true,
+  "files": [
+    "base.json",
+    "node.json"
+  ]
+}

package/templates/bases/turborepo-monorepo/files/pnpm-workspace.yaml

@@ -0,0 +1,7 @@
+packages:
+  - apps/*
+  - packages/*
+
+# pnpm 11 fails the install unless every dependency build script is explicitly allowed.
+allowBuilds:
+  esbuild: true

package/templates/bases/turborepo-monorepo/files/turbo.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://turborepo.com/schema.json",
+  "ui": "tui",
+  "globalEnv": ["NODE_ENV"],
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**"]
+    },
+    "check-types": {
+      "dependsOn": ["^build"]
+    },
+    "lint": {
+      "dependsOn": ["^build"]
+    },
+    "dev": {
+      "dependsOn": ["^build"],
+      "cache": false,
+      "persistent": true
+    }
+  }
+}

package/templates/layers/api-versioning/blueprint.yaml

@@ -0,0 +1,264 @@
+id: api-versioning
+kind: layer
+name: API versioning and contract stability
+description: >-
+  Version negotiation and contract stability for APIs with shipped clients that
+  cannot be force-upgraded. Resolves the requested version from the URL path, a
+  header, a query parameter, or an Accept media-type parameter; refuses unknown
+  versions with an RFC 9457 problem document; emits RFC 9745 Deprecation and
+  RFC 8594 Sunset headers for versions on the way out; and enforces a minimum
+  deprecation-notice window at startup so no version can be retired faster than
+  policy allows. Ships a direction-aware contract differ so an additive change
+  and a breaking change are distinguishable in CI rather than in production.
+
+tags:
+  - api
+  - versioning
+  - deprecation
+  - sunset
+  - backward-compatibility
+  - contract-testing
+  - http
+
+# Nothing. The layer is stdlib-only in every stack and takes the request as a plain
+# value rather than reaching into a framework, so it composes with any base that
+# serves HTTP — and with one that does not yet, since the policy and the contract
+# differ are useful on their own. `requires` must name blueprint ids, not capability
+# names, so "needs an HTTP surface" cannot be expressed here even if it were true.
+requires: []
+
+# A conflict must name a blueprint that already exists or the entire catalog fails to
+# load (loader.assertReferencesResolve), and no competing versioning or deprecation
+# layer exists. Conflicts are symmetric at resolve time, so a future `api-versioning-*`
+# alternative declares the pair from its own side.
+conflicts: []
+
+# Capability names other blueprints key off instead of naming this one. A gateway,
+# SDK-generation, or CI layer wants "there is a version policy", not "api-versioning
+# is installed".
+provides:
+  - api-versioning
+  - version-negotiation
+  - version-policy
+  - deprecation-headers
+  - sunset-headers
+  - contract-snapshots
+  - contract-compatibility
+  - api-version-config
+
+# Versioning is a transport-edge concern, orthogonal to how the source tree is
+# organized — the policy module drops into every overlay unchanged.
+supportsArchitectures: []
+
+variables:
+  - name: apiVersionEnvPrefix
+    prompt: Environment-variable prefix for versioning settings
+    type: string
+    default: API_VERSION
+    required: true
+
+  - name: apiVersionStrategy
+    prompt: Where the client states which version it wants
+    type: select
+    choices:
+      - { value: path, label: 'URL path segment — /api/v2/orders (most visible, most cacheable)' }
+      - { value: header, label: 'Request header — X-API-Version: v2' }
+      - { value: query, label: 'Query parameter — ?api-version=v2' }
+      - { value: accept, label: 'Accept media-type parameter — application/json; version=v2' }
+    default: path
+    required: true
+
+  # Ordered oldest to newest. Order is declaration order, not a parsed scheme, so
+  # "v1,v2" and "2025-01-01,2025-06-01" both work without a version grammar.
+  - name: apiVersionSupported
+    prompt: Comma-separated supported versions, oldest first
+    type: string
+    default: v1
+    required: true
+
+  # A client that states no version must keep getting what it got on the day it
+  # shipped, so this defaults to the OLDEST supported version, never the newest.
+  - name: apiVersionDefault
+    prompt: Version served when the client states none (keep this the oldest supported version)
+    type: string
+    default: v1
+    required: true
+
+  - name: apiVersionHeaderName
+    prompt: Header carrying the version (also echoed on every response)
+    type: string
+    default: X-API-Version
+    required: true
+
+  - name: apiVersionQueryParam
+    prompt: Query parameter carrying the version
+    type: string
+    default: api-version
+    required: true
+
+  - name: apiVersionMediaType
+    prompt: Base media type for the Accept strategy
+    type: string
+    default: application/json
+    required: true
+
+  - name: apiVersionPathPrefix
+    prompt: Path prefix before the version segment (empty for /v2/... at the root)
+    type: string
+    default: /api
+    required: false
+
+  # Refusing to retire a version faster than this is the entire point of the layer,
+  # so a deprecation that breaks the window fails at startup rather than in the field.
+  - name: apiVersionMinSunsetDays
+    prompt: Minimum days between announcing a deprecation and its sunset date
+    type: number
+    default: 180
+    required: true
+
+  - name: apiVersionPolicyUrl
+    prompt: URL of the published deprecation policy (blank omits the Link header)
+    type: string
+    default: ''
+    required: false
+
+  - name: apiVersionContractDir
+    prompt: Directory holding committed contract snapshots
+    type: string
+    default: contracts
+    required: true
+
+  # A browser SPA is a version *client*, not a version server, and a library base
+  # is neither. One question keeps a single layer id honest for all three.
+  - name: apiVersionTarget
+    prompt: What does this project do with API versions?
+    type: select
+    choices:
+      - { value: server, label: 'Serves a versioned API (also gets the client helper)' }
+      - { value: client, label: 'Only calls a versioned API — browser or SDK' }
+      - { value: none, label: 'Neither — policy and contract differ only' }
+    default: server
+    required: true
+    when: "stack == 'typescript' || stack == 'node'"
+
+  - name: apiVersionTestRunner
+    prompt: Test runner for the versioning suite
+    type: select
+    choices:
+      - { value: node, label: 'node:test (no dependency)' }
+      - { value: vitest, label: Vitest }
+    default: node
+    required: false
+    when: "stack == 'typescript' || stack == 'node'"
+
+  - name: dotnetTargetFramework
+    prompt: Target framework for the versioning project
+    type: string
+    default: net10.0
+    required: false
+    when: "stack == 'dotnet'"
+
+files:
+  # ── stack-agnostic ──────────────────────────────────────────────────────────
+  # A polyglot monorepo has no single edge to negotiate at; it composes this layer
+  # per service instead, so it gets neither code nor docs.
+  - from: files/docs/api-versioning.md
+    to: .
+    when: "stack != 'polyglot'"
+
+  # The committed snapshot directory has to exist before the first `--update` run,
+  # and its name follows the setting so code and disk cannot drift apart.
+  - from: files/__apiVersionContractDir__/README.md
+    to: .
+    when: "stack != 'polyglot'"
+
+  # .NET binds the ApiVersioning configuration section instead of a dotenv file.
+  - from: files/.env.apiversion.example
+    to: .
+    when: "stack != 'polyglot' && stack != 'dotnet'"
+
+  # ── typescript / node ───────────────────────────────────────────────────────
+  # One implementation for both stacks: ESM with `.js` relative specifiers and
+  # `import type`, which satisfies Hono's nodenext resolution and Nest's commonjs
+  # build alike. A single `*` never descends, so the subdirectories below are not
+  # double-claimed.
+  - from: files/src/apiversion/*.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget == 'server'"
+
+  # node:http is split out so a Workers/edge build never sees a node: import.
+  - from: files/src/apiversion/node/*.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget == 'server'"
+
+  # Pure functions over plain objects — no fs, no process, so the same module is
+  # importable from a test, a CI script, or a browser bundle.
+  - from: files/src/apiversion/contract/*.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget != 'none'"
+
+  # Reading and writing snapshot files needs node:fs, so it is not part of the
+  # browser-safe contract core above.
+  - from: files/src/apiversion/contract/node/*.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget == 'server'"
+
+  # The pinning fetch wrapper takes its config as an argument rather than from
+  # process.env, so it works in a browser bundle and in a server-side SDK call.
+  - from: files/src/apiversion/client/*.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget != 'none'"
+
+  # `.test.ts` is discovered by `node --test`, `.spec.ts` by Vitest. Emitting exactly
+  # one keeps the base's existing test command green either way.
+  - from: files/src/apiversion/tests/apiversion.test.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget == 'server' && apiVersionTestRunner == 'node'"
+  - from: files/src/apiversion/tests/apiversion.spec.ts
+    to: .
+    when: "(stack == 'typescript' || stack == 'node') && apiVersionTarget == 'server' && apiVersionTestRunner == 'vitest'"
+
+  # ── python ──────────────────────────────────────────────────────────────────
+  - from: files/src/__solutionName.snake__/apiversion/*.py
+    to: .
+    when: "stack == 'python'"
+  - from: files/tests/test_api_versioning.py
+    to: .
+    when: "stack == 'python'"
+
+  # ── go ──────────────────────────────────────────────────────────────────────
+  # Standalone package on the standard library only, so it never needs to know the
+  # base's module path.
+  - from: files/internal/apiversion/*.go
+    to: .
+    when: "stack == 'go'"
+
+  # ── dotnet ──────────────────────────────────────────────────────────────────
+  # Self-contained class library on the ASP.NET Core shared framework: no
+  # PackageReference, so it stays compatible with central package management.
+  - from: files/src/__solutionName.dot__.ApiVersioning/*
+    to: .
+    when: "stack == 'dotnet'"
+
+  # Code that imports a package the manifest never installs does not build (ADR 0005).
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # The solution is completed declaratively rather than by `dotnet sln add`, which runs
+  # after the first build and is skippable — a solution missing projects that exist on
+  # disk builds green while covering less than the repo contains (ADR 0005, spec 003).
+  - from: files/__solutionName.dot__.slnx
+    to: .
+    onConflict: merge
+    when: "stack == 'dotnet'"
+
+postApply:
+  # Nothing to install anywhere: negotiation, header formatting, JSON and date math
+  # are stdlib or shared-framework in every stack covered here.
+  # Unpinned so uv resolves the current stable rather than a version frozen into a template.
+  - run: uv add --dev pytest
+    when: "stack == 'python'"
+    optional: true
+  # The csproj declares no PackageReference; this only joins the solution.

package/templates/layers/api-versioning/files/.env.apiversion.example

@@ -0,0 +1,53 @@
+# API versioning settings. Copy the keys you need into .env — the defaults in code already
+# produce a working policy for a single-version API.
+
+# Turning this off skips negotiation entirely and serves DEFAULT to everyone. It does not
+# skip validation: a malformed policy still fails at startup instead of hiding the bug.
+{{ apiVersionEnvPrefix }}_ENABLED=true
+
+# path   = /api/v2/orders          (visible, cacheable, survives proxies that strip headers)
+# header = X-API-Version: v2
+# query  = ?api-version=v2
+# accept = Accept: application/json; version=v2
+{{ apiVersionEnvPrefix }}_STRATEGY={{ apiVersionStrategy }}
+
+# Every version this deployment can serve, oldest first. Order here IS the ordering — no
+# version grammar is parsed, so "v1,v2" and "2025-01-01,2025-06-01" both work.
+# Removing a version from this list is the actual retirement; the sunset date only announces it.
+{{ apiVersionEnvPrefix }}_SUPPORTED={{ apiVersionSupported }}
+
+# Served to clients that state no version. Keep this the OLDEST supported version: a client
+# shipped two years ago sends nothing, and it must not silently move to new behaviour.
+{{ apiVersionEnvPrefix }}_DEFAULT={{ apiVersionDefault }}
+
+# true  = an unknown version is refused with 400 and an RFC 9457 problem document
+# false = an unknown version falls back to DEFAULT (only sane behind a gateway that already validated)
+{{ apiVersionEnvPrefix }}_STRICT=true
+
+{{ apiVersionEnvPrefix }}_HEADER_NAME={{ apiVersionHeaderName }}
+{{ apiVersionEnvPrefix }}_QUERY_PARAM={{ apiVersionQueryParam }}
+{{ apiVersionEnvPrefix }}_MEDIA_TYPE={{ apiVersionMediaType }}
+
+# Path segments before the version segment. Empty means the version is the first segment.
+{{ apiVersionEnvPrefix }}_PATH_PREFIX={{ apiVersionPathPrefix }}
+
+# Versions on the way out, as version:announced:sunset with ISO-8601 dates.
+# Example: v1:2026-01-15:2026-08-01
+# Both dates are required, and (sunset - announced) must be at least MIN_SUNSET_DAYS or the
+# process refuses to start. That check is the whole reason this layer exists.
+{{ apiVersionEnvPrefix }}_DEPRECATED=
+
+# Minimum notice window. Raise it for partner APIs and embedded clients; never lower it to
+# make a shipping date work.
+{{ apiVersionEnvPrefix }}_MIN_SUNSET_DAYS={{ apiVersionMinSunsetDays }}
+
+# Published deprecation policy. When set it is sent as Link rel="deprecation" and
+# rel="sunset" so a client can discover the migration guide from the response alone.
+{{ apiVersionEnvPrefix }}_POLICY_URL={{ apiVersionPolicyUrl }}
+
+# Echo the resolved version on every response. Leave on: it is how a client proves which
+# contract it is actually talking to, and how support answers "which version did you get".
+{{ apiVersionEnvPrefix }}_EMIT_RESPONSE_HEADER=true
+
+# Where committed contract snapshots live, relative to the repository root.
+{{ apiVersionEnvPrefix }}_CONTRACT_DIR={{ apiVersionContractDir }}

package/templates/layers/api-versioning/files/__apiVersionContractDir__/README.md

@@ -0,0 +1,48 @@
+# Contract snapshots
+
+One JSON file per API version, committed to the repository. Each file records the *shape*
+of every payload that version promises — field names, types, and which fields are always
+present.
+
+These files are the record of what shipped clients were told. They are evidence, not
+configuration: nothing reads them at runtime.
+
+## Layout
+
+```
+{{ apiVersionContractDir }}/
+  {{ apiVersionDefault }}.json      one snapshot per entry in {{ apiVersionEnvPrefix }}_SUPPORTED
+```
+
+A snapshot looks like this:
+
+```json
+{
+  "version": "{{ apiVersionDefault }}",
+  "operations": {
+    "GET /orders/{id}": {
+      "response": { "kind": "object", "fields": { "id": { "required": true, "shape": { "kind": "string" } } } }
+    }
+  }
+}
+```
+
+## Workflow
+
+1. Write a test that builds a real payload for each operation and describes it.
+2. Run the suite. A first run writes the snapshot; later runs diff against it.
+3. The differ classifies every change as `breaking`, `additive`, or `neutral`, and the
+   test fails only on `breaking`. Additive changes update the snapshot in the same commit
+   that introduces them.
+
+Direction matters and the differ knows it. On a **response**, removing a field or making a
+previously guaranteed field optional breaks clients; adding a field does not. On a
+**request**, the reverse holds: a new required field breaks clients, a new optional one
+does not.
+
+## Retiring a version
+
+A snapshot is deleted only when its version leaves `{{ apiVersionEnvPrefix }}_SUPPORTED`,
+and that only happens after the sunset date announced in
+`{{ apiVersionEnvPrefix }}_DEPRECATED` has passed. Deleting a snapshot early throws away the
+only record of what a client in the field still expects.

package/templates/layers/api-versioning/files/__solutionName.dot__.slnx

@@ -0,0 +1,5 @@
+<Solution>
+  <Folder Name="/src/">
+    <Project Path="src/{{ solutionName | dot }}.ApiVersioning/{{ solutionName | dot }}.ApiVersioning.csproj" />
+  </Folder>
+</Solution>

package/templates/layers/api-versioning/files/docs/api-versioning.md

@@ -0,0 +1,100 @@
+# API versioning and contract stability
+
+The clients you cannot upgrade decide what you are allowed to change. This layer makes
+that constraint mechanical instead of cultural: the version a caller gets is negotiated
+explicitly, versions are retired on a published clock, and a breaking change to a shipped
+contract fails the build.
+
+## The rules this layer enforces
+
+1. **A client that states no version keeps what it had.** `{{ apiVersionEnvPrefix }}_DEFAULT`
+   is the *oldest* supported version, not the newest. Anything else silently migrates a
+   two-year-old mobile build on the day you deploy.
+2. **An unknown version is refused, not guessed.** Strict mode answers 400 with an
+   RFC 9457 problem document naming the versions that do exist.
+3. **A version cannot be retired faster than policy allows.** Every deprecation carries an
+   announcement date and a sunset date, and the process refuses to start if the gap is under
+   `{{ apiVersionEnvPrefix }}_MIN_SUNSET_DAYS` ({{ apiVersionMinSunsetDays }} days here).
+4. **Deprecation is discoverable from the response.** RFC 9745 `Deprecation` and RFC 8594
+   `Sunset` headers go out on every response served by a deprecated version, so a client
+   learns it is on borrowed time without reading a changelog.
+5. **A breaking contract change fails CI.** Committed snapshots in
+   `{{ apiVersionContractDir }}/` record what each version promised; the differ separates
+   additive changes from breaking ones.
+
+## Negotiation
+
+The strategy is `{{ apiVersionStrategy }}` by default and is set by
+`{{ apiVersionEnvPrefix }}_STRATEGY`.
+
+| Strategy | Client sends | Notes |
+|---|---|---|
+| `path` | `{{ apiVersionPathPrefix }}/v2/orders` | Most visible, cache-key-safe, survives header-stripping proxies |
+| `header` | `{{ apiVersionHeaderName }}: v2` | Keeps URLs stable; needs `Vary` handling in caches |
+| `query` | `?{{ apiVersionQueryParam }}=v2` | Easy to test by hand; leaks into logs and bookmarks |
+| `accept` | `Accept: {{ apiVersionMediaType }}; version=v2` | Most correct by HTTP semantics, least used by real clients |
+
+Resolution is a pure function of the request. It returns the version, the source it came
+from, and what the client originally asked for — so a fallback to the default is visible in
+logs rather than indistinguishable from an explicit request.
+
+## Versions are opaque, ordering is declaration order
+
+`{{ apiVersionEnvPrefix }}_SUPPORTED` is a comma-separated list, oldest first. No version
+grammar is parsed, so `v1,v2,v3` and `2025-01-01,2025-06-01` both work and compare
+correctly. The last entry is "latest"; there is no separate setting for it, because two
+settings that must agree eventually disagree.
+
+Removing a version from `SUPPORTED` is the retirement. The sunset date only announces it.
+
+## Deprecation
+
+```
+{{ apiVersionEnvPrefix }}_DEPRECATED=v1:2026-01-15:2026-08-01
+```
+
+`version:announced:sunset`. Both dates are required. Responses on `v1` then carry:
+
+```
+Deprecation: @1768435200
+Sunset: Sat, 01 Aug 2026 00:00:00 GMT
+Link: <https://example.test/api/deprecations>; rel="deprecation", <https://example.test/api/deprecations>; rel="sunset"
+```
+
+The `Link` header is emitted only when `{{ apiVersionEnvPrefix }}_POLICY_URL` is set.
+
+Past the sunset date the version keeps serving — the layer reports the condition, it never
+silently starts rejecting traffic. Removing the entry from `SUPPORTED` is a deliberate act
+by an operator, not a side effect of a clock rolling over.
+
+## Contract snapshots
+
+Describe a payload, compare it to what is committed, classify every difference:
+
+- **breaking** — a response field disappeared, a guaranteed response field became optional,
+  a type changed, or a request gained a required field.
+- **additive** — a response gained a field, or a request gained an optional one.
+- **neutral** — anything that cannot affect a client, such as a description change.
+
+Direction is part of the comparison because the same edit is safe in one direction and
+fatal in the other. A new field is free to add to a response and impossible to add as a
+required request field without breaking every client already in the field.
+
+Snapshots live in `{{ apiVersionContractDir }}/`, one per version, and are committed. The
+test suite fails on `breaking` and prints the exact path of every offending field.
+
+## Adding a version
+
+1. Append it to `{{ apiVersionEnvPrefix }}_SUPPORTED`. Do **not** touch `_DEFAULT`.
+2. Copy the previous snapshot to `{{ apiVersionContractDir }}/<new>.json` and edit it to
+   describe the new shape. Breaking changes are allowed here — that is what a new version
+   is for.
+3. When the old version is ready to retire, add it to `{{ apiVersionEnvPrefix }}_DEPRECATED`
+   with a sunset at least {{ apiVersionMinSunsetDays }} days out.
+4. After the sunset date, remove it from `SUPPORTED`. Keep its snapshot until then.
+
+## Configuration
+
+Every value above is read from the environment with one typed default in the settings
+module, and nothing else in the codebase may hardcode a version, a header name, or a date.
+See `.env.apiversion.example` for the full key list.