Capabilities manifest

The capabilities manifest is a structured, machine-readable description of what the running exd telemetry install can do: which commands exist, what parameters they accept, what output shapes they produce, and which T-codes they may emit.

It is the agent-discoverable counterpart to this reference. An agent encountering an unfamiliar exd install reads the capabilities manifest first and plans from there, instead of relying on documentation that may have been written against a different version.

This is the telemetry analogue of an OpenAPI document for an HTTP API.

Endpoint

exd telemetry capabilities --format json

The command MUST succeed without network access and without read access to any evaluation data. The capabilities manifest describes the install itself; it is independent of any data the install can read.

--format human renders a human-readable table. --format json is the normative form and is what agents consume.

CLI use cases live in reference/cli/exd/telemetry/capabilities.

Top-level shape

{
  "spec_version": 1,
  "exd_version": "0.5.0",
  "schema_version": 1,
  "engines": [
    { "name": "duckdb", "version": "1.0.0", "default": true },
    { "name": "snowflake", "version": null, "default": false }
  ],
  "commands": [ ... ],
  "queries": [ ... ],
  "diagnostics": [ ... ],
  "schemas": { ... }
}

Field	Required	Type	Description
`spec_version`	yes	integer	The telemetry spec version this install conforms to. Currently `1`.
`exd_version`	yes	string	The version of `exd-client` providing this install.
`schema_version`	yes	integer	The `EvaluationRecord` schema version this install produces and consumes.
`engines`	yes	array	Supported query engines. The first entry with `default: true` is the engine used when `--engine` is omitted.
`commands`	yes	array	Every `exd telemetry` subcommand.
`queries`	yes	array	Every user-defined query discovered in the manifest's `queries/` directory. Empty in Phase 1 — see § `queries` entry.
`diagnostics`	yes	array	Every `T-code` this install knows about.
`schemas`	yes	object	JSON Schemas referenced by `commands[].output_schema_ref` and `diagnostics[].data_schema_ref`.

`commands` entry

{
  "name": "telemetry.summary",
  "alias": "summary",
  "description": "Per-flag eval counts and variant distribution.",
  "stability": "stable",
  "parameters": [
    { "name": "flag", "type": "key", "required": false },
    { "name": "since", "type": "duration", "required": true },
    { "name": "compare_to", "type": "duration", "required": false }
  ],
  "output_schema_ref": "#/schemas/summary-result",
  "diagnostics": ["T007", "T008", "T009", "T010"],
  "engines": ["duckdb", "snowflake", "bigquery", "databricks", "redshift"]
}

Field	Required	Type	Description
`name`	yes	string	Stable identifier. Mirrors the named-query form (`telemetry.<name>` for built-ins).
`alias`	no	string	Top-level CLI alias if one exists (e.g. `summary` for `telemetry.summary`).
`description`	yes	string	One-line description.
`stability`	yes	enum	`stable`, `experimental`, or `deprecated`.
`parameters`	yes	array	Parameter declarations (see below).
`output_schema_ref`	yes	string	JSON-Pointer reference into `schemas`.
`diagnostics`	no	array of `T-code`	Diagnostics this command may emit.
`engines`	yes	array	Engines that support this command.

Parameter declaration

Field	Required	Type	Description
`name`	yes	string	Parameter name.
`type`	yes	string	One of the parameter types listed in query-catalog § `[parameters.<name>]`.
`required`	yes	bool	Whether the parameter is required.
`default`	no	matching `type`	Default value if not required.
`description`	no	string	Free-form.

`queries` entry

Deferred indefinitely. With the user-defined query catalog deferred, queries is always an empty array in Phase 1 outputs. The shape below describes what entries would carry if user-defined queries were reintroduced. The field stays in the top-level envelope so consumers don't need to special-case its presence.

User-defined queries discovered in the manifest's queries/ directory would be reflected here when exd telemetry capabilities is run from inside a manifest repo. Each entry has the same shape as a commands entry, plus:

Additional field	Required	Type	Description
`version`	yes	integer	The query's declared `version`.
`source_path`	yes	string	Path to the query file relative to the manifest root.

`diagnostics` entry

{
  "code": "T001",
  "severity": "warning",
  "summary": "Sample-ratio mismatch detected.",
  "data_schema_ref": "#/schemas/T001-data",
  "stability": "stable"
}

Field	Required	Type	Description
`code`	yes	string	The `T-code`.
`severity`	yes	enum	`info`, `warning`, or `error`.
`summary`	yes	string	One-line description.
`data_schema_ref`	yes	string	JSON-Pointer reference into `schemas` for the diagnostic's `data` payload.
`stability`	yes	enum	`stable`, `experimental`, or `deprecated`.

`schemas` block

The schemas field is a JSON object whose values are JSON Schema documents. Both commands[].output_schema_ref and diagnostics[].data_schema_ref resolve into this object using JSON-Pointer syntax (#/schemas/<name>).

The reference Rust implementation embeds these schemas at build time so that exd telemetry capabilities can produce them with no I/O. Schemas use JSON Schema Draft 2020-12.

Stability and tolerance

The capabilities manifest is itself versioned by the spec_version field. Compatibility expectations:

Forward compatibility for agents. Agents consuming the capabilities manifest MUST tolerate unknown fields, unknown commands, unknown diagnostic codes, and unknown engines by ignoring them, not by failing.
Backward compatibility for installs. An exd-client of spec version N MUST be able to produce a capabilities manifest accepted by an agent reading at spec version N or N-1.
Discovery first. Agents SHOULD query exd telemetry capabilities once per session and reason from the result, rather than encoding command shapes at the agent level.

Generating the capabilities manifest

The reference implementation lives in crates/exd-client/src/telemetry/capabilities.rs. It is generated by introspecting:

The compiled set of built-in telemetry.* queries.
The T-code registry.
The set of registered query engines (gated on Cargo features).
(Deferred indefinitely) User-defined queries discovered by walking the manifest repo's queries/ directory. In Phase 1 the manifest-repo walk does not run and queries is emitted as an empty array.

Generation is deterministic. Agents that cache the capabilities manifest can detect drift by comparing the exd_version field across runs.

Endpoint​

Top-level shape​

commands entry​

Parameter declaration​

queries entry​

diagnostics entry​

schemas block​

Stability and tolerance​

Generating the capabilities manifest​

See also​