> ## Documentation Index
> Fetch the complete documentation index at: https://sponson.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR 0015: Adapters and secret sources describe themselves

> Architecture decision record 0015. Status: Accepted

Date: 2026-10-10

## Status

Accepted

## Context

The docs list every built-in adapter (with the variable that holds its credential and the one that overrides its API
base URL) and every secret scheme (with the reference form and how it is resolved). Those lists are generated by
`pnpm docs:gen`, but the facts they show were kept in two hand-written maps in `scripts/gen-docs.ts`, while the same
variable names were written again, as string literals, in each adapter's code.

A first-contributor walkthrough showed the cost: a new adapter meant editing the generator script (the adapter
scaffold had to patch it by regular expression), and nothing tied the documented variable name to the one the code
actually read. The two could disagree silently.

## Decision

* `ResourceAdapter` has an optional `about: { credentialEnv, baseUrlEnv? }`. Each adapter declares it once, as a
  constant its own code uses (`requireEnv(actx.env, ABOUT.credentialEnv, …)`), and the generated docs read it from
  the registry.
* `SecretSource` has optional `form` and `resolvedBy`, written next to the source's `resolve`.
* Both are optional in the type so third-party plugins keep compiling; `pnpm docs:gen` fails for a *built-in*
  adapter or source that leaves them out.
* A source's `resolve` throws a reason only; the engine prefixes the reference once. The message never contains the
  value.

## Consequences

* Adding an adapter or a secret source touches only its own file, its registration, its tests and its docs section;
  `scripts/gen-docs.ts` no longer changes, and the scaffold no longer edits it.
* The documented variable name is the one the code reads, by construction.
* The public adapter contract grew by one optional field and one type (`AdapterAbout`). Plugins may adopt it to be
  listed by future tooling; nothing requires it of them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.