# ADR 0001 — The support catalog is rendered, never restated

- **Status**: accepted
- **Scope**: `putnami.dev` (`sites/putnami.dev`)

## Context

A support status is a public promise: it tells a reader whether they can depend
on a package today. The workspace root holds one reviewed authority for those
promises, `putnami.support.json`, and `protocols/support` requires a generated
view to point back at it instead of becoming a second inventory. A hand-written
status on the site drifts silently: publishing `preview` for something the
catalog calls `stable` understates a commitment, and the reverse invents one.

## Decision

The reviewed catalog is the site's only source of support statuses.

`/docs/support` is generated. `src/plugins/support-catalog.plugin.ts` reads
`putnami.support.json` and renders every classified package and protocol, with
the independent `default` and `parity` claims where present. The page is never
committed and is a pure function of the catalog bytes.

The reader is strict. Only the three reviewed statuses parse. A token like
`beta` or `evolving`, a `protocolVersion` other than the integer `1`, a repeated
`(kind, id)`, or an `experimental` subject that claims to be default-on fails
the build.

`src/lib/tools.ts` names each documented surface's catalog subject
(`supportSubject`) and never its value. Statuses are resolved server-side in
`src/app/docs/loader.ts`, which keeps `tools.ts` client-safe for the islands. A
surface the catalog does not classify carries `supportSubject: null` and renders
no badge. The managed platform and the two `sites/` projects are such surfaces:
the support protocol classifies things a user depends on, not services Putnami
operates.

The page is written before static paths are enumerated, from the callback that
materializes content bundles, so cold and warm builds publish the same page set
and route digest.

## Rejected alternatives

- **Keep a hand-written list and test it against the catalog.** Every
  classification would still need two edits.
- **Import the catalog from the client-safe module.** Reaches outside the
  project root and ships the whole catalog to the browser.
- **Commit the generated page.** It would drift the moment a classification
  changed without a rebuild.
- **Also write the page into the source `public/docs` mirror.** The
  static-files and public-surface plugins would both declare the route and fail
  with `http_routes.duplicate_route`.
- **Invent a `site` support kind.** A wire change to a closed vocabulary that
  turns a promise about artifacts into one about hosted services.
- **Publish what could be read from a malformed catalog.** A missing row reads
  as "not supported".

## Consequences

- A catalog edit changes a published page with no site edit, so a careless
  edit is immediately public.
- The catalog is part of this project's generate cache key, so a classification
  change invalidates the site build.
- A malformed catalog breaks the site build as well as the support protocol's
  gate.
- A surface without a badge gets one by being classified, never by a site edit.
- The status vocabulary here is closed at three values; a fourth needs a
  support-protocol version bump first.