Clear Exchange documentation

Published at https://docs.clearexchange.ai on every deploy. Every page is also in the repository under docs/.

Integrating with the API (partner engineers)

1. API reference: every endpoint, with request and response examples and error codes.
2. Entitlements: token format and how to verify it, online or offline.
3. Telemetry: the SPUR v1.0 events agents report, and the provisional fields.
4. Rate cards: the price list schema and how offers are priced.
5. Licence terms: the structured key terms and summary on every offer and entitlement, their defaults, and filtering queries by them.
6. Adding a source: the supply adapter interface, the v1 offer contract for publishers, and how to add a publisher or marketplace.

Working on the code (new engineers)

1. Architecture and request flow: how a query becomes an offer, an entitlement, a ledger entry and telemetry; code map; key decisions.
2. Configuration and deploy: environment variables, CI, continuous deployment to Fly.io and the GitHub secrets.
3. Agent-user harness: synthetic agents that test the exchange end to end.
4. Customer survey: a generated crowd of AI buyers and publishers that use the exchange and say whether they would adopt it.
5. Live sources: the Wikinews and Wikipedia adapter, licences and resilience.
6. Demo supply and coverage: the fictional demo verticals (finance, developer docs, research), their publishers and rate cards, and the coverage page.
7. Web UI: the marketing page and demo app.
8. Docs site: how these pages are published at docs.clearexchange.ai and adding a page.
9. Hostnames and DNS: which hostname serves what, redirects, the canonical issuer, certificates, IP addresses and DNS records.
10. Roadmap: what is built, what is stubbed, and what is planned but not built.