Problem

Workspace configuration keys are documented as narrative sections in docs/configuration/top-level.md and docs/configuration/examples.md. That shape has three costs:

• No linkable per-parameter target. Issues, PRs, CHANGES entries, and warnings can't point at "the synchronize reference" — only at a whole page.
• No canonical inventory. The set of valid keys lives implicitly across loader.expand(), loader.trickle(), validation.validate_schema(), and the builder. Discovering "what can I put in a workspace file, at which level, with what default?" requires reading source.
• Drift risk. Prose and code are updated separately; the parity work (tmuxinator/teamocil feature parity #1016, Workspace(feat[runtime]): Add pane title and synchronization keys #1047–Workspace(feat[importers]): Add tmuxinator and teamocil parity fallbacks #1049) is adding many new keys (pane titles, synchronize, shell_command_after, clear, lifecycle hooks), which multiplies both the value of a reference and the surface for drift.

Proposal

1. Per-parameter reference pages

One page (or one anchored section) per config parameter, each carrying:

• Name, level (session / window / pane), type, default
• Version introduced
• 1–3 prose paragraphs of behavior
• At least one copy-paste workspace example
• Related keys / interactions (e.g. synchronize: after vs shell_command_after ordering)

Plus an index table grouped by level, so the full vocabulary is scannable on one screen.

2. Bonus: make them autodocumentable

The drift problem disappears if docs and validation share one source of truth. Sketch:

1. Declarative schema registry in code — a dataclass (or table of records) describing every key: name, level, type, default, since-version, help text, example. loader/validation consume it instead of hardcoding key knowledge; validate_schema() becomes data-driven.
2. Sphinx directive that renders the registry — prior art is exactly this pattern:
   • myst-parser documents MdParserConfig by introspecting its dataclass fields and field.metadata["help"] via a custom MystConfigDirective, invoked in docs as a {myst-config} fenced directive (myst_parser/_docs.py). tmuxp can do the same with a {tmuxp-config} directive filterable by level.
   • Sphinx core documents its own options with the confval directive, which yields stable cross-referenceable targets ({confval} role) — adopting confval-style object types gives every parameter a permalink usable from CHANGES and warnings.
3. The generic directive could live in tmuxp's docs conf.py initially; if it proves reusable, graduating it to the shared docs platform (gp-sphinx) is a natural follow-up.

Phasing

1. Inventory + anchors — enumerate every key from loader/validation/builder, restructure existing prose under per-key anchors, add the index table. Docs-only, no code changes.
2. Schema registry — introduce the declarative registry; port validate_schema() and loader key-handling onto it; doctest the registry.
3. Directive — render per-key reference docs from the registry; delete the now-duplicated hand-written tables; CI ensures a key without registry metadata fails the build.

Acceptance criteria

• Every workspace config key has a linkable reference target with level, type, default, and a working example
• The key inventory in docs is generated from (or validated against) the same structure the loader/validator uses
• Adding a new config key without docs metadata fails loudly (build or test)

Refs #1016 (the parity effort expanding the config surface this would document).