docs: deterministic API reference + docs-check CI gate (Phase A)

.github/workflows/ci.yml

@@ -27,3 +27,15 @@ jobs:
       - run: npm run typecheck
       - run: npm test
       - run: npm pack --dry-run
+
+  docs-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22.x'
+          cache: npm
+      - run: npm ci
+      - run: npm run build
+      - run: npm run docs:check

Makefile

@@ -1,11 +1,17 @@
 LIVE_ENV_FILE ?= .env.live
 .DEFAULT_GOAL := test
 
-.PHONY: build test test-unit test-contract test-scenarios test-live test-live-managed test-live-all test-live-check test-e2e
+.PHONY: build test test-unit test-contract test-scenarios test-live test-live-managed test-live-all test-live-check test-e2e docs docs-check
 
 build:
 	npm run build
 
+docs:
+	npm run docs
+
+docs-check:
+	npm run docs:check
+
 test:
 	npm test
 

README.md

@@ -340,6 +340,10 @@ Neither hook is applied to file downloads, which deliberately bypass the client
 
 Node.js 20.12 or later. The SDK relies only on the platform's `fetch`, `Request`, `Response`, `Headers`, `AbortController`, `Blob` and `File` — any runtime providing those, and a `fetch` you can inject if not, should work. Deno, Bun, Cloudflare Workers and Vercel Edge are not part of the test matrix.
 
+## Documentation
+
+The API reference under `docs/api/` is generated from the source. Regenerate it with `make docs` (or `npm run docs`). To verify the committed reference is up to date and the README snippets still compile, run `make docs-check` (or `npm run docs:check`); CI runs the same gate on every pull request.
+
 ## License
 
 Released under the [MIT License](LICENSE).

docs/api/README.md

@@ -0,0 +1,16 @@
+**qca-sdk**
+
+***
+
+# qca-sdk
+
+## Modules
+
+- [index](index/README.md)
+- [forward](forward/README.md)
+- [managed](managed/README.md)
+
+## Related
+
+- [README](../../README.md)
+- [Examples](../../examples)