Merge pull request #26 from Permissionless-Software-Foundation/ct-unstable

Updates to x402 docs and api docs in Docker

.env-example

@@ -16,6 +16,9 @@ LOCAL_RESTURL=http://localhost:5942/v6
 
 # END INFRASTRUCTURE SETUP
 
+# Public base URL for apiDoc HTML (optional; used by Docker entrypoint before `npm run docs`).
+#APIDOC_URL=https://api.example.com
+
 
 # START ACCESS CONTROL
 
@@ -23,6 +26,8 @@ PORT=5942
 
 # x402 payments required to access this API?
 X402_ENABLED=true
+# Also gates discovery endpoints:
+# /.well-known/x402, /openapi.json, /swagger.json, /llms.txt, /.well-known/agent.json
 SERVER_BCH_ADDRESS=bitcoincash:qqlrzp23w08434twmvr4fxw672whkjy0py26r63g3d
 FACILITATOR_URL=http://localhost:4345/facilitator
 X402_PRICE_SAT=200

README.md

@@ -98,6 +98,16 @@ Every API call under the `/v6` prefix requires a BCH micro-payment. When a reque
 
 This is the right choice for **public, monetized APIs** where you want to charge per call.
 
+When `X402_ENABLED=true`, the server also exposes machine-discovery endpoints:
+
+- `/.well-known/x402` - x402-bch v2 payment discovery manifest
+- `/openapi.json` - OpenAPI 3 projection generated from apiDoc annotations
+- `/swagger.json` - Swagger 2.0 compatibility projection
+- `/llms.txt` - LLM-oriented markdown index of service metadata
+- `/.well-known/agent.json` - draft agent manifest describing API actions
+
+When `X402_ENABLED=false`, these discovery endpoints return `404`.
+
 #### Combined: x402 + Bearer Token
 
 You can enable both at the same time:
