fix(x402 docs): Adding common LLM discovery documentation

dev-docs/update-logs/2026-04-01.md

@@ -0,0 +1,72 @@
+# 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