# 2026-04-01 Update Log

## Summary

Added x402-gated discovery endpoints for agent/tool self-discovery, built a docs-derived artifact pipeline from apiDoc annotations, and documented the new flow and behavior.

## Changes Made

- Added new discovery controller/router:
  - `src/controllers/discovery/controller.js`
  - `src/controllers/discovery/router.js`
- Added five root-path discovery endpoints:
  - `GET /.well-known/x402`
  - `GET /openapi.json`
  - `GET /swagger.json`
  - `GET /llms.txt`
  - `GET /.well-known/agent.json`
- Added x402-enabled gating:
  - All five endpoints now return `404` when `X402_ENABLED=false`.
  - When enabled, payloads are returned with x402-bch v2-oriented metadata.
- Added apiDoc-derived document builder:
  - `src/discovery/build-documents.js`
  - Parses `@api` annotations and builds OpenAPI, Swagger, llms, and agent documents.
  - Uses `docs/discovery-artifacts.json` if present, otherwise builds in-process.
- Added artifact generation script:
  - `scripts/build-discovery-artifacts.js`
  - Writes `docs/discovery-artifacts.json`
- Updated npm scripts in `package.json`:
  - `docs:discovery`
  - `docs:all` (runs `docs` then `docs:discovery`)
- Wired discovery routes into server bootstrap:
  - `bin/server.js`
- Added tests:
  - `test/unit/controllers/discovery-controller-unit.js`
  - `test/unit/controllers/discovery-router-unit.js`
  - `test/unit/controllers/discovery-documents-unit.js`
- Updated docs/config examples:
  - `README.md` (discovery endpoints + docs workflow)
  - `.env-example` (x402 gating note for discovery endpoints)

## Why This Was Changed

- Endpoint probes for discovery paths are common from API tooling and AI agents.
- Serving structured discovery metadata improves machine interoperability for:
  - API clients and SDK tooling (`openapi.json`, `swagger.json`)
  - LLM retrieval workflows (`llms.txt`)
  - Agent capability discovery (`agent.json`)
  - x402 payment discovery (`/.well-known/x402`)
- Gating by `X402_ENABLED` keeps discovery aligned with monetization mode and avoids advertising payment surfaces when x402 is disabled.

## Validation Notes

- Lint passed.
- New discovery-focused unit tests passed.
- Full `npm test` run showed one pre-existing timeout failure in `test/unit/use-cases/price-use-cases-unit.js` unrelated to discovery endpoint changes.

## References

- Local protocol spec:
  - `../x402-bch/specs/x402-bch-specification-v2.2.md`
- OpenAPI Specification:
  - https://spec.openapis.org/oas/latest.html
- Swagger / OpenAPI 2.0:
  - https://swagger.io/specification/v2/
- llms.txt proposal:
  - https://www.llmstxt.org/index.html
- Agent manifest draft reference:
  - https://agentwebprotocol.org/spec
- x402 HTTP 402 background:
  - https://docs.x402.org/core-concepts/http-402
- x402 DNS discovery draft:
  - https://www.ietf.org/archive/id/draft-jeftovic-x402-dns-discovery-00.html