feat(docs): add API reference generation and PR CI

.github/workflows/ci.yml

@@ -0,0 +1,54 @@
+# PR CI baseline for qoder-cloud-agents-sdk-go.
+#
+# Matrix job (`check`) runs make lint → make build → make test across the
+# module's minimum Go version and a recent stable release. The docs-check job
+# runs on a single pinned Go version (matches the toolchain used to author
+# docs/api/reference.md) — go/doc rendering varies across Go versions, so
+# doc drift must be judged against exactly one.
+#
+# All jobs are offline: `make test` = test-unit (with the offline live
+# subset) + test-contract, no live tags, no PAT, no external Aliyun deps.
+name: ci
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: check (${{ matrix.go-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        go-version: ["1.23.x", "1.26.x"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+          cache: true
+      - name: make lint
+        run: make lint
+      - name: make build
+        run: make build
+      - name: make test
+        run: make test
+
+  docs-check:
+    name: docs-check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          # Pinned to a single toolchain version — matches the version used
+          # to regenerate docs/api/reference.md locally. Bump both together.
+          go-version: "1.26.x"
+          cache: true
+      - name: make docs-check
+        run: make docs-check

Makefile

@@ -2,11 +2,34 @@ PYTHON ?= python3
 LIVE_ENV_FILE ?= .env.live
 .DEFAULT_GOAL := test
 
-.PHONY: build test test-unit test-contract test-live test-live-check test-live-managed test-live-managed-check test-live-all check-version
+.PHONY: build test test-unit test-contract test-live test-live-check test-live-managed test-live-managed-check test-live-all check-version docs docs-check lint
 
 build:
 	go build ./...
 
+# Regenerate the committed API reference from source (public forward / managed
+# / convention packages via a pinned gomarkdoc; see internal/docs).
+docs:
+	go run ./internal/docs/cmd/generate
+
+# Drift + normalization + coarse core-surface + internal-link gate. Red when
+# committed docs/api/reference.md lags source, when any source link still
+# carries a #Lxx anchor, when the core public surface is missing from the
+# output, or when an internal relative link is broken.
+docs-check:
+	go run ./internal/docs/cmd/check
+
+# gofmt + go vet gate. Fails if any tracked .go file is not gofmt'd or if vet
+# reports a diagnostic. Wired into the CI matrix (see .github/workflows/ci.yml).
+lint:
+	@unformatted=$$(gofmt -l .); \
+		if test -n "$$unformatted"; then \
+			echo "gofmt reports unformatted files:" >&2; \
+			echo "$$unformatted" >&2; \
+			exit 1; \
+		fi
+	go vet ./...
+
 # Run before tagging a release: the reported version is a compile-time constant,
 # so tagging without bumping it makes the SDK report a version it is not.
 check-version:

README.md

@@ -740,11 +740,23 @@ The programs print their steps, messages, assistant replies and cleanup results;
 ```sh
 make test
 make build
+make lint
 go test -race ./...
 ```
 
 The offline tests cover request serialization, API contracts, response decoding, errors, retries, pagination, SSE and cleanup behaviour. Files ending in `_live_test.go` need the `live` build tag and a test configuration; the runnable examples do not.
 
+### API reference
+
+The committed API reference lives at [`docs/api/reference.md`](docs/api/reference.md) and is regenerated from the current source with a pinned `gomarkdoc` release:
+
+```sh
+make docs        # regenerate docs/api/reference.md
+make docs-check  # regenerate + drift/normalization/core-surface/link gate (used in CI)
+```
+
+The gate is what CI enforces; run `make docs` and commit the result whenever you change GoDoc on an exported symbol. Under the hood `make docs` runs `go run github.com/princjef/gomarkdoc/cmd/gomarkdoc@v1.1.0 --repository.url … --repository.default-branch main --repository.path / ./forward ./managed ./convention/...` — the version is pinned in `internal/docs/generate.go`.
+
 ## Versioning
 
 The module is pre-1.0. Per semantic versioning, the compatibility guarantee does not apply below `v1.0.0`, so a minor release may change the API; pin a version in `go.mod` and read the release notes before upgrading.