Identity-only discovery

Why agent-signup.json is a parameter document, which fields it may carry, and why vendor capability stays out.

agent-signup.json answers one question: can this agent, acting for this human, accept these terms and create an account here? It is a parameter document for that decision. It is not a capability catalog, a product description or an API index.

The normative field rules are in the specification. This page explains the design choice and the boundary.

What belongs in discovery

Group	Examples	Why it is identity
Protocol and service identity	`protocol`, `audience`, `provider_name`, `provider_url`, `contact`	Tells the agent which contract and which service it is talking to.
Trust anchors	`issuer_allowlist`	Names the brokers whose assertions this service accepts.
Delegation requirements	`required_scopes`	States what the agent must be allowed to do before signup.
Terms binding	`terms.version`, `terms.url`, `terms.sha256`, `terms.text`	Pins the exact agreement the human is bound to.
One endpoint	`endpoints.agent_signup`	The only place the assertion may be sent.
Optional provider identity	`rp_attestation`	The broker-issued provider verification credential binding origin, audience, identity, level and keys. Absence means unverified, not invalid.

All required and optional fields, with types and spec sections, are in Discovery fields.

What does not belong in discovery

Anything that answers "what do you sell?" or "how do I call your API?" is vendor scope:

catalogs, SKUs, pricing tiers, quotas and product specs;
provisioning, resource, lifecycle or credential endpoints;
legacy email-signup and OTP endpoints;
broker receipt callbacks;
API or SDK usage metadata.

The prohibition applies at any nesting depth, including under extensions. Moving instance_catalog under extensions.dev.example does not make it conformant; the validator fails it. This is the one-way door described in Scope boundaries: the protocol owns identity and liability, the vendor guide owns capability.

The reason is not minimalism for its own sake. A catalog in a document that any agent fetches before any relationship exists is unversioned marketing data, and it invites the broker to validate commercial claims it cannot verify. Keeping discovery identity-only makes the conformance question precise and keeps liability with the party that wrote the terms.

The `extensions` rule

extensions is for non-capability metadata, keyed by a reverse-DNS namespace:

{
  "extensions": {
    "dev.example": {
      "status_page": "https://status.example.com"
    }
  }
}

Use it for things like a status page or a support URL. Do not use it to smuggle a catalog, a SKU list, a provisioning URL or a price. The validator warns on non-reverse-DNS keys and fails on capability fields at any depth.

Transport and caching

Serve GET /.well-known/agent-signup.json from the canonical HTTPS origin.
Return 200 with application/json when you support agent-identity-v1.
Return 404 or 410 when you do not. Do not use 401 or 403 to signal non-support.
No authentication, no redirect, no HTML.
Cache-Control: public, max-age=60 (maximum 300) and Access-Control-Allow-Origin: * are recommended; the validator reports them as warnings when absent.
Keep the body under 1 MiB. The complete terms text counts toward that.

http://localhost and http://127.0.0.1 are the development exception. A live provider uses HTTPS.

Non-goals

Discovery does not prove the service is trustworthy, secure or available.
Discovery itself is not signed in v1.2. The optional rp_attestation is a signed statement about the provider, not a signature over the document. Trust in the document comes from TLS, the issuer allowlist, and the signed assertion; the credential adds a separately verifiable provider identity.
Discovery does not advertise vendor capabilities, and it is not a place to negotiate them.
Discovery does not replace the terms page a human reads; terms.url points at the human-readable copy.

Verify

Run the validator against your document and confirm that no forbidden field appears at any depth:

pnpm --silent validate:discovery https://example.com/.well-known/agent-signup.json --json

The command and output are documented in the conformance validator.

Brokered signup handshake: what the agent sends and what you must verify.
Liability and ToS: the acceptance record and what to retain.
Publish discovery: the implementation step.