@@ -147,6 +157,12 @@ The API reference documentation is generated by [apiDoc](https://apidocjs.com/)
 
 The output is written to the `docs/` directory and served by the running server at its root URL.
 
+To regenerate API docs plus discovery artifacts (`openapi.json`, `swagger.json`, `llms.txt`, and `agent.json` payload source):
+
+`npm run docs:all`
+
+This runs apiDoc first, then generates `docs/discovery-artifacts.json` from the same annotation source.
+
 A live version can be found at [bch.fullstack.cash](https://bch.fullstack.cash/).
 
 ## Production (Docker)
@@ -171,6 +187,8 @@ FULCRUM_API=http://172.17.0.1:3001/v1
 SLP_INDEXER_API=http://172.17.0.1:5010
 ```
 
+Set `APIDOC_URL` to the public base URL for your deployment (for example `https://api.example.com` or your subdomain). The container entrypoint applies this value to `apidoc.json` and the `apidoc` section of `package.json`, then runs `npm run docs` before starting the server so generated HTML matches each instance. The compose file mounts `./.env` to `/home/safeuser/psf-bch-api/.env` so it matches `dotenv.config()` in the app.
+
 4. Build the Docker image:
 
 `docker-compose build --no-cache`

bin/server.js

@@ -17,6 +17,7 @@ import Controllers from '../src/controllers/index.js'
 import wlogger from '../src/adapters/wlogger.js'
 import { buildX402Routes, getX402Settings, getBasicAuthSettings } from '../src/config/x402.js'
 import { basicAuthMiddleware } from '../src/middleware/basic-auth.js'
+import DiscoveryRouter from '../src/controllers/discovery/router.js'
 
 // Load environment variables
 dotenv.config()
@@ -216,6 +217,8 @@ class Server {
 
       // Attach REST API controllers to the app.
       this.controllers.attachRESTControllers(app)
+      const discoveryRouter = new DiscoveryRouter()
+      discoveryRouter.attach(app)
 
       // Initialize any other controller libraries.
       this.controllers.initControllers()

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

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

@@ -0,0 +1,19 @@
+# 2026-04-02 Update Log
+
+## Summary
+
+Docker deployments now run `npm run docs` at container start via an entrypoint script, and optionally apply `APIDOC_URL` from the environment so apiDoc HTML matches each deployment subdomain or public URL.
+
+## Changes Made
+
+- Added `scripts/patch-apidoc-from-env.js` to set `apidoc.json` and `package.json` `apidoc.url` from `APIDOC_URL` (dotenv loads the project `.env`, same path as `bin/server.js`).
+- Added `production/docker/entrypoint.sh` to run the patch script, `npm run docs`, then `exec npm start`.
+- Updated `production/docker/Dockerfile` to remove build-time `npm run docs`, copy the entrypoint and patch script from the build context, and use `ENTRYPOINT` for the shell script.
+- Updated `production/docker/docker-compose.yml` to use build `context: ../..` and `dockerfile: production/docker/Dockerfile` so COPY paths resolve from the repository root.
+- Compose mounts `./.env` at `/home/safeuser/psf-bch-api/.env` so the app and entrypoint share one file (not `/home/safeuser/.env`).
+- Documented `APIDOC_URL` in `.env-example`, `production/docker/.env-example`, and `README.md` (Production Docker section).
+
+## Outcome
+
+- Operators can set `APIDOC_URL` in the mounted `.env` (for example `https://api.example.com`) per instance without rebuilding the image for each subdomain.
+- The HTML apiDoc bundle is regenerated on every container start so it stays aligned with the configured URL.

package.json

@@ -6,6 +6,8 @@
   "scripts": {
     "start": "node bin/server.js",
     "docs": "./node_modules/.bin/apidoc -i src/ -o docs",
+    "docs:discovery": "node scripts/build-discovery-artifacts.js",
+    "docs:all": "npm run docs && npm run docs:discovery",
     "lint": "standard --env mocha --fix",
     "test": "npm run lint && TEST=unit c8 mocha 'test/unit/**/*.js' --exit",
     "test:integration": "mocha --timeout 25000 'test/integration/**/*.js' --exit",

production/docker/.env-example

@@ -16,6 +16,10 @@ LOCAL_RESTURL=http://172.17.0.1:5942/v6
 
 # END INFRASTRUCTURE SETUP
 
+# Public base URL for apiDoc HTML (set per deployment / subdomain).
+# Applied at container start before `npm run docs`. Example: https://api.example.com
+#APIDOC_URL=https://api.example.com
+
 
 # START ACCESS CONTROL
 

production/docker/Dockerfile

@@ -57,13 +57,15 @@ RUN git checkout ct-unstable
 RUN npm install
 RUN npm install minimal-slp-wallet
 
-# Generate the API docs
-RUN npm run docs
+# Runtime entrypoint + apidoc URL patch (see production/docker/entrypoint.sh).
+# API docs are generated at container start so APIDOC_URL can be set per deployment.
+COPY production/docker/entrypoint.sh /home/safeuser/psf-bch-api/entrypoint.sh
+COPY scripts/patch-apidoc-from-env.js /home/safeuser/psf-bch-api/scripts/patch-apidoc-from-env.js
+RUN chmod +x /home/safeuser/psf-bch-api/entrypoint.sh
 
-COPY .env .env
+# Runtime `.env` is provided by docker-compose (mount at psf-bch-api/.env), not baked into the image.
 
-
-CMD ["npm", "start"]
+ENTRYPOINT ["/home/safeuser/psf-bch-api/entrypoint.sh"]
 
 # Used to debug the container.
 #COPY temp.js temp.js

production/docker/docker-compose.yml

@@ -2,7 +2,9 @@
 
 services:
     psf-bch-api:
-      build: .
+      build:
+        context: ../..
+        dockerfile: production/docker/Dockerfile
       container_name: psf-bch-api
       logging:
         driver: 'json-file'
@@ -16,7 +18,7 @@ services:
         - '5942:5942' # <host port>:<container port>
       volumes:
         #- ./start-rest2nostr.sh:/home/safeuser/REST2NOSTR/start-rest2nostr.sh
-        - ./.env:/home/safeuser/.env
+        - ./.env:/home/safeuser/psf-bch-api/.env
         - ../data:/home/safeuser/psf-bch-api/production/data
         - ../data/logs:/home/safeuser/psf-bch-api/logs
       restart: always

production/docker/entrypoint.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+set -euo pipefail
+
+cd /home/safeuser/psf-bch-api
+
+node scripts/patch-apidoc-from-env.js
+
+npm run docs
+
+exec npm start

scripts/build-discovery-artifacts.js

@@ -0,0 +1,21 @@
+/*
+  Build discovery endpoint artifacts from apiDoc source annotations.
+*/
+
+import { mkdirSync, writeFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+
+import { buildDiscoveryDocuments } from '../src/discovery/build-documents.js'
+
+function main () {
+  const outputPath = resolve(process.cwd(), 'docs/discovery-artifacts.json')
+  const docs = buildDiscoveryDocuments()
+
+  mkdirSync(dirname(outputPath), { recursive: true })
+  writeFileSync(outputPath, `${JSON.stringify(docs, null, 2)}\n`)
+
+  // eslint-disable-next-line no-console
+  console.log(`Wrote discovery artifacts to ${outputPath}`)
+}
+
+main()

scripts/patch-apidoc-from-env.js

@@ -0,0 +1,41 @@
+/*
+  Applies APIDOC_URL from the environment to apidoc.json and package.json (apidoc.url).
+  Loads dotenv from the project root `.env` (same file as `dotenv.config()` in bin/server.js).
+  Exits without changes when APIDOC_URL is unset or empty.
+*/
+
+import dotenv from 'dotenv'
+import { readFileSync, writeFileSync } from 'fs'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const root = resolve(__dirname, '..')
+
+dotenv.config({ path: resolve(root, '.env') })
+
+const url = process.env.APIDOC_URL
+if (url === undefined || url === null || String(url).trim() === '') {
+  process.exit(0)
+}
+
+const normalized = String(url).trim()
+
+function patchApidocJson () {
+  const path = resolve(root, 'apidoc.json')
+  const data = JSON.parse(readFileSync(path, 'utf8'))
+  data.url = normalized
+  data.sampleUrl = normalized
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`)
+}
+
+function patchPackageJson () {
+  const path = resolve(root, 'package.json')
+  const data = JSON.parse(readFileSync(path, 'utf8'))
+  if (!data.apidoc) data.apidoc = {}
+  data.apidoc.url = normalized
+  writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`)
+}
+
+patchApidocJson()
+patchPackageJson()

src/controllers/discovery/controller.js

@@ -0,0 +1,152 @@
+/*
+  Controller for discovery and machine-readable metadata endpoints.
+*/
+
+import config from '../../config/index.js'
+import { getX402Settings } from '../../config/x402.js'
+import { getDiscoveryDocuments } from '../../discovery/build-documents.js'
+
+const BCH_MAINNET_CAIP2 = 'bip122:000000000000000000651ef99cb9fcbe'
+const BCH_NATIVE_ASSET = '0x0000000000000000000000000000000000000001'
+const X402_TIMEOUT_SECONDS = 60
+
+class DiscoveryController {
+  constructor (localConfig = {}) {
+    this.getX402Settings = localConfig.getX402Settings || getX402Settings
+    this.getDiscoveryDocuments = localConfig.getDiscoveryDocuments || getDiscoveryDocuments
+    this.apiPrefix = localConfig.apiPrefix || config.apiPrefix
+
+    this.x402Manifest = this.x402Manifest.bind(this)
+    this.openapi = this.openapi.bind(this)
+    this.swagger = this.swagger.bind(this)
+    this.llmsTxt = this.llmsTxt.bind(this)
+    this.agentManifest = this.agentManifest.bind(this)
+    this.respondNotFoundWhenDisabled = this.respondNotFoundWhenDisabled.bind(this)
+    this.sendText = this.sendText.bind(this)
+  }
+
+  respondNotFoundWhenDisabled (res) {
+    const { enabled } = this.getX402Settings()
+    if (enabled) return false
+
+    res.status(404).json({
+      error: 'Not found'
+    })
+    return true
+  }
+
+  /**
+   * @api {get} /.well-known/x402 x402-bch resource discovery
+   * @apiName X402Discovery
+   * @apiGroup Discovery
+   * @apiDescription Returns x402-bch v2 resource and payment requirement metadata.
+   */
+  x402Manifest (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const x402 = this.getX402Settings()
+    const apiPrefix = this.apiPrefix || '/v6'
+    const prefixWithSlash = apiPrefix.startsWith('/') ? apiPrefix : `/${apiPrefix}`
+
+    const payload = {
+      x402Version: 2,
+      network: BCH_MAINNET_CAIP2,
+      facilitator: {
+        url: x402.facilitatorUrl
+      },
+      resources: [
+        {
+          resource: `${prefixWithSlash}/*`,
+          type: 'http',
+          x402Version: 2,
+          accepts: [
+            {
+              scheme: 'utxo',
+              network: BCH_MAINNET_CAIP2,
+              amount: String(x402.priceSat),
+              description: `Access to protected psf-bch-api resources (${x402.priceSat} satoshis)`,
+              mimeType: 'application/json',
+              payTo: x402.serverAddress,
+              maxTimeoutSeconds: X402_TIMEOUT_SECONDS,
+              asset: BCH_NATIVE_ASSET,
+              extra: {}
+            }
+          ]
+        }
+      ]
+    }
+
+    return res.status(200).json(payload)
+  }
+
+  /**
+   * @api {get} /openapi.json OpenAPI discovery document
+   * @apiName OpenApiDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns an OpenAPI document generated from apiDoc annotations.
+   */
+  openapi (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return res.status(200).json(docs.openapi)
+  }
+
+  /**
+   * @api {get} /swagger.json Swagger discovery document
+   * @apiName SwaggerDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns a Swagger 2.0 compatibility document generated from apiDoc annotations.
+   */
+  swagger (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return res.status(200).json(docs.swagger)
+  }
+
+  /**
+   * @api {get} /llms.txt LLM discovery file
+   * @apiName LlmsDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns an llms.txt markdown index for AI tooling discovery.
+   */
+  llmsTxt (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return this.sendText(res, docs.llms)
+  }
+
+  /**
+   * @api {get} /.well-known/agent.json Agent manifest
+   * @apiName AgentManifestDiscovery
+   * @apiGroup Discovery
+   * @apiDescription Returns a draft agent manifest describing API capabilities.
+   */
+  agentManifest (req, res) {
+    if (this.respondNotFoundWhenDisabled(res)) return
+
+    const docs = this.getDiscoveryDocuments()
+    return res.status(200).json(docs.agent)
+  }
+
+  sendText (res, text) {
+    res.status(200)
+    res.setHeader('Content-Type', 'text/plain; charset=utf-8')
+
+    if (typeof res.send === 'function') {
+      return res.send(text)
+    }
+
+    if (typeof res.write === 'function') {
+      res.write(text)
+    }
+    if (typeof res.end === 'function') {
+      res.end()
+    }
+    return res
+  }
+}
+
+export default DiscoveryController

src/controllers/discovery/router.js

@@ -0,0 +1,30 @@
+/*
+  Router for discovery and machine-readable metadata endpoints.
+*/
+
+import express from 'express'
+import DiscoveryController from './controller.js'
+
+class DiscoveryRouter {
+  constructor (localConfig = {}) {
+    this.controller = localConfig.controller || new DiscoveryController()
+    this.router = express.Router()
+    this.attach = this.attach.bind(this)
+  }
+
+  attach (app) {
+    if (!app) {
+      throw new Error('Must pass app object when attaching DiscoveryRouter.')
+    }
+
+    this.router.get('/.well-known/x402', this.controller.x402Manifest)
+    this.router.get('/openapi.json', this.controller.openapi)
+    this.router.get('/swagger.json', this.controller.swagger)
+    this.router.get('/llms.txt', this.controller.llmsTxt)
+    this.router.get('/.well-known/agent.json', this.controller.agentManifest)
+
+    app.use(this.router)
+  }
+}
+
+export default DiscoveryRouter

src/discovery/build-documents.js

@@ -0,0 +1,223 @@
+/*
+  Build and cache discovery documents from apiDoc-style annotations.
+*/
+
+import { readFileSync, existsSync, readdirSync } from 'fs'
+import { resolve } from 'path'
+
+import config from '../config/index.js'
+import { getX402Settings } from '../config/x402.js'
+
+const BCH_MAINNET_CAIP2 = 'bip122:000000000000000000651ef99cb9fcbe'
+const X402_SPEC_VERSION = 2
+
+let cachedDocs = null
+
+function parseApiAnnotations () {
+  const srcRoot = resolve(process.cwd(), 'src/controllers/rest-api')
+  const entries = []
+  const files = walkJsFiles(srcRoot)
+
+  for (const file of files) {
+    const text = readFileSync(file, 'utf8')
+    const blocks = text.match(/\/\*\*[\s\S]*?\*\//g) || []
+
+    for (const block of blocks) {
+      const endpoint = parseBlock(block)
+      if (endpoint) entries.push(endpoint)
+    }
+  }
+
+  return entries
+}
+
+function parseBlock (block) {
+  const methodMatch = block.match(/@api\s+\{([^}]+)\}\s+(\S+)\s+([^\n\r*]+)/)
+  if (!methodMatch) return null
+
+  const method = methodMatch[1].trim().toUpperCase()
+  const path = methodMatch[2].trim()
+  const summary = methodMatch[3].trim()
+
+  const groupMatch = block.match(/@apiGroup\s+([^\n\r*]+)/)
+  const descriptionMatch = block.match(/@apiDescription\s+([^\n\r*][\s\S]*?)(?=\n\s*\*\s*@api|\n\s*\*\/)/)
+  const apiNameMatch = block.match(/@apiName\s+([^\n\r*]+)/)
+
+  return {
+    method,
+    path,
+    summary,
+    group: groupMatch ? groupMatch[1].trim() : 'General',
+    operationId: apiNameMatch ? apiNameMatch[1].trim() : `${method.toLowerCase()}_${path.replace(/[^\w]/g, '_')}`,
+    description: descriptionMatch
+      ? descriptionMatch[1].replace(/\n\s*\*\s?/g, ' ').trim()
+      : summary
+  }
+}
+
+function walkJsFiles (dir) {
+  const output = []
+
+  for (const item of readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = resolve(dir, item.name)
+    if (item.isDirectory()) {
+      output.push(...walkJsFiles(fullPath))
+      continue
+    }
+
+    if (item.isFile() && fullPath.endsWith('.js')) output.push(fullPath)
+  }
+
+  return output
+}
+
+function normalizePaths (endpoints) {
+  const paths = {}
+
+  for (const endpoint of endpoints) {
+    if (!paths[endpoint.path]) paths[endpoint.path] = {}
+
+    const op = {
+      tags: [endpoint.group],
+      summary: endpoint.summary,
+      description: endpoint.description,
+      operationId: endpoint.operationId,
+      responses: {
+        200: {
+          description: 'Successful response'
+        },
+        402: {
+          description: 'Payment required when x402 is enabled'
+        }
+      },
+      'x-payment-model': 'x402-bch-v2'
+    }
+
+    paths[endpoint.path][endpoint.method.toLowerCase()] = op
+  }
+
+  return paths
+}
+
+function buildOpenApi (paths) {
+  return {
+    openapi: '3.0.3',
+    info: {
+      title: 'psf-bch-api',
+      version: config.version,
+      description: 'OpenAPI projection generated from apiDoc annotations'
+    },
+    servers: [
+      {
+        url: '/'
+      }
+    ],
+    paths
+  }
+}
+
+function buildSwagger (paths) {
+  return {
+    swagger: '2.0',
+    info: {
+      title: 'psf-bch-api',
+      version: config.version,
+      description: 'Swagger projection generated from apiDoc annotations'
+    },
+    basePath: '/',
+    schemes: ['https', 'http'],
+    paths
+  }
+}
+
+function buildLlms (endpoints) {
+  const lines = [
+    '# psf-bch-api',
+    '',
+    '> REST API proxy to Bitcoin Cash infrastructure with optional x402-bch monetized access.',
+    '',
+    '## Discovery',
+    '- [OpenAPI document](/openapi.json): OpenAPI 3 projection generated from apiDoc annotations.',
+    '- [Swagger document](/swagger.json): Swagger 2.0 compatibility projection.',
+    '- [x402 manifest](/.well-known/x402): x402-bch v2 payment requirement discovery.',
+    '- [Agent manifest](/.well-known/agent.json): draft agent capability surface.',
+    '',
+    '## API Groups'
+  ]
+
+  const seen = new Set()
+  for (const endpoint of endpoints) {
+    if (seen.has(endpoint.group)) continue
+    seen.add(endpoint.group)
+    lines.push(`- ${endpoint.group}`)
+  }
+
+  lines.push('', '## Optional', '- [Human docs](/): apiDoc HTML documentation root.')
+  return lines.join('\n')
+}
+
+function buildAgent (endpoints) {
+  const x402 = getX402Settings()
+  const actions = endpoints.map(endpoint => ({
+    id: endpoint.operationId,
+    description: endpoint.summary,
+    auth_required: true,
+    endpoint: endpoint.path,
+    method: endpoint.method
+  }))
+
+  return {
+    awp_version: '0.1',
+    domain: 'localhost',
+    intent: 'Programmatic BCH blockchain API access',
+    capabilities: {
+      batch_actions: false,
+      streaming: false
+    },
+    auth: {
+      type: 'x402-bch-v2',
+      required_for: actions.map(a => a.id),
+      pricing: {
+        amountSat: String(x402.priceSat),
+        payTo: x402.serverAddress,
+        network: BCH_MAINNET_CAIP2,
+        x402Version: X402_SPEC_VERSION
+      }
+    },
+    actions
+  }
+}
+
+export function buildDiscoveryDocuments () {
+  const endpoints = parseApiAnnotations()
+  const paths = normalizePaths(endpoints)
+
+  return {
+    openapi: buildOpenApi(paths),
+    swagger: buildSwagger(paths),
+    llms: buildLlms(endpoints),
+    agent: buildAgent(endpoints)
+  }
+}
+
+export function getDiscoveryDocuments () {
+  if (cachedDocs) return cachedDocs
+
+  const artifactPath = resolve(process.cwd(), 'docs/discovery-artifacts.json')
+  if (existsSync(artifactPath)) {
+    try {
+      cachedDocs = JSON.parse(readFileSync(artifactPath, 'utf8'))
+      return cachedDocs
+    } catch {
+      cachedDocs = buildDiscoveryDocuments()
+      return cachedDocs
+    }
+  }
+
+  cachedDocs = buildDiscoveryDocuments()
+  return cachedDocs
+}
+
+export function resetDiscoveryDocumentCache () {
+  cachedDocs = null
+}

test/unit/controllers/discovery-controller-unit.js

@@ -0,0 +1,106 @@
+/*
+  Unit tests for DiscoveryController.
+*/
+
+import { assert } from 'chai'
+
+import DiscoveryController from '../../../src/controllers/discovery/controller.js'
+import { createMockRequest, createMockResponse } from '../mocks/controller-mocks.js'
+
+describe('#discovery-controller.js', () => {
+  const makeController = ({ enabled = true } = {}) => {
+    return new DiscoveryController({
+      apiPrefix: '/v6',
+      getX402Settings: () => ({
+        enabled,
+        facilitatorUrl: 'http://localhost:4345/facilitator',
+        serverAddress: 'bitcoincash:qtestaddress',
+        priceSat: 200
+      }),
+      getDiscoveryDocuments: () => ({
+        openapi: { openapi: '3.0.3', paths: { '/v6/price/bchusd': {} } },
+        swagger: { swagger: '2.0', paths: { '/v6/price/bchusd': {} } },
+        llms: '# psf-bch-api',
+        agent: { awp_version: '0.1', actions: [] }
+      })
+    })
+  }
+
+  describe('x402 disabled gating', () => {
+    it('should return 404 for all discovery endpoints when x402 disabled', async () => {
+      const uut = makeController({ enabled: false })
+      const req = createMockRequest()
+
+      const handlers = [
+        uut.x402Manifest,
+        uut.openapi,
+        uut.swagger,
+        uut.llmsTxt,
+        uut.agentManifest
+      ]
+
+      for (const handler of handlers) {
+        const res = createMockResponse()
+        await handler(req, res)
+        assert.equal(res.statusValue, 404)
+        assert.deepEqual(res.jsonData, { error: 'Not found' })
+      }
+    })
+  })
+
+  describe('x402 enabled responses', () => {
+    it('should return x402 manifest schema fields', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.x402Manifest(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.equal(res.jsonData.x402Version, 2)
+      assert.isArray(res.jsonData.resources)
+      assert.equal(res.jsonData.resources[0].accepts[0].scheme, 'utxo')
+      assert.equal(res.jsonData.resources[0].accepts[0].amount, '200')
+    })
+
+    it('should return openapi and swagger docs', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+
+      const openapiRes = createMockResponse()
+      await uut.openapi(req, openapiRes)
+      assert.equal(openapiRes.statusValue, 200)
+      assert.equal(openapiRes.jsonData.openapi, '3.0.3')
+
+      const swaggerRes = createMockResponse()
+      await uut.swagger(req, swaggerRes)
+      assert.equal(swaggerRes.statusValue, 200)
+      assert.equal(swaggerRes.jsonData.swagger, '2.0')
+    })
+
+    it('should return llms.txt as text/plain', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.llmsTxt(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.equal(res.headers['Content-Type'], 'text/plain; charset=utf-8')
+      assert.equal(res.writeData[0], '# psf-bch-api')
+      assert.isTrue(res.endCalled)
+    })
+
+    it('should return agent manifest json', async () => {
+      const uut = makeController({ enabled: true })
+      const req = createMockRequest()
+      const res = createMockResponse()
+
+      await uut.agentManifest(req, res)
+
+      assert.equal(res.statusValue, 200)
+      assert.equal(res.jsonData.awp_version, '0.1')
+      assert.isArray(res.jsonData.actions)
+    })
+  })
+})

test/unit/controllers/discovery-documents-unit.js

@@ -0,0 +1,25 @@
+/*
+  Unit tests for discovery document builder.
+*/
+
+import { assert } from 'chai'
+
+import { buildDiscoveryDocuments } from '../../../src/discovery/build-documents.js'
+
+describe('#discovery-build-documents.js', () => {
+  it('should build openapi and swagger documents with v6 paths', () => {
+    const docs = buildDiscoveryDocuments()
+
+    assert.property(docs, 'openapi')
+    assert.property(docs, 'swagger')
+    assert.property(docs, 'llms')
+    assert.property(docs, 'agent')
+
+    assert.isString(docs.openapi.openapi)
+    assert.equal(docs.swagger.swagger, '2.0')
+    assert.isAbove(Object.keys(docs.openapi.paths).length, 0)
+
+    const hasV6Path = Object.keys(docs.openapi.paths).some(path => path.startsWith('/v6/'))
+    assert.isTrue(hasV6Path)
+  })
+})

test/unit/controllers/discovery-router-unit.js

@@ -0,0 +1,43 @@
+/*
+  Unit tests for DiscoveryRouter.
+*/
+
+import { assert } from 'chai'
+
+import DiscoveryRouter from '../../../src/controllers/discovery/router.js'
+
+describe('#discovery-router.js', () => {
+  it('should require app object in attach()', () => {
+    const uut = new DiscoveryRouter()
+    assert.throws(() => uut.attach(), /Must pass app object/)
+  })
+
+  it('should register all discovery routes', () => {
+    const calls = []
+    const app = {
+      use: () => {}
+    }
+
+    const mockRouter = {
+      get: (path, handler) => calls.push({ path, handler })
+    }
+
+    const mockController = {
+      x402Manifest: () => {},
+      openapi: () => {},
+      swagger: () => {},
+      llmsTxt: () => {},
+      agentManifest: () => {}
+    }
+
+    const uut = new DiscoveryRouter({ controller: mockController })
+    uut.router = mockRouter
+    uut.attach(app)
+
+    assert.equal(calls.length, 5)
+    assert.deepEqual(
+      calls.map(x => x.path),
+      ['/.well-known/x402', '/openapi.json', '/swagger.json', '/llms.txt', '/.well-known/agent.json']
+    )
+  })
+})