TypeSpec already generates OpenAPI 3.1 for the REST and Compatibility APIs and JSON Schema for SWML; the relationships should be explicit in both directions. OpenAPI operations get externalDocs and x-signalwire extensions pointing at guides and concepts, guides list the operations they cover, and SDK references state which REST operation or SWML method they wrap — the AgentBase page already does this well ("generates Calling SWML containing the ai method") and should be the model.
Also add machine-readable frontmatter to every exported page: canonical_url, document_type, product, version, last_verified, identifiers, prerequisites, related, deprecated. This supports freshness ranking, canonicalization, and citation accuracy. Audit §9 and §11.
The frontmatter set also needs area and a source block (type, commit). Most of the reference corpus is generated from TypeSpec, and the source commit is what lets a consumer — or CI — detect a page that no longer matches the spec it came from.
TypeSpec already generates OpenAPI 3.1 for the REST and Compatibility APIs and JSON Schema for SWML; the relationships should be explicit in both directions. OpenAPI operations get externalDocs and x-signalwire extensions pointing at guides and concepts, guides list the operations they cover, and SDK references state which REST operation or SWML method they wrap — the AgentBase page already does this well ("generates Calling SWML containing the ai method") and should be the model.
Also add machine-readable frontmatter to every exported page: canonical_url, document_type, product, version, last_verified, identifiers, prerequisites, related, deprecated. This supports freshness ranking, canonicalization, and citation accuracy. Audit §9 and §11.
The frontmatter set also needs
areaand asourceblock (type,commit). Most of the reference corpus is generated from TypeSpec, and the source commit is what lets a consumer — or CI — detect a page that no longer matches the spec it came from.