* fix(#2615): document the effortSurface axis in the host-integration matrix
#2481 added `effortSurface` as the ninth negotiated `hostIntegration` axis and
wrote documentation-sourced values into 18 descriptors, but never touched
`docs/reference/host-integration-capability-matrix.md`. The matrix that ADR-1239
designates the cited source of truth had zero occurrences of the axis: no entry in
the axes legend, and no row in any of the per-runtime tables. `src/host-integration.cts`
states "every value is documented or explicitly 'undocumented'" — for this axis
that was false for every runtime.
Adds the legend entry (the `argv` / `none` / `undocumented` vocabulary, plus why
there is deliberately no config-file member) and an `effortSurface` row to all 19
per-runtime tables. Every citation is carried over from #2481's own commit message,
where the values were sourced:
- claude argv -- `claude --help` documents `--effort <level>`
- opencode argv -- `opencode run --help` documents `--variant`
- codex argv -- `model_reasoning_effort` is a config.toml key, not a dedicated
flag, so the generic `-c key=value` override is the only argv
route (still argv)
- 15 hosts undocumented -- their docs state no reasoning setting
kimi-code is the nineteenth section (added by #2603 after #2481) and is the one
runtime with no declared value. Its row and a Documentation-gaps entry record why
rather than inventing one: Kimi Code documents `/effort` (alias `/thinking`), but
only as an INTERACTIVE slash command — `-m, --model` is the only model-adjacent
argv. Neither vocabulary member is accurate (`none` would deny a mechanism the host
has, `argv` would claim one it does not expose), so closing that gap needs a
vocabulary decision, which is a negotiation change and not a documentation one. The
absent value already degrades closed exactly as the sentinel does.
The regression test derives its runtime list from the registry rather than
hardcoding it, so a runtime added later fails until its matrix row exists — the
ratchet whose absence let #2481 add an axis with nothing catching the missing docs.
Closes#2615
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QT3ibz5qJuDuGqpTGRYVGf
* docs(#2615): honest citations for the undocumented rows; fix the four stale 8-axis lists
Two findings from the orthogonal review of the first commit.
1. The 15 `undocumented` rows shared byte-identical text — "searched the runtime's
official docs (see Sources consulted above)" — which is weaker than this file's
own convention ("no authoritative doc — searched: <url>") and, worse, implies a
per-host targeted search that did not happen: each section's Sources-consulted
list was gathered for OTHER axes and contains no CLI-reference or
reasoning-effort source. The rows now say plainly what the finding is — an
ABSENCE established by #2481's cross-host survey — and cite that survey rather
than implying a URL was checked per host.
2. Four normative docs still described "the eight negotiated axes" and omitted
effortSurface entirely. The worst of them is
docs/how-to/add-or-update-a-host-integration.md — the maintainer's own guide for
onboarding a host, whose Step 2 axis table would have a maintainer reproduce
exactly the gap #2615 exists to close. Also fixed:
docs/reference/host-integration-interface.md (which calls itself the normative
reference and had no effortSurface row at all),
docs/how-to/author-a-host-plugin.md, docs/registries/README.md ("**exactly** the
eight … axes keys"), and CONTEXT.md's matching EoS-registry sentence.
Deliberately NOT changed, because they are historical records rather than current
contract: docs/whats-new-1.7.0.md and docs/FEATURES.md's 1.7.0 entry (effortSurface
shipped in 1.8.0 via #2481 — rewriting them would falsify the release history),
ADR-1239's pre-amendment body (already superseded by its own
"Amendment (2026-07-21): effortSurface axis (#2481)"), and ADR-1016's "original
eight axes", which refers to a different axis set entirely.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QT3ibz5qJuDuGqpTGRYVGf
* chore(#2615): backfill changeset PR number (#2698)
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
The submission process told an admin to create a `Registry` Discussions
category and never stated its format. Both were wrong in a way a correct
reading of the docs could not catch.
Name: the category is `EoS Registry`, and it carries threads for both
registries — `discussion` is a required field on Capability entries as well as
EoS entries. A reader following the old text would create a second, duplicate
category.
Format: `discussion` being required means the thread must exist before the
entry's PR, opened by the entry's author — an outside contributor holding
neither `maintain` nor `admin`. GitHub's Announcement format restricts starting
discussions to those two levels, so an admin could pick it, block every external
submission at the first step, and see nothing wrong. Records open-ended as the
required format, and why Announcement and Question/Answer do not work.
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Instantiates the second discoverability catalog from issue #2182 on top of the
shared registry foundation shipped in PR #2188: an empty eos.json source and the
generated eos-registry.md (EoS entries declare the six Host-Integration interface
points, eight negotiated axes, and protocol version per ADR-1239). The validation,
generation, and rendering machinery + README schema + glossary term already landed
and are tested in PR #2188; this PR adds the EoS registry data + catalog page.
Closes#2182
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Implements the three pure functions in registry-schema.cjs (isValidGsdRange,
validateEntries, renderMarkdown) that were stubbed in the previous commit, turning
the red suite green: strict per-type schema validation (capability + eos), a
self-contained engines.gsd range validator (no semver dep), and deterministic
Markdown generation with shields.io release badges + per-entry Discussion links.
Regenerates docs/registries/capability-registry.md and adds the Added changeset.
Also hardens the isValidGsdRange fast-check property (letters-only major) so it
cannot intermittently generate a valid prerelease range and flake.
Closes#2182
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds the discoverability-registry surface for issue #2182: JSON-sourced
capability/eos catalogs, a pure schema/vocab module (registry-schema.cjs)
with the ADR-857 loop points + ADR-1239 axes, thin validate/gen CLIs,
the registry-entry PR template, README spec, and CONTEXT.md glossary terms.
The three pure functions (isValidGsdRange/validateEntries/renderMarkdown)
are stubbed here so the comprehensive test suite fails first (red), per the
feature-implementation red-first directive; the next commit implements them.
Refs #2182
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
