docs(registry): registering-an-agent — four crawl paths + AAO-membership value story#3543
Merged
Merged
Conversation
…_from, /operator auth-aware note Refs #3538. Three docs-IA cleanups for the Registry API. Source-side changes only — OpenAPI YAML regen lands in a separate commit so reviewers can see the intentional changes without skimming past 500 lines of mechanical diff. ## Tag rename: "Lookups & Authorization" -> "Authorization Lookups" The & in the tag name forced Mintlify to slugify the URL as lookups-%26-authorization, making /operator-lookup and the other 7 endpoints under that tag effectively unsearchable. 8 sites in registry-api.ts. ## Source / member / discovered_from descriptions server/src/schemas/registry.ts gains .openapi({ description }) on three fields that previously rendered as bare attributes: - source — explains 'registered' (AAO-attested, opt-in) vs 'discovered' (crawled from a publisher's adagents.json, no opt-in) and that they are different trust levels. - member — explains it is null for 'discovered' even when the publisher_domain is owned by a member (Problem 6 in #3538). - discovered_from — explains it is mutually exclusive with member. ## /api/registry/operator auth-aware description Endpoint description now spells out that the response shape changes by caller: anonymous gets 'public' only, AAO API-tier callers see 'members_only', profile owners see 'private'. This is the primary mechanism by which AAO membership unlocks deeper registry visibility — previously documented nowhere except the source.
Mechanical regen via npm run build:openapi after the source-side changes in
the previous commit. Captures:
- "Authorization Lookups" tag (8 sites) replacing the slug-breaking
"Lookups & Authorization".
- New .openapi({ description }) annotations on source, member, and
discovered_from in the registry response schema.
- /api/registry/operator auth-aware response-shape note.
Also picks up pre-existing drift from earlier PRs that didn't run
build:openapi: VerifiedBadge schema, declared_specialisms, check_interval_hours,
and verified-badge fields on agent responses. Pure mechanical catch-up; no
behavior change here that wasn't already in the source tree.
Split from the source-side commit so reviewers can scan the YAML diff as
hygiene, not feature work.
4 tasks
…hip value story Refs #3538. Closes the docs gap for non-members who have no first-class self-registration path today. Documents what does and does not work. ## Page contents - Two trust levels: `registered` (canonical, AAO-attested, opt-in) vs `discovered` (crawled from someone's adagents.json, no opt-in by the agent itself). - Four entry points the registry uses, with `source` and trust signals: 1. Self-registration via member profile — `registered` 2. Listed in a member publisher's adagents.json — `discovered` 3. Triggered crawl (POST /api/registry/crawl-request, POST /api/properties/check) — `discovered` 4. Sales agent's list_authorized_properties surfaces a publisher domain — `discovered` - Practical options for non-members (paths 2/3/4). - Membership benefits table: visibility (`public` / `members_only` / `private`), Verified badge, storyboard testing, compliance reporting, the auth-aware /api/registry/operator endpoint. - How to verify how your own agent appears (curl + JS examples). ## Nav Added `docs/registry/registering-an-agent` next to `docs/registry/index` in both `docs.json` Registry API page lists. ## Test plan - [x] `node -e "JSON.parse(...)" docs.json` — valid JSON. - [x] Page renders cleanly in Mintlify locally (CodeGroup, table, internal links).
EmmaLouise2018
force-pushed
the
EmmaLouise2018/docs-registering-an-agent
branch
from
10da65d to
9d53146
Compare
EmmaLouise2018
changed the base branch from
main
to
EmmaLouise2018/registry-docs-ia-annotations
This was referenced Apr 29, 2026
Base automatically changed from
EmmaLouise2018/registry-docs-ia-annotations
to
main
April 30, 2026 03:12
EmmaLouise2018
added a commit
that referenced
this pull request
Apr 30, 2026
- Tag-group label is "Authorization Lookups" (renamed in #3542), not "Lookups & Authorization". - Reference deep links retarget to the Mintlify auto-generated per-endpoint pages (`/docs/registry/api-reference/authorization-lookups/{operator,publisher}-lookup`) — same pattern #3543 already uses on `registering-an-agent.mdx`. - Cited file:line on `registry-api.ts` updated to current main: `/operator` 5165→5486, `/publisher` 5229→5550 (drifted in the post-#3542 main merge). No prose-shape change beyond stale-reference fixes.
bokelley
pushed a commit
that referenced
this pull request
May 1, 2026
…s publisher (#3559) * docs(registry): three-endpoint overview table — catalog vs operator vs publisher Refs #3538 Problem 4 P1. Three overlapping lookup endpoints on the Registry API have no top-level prose tying them together. They live under two different tag groups in the docs, so a reader has to know which tag to start in. Adds an overview table to docs/registry/index.mdx covering: - /api/registry/agents — "give me the catalog" - /api/registry/operator?domain=X — "what does this entity operate?" - /api/registry/publisher?domain=X — "what does this entity publish?" Each row includes the question it answers, when to use it, auth-aware response-shape note where relevant. Auth-aware note on /operator added in #3542; /publisher parity tracked in #3546. Pure docs change. No schema or behavior change. * docs(registry): align overview table with post-#3542 canonical framing - Tag-group label is "Authorization Lookups" (renamed in #3542), not "Lookups & Authorization". - Reference deep links retarget to the Mintlify auto-generated per-endpoint pages (`/docs/registry/api-reference/authorization-lookups/{operator,publisher}-lookup`) — same pattern #3543 already uses on `registering-an-agent.mdx`. - Cited file:line on `registry-api.ts` updated to current main: `/operator` 5165→5486, `/publisher` 5229→5550 (drifted in the post-#3542 main merge). No prose-shape change beyond stale-reference fixes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Refs #3538.
Closes the docs gap for non-members who today have no first-class self-registration path. Documents what does and does not work, in plain language.
Why
Issue #3538 surfaced that the registry's discovery mechanism is undocumented and that non-members had no way to learn how (or whether) they could appear in the registry. The four crawl paths existed in code but nowhere in docs. The auth-aware response shape on
/api/registry/operator— the primary mechanism by which AAO membership unlocks deeper data — was undocumented (separately addressed in #3542).This PR ships the docs side. It does not change product behavior.
Page contents
registered(canonical, AAO-attested, opt-in) vsdiscovered(crawled from someone'sadagents.json, no opt-in by the agent itself).sourcevalue and trust signal:registeredadagents.json—discoveredPOST /api/registry/crawl-request,POST /api/properties/check) —discoveredlist_authorized_propertiessurfaces a publisher domain —discoveredpublic/members_only/private), Verified badge, storyboard test access, compliance reporting, the auth-aware/api/registry/operatorendpoint.sourcefield.Stack ordering
This PR is stacked on #3542 (
base: EmmaLouise2018/registry-docs-ia-annotations). The "Related" section deep-links to/docs/registry/api-reference/authorization-lookups/operator-lookup, which only resolves with #3542's tag rename in the OpenAPI YAML. Stacking lets CI's broken-links check run against the union — green here, no follow-up TODO required.After #3542 merges to main, retarget this PR to
main(auto-rebases since #3542's commits are already absorbed). Diff reduces to the single new page commit.Recommended merge order from #3538: 3540 → 3542 → 3543 → 3541.
Nav
docs/registry/registering-an-agentadded next todocs/registry/indexin bothdocs.jsonRegistry API page lists.Test plan
node -e "JSON.parse(...)" docs.json— valid JSON.authorization-lookupsslug).Out of scope
?source=query param + UI segmentation on/registry(Problem 3 P1 in Registry: follow-ups from #3495 — stale types, registered/discovered conflation, docs IA gaps, non-member path #3538).