Versioning

Additive and breaking changes, the protocol id, the path policy and the release-notes process.

agent-identity-v1 carries its major version in the discovery document's protocol field. This page explains how the protocol changes and how the docs site tracks it. The normative policy is spec section 13.

Current version

Protocol id: agent-identity-v1.
Specification release: v1.2.0, released 2026-10-24.
Package: @agentregistrar/discovery 1.2.0.
The v1.2.0 release adds Contracts G/H/I, the optional rp_attestation, the trust model and policy matrix, RP-signed receipts, authenticated Contract F and D.2, and the separate conformance/verification validator result. It removes no required field.
v1.0.0 and v1.1.0 implementations remain conformant. Absence of rp_attestation means unverified, never invalid.

The full release history is in the changelog.

Additive changes

Additive identity fields and clarifications are allowed within v1. They do not change the protocol value or the discovery path.

Consumers must ignore unknown fields.
Producers should namespace non-capability vendor metadata under extensions.<reverse-dns>.
An additive change must pass the scope-boundaries review checklist.
Additive changes are recorded in the specification changelog and the release notes.
The schema, the JSON Schema and the validator are updated together so they cannot drift.

Vendor catalogs, provisioning endpoints, resource metadata and API-usage documentation are not additive protocol fields at any version. They belong in the post-signup guide.

Breaking changes

A breaking change must use a new protocol value and a new discovery path, for example agent-signup-v2.json.

The v1 path must not silently change semantics.
A future version should be dual-published during a migration window.
The public specification URL should be versioned. The optional spec field lets agents and humans find the exact document.
The registry lists implementations by the protocol value their discovery document advertises.

Path policy

The docs site follows the protocol path:

/agent-identity/v1/ is the canonical path for this major version.
A breaking change would add /agent-identity/v2/ rather than rewriting the v1 pages.
There is no whole-site versioning. Only the protocol family is path-versioned.
The generated pages under /agent-identity/v1/ are pinned to one spec tag and are regenerated by pnpm sync:spec.

Deprecation and release notes

v1.2.0 does not deprecate v1.0.0 or v1.1.0. It is an additive revision.
The specification's changelog records every additive v1 change with its date.
Release notes record the release evidence, the change process and any non-blocking follow-ups.
v1 has no formal sunset date. A future breaking change would be dual-published during a migration window; v1 would stay published for that window.
A deprecation notice, if one is ever needed, belongs in the release notes and at the top of the affected version's landing page. The docs site does not invent a deprecation schedule ahead of the specification.

Updating the rendered docs

The rendered pages are generated from a pinned tag, never hand-edited. The version-bump runbook is in the docs repository's AGENT.md:

Confirm the spec tag and release notes exist; read the diff.
Update spec.lock.json tag and let the sync resolve the commit and hashes.
Run pnpm sync:spec; review the generated diff for normative changes.
Update the hand-authored protocol pages if fields, errors or claims changed.
Update the changelog and any current-version strings.
Run the build, check, lint and theme gates; verify the schema $id.
Commit the lock, the generated pages and the hand-authored changes together.

Known limits

There is no formal deprecation timetable for v1.
Additive changes do not change the wire protocol id, so an agent cannot tell minor versions apart from protocol alone. The optional spec field is the version pointer.
The docs site renders one pinned tag. A newer tag is not live until the sync and review land.